EPICSWIKI - User contributions [en]

RRM 3-14 Binary Output

2015-03-12T18:15:53Z

TimMooney: /* Convert and Write Parameters */

[[RRM 3-14|EPICS Record Reference Manual]]

= bo - Binary Output =

The normal use for this record type is to store a simple bit (0 or 1) value to be sent to a Digital Output module. It can also be used to write binary values into other records via database or channel access links. This record can implement both latched and momentary binary outputs depending on how the HIGH field is configured.

== Parameter Fields ==

The binary output's fields fall into the following categories:

* scan parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* run-time parameters

=== Scan Parameters ===

The binary output record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The binary output record must specify where its desired output originates. The desired output needs to be in engineering units.

The first field that determines where the desired output originates is the output mode select (OMSL) field, which can have two possible values: <CODE>closed_loop</CODE> or <CODE>supervisory</CODE>. If <CODE>supervisory</CODE> is specified, the value in the VAL field can be set externally via dbPuts at run-time. If <CODE>closed_loop</CODE> is specified, the VAL field's value is obtained from the address specified in the desired output location (DOL) field which can be a database link, a channel access link, or a constant. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

[[RRM 3-14 Concepts#Address Specification|Address Specification]] presents more information on database addresses and links. [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains the effect of database linkage on scanning.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DOL<TD>Desired Output Location (Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices#menuOmsl|menuOmsl]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Convert and Write Parameters ===

These parameters are used to determine where the binary output writes to and how to convert the engineering units to a raw signal. After VAL is set and forced to be either 1 or 0, as the result of either a dbPut or a new value being retrieved from the link in the DOL field, then what happens next depends on which device support routine is used and how the HIGH field is configured.

If the <CODE>Soft Channel</CODE> device support routine is specified, then the device support routine writes the VAL field's value to the address specified in the OUT field. Otherwise, RVAL is the value finally written by the device support routines after being converted.

If VAL is equal to 0, then the record processing routine sets RVAL equal to zero. When VAL is not equal to 0, then RVAL is set equal to the value contained in the MASK field. (MASK is set by the device support routines and is of no concern to the user.) Also when VAL is not 0 and after RVAL is set equal to MASK, the record processing routine checks to see if the HIGH field is greater than 0. If it is, then the routine will process the record again with VAL set to 0 after the number of seconds specified by HIGH. Thus, HIGH implements a momentary output which changes the state of the device back to 0 after ''N'' number of seconds.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>HIGH<TD>Seconds to Hold High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ZNAM<TD>Zero Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONAM<TD>One Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

==== Conversion Parameters ====

The ZNAM field has the string that corresponds to the 0 state, and the ONAM field holds the string that corresponds to the 1 state. These fields, other than being used to tell the operator what each state represents, are used to perform conversions if the value fetched by DOL is a string. If it is, VAL is set to the state correspond to that string. For instance, if the value fetched is the string "Off" and the ZNAM string is "Off," then VAL is set to 0.

After VAL is set, if VAL is equal to 0, then the record processing routine sets RVAL equal to zero. When VAL is not equal to 0, then RVAL is set equal to the value contained in the MASK field. (MASK is set by the device support routines and is of no concern to the user.) Also when VAL is equal to 1 and after RVAL is set equal to MASK, the record processing routine checks to see if the HIGH field is greater than 0. If it is, then the routine process the record again with VAL=0 after the number of seconds specified by HIGH. Thus, HIGH implements a latched output which changes the state of the device or link to 1, then changes it back to 0 after N number of seconds.

<TABLE BORDER="1">
<TD>ZNAM<TD>ASCII string defining state zero<TR>
<TD>ONAM<TD>ASCII string defining state one<TR>
<TD>HIGH<TD>If this value is greater than zero, then whenever VAL is set equal to 1, it is reset to zero after HIGH seconds.
</TABLE>

==== Output Specification ====

The OUT field specifies where the binary output record writes its output. It must specify the address of an I/O card if the record sends its output to hardware, and the DTYP field must contain a the corresponding device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

Otherwise, if the record is configured to use the soft device support modules, then it can be either a database link, a channel access link, or a constant. Be aware that nothing will be written when OUT is a constant. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses. Also, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on output to other records.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. The <CODE>get_enum_str</CODE> record support routine can retrieve the state string corresponding to the VAL's state. So if the value is 1, <CODE>get_enum_str</CODE> will return the string in the ONAM field; and if 0, <CODE>get_enum_str</CODE> will return the ZNAM string.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZNAM<TD>Zero Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONAM<TD>One Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

These parameters are used to determine the binary output's alarm condition and to determine the severity of that condition. The possible alarm conditions for binary outputs are the SCAN, READ , INVALID, and state alarms. The user can configure the state alarm conditions using these fields.

The possible values for these fields are <CODE>NO_ALARM</CODE>, <CODE>MINOR</CODE>, and <CODE>MAJOR</CODE>. The ZSV holds the severity for the zero state; OSV for the one state. COSV is used to cause an alarm whenever the state changes between the states (0-1, or 1-0) and its severity is configured as MINOR or MAJOR.

See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZSV<TD>Zero Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>OSV<TD>One Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>COSV<TD>Change of State Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices#menuIvoa|menuIvoa]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value<TD>USHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the binary output. They are not configurable using a configuration tool. They represent the current state of the binary output.

ORAW is used to determine if monitors should be triggered for RVAL at the same time they are triggered for VAL.

MASK is given a value by the device support routines and should not concern the user.

The RBV field is also set by device support. It is the actual read back value obtained from the hardware itself or from the associated device driver. The ORBV field is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM field holds the value of the last occurrence of the change of state alarm. It is used to implement the change of state alarm, and thus only has meaning if COSV is MINOR or MAJOR.

The MLST is used by the <CODE>process</CODE> record support routine to determine if archive and value change monitors are invoked. They are if MLST is not equal to VAL.

The WPDT field is a private field for honoring seconds to hold HIGH.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Hardware Mask<TD>ULONG<TD>No<TD>compute<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Readback Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ORBV<TD>Old Readback Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed Value<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Monitored Value<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RPVT<TD>Record Private<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD>No<TR>
<TD>WDPT<TD>Watchdog Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the binary output in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created .

This routine next checks to see that device support is available. The routine next checks to see if the device support write routine is defined.

If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then VAL is initialized to 1 if its value is nonzero or initialized to 0 if DOL is zero, and UDF is set to FALSE.

If device support includes init_record, it is called. VAL is set using RVAL, and UDF is set to FALSE.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_enum_str ====

Retrieves ASCII string corresponding to VAL.

==== get_enum_strs ====

Retrieves ASCII strings for ZNAM and ONAM.

==== put_enum_str ====

Checks if string matches ZNAM or ONAM, and if it does, sets VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE
#* if DOL is DB_LINK and OMSL is CLOSED_LOOP
#** get value from DOL
#** check for link alarm
#** force VAL to be 0 or 1
#** if MASK is defined
#*** if VAL is 0 set RVAL = 0
#** else set RVAL = MASK
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on how INVALID alarms affect output.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check WAIT. If VAL is 1 and WAIT is greater than 0, process again with a VAL=0 after WAIT seconds.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL and for RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each binary output record must have an associated set of device support routines. The primary responsibility of the device support routines is to write a new value whenever write_bo is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value Field<TD>This field is only of interest to device support routines that do not use MASK and RVAL.<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>RVAL<TD>Raw Data Value<TD>If MASK is defined then record support sets RVAL=(0,MASK) if VAL is (0, not zero).<TR>
<TD>MASK<TD>Hardware mask.<TD>The device support module must set this field. Not that if VAL is 1, then record processing sets RVAL = MASK.<TR>
<TD>RBV<TD>Read Back Value<TD>This is the actual read back value obtained from the hardware itself or from the associated device driver. It is the responsibility of the device support routine to give this field a value.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. It should determine MASK if it is needed.

* 0: Success. RVAL modified (VAL will be set accordingly)
* 2: Success. VAL modified
* other: Error.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_bo ====

write_bo(precord)

This routine must output an new value. It returns the following values:

* 0: Success.
* other: Error.

=== Device Support For Soft Records ===

Two soft device support modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided for output records not related to actual hardware devices. The OUT link type must be either a CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

This module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record. init_record always returns a value of 2, which means that no conversion will ever be attempted. write_bo calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]] for details.

==== Raw Soft Channel ====

This module is like the previous except that it writes the current value of RVAL.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Binary Output

2015-03-12T18:15:14Z

TimMooney: /* Desired Output Parameters */

[[RRM 3-14|EPICS Record Reference Manual]]

= bo - Binary Output =

The normal use for this record type is to store a simple bit (0 or 1) value to be sent to a Digital Output module. It can also be used to write binary values into other records via database or channel access links. This record can implement both latched and momentary binary outputs depending on how the HIGH field is configured.

== Parameter Fields ==

The binary output's fields fall into the following categories:

* scan parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* run-time parameters

=== Scan Parameters ===

The binary output record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The binary output record must specify where its desired output originates. The desired output needs to be in engineering units.

The first field that determines where the desired output originates is the output mode select (OMSL) field, which can have two possible values: <CODE>closed_loop</CODE> or <CODE>supervisory</CODE>. If <CODE>supervisory</CODE> is specified, the value in the VAL field can be set externally via dbPuts at run-time. If <CODE>closed_loop</CODE> is specified, the VAL field's value is obtained from the address specified in the desired output location (DOL) field which can be a database link, a channel access link, or a constant. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

[[RRM 3-14 Concepts#Address Specification|Address Specification]] presents more information on database addresses and links. [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains the effect of database linkage on scanning.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DOL<TD>Desired Output Location (Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices#menuOmsl|menuOmsl]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Convert and Write Parameters ===

These parameters are used to determine where the binary output writes to and how to convert the engineering units to a raw signal. After VAL is set and forced to be either 1 or 0, as the result of either a dbPut or a new value being retrieved from the link in the DOL field, then what happens next depends on which device support routine is used and how the HIGH field is configured.

If the <CODE>Soft Channel</CODE> device support routine is specified, then the device support routine writes the VAL field's value to the address specified in the OUT field. Otherwise, RVAL is the value finally written by the device support routines after being converted.

If VAL is equal to 0, then the record processing routine sets RVAL equal to zero. When VAL is not equal to 0, then RVAL is set equal to the value contained in the MASK field. (MASK is set by the device support routines and is of no concern to the user.) Also when VAL is not 0 and after RVAL is set equal to MASK, the record processing routine checks to see if the HIGH field is greater than 0. If it is, then the routine will process the record again with VAL set to 0 after the number of seconds specified by HIGH. Thus, HIGH implements a momentary output which changes the state of the device back to 0 after ''N'' number of seconds.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>HIGH<TD>Seconds to Hold High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ZNAM<TD>Zero Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONAM<TD>One Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

==== Conversion Parameters ====

The ZNAM field has the string that corresponds to the 0 state, and the ONAM field holds the string that corresponds to the 1 state. These fields, other than being used to tell the operator what each state represents, are used to perform conversions if the value fetched by DOL is a string. If it is, VAL is set to the state correspond to that string. For instance, if the value fetched is the string "Off" and the ZNAM string is "Off," then VAL is set to 0.

After VAL is set, if VAL is equal to 0, then the record processing routine sets RVAL equal to zero. When VAL is not equal to 0, then RVAL is set equal to the value contained in the MASK field. (MASK is set by the device support routines and is of no concern to the user.) Also when VAL is equal to 1 and after RVAL is set equal to MASK, the record processing routine checks to see if the HIGH field is greater than 0. If it is, then the routine process the record again with VAL=0 after the number of seconds specified by HIGH. Thus, HIGH implements a latched output which changes the state of the device or link to 1, then changes it back to 0 after N number of seconds.

<TABLE BORDER="1">
<TD>ZNAM<TD>ASCII string defining state zero<TR>
<TD>ONAM<TD>ASCII string defining state one<TR>
<TD>HIGH<TD>If this value is greater than zero, then whenever VAL is set equal to 1, it is reset to zero after HIGH seconds.
</TABLE>

==== Output Specification ====

The OUT field specifies where the binary output record writes its output. It must specify the address of an I/O card if the record sends its output to hardware, and the DTYP field must contain a the corresponding device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

Otherwise, if the record is configured to use the soft device support modules, then it can be either a database link, a channel access link, or a constant. Be aware that nothing will be written when OUT is a constant. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses. Also, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on output to other records.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. The <CODE>get_enum_str</CODE> record support routine can retrieve the state string corresponding to the VAL's state. So if the value is 1, <CODE>get_enum_str</CODE> will return the string in the ONAM field; and if 0, <CODE>get_enum_str</CODE> will return the ZNAM string.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZNAM<TD>Zero Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONAM<TD>One Name<TD>STRING [20]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

These parameters are used to determine the binary output's alarm condition and to determine the severity of that condition. The possible alarm conditions for binary outputs are the SCAN, READ , INVALID, and state alarms. The user can configure the state alarm conditions using these fields.

The possible values for these fields are <CODE>NO_ALARM</CODE>, <CODE>MINOR</CODE>, and <CODE>MAJOR</CODE>. The ZSV holds the severity for the zero state; OSV for the one state. COSV is used to cause an alarm whenever the state changes between the states (0-1, or 1-0) and its severity is configured as MINOR or MAJOR.

See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZSV<TD>Zero Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>OSV<TD>One Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>COSV<TD>Change of State Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices#menuIvoa|menuIvoa]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value<TD>USHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the binary output. They are not configurable using a configuration tool. They represent the current state of the binary output.

ORAW is used to determine if monitors should be triggered for RVAL at the same time they are triggered for VAL.

MASK is given a value by the device support routines and should not concern the user.

The RBV field is also set by device support. It is the actual read back value obtained from the hardware itself or from the associated device driver. The ORBV field is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM field holds the value of the last occurrence of the change of state alarm. It is used to implement the change of state alarm, and thus only has meaning if COSV is MINOR or MAJOR.

The MLST is used by the <CODE>process</CODE> record support routine to determine if archive and value change monitors are invoked. They are if MLST is not equal to VAL.

The WPDT field is a private field for honoring seconds to hold HIGH.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Hardware Mask<TD>ULONG<TD>No<TD>compute<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Readback Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ORBV<TD>Old Readback Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed Value<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Monitored Value<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RPVT<TD>Record Private<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD>No<TR>
<TD>WDPT<TD>Watchdog Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the binary output in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created .

This routine next checks to see that device support is available. The routine next checks to see if the device support write routine is defined.

If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then VAL is initialized to 1 if its value is nonzero or initialized to 0 if DOL is zero, and UDF is set to FALSE.

If device support includes init_record, it is called. VAL is set using RVAL, and UDF is set to FALSE.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_enum_str ====

Retrieves ASCII string corresponding to VAL.

==== get_enum_strs ====

Retrieves ASCII strings for ZNAM and ONAM.

==== put_enum_str ====

Checks if string matches ZNAM or ONAM, and if it does, sets VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE
#* if DOL is DB_LINK and OMSL is CLOSED_LOOP
#** get value from DOL
#** check for link alarm
#** force VAL to be 0 or 1
#** if MASK is defined
#*** if VAL is 0 set RVAL = 0
#** else set RVAL = MASK
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on how INVALID alarms affect output.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check WAIT. If VAL is 1 and WAIT is greater than 0, process again with a VAL=0 after WAIT seconds.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL and for RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each binary output record must have an associated set of device support routines. The primary responsibility of the device support routines is to write a new value whenever write_bo is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value Field<TD>This field is only of interest to device support routines that do not use MASK and RVAL.<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>RVAL<TD>Raw Data Value<TD>If MASK is defined then record support sets RVAL=(0,MASK) if VAL is (0, not zero).<TR>
<TD>MASK<TD>Hardware mask.<TD>The device support module must set this field. Not that if VAL is 1, then record processing sets RVAL = MASK.<TR>
<TD>RBV<TD>Read Back Value<TD>This is the actual read back value obtained from the hardware itself or from the associated device driver. It is the responsibility of the device support routine to give this field a value.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. It should determine MASK if it is needed.

* 0: Success. RVAL modified (VAL will be set accordingly)
* 2: Success. VAL modified
* other: Error.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_bo ====

write_bo(precord)

This routine must output an new value. It returns the following values:

* 0: Success.
* other: Error.

=== Device Support For Soft Records ===

Two soft device support modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided for output records not related to actual hardware devices. The OUT link type must be either a CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

This module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record. init_record always returns a value of 2, which means that no conversion will ever be attempted. write_bo calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]] for details.

==== Raw Soft Channel ====

This module is like the previous except that it writes the current value of RVAL.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14

2014-12-03T20:52:11Z

TimMooney: /* Record Types Not in Base */

<H2 style="color:#C00000">Help Needed!</H2>

This documentation has been revised since the older 3-13 version, but the software has been updated significantly since the docs were written so there may still be a number of inaccuracies here. The [[RRM 3-14 Editing Tasks|Editing Tasks]] page gives some ideas on what else might need doing.

== EPICS 3-14 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson and Kazimierz Gofron

* [[RRM 3-14 Copyright|Copyright]]
* [[RRM 3-14 Preface|Preface]]

* [[RRM 3-14 Concepts|Database Concepts]]
* [[RRM 3-14 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-14 Common|Fields Common to Many Record Types]]

