RRM 3-14 Binary Output

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 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 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: 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 (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.

Address Specification presents more information on database addresses and links. Scanning Specification explains the effect of database linkage on scanning.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
DOL	Desired Output Location (Input Link)	INLINK	Yes	0	Yes	Yes	N/A	No
OMSL	Output Mode Select	menuOmsl	Yes	0	Yes	Yes	No	No

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 Soft Channel 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.

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

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.

ZNAM	ASCII string defining state zero
ONAM	ASCII string defining state one
HIGH	If this value is greater than zero, then whenever VAL is set equal to 1, it is reset to zero after HIGH seconds.
MASK	Raw value if VAL != 0

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 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 dbst 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 Address Specification for information on the format of database and channel access addresses. Also, see 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 get_enum_str record support routine can retrieve the state string corresponding to the VAL's state. So if the value is 1, get_enum_str will return the string in the ONAM field; and if 0, get_enum_str will return the ZNAM string.

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
ZNAM	Zero Name	STRING [20]	Yes	Null	Yes	Yes	No	Yes
ONAM	One Name	STRING [20]	Yes	Null	Yes	Yes	No	Yes
NAME	Record Name	STRING [29]	Yes	0	Yes	No	No	No
DESC	Description	STRING [29]	Yes	Null	Yes	Yes	No	No

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 NO_ALARM, MINOR, and MAJOR. 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 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
ZSV	Zero Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	Yes
OSV	One Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	Yes
COSV	Change of State Severity	menuAlarmSevr	Yes	0	Yes	Yes	No	Yes
IVOA	Invalid Alarm Output Action	menuIvoa	Yes	0	Yes	Yes	No	No
IVOV	Invalid Alarm Output Value	USHORT	Yes	0	Yes	Yes	No	No

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

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
ORAW	Old Raw Value	ULONG	No	0	Yes	No	No	No
RBV	Readback Value	ULONG	No	0	Yes	No	No	No
ORBV	Old Readback Value	ULONG	No	0	Yes	No	No	No
LALM	Last Alarmed Value	USHORT	No	0	Yes	No	No	No
MLST	Last Monitored Value	USHORT	No	0	Yes	No	No	No
RPVT	Record Private	NOACCESS	No	0	No	No	No	No
WDPT	Watchdog Pointer	NOACCESS	No	0	No	No	No	No

The following fields are used to operate the binary 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

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:

1. 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.
2. 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
3. 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.
4. Check severity and write the new value. See Invalid Alarm Output Action for more information on how INVALID alarms affect output.
5. 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.
6. Check WAIT. If VAL is 1 and WAIT is greater than 0, process again with a VAL=0 after WAIT seconds.
7. 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.
8. 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:

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
VAL	Value Field	This field is only of interest to device support routines that do not use MASK and RVAL.
OUT	Output Link	This field is used by the device support routines to locate its output.
RVAL	Raw Data Value	If MASK is defined then record support sets RVAL=(0,MASK) if VAL is (0, not zero).
MASK	Hardware mask.	The device support module must set this field. Not that if VAL is 1, then record processing sets RVAL = MASK.
RBV	Read Back Value	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.

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