Array Subroutine Record (aSub)

The aSub record is an advanced variant of the 'sub' (subroutine) record which has a number of additional features:

Record-specific Menus

Menu aSubLFLG

The LFLG menu field controls whether the SUBL link will be read to update the name of the subroutine to be called when the record processes.

IndexIdentifierChoice String
0 aSubLFLG_IGNORE IGNORE
1 aSubLFLG_READ READ

Menu aSubEFLG

The EFLG menu field indicates whether monitor events should be posted for the VALA..VALU output value fields.

IndexIdentifierChoice String
0 aSubEFLG_NEVER NEVER
1 aSubEFLG_ON_CHANGE ON CHANGE
2 aSubEFLG_ALWAYS ALWAYS

Parameter Fields

The record-specific fields are described below.

Subroutine Fields

The VAL field is set to the value returned by the user subroutine. The value is treated as an error status value where zero mean success. The output links OUTA ... OUTU will only be used to forward the associated output value fields when the subroutine has returned a zero status. If the return status was non-zero, the record will be put into SOFT_ALARM state with severity given by the BRSV field.

The INAM field may be used to name a subroutine that will be called once at IOC initialization time.

LFLG tells the record whether to read or ignore the SUBL link. If the value is READ, then the name of the subroutine to be called at process time is read from SUBL. If the value is IGNORE, the name of the subroutine is that currently held in SNAM.

A string is read from the SUBL link to fetch the name of the subroutine to be run during record processing.

SNAM holds the name of the subroutine to be called when the record processes. The value in this field can be overwritten by the SUBL link if LFLG is set to READ.

The SADR field is only accessible from C code; it points to the subroutine to be called.

The CADR field may be set by the user subroutine to point to another function that will be called immediately before setting the SADR field to some other routine. This allows the main user subroutine to allocate resources when it is first called and be able to release them again when they are no longer needed.

FieldSummaryTypeDCT DefaultReadWriteCA PP
VALSubr. return valueLONGNo YesYesNo
OVALOld return valueLONGNo YesNoNo
INAMInitialize Subr. NameSTRING [41]Yes YesNoNo
LFLGSubr. Input EnableMENU (aSubLFLG)Yes YesYesNo
SUBLSubroutine Name LinkINLINKYes YesNoNo
SNAMProcess Subr. NameSTRING [41]Yes YesYesNo
ONAMOld Subr. NameSTRING [41]Yes YesNoNo
SADRSubroutine AddressNOACCESSNo NoNoNo
CADRSubroutine Cleanup AddressNOACCESSNo NoNoNo
BRSVBad Return SeverityMENU (menuAlarmSevr)Yes YesYesYes

Operator Display Parameters

The PREC field specifies the number of decimal places with which to display the values of the value fields A ... U and VALA ... VALU. Except when it doesn't.

Output Event Flag

This field tells the record when to post change events on the output fields VALA ... VALU. If the value is NEVER, events are never posted. If the value is ALWAYS, events are posted every time the record processes. If the value is ON CHANGE, events are posted when any element of an array changes value. This flag controls value, log (archive) and alarm change events.

FieldSummaryTypeDCT DefaultReadWriteCA PP
EFLGOutput Event FlagMENU (aSubEFLG)Yes1YesYesNo

Input Link Fields

The input links from where the values of A,...,U are fetched during record processing.

FieldSummaryTypeDCT DefaultReadWriteCA PP
INPAInput Link AINLINKYes YesYesNo
INPBInput Link BINLINKYes YesYesNo
INPCInput Link CINLINKYes YesYesNo
INPDInput Link DINLINKYes YesYesNo
INPEInput Link EINLINKYes YesYesNo
INPFInput Link FINLINKYes YesYesNo
INPGInput Link GINLINKYes YesYesNo
INPHInput Link HINLINKYes YesYesNo
INPIInput Link IINLINKYes YesYesNo
INPJInput Link JINLINKYes YesYesNo
INPKInput Link KINLINKYes YesYesNo
INPLInput Link LINLINKYes YesYesNo
INPMInput Link MINLINKYes YesYesNo
INPNInput Link NINLINKYes YesYesNo
INPOInput Link OINLINKYes YesYesNo
INPPInput Link PINLINKYes YesYesNo
INPQInput Link QINLINKYes YesYesNo
INPRInput Link RINLINKYes YesYesNo
INPSInput Link SINLINKYes YesYesNo
INPTInput Link TINLINKYes YesYesNo
INPUInput Link UINLINKYes YesYesNo