* [[RRM 3-14 Array Analog Input|aai - Array Analog Input]]
* [[RRM 3-14 Array Analog Output|aao - Array Analog Output]]
* [[RRM 3-14 Analog Input|ai - Analog Input]]
* [[RRM 3-14 Analog Output|ao - Analog Output]]
* [[RRM 3-14 Array Subroutine|aSub - Array Subroutine]]
* [[RRM 3-14 Binary Input|bi - Binary Input]]
* [[RRM 3-14 Binary Output|bo - Binary Output]]
* [[RRM 3-14 Calculation|calc - Calculation]]
* [[RRM 3-14 Calcout|calcout - Calculation Output]]
* [[RRM 3-14 Compression|compress - Compression]]
* [[RRM 3-14 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-14 Event|event - Event]]
* [[RRM 3-14 Fanout|fanout - Fanout]]
* [[RRM 3-14 Histogram|histogram - Histogram]]
* [[RRM 3-14 Long Input|longin - Long Input]]
* [[RRM 3-14 Long Output|longout - Long Output]]
* [[RRM 3-14 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-14 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-14 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-14 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-14 Permissive|permissive - Permissive]]
* [[RRM 3-14 Select|sel - Select]]
* [[RRM 3-14 Sequence|seq - Sequence]]
* [[RRM 3-14 State|state - State]]
* [[RRM 3-14 String Input|stringin - String Input]]
* [[RRM 3-14 String Output|stringout - String Output]]
* [[RRM 3-14 SubArray|subArray - Sub-Array]]
* [[RRM 3-14 Subroutine|sub - Subroutine]]
* [[RRM 3-14 Waveform|waveform - Waveform]]

* [[RRM 3-14 Menu Choices|Appendix: Menu Choices]]

----

=== Record Types Not in Base ===

* [[RRM 3-14 Archive|archive - Archive]]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-24/asynRecord.html asyn]
* [[RRM 3-14 CPID Control|cpid - CPID Control]]
* [[RRM 3-14 PID Control|pid - PID Control]]
* [[RRM 3-14 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-14 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-14 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-14 Scan|scan - Scan]]
* [[RRM 3-14 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-14 Timer|timer - Timer]]
* [[RRM 3-14 Wait|wait - Wait]]
* synApps records
** [http://www.aps.anl.gov/bcda/synApps/alive/aliveRecord.html alive]
** [http://www.aps.anl.gov/bcda/synApps/calc/aCalcoutRecord.html acalcout] Array Calculation Output
** [http://www.aps.anl.gov/bcda/synApps/sscan/busyRecord.html busy] Signal put_callback() completion
** [http://cars9.uchicago.edu/software/epics/camacRecord.html camac] Generic CAMAC Record
** [http://www.aps.anl.gov/bcda/synApps/vac/README.txt digitel] Vacuum controller
** [http://cars9.uchicago.edu/software/epics/dxpRecord.html dxp]
** [http://www.aps.anl.gov/bcda/synApps/std/epidRecord.html epid] Enhanced PID
**[http://cars9.uchicago.edu/software/epics/mcaRecord.html mca] Multichannel analyzer, multichannel scaler
** [http://www.aps.anl.gov/bcda/synApps/motor/R6-8/motorRecord.html motor] Stepper and servo motor
** [http://www.aps.anl.gov/bcda/synApps/calc/sCalcoutRecord.html scalcout] String Calculation Output
** [http://www.aps.anl.gov/bcda/synApps/std/scalerRecord.html scaler] Multibank counter
** [http://www.aps.anl.gov/bcda/synApps/sscan/sscanRecord.html sscan] Set conditions, trigger detectors, record data, write data files
** [http://www.aps.anl.gov/bcda/synApps/sscan/scanparmRecord.html scanparm] One-button scan
** [http://www.aps.anl.gov/bcda/synApps/std/sseqRecord.html sseq] String sequence
** [http://www.aps.anl.gov/bcda/synApps/calc/swaitRecord.html swait] Calcout variant
** [http://www.aps.anl.gov/bcda/synApps/optics/tableRecord.html table] Optical table
** [http://www.aps.anl.gov/bcda/synApps/calc/transformRecord.html transform] Calc variant
** [http://cars9.uchicago.edu/software/epics/vmeRecord.html vme] Generic VME access
** [http://www.aps.anl.gov/bcda/synApps/vac/README.txt vs] Vacuum sensor

RRM 3-14 Array Subroutine

2013-03-12T22:54:45Z

TimMooney: EFLG actually defaults to "ON CHANGE", not to "ALWAYS"

[[RRM 3-14|EPICS Record Reference Manual]]

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array or scalar
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing, which is a status value that controls whether the output links are used or not.

== Field Summary ==
<table border="1">
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ON CHANGE<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border="1">
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined process routine, which must be zero for the output links OUTA...OUTU to be processed.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>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 everytime 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.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be any of the following:
"STRING","CHAR","UCHAR","SHORT","USHORT","LONG","ULONG","FLOAT","DOUBLE, "ENUM".

<tr><td>NOA..., NOU<td>Max elements in A,.. Max elements in U
<td>The number of elements of storage allocated for each input field. Default is 1 (scalar value). An array is specified by setting this field to greater than 1.

<tr><td>NEA..., NEU<td>Number of elements in A,.. Number of elements in U
<td>The current number of elements stored in each input field. Field contains an array if this field is greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Max elements in VALA,.. Max elements in VALU
<td>The number of elements of storage allocated for each output field. Default is 1 (scalar value). An array is specified by setting this field to greater than 1.

<tr><td>NEVA,..., NEVU<td>Number of elements in VALA,.. Number of elements in VALU
<td>The current number of elements stored in each output field. Field contains an array if this field is greater than 1.

</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* field values.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* If VAL is zero, write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM (again).
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* If VAL is zero, write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. During development when trying several versions of the routine, it is not necessary to reboot the IOC and reload the database. A new routine can be loaded with the vxWorks ld command, and Channel Access or the dbpf command used to put the name of the routine into the record's SNAM field. The record will look up the symbol name in the symbol table whenever the SNAM field gets modified. The same routine name can even be used as the vxWorks symbol lookup returns the latest version of the code to have been loaded.

RRM 3-14 Array Subroutine

2010-12-03T18:15:06Z

TimMooney: /* Field Descriptions */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>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 everytime 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.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be any of the following:
"STRING","CHAR","UCHAR","SHORT","USHORT","LONG","ULONG","FLOAT","DOUBLE, "ENUM".

<tr><td>NOA..., NOU<td>Max elements in A,.. Max elements in U
<td>The number of elements of storage allocated for each input field. Default is 1 (scalar value). An array is specified by setting this field to greater than 1.

<tr><td>NEA..., NEU<td>Number of elements in A,.. Number of elements in U
<td>The current number of elements stored in each input field. Field contains an array if this field is greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Max elements in VALA,.. Max elements in VALU
<td>The number of elements of storage allocated for each output field. Default is 1 (scalar value). An array is specified by setting this field to greater than 1.

<tr><td>NEVA,..., NEVU<td>Number of elements in VALA,.. Number of elements in VALU
<td>The current number of elements stored in each output field. Field contains an array if this field is greater than 1.

</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* field values.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==
The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU). There is no association between A and VALA, etc. 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').

=== 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)
}

Note that the subroutine must always treat 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 include something like the following along with your subroutine code. This tells EPICS how to handle references to your subroutine:

#include <registryFunction.h>
#include <epicsExport.h>

static registryFunctionRef my_asub_Ref[] = {
{"my_asub_routine", (REGISTRYFUNCTION) my_asub_routine}
};

static void my_asub_Registrar(void) {
registryFunctionRefAdd(my_asub_Ref, NELEMENTS(my_asub_Ref));
}

epicsExportRegistrar(my_asub_Registrar);

=== Required database-definition code ===

The .dbd file loaded into the ioc must contain something like the following, so EPICS can find the subroutine:

registrar(my_asub_Registrar)

=== Device support, writing to hardware ===

Note, by the way, that the aSub record does not talk to device support. 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14

2009-09-12T06:13:13Z

TimMooney: /* EPICS 3-14 Record Reference Manual */

<H2 style="color:#C00000">Help Needed!</H2>

This documentation is a revision of 3-13 documentation, as the software has been updated significantly since the docs were written. The [[RRM 3-14 Editing Tasks|Editing Tasks]] page gives some ideas on what needs doing to bring it up to the R3.14.9 implementation.

== EPICS 3-14 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson and Kazimierz Gofron

* [[RRM 3-14 Copyright|Copyright]]
* [[RRM 3-14 Preface|Preface]]

* [[RRM 3-14 Concepts|Database Concepts]]
* [[RRM 3-14 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-14 Common|Fields Common to Many Record Types]]

* [[RRM 3-14 Analog Input|ai - Analog Input]]
* [[RRM 3-14 Analog Output|ao - Analog Output]]
* [[RRM 3-14 Array Subroutine|aSub - Array Subroutine]]
* [[RRM 3-14 Binary Input|bi - Binary Input]]
* [[RRM 3-14 Binary Output|bo - Binary Output]]
* [[RRM 3-14 Calculation|calc - Calculation]]
* [[RRM 3-14 Calcout|calcout - Calculation Output]]
* [[RRM 3-14 Compression|compress - Compression]]
* [[RRM 3-14 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-14 Event|event - Event]]
* [[RRM 3-14 Fanout|fanout - Fanout]]
* [[RRM 3-14 Histogram|histogram - Histogram]]
* [[RRM 3-14 Long Input|longin - Long Input]]
* [[RRM 3-14 Long Output|longout - Long Output]]
* [[RRM 3-14 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-14 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-14 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-14 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-14 Permissive|permissive - Permissive]]
* [[RRM 3-14 Select|sel - Select]]
* [[RRM 3-14 Sequence|seq - Sequence]]
* [[RRM 3-14 State|state - State]]
* [[RRM 3-14 String Input|stringin - String Input]]
* [[RRM 3-14 String Output|stringout - String Output]]
* [[RRM 3-14 SubArray|subArray - Sub-Array]]
* [[RRM 3-14 Subroutine|sub - Subroutine]]
* [[RRM 3-14 Waveform|waveform - Waveform]]

* [[RRM 3-14 Menu Choices|Appendix: Menu Choices]]

----

=== Other Record Types Not in Base ===

* [[RRM 3-14 Archive|archive - Archive]]
* [[RRM 3-14 CPID Control|cpid - CPID Control]]
* [[RRM 3-14 PID Control|pid - PID Control]]
* [[RRM 3-14 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-14 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-14 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-14 Scan|scan - Scan]]
* [[RRM 3-14 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-14 Timer|timer - Timer]]
* [[RRM 3-14 Wait|wait - Wait]]

RRM 3-14 Array Subroutine

2009-09-10T21:47:31Z

TimMooney: /* Device support, writing to hardware */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* fields.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==
The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU). There is no association between A and VALA, etc. 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').

=== 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)
}

Note that the subroutine must always treat 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 include something like the following along with your subroutine code. This tells EPICS how to handle references to your subroutine:

#include <registryFunction.h>
#include <epicsExport.h>

static registryFunctionRef my_asub_Ref[] = {
{"my_asub_routine", (REGISTRYFUNCTION) my_asub_routine}
};

static void my_asub_Registrar(void) {
registryFunctionRefAdd(my_asub_Ref, NELEMENTS(my_asub_Ref));
}

epicsExportRegistrar(my_asub_Registrar);

=== Required database-definition code ===

The .dbd file loaded into the ioc must contain something like the following, so EPICS can find the subroutine:

registrar(my_asub_Registrar)

=== Device support, writing to hardware ===

Note, by the way, that the aSub record does not talk to device support. 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T21:40:59Z

TimMooney: /* Field Summary */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td><td><td><td><td><td><td><td>
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* fields.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==
The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU). There is no association between A and VALA, etc. 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').

=== 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)
}

Note that the subroutine must always treat 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 include something like the following along with your subroutine code. This tells EPICS how to handle references to your subroutine:

#include <registryFunction.h>
#include <epicsExport.h>

static registryFunctionRef my_asub_Ref[] = {
{"my_asub_routine", (REGISTRYFUNCTION) my_asub_routine}
};

static void my_asub_Registrar(void) {
registryFunctionRefAdd(my_asub_Ref, NELEMENTS(my_asub_Ref));
}

epicsExportRegistrar(my_asub_Registrar);

=== Required database-definition code ===

The .dbd file loaded into the ioc must contain something like the following, so EPICS can find the subroutine:

registrar(my_asub_Registrar)

=== Device support, writing to hardware ===

Note, by the way, that he aSub record does not talk to device support. 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T21:36:55Z

TimMooney: /* Dynamically Changing the User Routine called during Record Processing */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* fields.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==
The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU). There is no association between A and VALA, etc. 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').

=== 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)
}

Note that the subroutine must always treat 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 include something like the following along with your subroutine code. This tells EPICS how to handle references to your subroutine:

#include <registryFunction.h>
#include <epicsExport.h>

static registryFunctionRef my_asub_Ref[] = {
{"my_asub_routine", (REGISTRYFUNCTION) my_asub_routine}
};

static void my_asub_Registrar(void) {
registryFunctionRefAdd(my_asub_Ref, NELEMENTS(my_asub_Ref));
}

epicsExportRegistrar(my_asub_Registrar);

=== Required database-definition code ===

The .dbd file loaded into the ioc must contain something like the following, so EPICS can find the subroutine:

registrar(my_asub_Registrar)

=== Device support, writing to hardware ===

Note, by the way, that he aSub record does not talk to device support. 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T21:36:18Z

TimMooney: /* Required database-definition code */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* fields.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==
The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU). There is no association between A and VALA, etc. 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').

=== 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)
}

Note that the subroutine must always treat 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 include something like the following along with your subroutine code. This tells EPICS how to handle references to your subroutine:

#include <registryFunction.h>
#include <epicsExport.h>

static registryFunctionRef my_asub_Ref[] = {
{"my_asub_routine", (REGISTRYFUNCTION) my_asub_routine}
};

static void my_asub_Registrar(void) {
registryFunctionRefAdd(my_asub_Ref, NELEMENTS(my_asub_Ref));
}

epicsExportRegistrar(my_asub_Registrar);

=== Required database-definition code ===

The .dbd file loaded into the ioc must contain something like the following, so EPICS can find the subroutine:

registrar(my_asub_Registrar)

=== Device support, writing to hardware ===

Note, by the way, that he aSub record does not talk to device support. 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T21:35:48Z

TimMooney: /* Required export code */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* fields.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==
The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU). There is no association between A and VALA, etc. 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').

=== 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)
}

Note that the subroutine must always treat 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 include something like the following along with your subroutine code. This tells EPICS how to handle references to your subroutine:

#include <registryFunction.h>
#include <epicsExport.h>

static registryFunctionRef my_asub_Ref[] = {
{"my_asub_routine", (REGISTRYFUNCTION) my_asub_routine}
};

static void my_asub_Registrar(void) {
registryFunctionRefAdd(my_asub_Ref, NELEMENTS(my_asub_Ref));
}

epicsExportRegistrar(my_asub_Registrar);

=== Required database-definition code ===

The .dbd file loaded into the ioc must contain the following, so EPICS can find the subroutine:

registrar(my_asub_Registrar)

=== Device support, writing to hardware ===

Note, by the way, that he aSub record does not talk to device support. 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T21:34:04Z

TimMooney:

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* fields.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==
The aSub record has input-value fields (A-U) and output-value fields (VALA-VALU). There is no association between A and VALA, etc. 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').

=== 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)
}

Note that the subroutine must always treat 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 include something like the following in the file that contains your subroutine code. This tells EPICS how to handle references to your subroutine:

#include <registryFunction.h>
#include <epicsExport.h>

static registryFunctionRef my_asub_Ref[] = {
{"my_asub_routine", (REGISTRYFUNCTION) my_asub_routine}
};

static void my_asub_Registrar(void) {
registryFunctionRefAdd(my_asub_Ref, NELEMENTS(my_asub_Ref));
}

epicsExportRegistrar(my_asub_Registrar);

=== Required database-definition code ===

The .dbd file loaded into the ioc must contain the following, so EPICS can find the subroutine:

registrar(my_asub_Registrar)

=== Device support, writing to hardware ===

Note, by the way, that he aSub record does not talk to device support. 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T20:19:26Z

TimMooney: /* init_record */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. Initialize fields NE* to the values of the associated NO* fields.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
* If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

== 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T20:13:57Z

TimMooney: /* Field Summary */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>MENU(IGNORE, READ)<td>Yes<td>IGNORE<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>MENU(NEVER, ON CHANGE, ALWAYS)<td>Yes<td>ALWAYS<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>MENU<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>MENU<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

== 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T20:09:29Z

TimMooney: /* Field Summary */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec Proc Monitor<th>PP
<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

== 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T19:46:12Z

TimMooney: /* Field Descriptions */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec<th>Proc<th>Monitor<th>PP

<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No

<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No

</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>Num. elements in field<td>Num. elements in field

<tr><td>NEVA,..., NEVU<td>Num. elements in field<td>Num. elements in field
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

== 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T19:39:46Z

TimMooney: /* process */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec<th>Proc<th>Monitor<th>PP

<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No

<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No

</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>

<tr><td>NEVA,..., NEVU<td>
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* If PACT is FALSE, perform normal processing
* If PACT is TRUE, perform asynchronous-completion processing

