1 1999/Ph 514: Record Support EPICS Record Support Marty Kraimer APS

2 1999/Ph 514: Record Support EPICS u Record Support u Implements a Record Type u Plugs into database common environment u Implementation steps u Prepare a Database Definition (.dbd) file u Create a C source file which implements semantics u Start with existing support!!! u Documentation u App Dev Guide - Chapters 3 and 8 u makeBaseApp example - xxxRecord u base/src/rec

3 1999/Ph 514: Record Support EPICS Database Definition File - dbd u Syntax recordtype( ) { include “dbCommon.dbd” field(, ) { } field(, ) { }... } u Example recordtype(example) { include “dbCommon.dbd” field(PREC,DBF_DOUBLE) { prompt(“Display Precision”) promptGroup(GUI_DISPLAY) } field(VAL,DBF_DOUBLE) }

4 1999/Ph 514: Record Support EPICS dbd - cont.  Should be alphanumeric starting with letter u u Should be alphanumeric starting with letter u For now length is limited to four characters u In dbd file this should be upper case. It is converted to lower case in include file. u 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

5 1999/Ph 514: Record Support EPICS dbd - cont u  asl : access security level  ASL1 - Fields seldom modified - default  ASL0 - Fields meant to be modified  initial : initial value  prompt : string for Database Configuration  promptgroup : Should DCT allow field to be configured? Many groups but no DCT distinguishes between groups.  special: Special handling on put u Several values  SPC_MOD, SPC_DBADDR, SPC SPC_NOMOD  pp : process passive record on put?  interest : interest level used by dbpr  base : DECIMAL (default) or HEX  size : For DBF_STRING  extra : For DBF_NOACCESS  menu : For DBF_MENU.

6 1999/Ph 514: Record Support EPICS String Field  DBF_STRING fields u Fixed length null terminated strings u Channel access support max of 40 characters u Arrays of character strings are possible u Example field(VAL,DBF_STRING) { size(40) prompt(“value”) promptgroup(GUI_DISPLAY) }

7 1999/Ph 514: Record Support EPICS Numeric Fields  DBF_CHAR, …, DBF_DOUBLE u Standard C datatypes  Note that DBF_CHAR, DBF_UCHAR problem u All attributes except size, extra, menu meaningful u Arrays  dbd file must define special(SPC_DBADDR)  Record support must implement cvt_dbaddr, get_array_info, put_array_info u No support by Database Configuration Tools.

8 1999/Ph 514: Record Support EPICS Enumerated Fields  DBF_ENUM u Record Support provides choices and index  See biRecord, mbbiRecord, etc  Actual field type is unsigned short u Record support MUST implement u get_enum_str u put_enum_str u get_enum_strs

9 1999/Ph 514: Record Support EPICS Menu Fields u DBF_MENU menu( ) { choice(,” “) … } … recordtype( ) { field(,DBF_MENU) { menu( ) } u Example menu(menuYesNo) { choice(menuYesNo,”NO”) choice(menuYesNo,”YES”) } … field(PINI,DBF_MENU) { … menu(menuYesNo) }

/Ph 514: Record Support EPICS Device Field  DBF_DEVICE  Database Common Field - DTYP u Related to device definitions  Has associated INP or OUT field u Device Support must be provided u Example device(ai,CONSTANT,devAiSoft,”Soft Channel”) device(ai,CONSTANT,devAiSoftRaw,”Raw Soft Channel”)

/Ph 514: Record Support EPICS link Fields  DBF_INLINK, DBF_OUTLINK  Not INP or OUT u Constant link - Just initialization  PV_LINK becomes DB_LINK or CA_LINK  INP or OUT and Device Support u device definitions determine choices u Associated with choice is bus type  Gory details in link.h  DBF_FWDLINK u references another record which is processed if it is passive.  FLNK u In dbCommon  record support calls recGblFwdLink  Other DBF_FWDLINKs can be defined  Call dbScanFwdLink NOT recGblFwdLink

/Ph 514: Record Support EPICS Generated Include Files  dbToMenuH u Code should use generated files. u menuYesNo.h typedef enum { menuYesNoNO, menuYesNoYES } menuYesNo;  dbToRecordTypeH u Code MUST use generated files u Include code to compute field sizes, offsets typedef struct aiRecord { charname[29]; … } #define aiRecordNAME 0 … #ifdef GEN_SIZE_OFFSET int aiRecordSizeOffset(dbRecordType *p) { … } u Only record support and associated device support is allowed to use the include files.

/Ph 514: Record Support EPICS Record Support Routines u Provide Execution Semantics  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 RSET = { RSETNUMBER, report, initialize, init_record, process, … };

/Ph 514: Record Support EPICS Record Support Routines - Summary u Report, Initialization, Processing u report u initialize u init_record u process u Support for Channel/ Database Access u special u cvt_dbaddr u get_array_info u put_array_info u get_units u get_precision u get_enum_str u put_enum_str u get_enum_strs u get_graphic_double u get_control_double u get_alarm_double

/Ph 514: Record Support EPICS Report, Initialization, Processing  report(void *precord) u Nothing calls this. u Normally not implemented u initialize(void) u Called once before first call to init_record u Not normally needed  init_record(void *precord, int pass) u Normally implemented u Called twice u pass 0 - Can do anything except access other records. For example storage for arrays should be allocated during pass 0. u pass 1 - Finish initialization and also call associated device support initialization  process u VERY IMPORTANT u Implements record semantics

/Ph 514: Record Support EPICS init_record example /* assume val is double *val */ typedef struct xxxdset { long number, DEVSUPFUN report; DEVSUPFUN init; DEVSUPFUN init_record; DEVSUPFUN get_ioint_info; DEVSUPFUN read; } xxxdset; static long init_record(void *prec, int pass) { xxxarrayRecord *paf = (xxxarrayRecord *)prec; xxxdest *pdset = (xxxdset *)paf->dset; if(pass==0) { if(paf->nelm nelm = 1; paf->val = (double *)calloc( paf->nelm,sizeof(double)); return(0); } /* Must have dset defined */ if(!pdset !! (pdset->number read ) { epicsPrintf(“%s no or invalid dset\n”, paf->name); return(0); } (*pdset->init_record)(paf); return(0); }

/Ph 514: Record Support EPICS process overview  process is called if u Decision was made to process the record  Record not active ( PACT FALSE )  Record is enabled ( DISV !=DISA )  process with device support must  set record active ( PACT TRUE ) u Perform I/O u Check for record specific alarms u Raise database monitors u Request processing of forward links  Set PACT FALSE and return

/Ph 514: Record Support EPICS process overview continued u For asynchronous devices. u Asynchronous start u Initiate I/O. u Determine a method for again calling process when operation completes  Return leaving PACT TRUE. u Asynchronous completion  Call process as follows: dbScanLock(precord); *(prset->process)(precord); dbScanUnlock(precord);  process completes record processing u Complete I/O u Check for record specific alarms u Raise database monitors u Request processing of forward links  Set PACT FALSE u return

/Ph 514: Record Support EPICS process example static long process(void *prec, int pass) { xxxarrayRecord *paf = (xxxarrayRecord *)prec; xxxdest *pdset = (xxxdset *)paf->dset; unsigned char pact = paf->pact; unsigned short monitor_mask; /* Must have dset defined */ if(!pdset !! (pdset->number 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 = recGblResetAlarms(paf); monitor_mask |= (DBE_LOG|DBE_VALUE) db_post_events(paf,paf->val,monitor_mask); recGblFwdLink(paf); paf->pact = FALSE return(0); }

/Ph 514: Record Support EPICS alarm and monitors u alarms u recGblSetSevr(void *prec,, )  Status and severity values defined in alarm.h u Must prevent alarm storms on numeric values u value fluctuating around alarm limit u See Application Developer’s guide for algorithm  process must call recGblResetAlarms after all alarms have been raised and before calling recGblFwdLink. Also, if possible, before raising monitors. u monitors u db_post_event(void *prec, void *pfield, monitor_mask) u Call for all fields that change as a result of record processing u Support value change hysteresis when possible.  Look at aiRecord for an example

/Ph 514: Record Support EPICS Routines with a DBADDR argument u Called by database/channel access  Call dbGetFieldIndex to find out which field. int fieldIndex; fieldIndex = dbGetFieldIndex(pdbaddr); if(fieldIndex == aiRecordVAL)...  DBADDR typedef struct dbAddr{ dbCommon *precord; void *pfield; void *pfldDes; void *asPvt; long no_elements; short field_type; short field_size; short special; short dbr_field_type; }DBADDR;

/Ph 514: Record Support EPICS Record Support Routines - Cont.  special(DBADDR *pdbaddr,int after)  Called if special defined in dbd file u Called before and after field is modified. u dbGetFieldIndex(pdbaddr)  pdbaddr->special u The special type as defined in.dbd file.  Must include file special.h u cvt_dbaddr(DBADDR *pdbaddr) u Called by database library when DB/CA connects to field.  Called if special(SPC_DBADDR) specified  Following fields of DBADDR can be changed no_elements field_type field_size special dbr_type

/Ph 514: Record Support EPICS Record Support Routines - Cont. u Array Routines  Called if cvt_dbaddr sets no_elements > 1 u get_array_info(DBADDR *pdbaddr, long *no_elements, long *offset) u Called when database access gets an array  Must set no_elements u Can set offset if field is circular buffer  put_array_info( DBADDR *pdbaddr,long nNew) Called after database access has written array

/Ph 514: Record Support EPICS Record Support Routines - Cont. u Units/Precision  get_units(DBADDR *pdbaddr, char *punits) CA has MAX_UNITS_SIZE 8  get_precision(DBADDR *pdbaddr, long *precision) Problems with only precision. u Enumerated Values u get_enum_str(DBADDR *pdbaddr,char *p) u put_enum_str(DBADDR *pdbaddr,char *p)  get_enum_strs(DBADDR *pdbaddr, dbr_enumStrs *p) CA has limit of 16 choices, 26 characters in each choice u Graphic/ Control/ Alarm Limits u get_graphic_double(DBADDR *pdbaddr,struct dbr_grDouble *p) u get_control_double(DBADDR *pdbaddr,struct dbr_ctrlDouble *p) u get_alarm_double(DBADDR *pdbaddr,struct dbr_alDouble *p)

/Ph 514: Record Support EPICS Global Record Support Routines  All start with recGbl u Intended for record/device support but also called by other code  Reporting Errors Deprecated - Use epicsPrintf instead u Alarm Processing u recGblSetSevr(void *precord, short newstat, short newsevr) u recGblResetAlarms(void *precord); u Limits u Defaults for fields record support doesn’t know how to handle u Channel Access client often not happy u Graphics, Control, Alarm limits  recGblInitConstantLink For use on link fields with a constant value. Only works on numeric values!!

/Ph 514: Record Support EPICS Global Record Support Routines continued  recGblGetTimeStamp record support should call this each time record completes processing.  recGblFwdLink Must be called with pact true and all other processing complete

/Ph 514: Record Support EPICS Database Access Routines for Record Support u When in context of process use dbGetLink, dbPutLink u Link information  dbGetPdbAddrFromLink gets address of DBADDR.  dbGetRset gets address of Record Support Entry table  dbIsLinkConnected Is link connected?