Input Value Fields

Thse fields hold the scalar or array values fetched through the input links INPA,...,INPU.

FieldSummaryTypeDCT DefaultReadWriteCA PP
AInput value ASet by FTANo YesYesNo
BInput value BSet by FTBNo YesYesNo
CInput value CSet by FTCNo YesYesNo
DInput value DSet by FTDNo YesYesNo
EInput value ESet by FTENo YesYesNo
FInput value FSet by FTFNo YesYesNo
GInput value GSet by FTGNo YesYesNo
HInput value HSet by FTHNo YesYesNo
IInput value ISet by FTINo YesYesNo
JInput value JSet by FTJNo YesYesNo
KInput value KSet by FTKNo YesYesNo
LInput value LSet by FTLNo YesYesNo
MInput value MSet by FTMNo YesYesNo
NInput value NSet by FTNNo YesYesNo
OInput value OSet by FTONo YesYesNo
PInput value PSet by FTPNo YesYesNo
QInput value QSet by FTQNo YesYesNo
RInput value RSet by FTRNo YesYesNo
SInput value SSet by FTSNo YesYesNo
TInput value TSet by FTTNo YesYesNo
UInput value USet by FTUNo YesYesNo

Input Value Data Types

Field types of the input value fields. The choices can be found by following the link to the menuFtype definition.

FieldSummaryTypeDCT DefaultReadWriteCA PP
FTAType of AMENU (menuFtype)YesDOUBLEYesNoNo
FTBType of BMENU (menuFtype)YesDOUBLEYesNoNo
FTCType of CMENU (menuFtype)YesDOUBLEYesNoNo
FTDType of DMENU (menuFtype)YesDOUBLEYesNoNo
FTEType of EMENU (menuFtype)YesDOUBLEYesNoNo
FTFType of FMENU (menuFtype)YesDOUBLEYesNoNo
FTGType of GMENU (menuFtype)YesDOUBLEYesNoNo
FTHType of HMENU (menuFtype)YesDOUBLEYesNoNo
FTIType of IMENU (menuFtype)YesDOUBLEYesNoNo
FTJType of JMENU (menuFtype)YesDOUBLEYesNoNo
FTKType of KMENU (menuFtype)YesDOUBLEYesNoNo
FTLType of LMENU (menuFtype)YesDOUBLEYesNoNo
FTMType of MMENU (menuFtype)YesDOUBLEYesNoNo
FTNType of NMENU (menuFtype)YesDOUBLEYesNoNo
FTOType of OMENU (menuFtype)YesDOUBLEYesNoNo
FTPType of PMENU (menuFtype)YesDOUBLEYesNoNo
FTQType of QMENU (menuFtype)YesDOUBLEYesNoNo
FTRType of RMENU (menuFtype)YesDOUBLEYesNoNo
FTSType of SMENU (menuFtype)YesDOUBLEYesNoNo
FTTType of TMENU (menuFtype)YesDOUBLEYesNoNo
FTUType of UMENU (menuFtype)YesDOUBLEYesNoNo

Input Value Array Capacity

These fields specify how many array elements the input value fields may hold.