Normal processing:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Set PACT to FALSE
* If all input-link fetches succeeded, call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* If the SNAM routine set PACT to TRUE, then return. In this case, we presume the routine has arranged that process will be called at some later time for asynchronous completion.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

Asynchronous-completion processing:

* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Set PACT to TRUE.
* Write the output values using the output links.
* Get the time of processing and put it into the timestamp field.
* If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

== 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T19:07:32Z

TimMooney: /* Use of the aSub Record */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec<th>Proc<th>Monitor<th>PP

<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No

<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No

</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>

<tr><td>NEVA,..., NEVU<td>
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Place the output values on the output links.
* Get the time of processing and put it into the timestamp field.
* If the subroutine address has changed, post a change-of-value event and a log event for the SADR field. If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

== 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:

* The LFLG field can be set to READ so that the name of the routine is read from the SUBL link. Thus, whatever is feeding this link can change the name of the routine before the aSub record is processed. In this case, the record looks in the symbol table for the symbol name whenever the name of routine fetched from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during record processing is that specified in the SNAM field. Under these conditions, the SNAM field can be changed by a Channel Access write to that field. Thus, during development work, when it is often required to run a modified version of the routine, it will no longer be a requirement to reboot the IOC and reload the database. A new routine will be called during record processing if the routine is loaded with the vxWorks ld command, and cau is used to put the name of the routine into the record's SNAM field. After the SNAM field has been changed, the record automatically looks up the symbol name in the symbol table. Note that, if the same routine name is used, this is not a problem. The record finds the latest version of the code which has been loaded. Obviously, one needs to take care of the amount of memory used in the system, if the vxWorks unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T19:05:11Z

TimMooney: /* special */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec<th>Proc<th>Monitor<th>PP

<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No

<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No

</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>

<tr><td>NEVA,..., NEVU<td>
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Place the output values on the output links.
* Get the time of processing and put it into the timestamp field.
* If the subroutine address has changed, post a change-of-value event and a log event for the SADR field. If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of the routine specified by SNAM. Set the SADR field equal to the subroutine address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

1.6 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:

* The LFLG field can be set to READ so that the name of the routine is read from
the SUBL link. Thus, whatever is feeding this link can change the name of the
routine before the aSub record is processed. In this case, the record looks
in the symbol table for the symbol name whenever the name of routine fetched
from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during
record processing is that specified in the SNAM field. Under these conditions,
the SNAM field can be changed by a Channel Access write to that field. Thus,
during development work, when it is often required to run a modified version of
the routine, it will no longer be a requirement to reboot the IOC and reload
the database. A new routine will be called during record processing if the
routine is loaded with the vxWorks ld command, and cau is used to put the name
of the routine into the record's SNAM field. After the SNAM field has been
changed, the record automatically looks up the symbol name in the symbol table.
Note that, if the same routine name is used, this is not a problem. The record
finds the latest version of the code which has been loaded. Obviously, one
needs to take care of the amount of memory used in the system, if the vxWorks
unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T19:04:52Z

TimMooney: /* process */

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec<th>Proc<th>Monitor<th>PP

<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No

<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No

</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>

<tr><td>NEVA,..., NEVU<td>
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link. If the name is not NULL and it is not the same as the previous subroutine name, lookup the subroutine address. Set the old subroutine name, ONAM, equal to the current name, SNAM.
* Fetch the values from the input links.
* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Place the output values on the output links.
* Get the time of processing and put it into the timestamp field.
* If the subroutine address has changed, post a change-of-value event and a log event for the SADR field. If VAL has changed, post a change-of value and log event for this field. If EFLG is set to ALWAYS, post change-of-value and log events for every output field. If EFLG is set to ON CHANGE, post change-of-value and log events for every output field which has changed. In the case of an array, an event will be posted if any single element of the array has changed. If EFLG is set to NEVER, no change-of-value or log events are posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of
the routine specified by SNAM. Set the SADR field equal to the subroutine
address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

1.6 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:

* The LFLG field can be set to READ so that the name of the routine is read from
the SUBL link. Thus, whatever is feeding this link can change the name of the
routine before the aSub record is processed. In this case, the record looks
in the symbol table for the symbol name whenever the name of routine fetched
from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during
record processing is that specified in the SNAM field. Under these conditions,
the SNAM field can be changed by a Channel Access write to that field. Thus,
during development work, when it is often required to run a modified version of
the routine, it will no longer be a requirement to reboot the IOC and reload
the database. A new routine will be called during record processing if the
routine is loaded with the vxWorks ld command, and cau is used to put the name
of the routine into the record's SNAM field. After the SNAM field has been
changed, the record automatically looks up the symbol name in the symbol table.
Note that, if the same routine name is used, this is not a problem. The record
finds the latest version of the code which has been loaded. Obviously, one
needs to take care of the amount of memory used in the system, if the vxWorks
unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T19:03:41Z

TimMooney: formatting

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec<th>Proc<th>Monitor<th>PP

<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No

<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No

</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>

<tr><td>NEVA,..., NEVU<td>
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If they have been defined, call them to get the size of the structure which is to passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user function has been defined, calloc the space required by the multiple of the number of elements and size returned from the user function. For the output fields, also calloc space to hold the previous value of a field. This is required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link.
If the name is not NULL and it is not the same as the previous subroutine name,
lookup the subroutine address. Set the old subroutine name, ONAM, equal to the
current name, SNAM.
* Fetch the values from the input links.
* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Place the output values on the output links.
* Get the time of processing and put it into the timestamp field.
* If the subroutine address has changed, post a change-of-value event and a log
event for the SADR field. If VAL has changed, post a change-of value and log
event for this field. If EFLG is set to ALWAYS, post change-of-value and log
events for every output field. If EFLG is set to ON CHANGE, post
change-of-value and log events for every output field which has changed. In the
case of an array, an event will be posted if any single element of the array
has changed. If EFLG is set to NEVER, no change-of-value or log events are
posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of
the routine specified by SNAM. Set the SADR field equal to the subroutine
address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

1.6 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:

* The LFLG field can be set to READ so that the name of the routine is read from
the SUBL link. Thus, whatever is feeding this link can change the name of the
routine before the aSub record is processed. In this case, the record looks
in the symbol table for the symbol name whenever the name of routine fetched
from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during
record processing is that specified in the SNAM field. Under these conditions,
the SNAM field can be changed by a Channel Access write to that field. Thus,
during development work, when it is often required to run a modified version of
the routine, it will no longer be a requirement to reboot the IOC and reload
the database. A new routine will be called during record processing if the
routine is loaded with the vxWorks ld command, and cau is used to put the name
of the routine into the record's SNAM field. After the SNAM field has been
changed, the record automatically looks up the symbol name in the symbol table.
Note that, if the same routine name is used, this is not a problem. The record
finds the latest version of the code which has been loaded. Obviously, one
needs to take care of the amount of memory used in the system, if the vxWorks
unld command is never used.

RRM 3-14 Array Subroutine

2009-09-10T18:56:02Z

TimMooney: First try

= aSub - Array Subroutine =

The aSub record is a variant of the 'sub' (subroutine) record with array-valued
input and output fields, whose types are user specifiable at database-configure time, and associated input and output links.

The routine to be called at process time can be changed dynamically after the database has been loaded.
The name of the routine can either be fetched in over a link from another record or written directly into
the SNAM field.

The user can configure the record to decide when events will be posted for the output fields. This can be:
Never, Always or just when any element of an array changes value.

The VAL field holds the value returned from the routine called during record processing.

== Field Summary ==
<table border>
<th>Field<th>Type<th>DCT<th>Initial<th>Access<th>Modify<th>Rec<th>Proc<th>Monitor<th>PP

<tr><td>VAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>Yes<td>No
<tr><td>OVAL<td>LONG<td>No<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>SADR<td>LONG<td>No<td>0<td>Yes<td>No<td>Yes<td>No
<tr><td>OSAD<td>LONG<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>LFLG<td>RECCHOICE<td>Yes<td>Ignore<td>Yes<td>Yes<td>No<td>No
<tr><td>EFLG<td>RECCHOICE<td>Yes<td>Always<td>Yes<td>Yes<td>No<td>No
<tr><td>SUBL<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>SNAM<td>STRING<td>Yes<td>Null<td>Yes<td>Yes<td>No<td>No
<tr><td>ONAM<td>STRING<td>Yes<td>Null<td>Yes<td>No<td>No<td>No
<tr><td>STYP<td>SHORT<td>No<td>0<td>Yes<td>No<td>No<td>No
<tr><td>BRSV<td>GBLCHOICE<td>Yes<td>0<td>Yes<td>Yes<td>No<td>Yes
<tr><td>PREC<td>SHORT<td>Yes<td>0<td>Yes<td>Yes<td>No<td>No
<tr><td>INPA<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>INPB<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>INPU<td>INLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>A<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>B<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>U<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>No<td>No
<tr><td>FTA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>OUTA<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>OUTB<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OUTU<td>OUTLINK<td>Yes<td>0<td>No<td>No<td>NA<td>No
<tr><td>VALA<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>VALB<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>VALU<td>NOACCESS<td>No<td>0<td>No<td>Yes<td>Yes<td>No
<tr><td>OVLA<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>OVLB<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>OVLU<td>NOACCESS<td>No<td>0<td>No<td>No<td>No<td>No
<tr><td>FTVA<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>FTVB<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>FTVU<td>GBLCHOICE<td>Yes<td>DOUBLE<td>Yes<td>No<td>No<td>No
<tr><td>NOVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NOVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NOVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>TOVA<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>TOVB<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>TOVU<td>ULONG<td>Yes<td>0<td>Yes<td>No<td>No<td>No

<tr><td>NEA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVA<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>NEVB<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No
<tr><td>...<td>...<td>...<td>...<td>...<td>...<td>...<td>...
<tr><td>NEVU<td>ULONG<td>Yes<td>1<td>Yes<td>No<td>No<td>No

</table>

== Field Descriptions ==

<table border>
<th>Name<th>Summary<th>Description

<tr><td>VAL<td>Value returned from process routine<td>This field holds the value returned from the user defined
process routine.

<tr><td>OVAL<td>Old VAL<td>Previous VAL, used to decide when to post events.

<tr><td>SADR<td>Subroutine Address <td>The address of the routine called at process time.

<tr><td>OSAD<td>Old SADR<td>Previous SADR, used to decide when to post events.

<tr><td>LFLG<td>Link Flag<td>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.

<tr><td>EFLG<td>Event Flag<td>Tells the record when to post events on the output fields
VALA,...,VALU. If the value is NEVER, events are never
posted. If the value is ALWAYS, events are posted everytime
the record processes. If the value is ON CHANGE, events are
posted when any element of an array changes value.
Archiving and Value Change events are posted in each case.

<tr><td>SUBL<td>Subroutine Link<td>Where to get the subroutine name from.

<tr><td>INAM<td>Initialisation Routine <td>This is the name of the initialisation routine to be called once,
at iocInit.

<tr><td>SNAM<td>Process Routine<td>This is the name of the routine to be called when the record
processes. Note, this can be overwritten by the SUBL link, if
LFLG is set to READ.

<tr><td>ONAM<td>Process Routine<td>Old process subroutine name.

<tr><td>STYP<td>Subroutine Symbol Type <td>Filled in by record processing.

<tr><td>BRSV<td>Severity for a subroutine return value less than 0. <td>Specifies the Alarm severity.

<tr><td>PREC<td>Display Precision <td>Specifies the number of decimal places with which to display
the values of the fields VALA,...,VALU.

<tr><td>INPA,..., INPU<td>Input Link A,..., Input Link U
<td>The input links from where the values of A,...,U are fetched
during record processing.

<tr><td>A,...,U<td>Input Fields
<td>The input fields which hold the scalar values or arrays fetched
in across the input links INPA,...,INPU.

<tr><td>FTA,..., FTU<td>Field Type of A Field Type of U
<td>Field types of the input values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>NOA..., NOU<td>Number of elements in A,.. Number of elements in U
<td>The number of elements in each input field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>OUTA,..., OUTU<td>Output Link A,.. Output Link U
<td>The output links on which the scalars or arrays located at
VALA,...,VALU are placed during record processing.

<tr><td>VALA,.., VALU<td>Output Fields
<td>The output fields which hold the scalar values or arrays
pushed out across the output links OUTA,...,OUTU.

<tr><td>FTVA,..., FTVU<td>Field Type of VALA Field Type of VALU
<td>Field types of the output values. These can be CHAR,
STRING, DOUBLE, LONG, etc.

<tr><td>OVLA,.., OVLU<td>Previous Outputs
<td>The previous values of the outputs. These are used to decide
when to post events if EFLG is set to ON CHANGE.

<tr><td>NOVA,..., NOVU<td>Number of elements in VALA Number of elements in VALU
<td>The number of elements in each output field. Default is 1
(scalar value). An array is specified by setting this field to
greater than 1.

<tr><td>TOVA,..., TOVU<td>Total Number of bytes in VALA Total Number of bytes in VALU
<td>The total number of bytes in each output field. These are used
internally by record processing and do not concern the user.

<tr><td>NEA,..., NEU<td>

<tr><td>NEVA,..., NEVU<td>
</table>

== Record Support Routines ==
=== init_record ===

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

* Look for any user functions defined in the fields UFA-UFU and UFVA-UFVU. If
they have been defined, call them to get the size of the structure which is to
passed across the link. If they are not defined, no routine is called.
* Calloc sufficient space to hold the number of input scalars and/or arrays
defined by the settings of the fields FTA-FTU and NOA-NOU. If a user function
has been defined, calloc the space required by the multiple of the number of
elements and size returned from the user function.
* Calloc sufficient space to hold the number of output scalars and/or arrays
defined by the settings of the fields FTVA-FTVU and NOVA-NOVU. If a user
function has been defined, calloc the space required by the multiple of the
number of elements and size returned from the user function. For the output
fields, also calloc space to hold the previous value of a field. This is
required when the decision is made on whether or not to post events.

On the second call, it does the following:

* Initializes SUBL if it is a constant link.
* Initializes each constant input link.
* If the field INAM is set, look-up the address of the routine and call it.
*If the field LFLG is set to IGNORE and SNAM is defined, look-up the address of
the process routine.

=== process ===
This routine implements the following algorithm:

* Set PACT to TRUE.
* If the field LFLG is set to READ, get the subroutine name from the SUBL link.
If the name is not NULL and it is not the same as the previous subroutine name,
lookup the subroutine address. Set the old subroutine name, ONAM, equal to the
current name, SNAM.
* Fetch the values from the input links.
* Call the routine specified by SNAM.
* Set VAL equal to the return value from the routine specified by SNAM.
* Place the output values on the output links.
* Get the time of processing and put it into the timestamp field.
* If the subroutine address has changed, post a change-of-value event and a log
event for the SADR field. If VAL has changed, post a change-of value and log
event for this field. If EFLG is set to ALWAYS, post change-of-value and log
events for every output field. If EFLG is set to ON CHANGE, post
change-of-value and log events for every output field which has changed. In the
case of an array, an event will be posted if any single element of the array
has changed. If EFLG is set to NEVER, no change-of-value or log events are
posted for the output fields.
* Process the record on the end of the forward link, if one exists.
* Set PACT to FALSE.

=== get_value ===
Fills in the values of struct valueDes so that they refer to VAL.

=== get_precision ===

Sets the display precision to the value of PREC for any of the output fields
VALA,..., VALU. This routine could be called for any of these fields.

=== cvt_dbaddr ===

The purpose of this routine is to fill in the struct dbAddr for the field of the
record for which it has been called. Typically, the number of elements in the
field, the field type and the size of the field will be set in this routine.
For arrays, this record support routine is essential.

=== get_array_info ===

This routine returns the current number of elements and the offset of the first
value for an array. For this record, the offset field is always 0.

=== put_array_info ===

This routine is called after new values have been placed in an array.

=== special ===

This routine is called whenever the SNAM field changes. It is called twice, once
before the change and once after. On the first call, the routine simply
returns. On the second call, after SNAM has changed, it implements the
following algorithm:

* If LFLG is set to IGNORE and SNAM is not NULL, then look-up the address of
the routine specified by SNAM. Set the SADR field equal to the subroutine
address.
* Post change-of-value and log events for the SADR field, if this has changed.

== Use of the aSub Record ==

Two aSub records can be used to transfer data between one another. These
records can be located in the same IOC or in separate IOC's. The data can be a
scalar of any type, an array, a user defined structure or an array of user
defined structures.

Let us name the aSub record which is sending data, record A, and the aSub
record which is receiving the data, record B. There are some fields which must
be set-up correctly in each record before the data transfer can occur without
error. The output field types and the number of elements in the output fields
of record A must match the input field types and number of elements in the
input fields of record B. Thus, combining the two records is rather like a
jigsaw. Let us take an example.

If 5 doubles are to be passed from the VALA field of record A to the A field of
record B, then the following settings are necessary:

Record A should have: FTVA = DOUBLE, NOVA = 5.
Record B should have: FTA = DOUBLE, NOA = 5.

1.6 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:

