EPICSWIKI - User contributions [en]

RRM 3-14 Binary Output

2019-09-18T13:35:23Z

BenFranksen: /* 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, but not 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. 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>MASK<TD>Hardware Mask<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<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.

MASK is the value that RVAL receives when VAL is non-zero (unless MASK itself is zero). If VAL==0 then RVAL is set to 0, otherwise if MASK is non-zero, it is set to MASK. This field is usually given a value by the device support routines and in this case should not concern the user. However, if the DTYP is "Raw Soft Channel", then MASK can be set by the user.

<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.<TR>
<TD>MASK<TD>Raw value if VAL != 0<TR>
</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.

The RBV field is 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>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

2019-09-18T13:28:55Z

BenFranksen: /* Conversion 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, but not 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.

MASK is the value that RVAL receives when VAL is non-zero (unless MASK itself is zero). If VAL==0 then RVAL is set to 0, otherwise if MASK is non-zero, it is set to MASK. This field is usually given a value by the device support routines and in this case should not concern the user. However, if the DTYP is "Raw Soft Channel", then MASK can be set by the user.

<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.<TR>
<TD>MASK<TD>Raw value if VAL != 0<TR>
</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.

The RBV field is 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>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

2019-09-18T13:28:25Z

BenFranksen: /* Conversion 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, but not 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.

MASK is the value that RVAL receives when VAL is non-zero (unless MASK itself is zero). If VAL==0 then RVAL is set to 0, otherwise if MASK is non-zero, it is set to MASK. This field is usually given a value by the device support routines and in this case should not concern the user. However, if the DTYP is "Raw Soft Channel", then MASK can be set by the user.

<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.
<TD>MASK<TD>Raw value if VAL != 0<TR>
</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.

The RBV field is 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>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

2019-09-18T13:24:37Z

BenFranksen: /* Run-Time and Simulation Mode 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, but not 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.

The RBV field is 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>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

2019-09-18T12:45:46Z

BenFranksen: /* 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, but not 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 Long Output

2015-05-27T13:50:06Z

BenFranksen: Added missing documentation for DRVH/DRVL (mostly copied from ao)

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

= longout - Long Output =

The normal use for the long output or "longout" record type is to store long integer values of up to 32 bits and write them to hardware devices. The <CODE>Soft Channel</CODE> device support routine can also be used to write values to other records via database or channel access links. The OUT field determines how the record is used. The record supports alarm limits and graphics and control limits.

== Parameter Fields ==

The fields in this record fall into the following categories:

* scan parameters
* desired output parameters
* write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* simulation mode parameters

=== Scan Parameters ===

The longout record has the standard fields for specifying under what circumstances it 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 record must specify where the desired output originates, i.e., the 32 bit integer value it is to write. The output mode select (OMSL) field determines whether the output originates from another record or from 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 into the VAL field via dpPuts at run-time.

A third type of value for the DOL field is a constant in which case, when the record is initialized, the VAL field will be initialized with this constant value.

The VAL field's value will be clipped within limits specified in the fields DRVH and DRVL if these have been configured by the database designer:

DRVL <= VAL <= DRVH

Note: These limits are only enforced as long as DRVH > DRVL. If they are not set or DRVH <= DRVL they will not 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>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-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value Field<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Write Parameters ===

The OUT link field determines where the record is to send its output. For records that write values to hardware devices, the OUT output link field must specify the address of the I/O card, and the DTYP field must specify the name of the corresponding device support module. 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.

For soft records, the OUT output link can be a constant, a database link, or a channel access link. If the link is a constant, the result is no output. The DTYP field must then specify the <CODE>Soft Channel</CODE> device support routine.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses and 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<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 long output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the long output measures. It is retrieved by the <CODE>get_units</CODE> record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the <CODE>get_graphic_double</CODE> and <CODE>get_control_double</CODE> record support routines retrieve these fields.

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>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 long inputs are the SCAN, READ, INVALID, and limit alarms. The SCAN and READ alarms are not configurable by the user because their severity is always MAJOR. The INVALID alarm is called by the record support routine when the record or device support routines cannot write the record's output. The IVOA field specifies the action to take in this case.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. The HYST field contains the alarm deadband around each limit alarm.

See the See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. For an explanation of the IVOA and IVOV fields, see [[RRM 3-14 Common#Output Records|Output Records]]. [[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>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-14 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-14 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-14 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-14 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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<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 value field. The monitors are sent when the value field exceeds the last monitored field by the appropriate delta. 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. The ADEL field is the delta for archive monitors, and the MDEL field is the delta for all other types of monitors. See [[RRM 3-14 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 and Simulation Mode Parameters ===

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks. Only if the difference between these fields and the corresponding value field is greater than the appropriate delta (MDEL, ADEL, HYST)--only then are monitors triggered. For instance, only if the difference between VAL and MLST is greater than MDEL are the monitors triggered for VAL.

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

The following fields are used to operate the long 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 the simulation mode 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|GBLCHOICE]]<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|GBLCHOICE]]<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 its value and UDF is set to FALSE. If DOL type is a PV_LINK then dbCaAddInlink is called to create a channel access link.

If device support includes init_record, it is called.

==== process ====

See next section.

==== get_value ====

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

==== get_units ====

Retrieves EGU.

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

=== 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 and OMSL is CLOSED_LOOP recGblGetLinkValue is called to read the current value of VAL. See [[RRM 3-14 Common#Output Records|Output Records]] for more information. If the return status of recGblGetLinkValue is zero then 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 more than HYST before the alarm status and severity is lowered.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for information on how INVALID alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 long output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_longout 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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

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

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

write_longout(precord)

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

* 0: Success.
* Other: Error.

=== Device Support For Soft Records ===

The <CODE>Soft Channel</CODE> module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record.

write_longout calls recGblPutLinkValue to write the current value of VAL.

See [[RRM 3-14 Common#Soft Output|Soft Output]] for a further explanation.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Analog Output

2011-11-18T12:25:12Z

BenFranksen: /* Conversion Related Fields and the Conversion Process */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog 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 analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying 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>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<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>[[RRM 3-14 Menu Choices#aoOIF|aoOIF]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR or SLOPE for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database for records that use LINEAR conversions. They are used to calculate the values for ESLO and EOFF. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL when LINR specifies LINEAR. These values must be supplied by the user when LINR specifies SLOPE. Used only when LINR specifies LINEAR or SLOPE.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR or LINR==SLOPE, then X = (VAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = VAL, else X is obtained via breakpoint table.

: 2. X = (X - AOFF) / ASLO

: 3. RVAL = round(X) - ROFF

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the 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. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>DOUBLE<TD>Yes<TD>0<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. 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>HIHI<TD>Hihi Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<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<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, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See [[RRM 3-14 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode 2|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 ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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]] 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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF or EGUL is modified. To support LINEAR conversion, EOFF and ESLO must be set accordingly. The record support sets EOFF to EGUL before calling this routine which is a common situation when RAWL is zero below.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao 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.

RRM 3-14 Calcout

2009-02-10T13:26:15Z

BenFranksen: /* Output Parameters */

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

= Calcout - Calculation Output Record =

The Calculation Output or "Calcout" record is similar to the Calc record with the added feature of having outputs (an "output link" and an "output event") which are conditionally executed based on the result of the calculation. This feature allows conditional branching to be implemented within an EPICS database (e.g., process Record_A only if Record_B has a value of 0). The Calcout record is also similar to the Wait record (with additional features) but uses EPICS standard INLINK and OUTLINK fields rather than the DBF_STRING fields used in the Wait record. For new databases, it is recommended that the Calcout record be used instead of the Wait record.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calcout 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. Since the Calcout 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 Calcout record consist of 12 input links INPA, INPB, ... INPL. 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, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. These fields cannot be hardware addresses. In addition, the Calcout record contains the INAV, INBV, . . . INLV fields which indicate the status 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-14 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>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

Like the Calc record, the Calcout record has a CALC field in which the developer can enter an infix expression which the record routine will evaluate when it processes the record. The resulting value is placed in the VAL field. This value 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. It can also be the value that is written to the output link. The CALC expression is actually converted to opcode and stored in Reverse Polish Notation in the RPCL field. It is this expression which is actually used to calculate VAL. The Reverse Polish expression is evaluated more efficiently during run-time than an infix expression. CALC can be changed at run-time, and a special record routine will call a function to convert it to Reverse Polish Notation.

The range of expressions supported by the calculation record are separated into operands, algebraic operators, trigonometric operators, relational operators, logical operators, parentheses and commas, and the conditional '?:' operator. The expression can consist of any of these operators, as well as any of the values from the input links which are the operands.

<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>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE> Also, the RNDM unary function can be included as an operand in the expression in order to generate a random number between 0 and 1.

==== Operands ====

The expression can use the values retrieved from the INP''x'' links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L fields. The values to be used in the expression are simply referenced by the field letter. For instance, 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="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (binary function)
* MAX: Maximum (binary function)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

(condition)? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

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

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Output Parameters ===

These parameters specify and control the output capabilities of the Calcout 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:

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 field. If <CODE>Use OCAL</CODE> is specified, the record will instead write the result of the expression in the OCAL field, which is contained in the OVAL 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 system dependent.

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<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>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</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 Calcout 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.

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 fields indicate the status of the link to the PVs specified in the INPA-INPL fields, respectively. The field 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 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 [[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>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>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>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<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 possible alarm conditions for the Calc 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these 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>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>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 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 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. See [[RRM 3-14 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 ===

These fields are not configurable using a configuration too 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="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 Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</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 postfix is called to convert the infix expression in CALC and OCAL to reverse polish notation. The result is stored in RPCL and ORPC, respectively.

==== process ====

See next section.

==== special ====

This is called if CALC or OCAL is changed. special calls postfix.

==== get_value ====

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

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

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# Call routine calcPerform(), which calculates VAL from the postfix version of the expression given in CALC. If calcPerform() 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 after the specified interval. See the explanation for the <CODE>execOutput()</CODE> routine below.
# 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 ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, 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 - 19 MAY 1998

RRM 3-14 Analog Output

2008-11-21T14:07:09Z

BenFranksen: /* Run-Time Parameters and Simulation Mode Parameters */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog 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 analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying 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>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<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>[[RRM 3-14 Menu Choices#aoOIF|aoOIF]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR, then X = (OVAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = OVAL, else X is obtained via breakpoint table.

: 2. X = X * ASLO + AOFF

: 3. RVAL = round(X) - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the 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. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. 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>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-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<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<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, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See [[RRM 3-14 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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 ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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]] 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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao 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 Analog Output

2008-11-21T14:06:22Z

BenFranksen: /* Alarm Parameters */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog 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 analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying 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>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<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>[[RRM 3-14 Menu Choices#aoOIF|aoOIF]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR, then X = (OVAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = OVAL, else X is obtained via breakpoint table.

: 2. X = X * ASLO + AOFF

: 3. RVAL = round(X) - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the 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. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. 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>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-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<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<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, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See [[RRM 3-14 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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]] 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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao 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 Analog Output

2008-11-21T14:04:22Z

BenFranksen: /* Convert and Write Parameters */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog 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 analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying 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>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<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>[[RRM 3-14 Menu Choices#aoOIF|aoOIF]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR, then X = (OVAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = OVAL, else X is obtained via breakpoint table.

: 2. X = X * ASLO + AOFF

: 3. RVAL = round(X) - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the 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. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. 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>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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See [[RRM 3-14 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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]] 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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao 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 Analog Output

2008-11-21T14:03:41Z

BenFranksen: /* Desired Output Parameters */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog 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 analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying 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>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<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>[[RRM 3-14 Menu Choices#aoOIF|aoOIF]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR, then X = (OVAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = OVAL, else X is obtained via breakpoint table.

: 2. X = X * ASLO + AOFF

: 3. RVAL = round(X) - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the 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. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. 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>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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See [[RRM 3-14 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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]] 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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao 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 Analog Input

2008-11-21T14:00:25Z

BenFranksen: /* Run-Time Parameters and Simulation Mode Parameters */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the EOFF and ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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 ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Analog Input

2008-11-21T13:58:32Z

BenFranksen: /* Alarm Parameters */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the EOFF and ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Analog Input

2008-11-21T13:56:43Z

BenFranksen: /* Read and Convert Parameters */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the EOFF and ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Menu Choices

2008-11-21T13:52:43Z

BenFranksen:

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

= Menu Choices =

== Menu Fields ==

Some of the fields in EPICS records are of type menuXXX, meaning that the value of the field must be one from a menu of specific choices. There are several different menus available and each menu field uses one. Note that the value given to the record field must be the 'Choice Name' in the tables below, not the 'C Identifier'. The latter is used internally to refer to a choice from C code.

For instance, the simplest menu is called <CODE>menuYesNo</CODE> and has two possible choices, "NO" and "YES"; no other values for a field that uses <CODE>menuYesNo</CODE> are possible; e.g. "0.5", "MAYBE", and "NO WAY" are not possible choices for the field. In addition, when a menu field is configured to have a certain value, its value string must match exactly one of the possible choices in its menu, including its case. For instance, if a field's menu is <CODE>menuYesNo</CODE>, the choices "yes", "No", and "Yes" are not valid choices: they don't match the case of "NO" or "YES".

There are several menus provided as part of the standard EPICS release. Here are their names:

* seqSELM
* selSELM
* menuYesNo
* menuSimm
* menuScan
* menuPriority
* menuOmsl
* menuIvoa
* menuFtype
* menuConvert
* menuCompress
* menuAlarmStat
* menuAlarmSevr
* fanoutSELM
* compressALG
* aoOIF

A few of these menus are record-specific. For example, <CODE>aoOIF</CODE> is used solely by the OIF field in the analog output record. Most of the above menus, however, are used by many different fields in different records. For example, the <CODE>menuAlarmSevr</CODE> menu is used by the LLSV field in the analog input record as well as the COSV field in the binary input record, among others.

The above menus and their choices are provided as part of the standard EPICS release; however, developers can add to, delete, or change the choices of each, as well as add new menu types. (See the ''Application Developer's Guide'' for your release for more information on how to add and change existing menus). Thus, the database designer should know that the available menus and their choices may vary from site to site. The designer must be familiar with the menu and menu choices for any fields he/she is configuring. This isn't a problem for most database designers because such tools as VDCT, GDCT, and Capfast allow the designer configuring the database to choose from the specified choices. Nonetheless, there are ways a designer can figure out the available choices for a particular menu and thus for a particular field without using a database configuration tool.

=== Determining the Choices of a Menu Field ===

==== Peeking at the Database Definition Files ====

The definition for a particular menu can be found by looking at the database definition or <CODE>.dbd</CODE> file for that menu. For instance, the <CODE>menuAlarmSevr.dbd</CODE> file contains the definition for the <CODE>menuAlarmSevr</CODE> menu. You can see which menu a field uses by looking at the <CODE>dbCommonRecord.dbd</CODE> file if the field is common to all record types or by looking at the file that defines that record type if the field is not common to all record types. For example, to see which menu the OIF field uses, one would have to look in the <CODE>aoRecord.dbd</CODE> file which contains the definition for the analog output record, because OIF is particular to the analog output record and is not common to all other record types.

For historical reasons, some record types define choices inside the record type definition file instead of providing a separate <CODE>menuXXX.dbd</CODE> file. For example, the field OIF uses the <CODE>aoOIF</CODE> menu which is defined at the beginning of <CODE>aoRecord.dbd</CODE>. This practise is discouraged and should be avoided for new record types.

=== Standard Menu Definitions ===

Here are the definitions for the menus available as part of the standard EPICS release. The designer should know that the definitions of these menus may be different at his/her site and these are provided merely as a convenience. It's recommended that you use the <CODE>dbst</CODE> utility to view menu choices. Remember that the actual choices appear in quotes.

==== seqSELM ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>seqSELM_All<TD>"All"<TR>
<TD>seqSELM_Specified<TD>"Specified"<TR>
<TD>seqSELM_Mask<TD>"Mask"<TR>
</TABLE>

==== selSELM ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>selSELM_Specified<TD>"Specified"<TR>
<TD>selSELM_High_Signal<TD>"High Signal"<TR>
<TD>selSELM_Low_Signal<TD>"Low Signal"<TR>
<TD>selSELM_Median_Signal<TD>"Median Signal"<TR>
</TABLE>

==== menuYesNo ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuYesNoNO<TD>"NO"<TR>
<TD>menuYesNoYES<TD>"YES"<TR>
</TABLE>

==== menuSimm ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuSimmNO<TD>"NO"<TR>
<TD>menuSimmYES<TD>"YES"<TR>
<TD>menuSimmRAW<TD>"RAW"<TR>
</TABLE>

==== menuScan ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuScanPassive<TD>"Passive"<TR>
<TD>menuScanEvent<TD>"Event"<TR>
<TD>menuScanI_O_Intr<TD>"I/O Intr"<TR>
<TD>menuScan10_second<TD>"10 second"<TR>
<TD>menuScan5_second<TD>"5 second"<TR>
<TD>menuScan2_second<TD>"2 second"<TR>
<TD>menuScan1_second<TD>"1 second"<TR>
<TD>menuScan_5_second<TD>".5 second"<TR>
<TD>menuScan_2_second<TD>".2 second"<TR>
<TD>menuScan_1_second<TD>".1 second"<TR>
</TABLE>

==== menuPriority ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuPriorityLOW<TD>"LOW"<TR>
<TD>menuPriorityMEDIUM<TD>"MEDIUM"<TR>
<TD>menuPriorityHIGH<TD>"HIGH"<TR>
</TABLE>

==== menuOmsl ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuOmslsupervisory<TD>"supervisory"<TR>
<TD>menuOmslclosed_loop<TD>"closed_loop"<TR>
</TABLE>

==== menuIvoa ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuIvoaContinue_normally<TD>"Continue normally"<TR>
<TD>menuIvoaDon_t_drive_outputs<TD>"Don't drive outputs"<TR>
<TD>menuIvoaSet_output_to_IVOV<TD>"Set output to IVOV"<TR>
</TABLE>

==== menuFtype ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuFtypeSTRING<TD>"STRING"<TR>
<TD>menuFtypeCHAR<TD>"CHAR"<TR>
<TD>menuFtypeUCHAR<TD>"UCHAR"<TR>
<TD>menuFtypeSHORT<TD>"SHORT"<TR>
<TD>menuFtypeUSHORT<TD>"USHORT"<TR>
<TD>menuFtypeLONG<TD>"LONG"<TR>
<TD>menuFtypeULONG<TD>"ULONG"<TR>
<TD>menuFtypeFLOAT<TD>"FLOAT"<TR>
<TD>menuFtypeDOUBLE<TD>"DOUBLE"<TR>
<TD>menuFtypeENUM<TD>"ENUM"<TR>
</TABLE>

==== menuConvert ====

Note that menuConvert is special in that applications are expected to change it. The application must however never change the number and order of the first three choices ("NO CONVERSION","SLOPE","LINEAR"). Any choices beyond "LINEAR" are interpreted as names of breakpoint tables. EPICS comes with a default set of breakpoint tables for converting temperature units, see the table below.

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuConvertNO_CONVERSION<TD>"NO CONVERSION"<TR>
<TD>menuConvertSLOPE<TD>"SLOPE"<TR>
<TD>menuConvertLINEAR<TD>"LINEAR"<TR>
<TD>menuConverttypeKdegF<TD>"typeKdegF"<TR>
<TD>menuConverttypeKdegC<TD>"typeKdegC"<TR>
<TD>menuConverttypeJdegF<TD>"typeJdegF"<TR>
<TD>menuConverttypeJdegC<TD>"typeJdegC"<TR>
<TD>menuConverttypeEdegF<TD>"typeEdegF(ixe only)"<TR>
<TD>menuConverttypeEdegC<TD>"typeEdegC(ixe only)"<TR>
<TD>menuConverttypeTdegF<TD>"typeTdegF"<TR>
<TD>menuConverttypeTdegC<TD>"typeTdegC"<TR>
<TD>menuConverttypeRdegF<TD>"typeRdegF"<TR>
<TD>menuConverttypeRdegC<TD>"typeRdegC"<TR>
<TD>menuConverttypeSdegF<TD>"typeSdegF"<TR>
<TD>menuConverttypeSdegC<TD>"typeSdegC"<TR>
</TABLE>

==== menuCompress ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuCompressN_to_1_First_Value<TD>"N to 1 First Value"<TR>
<TD>menuCompressN_to_1_Low_Value<TD>"N to 1 Low Value"<TR>
<TD>menuCompressN_to_1_High_Value<TD>"N to 1 High Value"<TR>
<TD>menuCompressN_to_1_Average<TD>"N to 1 Average"<TR>
</TABLE>

==== menuAlarmStat ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuAlarmStat<TD>"NO_ALARM"<TR>
<TD>menuAlarmStatREAD<TD>"READ"<TR>
<TD>menuAlarmStatWRITE<TD>"WRITE"<TR>
<TD>menuAlarmStatHIHI<TD>"HIHI"<TR>
<TD>menuAlarmStatHIGH<TD>"HIGH"<TR>
<TD>menuAlarmStatLOLO<TD>"LOLO"<TR>
<TD>menuAlarmStatLOW<TD>"LOW"<TR>
<TD>menuAlarmStatSTATE<TD>"STATE"<TR>
<TD>menuAlarmStatCOS<TD>"COS"<TR>
<TD>menuAlarmStatCOMM<TD>"COMM"<TR>
<TD>menuAlarmStatTIMEOUT<TD>"TIMEOUT"<TR>
<TD>menuAlarmStatHWLIMIT<TD>"HWLIMIT"<TR>
<TD>menuAlarmStatCALC<TD>"CALC"<TR>
<TD>menuAlarmStatSCAN<TD>"SCAN"<TR>
<TD>menuAlarmStatLINK<TD>"LINK"<TR>
<TD>menuAlarmStatSOFT<TD>"SOFT"<TR>
<TD>menuAlarmStatBAD_SUB<TD>"BAD_SUB"<TR>
<TD>menuAlarmStatUDF<TD>"UDF"<TR>
<TD>menuAlarmStatDISABLE<TD>"DISABLE"<TR>
<TD>menuAlarmStatSIMM<TD>"SIMM"<TR>
<TD>menuAlarmStatREAD_ACCESS<TD>"READ_ACCESS"<TR>
<TD>menuAlarmStatWRITE_ACCESS<TD>"WRITE_ACCESS"<TR>
</TABLE>

==== menuAlarmSevr ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuAlarmSevrNO_ALARM<TD>"NO_ALARM"<TR>
<TD>menuAlarmSevrMINOR<TD>"MINOR"<TR>
<TD>menuAlarmSevrMAJOR<TD>"MAJOR"<TR>
<TD>menuAlarmSevrINVALID<TD>"INVALID"<TR>
</TABLE>

==== fanoutSELM ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>fanoutSELM_All<TD>"All"<TR>
<TD>fanoutSELM_Specified<TD>"Specified"<TR>
<TD>fanoutSELM_Mask<TD>"Mask"<TR>
</TABLE>

==== compressALG ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>compressALG_N_to_1_Low_Value<TD>"N to 1 Low Value"<TR>
<TD>compressALG_N_to_1_High_Value<TD>"N to 1 High Value"<TR>
<TD>compressALG_N_to_1_Average<TD>"N to 1 Average"<TR>
<TD>compressALG_Average<TD>"Average"<TR>
<TD>compressALG_Circular_Buffer<TD>"Circular Buffer"<TR>
</TABLE>

==== aoOIF ====

<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>aoOIF_Full<TD>"Full"<TR>
<TD>aoOIF_Incremental<TD>"Incremental"<TR>
</TABLE>

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Menu Choices

2008-11-21T13:06:12Z

BenFranksen: /* menuConvert */

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

= Menu Choices =

== GBLCHOICE and RECCHOICE Fields ==

Some of the fields in EPICS records are of type GBLCHOICE or RECCHOICE, meaning that the value of the field must be one from a menu of specific choices. There are several different menus available and each GBLCHOICE or RECCHOICE field uses one. For instance, the simplest menu is called <CODE>menuYesNo</CODE> and has two possible choices, NO and YES; no other values for a field that uses <CODE>menuYesNo</CODE> are possible--0.5, MAYBE, and NO WAY are not possible choices for the field. In addition, when a menu field is configured to have a certain value, its value string must match exactly one of the possible choices in its menu, including its case. For instance, if a field's type is GBLCHOICE and its menu is <CODE>menuYesNo</CODE>, the choices <CODE>yes</CODE>, <CODE>No</CODE>, and <CODE>Yes</CODE> are not valid choices: they don't match the case of NO or YES.

There are several menus provided as part of the standard EPICS release. Here are their names:

* seqSELM
* selSELM
* menuYesNo
* menuSimm
* menuScan
* menuPriority
* menuOmsl
* menuLinr
* menuIvoa
* menuFtype
* menuConvert
* menuCompress
* menuAlarmStat
* menuAlarmSevr
* fanoutSELM
* compressALG
* aoOIF

A few of these menus are record-specific. For example, <CODE>aoOIF</CODE> is used solely by the OIF field in the analog output record. Any field using one of these menus will be of type RECCHOICE. Most of the above menus, however, are used by many different fields in different records. These are of type GBLCHOICE. For example, the <CODE>menuAlarmSevr</CODE> menu is used by the LLSV field in the analog input record as well as the COSV field in the binary input record, among others.

The above menus and their choices are provided as part of the standard EPICS release; however, developers can add to, delete, or change the choices of each, as well as add new menu types. (See the ''Application Developer's Guide'' for your release for more information on how to add and change existing menus). Thus, the database designer should know that the available menus and their choices may vary from site to site. The designer must be familiar with the menu and menu choices for any fields he/she is configuring. This isn't a problem for most database designers because such tools as VDCT, GDCT, and Capfast allow the designer configuring the database to choose from the specified choices. Nonetheless, there are ways a designer can figure out the available choices for a particular menu and thus for a particular field without using a database configuration tool.

=== Determining the Choices of a GBLCHOICE or RECCHOICE Field ===

==== Peeking at the Database Definition Files ====

The definition for a particular menu can be found by looking at the database definition or <CODE>.dbd</CODE> file for that menu. For instance, the <CODE>menuAlarmSevr.dbd</CODE> file contains the definition for the <CODE>menuAlarmSevr</CODE> menu. In addition, you can see which menu a GBLCHOICE field uses by looking at the <CODE>dbCommonRecord.dbd</CODE> file if the field is common to all record types or by looking at the file that defines that record type if the field is not command to all record types. For example, to see which menu the OIF field uses, one would have to look in the <CODE>aoRecord.dbd</CODE> file which contains the definition for the analog output record, because OIF is particular to the analog output record and is not common to all other record types. RECCHOICE menus are defined in the definition file for the record type in which they are used, usually at the beginning. For example, the field OIF is of type RECCHOICE and uses the <CODE>aoOIF</CODE> menu which is defined at the beginning of <CODE>aoRecord.dbd</CODE>.

=== Standard Menu Definitions ===

Here are the definitions for the menus available as part of the standard EPICS release. The designer should know that the definitions of these menus may be different at his/her site and these are provided merely as a convenience. It's recommended that you use the <CODE>dbst</CODE> utility to view menu choices. Remember that the actual choices appear in quotes.

==== seqSELM ====

choice(seqSELM_All,"All")
choice(seqSELM_Specified,"Specified")
choice(seqSELM_Mask,"Mask")

==== selSELM ====

choice(selSELM_Specified,"Specified")
choice(selSELM_High_Signal,"High Signal")
choice(selSELM_Low_Signal,"Low Signal")
choice(selSELM_Median_Signal,"Median Signal")

==== menuYesNo ====

choice(menuYesNoNO,"NO")
choice(menuYesNoYES,"YES")

==== menuSimm ====

choice(menuSimmNO,"NO")
choice(menuSimmYES,"YES")
choice(menuSimmRAW,"RAW")

==== menuScan ====

choice(menuScanPassive,"Passive")
choice(menuScanEvent,"Event")
choice(menuScanI_O_Intr,"I/O Intr")
choice(menuScan10_second,"10 second")
choice(menuScan5_second,"5 second")
choice(menuScan2_second,"2 second")
choice(menuScan1_second,"1 second")
choice(menuScan_5_second,".5 second")
choice(menuScan_2_second,".2 second")
choice(menuScan_1_second,".1 second")

==== menuPriority ====

choice(menuPriorityLOW,"LOW")
choice(menuPriorityMEDIUM,"MEDIUM")
choice(menuPriorityHIGH,"HIGH")

==== menuOmsl ====

choice(menuOmslsupervisory,"supervisory")
choice(menuOmslclosed_loop,"closed_loop")

==== menuLinr ====

choice(menuLinrNO_CONVERSION,"NO CONVERSION")
choice(menuLinrLINEAR,"LINEAR")

==== menuIvoa ====

choice(menuIvoaContinue_normally,"Continue normally")
choice(menuIvoaDon_t_drive_outputs,"Don't drive outputs")
choice(menuIvoaSet_output_to_IVOV,"Set output to IVOV")

==== menuFtype ====

choice(menuFtypeSTRING,"STRING")
choice(menuFtypeCHAR,"CHAR")
choice(menuFtypeUCHAR,"UCHAR")
choice(menuFtypeSHORT,"SHORT")
choice(menuFtypeUSHORT,"USHORT")
choice(menuFtypeLONG,"LONG")
choice(menuFtypeULONG,"ULONG")
choice(menuFtypeFLOAT,"FLOAT")
choice(menuFtypeDOUBLE,"DOUBLE")
choice(menuFtypeENUM,"ENUM")

==== menuConvert ====

choice(menuConvertNO_CONVERSION,"NO CONVERSION")
choice(menuConvertSLOPE,"SLOPE")
choice(menuConvertLINEAR,"LINEAR")
choice(menuConverttypeKdegF,"typeKdegF")
choice(menuConverttypeKdegC,"typeKdegC")
choice(menuConverttypeJdegF,"typeJdegF")
choice(menuConverttypeJdegC,"typeJdegC")
choice(menuConverttypeEdegF,"typeEdegF(ixe only)")
choice(menuConverttypeEdegC,"typeEdegC(ixe only)")
choice(menuConverttypeTdegF,"typeTdegF")
choice(menuConverttypeTdegC,"typeTdegC")
choice(menuConverttypeRdegF,"typeRdegF")
choice(menuConverttypeRdegC,"typeRdegC")
choice(menuConverttypeSdegF,"typeSdegF")
choice(menuConverttypeSdegC,"typeSdegC")

==== menuCompress ====

choice(menuCompressN_to_1_First_Value,"N to 1 First Value")
choice(menuCompressN_to_1_Low_Value,"N to 1 Low Value")
choice(menuCompressN_to_1_High_Value,"N to 1 High Value")
choice(menuCompressN_to_1_Average,"N to 1 Average")

==== menuAlarmStat ====

choice(menuAlarmStat,"NO_ALARM")
choice(menuAlarmStatREAD,"READ")
choice(menuAlarmStatWRITE,"WRITE")
choice(menuAlarmStatHIHI,"HIHI")
choice(menuAlarmStatHIGH,"HIGH")
choice(menuAlarmStatLOLO,"LOLO")
choice(menuAlarmStatLOW,"LOW")
choice(menuAlarmStatSTATE,"STATE")
choice(menuAlarmStatCOS,"COS")
choice(menuAlarmStatCOMM,"COMM")
choice(menuAlarmStatTIMEOUT,"TIMEOUT")
choice(menuAlarmStatHWLIMIT,"HWLIMIT")
choice(menuAlarmStatCALC,"CALC")
choice(menuAlarmStatSCAN,"SCAN")
choice(menuAlarmStatLINK,"LINK")
choice(menuAlarmStatSOFT,"SOFT")
choice(menuAlarmStatBAD_SUB,"BAD_SUB")
choice(menuAlarmStatUDF,"UDF")
choice(menuAlarmStatDISABLE,"DISABLE")
choice(menuAlarmStatSIMM,"SIMM")
choice(menuAlarmStatREAD_ACCESS,"READ_ACCESS")
choice(menuAlarmStatWRITE_ACCESS,"WRITE_ACCESS")

==== menuAlarmSevr ====

choice(menuAlarmSevrNO_ALARM,"NO_ALARM")
choice(menuAlarmSevrMINOR,"MINOR")
choice(menuAlarmSevrMAJOR,"MAJOR")
choice(menuAlarmSevrINVALID,"INVALID")

==== fanoutSELM ====

choice(fanoutSELM_All,"All")
choice(fanoutSELM_Specified,"Specified")
choice(fanoutSELM_Mask,"Mask")

==== compressALG ====

choice(compressALG_N_to_1_Low_Value,"N to 1 Low Value")
choice(compressALG_N_to_1_High_Value,"N to 1 High Value")
choice(compressALG_N_to_1_Average,"N to 1 Average")
choice(compressALG_Average,"Average")
choice(compressALG_Circular_Buffer,"Circular Buffer")

==== aoOIF ====

choice(aoOIF_Full,"Full")
choice(aoOIF_Incremental,"Incremental")

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Binary Output

2008-11-21T13:04:06Z

BenFranksen: /* 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 (OSML) 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 either a database link or a channel access link. 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>No<TD>No<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 gets its input. 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<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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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.

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

2008-11-21T13:02:26Z

BenFranksen: /* Run-Time and Simulation Mode 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 (OSML) 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 either a database link or a channel access link. 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>No<TD>No<TD>N/A<TD>No<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<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 gets its input. 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<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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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.

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

2008-11-21T12:59:59Z

BenFranksen: /* Alarm 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 (OSML) 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 either a database link or a channel access link. 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>No<TD>No<TD>N/A<TD>No<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<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 gets its input. 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<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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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|GBLCHOICE]]<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|GBLCHOICE]]<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.

==== 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-13 Binary Output

2007-09-25T12:26:57Z

BenFranksen: /* Desired Output Parameters */

[[RRM 3-13|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-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 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 (OSML) 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 either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

[[RRM 3-13 Concepts#Address Specification|Address Specification]] presents more information on database addresses and links. [[RRM 3-13 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>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
</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 gets its input. 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-13 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-13 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-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>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-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>ZSV<TD>Zero Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>OSV<TD>One Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>COSV<TD>Change of State Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>IVOA<TD>Invalid Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<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-13 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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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-13 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<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-13 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-13 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.

==== 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-13 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-13 dbCommon

2007-09-11T09:03:58Z

BenFranksen: /* Field Description */

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

== Fields Common to All Record Types ==

=== Introduction ===

This chapter contains a description of fields that are common to all records. These fields are defined in dbcommon.dbd.

=== Scan Fields ===

These fields contain information related to how and when a record processes. For a further explanation of these record processing and these fields, see Scanning Specification, Chapter 1, 1. A few records have unique fields that also affect how they process. These fields, if any, will be listed and explained in the chapter for each record.

==== Field Summary ====

<TABLE BORDER="1">
<TR>
<TH>Field<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TH>PP<TR>
<TD>SCAN<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PINI<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PHAS<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>EVNT<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PRIO<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISV<TD>SHORT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISA<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SDIS<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>PROC<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DISS<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LSET<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LCNT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>PACT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>FLNK<TD>FWDLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SCAN<TD>Scanning Algorithm<TD>This can be one of the periodic intervals (<CODE>.1 second</CODE>, <CODE>.2 second</CODE>, <CODE>.5 second</CODE>, <CODE>1 second</CODE>, <CODE>2 second</CODE>, <CODE>5 second</CODE>, <CODE>10 second</CODE>, <CODE>I/O Intr</CODE>, <CODE>Event</CODE>, or <CODE>Passive</CODE>.<TR>
<TD>PINI<TD>Process at Initialization<TD>If this field is set to YES during database configuration, then the record is processed once at IOC initialization (before the normal scan tasks are started).<TR>
<TD>PHAS<TD>Scan Phase Number<TD>This field orders the records within a specific SCAN group. This is not meaningful for passive records. All records of a specified phase are processed before those with higher phase number. Whenever possible it is better to use linked passive records to enforce the order of processing rather than phase number.<TR>
<TD>EVNT<TD>Event Number<TD>Event number for scan type SCAN_EVENT. All records with scan type event and the same EVNT value will be processed when a call to post_event for EVNT is made. The call to post_event is: post_event(short event_number)<TR>
<TD>PRIO<TD>Priority<TD>Scheduling priority for processing I/O Event scanned records and asynchronous record completion tasks.<TR>
<TD>DISV<TD>Disable Value<TD>If DISV=DISA, then the record will be disabled, i.e. dbProcess will not process the record.<TR>
<TD>DISA<TD>Scan Disable Input Link Value<TD>This is the value that is compared with DISV to determine if the record is disabled. Its value is obtained via SDIS if SDIS is a database or channel access link. If SDIS is not a database or channel access link, then DISA can be set via dbPutField or dbPutLink.<TR>
<TD>SDIS<TD>Scan Disable Input Link<TD>An input link from which to obtain a value for DISA. This field is ignored unless it is a database link or a channel access link. If it is a database or a channel access link, dbProcess calls dbGetLink to obtain a value for DISA before deciding to call the processing routine.<TR>
<TD>PROC<TD>Process Record<TD>A record will be processed whenever a dbPutField is directed to this field.<TR>
<TD>DISS<TD>Disable Alarm Severity<TD>When this record is disabled, it will be put into alarm with this severity and a status of DISABLE_ALARM.<TR>
<TD>LSET<TD>Lock Set<TD>The lock set to which this record belongs. All records linked in any way via input, output, or forward database links belong to the same lock set. The only exception is that non-process passive input links do not force the linked record to be in the same lock set. The lock sets are determined at IOC initialization time.<TR>
<TD>LCNT<TD>Lock Count<TD>The number of times in succession dbProcess finds the record active, i.e. PACT is TRUE. If dbProcess finds the record active MAX_LOCK (currently set to 10) times in succession, it raises a SCAN_ALARM.<TR>
<TD>PACT<TD>Processing Active<TD>See Application Developers Guide for details on usage. PACT is TRUE while the record is being processed. For asynchronous records PACT can be TRUE from the time record processing is started until the asynchronous completion occurs. As long as PACT is TRUE, dbProcess will not call the record processing routine.<TR>
<TD>FLNK<TD>Forward Link<TD>This field is a database link. If FLNK is specified, processing this record will force a processing of the scan passive forward link record.</TABLE>

=== Alarm Fields ===

These fields indicate the status and severity of alarms, or else determine the how and when alarms are triggered. For a further explanation of database alarms, see Alarm Specification, Chapter 1, 4. Of course, many records have alarm-related fields not common to all records. These fields are listed and explained in the appropriate chapter on each record.

==== 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>STAT<TD>GBLCHOICE<TD>No<TD>UDF_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>SEVR<TD>GBLCHOICE<TD>No<TD>INVALID_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>NSTA<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NSEV<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ACKS<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ACKT<TD>GBLCHOICE<TD>No<TD>11<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>UDF<TD>UCHAR<TD>No<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>STAT<TD>Current Alarm Status<TD rowspan=4>These four fields are the alarm status and severity fields. STAT and SEVR are the values seen outside database access. NSTA and NSEV are the fields the database access, record support, and device support use to set new alarm status and severity values. Whenever any software component discovers an alarm condition, it uses the following macro function: recGblSetSevr(precord,new_status,new_severity) This ensures that the current alarm severity is set equal to the highest outstanding alarm. The file alarm.h defines all allowed alarm status and severity values.<TR>
<TD>SEVR<TD>Current Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>ACKS<TD>Alarm Acknowledge Severity<TD>Highest severity unacknowledged alarm<TR>
<TD>ACKT<TD>Alarm Acknowledge Transient<TD>Is it necessary to acknowledge transient alarms?<TR>
<TD>UDF<TD>VAL Undefined<TD>UDF is initialized to TRUE at IOC initialization. Record and device support routines which write to the VAL field are responsible for setting UDF to FALSE.</TABLE>

=== Device Fields ===

These fields contain information about the device and record support used by a record.

==== 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>SPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SPVT<TD>Scan Private<TD>This field is for private use of the scanning system.<TR>
<TD>RSET<TD>Address of Record Support Entry Table<TD>See Application Developers Guide for details on usage.<TR>
<TD>DSET<TD>Address of Device Support Entry Table<TD>This address of the device support entry table for this record. The value of this field is determined at IOC initialization time. Record support routines use this field to locate their device support routines.<TR>
<TD>DPVT<TD>Device Private<TD>This field is for private use of the device support modules.</TABLE>

=== Debugging Fields ===

These fields can aid in the debugging process.

==== 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>TPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>BKPT<TD>NOACCESS<TD>No<TD>1<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>TPRO<TD>Trace Processing<TD>If this field is set 1, a message is printed each time this record is processed and a message is printed for each record processed as a result of this record being processed<TR>
<TD>BKPT<TD>BreakPoint<TD>Holds a pointer to the breakpoint table specified in LINR, if any.</TABLE>

=== Miscellaneous Fields ===

These are miscellaneous fields common to all record types.

==== 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>NAME<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ASG<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSE<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSEL<TD>INLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>MLOK<TD>NOACCESS<TD>No<TD>8<TD>No<TD>No<TD>No<TD> <TR>
<TD>MLIS<TD>NOACCESS<TD>No<TD>12<TD>No<TD>No<TD>No<TD> <TR>
<TD>DISP<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>PUTF<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>RPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ASP<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPN<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPNR<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RDES<TD>NO_ACCESS<TD> <TD> <TD> <TD> <TD> <TD> <TR>
<TD>TIME<TD>NOACCESS<TD>No<TD>8<TD>Option<TD>No<TD>No<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>NAME<TD>Record Name<TD>An arbitrary 28 character record name supplied by the application developer. This name is the means of identifying a specific record. It must have a unique value across all IOCs attached to the same local area subnet.<TR>
<TD>DESC<TD>Description<TD>An arbitrary 28 character record description supplied by the application developer.<TR>
<TD>ASG<TD>Access Security Group<TD>A character string value defining the access security group for this record. If left NULL, the record is placed in group DEFAULT.<TR>
<TD>TSE<TD>Time Stamp Event<TD>The event number for time stamp. This is only meaningful if the IOC has an associated hardware event receiver. See 'er' record for details.<TR>
<TD>TSEL<TD>Time Stamp Event Link<TD>An input link for obtaining the time stamp event number.<TR>
<TD>DTYP<TD>Device Type<TD>This field specifies the device type for the record. Each record type has its own set of device support routines which are specified in devSup.ASCII. If a record type does not have any associated device support, DTYP and DSET are meaningless.<TR>
<TD>MLOK<TD>Monitor Lock<TD>The lock used by the monitor routines when the monitor list is being used. The list is locked whenever monitors are being scheduled, invoked, or when monitors are being added to or removed from the list. This field is accessed only by the dbEvent routines.<TR>
<TD>MLIS<TD>Monitor List<TD>This is the head of the list of monitors connected to this record. Each record support module is responsible for triggering monitors for any fields that change as a result of record processing. Monitors are present if mlis count is greater than zero. The call to trigger monitors is: db_post_event(precord,&data,mask), where "mask" is some combination of DBE_ALARM, DBE_VALUE, and DBE_LOG.<TR>
<TD>DISP<TD>Disable putFields<TD>If this field is set to TRUE, then all dbPutFields (normally issued by channel access) directed to this record are ignored except to the field DISP itself.<TR>
<TD>PUTF<TD>dbPutField Process<TD>Did dbPutField cause the current record processing?<TR>
<TD>RPRO<TD>Reprocess<TD>Reprocess record when current processing completes.<TR>
<TD>ASP<TD>Access Security Private<TD> <TR>
<TD>PPN<TD>Address of putNotify<TD>Address of putNotify callback.<TR>
<TD>PPNR<TD>Next Record for putNotify<TD>Next record for PutNotify.<TR>
<TD>RDES<TD>Address of dbRecordType<TD> <TR>
<TD>TIME<TD>Time<TD>The time when this record was last processed, in standard format.</TABLE>

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 dbCommon

2007-06-21T10:44:46Z

BenFranksen: /* Field Description */

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

== Fields Common to All Record Types ==

=== Introduction ===

This chapter contains a description of fields that are common to all records. These fields are defined in dbcommon.dbd.

=== Scan Fields ===

These fields contain information related to how and when a record processes. For a further explanation of these record processing and these fields, see Scanning Specification, Chapter 1, 1. A few records have unique fields that also affect how they process. These fields, if any, will be listed and explained in the chapter for each record.

==== Field Summary ====

<TABLE BORDER="1">
<TR>
<TH>Field<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TH>PP<TR>
<TD>SCAN<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PINI<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PHAS<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>EVNT<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PRIO<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISV<TD>SHORT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISA<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SDIS<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>PROC<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DISS<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LSET<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LCNT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>PACT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>FLNK<TD>FWDLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SCAN<TD>Scanning Algorithm<TD>This can be one of the periodic intervals (<CODE>.1 second</CODE>, <CODE>.2 second</CODE>, <CODE>.5 second</CODE>, <CODE>1 second</CODE>, <CODE>2 second</CODE>, <CODE>5 second</CODE>, <CODE>10 second</CODE>, <CODE>I/O Intr</CODE>, <CODE>Event</CODE>, or <CODE>Passive</CODE>.<TR>
<TD>PINI<TD>Process at Initialization<TD>If this field is set to YES during database configuration, then the record is processed once at IOC initialization (before the normal scan tasks are started).<TR>
<TD>PHAS<TD>Scan Phase Number<TD>This field orders the records within a specific SCAN group. This is not meaningful for passive records. All records of a specified phase are processed before those with higher phase number. Whenever possible it is better to use linked passive records to enforce the order of processing rather than phase number.<TR>
<TD>EVNT<TD>Event Number<TD>Event number for scan type SCAN_EVENT. All records with scan type event and the same EVNT value will be processed when a call to post_event for EVNT is made. The call to post_event is: post_event(short event_number)<TR>
<TD>PRIO<TD>Priority<TD>Scheduling priority for processing I/O Event scanned records and asynchronous record completion tasks.<TR>
<TD>DISV<TD>Disable Value<TD>If DISV=DISA, then the record will be disabled, i.e. dbProcess will not process the record.<TR>
<TD>DISA<TD>Scan Disable Input Link Value<TD>This is the value that is compared with DISV to determine if the record is disabled. Its value is obtained via SDIS if SDIS is a database or channel access link. If SDIS is not a database or channel access link, then DISA can be set via dbPutField or dbPutLink.<TR>
<TD>SDIS<TD>Scan Disable Input Link<TD>An input link from which to obtain a value for DISA. This field is ignored unless it is a database link or a channel access link. If it is a database or a channel access link, dbProcess calls dbGetLink to obtain a value for DISA before deciding to call the processing routine.<TR>
<TD>PROC<TD>Process Record<TD>A record will be processed whenever a dbPutField is directed to this field.<TR>
<TD>DISS<TD>Disable Alarm Severity<TD>When this record is disabled, it will be put into alarm with this severity and a status of DISABLE_ALARM.<TR>
<TD>LSET<TD>Lock Set<TD>The lock set to which this record belongs. All records linked in any way via input, output, or forward database links belong to the same lock set. The only exception is that non-process passive input links do not force the linked record to be in the same lock set. The lock sets are determined at IOC initialization time.<TR>
<TD>LCNT<TD>Lock Count<TD>The number of times in succession dbProcess finds the record active, i.e. PACT is TRUE. If dbProcess finds the record active MAX_LOCK (currently set to 10) times in succession, it raises a SCAN_ALARM.<TR>
<TD>PACT<TD>Processing Active<TD>See Application Developers Guide for details on usage. PACT is TRUE while the record is being processed. For asynchronous records PACT can be TRUE from the time record processing is started until the asynchronous completion occurs. As long as PACT is TRUE, dbProcess will not call the record processing routine.<TR>
<TD>FLNK<TD>Forward Link<TD>This field is a database link. If FLNK is specified, processing this record will force a processing of the scan passive forward link record.</TABLE>

=== Alarm Fields ===

These fields indicate the status and severity of alarms, or else determine the how and when alarms are triggered. For a further explanation of database alarms, see Alarm Specification, Chapter 1, 4. Of course, many records have alarm-related fields not common to all records. These fields are listed and explained in the appropriate chapter on each record.

==== 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>STAT<TD>GBLCHOICE<TD>No<TD>UDF_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>SEVR<TD>GBLCHOICE<TD>No<TD>INVALID_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>NSTA<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NSEV<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ACKS<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ACKT<TD>GBLCHOICE<TD>No<TD>11<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>UDF<TD>UCHAR<TD>No<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>STAT<TD>Current Alarm Status<TD rowspan=4>These four fields are the alarm status and severity fields. STAT and SEVR are the values seen outside database access. NSTA and NSEV are the fields the database access, record support, and device support use to set new alarm status and severity values. Whenever any software component discovers an alarm condition, it uses the following macro function: recGblSetSevr(precord,new_status,new_severity) This ensures that the current alarm severity is set equal to the highest outstanding alarm. The file alarm.h defines all allowed alarm status and severity values.<TR>
<TD>SEVR<TD>Current Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>ACKS<TD>Alarm Acknowledge Severity<TD>Highest severity unacknowledged alarm<TR>
<TD>ACKT<TD>Alarm Acknowledge Transient<TD>Is it necessary to acknowledge transient alarms?<TR>
<TD>UDF<TD>VAL Undefined<TD>UDF is initialized to TRUE at IOC initialization. Record and device support routines which write to the VAL field are responsible for setting UDF to FALSE.</TABLE>

=== Device Fields ===

These fields contain information about the device and record support used by a record.

==== 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>SPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SPVT<TD>Scan Private<TD>This field is for private use of the scanning system.<TR>
<TD>RSET<TD>Address of Record Support Entry Table<TD>See Application Developers Guide for details on usage.<TR>
<TD>DSET<TD>Address of Device Support Entry Table<TD>This address of the device support entry table for this record. The value of this field is determined at IOC initialization time. Record support routines use this field to locate their device support routines.<TR>
<TD>DPVT<TD>Device Private<TD>This field is for private use of the device support modules.</TABLE>

=== Debugging Fields ===

These fields can aid in the debugging process.

==== 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>TPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>BKPT<TD>NOACCESS<TD>No<TD>1<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>TPRO<TD>Trace Processing<TD>If this field is set TRUE, a message is printed each time this record is processed and a message is printed for each record processed as a result of this record being processed<TR>
<TD>BKPT<TD>BreakPoint<TD>Holds a pointer to the breakpoint table specified in LINR, if any.</TABLE>

=== Miscellaneous Fields ===

These are miscellaneous fields common to all record types.

==== 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>NAME<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ASG<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSE<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSEL<TD>INLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>MLOK<TD>NOACCESS<TD>No<TD>8<TD>No<TD>No<TD>No<TD> <TR>
<TD>MLIS<TD>NOACCESS<TD>No<TD>12<TD>No<TD>No<TD>No<TD> <TR>
<TD>DISP<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>PUTF<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>RPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ASP<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPN<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPNR<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RDES<TD>NO_ACCESS<TD> <TD> <TD> <TD> <TD> <TD> <TR>
<TD>TIME<TD>NOACCESS<TD>No<TD>8<TD>Option<TD>No<TD>No<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>NAME<TD>Record Name<TD>An arbitrary 28 character record name supplied by the application developer. This name is the means of identifying a specific record. It must have a unique value across all IOCs attached to the same local area subnet.<TR>
<TD>DESC<TD>Description<TD>An arbitrary 28 character record description supplied by the application developer.<TR>
<TD>ASG<TD>Access Security Group<TD>A character string value defining the access security group for this record. If left NULL, the record is placed in group DEFAULT.<TR>
<TD>TSE<TD>Time Stamp Event<TD>The event number for time stamp. This is only meaningful if the IOC has an associated hardware event receiver. See 'er' record for details.<TR>
<TD>TSEL<TD>Time Stamp Event Link<TD>An input link for obtaining the time stamp event number.<TR>
<TD>DTYP<TD>Device Type<TD>This field specifies the device type for the record. Each record type has its own set of device support routines which are specified in devSup.ASCII. If a record type does not have any associated device support, DTYP and DSET are meaningless.<TR>
<TD>MLOK<TD>Monitor Lock<TD>The lock used by the monitor routines when the monitor list is being used. The list is locked whenever monitors are being scheduled, invoked, or when monitors are being added to or removed from the list. This field is accessed only by the dbEvent routines.<TR>
<TD>MLIS<TD>Monitor List<TD>This is the head of the list of monitors connected to this record. Each record support module is responsible for triggering monitors for any fields that change as a result of record processing. Monitors are present if mlis count is greater than zero. The call to trigger monitors is: db_post_event(precord,&data,mask), where "mask" is some combination of DBE_ALARM, DBE_VALUE, and DBE_LOG.<TR>
<TD>DISP<TD>Disable putFields<TD>If this field is set to TRUE, then all dbPutFields (normally issued by channel access) directed to this record are ignored except to the field DISP itself.<TR>
<TD>PUTF<TD>dbPutField Process<TD>Did dbPutField cause the current record processing?<TR>
<TD>RPRO<TD>Reprocess<TD>Reprocess record when current processing completes.<TR>
<TD>ASP<TD>Access Security Private<TD> <TR>
<TD>PPN<TD>Address of putNotify<TD>Address of putNotify callback.<TR>
<TD>PPNR<TD>Next Record for putNotify<TD>Next record for PutNotify.<TR>
<TD>RDES<TD>Address of dbRecordType<TD> <TR>
<TD>TIME<TD>Time<TD>The time when this record was last processed, in standard format.</TABLE>

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Common

2007-06-21T10:43:22Z

BenFranksen: /* Common Fields */

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

== Fields Common to Many Record Types ==

=== Introduction ===

This chapter describes input and output fields that are common to multiple record types. These fields have the same meaning whenever they are used.

=== Input Records ===

==== Common Fields ====

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to obtain input. For soft analog records it can be a constant, a database link, or a channel access link.<TR>
<TD>DTYP<TD>Device Type<TD>DTYP specifies the name of the device support module that will input values. Each record type has its own set of device support routines. If a record type does not have any associated device support, DTYP is meaningless.<TR>
<TD>RVAL<TD>Raw Value<TD>Whenever possible this field contains the raw data value exactly as it is obtained from the hardware or from the associated device driver and before it undergoes any conversions. The <CODE>Soft Channel</CODE> device support module reads values directly into VAL, bypassing this field.<TR>
<TD>VAL<TD>Value<TD>This is the record's final value, after any needed conversions have been performed.<TR>
<TD>SIMM<TD>Simulation Mode<TD>This field has either the value YES or NO. By setting this field to YES, the record can be switched into simulation mode of operation. While in simulation mode, input will be obtained from SIOL instead of INP.<TR>
<TD>SIML<TD>Simulation Mode Location<TD>This field can be a constant, a database link, or a channel access link. If SIML is a database or channel access link, then SIMM is read from SIML. If SIML is a constant link then SIMM is initialized with the constant value but can be changed via dbPuts.<TR>
<TD>SVAL<TD>Simulation Value<TD>This is the record's input value, in engineering units, when the record is switched into simulation mode, i.e. when SIMM is set to YES.<TR>
<TD>SIOL<TD>Simulation Value Location<TD>This field can be a constant, a database link, or a channel access link. If SIOL is a database or channel access link, then SVAL is read from SIOL. If SIOL is a constant link then SVAL is initialized with the constant value but can be changed via dbPuts.<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>When this record is in simulation mode, it will be put into alarm with this severity and a status of SIMM.
</TABLE>

==== Device Input ====

A device input routine normally returns one of the following values to its associated record support routine:

* 0: Success and convert. The input value is in RVAL. The record support module is expected to compute VAL from RVAL.
* 2: Success, but don't convert. The device support module can specify this value if it does not want any conversions. It might do this for two reasons:
** A hardware error is detected (in this case, it should also raise an alarm condition).
** The device support routine reads values directly into the VAL field and then sets UDF to FALSE.

==== Soft Input ====

In almost all cases, two special device support modules are provided: Soft Channel and Raw Soft Channel. Both allow INP to be a constant, a database link, or a channel access link. The Soft Channel device support module reads input directly into the VAL field and specifies that no conversion of any type should be performed. Thus, it allows the record to hold values corresponding to the C data type of the VAL field. Note that for soft input, RVAL is not used. The Raw Soft Channel support module reads input into RVAL and asks that any specified conversions be performed.

The device support read routine normally calls recGblGetLinkValue() which performs the following steps:

* If the INP link type is CONSTANT recGblGetLinkValue() does nothing and returns with a status of zero.
* If the INP link type is DB_LINK, then dbGetLink() is called to obtain a new input value. If dbGetLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised. RecGblGetLinkValue() returns the status returned by dbGetLink().
* If the INP link type is CA_LINK, then dbCaGetLink() is called to obtain a new input value. If dbCaGetLink() returns an error, a LINK alarm with a severity of INVALID is raised. RecGblGetLinkValue() returns the status of dbCaGetLink().

If the return status of recGblGetLinkValue() is zero and the INP link type is not CONSTANT, then UDF is set to FALSE. The device support read routine normally returns the status of recGblGetLinkValue.

==== Simulation Mode ====

A record can be switched into simulation mode of operation by setting the value of SIMM to YES. During simulation, the record will be put into alarm with a severity of SIMS and a status of SIMM_ALARM. While in simulation mode, input values, in engineering units, will be obtained from SIOL instead of INP. Also, while the record is in simulation mode, there will be no raw value conversion and no calls to device support when the record is processed.

Normally input records contain a private readValue() routine which performs the following steps:

* If PACT is TRUE, the device support read routine is called, status is set to its return code, and readValue returns.
* Call recGblGetLinkValue() to get a new value for SIMM if SIML is a DB_LINK or a CA_LINK.
* Check value of SIMM.
* If SIMM is NO, then call the device support read routine, set status to its return code, and return.
* If SIMM is YES, then call recGblGetLinkValue to read the input value from SIOL into SVAL. If success, then set VAL to SVAL and UDF to FALSE and set status to 2 (don't convert) if input record supports conversion. If SIMS is greater than zero, set alarm status to SIMM and severity to SIMS. Set status to the return code from recGblGetLinkValue and return.
* IF SIMM is not YES or NO, a SOFT alarm with a severity of INVALID is raised, and return status is set to -1.

=== Output Records ===

==== Common Fields ====

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to decide where to send output. For soft records, it can be a constant, a database link, or a channel access link. If the link is a constant, the result is no output.<TR>
<TD>DTYP<TD>Device Type<TD>DTYP specifies the name of the device support module that will receive values. Each record type has its own set of device support routines. If a record type does not have any associated device support, DTYP is meaningless.<TR>
<TD>VAL<TD>Value<TD>This is the desired value before any conversions to raw output have been performed.<TR>
<TD>OVAL<TD>Output Value<TD>OVAL is used to decide when to invoke monitors. Archive and value change monitors are invoked if OVAL is not equal to VAL. If a record type needs to make adjustments, OVAL is used to enforce the maximum rate of change limit before converting the desired value to a raw value.<TR>
<TD>RVAL<TD>Raw Value<TD>Whenever possible this is the actual value sent to the hardware itself or to the associated device driver.<TR>
<TD>RBV<TD>Read Back Value<TD>Whenever possible this is the actual read back value obtained from the hardware itself or from the associated device driver.<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>DOL can be a constant, a database link, or a channel access link. There is no device support associated with DOL. If DOL is a database or channel access link and OMSL is closed_loop, then VAL is obtained from DOL.<TR>
<TD>OMSL<TD>Output Mode Select<TD>This field has either the value "supervisory" or "closed_loop". DOL is used to determine VAL only if OMSL has the value "closed_loop". By setting this field the record can be switched between supervisory and closed loop mode of operation. While in closed loop mode, the VAL field cannot be set via dbPuts.<TR>
<TD>OIF<TD>Output Full or Incremental (analog output record only)<TD>This field, which is only used when input is obtained from DOL, determines if the value obtained from DOL is an increment to add to the current VAL or is the actual VAL desired.<TR>
<TD>SIMM<TD>Simulation Mode<TD>This field has either the value YES or NO. By setting this field to YES, the record can be switched into simulation mode of operation. While in simulation mode, output will be written to SIOL instead of OUT.<TR>
<TD>SIML<TD>Simulation Mode Location<TD>This field can be a constant, a database link, or a channel access link. If SIML is a database or channel access link, then SIMM is read from SIML. If SIML is a constant link then SIMM is initialized with the constant value but can be changed via dbPuts.<TR>
<TD>SIOL<TD>Simulation Value Location<TD>This field can be a constant, a database link, or a channel access link. If SIOL is a database or channel access link, then the output value is written to SIOL. If this link is a constant, the result is no output.<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>When this record is in simulation mode, it will be put into alarm with this severity and a status of SIMM_ALARM.<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>Whenever the record is put into INVALID alarm severity IVOA specifies an action. IVOA can be one of the following actions: Continue normally, Don't drive outputs, Set output equal to IVOV<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, In Engineering Units<TD>When new severity has been set to INVALID alarm and IVOA is "Set output equal to IVOV", then, VAL is set to IVOV and converted to RVAL before device support is called.
</TABLE>

==== Soft Output ====

Normally two soft output device support modules are provided Soft and Raw Soft. Both allow the output link OUT to be a constant, a database link, or a channel access link. It is normally meaningless to use constant output links. The Soft support module writes output from the value associated with OVAL or VAL (if OVAL does not exist). The Raw Soft Channel support module writes the value associated with the RVAL field after conversion has been performed.

The device support write routine normally calls recGblPutLinkValue which performs the following steps:

* If the OUT link type is CONSTANT recGblPutLinkValue does nothing and returns with a status of zero.
* If the OUT link type is DB_LINK, then dbPutLink is called to write the current value. If dbPutLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised. RecGblPutLinkValue returns the status of dbPutLink.
* If the OUT link type is CA_LINK, then dbCaPutLink is called to write the current value. If dbCaPutLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised. RecGblPutLinkValue returns the status of dbCaPutLink.

The device support write routine normally returns the status of recGblPutLinkValue.

==== Output Mode Select ====

The fields DOL and OMSL are used to allow the output record to be part of a closed loop control algorithm. OMSL is meaningful only if DOL refers to a database or channel access link. It can have the values SUPERVISORY or CLOSED_LOOP. If the mode is SUPERVISORY, then nothing is done to VAL. If the mode is CLOSED_LOOP and the record type does not contain an OIF field, then each time the record is processed, VAL is set equal to the value obtained from the location referenced by DOL. If the mode is CLOSED_LOOP in record types with an OIF field and OIF is Full, VAL is set equal to the value obtained from the location referenced by DOL; if OIF is Incremental VAL is incremented by the value obtained from DOL.

==== Simulation Mode ====

An output record can be switched into simulation mode of operation by setting the value of SIMM to YES. During simulation, the record will be put into alarm with a severity of SIMS and a status of SIMM_ALARM. While in simulation mode, output values, in engineering units, will be written to SIOL instead of OUT. However, the output values are never converted.

-- (SIMM = FALSE?) INP -> RVAL --(maybe convert) -> VAL
/
SIML -> SIMM
\
-- (SIMM = TRUE?) SIOL -> SVAL --(never convert) -> RVAL

Also, while the record is in simulation mode, there will be no calls to device support during record processing.

Normally output records contain a private writeValue() routine which performs the following steps:

* If PACT is TRUE, the device support write routine is called, status is set to its return code, and readValue returns.
* Call recGblGetLinkValue to get a new value for SIMM if SIML is a DB_LINK or a CA_LINK.
* Check value of SIMM.
* If SIMM is NO, then call the device support write routine, set status to its return code, and return.
* If SIMM is YES, then call recGblPutLinkValue to write the output value from VAL or OVAL to SIOL. Set alarm status to SIMM and severity to SIMS, if SIMS is greater than zero. Set status to the return code from recGblPutLinkValue and return.
* If SIMM not one of the above, a SOFT alarm with a severity of INVALID is raised, and return status is set to -1.

==== Invalid Alarm Output Action ====

Whenever an output record is put into INVALID alarm severity, IVOA specifies an action to take. The record support process routine for each output record contains code which performs the following steps.

* If new severity is less than INVALID, then call writeValue:
* Else do the following:
** If IVOA is CONTINUE, then call writeValue.
** If IVOA is NO_OUTPUT, then do not write output.
** If IVOA is OUTPUT_IVOV, then set VAL to IVOV, call convert if necessary, and then call writeValue.
** If IVOA not one of the above, an error message is generated.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Calcout

2006-03-09T13:02:17Z

BenFranksen: /* Output Parameters */

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

= Calcout - Calculation Output Record =

The Calculation Output or "Calcout" record is similar to the Calc record with the added feature of having outputs (an "output link" and an "output event") which are conditionally executed based on the result of the calculation. This feature allows conditional branching to be implemented within an EPICS database (e.g., process Record_A only if Record_B has a value of 0). The Calcout record is also similar to the Wait record (with additional features) but uses EPICS standard INLINK and OUTLINK fields rather than the DBF_STRING fields used in the Wait record. For new databases, it is recommended that the Calcout record be used instead of the Wait record.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* output parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calcout 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 Calcout 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 Calcout record consist of 12 input links INPA, INPB, ... INPL. 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, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. These fields cannot be hardware addresses. In addition, the Calcout record contains the INAV, INBV, . . . INLV fields which indicate the status 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>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

Like the Calc record, the Calcout record has a CALC field in which the developer can enter an infix expression which the record routine will evaluate when it processes the record. The resulting value is placed in the VAL field. This value 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. It can also be the value that is written to the output link. The CALC expression is actually converted to opcode and stored in Reverse Polish Notation in the RPCL field. It is this expression which is actually used to calculate VAL. The Reverse Polish expression is evaluated more efficiently during run-time than an infix expression. CALC can be changed at run-time, and a special record routine will call a function to convert it to Reverse Polish Notation.

The range of expressions supported by the calculation record are separated into operands, algebraic operators, trigonometric operators, relational operators, logical operators, parentheses and commas, and the conditional '?:' operator. The expression can consist of any of these operators, as well as any of the values from the input links which are the operands.

<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>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE> Also, the RNDM unary function can be included as an operand in the expression in order to generate a random number between 0 and 1.

==== Operands ====

The expression can use the values retrieved from the INP''x'' links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L fields. The values to be used in the expression are simply referenced by the field letter. For instance, 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="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (binary function)
* MAX: Maximum (binary function)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

(condition)? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

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

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Output Parameters ===

These parameters specify and control the output capabilities of the Calcout 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:

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 field. If <CODE>Use OCAL</CODE> is specified, the record will instead write the result of the expression in the OCAL field, which is contained in the OVAL 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 <CODE>tickLib</CODE>).

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<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>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-13 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-13 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Action<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</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 Calcout 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.

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 fields indicate the status of the link to the PVs specified in the INPA-INPL fields, respectively. The field 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 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 [[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>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>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<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 possible alarm conditions for the Calc 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 [[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>Severity for a Hihi Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<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 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. 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 ===

These fields are not configurable using a configuration too 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="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 Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</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 postfix is called to convert the infix expression in CALC and OCAL to reverse polish notation. The result is stored in RPCL and ORPC, respectively.

==== process ====

See next section.

==== special ====

This is called if CALC or OCAL is changed. special calls postfix.

==== get_value ====

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

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

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# Call routine calcPerform(), which calculates VAL from the postfix version of the expression given in CALC. If calcPerform() 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 after the specified interval. See the explanation for the <CODE>execOutput()</CODE> routine below.
# 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 ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, 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 - 19 MAY 1998

RRM 3-13 Analog Output

2006-02-20T12:05:13Z

BenFranksen: /* Conversion Related Fields and the Conversion Process */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR, then X = (OVAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = OVAL, else X is obtained via breakpoint table.

: 2. X = X * ASLO + AOFF

: 3. RVAL = round(X) - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 Analog Output

2006-02-20T12:04:42Z

BenFranksen: /* Conversion Related Fields and the Conversion Process */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR, then X = (OVAL - EOFF) / ESLO, else if LINR=NO_CONVERSION, then X = OVAL, else X is obtained via breakpoint table.

: 2. X = X * ASLO + AOFF

: 3. RVAL = round(X) - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 dbCommon

2006-02-13T10:54:17Z

BenFranksen: /* Field Description */

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

== Fields Common to All Record Types ==

=== Introduction ===

This chapter contains a description of fields that are common to all records. These fields are defined in dbcommon.dbd.

=== Scan Fields ===

These fields contain information related to how and when a record processes. For a further explanation of these record processing and these fields, see Scanning Specification, Chapter 1, 1. A few records have unique fields that also affect how they process. These fields, if any, will be listed and explained in the chapter for each record.

==== Field Summary ====

<TABLE BORDER="1">
<TR>
<TH>Field<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TH>PP<TR>
<TD>SCAN<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PINI<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PHAS<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>EVNT<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PRIO<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISV<TD>SHORT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISA<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SDIS<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>PROC<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DISS<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LSET<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LCNT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>PACT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>FLNK<TD>FWDLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SCAN<TD>Scanning Algorithm<TD>This can be one of the periodic intervals (<CODE>.1 second</CODE>, <CODE>.2 second</CODE>, <CODE>.5 second</CODE>, <CODE>1 second</CODE>, <CODE>2 second</CODE>, <CODE>5 second</CODE>, <CODE>10 second</CODE>, <CODE>I/O Intr</CODE>, <CODE>Event</CODE>, or <CODE>Passive</CODE>.<TR>
<TD>PINI<TD>Process at Initialization<TD>If this field is set to TRUE during database configuration, then the record is processed once at IOC initialization (before the normal scan tasks are started).<TR>
<TD>PHAS<TD>Scan Phase Number<TD>This field orders the records within a specific SCAN group. This is not meaningful for passive records. All records of a specified phase are processed before those with higher phase number. Whenever possible it is better to use linked passive records to enforce the order of processing rather than phase number.<TR>
<TD>EVNT<TD>Event Number<TD>Event number for scan type SCAN_EVENT. All records with scan type event and the same EVNT value will be processed when a call to post_event for EVNT is made. The call to post_event is: post_event(short event_number)<TR>
<TD>PRIO<TD>Priority<TD>Scheduling priority for processing I/O Event scanned records and asynchronous record completion tasks.<TR>
<TD>DISV<TD>Disable Value<TD>If DISV=DISA, then the record will be disabled, i.e. dbProcess will not process the record.<TR>
<TD>DISA<TD>Scan Disable Input Link Value<TD>This is the value that is compared with DISV to determine if the record is disabled. Its value is obtained via SDIS if SDIS is a database or channel access link. If SDIS is not a database or channel access link, then DISA can be set via dbPutField or dbPutLink.<TR>
<TD>SDIS<TD>Scan Disable Input Link<TD>An input link from which to obtain a value for DISA. This field is ignored unless it is a database link or a channel access link. If it is a database or a channel access link, dbProcess calls dbGetLink to obtain a value for DISA before deciding to call the processing routine.<TR>
<TD>PROC<TD>Process Record<TD>A record will be processed whenever a dbPutField is directed to this field.<TR>
<TD>DISS<TD>Disable Alarm Severity<TD>When this record is disabled, it will be put into alarm with this severity and a status of DISABLE_ALARM.<TR>
<TD>LSET<TD>Lock Set<TD>The lock set to which this record belongs. All records linked in any way via input, output, or forward database links belong to the same lock set. The only exception is that non-process passive input links do not force the linked record to be in the same lock set. The lock sets are determined at IOC initialization time.<TR>
<TD>LCNT<TD>Lock Count<TD>The number of times in succession dbProcess finds the record active, i.e. PACT is TRUE. If dbProcess finds the record active MAX_LOCK (currently set to 10) times in succession, it raises a SCAN_ALARM.<TR>
<TD>PACT<TD>Processing Active<TD>See Application Developers Guide for details on usage. PACT is TRUE while the record is being processed. For asynchronous records PACT can be TRUE from the time record processing is started until the asynchronous completion occurs. As long as PACT is TRUE, dbProcess will not call the record processing routine.<TR>
<TD>FLNK<TD>Forward Link<TD>This field is a database link. If FLNK is specified, processing this record will force a processing of the scan passive forward link record.</TABLE>

=== Alarm Fields ===

These fields indicate the status and severity of alarms, or else determine the how and when alarms are triggered. For a further explanation of database alarms, see Alarm Specification, Chapter 1, 4. Of course, many records have alarm-related fields not common to all records. These fields are listed and explained in the appropriate chapter on each record.

==== 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>STAT<TD>GBLCHOICE<TD>No<TD>UDF_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>SEVR<TD>GBLCHOICE<TD>No<TD>INVALID_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>NSTA<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NSEV<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ACKS<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ACKT<TD>GBLCHOICE<TD>No<TD>11<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>UDF<TD>UCHAR<TD>No<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>STAT<TD>Current Alarm Status<TD rowspan=4>These four fields are the alarm status and severity fields. STAT and SEVR are the values seen outside database access. NSTA and NSEV are the fields the database access, record support, and device support use to set new alarm status and severity values. Whenever any software component discovers an alarm condition, it uses the following macro function: recGblSetSevr(precord,new_status,new_severity) This ensures that the current alarm severity is set equal to the highest outstanding alarm. The file alarm.h defines all allowed alarm status and severity values.<TR>
<TD>SEVR<TD>Current Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>ACKS<TD>Alarm Acknowledge Severity<TD>Highest severity unacknowledged alarm<TR>
<TD>ACKT<TD>Alarm Acknowledge Transient<TD>Is it necessary to acknowledge transient alarms?<TR>
<TD>UDF<TD>VAL Undefined<TD>UDF is initialized to TRUE at IOC initialization. Record and device support routines which write to the VAL field are responsible for setting UDF to FALSE.</TABLE>

=== Device Fields ===

These fields contain information about the device and record support used by a record.

==== 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>SPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SPVT<TD>Scan Private<TD>This field is for private use of the scanning system.<TR>
<TD>RSET<TD>Address of Record Support Entry Table<TD>See Application Developers Guide for details on usage.<TR>
<TD>DSET<TD>Address of Device Support Entry Table<TD>This address of the device support entry table for this record. The value of this field is determined at IOC initialization time. Record support routines use this field to locate their device support routines.<TR>
<TD>DPVT<TD>Device Private<TD>This field is for private use of the device support modules.</TABLE>

=== Debugging Fields ===

These fields can aid in the debugging process.

==== 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>TPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>BKPT<TD>NOACCESS<TD>No<TD>1<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>TPRO<TD>Trace Processing<TD>If this field is set TRUE, a message is printed each time this record is processed and a message is printed for each record processed as a result of this record being processed<TR>
<TD>BKPT<TD>BreakPoint<TD>Holds a pointer to the breakpoint table specified in LINR, if any.</TABLE>

=== Miscellaneous Fields ===

These are miscellaneous fields common to all record types.

==== 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>NAME<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ASG<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSE<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSEL<TD>INLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>MLOK<TD>NOACCESS<TD>No<TD>8<TD>No<TD>No<TD>No<TD> <TR>
<TD>MLIS<TD>NOACCESS<TD>No<TD>12<TD>No<TD>No<TD>No<TD> <TR>
<TD>DISP<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>PUTF<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>RPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ASP<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPN<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPNR<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RDES<TD>NO_ACCESS<TD> <TD> <TD> <TD> <TD> <TD> <TR>
<TD>TIME<TD>NOACCESS<TD>No<TD>8<TD>Option<TD>No<TD>No<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>NAME<TD>Record Name<TD>An arbitrary 28 character record name supplied by the application developer. This name is the means of identifying a specific record. It must have a unique value across all IOCs attached to the same local area subnet.<TR>
<TD>DESC<TD>Description<TD>An arbitrary 28 character record description supplied by the application developer.<TR>
<TD>ASG<TD>Access Security Group<TD>A character string value defining the access security group for this record. If left NULL, the record is placed in group DEFAULT.<TR>
<TD>TSE<TD>Time Stamp Event<TD>The event number for time stamp. This is only meaningful if the IOC has an associated hardware event receiver. See 'er' record for details.<TR>
<TD>TSEL<TD>Time Stamp Event Link<TD>An input link for obtaining the time stamp event number.<TR>
<TD>DTYP<TD>Device Type<TD>This field specifies the device type for the record. Each record type has its own set of device support routines which are specified in devSup.ASCII. If a record type does not have any associated device support, DTYP and DSET are meaningless.<TR>
<TD>MLOK<TD>Monitor Lock<TD>The lock used by the monitor routines when the monitor list is being used. The list is locked whenever monitors are being scheduled, invoked, or when monitors are being added to or removed from the list. This field is accessed only by the dbEvent routines.<TR>
<TD>MLIS<TD>Monitor List<TD>This is the head of the list of monitors connected to this record. Each record support module is responsible for triggering monitors for any fields that change as a result of record processing. Monitors are present if mlis count is greater than zero. The call to trigger monitors is: db_post_event(precord,&data,mask), where "mask" is some combination of DBE_ALARM, DBE_VALUE, and DBE_LOG.<TR>
<TD>DISP<TD>Disable putFields<TD>If this field is set to TRUE, then all dbPutFields (normally issued by channel access) directed to this record are ignored except to the field DISP itself.<TR>
<TD>PUTF<TD>dbPutField Process<TD>Did dbPutField cause the current record processing?<TR>
<TD>RPRO<TD>Reprocess<TD>Reprocess record when current processing completes.<TR>
<TD>ASP<TD>Access Security Private<TD> <TR>
<TD>PPN<TD>Address of putNotify<TD>Address of putNotify callback.<TR>
<TD>PPNR<TD>Next Record for putNotify<TD>Next record for PutNotify.<TR>
<TD>RDES<TD>Address of dbRecordType<TD> <TR>
<TD>TIME<TD>Time<TD>The time when this record was last processed, in standard format.</TABLE>

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 dbCommon

2006-02-13T10:52:35Z

BenFranksen: /* Field Summary */

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

== Fields Common to All Record Types ==

=== Introduction ===

This chapter contains a description of fields that are common to all records. These fields are defined in dbcommon.dbd.

=== Scan Fields ===

These fields contain information related to how and when a record processes. For a further explanation of these record processing and these fields, see Scanning Specification, Chapter 1, 1. A few records have unique fields that also affect how they process. These fields, if any, will be listed and explained in the chapter for each record.

==== Field Summary ====

<TABLE BORDER="1">
<TR>
<TH>Field<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TH>PP<TR>
<TD>SCAN<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PINI<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PHAS<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>EVNT<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PRIO<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISV<TD>SHORT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISA<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SDIS<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>PROC<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DISS<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LSET<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LCNT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>PACT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>FLNK<TD>FWDLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SCAN<TD>Scanning Algorithm<TD>This can be one of the periodic intervals (<CODE>.1 second</CODE>, <CODE>.2 second</CODE>, <CODE>.5 second</CODE>, <CODE>1 second</CODE>, <CODE>2 second</CODE>, <CODE>5 second</CODE>, <CODE>10 second</CODE>, <CODE>I/O Intr</CODE>, <CODE>Event</CODE>, or <CODE>Passive</CODE>.<TR>
<TD>PINI<TD>Process at Initialization<TD>If this field is set to TRUE during database configuration, then the record is processed once at IOC initialization (before the normal scan tasks are started).<TR>
<TD>PHAS<TD>Scan Phase Number<TD>This field orders the records within a specific SCAN group. This is not meaningful for passive records. All records of a specified phase are processed before those with higher phase number. Whenever possible it is better to use linked passive records to enforce the order of processing rather than phase number.<TR>
<TD>EVNT<TD>Event Number<TD>Event number for scan type SCAN_EVENT. All records with scan type event and the same EVNT value will be processed when a call to post_event for EVNT is made. The call to post_event is: post_event(short event_number)<TR>
<TD>PRIO<TD>Priority<TD>Scheduling priority for processing I/O Event scanned records and asynchronous record completion tasks.<TR>
<TD>DISV<TD>Disable Value<TD>If DISV=DISA, then the record will be disabled, i.e. dbProcess will not process the record.<TR>
<TD>DISA<TD>Scan Disable Input Link Value<TD>This is the value that is compared with DISV to determine if the record is disabled. Its value is obtained via SDIS if SDIS is a database or channel access link. If SDIS is not a database or channel access link, then DISA can be set via dbPutField or dbPutLink.<TR>
<TD>SDIS<TD>Scan Disable Input Link<TD>An input link from which to obtain a value for DISA. This field is ignored unless it is a database link or a channel access link. If it is a database or a channel access link, dbProcess calls dbGetLink to obtain a value for DISA before deciding to call the processing routine.<TR>
<TD>PROC<TD>Process Record<TD>A record will be processed whenever a dbPutField is directed to this field.<TR>
<TD>DISS<TD>Disable Alarm Severity<TD>When this record is disabled, it will be put into alarm with this severity and a status of DISABLE_ALARM.<TR>
<TD>LSET<TD>Lock Set<TD>The lock set to which this record belongs. All records linked in any way via input, output, or forward database links belong to the same lock set. The only exception is that non-process passive input links do not force the linked record to be in the same lock set. The lock sets are determined at IOC initialization time.<TR>
<TD>LCNT<TD>Lock Count<TD>The number of times in succession dbProcess finds the record active, i.e. PACT is TRUE. If dbProcess finds the record active MAX_LOCK (currently set to 10) times in succession, it raises a SCAN_ALARM.<TR>
<TD>PACT<TD>Processing Active<TD>See Application Developers Guide for details on usage. PACT is TRUE while the record is being processed. For asynchronous records PACT can be TRUE from the time record processing is started until the asynchronous completion occurs. As long as PACT is TRUE, dbProcess will not call the record processing routine.<TR>
<TD>FLNK<TD>Forward Link<TD>This field is a database link. If FLNK is specified, processing this record will force a processing of the scan passive forward link record.</TABLE>

=== Alarm Fields ===

These fields indicate the status and severity of alarms, or else determine the how and when alarms are triggered. For a further explanation of database alarms, see Alarm Specification, Chapter 1, 4. Of course, many records have alarm-related fields not common to all records. These fields are listed and explained in the appropriate chapter on each record.

==== 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>STAT<TD>GBLCHOICE<TD>No<TD>UDF_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>SEVR<TD>GBLCHOICE<TD>No<TD>INVALID_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>NSTA<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NSEV<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ACKS<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ACKT<TD>GBLCHOICE<TD>No<TD>11<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>UDF<TD>UCHAR<TD>No<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>STAT<TD>Current Alarm Status<TD rowspan=4>These four fields are the alarm status and severity fields. STAT and SEVR are the values seen outside database access. NSTA and NSEV are the fields the database access, record support, and device support use to set new alarm status and severity values. Whenever any software component discovers an alarm condition, it uses the following macro function: recGblSetSevr(precord,new_status,new_severity) This ensures that the current alarm severity is set equal to the highest outstanding alarm. The file alarm.h defines all allowed alarm status and severity values.<TR>
<TD>SEVR<TD>Current Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>ACKS<TD>Alarm Acknowledge Severity<TD>Highest severity unacknowledged alarm<TR>
<TD>ACKT<TD>Alarm Acknowledge Transient<TD>Is it necessary to acknowledge transient alarms?<TR>
<TD>UDF<TD>VAL Undefined<TD>UDF is initialized to TRUE at IOC initialization. Record and device support routines which write to the VAL field are responsible for setting UDF to FALSE.</TABLE>

=== Device Fields ===

These fields contain information about the device and record support used by a record.

==== 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>SPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SPVT<TD>Scan Private<TD>This field is for private use of the scanning system.<TR>
<TD>RSET<TD>Address of Record Support Entry Table<TD>See Application Developers Guide for details on usage.<TR>
<TD>DSET<TD>Address of Device Support Entry Table<TD>This address of the device support entry table for this record. The value of this field is determined at IOC initialization time. Record support routines use this field to locate their device support routines.<TR>
<TD>DPVT<TD>Device Private<TD>This field is for private use of the device support modules.</TABLE>

=== Debugging Fields ===

These fields can aid in the debugging process.

==== 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>TPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>BKPT<TD>NOACCESS<TD>No<TD>1<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>TPRO<TD>Trace Processing<TD>If this field is set TRUE, a message is printed each time this record is processed and a message is printed for each record processed as a result of this record being processed<TR>
<TD>BKPT<TD>BreakPoint<TD>Holds a pointer to the breakpoint table specified in LINR, if any.</TABLE>

=== Miscellaneous Fields ===

These are miscellaneous fields common to all record types.

==== 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>NAME<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ASG<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSE<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSEL<TD>INLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>MLOK<TD>NOACCESS<TD>No<TD>8<TD>No<TD>No<TD>No<TD> <TR>
<TD>MLIS<TD>NOACCESS<TD>No<TD>12<TD>No<TD>No<TD>No<TD> <TR>
<TD>DISP<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>PUTF<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>RPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ASP<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPN<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPNR<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RDES<TD>NO_ACCESS<TD> <TD> <TD> <TD> <TD> <TD> <TR>
<TD>TIME<TD>NOACCESS<TD>No<TD>8<TD>Option<TD>No<TD>No<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>NAME<TD>Record Name<TD>An arbitrary 28 character record name supplied by the application developer. This name is the means of identifying a specific record. It must have a unique value across all IOCs attached to the same local area subnet.<TR>
<TD>DESC<TD>Description<TD>An arbitrary 28 character record description supplied by the application developer.<TR>
<TD>ASG<TD>Access Security Group<TD>A character string value defining the access security group for this record. If left NULL, the record is placed in group DEFAULT.<TR>
<TD>TSE<TD>Time Stamp Event<TD>The event number for time stamp. This is only meaningful if the IOC has an associated hardware event receiver. See 'er' record for details.<TR>
<TD>TSEL<TD>Time Stamp Event Link<TD>An input link for obtaining the time stamp event number.<TR>
<TD>DTYP<TD>Device Type<TD>This field specifies the device type for the record. Each record type has its own set of device support routines which are specified in devSup.ASCII. If a record type does not have any associated device support, DTYP and DSET are meaningless.<TR>
<TD>MLOK<TD>Monitor Lock<TD>The lock used by the monitor routines when the monitor list is being used. The list is locked whenever monitors are being scheduled, invoked, or when monitors are being added to or removed from the list. This field is accessed only by the dbEvent routines.<TR>
<TD>MLIS<TD>Monitor List<TD>This is the head of the list of monitors connected to this record. Each record support module is responsible for triggering monitors for any fields that change as a result of record processing. Monitors are present if mlis count is greater than zero. The call to trigger monitors is: db_post_event(precord,&data,mask), where "mask" is some combination of DBE_ALARM, DBE_VALUE, and DBE_LOG.<TR>
<TD>DISP<TD>Disable putFields<TD>If this field is set to TRUE, then all dbPutFields (normally issued by channel access) directed to this record are ignored except to the field DISP itself.<TR>
<TD>PUTF<TD>dbPutField Process<TD>Did dbPutField cause the current record processing?<TR>
<TD>RPRO<TD>Reprocess<TD>Reprocess record when current processing completes.<TR>
<TD>ASP<TD>Access Security Private<TD> <TR>
<TD>PPN<TD>Address of putNotify<TD>Address of putNotify callback.<TR>
<TD>PPNN<TD>Next Record for putNotify<TD>Next record for PutNotify.<TR>
<TD>RDES<TD>Address of dbRecordType<TD> <TR>
<TD>TIME<TD>Time<TD>The time when this record was last processed, in standard format.</TABLE>

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 dbCommon

2006-02-13T10:36:14Z

BenFranksen: /* Field Summary */

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

== Fields Common to All Record Types ==

=== Introduction ===

This chapter contains a description of fields that are common to all records. These fields are defined in dbcommon.dbd.

=== Scan Fields ===

These fields contain information related to how and when a record processes. For a further explanation of these record processing and these fields, see Scanning Specification, Chapter 1, 1. A few records have unique fields that also affect how they process. These fields, if any, will be listed and explained in the chapter for each record.

==== Field Summary ====

<TABLE BORDER="1">
<TR>
<TH>Field<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor
<TH>PP<TR>
<TD>SCAN<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PINI<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PHAS<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>EVNT<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PRIO<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISV<TD>SHORT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DISA<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SDIS<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>PROC<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DISS<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LSET<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LCNT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>PACT<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>FLNK<TD>FWDLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SCAN<TD>Scanning Algorithm<TD>This can be one of the periodic intervals (<CODE>.1 second</CODE>, <CODE>.2 second</CODE>, <CODE>.5 second</CODE>, <CODE>1 second</CODE>, <CODE>2 second</CODE>, <CODE>5 second</CODE>, <CODE>10 second</CODE>, <CODE>I/O Intr</CODE>, <CODE>Event</CODE>, or <CODE>Passive</CODE>.<TR>
<TD>PINI<TD>Process at Initialization<TD>If this field is set to TRUE during database configuration, then the record is processed once at IOC initialization (before the normal scan tasks are started).<TR>
<TD>PHAS<TD>Scan Phase Number<TD>This field orders the records within a specific SCAN group. This is not meaningful for passive records. All records of a specified phase are processed before those with higher phase number. Whenever possible it is better to use linked passive records to enforce the order of processing rather than phase number.<TR>
<TD>EVNT<TD>Event Number<TD>Event number for scan type SCAN_EVENT. All records with scan type event and the same EVNT value will be processed when a call to post_event for EVNT is made. The call to post_event is: post_event(short event_number)<TR>
<TD>PRIO<TD>Priority<TD>Scheduling priority for processing I/O Event scanned records and asynchronous record completion tasks.<TR>
<TD>DISV<TD>Disable Value<TD>If DISV=DISA, then the record will be disabled, i.e. dbProcess will not process the record.<TR>
<TD>DISA<TD>Scan Disable Input Link Value<TD>This is the value that is compared with DISV to determine if the record is disabled. Its value is obtained via SDIS if SDIS is a database or channel access link. If SDIS is not a database or channel access link, then DISA can be set via dbPutField or dbPutLink.<TR>
<TD>SDIS<TD>Scan Disable Input Link<TD>An input link from which to obtain a value for DISA. This field is ignored unless it is a database link or a channel access link. If it is a database or a channel access link, dbProcess calls dbGetLink to obtain a value for DISA before deciding to call the processing routine.<TR>
<TD>PROC<TD>Process Record<TD>A record will be processed whenever a dbPutField is directed to this field.<TR>
<TD>DISS<TD>Disable Alarm Severity<TD>When this record is disabled, it will be put into alarm with this severity and a status of DISABLE_ALARM.<TR>
<TD>LSET<TD>Lock Set<TD>The lock set to which this record belongs. All records linked in any way via input, output, or forward database links belong to the same lock set. The only exception is that non-process passive input links do not force the linked record to be in the same lock set. The lock sets are determined at IOC initialization time.<TR>
<TD>LCNT<TD>Lock Count<TD>The number of times in succession dbProcess finds the record active, i.e. PACT is TRUE. If dbProcess finds the record active MAX_LOCK (currently set to 10) times in succession, it raises a SCAN_ALARM.<TR>
<TD>PACT<TD>Processing Active<TD>See Application Developers Guide for details on usage. PACT is TRUE while the record is being processed. For asynchronous records PACT can be TRUE from the time record processing is started until the asynchronous completion occurs. As long as PACT is TRUE, dbProcess will not call the record processing routine.<TR>
<TD>FLNK<TD>Forward Link<TD>This field is a database link. If FLNK is specified, processing this record will force a processing of the scan passive forward link record.</TABLE>

=== Alarm Fields ===

These fields indicate the status and severity of alarms, or else determine the how and when alarms are triggered. For a further explanation of database alarms, see Alarm Specification, Chapter 1, 4. Of course, many records have alarm-related fields not common to all records. These fields are listed and explained in the appropriate chapter on each record.

==== 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>STAT<TD>GBLCHOICE<TD>No<TD>UDF_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>SEVR<TD>GBLCHOICE<TD>No<TD>INVALID_ALARM<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>NSTA<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NSEV<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ACKS<TD>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ACKT<TD>GBLCHOICE<TD>No<TD>11<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>UDF<TD>UCHAR<TD>No<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>STAT<TD>Current Alarm Status<TD rowspan=4>These four fields are the alarm status and severity fields. STAT and SEVR are the values seen outside database access. NSTA and NSEV are the fields the database access, record support, and device support use to set new alarm status and severity values. Whenever any software component discovers an alarm condition, it uses the following macro function: recGblSetSevr(precord,new_status,new_severity) This ensures that the current alarm severity is set equal to the highest outstanding alarm. The file alarm.h defines all allowed alarm status and severity values.<TR>
<TD>SEVR<TD>Current Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>ACKS<TD>Alarm Acknowledge Severity<TD>Highest severity unacknowledged alarm<TR>
<TD>ACKT<TD>Alarm Acknowledge Transient<TD>Is it necessary to acknowledge transient alarms?<TR>
<TD>UDF<TD>VAL Undefined<TD>UDF is initialized to TRUE at IOC initialization. Record and device support routines which write to the VAL field are responsible for setting UDF to FALSE.</TABLE>

=== Device Fields ===

These fields contain information about the device and record support used by a record.

==== 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>SPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DSET<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>DPVT<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>SPVT<TD>Scan Private<TD>This field is for private use of the scanning system.<TR>
<TD>RSET<TD>Address of Record Support Entry Table<TD>See Application Developers Guide for details on usage.<TR>
<TD>DSET<TD>Address of Device Support Entry Table<TD>This address of the device support entry table for this record. The value of this field is determined at IOC initialization time. Record support routines use this field to locate their device support routines.<TR>
<TD>DPVT<TD>Device Private<TD>This field is for private use of the device support modules.</TABLE>

=== Debugging Fields ===

These fields can aid in the debugging process.

==== 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>TPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>BKPT<TD>NOACCESS<TD>No<TD>1<TD>No<TD>No<TD>No<TD> </TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>TPRO<TD>Trace Processing<TD>If this field is set TRUE, a message is printed each time this record is processed and a message is printed for each record processed as a result of this record being processed<TR>
<TD>BKPT<TD>BreakPoint<TD>Holds a pointer to the breakpoint table specified in LINR, if any.</TABLE>

=== Miscellaneous Fields ===

These are miscellaneous fields common to all record types.

==== 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>NAME<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ASG<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSE<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD> <TR>
<TD>TSEL<TD>INLINK<TD>Yes<TD>Null<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>MLOK<TD>NOACCESS<TD>No<TD>8<TD>No<TD>No<TD>No<TD> <TR>
<TD>MLIS<TD>NOACCESS<TD>No<TD>12<TD>No<TD>No<TD>No<TD> <TR>
<TD>DISP<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>PUTF<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>RPRO<TD>UCHAR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ASP<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPN<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>PPNN<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>RDES<TD>NO_ACCESS<TD> <TD> <TD> <TD> <TD> <TD> <TR>
<TD>TIME<TD>NOACCESS<TD>No<TD>8<TD>Option<TD>No<TD>No<TD>No</TABLE>

==== Field Description ====

<TABLE BORDER="1"><TH>Name<TH>Summary<TH>Description<TR>
<TD>NAME<TD>Record Name<TD>An arbitrary 28 character record name supplied by the application developer. This name is the means of identifying a specific record. It must have a unique value across all IOCs attached to the same local area subnet.<TR>
<TD>DESC<TD>Description<TD>An arbitrary 28 character record description supplied by the application developer.<TR>
<TD>ASG<TD>Access Security Group<TD>A character string value defining the access security group for this record. If left NULL, the record is placed in group DEFAULT.<TR>
<TD>TSE<TD>Time Stamp Event<TD>The event number for time stamp. This is only meaningful if the IOC has an associated hardware event receiver. See 'er' record for details.<TR>
<TD>TSEL<TD>Time Stamp Event Link<TD>An input link for obtaining the time stamp event number.<TR>
<TD>DTYP<TD>Device Type<TD>This field specifies the device type for the record. Each record type has its own set of device support routines which are specified in devSup.ASCII. If a record type does not have any associated device support, DTYP and DSET are meaningless.<TR>
<TD>MLOK<TD>Monitor Lock<TD>The lock used by the monitor routines when the monitor list is being used. The list is locked whenever monitors are being scheduled, invoked, or when monitors are being added to or removed from the list. This field is accessed only by the dbEvent routines.<TR>
<TD>MLIS<TD>Monitor List<TD>This is the head of the list of monitors connected to this record. Each record support module is responsible for triggering monitors for any fields that change as a result of record processing. Monitors are present if mlis count is greater than zero. The call to trigger monitors is: db_post_event(precord,&data,mask), where "mask" is some combination of DBE_ALARM, DBE_VALUE, and DBE_LOG.<TR>
<TD>DISP<TD>Disable putFields<TD>If this field is set to TRUE, then all dbPutFields (normally issued by channel access) directed to this record are ignored except to the field DISP itself.<TR>
<TD>PUTF<TD>dbPutField Process<TD>Did dbPutField cause the current record processing?<TR>
<TD>RPRO<TD>Reprocess<TD>Reprocess record when current processing completes.<TR>
<TD>ASP<TD>Access Security Private<TD> <TR>
<TD>PPN<TD>Address of putNotify<TD>Address of putNotify callback.<TR>
<TD>PPNN<TD>Next Record for putNotify<TD>Next record for PutNotify.<TR>
<TD>RDES<TD>Address of dbRecordType<TD> <TR>
<TD>TIME<TD>Time<TD>The time when this record was last processed, in standard format.</TABLE>

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Data Fanout

2006-01-23T14:24:26Z

BenFranksen: /* Alarm Parameters */

[[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.

<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 Analog Output

2006-01-12T14:15:31Z

BenFranksen: /* special_linconv */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

: 1. RVAL = round( OVAL - EOFF / ESLO )

: 2. RVAL = RVAL * ASLO + AOFF

If the conversion is via a breakpoint table, the new value is obtained.

: 3. RVAL = RVAL - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 Analog Output

2006-01-12T14:14:12Z

BenFranksen: /* init_record */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

: 1. RVAL = round( OVAL - EOFF / ESLO )

: 2. RVAL = RVAL * ASLO + AOFF

If the conversion is via a breakpoint table, the new value is obtained.

: 3. RVAL = RVAL - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 Analog Output

2006-01-12T14:11:51Z

BenFranksen: /* Fields Of Interest To Device Support */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

: 1. RVAL = round( OVAL - EOFF / ESLO )

: 2. RVAL = RVAL * ASLO + AOFF

If the conversion is via a breakpoint table, the new value is obtained.

: 3. RVAL = RVAL - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert.

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 Analog Output

2006-01-12T14:09:07Z

BenFranksen: /* Record Processing */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

: 1. RVAL = round( OVAL - EOFF / ESLO )

: 2. RVAL = RVAL * ASLO + AOFF

If the conversion is via a breakpoint table, the new value is obtained.

: 3. RVAL = RVAL - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>ROFF<TD>Raw Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert.

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 Analog Output

2006-01-12T13:55:53Z

BenFranksen: /* init_record */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

: 1. RVAL = round( OVAL - EOFF / ESLO )

: 2. RVAL = RVAL * ASLO + AOFF

If the conversion is via a breakpoint table, the new value is obtained.

: 3. RVAL = RVAL - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EGUL)/ESLO -ROFF
#** For break point table conversion a call is made to cvtEngToRawBpt.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>ROFF<TD>Raw Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert.

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 Analog Output

2006-01-12T13:47:59Z

BenFranksen: /* Convert and Write Parameters */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

: 1. RVAL = round( OVAL - EOFF / ESLO )

: 2. RVAL = RVAL * ASLO + AOFF

If the conversion is via a breakpoint table, the new value is obtained.

: 3. RVAL = RVAL - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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 device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized If linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = (RVAL+ROFF) / ESLO + EGUL

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EGUL)/ESLO -ROFF
#** For break point table conversion a call is made to cvtEngToRawBpt.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>ROFF<TD>Raw Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert.

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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-13 Analog Input

2006-01-12T13:43:41Z

BenFranksen: /* Read and Convert Parameters */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the EOFF and ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. 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 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-13 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-13 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-13 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-13 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Analog Input

2006-01-12T13:42:46Z

BenFranksen: /* Raw Soft Channel */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the EOFF and ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. 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 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-13 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-13 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-13 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-13 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Analog Input

2006-01-12T13:41:57Z

BenFranksen: /* Soft Channel */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the EOFF and ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. 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 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-13 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-13 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-13 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-13 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and ROFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Analog Input

2006-01-12T13:40:56Z

BenFranksen: /* Read and Convert Parameters */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the EOFF and ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. 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 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-13 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-13 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-13 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-13 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and ROFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Analog Input

2006-01-12T13:37:15Z

BenFranksen: /* special_linconv */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. 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 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-13 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-13 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-13 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-13 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and ROFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Analog Input

2006-01-12T13:26:13Z

BenFranksen: /* Fields Of Interest To Device Support */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. 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 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-13 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-13 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-13 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-13 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and ROFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Analog Input

2006-01-12T13:23:17Z

BenFranksen: /* Conversion Related Fields */

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

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<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>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO

Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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 state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. 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 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>LOLO<TD>Lolo 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>HHSV<TD>Hihi Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>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 appropriate deadband. 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. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. 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 analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-13 Common#Simulation Mode|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV. which is invoked whenever any of the fields LINR, EGUF, EGUL or ROFF is changed.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-13 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), 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 more than HYST before the alarm status and severity is lowered.
# 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 ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

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

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai 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=5>See [[RRM 3-13 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>ROFF<TD>Raw Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</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.

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

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-13 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and ROFF always have their default values of 1 and 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Analog Output

2006-01-12T13:17:13Z

BenFranksen: /* Conversion Related Fields and the Conversion Process */

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

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

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

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output 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. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which can has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL<=VAL<=DRVH

Note: If nothing is entered for DRVH and DRVL, the output value will never change.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-13 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>OMSL<TD>Output Mode Select<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>RECCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO 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>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>CVTCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>FLOAT<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database. They are used to calculate the value ESLO, and are thus only significant for records that use linear conversions. See [[RRM 3-13 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL. Used if LINR specifies LINEAR.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
</TABLE>

: 1. RVAL = round( OVAL - EOFF / ESLO )

: 2. RVAL = RVAL * ASLO + AOFF

If the conversion is via a breakpoint table, the new value is obtained.

: 3. RVAL = RVAL - ROFF

Since RVAL is now defined, the last step is to set UDF to FALSE.

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-13 dbCommon#Miscellaneous Fields|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>PREC<TD>Display Precision<TD>SHORT<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>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 possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV 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>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>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<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. 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 processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. 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 analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field 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.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<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>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<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<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-13 Common#Simulation Mode 2|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>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<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>GBLCHOICE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>GBLCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double 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. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

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 device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized If linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = (RVAL+ROFF) / ESLO + EGUL

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

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

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== 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 set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EGUL)/ESLO -ROFF
#** For break point table conversion a call is made to cvtEngToRawBpt.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y 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 is reduced.
# Check severity and write the new value. See [[RRM 3-13 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# 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 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 ADEL and MDEL conditions are met.
#* 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 and INIT FALSE, and return.

== Device Support ==

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

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao 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-13 dbCommon|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>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>ROFF<TD>Raw Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== 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 returns a zero for success or a 2 for success, don't convert.

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

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF, EGUL or ROFF is modified.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel 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 OVAL.

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_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-13 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

V4 CA Protocol Specification

2005-10-30T09:39:35Z

BenFranksen: /* Design Notes */

= EPICS Channel Access Protocol Specification =

EPICS Version: 4

Channel Access Protocol Version: 4.15

Author: Jeff Hill

LA-UR-05-8238

== Data Types ==

* All multi-octet primitive types are transmitted in little endian byte order.
* All signed integers use two's complement arithmetic.
* All floating point numbers shall comply with IEEE floating point standards.

{| border="1"
|+ Externally Visible Data Types
! Mnemonic
! Data Type
! Identifier
|-
|
| reserved
| 0
|-
| INT8
| 8 bit signed integer
| 1
|-
| INT16
| 16 bit signed integer
| 2
|-
| INT32
| 32 bit signed integer
| 3
|-
| INT64
| 64 bit signed integer
| 4
|-
| FLOAT32
| 32 bit IEEE floating point
| 5
|-
| FLOAT64
| 64 bit IEEE floating point
| 6
|-
| FLOAT128
| 128 bit IEEE floating point
| 7
|-
|
[[#STRING.2C_UTF-8_Encoded_Character_String|STRING]]
| UTF-8 encoded character string
| 8
|-
|
[[#PSD.2C_Property_Sequence_Description|PSD]]
| property sequence description
| 9
|-
|
| reserved
| 10 - 128
|}

{| border="1"
|+ Protocol Private Data Types
! Mnemonic
! Data Type
|-
| UINT8
| 8 bit unsigned integer
|-
| UNIT16
| 16 bit unsigned integer
|-
| UINT32
| 32 bit unsigned integer
|-
| UINT64
| 64 bit unsigned integer
|-
|
[[#UINTN.2C_Variable_Length_Unsigned_Integer|UINTN]]
| variable length unsigned integer
|-
|
[[#PTD.2C_Property_Transport_Definition|PTD]]
| property transport definition
|-
|
[[#DSD.2C_Dimension_Sequence_Description|DSD]]
| dimension sequence description
|-
|
[[#DBD.2C_Dimension_Bounds_Definition|DBD]]
| dimension bounds definition
|-
|
[[#ADB.2C_Array_Dimension_Bound|ADB]]
| array dimension bound
|}

=== UINTN, Variable Length Unsigned Integer ===

The octets below are in little endian order (least significant bits are transmitted before most significant bits).

{| border="1"
|+ UINTN - 1 octet
! Data Type
! Bit 7, msb
! Bits 7 - 0
|-
| OCTET
| 0
| Bits 0-7 of unsigned integer value
|}

{| border="1"
|+ UINTN - 2 octets
! Data Type
! Bit 7, msb
! Bits 7 - 0
|-
| OCTET
| 1
| Bits 0-7 of unsigned integer value
|-
| OCTET
| 0
| Bits 8-15 of unsigned integer value
|}

{| border="1"
|+ UINTN - 3 octets
! Data Type
! Bit 7, msb
! Bits 7 - 0
|-
| OCTET
| 1
| Bits 0-7 of unsigned integer value
|-
| OCTET
| 1
| Bits 8-15 of unsigned integer value
|-
| OCTET
| 0
| Bits 16-23 of unsigned integer value
|}

After 3 octets, the same pattern repeats.

{| border="1"
|+ UINTN - N octets
! Data Type
! msb
! Bits 7 - 0
|-
| OCTET
| 1
| Bits 0-7 of unsigned integer value
|-
| OCTET
| 1
| Bits 8-15 of unsigned integer value
|-
| OCTET
| 1
| Bits 16-23 of unsigned integer value
|-
| ...
| 1
| ...
|-
| OCTET N
| 0
| Bits N*8-N*9-1 of unsigned integer value
|}

=== STRING, UTF-8 Encoded Character String ===

{| border="1"
|+ STRING
! Data Type
! Purpose
|-
| UINTN
| the number of UTF-8 tokens
|-
| OCTET sequence
| UTF-8 encoded character string sequence
|}

Nill (zero) termination is not included in the string.

=== PSD, Property Sequence Description ===

This data type is used to describe a packed sequence of property values, a property sequence (PS), that might be encapsulated within a subsequent message on the same circuit, or in the same datagram. The order that the properties are described in the sequence is exactly the same as the order that the properties will be pushed onto the wire.

{| border="1"
|+ Container Property Transport Sequence Description
! Data Type
! Purpose
|-
| UINTN
| Number of properties in sequence
|-
| '''N''' Property transport definitions
| See below
|}

==== PTD, Property Transport Definition ====

If the <code>dimension</code> field is zero then property bounds definitions are not included, and the property transported has a scalar representation.

{| border="1"
|+ Property Transport Definition - Atomic
! Data Type
! Purpose
! Value
|-
| UINTN
| Property Id
| Sender defined
|-
| UINTN
| Data Type Identifier
| Sender defined, not 9
|-
| DSD
| Dimension sequence description
| Sender defined
|}

{| border="1"
|+ Property Transport Definition - Container
! Data Type
! Purpose
! Value
|-
| UINTN
| Property Id
| Sender defined
|-
| UINTN
| Data Type Identifier
| 9
|-
| DSD
| Dimension sequence description
| Sender defined
|-
| PSD
| Property sequence description
| Sender defined
|}

==== DSD, Dimension Sequence Description ====

{| border="1"
|+ Scalar Dimension Sequence
! Data Type
! Purpose
! Value
|-
| UINTN
| Specifies that the data is scalar
| 0
|}

{| border="1"
|+ Array Dimension Sequence
! Data Type
! Purpose
! Value
|-
| UINTN
| Specifies the number of property bounds definitions for array data
| N, not zero
|-
| N X DBD
| sequence of N property bounds definitions
| Sender defined
|}

==== DBD, Dimension Bounds Definition ====

{| border="1"
|+ Property Bounds Definition, Fixed Bound
! Data Type
! Purpose
! Value
|-
| UINTN
| Bound Type
| 0, fixed bound
|-
| ADB
| Array dimension bound
| Sender defined
|}

{| border="1"
|+ Property Bounds Definition, Variable Bound
! Data Type
! Purpose
! Value
|-
| UINTN
| Bound Type
| 1, variable bound
|}

===== Packaging of arrays on the wire =====

If the bound type is fixed, then the dimension does not accompany the array data on the wire. If the bound type is variable then any variable dimension information immediately precedes the data on the wire. The order that any dynamic dimensions are described in the dimension sequence description (DSD) is exactly the same order that any dynamic array dimension bound (ADB) will be pushed on to the wire prior to pushing the array data sequence on to the wire.

==== ADB, Array Dimension Bound ====

{| border="1"
|+ Array Dimension Bound
! Data Type
! Purpose
! Value
|-
| UINTN
| First element index
| Sender defined
|-
| UINTN
| Element count
| Sender defined
|}

== Property Hierarchy Path ==

<property hierarchy path> := <optional white space> . <optional white space> <property name> <optional white space> [ <property hierarchy path> ]

A "." character is employed to separate components of the property hierarchy path. Should the user need to include the "." in a channel name, they can escape the "." character with a back slash "\" character.

== Channel ==

A channel is defined to be a virtual communication path from a client application to a communication receptacle in a service. The communication receptacle is either a process variable or a message passing interface.

=== Channel Names ===

Flat (hierarchy challenged) tools like caGet will need to access a property deeply embedded in the property hierarchy as a simple PV.

Therefore, channel names will have the following format.

<communication receptacle name> [ <property hierarchy path> ]

:'''This syntax may clash with the current state of the version 4 database design.'''

== Message Transport ==

The protocol is designed for transport via a full duplex octet stream circuit such as is offered by TCP/IP. Clients initiate circuits with servers. All clients and servers initiating a new outgoing octet stream circuit ''must ''insert, prior to any other message, a <code>CA Protocol Initiate</code> message. Certain requests (see documentation for each request) will also be suitable for datagram transport such as is offered by UDP/IP. The <code>CA Protocol Initiate</code> message'' must'' be the first message in any CA protocol datagram prior to any other message in the datagram.

The protocol is asynchronous, and therefore multiple requests can be outstanding (waiting for a response) at the same time. It is expected that quality implementations will combine several messages together into one network frame.

=== CA Protocol Initiate ===

This message overlays a similar purposed message employed by previous versions of the protocol thereby retaining potential for client and server libraries to, at runtime, choose between dispatch tables suitable to different protocol revisions. This allows client and server libraries to communicate with multiple peers using both the EPICS version 3 and the EPICS version 4 protocols.

There is no response to this message.

{| border="1"
|+ CA Protocol Initiate
! Data Type
! Purpose
! Value
|-
| UINT16
| reserved
| 0
|-
| UINT16
| reserved
| 0
|-
| UINT16
| requested server dispatch priority where 0 is the lowest priority (executes last) and 255 is the highest priority (executes first), all other values are reserved
|
{| border="1"
| clients
| servers
|-
| 0 - 255
| 0
|}
|-
| UINT16
| protocol minor revision number
| 15
|-
| UINT32
| magic number
| 0x5b43415d == '[' 'C' 'A' ']'
|-
| UNIT32
|
Reserved for virtual circuits.

A sequence number incrementing with each successive message for datagrams. Clients use this sequence number to detect duplicates and out of order delivery.
|
{| border="1"
| circuit
| datagram
|-
| 0
| sequence number
|}
|}

The dispatch priority protocol element is relevant only when a client initiates communication with a server. Servers do not request a dispatch priority within its client, and should set this field to zero.

== Request / Response Protocol ==

=== Request Messages ===

Request messages are transmitted only by clients. Servers do not transmit request messages. There are two request message forms depending on whether a response is possible, or not.

{| border="1"
|+ Request Message - Response is Possible
! Data Type
! Purpose
! Value
|-
| UINTN
| Request identifier
| client defined
|-
| OBJID
| Request identifier
| client defined, 0 - 31 reserved
|-
| OCTETS
| Request payload
| request dependent
|}

{| border="1"
|+ Request Message - No Response
! Data Type
! Purpose
! Value
|-
| UINTN
| Request identifier
| client defined
|-
| OCTETS
| Request payload
| request dependent
|}

=== Response Messages ===

Response messages are transmitted only by servers. Clients do not transmit response messages.

==== Solicited Response Messages ====

{| border="1"
|+ Success Response
! Data Type
! Purpose
! Value
|-
| UINTN
| request identifier
| request defined
|-
| OCTETS
| response payload
| request dependent
|}

==== Unsolicited, or Indirectly Solicited, Response Messages ====

===== Exception Response =====

This indirectly solicited response is sent when a request fails in the server.

{| border="1"
|+ Exception Response
! Data Type
! Purpose
! Value
|-
| UINTN
| Request identifier
| 0
|-
| UINTN
| Exception identifier
| failure dependent, see below
|-
| STRING
| Failure context message
| failure dependent
|-
| UINTN
| Copy of request message length
| N, request defined, but zero if failure not caused by a request
|-
| N OCTETS
| Copy of request message
| request defined
|}

{| border="1"
|+ Exception Identifier
! Status Value
! Definition
! Severity
|-
| 0
| Insufficient memory to complete request
| Warning
|-
| 1
| Invalid request identifier
| Fatal
|-
| 2
| Invalid channel name
| Warning
|-
| 3
| Invalid channel identifier
| Fatal
|-
| 4
| Invalid property identifier
| Fatal
|-
| 5
| Invalid property transport sequence identifier
| Fatal
|-
| ...
|
|
|}

===== Server Status Beacon =====

This request is sent by a server to announce periodically its presence, and availability, on the network. This request might be sent over a virtual circuit, or in a datagram. There is no response. The property transport sequence might be predefined at compile time. It is used to identify the server address (including possibly a TCP port) of the sender, and other (possibly site specific) server state variables.

{| border="1"
|+ Server Status Beacon
! Data Type
! Purpose
! Value
|-
| UINTN
| Request identifier
| 1
|-
| UINTN
| Property sequence identifier
| Sender Defined
|-
| PS
| Server status parameters
| Sender Defined
|}

=== Protocol Encapsulation ===

{| border="1"
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 0
|-
| UINTN
| Encoding
| TBD, but to include an unmodified encoding and at least one standard type of compression encoding
|-
| UINTN
| Length
| N, compressed protocol sequence length
|-
| N OCTETS
| Encapsulated protocol octet sequence
| Sender defined, format determined by encoding
|}

The maximum size of an encapsulation probably needs to be specified.

Compression will be useful only when fast computers communicate or relatively slow links.

=== Define Channel ===

The client defines a channel in the server for its future use. There is no response unless the request is invalid, or cant be completed.

If at any time a communication endpoint to which a channel is bound ceases to exist, the server must send an <code>Invalid channel identifier</code> exception responses to all of the appropriate clients indicating that their channel is attached to a defunct resource. After receiving the <code>Invalid channel identifier</code> exception the client library is no-longer required to close the relevant channel with the server.

{| border="1"
|+ Define Channel Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 1
|-
| UINTN
| Channel Identifier
| Sender defined
|-
| STRING
| Channel Name
| Sender defined
|}

=== Expunge Channel ===

The client must expunge any channel from the server that will no-longer be used.

{| border="1"
|+ Expunge Channel Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| Channel Identifier
| Sender defined
|}

=== Swap Channel Identifiers ===

Commands the server to assign the process variable associated with channel identifier one to channel underived two and visa-versa. This functionality allows implementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

{| border="1"
|+ Swap Channel Identifiers Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| Channel Identifier one
| Sender defined
|-
| UINTN
| Channel Identifier two
| Sender defined
|}

{| border="1"
|+ Swap Channel Identifiers Successful Response
| Data Type
| Purpose
| Value
|-
| UINTN
| Request identifier
| Client defined
|}

=== Define Property ===

The client defines a property in the server for its future use. There is no response unless the request is invalid, or cant be completed. Commonly used properties, especially those used by datagram services, will be predefined thereby avoiding any need to define the property before it is used.

{| border="1"
|+ Define Property Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 2
|-
| UINTN
| Property identifier
| Sender defined
|-
| STRING
| Property name
| Sender defined
|}

=== Expunge Property ===

The client must expunge any property from the server that will no-longer be used.

{| border="1"
|+ Expunge Property Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| Property Identifier
| Sender defined
|}

=== Swap Property Identifiers ===

Commands the server to assign the property associated with property identifier one to property underived two and visa-versa. This functionality allows implementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

{| border="1"
|+ Swap Property Identifiers Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| Property Identifier one
| Sender defined
|-
| UINTN
| Property Identifier two
| Sender defined
|}

{| border="1"
|+ Swap Property Identifiers Successful Response
| Data Type
| Purpose
| Value
|-
| UINTN
| Request identifier
| Client defined
|}

=== Define Property Transport Sequence ===

The client defines a property transport sequence in the server for its future use. A property transport sequence exactly describes a stream of octets that will express a sequence of properties in the primitive type and dimension selected by the client. There is no response unless the request is invalid, or cant be completed.

:'''Commonly used property transport sequences, especially those used by datagram services, might be predefined thereby avoiding any need to define the property transport sequence before it is used.'''

{| border="1"
|+ Define Property Transport Sequence Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 3
|-
| UINTN
| Property sequence identifier
| Sender defined
|-
| PSD
| Property sequence description, see above
| Sender defined
|}

=== Expunge Property Transport Sequence ===

The client must expunge any property transport sequence from the server that will no-longer be used.

{| border="1"
|+ Expunge Property Transport Sequence Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| Property Transport Sequence Identifier
| Sender defined
|}

=== Swap Property Transport Sequence Identifiers ===

Commands the server to assign the property transport sequence associated with property identifier one to property transport sequence identifier two and visa-versa. This functionality allows implementmplementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

{| border="1"
|+ Swap Property Identifiers Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| Property Transport Sequence Identifier one
| Sender defined
|-
| UINTN
| Property Transport Sequence Identifier two
| Sender defined
|}

{| border="1"
|+ Swap Property Transport Sequence Identifiers Successful Response
| Data Type
| Purpose
| Value
|-
| UINTN
| Request identifier
| Client defined
|}

=== Define IO Request Modifier ===

Define an IO request modifier. There is no response unless the request is invalid, or cant be completed.

The client ''must'' cancel any request trigger specification in the server that will no-longer be used.

{| border="1"
|+ Define Request Trigger Specification Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 4
|-
| UINTN
| IO request modifier identifier
| Sender defined, see below
|-
| STRING
| <IO Request Modifier Expression>
| Sender defined, see below
|}

{| border="1"
|+ IO request modifier identifier
! Value
! Purpose
|-
| 0
|
{| border="1"
! IO Type
! Synchronization Type
|-
| write
| unsynchronized write
|-
| read
| unsynchronized read
|-
| command
| unsynchronized command
|-
| subscribe
| first update is an unsynchronized read followed by updates for every state change
|}
|-
| 1 - 32
| reserved
|-
| N > 32
| client library assigned
|}

==== IO Request Modifier Expression ====

<IO Request Modifier Expression> :=
<Property Match Expression> <IO Request Attribute List>

<Property Match Expression> :=
[(] [ [<Property Match Expression>] <Boolean Operator> ] <Property Match Specification> [)]

<IO Request Attribute List> :=
{
<IO Request Attribute> [ <IO Request Attribute List> ]
}

<IO Request Attribute> :=
{
<Subscription Modifier>,
<Minimum Period Spec>,
<Maximum Period Spec>,
<Minimum Percent Change Between Updates Spec>,
<Time Based Extraction Criteria>,
<Maximum Event Queue Length>,
<Trigger Time Offset>,
<Property Path>
}

<Property Match Expression> :=
<Property Name> <Comparison Operator>
{ <Property Name>, <Channel Name>, <Constant Expression> }

Here are some examples of IO modifier expressions. Parenthesis may be used to enforce order of operations.

(beamGate == 4 ) && ! ( bpm32.beamGate == 7)

beamGate == 4 && triggerTimeOffset ( 3 sec )

beamGate == 4 && eventQueueLength ( 1 ) maxPeriod ( 4 sec )

eventQueueLength ( 1 ) propertyPath ( limits )

eventQueueLength ( 1 ) propertyPath ( xAxisMotor.limits )

===== Minimum and Maximum Period (applicable only to subscriptions) =====

timeSpec := <real number> <time units>

maxPeriod ( timeSpec )

minPeriod ( timeSpec )

===== Minimum Percent Change Between Updates (applicable only to subscriptions) =====

minPercentChange ( <real number> )

===== Time Based Extraction Criteria (applicable only to subscriptions) =====

beginTime ( timeSpec )

endTime ( timeSpec )

===== Maximum Event Queue Length (applicable only to subscriptions) =====

eventQueueLength ( <integer number> )

===== Trigger Time Offset (applicable only to subscriptions) =====

triggerTimeOffset ( timeSpec )

===== Property Path =====

propertyPath ( <property hierarchy path> )

:'''Attributes controlling queueing versus caching behavior of read and writes are probably specified here. Needs more thought.'''

:'''Attributes controlling process passive and maximize severity (or their future functional equivalents) are probably specified here. Needs more thought.'''

=== Expunge IO Request Modifier ===

The client must expunge any IO request modifier from the server that will no-longer be used.

{| border="1"
|+ Expunge IO Request Modifier
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| IO request modifier identifier
| Sender defined
|}

=== Swap IO Request Modifier Identifiers ===

Commands the server to assign the trigger specification associated with property identifier one to trigger intensifier two and visa-versa. This functionality allows implementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

{| border="1"
|+ Swap Property Identifiers Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
|
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| IO request modifier identifier one
| Sender defined
|-
| UINTN
| IO request modifier identifier two
| Sender defined
|}

{| border="1"
|+ Swap Trigger Identifiers Successful Response
| Data Type
| Purpose
| Value
|-
| UINTN
| Request identifier
| Client defined
|}

=== Channel Write Without Response ===

The client writes a property transport sequence to a process variable in the service. There is no response unless the request is invalid, or cant be completed.

{| border="1"
|+ Channel Write Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 5
|-
| UNINT
| Channel identifier
| Sender defined
|-
| UINTN
| Property sequence identifier of payload
| Sender defined
|-
| UINTN
| IO request modifier identifier
| Sender defined
|-
| PS
| Property payload to be written
| Sender defined
|}

=== Channel Write With Response ===

The client writes a property transport sequence to a process variable in the service. There is always a response. A successful response indicates that the request, and all side effects, have completed. An unsuccessful response is an exception response (see above). It indicates that the request could not be completed in entirety, and that the internal state of the channel has not been modified.

{| border="1"
|+ Channel Write Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 6
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| Channel identifier
| Sender defined
|-
| UINTN
| Property sequence identifier of payload
| Sender defined
|-
| UINTN
| IO request modifier identifier
| Sender defined
|-
| PS
| Property payload to be written
| Sender defined
|}

{| border="1"
|+ Channel Write Successful Response
| Data Type
| Purpose
| Value
|-
| UINTN
| Request identifier
| Client defined
|}

=== Channel Read or Subscribe ===

The client reads a property transport sequence from a process variable in the service. If the request identifier is 7, there is only one response. Otherwise, if the request identifier is 8, a subscription is created and multiple responses are expected. A successful response includes the specified property transport sequence identifying the current state of the channel when the request was executed by the server. An unsuccessful response is an exception response (see above).

{| border="1"
|+ Channel Read or Subscribe Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 7 or 8
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| Channel identifier
| Sender defined
|-
| UINTN
| Property sequence identifier of response payload
| Sender defined
|-
| UINTN
| IO request modifier identifier
| Sender defined
|}

{| border="1"
|+ Channel Read or Subscribe Successful Response
! Data Type
! Purpose
! Value
|-
| UINTN
| Request identifier
| Client defined
|-
| PS
| Property payload read
| Client formatted, server defined
|}

=== Channel Command ===

The client sends a command to a message passing interface in the service. A request in the form of a property transport sequence is sent to the message passing interface in the service, and the message passing interface responds with another property transport sequence.

{| border="1"
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 9
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| Channel identifier
| Sender defined
|-
| UINTN
| Request property sequence payload identifier
| Sender defined
|-
| UINTN
| Response property sequence payload identifier
| Sender defined
|-
| UINTN
| IO request modifier identifier
| Sender defined
|-
| PS
| Request property payload
| Sender defined
|}

{| border="1"
|+ Channel Read or Subscribe Successful Response
! Data Type
! Purpose
! Value
|-
| UINTN
| Request identifier
| Client defined
|-
| PS
| Response property payload
| Client formatted, server defined
|}

=== Cancel Request ===

Cancel a request in progress. There is no response.

{| border="1"
|+ Cancel Previous Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 10
|-
| UINTN
| Request identifier
| identifier of the request to be canceled
|}

{| border="1"
|}

=== Server Verify ===

Verify that the server is responsive.

This request might also be accepted to by a datagram server. Typically, a response is mandatory, but a datagram server ''must'' never respond to any request of this type in a datagram sent to a broadcast or multicast address.

The property transport sequence is used to identify the condition of the server, and other (possibly site specific) server state variables.

{| border="1"
|+ Server Verify Request
! Data Type
! Purpose
! Value
|-
| UINTN
| Directive
| 11
|-
| UINTN
| Request identifier
| Sender defined
|-
| UINTN
| Property sequence identifier
| Sender defined
|}

{| border="1"
|+ Circuit Verify Successful Response
! Data Type
! Purpose
! Value
|-
| OBJID
| Request identifier
| Client defined
|-
| PS
| Server status parameters
| Client formatted, server defined
|}

=== Design Notes ===

# A fundamental choice of this design was that all identifiers are assigned by the client. This tends to make state change logic simpler in the client library and, since the server's identifier need not be returned in a response to the client, there will also be less TCP return pipe traffic during setup.<br>The server might continue to have only one hash table keyed by an {object id, client id} pair. Hopefully, the bucket use distribution for this table can be managed to be reasonably uniform. This type of keying probably slightly increases hashing and distribution overhead so, alternatively, there could be one hash table in the server for each client, contingent possibly on upgraded memory management for the hash table implementation.<br>There is a chance that a request to define a channel will be sent to a server that does not have the named communication receptacle. In that situation the server will send the client an exception, and respond to any subsequent requests specifying a bogus channel identifier with an exception message.<br>The unfortunate drawback to this approach will be the opportunity for a client to briefly think that it is connected when it isn't. We are currently ensuring that disconnect notification arrives within NNN seconds so perhaps brief windows of uncertainty are not unreasonable. Also, this window of uncertainty would exist prior to arrival of the first monitor update so any client that watches the magnitude of a channel should remain in a safe state.
# The flow-control functionality in previous versions of the CA protocol was probably only relevant to GUI applications. It is superseded in this version of the protocol by capabilities allowing clients to set the subscription event queue length?
# Server beacons are used to efficiently inform multiple clients about server state of health while using minimum bandwidth. Multicasts/broadcasts are typically the lowest bandwidth consuming option when sending one message to multiple clients. Server beacons are used to A) inform clients when a newly accessible IOC joins the network, and B) periodically communicate tangible indication of responsiveness to clients with idle TCP circuits.<br>In this version of the protocol hopefully beacons will be issued using multicast addresses thereby eliminating any need for the CA Repeater daemon.<br>In this version of the protocol additional server state of health properties might be included in the beacon message.
# The current baseline is to not include messages in the CA protocol for authentication purposes. Instead, we prefer to use transport protocol facilities for coarse host based authentication, and integrate public domain kerberos libraries (or some other equivalent) for stronger forms of authentication including user based authentication.
# The current baseline is to employ subordinate properties to communicate the current state of the access rights for a channel.<br>Will access rights properties need to show up in multiple places in the property hierarchy in order that the access rights might vary depending on what properties are accessed? If so, then how can we provide a consistent interface for clients so that they always know where to find the access rights in the property hierarchy?
# Users will need to monitor the connection state of channels.<br>Within the protocol there is a channel disconnect exception designating a service disconnect. There might also be a transport circuit disconnect.<br>The user will probably subscribe at the client programming interface for connection state change callbacks using the subscription mechanism. The client library will trap the appropriate exceptions and circuit disconnect state changes forwarding them as synthesized subscription update callbacks at the programming interface.
# The queueing versus caching behavior of write request sent to a channel will be modified by specifying a specialized IO request modifier with the write request.
# The EPICS function block database's process passive and maximize severity link attributes (or their future equivalents) will be manipulated by specifying a specialized IO request modifier.
# It will be necessary to introspect all of (or a subset of) the properties that are available in a channel. This will be accomplished by reading the <code>propertyList</code> property of the channel and requesting primitive type <code>PSD</code> or <code>STRING</code>.
# There will be situations where the client will prefer to create one channel, but index any part of the property hierarchy. This will be done by specifying the property path in a relevant IO request modifier.
# It will probably also be necessary to obtain a list of all of the communication receptacles in a server. This might be accomplished by sending a request / response command to a specialized PV. Wild cards could be specified in the request parameters and the channel list could be delivered in the response parameters.
# Within future EPICS systems a special property accompanying state change update notification payloads must efficiently indicate the type of state change that has occurred. For example, there are currently "default dead-band state change excursion", "archive dead-band state change excursion", and "alarm state change" state change identifying events. This information will be needed, for example, to improve the implementation of the CA gateway. Starting with version four of EPICS a PSD will define a special type for communicating this information, and a standard property name will be assigned for locating this information in a subscription update payload. This property will also be used in IO request modifiers to filter out state changes that might not be needed.

V4 Replacement for SNL

2005-07-14T12:44:55Z

BenFranksen:

Warning: The following is work in progress.<p>

= Scope =

This document is concerned mainly with features of SNL as a programming language, especially for the control of complex devices. Other people have gathered requirements that concentrate more on the interaction between the runtime system (the sequencer) and the rest of the IOC, in order to support features like redundant IOC replication, better debugging etc. I hope we will be able to bring all those requirements together, somehow.

= Deficiencies of current SNL =

The current version of SNL (State Notation Language) has a number of severe deficiencies that should be addressed in a new version for EPICS R4.

; No Abstraction Facilities
: SNL doesn't support factoring common functionality. Functions cannot be defined in SNL, only by escaping to C, loosing all the features SNL adds (for instance easy access to PVs via 'assigned' variables). A typical workaround is to create additional state sets as a kind of subroutine. However, parameter passing and start/done communication must be simulated via PV-assigned global variables.

; State Change is Determined by When Clause
: In SNL the next state is already determined by the when-condition. This means that a condition for when to *do* something is coupled to a commitment for what to do next. This is often very inconvenient and to work around this limitation leads to a proliferation of artificial states that have nothing to do with the original state machine model.

; Weak Support for Introspection
: SNL supports querying internal state via the iocShell, but this is rather inconvenient and doesn't cover continous monitoring of the current state of a state set. In order to achieve this, the programmer has to (1) create a record to contain the value representing the current state, and (2) manually pvPut a value corresponding to the state into the PV on entry to the state, which clutters the code with extremely repetitive code, maintained via cut & paste.

= Remedies =

We propose a redesign of SNL, building on good and bad experiences with the current version. The goal is to remedy the deficiencies mentioned above, without throwing away what is good and proven to work. The syntax and semantics should be similar, although we adopt a somewhat different viewpoint. This viewpoint naturally leads to a number of new features that, taken together, solve the above mentioned problems. In particular:

; Abstraction
: Instead of adding ordinary procedures to the language, we propose a new way to ''instantiate'' state sets. A state set can be ''called'' like a procedure. It accepts parameters and can return a value. This necessitates thinking about the lifetime of state set objects.

; State Change
: Going to another state becomes a statement. It can be executed from anywhere in the code.

; Introspection
: The current state of all state sets, as well as global diagnostics (like the number of connected PVs) are exported using Data Access. The whole SNL programm will be represented as a propertyCatalog, with sub-properties for each named state set instance.

== A Preliminary Observation ==

It is widely known that closures (procedure + environment) can be implemented as objects in a language that natively supports objects. It is less well known, that objects can be implemented as closures in languages where closures are a native feature. The two concepts are quite similar. In what follows we will often switch from viewing things as objects to viewing them as closures and vice versa.

== Overview ==

The new SNL will still be a programming language in its own right. It will still be based on the notions of "state" and "state set"; it will still support a subset of C for "normal" imperative programming (statements, if/then/else, assignment, etc.).

However, we introduce a new view on the concepts of "state set" and "state". A state set is regarded as a (special form of) closure resp. object.

* State sets can be asynchronously ''spawned'' to run as an independent task. But they can also be synchronously ''called'', like a normal procedure, where the caller stops and waits for the state set to return. In both cases, the caller can specify a name (string) for the state set that will be used to represent the state set to the outside.

* In contrast to the current SNL, all state sets must be instantiated explicitly, even those that are meant to "live forever". This has the additional advantage that initialization can be better controlled by the programmer.

* State sets can receive arguments on creation. In the OO view, this corresponds to constructor arguments. The arguments are visible throughout the state set, but not to any outside entity.

* State sets can also return a value. Returning from a state set always destroys the underlying object. If a value was returned and the state set was created with a <tt>call</tt>, the caller receives this value. Otherwise the returned value is lost.

* State sets can have local variables. These are not visible from the outside.

* Individual states in a state set can also have local variables, as well as parameters (but no return value). Variables and parameters are not visible outside the state. The general syntax for a state change is <tt>state state_name(arg,...);</tt>.

* The lifetime of asynchronously (via <tt>spawn</tt>) created state sets is always limited to the enclosing block. For state sets created at the top-level, this means forever (or rather as long as the underlying task doesn't get killed).

* Waiting on a condition to become true is done with the traditional when-clause. However, the clause does not determine a new state. Instead 'state x(args...);' is treated like an ordinary SNL action statement and can be used freely inside a when-block.

== Details ==

=== Creation and Execution of State Sets ===

There are two ways to specify instance creation and execution of a state set: synchronous

(result_1,...,result_n) = call stateSetName(arg_1,...,arg_n) as instanceName;

and asynchronous

spawn stateSetName(arg_1,...,arg_n) as instanceName;

In both cases an instance of the state set 'stateSetName' is created with the given parameters and started. The 'as instanceName' is optional. If given, 'instanceName' must be a constant string that gives a name to the state set instance. The state set will then be visible from outside of teh SNL program via the Data Access interface to the program.

; call
: The caller waits (blocks execution) until the called state set returns, at which point the return values get assigned to the result variables. Assignment to result variables is optional.

; spawn
: The caller does not block execution and cannot receive any return values.

In the old SNL, a state set declaration implied the creation and execution of a global top-level state set object. This is no longer the case. Instead, state set instances must be explicitly created at the top-level. If a top-level state set is supposed to run permanently, it must be created with a <tt>spawn</tt> statement. This gives the programmer full control over the sequence of initialization.

=== Return from a State Set ===

A state set can stop its own execution at any time, returning any number of values, with a

return(ret_1,...,ret_n);

statement. The list of return values (including parenthesis) can be omitted. If the state set instance was created with a <tt>spawn</tt>, then any return values are lost.

=== State Set Declaration ===

'''Synopsis'''

ss MyStateSet(int int_arg, double double_arg) {
string local_string_var = "a string";
/* more local variable declarations */
state aState {...}
/* more state declarations */
}

A state set declaration is introduced by the reserved word 'ss', followed by the name of the state set, followed by an optional parenthesized list of argument declarations, followed by the state set body. The body consist of any number of local variable declarations, followed by any number of state declarations.

Two things are new here:

* a state set may have parameters
* a state set may have local variables

These behave the same as parameters and local variables in a C procedure definition. That is, both are visible only inside the state set, and both live as long as the state set instance lives.

=== State Declaration ===

'''Synopsis'''

state myStateName(string string_arg,...) {
int state_local_var = 1;
/* ...initial action statements... */
when (condition) {
/* ...action statements... */
if (another_condition) {
state anotherState(42);
}
state yetAnotherState;
}
when (...) {...}
...
}

A state declaration can only appear inside a state set declaration. Similarly to a state set, a single state can have parameters and local variables. The main difference to the current version are:

* no <tt>state NextState;</tt> after the <tt>when</tt> block, instead
* state change can appear anywhere a normal action statement is allowed

It is not yet clear what best to do if code falls off a when clause without specifying a state change. Possibilities are:

* compiler warns about possibly missing state change
** similar to C compiler warning about missing return
** generated code adds "abort state set" action as guard at the end
* compiler enforces that last statement in a when block is a state change
* keep the old syntax as expressing a default state change if execution reaches the end of a when block

=== Main Program ===

'''Synopsis'''

program MyProgram;

int x = 0;
pv<double> y("mydevice:setpoint");
/* ...more variable declarations... */

ss MyStateSet(int n) {
...
}
/* ...more state set declarations... */

spawn MyStateSet(0) as "MyStateSetInstance0";
spawn MyStateSet(1) as "MyStateSetInstance1";

The main program starts with the word 'program', followed by the program name. After this follow variable declarations, then state set declarations, and then action statements. The action statements are executed immediately after program start.

=== PVs ===

==== PV Data Type ====

It might be useful to introduce a special data type to represent references to PVs. The idea is to make it possible to pass PV references as arguments to state sets (and states). With the way PVs are handled at the moment, i.e. declaring a variable and assigning it to a PV name, passing the variable would pass only the (current) value, but not the PV itself.

We could mimick C++ template syntax and declare PVs like this:

pv<double> var("pv_name");

Now, <tt>var</tt> would be a PV object. The main point here is that it now has a type different from a plain <tt>double</tt>. Implicit conversion can be applied, so that assignment (from a <tt>double</tt> value) and usage within an expression (expecting a <tt>double</tt>) can be done as before:

double x = var;
var += 1.0;

Setting up a monitor and synchronizing with an event flag can be done exactly like before. However, we could now use <tt>var</tt> as a parameter to a state set instantiation:

call MyStateSet(var);

where the state set was declared as taking a PV as argument:

ss MyStateSet(pv<double> arg) {...}

An example could be a state set that generically handles setting or releasing brakes on a motor. On instantiation of the state set, it gets passed the motor (and possibly other) PVs as the actual parameters to work on. Without a special PV type this would only be possible by declaring an array of PVs and passing an index into this array to the state set.

==== Anonymous PVs ====

Another useful feature would be to let the SNL machinery create anonymous PVs for variables that are not assigned. A typical example:

pv<int> myFlag;

ss ...{
state ...{
when (myFlag) {
...
}
}
}

Currently, you would have to externally create a record (for instance, a bo) and connect a variable 'myFlag' to it, even though nothing besides the SNL program is interested in the value of this flag. Automatically creating PVs for un-assigned PV variables is only possible in V4, where records can be added online. In principle, a full-blown record for such a variable is overkill; there may be a way for the sequencer to create the PV in some other way.

=== External Access ===

Each SNL program will be presented to the outside world as a Data Access property catalog. Available properties include diagnostics such as the number of connected/available member variables (if assigned to a PV), a list of all global variables assigned to PVs, and all existing (life) state set objects as subproperties. Properties of a state set include the current state (including the state's parameters), and member variables.

== Implementation ==

We believe that our proposals can be implemented efficiently and without significantly changing the way SNL code is compiled currently. Of course, this remains to be proven.

V4 Replacement for SNL

2005-07-14T11:26:39Z

BenFranksen:

Warning: The following is work in progress.<p>

= Deficiencies of current SNL =

The current version of SNL (State Notation Language) has a number of severe deficiencies that should be addressed in a new version for EPICS R4.

; No Abstraction Facilities
: SNL doesn't support factoring common functionality. Functions cannot be defined in SNL, only by escaping to C, loosing all the features SNL adds (for instance easy access to PVs via 'assigned' variables). A typical workaround is to create additional state sets as a kind of subroutine. However, parameter passing and start/done communication must be simulated via PV-assigned global variables.

; State Change is Determined by When Clause
: In SNL the next state is already determined by the when-condition. This means that a condition for when to *do* something is coupled to a commitment for what to do next. This is often very inconvenient and to work around this limitation leads to a proliferation of artificial states that have nothing to do with the original state machine model.

; Weak Support for Introspection
: SNL supports querying internal state via the iocShell, but this is rather inconvenient and doesn't cover continous monitoring of the current state of a state set. In order to achieve this, the programmer has to (1) create a record to contain the value representing the current state, and (2) manually pvPut a value corresponding to the state into the PV on entry to the state, which clutters the code with extremely repetitive code, maintained via cut & paste.

= Proposal for a new SNL =

We propose a redesign of SNL, building on good and bad experiences with the current version. The goal is to remedy the deficiencies mentioned above, without throwing away what is good and proven to work. The syntax and semantics should be similar, although we adopt a somewhat different viewpoint. This viewpoint naturally leads to a number of new features that, taken together, solve the above mentioned problems. In particular:

; Abstraction
: Instead of adding ordinary procedures to the language, we propose a new way to ''instantiate'' state sets. A state set can be ''called'' like a procedure. It accepts parameters and can return a value. This necessitates thinking about the lifetime of state set objects.

; State Change
: Going to another state becomes a statement. It can be executed from anywhere in the code.

; Introspection
: The current state of all state sets, as well as global diagnostics (like the number of connected PVs) are exported using Data Access. The whole SNL programm will be represented as a propertyCatalog, with sub-properties for each named state set instance.

== A Preliminary Observation ==

It is widely known that closures (procedure + environment) can be implemented as objects in a language that natively supports objects. It is less well known, that objects can be implemented as closures in languages where closures are a native feature. The two concepts are quite similar. In what follows we will often switch from viewing things as objects to viewing them as closures and vice versa.

== Overview of Concepts ==

The new SNL will still be a programming language in its own right. It will still be based on the notions of "state" and "state set"; it will still support a subset of C for "normal" imperative programming (statements, if/then/else, assignment, etc.).

However, we introduce a new view on the concepts of "state set" and "state". A state set is regarded as a (special form of) closure resp. object.

* State sets can be asynchronously ''spawned'' to run as an independent task. But they can also be synchronously ''called'', like a normal procedure, where the caller stops and waits for the state set to return. In both cases, the caller can specify a name (string) for the state set that will be used to represent the state set to the outside.

* In contrast to the current SNL, all state sets must be instantiated explicitly, even those that are meant to "live forever". This has the additional advantage that initialization can be better controlled by the programmer.

* State sets can receive arguments on creation. In the OO view, this corresponds to constructor arguments. The arguments are visible throughout the state set, but not to any outside entity.

* State sets can also return a value. Returning from a state set always destroys the underlying object. If a value was returned and the state set was created with a <tt>call</tt>, the caller receives this value. Otherwise the returned value is lost.

* State sets can have local variables. These are not visible from the outside.

* Individual states in a state set can also have local variables, as well as parameters (but no return value). Variables and parameters are not visible outside the state. The general syntax for a state change is <tt>state state_name(arg,...);</tt>.

* The lifetime of asynchronously (via <tt>spawn</tt>) created state sets is always limited to the enclosing block. For state sets created at the top-level, this means forever (or rather as long as the underlying task doesn't get killed).

* Waiting on a condition to become true is done with the traditional when-clause. However, the clause does not determine a new state. Instead 'state x(args...);' is treated like an ordinary SNL action statement and can be used freely inside a when-block.

=== Creation and Execution of State Sets ===

There are two ways to specify instance creation and execution of a state set: synchronous

(result_1,...,result_n) = call stateSetName(arg_1,...,arg_n) as instanceName;

and asynchronous

spawn stateSetName(arg_1,...,arg_n) as instanceName;

In both cases an instance of the state set 'stateSetName' is created with the given parameters and started. The 'as instanceName' is optional. If given, 'instanceName' must be a constant string that gives a name to the state set instance. The state set will then be visible from outside of teh SNL program via the Data Access interface to the program.

; call
: The caller waits (blocks execution) until the called state set returns, at which point the return values get assigned to the result variables. Assignment to result variables is optional.

; spawn
: The caller does not block execution and cannot receive any return values.

In the old SNL, a state set declaration implied the creation and execution of a global top-level state set object. This is no longer the case. Instead, state set instances must be explicitly created at the top-level. If a top-level state set is supposed to run permanently, it must be created with a <tt>spawn</tt> statement. This gives the programmer full control over the sequence of initialization.

=== Return from a State Set ===

A state set can stop its own execution at any time, returning any number of values, with a

return(ret_1,...,ret_n);

statement. The list of return values (including parenthesis) can be omitted. If the state set instance was created with a <tt>spawn</tt>, then any return values are lost.

=== State Set Declaration ===

'''Synopsis'''

ss MyStateSet(int int_arg, double double_arg) {
string local_string_var = "a string";
/* more local variable declarations */
state aState {...}
/* more state declarations */
}

A state set declaration is introduced by the reserved word 'ss', followed by the name of the state set, followed by an optional parenthesized list of argument declarations, followed by the state set body. The body consist of any number of local variable declarations, followed by any number of state declarations.

Two things are new here:

* a state set may have parameters
* a state set may have local variables

These behave the same as parameters and local variables in a C procedure definition. That is, both are visible only inside the state set, and both live as long as the state set instance lives.

=== State Declaration ===

'''Synopsis'''

state myStateName(string string_arg,...) {
int state_local_var = 1;
/* ...initial action statements... */
when (condition) {
/* ...action statements... */
if (another_condition) {
state anotherState(42);
}
state yetAnotherState;
}
when (...) {...}
...
}

Similarly to a state set, a single state can have parameters and local variables. The state change clause after the when block serves only as

=== Main Program ===

'''Synopsis'''

program MyProgram;

int x = 0;
pv<double> y("mydevice:setpoint");
/* ...more variable declarations... */

ss MyStateSet(int n) {
...
}
/* ...more state set declarations... */

spawn MyStateSet(0) as "MyStateSetInstance0";
spawn MyStateSet(1) as "MyStateSetInstance1";

The main program starts with the word 'program', followed by the program name. After this follow variable declarations, then state set declarations, and then action statements. The action statements are executed immediately after program start.

=== Access from the Outside ===

Each SNL program will be presented to the outside world as a Data Access property catalog. Available properties include diagnostics such as the number of connected/available member variables (if assigned to a PV), a list of all global variables assigned to PVs, and all existing (life) state set objects as subproperties. Properties of a state set include the current state (including the state's parameters), and member variables.

=== PVs ===

It might be a good idea to introduce a special data type to represent references to PVs. The idea is to make it possible to pass PV references as arguments to state sets (and states). With the way PVs are handled at the moment, i.e. declaring a variable and assigning it to a PV name, passing the variable would pass only the value of the variable, but not the PV itself.

We could mimick C++ template syntax and declare PVs like this:

pv<double> var("pv_name");

Now, <tt>var</tt> would be a PV object. The main point here is that it now has a type different from a plain <tt>double</tt>. Implicit conversion can be applied, so that assignment (from a <tt>double</tt> value) and usage within an expression (expecting a <tt>double</tt>) can be done as before:

double x = var;
var += 1.0;

Setting up a monitor and synchronizing with an event flag can be done exactly like before. However, we could now use <tt>var</tt> as a parameter to a state set instantiation:

call MyStateSet(var);

where the state set was declared as taking a PV as argument:

ss MyStateSet(pv<double> arg) {...}

An example could be a state set that generically handles setting or releasing brakes on a motor. On instantiation of the state set, it gets passed the motor (and possibly other) PVs as the actual parameters to work on. Without a special PV type this would only be possible by declaring an array of PVs and passing an index into this array to the state set.

== Implementation ==

We believe that our proposals can be implemented efficiently and without significantly changing the way SNL code is compiled currently. Of course, this remains to be proven.

V4 Replacement for SNL

2005-07-14T10:10:58Z

BenFranksen: /* State Set Declaration */

Warning: The following is work in progress.<p>

= Deficiencies of current SNL =

The current version of SNL (State Notation Language) has a number of severe deficiencies that should be addressed in a new version for EPICS R4.

; No Abstraction Facilities
: SNL doesn't support factoring common functionality. Functions cannot be defined in SNL, only by escaping to C, loosing all the features SNL adds (for instance easy access to PVs via 'assigned' variables). A typical workaround is to create additional state sets as a kind of subroutine. However, parameter passing and start/done communication must be simulated via PV-assigned global variables.

; State Change is Determined by When Clause
: In SNL the next state is already determined by the when-condition. This means that a condition for when to *do* something is coupled to a commitment for what to do next. This is often very inconvenient and to work around this limitation leads to a proliferation of artificial states that have nothing to do with the original state machine model.

; Weak Support for Introspection
: SNL supports querying internal state via the iocShell, but this is rather inconvenient and doesn't cover continous monitoring of the current state of a state set. In order to achieve this, the programmer has to (1) create a record to contain the value representing the current state, and (2) manually pvPut a value corresponding to the state into the PV on entry to the state, which clutters the code with extremely repetitive code, maintained via cut & paste.

= Proposal for a new SNL =

We propose a redesign of SNL, building on good and bad experiences with the current version. The goal is to remedy the deficiencies mentioned above, without throwing away what is good and proven to work. The syntax and semantics should be similar, although we adopt a somewhat different viewpoint. This viewpoint naturally leads to a number of new features that, taken together, solve the above mentioned problems. In particular:

; Abstraction
: Instead of adding ordinary procedures to the language, we propose a new way to ''instantiate'' state sets. A state set can be ''called'' like a procedure. It accepts parameters and can return a value. This necessitates thinking about the lifetime of state set objects.

; State Change
: Going to another state becomes a statement. It can be executed from anywhere in the code.

; Introspection
: The current state of all state sets, as well as global diagnostics (like the number of connected PVs) are exported using Data Access. The whole SNL programm will be represented as a propertyCatalog, with sub-properties for each named state set instance.

== A Preliminary Observation ==

It is widely known that closures (procedure + environment) can be implemented as objects in a language that natively supports objects. It is less well known, that objects can be implemented as closures in languages where closures are a native feature. The two concepts are quite similar. In what follows we will often switch from viewing things as objects to viewing them as closures and vice versa.

== Overview of Concepts ==

The new SNL will still be a programming language in its own right. It will still be based on the notions of "state" and "state set"; it will still support a subset of C for "normal" imperative programming (statements, if/then/else, assignment, etc.).

However, we introduce a new view on the concepts of "state set" and "state". A state set is regarded as a (special form of) closure resp. object.

* State sets can be asynchronously ''spawned'' to run as an independent task. But they can also be synchronously ''called'', like a normal procedure, where the caller stops and waits for the state set to return. In both cases, the caller can specify a name (string) for the state set that will be used to represent the state set to the outside.

* In contrast to the current SNL, all state sets must be instantiated explicitly, even those that are meant to "live forever". This has the additional advantage that initialization can be better controlled by the programmer.

* State sets can receive arguments on creation. In the OO view, this corresponds to constructor arguments. The arguments are visible throughout the state set, but not to any outside entity.

* State sets can also return a value. Returning from a state set always destroys the underlying object. If a value was returned and the state set was created with a <tt>call</tt>, the caller receives this value. Otherwise the returned value is lost.

* State sets can have local variables. These are not visible from the outside.

* Individual states in a state set can also have local variables, as well as parameters (but no return value). Variables and parameters are not visible outside the state. The general syntax for a state change is <tt>state state_name(arg,...);</tt>.

* The lifetime of asynchronously (via <tt>spawn</tt>) created state sets is always limited to the enclosing block. For state sets created at the top-level, this means forever (or rather as long as the underlying task doesn't get killed).

* Waiting on a condition to become true is done with the traditional when-clause. However, the clause does not determine a new state. Instead 'state x(args...);' is treated like an ordinary SNL action statement and can be used freely inside a when-block.

=== Creation and Execution of State Sets ===

There are two ways to specify instance creation and execution of a state set: synchronous

(result_1,...,result_n) = call stateSetName(arg_1,...,arg_n) as instanceName;

and asynchronous

spawn stateSetName(arg_1,...,arg_n) as instanceName;

In both cases an instance of the state set 'stateSetName' is created with the given parameters and started. The 'as instanceName' is optional. If given, 'instanceName' must be a constant string that gives a name to the state set instance. The state set will then be visible from outside of teh SNL program via the Data Access interface to the program.

; call
: The caller waits (blocks execution) until the called state set returns, at which point the return values get assigned to the result variables. Assignment to result variables is optional.

; spawn
: The caller does not block execution and cannot receive any return values.

In the old SNL, a state set declaration implied the creation and execution of a global top-level state set object. This is no longer the case. Instead, state set instances must be explicitly created at the top-level. If a top-level state set is supposed to run permanently, it must be created with a <tt>spawn</tt> statement. This gives the programmer full control over the sequence of initialization.

=== Return from a State Set ===

A state set can stop its own execution at any time, returning any number of values, with a

return(ret_1,...,ret_n);

statement. The list of return values (including parenthesis) can be omitted. If the state set instance was created with a <tt>spawn</tt>, then any return values are lost.

=== State Set Declaration ===

Synopsis:

ss MyStateSet(int int_arg, double double_arg)
{
string local_string_var = "a string";
state aState {...}
state anotherState...
}
}

Two things are new here:

* a state set may have parameters
* a state set may have local variables

These behave the same as parameters and local variables in a C procedure definition. That is, both are visible only inside the state set, and both live as long as the state set instance lives.

=== Local Variables ===

[to be done]

=== Main Program ===

[to be done]

=== Access from the Outside ===

Each SNL program will be presented to the outside world as a Data Access property catalog. Available properties include diagnostics such as the number of connected/available member variables (if assigned to a PV), a list of all global variables assigned to PVs, and all existing (life) state set objects as subproperties. Properties of a state set include the current state (including the state's parameters), and member variables.

=== PVs ===

It might be a good idea to introduce a special data type to represent references to PVs. The idea is to make it possible to pass PV references as arguments to state sets (and states). With the way PVs are handled at the moment, i.e. declaring a variable and assigning it to a PV name, passing the variable would pass only the value of the variable, but not the PV itself.

We could mimick C++ template syntax and declare PVs like this:

pv<double> var("pv_name");

Now, <tt>var</tt> would be a PV object. The main point here is that it now has a type different from a plain <tt>double</tt>. Implicit conversion can be applied, so that assignment (from a <tt>double</tt> value) and usage within an expression (expecting a <tt>double</tt>) can be done as before:

double x = var;
var += 1.0;

Setting up a monitor and synchronizing with an event flag can be done exactly like before. However, we could now use <tt>var</tt> as a parameter to a state set instantiation:

call MyStateSet(var);

where the state set was declared as taking a PV as argument:

ss MyStateSet(pv<double> arg) {...}

An example could be a state set that generically handles setting or releasing brakes on a motor. On instantiation of the state set, it gets passed the motor (and possibly other) PVs as the actual parameters to work on. Without a special PV type this would only be possible by declaring an array of PVs and passing an index into this array to the state set.

== Implementation ==

We believe that our proposals can be implemented efficiently and without significantly changing the way SNL code is compiled currently. Of course, this remains to be proven.

V4 Replacement for SNL

2005-07-14T10:10:28Z

BenFranksen: /* State Set Declaration */

Warning: The following is work in progress.<p>

= Deficiencies of current SNL =

The current version of SNL (State Notation Language) has a number of severe deficiencies that should be addressed in a new version for EPICS R4.

; No Abstraction Facilities
: SNL doesn't support factoring common functionality. Functions cannot be defined in SNL, only by escaping to C, loosing all the features SNL adds (for instance easy access to PVs via 'assigned' variables). A typical workaround is to create additional state sets as a kind of subroutine. However, parameter passing and start/done communication must be simulated via PV-assigned global variables.

; State Change is Determined by When Clause
: In SNL the next state is already determined by the when-condition. This means that a condition for when to *do* something is coupled to a commitment for what to do next. This is often very inconvenient and to work around this limitation leads to a proliferation of artificial states that have nothing to do with the original state machine model.

; Weak Support for Introspection
: SNL supports querying internal state via the iocShell, but this is rather inconvenient and doesn't cover continous monitoring of the current state of a state set. In order to achieve this, the programmer has to (1) create a record to contain the value representing the current state, and (2) manually pvPut a value corresponding to the state into the PV on entry to the state, which clutters the code with extremely repetitive code, maintained via cut & paste.

= Proposal for a new SNL =

We propose a redesign of SNL, building on good and bad experiences with the current version. The goal is to remedy the deficiencies mentioned above, without throwing away what is good and proven to work. The syntax and semantics should be similar, although we adopt a somewhat different viewpoint. This viewpoint naturally leads to a number of new features that, taken together, solve the above mentioned problems. In particular:

; Abstraction
: Instead of adding ordinary procedures to the language, we propose a new way to ''instantiate'' state sets. A state set can be ''called'' like a procedure. It accepts parameters and can return a value. This necessitates thinking about the lifetime of state set objects.

; State Change
: Going to another state becomes a statement. It can be executed from anywhere in the code.

; Introspection
: The current state of all state sets, as well as global diagnostics (like the number of connected PVs) are exported using Data Access. The whole SNL programm will be represented as a propertyCatalog, with sub-properties for each named state set instance.

== A Preliminary Observation ==

It is widely known that closures (procedure + environment) can be implemented as objects in a language that natively supports objects. It is less well known, that objects can be implemented as closures in languages where closures are a native feature. The two concepts are quite similar. In what follows we will often switch from viewing things as objects to viewing them as closures and vice versa.

== Overview of Concepts ==

The new SNL will still be a programming language in its own right. It will still be based on the notions of "state" and "state set"; it will still support a subset of C for "normal" imperative programming (statements, if/then/else, assignment, etc.).

However, we introduce a new view on the concepts of "state set" and "state". A state set is regarded as a (special form of) closure resp. object.

* State sets can be asynchronously ''spawned'' to run as an independent task. But they can also be synchronously ''called'', like a normal procedure, where the caller stops and waits for the state set to return. In both cases, the caller can specify a name (string) for the state set that will be used to represent the state set to the outside.

* In contrast to the current SNL, all state sets must be instantiated explicitly, even those that are meant to "live forever". This has the additional advantage that initialization can be better controlled by the programmer.

* State sets can receive arguments on creation. In the OO view, this corresponds to constructor arguments. The arguments are visible throughout the state set, but not to any outside entity.

* State sets can also return a value. Returning from a state set always destroys the underlying object. If a value was returned and the state set was created with a <tt>call</tt>, the caller receives this value. Otherwise the returned value is lost.

* State sets can have local variables. These are not visible from the outside.

* Individual states in a state set can also have local variables, as well as parameters (but no return value). Variables and parameters are not visible outside the state. The general syntax for a state change is <tt>state state_name(arg,...);</tt>.

* The lifetime of asynchronously (via <tt>spawn</tt>) created state sets is always limited to the enclosing block. For state sets created at the top-level, this means forever (or rather as long as the underlying task doesn't get killed).

* Waiting on a condition to become true is done with the traditional when-clause. However, the clause does not determine a new state. Instead 'state x(args...);' is treated like an ordinary SNL action statement and can be used freely inside a when-block.

=== Creation and Execution of State Sets ===

There are two ways to specify instance creation and execution of a state set: synchronous

(result_1,...,result_n) = call stateSetName(arg_1,...,arg_n) as instanceName;

and asynchronous

spawn stateSetName(arg_1,...,arg_n) as instanceName;

In both cases an instance of the state set 'stateSetName' is created with the given parameters and started. The 'as instanceName' is optional. If given, 'instanceName' must be a constant string that gives a name to the state set instance. The state set will then be visible from outside of teh SNL program via the Data Access interface to the program.

; call
: The caller waits (blocks execution) until the called state set returns, at which point the return values get assigned to the result variables. Assignment to result variables is optional.

; spawn
: The caller does not block execution and cannot receive any return values.

In the old SNL, a state set declaration implied the creation and execution of a global top-level state set object. This is no longer the case. Instead, state set instances must be explicitly created at the top-level. If a top-level state set is supposed to run permanently, it must be created with a <tt>spawn</tt> statement. This gives the programmer full control over the sequence of initialization.

=== Return from a State Set ===

A state set can stop its own execution at any time, returning any number of values, with a

return(ret_1,...,ret_n);

statement. The list of return values (including parenthesis) can be omitted. If the state set instance was created with a <tt>spawn</tt>, then any return values are lost.

=== State Set Declaration ===

ss MyStateSet(int int_arg, double double_arg)
{
string local_string_var = "a string";
state aState {...}
state anotherState...
}
}

Two things are new here:

* a state set may have parameters
* a state set may have local variables

These behave the same as parameters and local variables in a C procedure definition. That is, both are visible only inside the state set, and both live as long as the state set instance lives.

=== Local Variables ===

[to be done]

=== Main Program ===

[to be done]

=== Access from the Outside ===

Each SNL program will be presented to the outside world as a Data Access property catalog. Available properties include diagnostics such as the number of connected/available member variables (if assigned to a PV), a list of all global variables assigned to PVs, and all existing (life) state set objects as subproperties. Properties of a state set include the current state (including the state's parameters), and member variables.

=== PVs ===

It might be a good idea to introduce a special data type to represent references to PVs. The idea is to make it possible to pass PV references as arguments to state sets (and states). With the way PVs are handled at the moment, i.e. declaring a variable and assigning it to a PV name, passing the variable would pass only the value of the variable, but not the PV itself.

We could mimick C++ template syntax and declare PVs like this:

pv<double> var("pv_name");

Now, <tt>var</tt> would be a PV object. The main point here is that it now has a type different from a plain <tt>double</tt>. Implicit conversion can be applied, so that assignment (from a <tt>double</tt> value) and usage within an expression (expecting a <tt>double</tt>) can be done as before:

double x = var;
var += 1.0;

Setting up a monitor and synchronizing with an event flag can be done exactly like before. However, we could now use <tt>var</tt> as a parameter to a state set instantiation:

call MyStateSet(var);

where the state set was declared as taking a PV as argument:

ss MyStateSet(pv<double> arg) {...}

An example could be a state set that generically handles setting or releasing brakes on a motor. On instantiation of the state set, it gets passed the motor (and possibly other) PVs as the actual parameters to work on. Without a special PV type this would only be possible by declaring an array of PVs and passing an index into this array to the state set.

== Implementation ==

We believe that our proposals can be implemented efficiently and without significantly changing the way SNL code is compiled currently. Of course, this remains to be proven.