FieldSummaryTypeDCT DefaultReadWriteCA PP
NOAMax. elements in AULONGYes1YesNoNo
NOBMax. elements in BULONGYes1YesNoNo
NOCMax. elements in CULONGYes1YesNoNo
NODMax. elements in DULONGYes1YesNoNo
NOEMax. elements in EULONGYes1YesNoNo
NOFMax. elements in FULONGYes1YesNoNo
NOGMax. elements in GULONGYes1YesNoNo
NOHMax. elements in HULONGYes1YesNoNo
NOIMax. elements in IULONGYes1YesNoNo
NOJMax. elements in JULONGYes1YesNoNo
NOKMax. elements in KULONGYes1YesNoNo
NOLMax. elements in LULONGYes1YesNoNo
NOMMax. elements in MULONGYes1YesNoNo
NONMax. elements in NULONGYes1YesNoNo
NOOMax. elements in OULONGYes1YesNoNo
NOPMax. elements in PULONGYes1YesNoNo
NOQMax. elements in QULONGYes1YesNoNo
NORMax. elements in RULONGYes1YesNoNo
NOSMax. elements in SULONGYes1YesNoNo
NOTMax. elements in TULONGYes1YesNoNo
NOUMax. elements in UULONGYes1YesNoNo

Input Value Array Size

These fields specify how many array elements the input value fields currently contain.

FieldSummaryTypeDCT DefaultReadWriteCA PP
NEANum. elements in AULONGNo1YesNoNo
NEBNum. elements in BULONGNo1YesNoNo
NECNum. elements in CULONGNo1YesNoNo
NEDNum. elements in DULONGNo1YesNoNo
NEENum. elements in EULONGNo1YesNoNo
NEFNum. elements in FULONGNo1YesNoNo
NEGNum. elements in GULONGNo1YesNoNo
NEHNum. elements in HULONGNo1YesNoNo
NEINum. elements in IULONGNo1YesNoNo
NEJNum. elements in JULONGNo1YesNoNo
NEKNum. elements in KULONGNo1YesNoNo
NELNum. elements in LULONGNo1YesNoNo
NEMNum. elements in MULONGNo1YesNoNo
NENNum. elements in NULONGNo1YesNoNo
NEONum. elements in OULONGNo1YesNoNo
NEPNum. elements in PULONGNo1YesNoNo
NEQNum. elements in QULONGNo1YesNoNo
NERNum. elements in RULONGNo1YesNoNo
NESNum. elements in SULONGNo1YesNoNo
NETNum. elements in TULONGNo1YesNoNo
NEUNum. elements in UULONGNo1YesNoNo

Output Link Fields

The output links through which the VALA ... VALU field values are sent during record processing, provided the subroutine returned 0.

FieldSummaryTypeDCT DefaultReadWriteCA PP
OUTAOutput Link AOUTLINKYes YesYesNo
OUTBOutput Link BOUTLINKYes YesYesNo
OUTCOutput Link COUTLINKYes YesYesNo
OUTDOutput Link DOUTLINKYes YesYesNo
OUTEOutput Link EOUTLINKYes YesYesNo
OUTFOutput Link FOUTLINKYes YesYesNo
OUTGOutput Link GOUTLINKYes YesYesNo
OUTHOutput Link HOUTLINKYes YesYesNo
OUTIOutput Link IOUTLINKYes YesYesNo
OUTJOutput Link JOUTLINKYes YesYesNo
OUTKOutput Link KOUTLINKYes YesYesNo
OUTLOutput Link LOUTLINKYes YesYesNo
OUTMOutput Link MOUTLINKYes YesYesNo
OUTNOutput Link NOUTLINKYes YesYesNo
OUTOOutput Link OOUTLINKYes YesYesNo
OUTPOutput Link POUTLINKYes YesYesNo
OUTQOutput Link QOUTLINKYes YesYesNo
OUTROutput Link ROUTLINKYes YesYesNo
OUTSOutput Link SOUTLINKYes YesYesNo
OUTTOutput Link TOUTLINKYes YesYesNo
OUTUOutput Link UOUTLINKYes YesYesNo

Output Value Fields

These fields hold scalar or array data generated by the subroutine which will be sent through the OUTA ... OUTU links during record processing.