* The LFLG field can be set to READ so that the name of the routine is read from
the SUBL link. Thus, whatever is feeding this link can change the name of the
routine before the aSub record is processed. In this case, the record looks
in the symbol table for the symbol name whenever the name of routine fetched
from the link changes.
* The LFLG field can be set to IGNORE. In this case, the routine called during
record processing is that specified in the SNAM field. Under these conditions,
the SNAM field can be changed by a Channel Access write to that field. Thus,
during development work, when it is often required to run a modified version of
the routine, it will no longer be a requirement to reboot the IOC and reload
the database. A new routine will be called during record processing if the
routine is loaded with the vxWorks ld command, and cau is used to put the name
of the routine into the record's SNAM field. After the SNAM field has been
changed, the record automatically looks up the symbol name in the symbol table.
Note that, if the same routine name is used, this is not a problem. The record
finds the latest version of the code which has been loaded. Obviously, one
needs to take care of the amount of memory used in the system, if the vxWorks
unld command is never used.

RRM 3-14

2009-09-10T18:01:59Z

TimMooney: /* EPICS 3-14 Record Reference Manual */

<H2 style="color:#C00000">Help Needed!</H2>

This documentation is a revision of 3-13 documentation, as the software has been updated significantly since the docs were written. The [[RRM 3-14 Editing Tasks|Editing Tasks]] page gives some ideas on what needs doing to bring it up to the R3.14.9 implementation.

== EPICS 3-14 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson and Kazimierz Gofron

* [[RRM 3-14 Copyright|Copyright]]
* [[RRM 3-14 Preface|Preface]]

* [[RRM 3-14 Concepts|Database Concepts]]
* [[RRM 3-14 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-14 Common|Fields Common to Many Record Types]]

* [[RRM 3-14 Analog Input|ai - Analog Input]]
* [[RRM 3-14 Analog Output|ao - Analog Output]]
* [[RRM 3-14 Binary Input|bi - Binary Input]]
* [[RRM 3-14 Binary Output|bo - Binary Output]]
* [[RRM 3-14 Calculation|calc - Calculation]]
* [[RRM 3-14 Calcout|calcout - Calculation Output]]
* [[RRM 3-14 Compression|compress - Compression]]
* [[RRM 3-14 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-14 Event|event - Event]]
* [[RRM 3-14 Fanout|fanout - Fanout]]
* [[RRM 3-14 Histogram|histogram - Histogram]]
* [[RRM 3-14 Long Input|longin - Long Input]]
* [[RRM 3-14 Long Output|longout - Long Output]]
* [[RRM 3-14 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-14 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-14 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-14 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-14 Permissive|permissive - Permissive]]
* [[RRM 3-14 Select|sel - Select]]
* [[RRM 3-14 Sequence|seq - Sequence]]
* [[RRM 3-14 State|state - State]]
* [[RRM 3-14 String Input|stringin - String Input]]
* [[RRM 3-14 String Output|stringout - String Output]]
* [[RRM 3-14 SubArray|subArray - Sub-Array]]
* [[RRM 3-14 Subroutine|sub - Subroutine]]
* [[RRM 3-14 Array Subroutine|aSub - Array Subroutine]]
* [[RRM 3-14 Waveform|waveform - Waveform]]

* [[RRM 3-14 Menu Choices|Appendix: Menu Choices]]

----

=== Other Record Types Not in Base ===

* [[RRM 3-14 Archive|archive - Archive]]
* [[RRM 3-14 CPID Control|cpid - CPID Control]]
* [[RRM 3-14 PID Control|pid - PID Control]]
* [[RRM 3-14 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-14 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-14 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-14 Scan|scan - Scan]]
* [[RRM 3-14 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-14 Timer|timer - Timer]]
* [[RRM 3-14 Wait|wait - Wait]]

RRM 3-14

2009-05-26T15:16:07Z

TimMooney: /* EPICS 3-14 Record Reference Manual */

<H2 style="color:#C00000">Help Needed!</H2>

This documentation is a revision of 3-13 documentation, as the software has been updated significantly since the docs were written. The [[RRM 3-14 Editing Tasks|Editing Tasks]] page gives some ideas on what needs doing to bring it up to the R3.14.9 implementation.

== EPICS 3-14 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson

Wiki version 3-14 created by Kazimierz Gofron

* [[RRM 3-14 Copyright|Copyright]]
* [[RRM 3-14 Preface|Preface]]

* [[RRM 3-14 Concepts|Database Concepts]]
* [[RRM 3-14 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-14 Common|Fields Common to Many Record Types]]

* [[RRM 3-14 Analog Input|ai - Analog Input]]
* [[RRM 3-14 Analog Output|ao - Analog Output]]
* [[RRM 3-14 Archive|archive - Archive]]
* [[RRM 3-14 Binary Input|bi - Binary Input]]
* [[RRM 3-14 Binary Output|bo - Binary Output]]
* [[RRM 3-14 Calculation|calc - Calculation]]
* [[RRM 3-14 Calcout|calcout - Calculation Output]]
* [[RRM 3-14 Compression|compress - Compression]]
* [[RRM 3-14 CPID Control|cpid - CPID Control]]
* [[RRM 3-14 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-14 Event|event - Event]]
* [[RRM 3-14 Fanout|fanout - Fanout]]
* [[RRM 3-14 Histogram|histogram - Histogram]]
* [[RRM 3-14 Long Input|longin - Long Input]]
* [[RRM 3-14 Long Output|longout - Long Output]]
* [[RRM 3-14 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-14 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-14 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-14 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-14 Permissive|permissive - Permissive]]
* [[RRM 3-14 PID Control|pid - PID Control]]
* [[RRM 3-14 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-14 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-14 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-14 Scan|scan - Scan]]
* [[RRM 3-14 Select|sel - Select]]
* [[RRM 3-14 Sequence|seq - Sequence]]
* [[RRM 3-14 State|state - State]]
* [[RRM 3-14 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-14 String Input|stringin - String Input]]
* [[RRM 3-14 String Output|stringout - String Output]]
* [[RRM 3-14 SubArray|subArray - Sub-Array]]
* [[RRM 3-14 Subroutine|sub - Subroutine]]
* [[RRM 3-14 Timer|timer - Timer]]
* [[RRM 3-14 Wait|wait - Wait]]
* [[RRM 3-14 Waveform|waveform - Waveform]]

* [[RRM 3-14 Menu Choices|Appendix: Menu Choices]]

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13

2009-05-26T15:15:11Z

TimMooney: /* EPICS 3.13 Record Reference Manual */

<H2 style="color:#C00000">Help Needed!</H2>

This documentation needs revising, as the software has been updated significantly since the docs were written. The [[RRM 3-13 Editing Tasks|Editing Tasks]] page gives some ideas on what needs doing to bring it up to the R3.13.10 implementation. However, '''please''' do ''not'' update any of these pages to cover the 3.14 releases of EPICS; we'll put up a separate manual for that version after the R3.13.10 documentation is up to scratch.

== EPICS 3.13 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson

* [[RRM 3-13 Copyright|Copyright]]
* [[RRM 3-13 Preface|Preface]]

* [[RRM 3-13 Concepts|Database Concepts]]
* [[RRM 3-13 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-13 Common|Fields Common to Many Record Types]]

* [[RRM 3-13 Analog Input|ai - Analog Input]]
* [[RRM 3-13 Analog Output|ao - Analog Output]]
* [[RRM 3-13 Archive|archive - Archive]]
* [[RRM 3-13 Binary Input|bi - Binary Input]]
* [[RRM 3-13 Binary Output|bo - Binary Output]]
* [[RRM 3-13 Calculation|calc - Calculation]]
* [[RRM 3-13 Calcout|calcout - Calculation Output]]
* [[RRM 3-13 Compression|compress - Compression]]
* [[RRM 3-13 CPID Control|cpid - CPID Control]]
* [[RRM 3-13 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-13 Event|event - Event]]
* [[RRM 3-13 Fanout|fanout - Fanout]]
* [[RRM 3-13 Histogram|histogram - Histogram]]
* [[RRM 3-13 Long Input|longin - Long Input]]
* [[RRM 3-13 Long Output|longout - Long Output]]
* [[RRM 3-13 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-13 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-13 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-13 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-13 Permissive|permissive - Permissive]]
* [[RRM 3-13 PID Control|pid - PID Control]]
* [[RRM 3-13 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-13 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-13 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-13 Scan|scan - Scan]]
* [[RRM 3-13 Select|sel - Select]]
* [[RRM 3-13 Sequence|seq - Sequence]]
* [[RRM 3-13 State|state - State]]
* [[RRM 3-13 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-13 String Input|stringin - String Input]]
* [[RRM 3-13 String Output|stringout - String Output]]
* [[RRM 3-13 SubArray|subArray - Sub-Array]]
* [[RRM 3-13 Subroutine|sub - Subroutine]]
* [[RRM 3-13 Timer|timer - Timer]]
* [[RRM 3-13 Wait|wait - Wait]]
* [[RRM 3-13 Waveform|waveform - Waveform]]

* [[RRM 3-13 Menu Choices|Appendix: Menu Choices]]

----

EPICS Record Reference Manual - 19 MAY 1998

How to make your EPICS driver operating system independent

2006-08-18T19:18:20Z

TimMooney: added mention of epicsThreadSleepQuantum()

=How to make your EPICS driver operating system independent=

'''W. Eric Norum'''

==Introduction==

The following table shows the changes made to some existing drivers to allow them to be used on systems other than vxWorks. Note that it is a very preliminary start at a set of conversion instructions. There's still no `cookbook' document to guide you, but many drivers can be converted without doing much more than applying the translations shown. A technique that I've found works well is to first change all the <code>#include</code> statements that mention vxWorks header files to their OSI equivalents, then enter a compile-edit cycle until all compile errors have been eliminated.

==Conversions==

