RRM 3-14 Analog Output
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 Scan Fields. In addition, 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 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 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.
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 Address Specification for information on specifying links. Scanning Specification explains the effect of database linkage on scanning.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| OMSL | Output Mode Select | menuOmsl | Yes | 0 | Yes | Yes | No | No |
| DOL | Desired Output Location (an Input Link) | INLINK | Yes | 0 | No | No | N/A | No |
| OIF | Out Full or Incremental | aoOIF | Yes | 0 | Yes | Yes | No | No |
| DRVH | Drive High | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| DRVL | Drive Low | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| VAL | Value | DOUBLE | No | 0 | Yes | Yes | Yes | Yes |
| OROC | Maximum Output Rate of Change | DOUBLE | Yes | 0 | Yes | Yes | No | No |
| OVAL | Output Value | DOUBLE | No | 0 | Yes | Yes | Yes | No |
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| OUT | Output Link | OUTLINK | Yes | 0 | No | No | N/A | No |
| DTYP | Device Type | DEVCHOICE | Yes | 0 | Yes | No | No | |
| LINR | Type of Conversion | menuConvert | Yes | 0 | Yes | Yes | No | Yes |
| RVAL | Raw Value | LONG | No | 0 | Yes | Yes | Yes | Yes |
| ROFF | Raw Value Offset | LONG | No | 0 | Yes | Yes | No | Yes |
| EGUF | Engineering Units Full | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| EGUL | Engineering Units Low | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| AOFF | Adjustment Offset | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| ASLO | Adjustment Slope | DOUBLE | Yes | 1 | Yes | Yes | No | Yes |
| ESLO | Slope for Linear Conversions | DOUBLE | Yes | 1 | Yes | No | No | No |
| EOFF | Offset for Linear Conversions | DOUBLE | Yes | 0 | Yes | No | No | No |
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.
| EGUF | 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 Conversion Specification for more information on how to calculate these fields. |
| EGUL | |
| AOFF | These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units. |
| ASLO | |
| ESLO | 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. |
| EOFF | |
| ROFF | 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. |
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 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 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 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 Fields Common to All Record Types for more on the record name (NAME) and description (DESC) fields.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| EGU | Engineering Units | STRING [16] | Yes | null | Yes | Yes | No | No |
| HOPR | High Operating Range | DOUBLE | Yes | 0 | Yes | Yes | No | No |
| LOPR | Low Operating Range | DOUBLE | Yes | 0 | Yes | Yes | No | No |
| PREC | Display Precision | SHORT | Yes | 0 | Yes | Yes | No | No |
| NAME | Record Name | STRING [29] | Yes | 0 | Yes | No | No | No |
| DESC | Description | STRING [29] | Yes | Null | Yes | Yes | No | No |
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 Alarm Specification for a complete explanation of alarms and these fields. See Invalid Alarm Output Action for more information on the IVOA and IVOV fields. Alarm Fields lists other fields related to a alarms that are common to all record types.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| HIHI | Hihi Alarm Limit | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| HIGH | High Alarm Limit | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| LOW | Low Alarm Limit | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| LOLO | Lolo Alarm Limit | DOUBLE | Yes | 0 | Yes | Yes | No | Yes |
| HHSV | Hihi Alarm Severity | menuAlarmSevr | Yes | 0 | Yes | Yes | No | Yes |
| HSV | High Alarm Severity | menuAlarmSevr | Yes | 0 | Yes | Yes | No | Yes |
| LSV | Low Alarm Severity | menuAlarmSevr | Yes | 0 | Yes | Yes | No | Yes |
| LLSV | Lolo Alarm Severity | menuAlarmSevr | Yes | 0 | Yes | Yes | No | Yes |
| HYST | Alarm Deadband | DOUBLE | Yes | 0 | Yes | Yes | No | No |
| IVOA | Invalid Alarm Output Action | menuIvoa | Yes | 0 | Yes | Yes | No | No |
| IVOV | Invalid Alarm Output Value, in eng. units | DOUBLE | Yes | 0 | Yes | Yes | No | No |
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 Monitor Specification for a complete explanation of monitors.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| ADEL | Archive Deadband | DOUBLE | Yes | 0 | Yes | Yes | No | No |
| MDEL | Monitor, i.e. value change, Deadband | DOUBLE | Yes | 0 | Yes | Yes | No | No |
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| ORAW | Old Raw Value | LONG | No | 0 | Yes | No | No | No |
| RBV | Read Back Value | LONG | No | 0 | Yes | No | Yes | No |
| ORBV | Old read back value | LONG | No | 0 | Yes | No | No | No |
| LALM | Last Alarm Monitor Trigger Value | DOUBLE | No | 0 | Yes | No | No | No |
| ALST | Last Archiver Monitor Trigger Value | DOUBLE | No | 0 | Yes | No | No | No |
| MLST | Last Value Change Monitor Trigger Value | DOUBLE | No | 0 | Yes | No | No | No |
| INIT | Initialize | SHORT | No | 0 | Yes | No | No | No |
| PBRK | Address of Breakpoint Table | NOACCESS | No | 4 | No | No | No | |
| LBRK | Last Breakpoint | SHORT | No | 0 | Yes | No | No | No |
| PVAL | Previous Data Value | DOUBLE | No | 0 | Yes | No | No | No |
| OMOD | OVAL modified? | LONG | No | Null | Yes | No | No | No |
The following fields are used to operate the analog output in the simulation mode. See Fields Common to Many Record Types for more information on these fields.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| SIOL | Simulation Value Location | INLINK | Yes | 0 | No | No | N/A | No |
| SIML | Simulation Mode Location | INLINK | Yes | 0 | No | No | N/A | No |
| SIMM | Simulation Mode | menuSimm | No | 0 | Yes | Yes | No | No |
| SIMS | Simulation Mode Alarm Severity | menuAlarmSevr | Yes | 0 | Yes | Yes | No | No |
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.
- fetch_values:
- 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 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:
| Name | Summary | Description |
|---|---|---|
| PACT | Processing Active | See Fields Common to All Record Types for an explanation of these fields. |
| DPVT | Device Private | |
| NSEV | New Alarm Severity | |
| NSTA | New Alarm Status | |
| OUT | Output Link | This field is used by the device support routines to locate its output. |
| EGUF | Engineering Units Full | These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits. |
| EGUL | Engineering Unit Low | |
| ESLO | Slope | 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. |
| EOFF | Offset | |
| RVAL | Raw Value | This is the value to write to OUT. |
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 Soft Output for details.
Raw Soft Channel
This module is like the previous except that it writes the current value of RVAL.