FieldSummaryTypeDCT DefaultReadWriteCA PP
VALAOutput value ASet by FTVANo YesYesNo
VALBOutput value BSet by FTVBNo YesYesNo
VALCOutput value CSet by FTVCNo YesYesNo
VALDOutput value DSet by FTVDNo YesYesNo
VALEOutput value ESet by FTVENo YesYesNo
VALFOutput value FSet by FTVFNo YesYesNo
VALGOutput value GSet by FTVGNo YesYesNo
VALHOutput value HSet by FTVHNo YesYesNo
VALIOutput value ISet by FTVINo YesYesNo
VALJOutput value JSet by FTVJNo YesYesNo
VALKOutput value KSet by FTVKNo YesYesNo
VALLOutput value LSet by FTVLNo YesYesNo
VALMOutput value MSet by FTVMNo YesYesNo
VALNOutput value NSet by FTVNNo YesYesNo
VALOOutput value OSet by FTVONo YesYesNo
VALPOutput value PSet by FTVPNo YesYesNo
VALQOutput value QSet by FTVQNo YesYesNo
VALROutput value RSet by FTVRNo YesYesNo
VALSOutput value SSet by FTVSNo YesYesNo
VALTOutput value TSet by FTVTNo YesYesNo
VALUOutput value USet by FTVUNo YesYesNo

Old Value Fields

The previous values of the output fields. These are used to determine when to post events if EFLG is set to ON CHANGE.

FieldSummaryTypeDCT DefaultReadWriteCA PP
VALAOutput value ASet by FTVANo YesYesNo
VALBOutput value BSet by FTVBNo YesYesNo
VALCOutput value CSet by FTVCNo YesYesNo
VALDOutput value DSet by FTVDNo YesYesNo
VALEOutput value ESet by FTVENo YesYesNo
VALFOutput value FSet by FTVFNo YesYesNo
VALGOutput value GSet by FTVGNo YesYesNo
VALHOutput value HSet by FTVHNo YesYesNo
VALIOutput value ISet by FTVINo YesYesNo
VALJOutput value JSet by FTVJNo YesYesNo
VALKOutput value KSet by FTVKNo YesYesNo
VALLOutput value LSet by FTVLNo YesYesNo
VALMOutput value MSet by FTVMNo YesYesNo
VALNOutput value NSet by FTVNNo YesYesNo
VALOOutput value OSet by FTVONo YesYesNo
VALPOutput value PSet by FTVPNo YesYesNo
VALQOutput value QSet by FTVQNo YesYesNo
VALROutput value RSet by FTVRNo YesYesNo
VALSOutput value SSet by FTVSNo YesYesNo
VALTOutput value TSet by FTVTNo YesYesNo
VALUOutput value USet by FTVUNo YesYesNo

Output Value Data Types

Field types of the output value fields. The choices can be found by following a link to the menuFtype definition.

FieldSummaryTypeDCT DefaultReadWriteCA PP
FTVAType of VALAMENU (menuFtype)YesDOUBLEYesNoNo
FTVBType of VALBMENU (menuFtype)YesDOUBLEYesNoNo
FTVCType of VALCMENU (menuFtype)YesDOUBLEYesNoNo
FTVDType of VALDMENU (menuFtype)YesDOUBLEYesNoNo
FTVEType of VALEMENU (menuFtype)YesDOUBLEYesNoNo
FTVFType of VALFMENU (menuFtype)YesDOUBLEYesNoNo
FTVGType of VALGMENU (menuFtype)YesDOUBLEYesNoNo
FTVHType of VALHMENU (menuFtype)YesDOUBLEYesNoNo
FTVIType of VALIMENU (menuFtype)YesDOUBLEYesNoNo
FTVJType of VALJMENU (menuFtype)YesDOUBLEYesNoNo
FTVKType of VALKMENU (menuFtype)YesDOUBLEYesNoNo
FTVLType of VALLMENU (menuFtype)YesDOUBLEYesNoNo
FTVMType of VALMMENU (menuFtype)YesDOUBLEYesNoNo
FTVNType of VALNMENU (menuFtype)YesDOUBLEYesNoNo
FTVOType of VALOMENU (menuFtype)YesDOUBLEYesNoNo
FTVPType of VALPMENU (menuFtype)YesDOUBLEYesNoNo
FTVQType of VALQMENU (menuFtype)YesDOUBLEYesNoNo
FTVRType of VALRMENU (menuFtype)YesDOUBLEYesNoNo
FTVSType of VALSMENU (menuFtype)YesDOUBLEYesNoNo
FTVTType of VALTMENU (menuFtype)YesDOUBLEYesNoNo
FTVUType of VALUMENU (menuFtype)YesDOUBLEYesNoNo