{| border="1" cellpadding="3"
! align="CENTER" | '''vxWorks'''
! align="CENTER" | '''OSI'''
|-
| <code>#include <vxWorks.h></code>
|-
| <code>#include <stdlib.h></code>
| <code>#include <epicsStdlib.h></code>
|-
| <code>#include <stdio.h></code>
| <code>#include <epicsStdioRedirect.h></code>
|-
| <code>#include <iosLib.h></code>
|-
| <code>#include <taskLib.h></code>
| <code>#include <epicsThread.h></code>
|-
| <code>#include <memLib.h></code>
|-
| <code>#include <rebootLib.h></code>
| <code>#include <epicsExit.h></code>
|-
| <code>#include <intLib.h></code>
| <code>#include <epicsInterrupt.h></code>
|-
| <code>#include <lstLib.h></code>
|-
| <code>#include <vme.h></code>
| <code>#include <devLib.h></code>
|-
| <code>#include <sysLib.h></code>
|-
| <code>#include <iv.h></code>
|-
|
| <code>#include <epicsExport.h></code>
<code>#include <iocsh.h></code>
|-
| <code>ERROR</code>
| <code>-1</code>
|-
| <code>OK</code>
| <code>0</code>
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID flag = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
semGive(flag);
semTake(flag, WAIT_FOREVER);
| valign="TOP" | <code>#include <epicsEvent.h></code>
epicsEventId flag = epicsEventMustCreate(epicsEventEmpty);
epicsEventSignal(flag);
epicsEventMustWait(flag);
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID Lock = semMCreate(SEM_Q_PRIORITY);
semTake(Lock, WAIT_FOREVER);
semGive(Lock);
| valign="TOP" | <code>#include <epicsMutex.h></code>
epicsMutexId Lock = epicsMutexMustCreate();
epicsMutexLock(Lock);
epicsMutexUnlock(Lock);
|-
| valign="TOP" | <code>taskDelay(1)</code>
| valign="TOP" | To generate a `short' delay:
epicsThreadSleep(0.001)
This works because the operating system specific layer ensures a delay of at least one system clock tick for epicsThreadSleep arguments greater than 0.
|-
| valign="TOP" | <code>taskDelay(30)</code>
| valign="TOP" | Much old code assumes a 60 Hz vxWorks system clock. On such systems the equivalent for the command shown would be:
epicsThreadSleep(0.5)
Of course, other code may assumes a 50 Hz or 100 Hz system clock rate. You can
find out what your system clock rate is using epicsThreadSleepQuantum(), which returns the clock period in seconds.
|-
| <code>taskSuspend(0)</code>
| <code>epicsThreadSuspendSelf()</code>
|-
| valign="TOP" | <code>intConnect(INUM_TO_IVEC(IrqVector), IrqHandler, pLink)</code>
| valign="TOP" | <code>devConnectInterruptVME(IrqVector, IrqHandler, pLink)</code>
|-
| <code>sysIntEnable(IrqLevel)</code>
| <code>devEnableInterruptLevelVME(IrqLevel)</code>
|-
| valign="TOP" | <code>sysBusToLocalAdrs(VME_AM_SUP_SHORT_IO, (char*)CardAddress, (char**)&ErLink[Card].pEr)</code>
| valign="TOP" | <code>devRegisterAddress("apsEr", atVMEA16, CardAddress, 0x40, (void*)&ErLink[Card].pEr)</code>
|-
| <code>vxMemProbe(pReg, READ, sizeof(short), &value)</code>
| <code>devReadProbe(sizeof(short), pReg, &value)</code>
|-
| <code>vxMemProbe(pReg,WRITE,sizeof(short), &value)</code>
| <code>devWriteProbe(sizeof(short), pReg, &value)</code>
|-
| <code>key = intLock()</code>
| <code>key = epicsInterruptLock()</code>
|-
| <code>intUnlock(key)</code>
| <code>epicsInterrupUnlock(key)</code>
|-
| <code>rebootHookAdd((FUNCPTR)ErRebootFunc)</code>
| <code>epicsAtExit(ErRebootFunc, NULL)</code>
|-
| valign="TOP" | <code>#include <fast_lock.h></code>
FAST_LOCK lock;
FASTLOCKINIT(&mzconf[card].lock);
FASTLOCKFREE(&mzconf[card].lock);
FASTLOCK(&mzconf[card].lock);
FASTUNLOCK(&mzconf[card].lock);
| valign="TOP" | You'll have to use your judgement here. If the section of code being protected is quick (less than a few microseconds) it's reasonable to simply disable interrupts while the code is active. In this case you can remove the 'lock' variable and the init/free operations and then add a local 'key' variable and replace the lock/unlock operations with epicsInterruptLock/Unlock operations. If the section of code being protected is longer you'll have to convert the FASTLOCK to an EPICS mutex.
|-
| <code>taskSpawn(...)</code>
| <code>epicsThreadCreate(...)</code>
You should consider rewriting the driver to use the "worker thread" environment provided by the ASYN package. This is likely to result in a shorter, simpler, and more robust driver.
|}

==Some other changes==

* Some R3.13 record support database definitions explicitly mention all fields rather than including dbCommon.dbd. This can cause problems with FAST_LOCK. The solution is to add <code>include "dbCommon.dbd"</code> at the beginning of the file in question and to remove all entries for the fields provided by dbCommon.dbd.
* You should set up IOC shell command registrations for all `configure' functions and for any other commands you may need to call from the IOC shell. Here's an example of a fairly complex configuration command:
<nowiki>
/*
* IOC shell command registration
*/
#include <iocsh.h>
static const iocshArg vtr10012ConfigArg0 = { "card",iocshArgInt};
static const iocshArg vtr10012ConfigArg1 = { "VME A16 offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg2 = { "VME memory offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg3 = { "interrupt vector",iocshArgInt};
static const iocshArg vtr10012ConfigArg4 = { "interrupt level",iocshArgInt};
static const iocshArg vtr10012ConfigArg5 = { "use DMA",iocshArgInt};
static const iocshArg vtr10012ConfigArg6 = { "nchannels",iocshArgInt};
static const iocshArg vtr10012ConfigArg7 = { "kilosamplesPerChan",iocshArgInt};
static const iocshArg *vtr10012ConfigArgs[] = {
&vtr10012ConfigArg0, &vtr10012ConfigArg1, &vtr10012ConfigArg2,
&vtr10012ConfigArg3, &vtr10012ConfigArg4, &vtr10012ConfigArg5,
&vtr10012ConfigArg6,&vtr10012ConfigArg7};
static const iocshFuncDef vtr10012ConfigFuncDef =
{"vtr10012Config",8,vtr10012ConfigArgs};
static void vtr10012ConfigCallFunc(const iocshArgBuf *args)
{
vtr10012Config(args[0].ival, args[1].ival, args[2].ival,
args[3].ival, args[4].ival, args[5].ival,
args[6].ival, args[7].ival);
}

/*
* This routine is called before multitasking has started, so there's
* no race condition in the test/set of firstTime.
*/
static void
drvVtr10012RegisterCommands(void)
{
static int firstTime = 1;
if (firstTime) {
iocshRegister(&vtr10012ConfigFuncDef,vtr10012ConfigCallFunc);
firstTime = 0;
}
}
epicsExportRegistrar(drvVtr10012RegisterCommands);</nowiki>
You must also provide a corresponding registrar statement in a <code>.dbd</code> file:
registrar(drvVtr10012RegisterCommands)
* If your driver provides functions that are referred to by name from database files you must:
** <code>#include <registryFunction.h></code>
** Add an <code>epicsExportFuncion()</code> statement for each such function.
** Add a corresponding <code>function</code> statement in a <code>.dbd</code> file.

==Additional Information==

The procedure for converting a support module from R3.13 to R3.14 is described in the [http://www.aps.anl.gov/epics/base/R3-14/8-docs/ConvertingR3.13AppsToR3.14.html Converting R3.13 Apps to R3.14] document.

==Acknowledgments==

* Peter Denison (Diamond) for getting me started on this document and for useful suggestions.
* Steve Shoaf and Nick DiMonte (ANL) for some early conversions.
* Andrew Johnson for 'wikifying' the contents and setting up this page.

----
Eric Norum 2006-08-17

RRM 3-13 Data Fanout

2006-06-29T21:35:51Z

TimMooney: Added description of SELM, SELN, SELL fields

[[RRM 3-13|EPICS Record Reference Manual]]

= dfanout - Data Fanout =

: Johnny Tang, Matthew Bickley, and Chip Watson
: Continuous Electron Beam Accelerator Facility
: Southeastern Universities Research Association

The dfanout record or data fanout record is used to forward data to up to eight other records. It's similar to the fanout record except that the capability to forward data has been added to it. It has no associated device support.

== Parameter Fields ==

The fields in this record can be classified into the following categories:

* scan parameters
* desired output parameters
* write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time and simulation mode parameters

=== Scan Parameters ===

The data fanout record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the data fanout record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Desired Output Parameters ===

The data fanout record must specify where the desired output value originates, i.e., the data which it is to forward to the records in its output links. The output mode select (OMSL) field determines whether the output originates from another record or from run-time database access. When set to <CODE>closed loop</CODE>, the desired output is retrieved from the link specified in the desired output (DOL) field, which can specify either a database or channel access link, and placed into the VAL field. When set to <CODE>supervisory</CODE>, the desired output can be written to the VAL field via dpPuts at run-time.

The DOL field can also be a constant in which case the VAL field is initialized to the constant value.

Note that there are no conversion parameters, so the desired output value undergoes no conversions before it is sent out to the output links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DOL<TD>Desired Output Location (Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OMSL<TD>Output Mode Select <TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>VAL <TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Write Parameters ===

The OUTA-OUTH fields specify where VAL is to be sent. Each field that is to forward data must specify an address to another record. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links.

The SELL, SELM, and SELN fields specify which output link(s) are to be used.
SELM is a menu, with the following choices: "All", "Specified", "Mask". If
SELM=="All", then all output links are used, and the values of SELL and SELN
are ignored.

If SELM=="Specified", then the value of SELN is used to specify a single link
which will be used. If SELN==0, then no link will be used; if SELN==1, then OUTA will be used, and so on.

SELN can either have its value set directly, or have its value retrieved from
another EPICS PV. If SELL is a valid PV link, then SELN will be set to the
value of the linked PV

If SELM=="Mask", then SELN will be treated as a bit mask. If bit one of SELN
is set, then OUTA will be used, if bit two is set, OUTB will be used. Thus
if SELN==5, OUTC and OUTA will be used.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Link A<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Link B<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OUTC<TD>Output Link C<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OUTD<TD>Output Link D<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OUTE<TD>Output Link E<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OUTF<TD>Output Link F<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OUTG<TD>Output Link G<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OUTH<TD>Output Link H<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the data fanout record either textually or graphically.

The EGU field can contain a string of up to 16 characters describing the value in the VAL field.

The HOPR and LOPR fields determine the upper and lower display limits for graphics displays and the upper and lower control limits for control displays. They apply to the VAL, HIHI, HIGH, LOW, and LOLO fields. The record support routines <CODE>get_graphic_double</CODE> or <CODE>get_control_double</CODE> retrieve HOPR and LOPR

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for data fanouts are the SCAN, READ, INVALID, and limit alarms. The SCAN and READ alarms are called by the record routines. The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using floating-point values. The limit alarms apply only to the VAL field. The severity for each of these limits is specified in the corresponding field (HHSV, LLSV, HSV, LSV) and can be either NO_ALARM, MINOR, or MAJOR. In the hysteresis field (HYST) can be entered a number which serves as the deadband on the limit alarms.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors placed on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband, ADEL for archiver monitors and MDEL for all other types of monitors. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-13 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time Parameters and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the data fanout record. They are not configurable. They are used to implement the hysteresis factors for monitor callbacks.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record() ====

This routine initializes all output links that are defined. Then it initializes DOL is DOL is a constant or PV_LINK. When initializing the output links and the DOL link, a non-zero value is returned if an error occurs.

==== process() ====

See next section.

==== get_value() ====

This routine fills in the members of <CODE>struct valueDes</CODE> with the VAL fields value and characteristics.

==== get_units() ====

The routine copies the string specified in the EGU field to the location specified by a pointer which is passed to the routine.

==== get_graphic_double() ====

If the referenced field is VAL, HIHI, HIGH, LOW, or LOLO, this routine sets the <CODE>upper_disp_limit</CODE> member of the <CODE>dbr_grDouble</CODE> structure to HOPR and the <CODE>lower_disp_limit</CODE> member to LOPR. If the referenced field is not one of the above fields, then the <CODE>recGblGetControlDouble()</CODE> routine is called.

==== get_control_double() ====

Same as the <CODE>get_graphic_double</CODE> routine except that it uses the <CODE>dbr_ctrlDouble</CODE> structure.

==== get_alarm_double() ====

This sets the members of the <CODE>dbr_alDouble</CODE> structure to the specified alarm limits if the referenced field is VAL:

upper_alarm_limit = HIHI
upper_warning_limit = HIGHT
lower_warning_limit = LOW
lower_alarm_limit = LOLO

If the referenced field is not VAL, the <CODE>recGblGetAlarmDouble()</CODE> routine is called.

=== Record Processing ===

# The <CODE>process()</CODE> routine first retrieves a value for DOL and places it in VAL if OMSL is set to closed loop mode. If ann error occurs, then UDF is set to FALSE.
# PACT is set TRUE.
# VAL is then sent to all the records specified in the OUTA-OUTH fields by calling the <CODE>recGblPutLinkValue()</CODE> for each link.
# Alarms are checked and monitors are called if conditions apply.
# The data fanout's own forward link is then processed.
# PACT is set FALSE, and the <CODE>process()</CODE> routine returns. A -1 is returned if there was an error writing values to one of the output links.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Transform

2006-06-09T15:29:06Z

TimMooney:

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> is not blank and is not simply a constant initializer, then <i>expression</i> may be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments. (EPICS 3.14-compatible version only.)</font>
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported. (EPICS 3.14-compatible version only.)</font>
* The binary operator '!=' (not equal) is a permitted alternatives '#'.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. This field is not very useful, because it's unlikely to pertain to all 16 value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They have the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed. For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

== Availability ==

The Transform record is not included with EPICS base. An EPICS 3.13-compatible version of this record is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-09T15:27:08Z

TimMooney:

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> is not blank and is not simply a constant initializer, then <i>expression</i> may be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments.</font>
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported.</font>
* The binary operator '!=' (not equal) is a permitted alternatives '#'.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. This field is not very useful, because it's unlikely to pertain to all 16 value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They have the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed. For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

== Availability ==

The Transform record is not included with EPICS base. An EPICS 3.13-compatible version of this record is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-09T15:11:56Z

TimMooney:

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> is not blank and is not simply a constant initializer, then <i>expression</i> may be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments.</font>
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported.</font>
* The binary operator '!=' (not equal) is a permitted alternatives '#'.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

== Availability ==

The Transform record is not included with EPICS base. An EPICS 3.13-compatible version of this record is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-09T15:11:39Z

TimMooney:

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Text that does not apply to the 3.13-compatible version is rendered in <font color="blue">blue</font>. Documentation specific to the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions and operands. The record has 12 numeric fields (A...L) and 12 string fields (AA...LL), which are used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and produces both numeric and string results, in the VAL and SVAL fields, respectively. The record's output link writes string or numeric data, depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>CALC</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[#Output Parameters|Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[#Output Parameters|Output Parameters]].

sCalcout-record expressions are very similar to standard EPICS Calc expressions, such as those used with the Calcout record. But in place of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record uses the <i>sCalc</i> engine, a separate piece of software, which normally is [[#Availability|distributed]] with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments.</font>
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported.</font>
* The binary operator '!=' (not equal) is a permitted alternatives '#'.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN(A,B)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX(A,B)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top><font color="blue">>&</font>
<td valign=top><font color="blue">Max (binary)</font>
<td><font color="blue"><code>A>?B</code></font>

<tr>
<td align=center valign=top><font color="blue"><&</font>
<td valign=top><font color="blue">Min (binary)</font>
<td><font color="blue"><code>A<?B</code></font>
</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN('a','b') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX('a','b') </code>→<code> 'b'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top><font color="blue">-|</font>
<td><font color="blue">Delete first occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'bca'</code></font>

<tr>
<td align=center valign=top><font color="blue">|-</font>
<td><font color="blue">Delete last occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top><font color="blue">TR_ESC</font>
<td><font color="blue">Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string</font>
<td><font color="blue"><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top><font color="blue">ESC</font>
<td><font color="blue">Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.</font>
<td><font color="blue"><code>ESC("a<return>c") </code>→<code> 'a\rc'</code></font>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD><font color="blue">WAIT</font></TD>
<TD><font color="blue">Wait for completion?</font></TD>
<TD><font color="blue">Menu</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">"NoWait"</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">No</font></TD>
</TR>
</TABLE>

<font color="blue">
The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.
</font>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met, either execute the output link (and output event) immediately (if ODLY=0), or schedule a callback to do so after the specified interval. See the explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
## NSEV and NSTA are reset to 0
# <font color="blue">Call device support to</font> execute output link.
# If we're not waiting for the output delay to expire, or for a completion callback, process the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", <font color="blue">call device support to</font> write the value of OVAL to <font color="blue">device or</font> PV specified by the OUT link, and post the event in OEVT (if non-zero).

== Availability ==

The sCalcout record is not included with EPICS base. The 3.14-compatible version is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software. The 3.13-compatible version is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module of a 3.13-compatible synApps distribution.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-09T15:02:51Z

TimMooney:

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> is not blank and is not simply a constant initializer, then <i>expression</i> may be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

== Availability ==

The Transform record is not included with EPICS base. An EPICS 3.13-compatible version of this record is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-09T15:01:35Z

TimMooney: /* Expression Parameters */

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> is not blank and not simply a constant initializer, then <i>expression</i> will be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

== Availability ==

The Transform record is not included with EPICS base. An EPICS 3.13-compatible version of this record is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-08T22:11:38Z

TimMooney:

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Text that does not apply to the 3.13-compatible version is rendered in <font color="blue">blue</font>. Documentation specific to the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions and operands. The record has 12 numeric fields (A...L) and 12 string fields (AA...LL), which are used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and produces both numeric and string results, in the VAL and SVAL fields, respectively. The record's output link writes string or numeric data, depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>CALC</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[#Output Parameters|Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[#Output Parameters|Output Parameters]].

sCalcout-record expressions are very similar to standard EPICS Calc expressions, such as those used with the Calcout record. But in place of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record uses the <i>sCalc</i> engine, a separate piece of software, which normally is [[#Availability|distributed]] with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments.</font>
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported.</font>
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN(A,B)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX(A,B)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top><font color="blue">>&</font>
<td valign=top><font color="blue">Max (binary)</font>
<td><font color="blue"><code>A>?B</code></font>

<tr>
<td align=center valign=top><font color="blue"><&</font>
<td valign=top><font color="blue">Min (binary)</font>
<td><font color="blue"><code>A<?B</code></font>
</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN('a','b') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX('a','b') </code>→<code> 'b'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top><font color="blue">-|</font>
<td><font color="blue">Delete first occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'bca'</code></font>

<tr>
<td align=center valign=top><font color="blue">|-</font>
<td><font color="blue">Delete last occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top><font color="blue">TR_ESC</font>
<td><font color="blue">Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string</font>
<td><font color="blue"><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top><font color="blue">ESC</font>
<td><font color="blue">Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.</font>
<td><font color="blue"><code>ESC("a<return>c") </code>→<code> 'a\rc'</code></font>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD><font color="blue">WAIT</font></TD>
<TD><font color="blue">Wait for completion?</font></TD>
<TD><font color="blue">Menu</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">"NoWait"</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">No</font></TD>
</TR>
</TABLE>

<font color="blue">
The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.
</font>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met, either execute the output link (and output event) immediately (if ODLY=0), or schedule a callback to do so after the specified interval. See the explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
## NSEV and NSTA are reset to 0
# <font color="blue">Call device support to</font> execute output link.
# If we're not waiting for the output delay to expire, or for a completion callback, process the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", <font color="blue">call device support to</font> write the value of OVAL to <font color="blue">device or</font> PV specified by the OUT link, and post the event in OEVT (if non-zero).

== Availability ==

The sCalcout record is not included with EPICS base. The 3.14-compatible version is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software. The 3.13-compatible version is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module of a 3.13-compatible synApps distribution.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-08T21:53:12Z

TimMooney:

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Text that does not apply to the 3.13-compatible version is rendered in <font color="blue">blue</font>. Documentation specific to the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions and operands. The record has 12 numeric fields (A...L) and 12 string fields (AA...LL), which are used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and produces both numeric and string results, in the VAL and SVAL fields, respectively. The record's output link writes string or numeric data, depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>CALC</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[#Output Parameters|Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[#Output Parameters|Output Parameters]].

sCalcout-record expressions are very similar to standard EPICS Calc expressions, such as those used with the Calcout record. But in place of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record uses the <i>sCalc</i> engine, a separate piece of software, which normally is [[#Availability|distributed]] with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments.</font>
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported.</font>
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN(A,B)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX(A,B)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top><font color="blue">>&</font>
<td valign=top><font color="blue">Max (binary)</font>
<td><font color="blue"><code>A>?B</code></font>

<tr>
<td align=center valign=top><font color="blue"><&</font>
<td valign=top><font color="blue">Min (binary)</font>
<td><font color="blue"><code>A<?B</code></font>
</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN('a','b') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX('a','b') </code>→<code> 'b'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top><font color="blue">-|</font>
<td><font color="blue">Delete first occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'bca'</code></font>

<tr>
<td align=center valign=top><font color="blue">|-</font>
<td><font color="blue">Delete last occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top><font color="blue">TR_ESC</font>
<td><font color="blue">Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string</font>
<td><font color="blue"><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top><font color="blue">ESC</font>
<td><font color="blue">Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.</font>
<td><font color="blue"><code>ESC("a<return>c") </code>→<code> 'a\rc'</code></font>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD><font color="blue">WAIT</font></TD>
<TD><font color="blue">Wait for completion?</font></TD>
<TD><font color="blue">Menu</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">"NoWait"</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">No</font></TD>
</TR>
</font>
</TABLE>

<font color="blue">
The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.
</font>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# <font color="blue">Call device support to</font> execute output link.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", <font color="blue">call device support to</font> write the value of OVAL to <font color="blue">device or</font> PV specified by the OUT link, and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. The 3.14-compatible version is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software. The 3.13-compatible version is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module of a 3.13-compatible synApps distribution.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-08T21:50:52Z

TimMooney:

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Text that does not apply to the 3.13-compatible version is rendered in <font color="blue">blue</font>. Documentation specific to the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions and operands. The record has 12 numeric fields (A...L) and 12 string fields (AA...LL), which are used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and produces both numeric and string results, in the VAL and SVAL fields, respectively. The record's output link writes string or numeric data, depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>CALC</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[#Output Parameters|Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[#Output Parameters|Output Parameters]].

sCalcout-record expressions are very similar to standard EPICS Calc expressions, such as those used with the Calcout record. But in place of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record uses the <i>sCalc</i> engine, a separate piece of software, which normally is [[#Availability|distributed]] with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments.</font>
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported.</font>
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN(A,B)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX(A,B)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top><font color="blue">>&</font>
<td valign=top><font color="blue">Max (binary)</font>
<td><font color="blue"><code>A>?B</code></font>

<tr>
<td align=center valign=top><font color="blue"><&</font>
<td valign=top><font color="blue">Min (binary)</font>
<td><font color="blue"><code>A<?B</code></font>
</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN('a','b') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX('a','b') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top><font color="blue">-|</font>
<td><font color="blue">Delete first occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'bca'</code></font>

<tr>
<td align=center valign=top><font color="blue">|-</font>
<td><font color="blue">Delete last occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top><font color="blue">TR_ESC</font>
<td><font color="blue">Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string</font>
<td><font color="blue"><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top><font color="blue">ESC</font>
<td><font color="blue">Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.</font>
<td><font color="blue"><code>ESC("a<return>c") </code>→<code> 'a\rc'</code></font>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD><font color="blue">WAIT</font></TD>
<TD><font color="blue">Wait for completion?</font></TD>
<TD><font color="blue">Menu</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">"NoWait"</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">No</font></TD>
</TR>
</font>
</TABLE>

<font color="blue">
The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.
</font>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# <font color="blue">Call device support to</font> execute output link.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", <font color="blue">call device support to</font> write the value of OVAL to <font color="blue">device or</font> PV specified by the OUT link, and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. The 3.14-compatible version is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software. The 3.13-compatible version is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module of a 3.13-compatible synApps distribution.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-08T21:23:58Z

TimMooney: Distinguish 3.14 from 3.13 with color

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Text that does not apply to the 3.13-compatible version is rendered in <font color="blue">blue</font>. Documentation of the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions and operands. The record has 12 string fields (AA...LL) used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results. The record's output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>CALC</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[#Output Parameters|Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[#Output Parameters|Output Parameters]].

sCalcout-record expressions are very similar to standard EPICS Calc expressions, such as those used with the Calcout record. But in place of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record uses the <i>sCalc</i> engine, a separate piece of software, which normally is [[#Availability|distributed]] with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants S2R (arc-seconds-to-radians) and R2S are supported.
* <font color="blue">The functions MIN() and MAX() may have more than two arguments.</font>
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* <font color="blue">The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported.</font>
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN(A,B)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX(A,B)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top><font color="blue">>&</font>
<td valign=top><font color="blue">Max (binary)</font>
<td><font color="blue"><code>A>?B</code></font>

<tr>
<td align=center valign=top><font color="blue"><&</font>
<td valign=top><font color="blue">Min (binary)</font>
<td><font color="blue"><code>A<?B</code></font>
</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MIN('a','b') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two<font color="blue">-or-more</font>-argument function)
<td><code>MAX('a','b') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top><font color="blue">-|</font>
<td><font color="blue">Delete first occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'bca'</code></font>

<tr>
<td align=center valign=top><font color="blue">|-</font>
<td><font color="blue">Delete last occurrence of substring (binary)</font>
<td><font color="blue"><code>'abca'-'a' </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top><font color="blue">TR_ESC</font>
<td><font color="blue">Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string</font>
<td><font color="blue"><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code></font>

<tr>
<td align=center valign=top><font color="blue">ESC</font>
<td><font color="blue">Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.</font>
<td><font color="blue"><code>ESC("a<return>c") </code>→<code> 'a\rc'</code></font>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD><font color="blue">WAIT</font></TD>
<TD><font color="blue">Wait for completion?</font></TD>
<TD><font color="blue">Menu</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">"NoWait"</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">Yes</font></TD>
<TD><font color="blue">No</font></TD>
</TR>
</font>
</TABLE>

<font color="blue">
The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.
</font>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# <font color="blue">Call device support to</font> execute output link.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", <font color="blue">call device support to</font> write the value of OVAL to <font color="blue">device or</font> PV specified by the OUT link, and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. The 3.14-compatible version is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software. The 3.13-compatible version is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module of a 3.13-compatible synApps distribution.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-08T18:31:54Z

TimMooney: /* Expression Parameters */

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Documentation of the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions in addition to numeric expressions. The record has 12 string fields (AA...LL) used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results. The record's output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>CALC</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[Output Parameters]].

sCalcout-record expressions are very similar to standard EPICS Calc expressions, such as those used with the Calcout record. But in place of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record uses the <i>sCalc</i> engine, a separate piece of software, which normally is [[#Availability|distributed]] with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two-or-more-argument function)
<td><code>MIN(A,B,C)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two-or-more-argument function)
<td><code>MAX(A,B,C)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top>>&
<td valign=top>Max (binary)
<td><code>A>?B</code>

<tr>
<td align=center valign=top><&
<td valign=top>Min (binary)
<td><code>A<?B</code>

</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two-or-more-argument function)
<td><code>MIN('a','b','c') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>-|
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>|-
<td>Delete last occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top>TR_ESC
<td>Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string
<td><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>ESC
<td>Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.
<td><code>ESC("a<return>c") </code>→<code> 'a\rc'</code>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>WAIT</TD>
<TD>Wait for completion?</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>"NoWait"</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

See the EPICS Record Reference Manual, for more on the record name (NAME) and
description (DESC) fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", call device support to write the value of OVAL to device or PV specified by the OUT link, and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-08T18:25:00Z

TimMooney: Added table of expression parameters

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Documentation of the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions in addition to numeric expressions. The record has 12 string fields (AA...LL) used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results. The record's output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>CALC</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Infix expression</TD>
<TD>String[40]</TD>
<TD>Yes</TD>
<TD>""</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>Long</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[Output Parameters]].

sCalcout-record expressions are very similar to Calcout-record expression described elsewhere in this manual. But instead of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record expressions are handled by the sCalc engine, a separate piece of software that normally is distributed along with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two-or-more-argument function)
<td><code>MIN(A,B,C)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two-or-more-argument function)
<td><code>MAX(A,B,C)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top>>&
<td valign=top>Max (binary)
<td><code>A>?B</code>

<tr>
<td align=center valign=top><&
<td valign=top>Min (binary)
<td><code>A<?B</code>

</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two-or-more-argument function)
<td><code>MIN('a','b','c') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>-|
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>|-
<td>Delete last occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top>TR_ESC
<td>Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string
<td><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>ESC
<td>Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.
<td><code>ESC("a<return>c") </code>→<code> 'a\rc'</code>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>WAIT</TD>
<TD>Wait for completion?</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>"NoWait"</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

See the EPICS Record Reference Manual, for more on the record name (NAME) and
description (DESC) fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", call device support to write the value of OVAL to device or PV specified by the OUT link, and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-07T21:47:33Z

TimMooney:

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Documentation of the 3.13-compatible version is currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions in addition to numeric expressions. The record has 12 string fields (AA...LL) used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results. The record's output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[Output Parameters]].

sCalcout-record expressions are very similar to Calcout-record expression described elsewhere in this manual. But instead of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record expressions are handled by the sCalc engine, a separate piece of software that normally is distributed along with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two-or-more-argument function)
<td><code>MIN(A,B,C)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two-or-more-argument function)
<td><code>MAX(A,B,C)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top>>&
<td valign=top>Max (binary)
<td><code>A>?B</code>

<tr>
<td align=center valign=top><&
<td valign=top>Min (binary)
<td><code>A<?B</code>

</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two-or-more-argument function)
<td><code>MIN('a','b','c') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>-|
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>|-
<td>Delete last occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top>TR_ESC
<td>Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string
<td><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>ESC
<td>Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.
<td><code>ESC("a<return>c") </code>→<code> 'a\rc'</code>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>WAIT</TD>
<TD>Wait for completion?</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>"NoWait"</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

See the EPICS Record Reference Manual, for more on the record name (NAME) and
description (DESC) fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", call device support to write the value of OVAL to device or PV specified by the OUT link, and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-07T21:46:57Z

TimMooney:

= sCalcout Record =

<i>This page actually describes the EPICS-3.14-compatible version of the sCalcout record. Documentation of the 3.13-compatible version are currently not available in this format, but may be found in the 'std' module of a 3.13-compatible synApps package.</i>

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions in addition to numeric expressions. The record has 12 string fields (AA...LL) used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results. The record's output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[Output Parameters]].

sCalcout-record expressions are very similar to Calcout-record expression described elsewhere in this manual. But instead of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record expressions are handled by the sCalc engine, a separate piece of software that normally is distributed along with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two-or-more-argument function)
<td><code>MIN(A,B,C)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two-or-more-argument function)
<td><code>MAX(A,B,C)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top>>&
<td valign=top>Max (binary)
<td><code>A>?B</code>

<tr>
<td align=center valign=top><&
<td valign=top>Min (binary)
<td><code>A<?B</code>

</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two-or-more-argument function)
<td><code>MIN('a','b','c') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>-|
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>|-
<td>Delete last occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top>TR_ESC
<td>Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string
<td><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>ESC
<td>Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.
<td><code>ESC("a<return>c") </code>→<code> 'a\rc'</code>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>WAIT</TD>
<TD>Wait for completion?</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>"NoWait"</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

See the EPICS Record Reference Manual, for more on the record name (NAME) and
description (DESC) fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", call device support to write the value of OVAL to device or PV specified by the OUT link, and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-07T21:39:26Z

TimMooney:

= sCalcout Record =

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions in addition to numeric expressions. The record has 12 string fields (AA...LL) used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results. The record's output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[Output Parameters]].

sCalcout-record expressions are very similar to Calcout-record expression described elsewhere in this manual. But instead of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record expressions are handled by the sCalc engine, a separate piece of software that normally is distributed along with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a non-blank input link is associated with this field, then it may
not be modified. This is true even if the input link is invalid (in which case, the value will be 0, for a numeric field, or "Huh?", for a string field).

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two-or-more-argument function)
<td><code>MIN(A,B,C)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two-or-more-argument function)
<td><code>MAX(A,B,C)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top>>&
<td valign=top>Max (binary)
<td><code>A>?B</code>

<tr>
<td align=center valign=top><&
<td valign=top>Min (binary)
<td><code>A<?B</code>

</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two-or-more-argument function)
<td><code>MIN('a','b','c') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>-|
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>|-
<td>Delete last occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top>TR_ESC
<td>Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string
<td><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>ESC
<td>Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.
<td><code>ESC("a<return>c") </code>→<code> 'a\rc'</code>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.) In other words, string arguments <i>delimit</i> the substring they are specifying without participating in it.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>WAIT</TD>
<TD>Wait for completion?</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>"NoWait"</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

See the EPICS Record Reference Manual, for more on the record name (NAME) and
description (DESC) fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform
for the postfix version of the expression in OCAL. Otherwise, use VAL.

# If the Alarm Severity is INVALID, follow the option as designated by
the field IVOA.

# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally",
call device support to write the value of OVAL to device or PV specified by
the OUT link, and post the event in OEVT (if non-zero).

# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-07T21:19:04Z

TimMooney: 3.14 version

= sCalcout Record =

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions in addition to numeric expressions. The record has 12 string fields (AA...LL) used as input variables for the expression. It calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results. The record's output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into the following categories:

* Scan Parameters
* Read Parameters
* Expression Parameters
* Output Parameters
* Operator Display Parameters
* Alarm Parameters
* Monitor Parameters
* Run-Time Parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 for numeric values (INPA→A, INPB→B, ... INPL→L); and 12 for string values (INAA→AA, INBB→BB, ... INLL→LL). The fields can be database links, channel access links, or constants. If they are links, they must contain a PV name. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, ... INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, ... ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [[Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TR><TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TR><TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TR><TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...
<TR><TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the sCalcout record has the fields CALC and OCAL, in which the developer or user can enter an infix expression to be evaluated when the record is processed. The numeric value resulting from evaluation of CALC will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see [[Output Parameters]]) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC and OCAL expressions are actually converted to opcodes and stored in postfix notation in the RPCL and ORPC fields. It is these expressions which are actually used to calculate VAL. A postfix expression can be evaluated more efficiently at run-time than an infix expression would be. When CALC or OCAL is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

In simple cases, OCAL is ignorable. It's use will be described later, in [[Output Parameters]].

sCalcout-record expressions are very similar to Calcout-record expression described elsewhere in this manual. But instead of the standard EPICS calc engine (which does not support string fields or operations), sCalcout-record expressions are handled by the sCalc engine, a separate piece of software that normally is distributed along with the sCalcout record. The differences between these engines that matter for numeric expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A...L used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a valid input link is associated with this field, then it may
not be modified.

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two-or-more-argument function)
<td><code>MIN(A,B,C)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two-or-more-argument function)
<td><code>MAX(A,B,C)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top>>&
<td valign=top>Max (binary)
<td><code>A>?B</code>

<tr>
<td align=center valign=top><&
<td valign=top>Min (binary)
<td><code>A<?B</code>

</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two-or-more-argument function)
<td><code>MIN('a','b','c') </code>→<code> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') </code>→<code> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') </code>→<code> 1</code><br>
<code>INT('abc1.9') </code>→<code> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') </code>→<code> 2</code><br>
<code>NINT('abc1.9') </code>→<code> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' </code>→<code> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>-|
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'bca'</code>

<tr>
<td align=center valign=top>|-
<td>Delete last occurrence of substring (binary)
<td><code>'abca'-'a' </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' </code>→<code> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' </code>→<code> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' </code>→<code> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') </code>→<code> 1.0</code><br>
<code>DBL('abc1.23') </code>→<code> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) </code>→<code> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') </code>→<code> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) </code>→<code> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") </code>→<code> 1.25</code>

<tr>
<td align=center valign=top>TR_ESC
<td>Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string
<td><code>TR_ESC("a\x62c") </code>→<code> 'abc'</code>

<tr>
<td align=center valign=top>ESC
<td>Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.
<td><code>ESC("a<return>c") </code>→<code> 'a\rc'</code>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] </code>→<code> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] </code>→<code> 'cd'</code>
<code><BR>'abcdef'[0,-1] </code>→<code> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} </code>→<code> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"<br>
A + "abc1.2"<br>
A + AA (where AA = "abc1.2")
:Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
:Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
:Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
:Result is "abc1.23".
:NOTE: unlike the c-language function printf(<format>,<arg1>,<arg2>,...), this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
:Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)<br>
:NOTE: unlike the c-language function sscanf(<source>,<format>,<dest1>,<dest2>,...), this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
:Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
:Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
:Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
:Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.)

A==2 ? "yes" : "no"
:Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
:Result is "adcbef".

"abcdef"{"zzz","dcb"}
:Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
:Result is "cd"

===== Array Examples =====
@0
:Result is the value of the numeric variable A. ("@0" is just another name for A.)

@@0
:Result is the value of the string variable AA.

@(A+B)
:Result is the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>WAIT</TD>
<TD>Wait for completion?</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>"NoWait"</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<code> xxx:record.field <b>CA</b> NMS</code>

Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<code> xxx:record.field <b>PP</b> NMS</code>

for example, then the record will not wait for completion before executing
its forward link.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

The DLYA field is set to one during the delay interval specified
in ODLY.

See the EPICS Record Reference Manual, for more on the record name (NAME) and
description (DESC) fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for
the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

* upper_alarm_limit = HIHI
* upper_warning_limit = HIGH
* lower_warning_limit = LOW
* lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform
for the postfix version of the expression in OCAL. Otherwise, use VAL.

# If the Alarm Severity is INVALID, follow the option as designated by
the field IVOA.

# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally",
call device support to write the value of OVAL to device or PV specified by
the OUT link, and post the event in OEVT (if non-zero).

# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 String Calcout

2006-06-07T19:59:21Z

TimMooney: First cut

= sCalcout Record =

The String Calculation Output or "sCalcout" record is derived from the Calcout record and extends it by supporting string expressions in addition to numeric expressions. The record has 12 string fields (AA...LL) used as input variables for the expression; calls an extended version of the EPICS calculation engine that accepts string arguments, supports a variety of string functions, and can produce string results; and its output link writes string or numeric data depending on the data type of the field to which it is linked.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The sCalcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the sCalcout record supports no direct interfaces to input hardware that might generate an interrupt, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the sCalcout record consist of 24 input links: 12 to numeric fields (INPA -> A, INPB -> B, . . . INPL -> L); and 12 to string fields (INAA -> AA, INBB -> BB, ...INLL -> LL). The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the sCalcout record contains the fields INAV, INBV, . . . INLV, which indicate the status of the links to numeric fields, and the fields IAAV, IBBV, . . . ILLV, which indicate the status of the links to string fields. These fields indicate whether or not the specified PV was found and a link to it established. See [Operator Display Parameters] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
<TD>INAA<TD>Input Link AA<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INBB<TD>Input Link BB<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INLL<TD>Input Link LL<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the sCalcout record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. The resulting numeric value will be placed in the VAL field, and the resulting string value will be placed in the SVAL field. VAL can then be used by the OOPT field (see Section 5, Output Parameters) to determine whether or not to write to the output link or post an output event. Either VAL and SVAL can also be written to the output link. (If you elect to write an output value, the record will choose between VAL and SVAL, depending on the data type of the field at the other end of the output link.)

The CALC expression is actually converted to opcodes and stored in postfix notation in the RPCL field. It is this expression which is actually used to calculate VAL. The postfix expression is evaluated more efficiently at run-time than an infix expression would be. When CALC is changed at run-time, the record-support routine special() will call a function to check it, and convert it to postfix.

The record also has a second set of calculation-related fields described in [Output Parameters].

sCalcout-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), sCalcout-record expressions are handled by the sCalc engine,
a separate piece of software that normally accompanies the sCalcout record. The differences between
these engines that matter for numeric expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

Expressions supported by the sCalcout record can involve operands, algebraic operators and functions, trigonometric functions, relational operators, logical operators, string operators and functions, parentheses and commas, and the conditional '?:' operator. Numeric and string operands are supported, and
any operand can be used with any operator or function. If an operand has the "wrong" type for the function or operator with which it is used, the operand will be converted implicitly to the correct type.

Grouping of operands with parentheses is important not only to specify the order in which operations are to be performed, but also to distinguish operands from operators whose names are spelled out, such as the logical operator 'AND'. For example, the expression 'AANDB', which could have meant 'A AND B', will be (mis)interpreted by the parser as 'AA NDB'.

==== Operands ====

The expression can use the values retrieved from the input links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L, and AA-LL fields. The values to be used in the expression are simply referenced by the field name. For example, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.

<TABLE BORDER>

<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>A</TD>
<TD>Input Value A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>B</TD>

<TD>Input Value B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>L</TD>
<TD>Input Value L</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR><TD></TR>

<TR>
<TD>AA</TD>
<TD>Input string AA</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>BB</TD>
<TD>Input string BB</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Input string LL</TD>
<TD>STRING (40)</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes/No*</TD>
<TD>Yes</TD>
<TD>Yes</TD>
</TR>

</TABLE>

Legend: * If a valid input link is associated with this field, then it may
not be modified.

There are a few special operands not associated with input fields, but
defined by the record (more exactly, defined by the calc engine the record uses
to evaluate expressions). All but <code>RNDM</code> are constants.

<table border>

<tr>
<td align=center valign=top>PI
<td valign=top>3.141592654

<tr>
<td align=center valign=top>D2R
<td valign=top>Degrees to radians (PI/180)

<tr>
<td align=center valign=top>R2D
<td valign=top>Radians to degrees (1/D2R)

<tr>
<td align=center valign=top>S2R
<td valign=top>Arc seconds to radians (D2R/3600)

<tr>
<td align=center valign=top>R2S
<td valign=top>Radians to arc seconds (1/S2R)

<tr>
<td align=center valign=top>RNDM
<td valign=top>Random number between 0 and 1.

</table>

==== Algebraic Functions/Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>ABS
<td valign=top>Absolute value (one-argument function)
<td><code>ABS(A)</code>

<tr>
<td align=center valign=top>SQRT
<td valign=top>Square root (one-argument function) (SQR is deprecated)
<td><code>SQRT(A)</code>

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum (two-or-more-argument function)
<td><code>MIN(A,B,C)</code>

<tr>
<td align=center valign=top>MAX
<td valign=top>Maximum (two-or-more-argument function)
<td><code>MAX(A,B,C)</code>

<tr>
<td align=center valign=top>CEIL
<td valign=top>Ceiling (one-argument function)
<td><code>CEIL(A)</code>

<tr>
<td align=center valign=top>FLOOR
<td valign=top>Floor (one-argument function)
<td><code>FLOOR(A)</code>

<tr>
<td align=center valign=top>INT
<td valign=top>Nearest integer (one-argument function)
<td><code>INT(A)</code>

<tr>
<td align=center valign=top>NINT
<td valign=top>Nearest integer (one-argument function)
<td><code>NINT(A)</code>

<tr>
<td align=center valign=top>LOG
<td valign=top>Log base 10 (one-argument function)
<td><code>LOG(A)</code>

<tr>
<td align=center valign=top>LN
<td valign=top>Natural logarithm (one-argument function)
<td><code>LN(A)</code>

<tr>
<td align=center valign=top>LOGE
<td valign=top>Deprecated synonym for 'LN'
<td><code>LOGE(A)</code>

<tr>
<td align=center valign=top>EXP
<td valign=top>Exponential function (unary)
<td><code>EXP(A)</code>

<tr>
<td align=center valign=top>^
<td valign=top>Exponential (binary) (Same as '**'.)
<td><code>A^B</code>

<tr>
<td align=center valign=top>**
<td valign=top>Exponential (binary) (Same as '^'.)
<td><code>A**B</code>

<tr>
<td align=center valign=top>+
<td valign=top>Addition (binary)
<td><code>A+B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Subtraction (binary)
<td><code>A-B</code>

<tr>
<td align=center valign=top>*
<td valign=top>Multiplication (binary)
<td><code>A*B</code>

<tr>
<td align=center valign=top>/
<td valign=top>Division (binary)
<td><code>A/B</code>

<tr>
<td align=center valign=top>%
<td valign=top>Modulo (binary)
<td><code>A%B</code>

<tr>
<td align=center valign=top>-
<td valign=top>Negate (unary)
<td><code>-A</code>

<tr>
<td align=center valign=top>NOT
<td valign=top>Negate (unary)
<td><code>NOT A</code>

<tr>
<td align=center valign=top>>&
<td valign=top>Max (binary)
<td><code>A>?B</code>

<tr>
<td align=center valign=top><&
<td valign=top>Min (binary)
<td><code>A<?B</code>

</table>

==== Trigonometric Functions ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>SIN
<td valign=top>Sine (one-argument function)
<td><code>SIN(A)</code>

<tr>
<td align=center valign=top>SINH
<td valign=top>Hyperbolic sine (one-argument function)
<td><code>SINH(A)</code>

<tr>
<td align=center valign=top>ASIN
<td valign=top>Arc sine (one-argument function)
<td><code>ASIN(A)</code>

<tr>
<td align=center valign=top>COS
<td valign=top>Cosine (one-argument function)
<td><code>COS(A)</code>

<tr>
<td align=center valign=top>COSH
<td valign=top>Hyperbolic cosine (one-argument function)
<td><code>COSH(A)</code>

<tr>
<td align=center valign=top>ACOS
<td valign=top>Arc cosine (one-argument function)
<td><code>ACOS(A)</code>

<tr>
<td align=center valign=top>TAN
<td valign=top>Tangent (one-argument function)
<td><code>TAN(A)</code>

<tr>
<td align=center valign=top>TANH
<td valign=top>Hyperbolic tangent (one-argument function)
<td><code>TANH(A)</code>

<tr>
<td align=center valign=top>ATAN
<td valign=top>Arc tangent (one-argument function)
<td><code>ATAN(A)</code>

<tr>
<td align=center valign=top>ATAN2
<td valign=top>Alternate form of arctangent (two-argument function)
<td><code>ATAN2(A,B)</code>

</table>

==== Relational Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>>=
<td valign=top>Greater than or equal to
<td><code>A>=B</code>

<tr>
<td align=center valign=top>>
<td valign=top>Greater than
<td><code>A>B</code>

<tr>
<td align=center valign=top><=
<td valign=top>Less than or equal to
<td><code>A<=B</code>

<tr>
<td align=center valign=top><
<td valign=top>Less than
<td><code>A<B</code>

<tr>
<td align=center valign=top>!=
<td valign=top>Not equal to (same as '#')
<td><code>A!=B</code>

<tr>
<td align=center valign=top>#
<td valign=top>Not equal to (same as '!=')
<td><code>A#B</code>

<tr>
<td align=center valign=top>==
<td valign=top>Equal to (same as '=')
<td><code>A==B</code>

<tr>
<td align=center valign=top>=
<td valign=top>Equal to (same as '==')
<td><code>A=B</code>

</table>

==== Logical Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>&&
<td valign=top>Logical AND
<td><code>A&&B</code>

<tr>
<td align=center valign=top>||
<td valign=top>Logical OR
<td><code>A||B</code>

<tr>
<td align=center valign=top>!
<td valign=top>Logical NOT
<td><code>!A</code>

</table>

==== Bitwise Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>|
<td valign=top>Bitwise OR
<td><code>A|B</code>

<tr>
<td align=center valign=top>OR
<td valign=top>Bitwise OR
<td><code>A OR B</code>

<tr>
<td align=center valign=top>&
<td valign=top>Bitwise AND
<td><code>A&B</code>

<tr>
<td align=center valign=top>AND
<td valign=top>Bitwise AND
<td><code>A AND B</code>

<tr>
<td align=center valign=top>XOR
<td valign=top>Bitwise Exclusive OR
<td><code>A XOR B</code>

<tr>
<td align=center valign=top>~
<td valign=top>One's Complement
<td><code>~A</code>

<tr>
<td align=center valign=top><<
<td valign=top>Left shift
<td><code>A<<B</code>

<tr>
<td align=center valign=top>>>
<td valign=top>Right shift
<td><code>A>>B</code>
</table>

==== Parentheses and Comma ====

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

==== Conditional Expression ====

The C language's question mark operator is supported. The format is:

<pre> <expression> ? <expression-true result> : <expression-false result></pre>

==== String Functions/Operators ====

Most two-argument string functions and binary string operators are "overloaded"
numeric functions and operators that perform string operations only if
both of their arguments/operands are strings.

<P><table border>
<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>MIN
<td valign=top>Minimum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') -> 'a'</code>

<tr>
<td align=center valign=top>MAX
<td>Maximum lexically (two-or-more-argument function)
<td><code>MAX('a','b','c') -> 'c'</code>

<tr>
<td align=center valign=top>INT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>INT('1.9') -> 1</code>
<td><code>INT('abc1.9') -> 1</code>

<tr>
<td align=center valign=top>NINT
<td>Find first number in string; return nearest integer (one-argument
function)
<td><code>NINT('1.9') -> 2</code>
<td><code>NINT('abc1.9') -> 2</code>

<tr>
<td align=center valign=top>+
<td>Concatenate (binary)
<td><code>'a'+'b' -> 'ab'</code>

<tr>
<td align=center valign=top>-
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' -> 'bca'</code>

<tr>
<td align=center valign=top>-|
<td>Delete first occurrence of substring (binary)
<td><code>'abca'-'a' -> 'bca'</code>

<tr>
<td align=center valign=top>|-
<td>Delete last occurrence of substring (binary)
<td><code>'abca'-'a' -> 'abc'</code>

<tr>
<td align=center valign=top>>=
<td>Lexically greater than or equal (binary)
<td><code>'a'>='b' -> 0</code>

<tr>
<td align=center valign=top>>
<td>Lexically greater than (binary)
<td><code>'a'>'b' -> 0</code>

<tr>
<td align=center valign=top><=
<td>Lexically less than or equal (binary)
<td><code>'a'<='b' -> 1</code>

<tr>
<td align=center valign=top><
<td>Lexically less than (binary)
<td><code>'a'<'b' -> 1</code>

<tr>
<td align=center valign=top>!=
<td>Lexically not equal to (binary)
<td><code>'a'!='b' -> 1</code>

<tr>
<td align=center valign=top>==
<td>Lexically equal to (binary)
<td><code>'a'=='b' -> 0</code>

<tr>
<td align=center valign=top>DBL
<td>Convert argument to double (one-argument function)
<td><code>DBL('1') -> 1.0</code>
<td><code>DBL('abc1.23') -> 1.23</code>

<tr>
<td align=center valign=top>STR
<td>Convert argument to string (one-argument function)
<td><code>STR(1) -> '1.00000000'</code>

<tr>
<td align=center valign=top>BYTE
<td>Convert first character of string argument to double (one-argument function)
<td><code>BYTE('abc') -> 97.0</code>

<tr>
<td align=center valign=top>PRINTF
<td valign=top>Return string constructed from format string and string or
double argument (two-argument function)  (NOTE: '$P' is a synonym for PRINTF)

<BR>Allowed format indicators: <B>%cdeEfgGiosuxX</B>
<BR>Disallowed indicators:<B> *</B>
<td><code>PRINTF("%.2f",1.23) -> '1.23'</code>

<tr>
<td align=center valign=top>SSCANF
<td>Return string or double parsed from string argument according
to format string (two-argument function) (NOTE: '$S' is a synonym for SSCANF)

<BR>Allowed format indicators: <B>%*[cdeEfgGhilosuxX</B>
<BR>Disallowed indicators: <B>$npw</B>
<td><code>SSCANF('V=1.25', "%*2c%lf") -> 1.25</code>

<tr>
<td align=center valign=top>TR_ESC
<td>Translate escape sequences into the characters they represent
(one-argument function). (NOTE: '$T' is a synonym for TR_ESC.)
<BR>TR_ESC() applies dbTranslateEscape() to its argument.
<BR>This function is approximately the opposite of ESC().
<BR>An escaped null character will terminate the result string
<td><code>TR_ESC("a\x62c") -> 'abc'</code>

<tr>
<td align=center valign=top>ESC
<td>Translate escape characters into equivalent escape sequences.
(one-argument function) (NOTE: '$E' is a synonym for ESC)
<BR>ESC() applies epicsStrSnEscaped() to its argument.
<BR>This function is approximately the opposite of TR_ESC().
<BR>The first null character found in the input string terminates it.
If there is no null chaacter, the string is assumed to be 40
characters long.
<td><code>ESC("a<return>c") -> 'a\rc'</code>

<tr>
<td align=center valign=top>[
<td>Substring
<td><code>'abcdef'[1,3] -> 'bcd'</code>
<code><BR>'abcdef'['ab','ef'] -> 'cd'</code>
<code><BR>'abcdef'[0,-1] -> 'abcdef'</code>

<tr>
<td align=center valign=top>{
<td>Substring substitution
<td><code>'abcdef'{'cd','XX'} -> 'abXXef'</code>

<tr>
<td align=center valign=top>"
<td>String indicator
<td><code>"abc"</code>

<tr>
<td align=center valign=top>'
<td>String indicator
<td><code>'abc'</code>

</table>

==== Operand-Array Operators ====

<table border>

<tr>
<th align=center valign=top>Op
<th valign=top>Description
<th valign=top>Example

<tr>
<td align=center valign=top>@
<td>Numeric array element. Regard the numeric fields A-L as an array whose elements
are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@A</code>

<tr>
<td align=center valign=top>@@
<td>String array element. Regard the string fields AA-LL as an array of strings whose
elements are numbered 0-11, and return the element whose number follows. (unary)
<td><code>@@A</code>

</table>

==== Examples ====

===== Algebraic Examples =====
A + B + 10
Result is A + B + 10

===== Relational Examples =====
(A + B) < (C + D)
Result is 1 if (A+B) < (C+D)
Result is 0 if (A+B) >= (C+D)

===== Question Mark Examples =====
(A+B)<(C+D)?E:F+L+10
Result is E if (A+B) < (C+D)
Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E
Result is E if (A+B) < (C+D)
Result is unchanged if (A+B) >= (C+D)

===== Logical Examples =====
A&B
Causes the following to occur:
* Convert A to integer
* Convert B to integer
* Perform bit-wise AND of A and B
* Convert result to floating point

===== String Examples =====
A + "abc"
A + "abc1.2"
A + AA (where AA = "abc1.2")
Result is A. The strings "abc" and "abc1.2" will be converted implicitly to the number 0.

A + DBL("abc1.2")
Result is A + 1.2. Explicit conversion to a number (by DBL, INT, or NINT) is more aggressive than implicit conversion, and skips leading non-numeric characters.

"abc" + "def"
Result is "abcdef".

PRINTF("abc%1.2f", A) (where A = 1.2345)
Result is "abc1.23".
NOTE: unlike the c-language function
printf(<format>,<arg1>,<arg2>,...),
this function accepts only one argument after the format string.

SSCANF(AA, "%*3c%lf") (where AA = "abc1.2")
Result is "1.20000000". (The format fragment "%*3c" directs sscanf to ignore three characters.)
NOTE: unlike the c-language function
sscanf(<source>,<format>,<dest1>,<dest2>,...),
this function cannot store to a variable, but only to the value stack.

BYTE("ABC")
Result is 65, the ASCII code for "A" in decimal.

"abcdef"[2,4]
Result is "cde". (The first character of the string is numbered "0".)

"abcdef"[-2,-1]
Result is "ef". (The last character of the string is numbered "-1".)

"abcdef"["ab","ef"]
Result is "cd". (If the first argument is a string, it returns the index of the first character after a successful match, or the first character in the string if no match was found. If the second argument is a string, it returns the index of the last character before a successful match, or the last character in the string if no match was found.)

A==2 ? "yes" : "no"
Result is "yes" if A == 2; otherwise, result is "no".

"abcdef"{"bcd","dcb"}
Result is "adcbef".

"abcdef"{"zzz","dcb"}
Result is "abcdef". (If no match, then no replacement.)

"abcdef"[1,-2][1,-2]
Result is "cd"

===== Array Examples =====
@0
Result in the value of the numeric variable A. ("@0" is just another name for A.)

@@0
Result in the value of the string variable AA.

@(A+B)
Result in the value of the numeric variable whose number is given by the sum of A and B.

=== Output Parameters ===

These parameters specify and control the output capabilities of the
sCalcout record. They determine when to write the output, where to write
it, and what the output will be. The OUT link specifies the Process Variable
to which the result will be written. The OOPT field determines the condition
that causes the output link to be written to. It's a menu field that has
six choices:

<P><table border>
<tr><td valign=top>
<TT>Every Time</TT><td valign=top>write output every time record is processed.

<tr><td valign=top>
<TT>On Change</TT><td valign=top>write output every time VAL changes, i.e., every
time the result of the expression changes.

<tr><td valign=top>
<TT>When Zero</TT><td valign=top>when record is processed, write output if VAL is
zero.

<tr><td valign=top>
<TT>When Non-zero</TT><td valign=top>when record is processed, write output if VAL
is non-zero.

<tr><td valign=top>
<TT>Transition to Zero</TT><td valign=top>when record is processed, write output only
if VAL is zero and last value was non-zero.

<tr><td valign=top>
<TT>Transition to Non-zero</TT><td valign=top>when record is processed, write output
only if VAL is non-zero and last value was zero.

<tr><td valign=top>
<TT>Never</TT><td valign=top>Don't write output ever.

</table>

<P> 
The DOPT field determines what data is written to the output link when
the output is executed. The field is a menu field with two options: <TT>Use
CALC</TT> or <TT>Use OCAL</TT>. If <TT>Use CALC</TT> is specified, when
the record writes its output it will write the result of the expression
in the CALC record, that is, it will write the value of the VAL [SVAL]
field to a double [string] destination. If <TT>Use OCAL</TT> is specified,
the record will instead write the result of the expression in the OCAL
field, which is contained in the OVAL field (string result in the OSV)
field. The OCAL field is exactly like the CALC field and has the same functionality:
it can contain the string representation of an expression which is evaluated
at run-time. Thus, if necessary, the record can use the result of the CALC
expression to determine if data should be written and can use the result
of the OCAL expression as the data to write.

<P> If the OEVT field specifies a non-zero integer and the condition
in the OOPT field is met, the record will post a corresponding event. If
the ODLY field is non-zero, the record pauses for the specified number
of seconds before executing the OUT link or posting the output event. During
this waiting period the record is "active" and will not be processed again
until the wait is over. The field DLYA is equal to 1 during the delay period.
The resolution of the delay entry is 1/60 of a second (it uses the VxWorks
<TT>tickLib</TT>).

<P> The IVOA field specifies what action to take with the OUT link
if the sCalcout record enters an INVALID alarm status. The options are
<TT>Continue normally</TT>, <TT>Don't drive outputs</TT>, and <TT>Set output
to IVOV</TT>. If the IVOA field is <TT>Set output to IVOV</TT>, the data
entered into the IVOV field is written to the OUT link if the record alarm
severity is INVALID.

<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>OUT</TD>
<TD>Output Specification</TD>
<TD>OUTLINK</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>N/A</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OOPT</TD>
<TD>Output Execute Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DOPT</TD>
<TD>Output Data Option</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCAL</TD>
<TD>Output Calculation</TD>
<TD>STRING[36]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OVAL</TD>
<TD>Output Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OEVT</TD>
<TD>Event To Issue</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ODLY</TD>
<TD>Output Execution Delay</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOV</TD>
<TD>Invalid Output Action</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IVOA</TD>
<TD>Invalid Output Value</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OSV</TD>
<TD>Output string value</TD>
<TD>STRING[40]</TD>
<TD>NO</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>

<TR>
<TD>WAIT</TD>
<TD>Wait for completion?</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>"NoWait"</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
</TR>
</TABLE>

<P> The sCalcout record now uses device support to write to the
<code>OUT</code> link. Soft device supplied with the record is selected with
the .dbd specification <pre> field(DTYP,"Soft Channel") </pre>

This device support uses the record's <code>WAIT</code> field to determine
whether to wait for completion of processing initiated by the <code>OUT</code>
link before causing the record to execute its forward link. The mechanism by
which this waiting for completion is performed requires that the
<code>OUT</code> link have the attribute <code>CA</code> -- i.e., the link text
looks something like

<p><code> xxx:record.field <b>CA</b> NMS</code>

<p>Currently, the record does not try to ensure that <code>WAIT</code> and
<code>OUT</code> are compatibly configured. If <code>WAIT</code> == "Wait",
but the link looks like

<p><code> xxx:record.field <b>PP</b> NMS</code>

<p>for example, then the record will not wait for completion before executing
its forward link.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.
Some are also meant to represent the status of the record at run-time.
An example of an interactive MEDM display screen that displays the status
of the sCalcout record is located here.

<P>The EGU field contains a string of up to 16 characters which is
supplied by the user and which describes the values being operated upon.
The string is retrieved whenever the routine <TT>get_units</TT> is called.
The EGU string is solely for an operator's sake and does not have to be
used.

<P>The HOPR and LOPR fields only refer to the limits of the VAL,
HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL
field.

<P>The INAV-INLV and IAAV-ILLV fields indicate the status of the
link to the PVs specified in the INPA-INPL and INAA-INLL fields, respectively.
The fields can have three possible values:

<P> 
<table border>

<tr>
<td valign=top>Ext PV NC
<td valign=top>the PV wasn't found on this IOC and a Channel Access link hasn't
been established.
</tr>

<tr>
<td valign=top>Ext PV OK
<td valign=top>the PV wasn't found on this IOC and a Channel Access link has
been established.
</tr>

<tr>
<td valign=top>Local PV
<td valign=top>the PV was found on this IOC.
</tr>

<tr>
<td valign=top>Constant
<td valign=top>the corresponding link field is a constant.
</tr>

</table>

<P>The OUTV field indicates the status of the OUT link. It has the same possible
values as the INAV-INLV fields.

<P>The CLCV and OLCV fields indicate the validity of the expression
in the CALC and OCAL fields, respectively. If the expression is invalid,
the field is set to one.

<P>The DLYA field is set to one during the delay interval specified
in ODLY.

<P>See the EPICS Record Reference Manual, for more on the record name (NAME) and
description (DESC) fields.

<P>
<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>EGU</TD>
<TD>Engineering Units</TD>
<TD>STRING [16]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>PREC</TD>
<TD>Display Precision</TD>
<TD>SHORT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>HOPR</TD>
<TD>High Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LOPR</TD>
<TD>Low Operating Range</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INAV</TD>
<TD>Link Status of INPA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>INBV</TD>
<TD>Link Status of INPB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>INLV</TD>
<TD>Link Status of INPL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OUTV</TD>
<TD>OUT PV Status</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>CLCV</TD>
<TD>CALC Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>OCLV</TD>
<TD>OCAL Valid</TD>
<TD>LONG</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DLYA</TD>
<TD>Output Delay Active</TD>
<TD>USHORT</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>NAME</TD>
<TD>Record Name</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>DESC</TD>
<TD>Description</TD>
<TD>STRING [29]</TD>
<TD>Yes</TD>
<TD>Null</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IAAV</TD>
<TD>Link Status of INAA</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>IBBV</TD>
<TD>Link Status of INBB</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>ILLV</TD>
<TD>Link Status of INLL</TD>
<TD>Menu</TD>
<TD>No</TD>
<TD>1</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the sCalcout record are the SCAN,
READ, Calculation, and limit alarms. The SCAN and READ alarms are called
by the record support routines. The Calculation alarm is called by the
record processing routine when the CALC expression is an invalid one, upon
which an error message is generated.

<P> The following alarm parameters which are configured by the user
define the limit alarms for the VAL field and the severity corresponding
to those conditions.

<P> The HYST field defines an alarm deadband for each limit. See the
EPICS Record Reference Manual for a complete explanation of alarms
and these fields.

<P>
<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>HIHI</TD>
<TD>Hihi Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HIGH</TD>
<TD>High Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOW</TD>
<TD>Low Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LOLO</TD>
<TD>Lolo Alarm Limit</TD>
<TD>FLOAT</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HHSV</TD>
<TD>Severity for a Hihi Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HSV</TD>
<TD>Severity for a High Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LSV</TD>
<TD>Severity for a Low Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>LLSV</TD>
<TD>Severity for a Lolo Alarm</TD>
<TD>Menu</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>Yes</TD>
</TR>

<TR>
<TD>HYST</TD>
<TD>Alarm Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors for the
value fields. The monitors are sent when the value field exceeds the last
monitored field by the appropriate deadband, the ADEL for archiver monitors
and the MDEL field for all other types of monitors. If these fields have
a value of zero, every time the value changes, monitors are triggered;
if they have a value of -1, every time the record is scanned, monitors
are triggered.

<TABLE BORDER >
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>ADEL</TD>
<TD>Archive Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MDEL</TD>
<TD>Monitor, i.e. value change, Deadband</TD>
<TD>DOUBLE</TD>
<TD>Yes</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

=== Run-time Parameters ===

These fields are not configurable using a configuration tool and none
are modifiable at run-time. They are used to process the record.

<P> The LALM field is used to implement the hysteresis factor for
the alarm limits.

<P> The LA-LL fields are used to decide when to trigger monitors for
the corresponding fields. For instance, if LA does not equal the value
for A, monitors for A are triggered. The MLST and MLST fields are used
in the same manner for the VAL field.

<P>
<TABLE BORDER>
<TR>
<TH>Field</TH>
<TH>Summary</TH>
<TH>Type</TH>
<TH>DCT</TH>
<TH>Initial</TH>
<TH>Access</TH>
<TH>Modify</TH>
<TH>Rec Proc Monitor</TH>
<TH>PP</TH>
</TR>

<TR>
<TD>LALM</TD>
<TD>Last Alarmed Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>ALST</TD>
<TD>Archive Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>MLST</TD>
<TD>Monitor Last Value</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LA</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LB</TD>
<TD>Previous Input Value for B</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LL</TD>
<TD>Previous Input Value for A</TD>
<TD>DOUBLE</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
<TD> </TD>
</TR>

<TR>
<TD>LAA</TD>
<TD>Previous Input Value for AA</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>LBB</TD>
<TD>Previous Input Value for BB</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

<TR>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
<TD>...</TD>
</TR>

<TR>
<TD>LLL</TD>
<TD>Previous Input Value for LL</TD>
<TD>STRING[40]</TD>
<TD>No</TD>
<TD>0</TD>
<TD>Yes</TD>
<TD>No</TD>
<TD>No</TD>
<TD>No</TD>
</TR>

</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# Call sCalcPerform(), which evaluates the expression specified in CALC and stores the result in VAL. If sCalcPerform() returns success, UDF is set to FALSE.
#Check alarms. This routine checks to see if the new VAL causes the alarm
status and severity to change. If so, NSEV, NSTA and LALM are set. It also
honors the alarm hysteresis factor (HYST). Thus the value must change by
at least HYST before the alarm status and severity changes.
# Determine if the Output Execution Option (OOPT) is met. If it is met,
either execute the output link (and output event) immediately (if ODLY
= 0), or schedule a callback to do so after the specified interval. See the
explanation for the <TT>execOutput()</TT> routine below.
# Determine what fields should be posted, and with what attributes.
## Post all fields the record has changed.
## Alarm monitors are invoked if the alarm status or severity has changed.
## Archive and value change monitors are invoked if ADEL and MDEL conditions
are met.
## NSEV and NSTA are reset to 0
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== special ====

This is called if any of the fields A-L, CALC, OCAL, INPA-INPL, INAA-INLL, or OUT are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field
is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR,
else if the field has upper and lower limits defined they will be used,
else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the
field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and
LOPR, else if the field has upper and lower limits defined they will be
used, else the upper and lower maximum values for the field type will be
used.

==== get_alarm_double ====

Sets the following values:

<P> upper_alarm_limit = HIHI

<P> upper_warning_limit = HIGH

<P> lower_warning_limit = LOW

<P> lower_alarm_limit = LOLO

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine sCalcPerform
for the postfix version of the expression in OCAL. Otherwise, use VAL.

# If the Alarm Severity is INVALID, follow the option as designated by
the field IVOA.

# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally",
call device support to write the value of OVAL to device or PV specified by
the OUT link, and post the event in OEVT (if non-zero).

# If an output delay was implemented, process the forward link.

== Availability ==

The sCalcout record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13

2006-06-07T19:56:56Z

TimMooney: Added sCalcout record

<H2 style="color:#C00000">Help Needed!</H2>

This documentation needs revising, as the software has been updated significantly since the docs were written. The [[RRM 3-13 Editing Tasks|Editing Tasks]] page gives some ideas on what needs doing to bring it up to the R3.13.10 implementation. However, '''please''' do ''not'' update any of these pages to cover the 3.14 releases of EPICS; we'll put up a separate manual for that version after the R3.13.10 documentation is up to scratch.

== EPICS 3.13 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson

* [[RRM 3-13 Copyright|Copyright]]
* [[RRM 3-13 Preface|Preface]]

* [[RRM 3-13 Concepts|Database Concepts]]
* [[RRM 3-13 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-13 Common|Fields Common to Many Record Types]]

* [[RRM 3-13 Analog Input|ai - Analog Input]]
* [[RRM 3-13 Analog Output|ao - Analog Output]]
* [[RRM 3-13 Archive|archive - Archive]]
* [[RRM 3-13 Binary Input|bi - Binary Input]]
* [[RRM 3-13 Binary Output|bo - Binary Output]]
* [[RRM 3-13 Calculation|calc - Calculation]]
* [[RRM 3-13 Calcout|calcout - Calculation Output]]
* [[RRM 3-13 Compression|compress - Compression]]
* [[RRM 3-13 CPID Control|cpid - CPID Control]]
* [[RRM 3-13 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-13 Event|event - Event]]
* [[RRM 3-13 Fanout|fanout - Fanout]]
* [[RRM 3-13 Histogram|histogram - Histogram]]
* [[RRM 3-13 Long Input|longin - Long Input]]
* [[RRM 3-13 Long Output|longout - Long Output]]
* [[RRM 3-13 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-13 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-13 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-13 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-13 Permissive|permissive - Permissive]]
* [[RRM 3-13 PID Control|pid - PID Control]]
* [[RRM 3-13 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-13 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-13 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-13 String Calcout|sCalcout - String Calculation and Output]]
* [[RRM 3-13 Scan|scan - Scan]]
* [[RRM 3-13 Select|sel - Select]]
* [[RRM 3-13 Sequence|seq - Sequence]]
* [[RRM 3-13 State|state - State]]
* [[RRM 3-13 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-13 String Input|stringin - String Input]]
* [[RRM 3-13 String Output|stringout - String Output]]
* [[RRM 3-13 SubArray|subArray - Sub-Array]]
* [[RRM 3-13 Subroutine|sub - Subroutine]]
* [[RRM 3-13 Timer|timer - Timer]]
* [[RRM 3-13 Transform|transform - Transform]]
* [[RRM 3-13 Wait|wait - Wait]]
* [[RRM 3-13 Waveform|waveform - Waveform]]

* [[RRM 3-13 Menu Choices|Appendix: Menu Choices]]

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Transform

2006-06-07T18:31:32Z

TimMooney: Replaced link to 3.14 distribution with link to 3.13. distribution

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> does not specify a PV name, then <i>expression</i> will be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

== Availability ==

The Transform record is not included with EPICS base. An EPICS 3.13-compatible version of this record is available as part of the [http://www.aps.anl.gov/aod/bcda/synApps/std/std.html std] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-07T18:20:01Z

TimMooney: Added link to the distribution web page

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> does not specify a PV name, then <i>expression</i> will be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

== Availability ==

The Transform record is not included with EPICS base. It is available
as part of the [http://www.aps.anl.gov/aod/bcda/synApps/calc/calc.html calc] module, which is part of the [http://www.aps.anl.gov/aod/bcda/synApps synApps] package of EPICS-based synchrotron-beamline software.
----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-07T17:39:21Z

TimMooney: Added Background information

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Background ==
The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

<table border = "1">
<th>field<th>expression<th>comment
<tr> <td>A <td>C-D/2 <td>position of left edge of slit
<tr> <td>B <td>C+D/2 <td>position of right edge of slit
<tr> <td>C <td>(A+B)/2 <td>position of center of slit
<tr> <td>D <td>B-A <td>width of slit
</table>

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> does not specify a PV name, then <i>expression</i> will be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-07T17:22:02Z

TimMooney: First reasonably complete version

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

INPA - link from which value for A will be read
IAV - status of INPA
A - value
CLCA - expression whose value might be written to A
CAV - validity of expression CLCA
OUTA - link to which A will be written
OAV - status of OUTA
CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a <i>put</i> from
some external agent, or as the result of input-link execution) since the last time the record processed.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> does not specify a PV name, then <i>expression</i> will be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_precision ====

Retrieves PREC.

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <b>x</b>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<b>x</b> and stores the result in <b>x</b>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 7 JUNE 2006

RRM 3-13 Transform

2006-06-07T16:50:44Z

TimMooney:

= Transform Record =

The Transform record combines features of the Calcout and Seq records, with
16 sets of the following fields:

* input link
* input-link status
* value (from input link or from calc expression)
* calc expression
* calc-expression status
* output link
* output-link status
* comment

For concreteness, here is the first set of fields:

* INPA - link from which value for A will be read
* IAV - status of INPA
* A - value
* CLCA - expression whose value might be written to A
* CAV - validity of expression CLCA
* OUTA - link to which A will be written
* OAV - status of OUTA

The value fields A-P are "process-passive", which means that writing to one of them from
a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive".
If the input link associated with a value field is not blank and is not an initialization constant, then
writes to that value field are not permitted.

Expressions are evaluated only if the associated value fields have not been modified (either by
a Put from some external agent, or as the result of input-link execution) since the last time the record processed.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters

=== Scan Parameters ===

The Transform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Transform record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>INPP<TD>Input Link P<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression Parameters ===

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix
expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which
is a member of its own (<i>inputlink</i>, <i>value</i>, <i>expression</i>, <i>outputlink</i>) group. For
each group, if <i>inputlink</i> does not specify a PV name, then <i>expression</i> will be evaluated when
the record processes, and the result will be placed in <i>value</i>.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this
manual. Instead of the standard EPICS calc engine (which does not permit an expression
to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for
transform-record expressions are the following:

* The constants PI (3.14159...), D2R (PI/180), R2D (180/PI), S2R (D2R/360), and R2S (1/S2R) are supported
* The functions MIN() and MAX() may have more than two arguments.
* The function NINT() (nearest integer) is supported.
* The function LN() (log base e) is a permitted alternative to LOGE()
* The function ATAN2() (alternative form of the arctangent function) is supported
* The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported
* The binary operators '==' (equal) and '!=' (not equal) are permitted alternatives to '=' and '#', respectively.
* The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
* The values of the variables A..P used in expressions may be the results of previously evaluated expressions.

=== Output Parameters ===

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record,
these links are not conditional; they execute every time the record processes.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUTA<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OUTB<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OUTP<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>

</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Transform record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine <CODE>get_units</CODE> is called. The EGU string is solely for an operator's sake and does not have to be used. This field is pretty much useless for the Transform record, because it's unlikely to pertain to all value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They has the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

* "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
* "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>IBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>IPV<TD>Link Status of INPP<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OAV<TD>Link Status of OUTA<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OBV<TD>Link Status of OUTB<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>OPV<TD>Link Status of OUTP<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CAV<TD>CLCA Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CBV<TD>CLCB Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TD>...<TR>
<TD>CPV<TD>CLCP Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===
The Transform record has no record-type-specific alarm fields.
See [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] for the list of alarm fields common to all record types.

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

==== process ====

See next section.

==== special ====

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed.
For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

==== get_value ====

No routine

==== get_units ====

No routine

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

No routine

==== get_control_double ====

No routine

==== get_alarm_double ====

No routine

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch values from all valid input links.
# For each value field <x>, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLC<x> and stores the result in <x>.
# Post all fields the record has changed.
# Execute all valid output links, in order from OUTA to OUTP.
# Execute the forward link, set PACT FALSE, and return.

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", put the value of OVAL to the OUT link and post the event in OEVT (if non-zero).
# If an output delay was implemented, process the forward link.

----

EPICS Record Reference Manual - 7 JUNE 2006