Getting Started With EPICS Lecture Series Writing Record

Getting Started With EPICS Lecture Series Writing Record Support Marty Kraimer, ASD/Controls 23 November 2004 Argonne National Laboratory Office of Science U. S. Department of Energy A U. S. Department of Energy Office of Science Laboratory Operated by The University of Chicago

Overview u Record Support v Implements a Record Type v Plugs into database common environment u Implementation steps v Prepare a Database Definition (. dbd) file v Create a C source file which implements semantics v Start with existing support!!! u Documentation v App Dev Guide 3. 14. 6 - Chapters 5, 6, and 11 v make. Base. App example - xxx. Record v base/src/rec u BUT FIRST: Ask the question Why? v Reasons against a new record type v Reasons for a new record type Pioneering Science and Technology Office of Science U. S. Department of Energy

Reasons Against a New Record Type u Only one STAT, SEVR, VAL v Example: Power Supply Record, i. e. multiple inputs, outputs. What do stat and sevr mean? v Is a template of standard record types a better choice? u No device support v Standard record types have extensive associated device support u No documentation. You should also provide it. u Can be tricky to implement proper semantics u Some standard tools may also need extensions. Example cap. Fast. Pioneering Science and Technology Office of Science U. S. Department of Energy

Reasons For a New Record Type u Sets of standard record types will not satisfy need v Are you really sure? Think hard!!! u State must be shared across multiple records v Example asyn. Record – Can dynamically change hardware addressing ✤I implemented via device support and standard records. Complicated!! ✤Mark implemented via new record type. Much easier to understand. u Many record instances: Example mbbi. Direct record type. u Because it is fun. NOT A GOOD REASON. u Example Event Generator/ Event Receiver Records v APS/SLS/Diamond/PLS – Special Record Types v SNS has different event system. ✤Question: Modify EG/ER or write device support for standard records? ✤Answer: Not clear!!! ✢Very few EG records ✢At most one ER per IOC ✢I think SNS decided to use device support for standard record types Pioneering Science and Technology Office of Science U. S. Department of Energy

Implementation: Create DBD. u Create a Database Definition (dbd) File. u Chapter 6 of 3. 14. 6 Application Developer’s Guide. u Syntax recordtype(<recordtype>) { include “db. Common. dbd” field(<fieldname>, <fieldtype>) { <fieldattributes> }. . . } Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD Example u Example recordtype(example) { include “db. Common. dbd” field(PREC, DBF_DOUBLE) { prompt(“Display Precision”) prompt. Group(GUI_DISPLAY) } field(VAL, DBF_DOUBLE) } Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD continued u recordtype(<recordtype>) Should be alphanumeric starting with letter u include “<filename>” v Must include db. Common first. u field(<fieldname>, <type>) {<attributes>} v Fieldname should be alphanumeric starting with letter v Length is normally limited to four characters ✤ 3. 14 allows arbitrary length ✤May cause problems with some Channel Access clients v In dbd file this should be upper case. It is converted to lower case when the <recordtype>. h file is generated. Bad decision!! Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD – Field Attributes u <fieldattributes> v asl : access security level ✤ASL 1 - Fields seldom modified - default ✤ASL 0 - Fields meant to be modified v initial : initial value v prompt : string for Database Configuration v promptgroup : Should DCT allow field to be configured? v special: Special handling on put ✤Several values ✤SPC_MOD, SPC_DBADDR, SPC_NOMOD Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD – Field Attributes continued u <fieldattributes> (continued) v pp : process passive record on put? v interest : interest level used by dbpr (Database Print Record) v base : DECIMAL (default) or HEX (Only used by db. Dump. Record) v size : For DBF_STRING v extra : For DBF_NOACCESS v menu : For DBF_MENU. Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD - Fieldtypes u <fieldtype> DBF_STRING DBF_CHAR DBF_UCHAR DBF_SHORT DBF_USHORT DBF_LONG DBF_ULONG DBF_FLOAT DBF_DOUBLE DBF_ENUM DBF_MENU DBF_DEVICE DBF_INLINK DBF_OUTLINK DBF_FWDLINK DBF_NOACCESS Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD String Field u DBF_STRING fields v Fixed length null terminated strings v Channel access support max of 40 characters v Arrays of character strings are possible u Example field(VAL, DBF_STRING) { size(40) prompt(“value”) promptgroup(GUI_DISPLAY) } Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD Numeric Fields u DBF_CHAR, … , DBF_DOUBLE v Standard C datatypes v All attributes except size, extra, menu meaningful u Arrays v dbd file must define special(SPC_DBADDR) v Record support must implement cvt_dbaddr, get_array_info, put_array_info v No support by Database Configuration Tools. Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD: Enumerated Field u DBF_ENUM v Record Support provides choices and index v See bi. Record, mbbi. Record, etc v Actual field type is unsigned short v Record support MUST implement ✤get_enum_str ✤put_enum_str ✤get_enum_strs Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD Menu Field u DBF_MENU menu(<menuname>) { choice(<choicename>, ”<choicevalue>“) … } … recordtype(<recordtype>) { field(<fieldname>, DBF_MENU) { menu(<menuname>) } Pioneering Science and Technology Office of Science U. S. Department of Energy

Menu Field Example u Example menu(menu. Yes. No) { choice(menu. Yes. No, ”NO”) choice(menu. Yes. No, ”YES”) } … field(PINI, DBF_MENU) { … menu(menu. Yes. No) } Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD Device Field u DBF_DEVICE v Database Common Field - DTYP v Related to device definitions v Has associated INP or OUT field v Device Support must be provided u Example field(DTYP, ”Soft Channel”) This requires a device definition like: device(ai, CONSTANT, dev. Ai. Soft, ”Soft Channel”) Pioneering Science and Technology Office of Science U. S. Department of Energy

DBD link Fields u DBF_INLINK, DBF_OUTLINK v Not INP or OUT ✤Constant link - Just initialization ✤PV_LINK becomes DB_LINK or CA_LINK v INP or OUT and Device Support ✤device definitions determine choices ✤Associated with choice is bus type ✤Gory details in link. h. Used by device support. u DBF_FWDLINK v references another record which is processed if it is passive. v FLNK ✤In db. Common ✤record support calls rec. Gbl. Fwd. Link v Other DBF_FWDLINKs can be defined ✤Call db. Scan. Fwd. Link NOT rec. Gbl. Fwd. Link Pioneering Science and Technology Office of Science U. S. Department of Energy

Implementation: Generate include files u Generate <menu>. h and <recordtype>. h include file u db. To. Menu. H generates <menu>. h v Code should use generated files instead of hard coding choices ✤Many standard records written before db. To. Menu. H existed. v Example menu. Yes. No. h typedef enum { menu. Yes. No. NO, menu. Yes. No. YES } menu. Yes. No; Pioneering Science and Technology Office of Science U. S. Department of Energy

Generate Include Files continued u db. To. Record. Type. H generates <recordtype>. h v Code MUST use generated files v Include code to compute field sizes, offsets typedef struct ai. Record { char name[29]; … } #define ai. Record. NAME 0 … #ifdef GEN_SIZE_OFFSET int ai. Record. Size. Offset(db. Record. Type *p) { … } v Only record support and associated device support is allowed to use the include files. Pioneering Science and Technology Office of Science U. S. Department of Energy

Implementation: Record Support Module u Provide Execution Semantics u Defined via RSET - Record Support Entry Table /* Create RSET - Record Support Entry Table #define report NULL #define initialize NULL static long init_record(); static long process(); … struct rset <recordtype>RSET = { RSETNUMBER, report, initialize, init_record, process, … }; Pioneering Science and Technology Office of Science U. S. Department of Energy

Record Support Methods - Summary u Report, Initialization, Processing v report v initialize v init_record v process Pioneering Science and Technology Office of Science U. S. Department of Energy

Record Support Methods - Summary u Support for Channel/ Database Access v special v cvt_dbaddr v get_array_info v put_array_info v get_units v get_precision v get_enum_str v put_enum_str v get_enum_strs v get_graphic_double v get_control_double v get_alarm_double Pioneering Science and Technology Office of Science U. S. Department of Energy

Record Support Method: Syntax u RSET – Record Support Entry Table v Except for RSETNUMBER just a structure of function pointers. v Similar to JAVA interface or pure virtual C++ class v BUT defined before standard C was available for EPICS v Does NOT use C function prototypes v Sorry!!!! v Perhaps this will change in EPICS version 4. Pioneering Science and Technology Office of Science U. S. Department of Energy

Methods: Report, Initialization, Processing u report(void *precord) v Nothing calls this. Normally not implemented u initialize(void) v Called once before first call to init_record. Not normally needed u init_record(void *precord, int pass) v Normally implemented v Called twice ✤pass 0 - Can do anything except access other records. For example storage for arrays should be allocated during pass 0. ✤pass 1 - Finish initialization and also call associated device support initialization u process v VERY IMPORTANT v Implements record semantics Pioneering Science and Technology Office of Science U. S. Department of Energy

init_record example /* assume val is double *val */ typedef struct xxxdset { long number, … DEVSUPFUN init_record; … DEVSUPFUN read; } xxxdset; static long init_record(void *prec, int pass) { xxxarray. Record *paf = (xxxarray. Record *)prec; xxxdest *pdset = (xxxdset *)paf->dset; if(pass==0) { if(paf->nelm<0) paf->nelm = 1; paf->val = (double *)calloc(paf->nelm, sizeof(double)); return(0); } /* Must have dset defined */ if(!pdset !! (pdset->number< 5) || !pdest->read ) { epics. Printf(“%s no or invalid dsetn”, paf->name); return(0); } (*pdset->init_record)(paf); return(0); } Pioneering Science and Technology Office of Science U. S. Department of Energy

process overview u db. Access: db. Process calls process if v Decision was made to process the record v Record not active (PACT FALSE) v Record is enabled (DISV !=DISA) u process with device support must v set record active (PACT TRUE) v Perform I/O v Check for record specific alarms v Raise database monitors v Request processing of forward links v Set PACT FALSE and return Pioneering Science and Technology Office of Science U. S. Department of Energy

process overview continued u For asynchronous devices. v Asynchronous start ✤Initiate I/O. ✤Determine a method for calling process when operation completes ✤Return leaving PACT TRUE. v Asynchronous completion ✤Call process as follows: db. Scan. Lock(precord); *(prset->process)(precord); db. Scan. Unlock(precord); Pioneering Science and Technology ✤process completes record processing ✢Complete I/O ✢Check for record specific alarms ✢Raise database monitors ✢Request processing of forward links ✢Set PACT FALSE ✢return Office of Science U. S. Department of Energy

process example static long process(void * prec, int pass) { xxxarray. Record *paf = (xxxarray. Record *)prec; xxxdest *pdset = (xxxdset *)paf->dset; unsigned char pact = paf->pact; unsigned short monitor_mask; /* Must have dset defined */ if(!pdset !! (pdset->number< 5) || !pdest->read ) { /*set pact true so process will not be called*/ paf->pact = TRUE; return(0); } (*pdset->read)(paf); /*return if beginning of asyn processing */ if(!pact && paf->pact) return(0); paf->pact = TRUE; alarm(paf); /*sample monitor code */ monitor_mask = rec. Gbl. Reset. Alarms(paf); monitor_mask |= (DBE_LOG|DBE_VALUE) db_post_events(paf, paf->val, monitor_mask); rec. Gbl. Fwd. Link(paf); paf->pact = FALSE return(0); } Pioneering Science and Technology Office of Science U. S. Department of Energy

alarm and monitors u alarms v rec. Gbl. Set. Sevr(void *prec, <alarm_status>, <alarm_severity>) v Status and severity values defined in alarm. h v Must prevent alarm storms on numeric values ✤value fluctuating around alarm limit ✤See Application Developer’s guide for algorithm v process must call rec. Gbl. Reset. Alarms after all alarms have been raised and before calling rec. Gbl. Fwd. Link. Also, if possible, before raising monitors. u monitors v db_post_event(void *prec, void *pfield, monitor_mask) v Call for all fields that change as a result of record processing v Support value change hysteresis when possible. v Look at ai. Record for an example Pioneering Science and Technology Office of Science U. S. Department of Energy

Routines with a DBADDR argument u Called by database/channel access u Call db. Get. Field. Index to find out which field. int field. Index; field. Index = db. Get. Field. Index(pdbaddr); if(field. Index == ai. Record. VAL). . . u DBADDR typedef struct db. Addr{ db. Common *precord; void *pfield; void *pfld. Des; void *as. Pvt; long no_elements; short field_type; short field_size; short special; short dbr_field_type; }DBADDR; Pioneering Science and Technology Office of Science U. S. Department of Energy

Record Support Routines - Cont. u special(DBADDR *pdbaddr, int after) v Called if special defined in dbd file v Called before and after field is modified. v db. Get. Field. Index(pdbaddr) v pdbaddr->special ✤ The special type as defined in. dbd file. USE SPC_MOD. ✤Must include file special. h u cvt_dbaddr(DBADDR *pdbaddr) v Called by database library when DB or CA connects to field. v Called if special(SPC_DBADDR) specified v Following fields of DBADDR can be changed no_elements field_type field_size special dbr_type Pioneering Science and Technology Office of Science U. S. Department of Energy

Record Support Routines - Cont. u Array Routines v Called if cvt_dbaddr sets no_elements > 1 v get_array_info(DBADDR *pdbaddr, long *no_elements, long *offset) ✤Called when database access gets an array ✤Must set no_elements ✤Can set offset if field is circular buffer v put_array_info( DBADDR *pdbaddr, long n. New) Called after database access has written array Pioneering Science and Technology Office of Science U. S. Department of Energy

Record Support Routines - Cont. u Units/Precision v get_units(DBADDR *pdbaddr, char *punits) CA has MAX_UNITS_SIZE 8 v get_precision(DBADDR *pdbaddr, long *precision) Problems with only precision. u Enumerated Values v get_enum_str(DBADDR *pdbaddr, char *p) v put_enum_str(DBADDR *pdbaddr, char *p) v get_enum_strs(DBADDR *pdbaddr, dbr_enum. Strs *p) CA has limit of 16 choices, 26 characters in each choice u Graphic/ Control/ Alarm Limits v get_graphic_double(DBADDR *pdbaddr, struct dbr_gr. Double *p) v get_control_double(DBADDR *pdbaddr, struct dbr_ctrl. Double *p) v get_alarm_double(DBADDR *pdbaddr, struct dbr_al. Double *p) Pioneering Science and Technology Office of Science U. S. Department of Energy

Global Record Support Routines u All start with rec. Gbl u Intended for record/device support but also called by other code u Reporting Errors Deprecated - Use errlog. Printf instead u Alarm Processing v rec. Gbl. Set. Sevr(void *precord, short newstat, short newsevr) v rec. Gbl. Reset. Alarms(void *precord); u Limits v rec. Gbl. Get. Graphic. Double, rec. Gbl. Get. Control. Double, etc. v Defaults for fields record support doesn’t know how to handle v Channel Access client often not happy v Graphics, Control, Alarm limits u rec. Gbl. Init. Constant. Link For use on link fields with a constant value. Only works on numeric values!! Pioneering Science and Technology Office of Science U. S. Department of Energy

Global Record Support Routines continued u rec. Gbl. Get. Time. Stamp record support should call this each time record completes processing. u rec. Gbl. Fwd. Link Must be called with pact true and all other processing complete Pioneering Science and Technology Office of Science U. S. Department of Energy

Database Access Routines for Record Support u When in context of process use db. Get. Link, db. Put. Link u Link information v db. Get. Pdb. Addr. From. Link gets address of DBADDR. v db. Get. Rset gets address of Record Support Entry table u db. Is. Link. Connected Is link connected? Pioneering Science and Technology Office of Science U. S. Department of Energy