Output Value Array Capacity

These fields specify how many array elements the output value fields may hold.

FieldSummaryTypeDCT DefaultReadWriteCA PP
NOVAMax. elements in VALAULONGYes1YesNoNo
NOVBMax. elements in VALBULONGYes1YesNoNo
NOVCMax. elements in VALCULONGYes1YesNoNo
NOVDMax. elements in VALDULONGYes1YesNoNo
NOVEMax. elements in VALEULONGYes1YesNoNo
NOVFMax. elements in VALFULONGYes1YesNoNo
NOVGMax. elements in VALGULONGYes1YesNoNo
NOVHMax. elements in VAlHULONGYes1YesNoNo
NOVIMax. elements in VALIULONGYes1YesNoNo
NOVJMax. elements in VALJULONGYes1YesNoNo
NOVKMax. elements in VALKULONGYes1YesNoNo
NOVLMax. elements in VALLULONGYes1YesNoNo
NOVMMax. elements in VALMULONGYes1YesNoNo
NOVNMax. elements in VALNULONGYes1YesNoNo
NOVOMax. elements in VALOULONGYes1YesNoNo
NOVPMax. elements in VALPULONGYes1YesNoNo
NOVQMax. elements in VALQULONGYes1YesNoNo
NOVRMax. elements in VALRULONGYes1YesNoNo
NOVSMax. elements in VALSULONGYes1YesNoNo
NOVTMax. elements in VALTULONGYes1YesNoNo
NOVUMax. elements in VALUULONGYes1YesNoNo

Output Value Array Size

These fields specify how many array elements the output value fields currently contain.

FieldSummaryTypeDCT DefaultReadWriteCA PP
NEVANum. elements in VALAULONGNo1YesNoNo
NEVBNum. elements in VALBULONGNo1YesNoNo
NEVCNum. elements in VALCULONGNo1YesNoNo
NEVDNum. elements in VALDULONGNo1YesNoNo
NEVENum. elements in VALEULONGNo1YesNoNo
NEVFNum. elements in VALFULONGNo1YesNoNo
NEVGNum. elements in VALGULONGNo1YesNoNo
NEVHNum. elements in VAlHULONGNo1YesNoNo
NEVINum. elements in VALIULONGNo1YesNoNo
NEVJNum. elements in VALJULONGNo1YesNoNo
NEVKNum. elements in VALKULONGNo1YesNoNo
NEVLNum. elements in VALLULONGNo1YesNoNo
NEVMNum. elements in VALMULONGNo1YesNoNo
NEVNNum. elements in VALNULONGNo1YesNoNo
NEVONum. elements in VALOULONGNo1YesNoNo
NEVPNum. elements in VALPULONGNo1YesNoNo
NEVQNum. elements in VALQULONGNo1YesNoNo
NEVRNum. elements in VALRULONGNo1YesNoNo
NEVSNum. elements in VALSULONGNo1YesNoNo
NEVTNum. elements in VALTULONGNo1YesNoNo
NEVUNum. elements in VALUULONGNo1YesNoNo

Old Value Array Size

These fields specify how many array elements the old value fields currently contain.

FieldSummaryTypeDCT DefaultReadWriteCA PP
ONVANum. elements in OVLAULONGNo1YesNoNo
ONVBNum. elements in OVLBULONGNo1YesNoNo
ONVCNum. elements in OVLCULONGNo1YesNoNo
ONVDNum. elements in OVLDULONGNo1YesNoNo
ONVENum. elements in OVLEULONGNo1YesNoNo
ONVFNum. elements in OVLFULONGNo1YesNoNo
ONVGNum. elements in OVLGULONGNo1YesNoNo
ONVHNum. elements in VAlHULONGNo1YesNoNo
ONVINum. elements in OVLIULONGNo1YesNoNo
ONVJNum. elements in OVLJULONGNo1YesNoNo
ONVKNum. elements in OVLKULONGNo1YesNoNo
ONVLNum. elements in OVLLULONGNo1YesNoNo
ONVMNum. elements in OVLMULONGNo1YesNoNo
ONVNNum. elements in OVLNULONGNo1YesNoNo
ONVONum. elements in OVLOULONGNo1YesNoNo
ONVPNum. elements in OVLPULONGNo1YesNoNo
ONVQNum. elements in OVLQULONGNo1YesNoNo
ONVRNum. elements in OVLRULONGNo1YesNoNo
ONVSNum. elements in OVLSULONGNo1YesNoNo
ONVTNum. elements in OVLTULONGNo1YesNoNo
ONVUNum. elements in OVLUULONGNo1YesNoNo



Record Support Routines

init_record

  long (*init_record)(struct dbCommon *precord, int pass)

This routine is called twice at iocInit. On the first call it does the following:

On the second call, it does the following:

process

  long (*process)(struct dbCommon *precord)

This routine implements the following algorithm:

Normal processing:

Asynchronous-completion processing:




Use of the aSub Record

The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU), which are completely independent. The input-value fields have associated input links (INPA-INPU), and the output-value fields have associated output links (OUTA-OUTU). Both inputs and outputs have type fields (FTA-FTU, FTVA-FTVU, which default to 'DOUBLE') and number-of-element fields (NOA-NOU, NOVA-NOVU, which default to '1'). The output links OUTA-OUTU will only be processed if the subroutine returns a zero (OK) status value.

Example database fragment

To use the A field to read an array from some other record, then, you would need a database fragment that might look something like this:

    record(aSub,"my_asub_record") {
        field(SNAM,"my_asub_routine")
        ...
        field(FTA, "LONG")
        field(NOA, "100")
        field(INPA, "myWaveform_1 NPP NMS")
        ...
    }

If you wanted some other record to be able to write to the A field, then you would delete the input link above. If you wanted the A field to hold a scalar value, you would either delete the NOA specification, or specify it as "1".

Example subroutine fragment

The associated subroutine code that uses the A field might look like this:

    static long my_asub_routine(aSubRecord *prec) {
        long i, *a;
        double sum=0;
        ...
        a = (long *)prec->a;
        for (i=0; i<prec->noa; i++) {
            sum += a[i];
        }
        ...
        return 0; /* process output links */
    }

Note that the subroutine code must always handle the value fields (A-U, VALA-VALU) as arrays, even if they contain only a single element.

Required export code

Aside from your own code, you must export and register your subroutines so the record can locate them. The simplest way is as follows:

    #include <registryFunction.h>
    #include <epicsExport.h>
    
    static long my_asub_routine(aSubRecord *prec) {
        ...
    }
    epicsRegisterFunction(my_asub_routine);

Required database-definition code

The .dbd file loaded by the ioc must then contain the following line, which tells the linker to include your object file in the IOC binary:

    function(my_asub_routine)

Device support, writing to hardware

The aSub record does not call any device support routines. If you want to write to hardware, you might use your output fields and links to write to some other record that can write to hardware.

Dynamically Changing the User Routine called during Record Processing

The aSub record allows the user to dynamically change which routine is called when the record processes. This can be done in two ways: