RRM 3-13 Binary Input
bi - Binary Input
Introduction
The normal use for this record type is to obtain a binary value of 0 or 1. Most device support modules obtain values from hardware and place the value in RVAL. For these devices record processing sets VAL = (0,1) if RVAL is (0, not 0). Devices support modules may optionally read a value directly into VAL.
Soft device modules are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. Two soft device support modules are provided: Soft Channel and Raw Soft Channel. The first allows VAL to be an arbitrary unsigned short integer. The second reads the value into RVAL just like normal hardware modules.
The binary input's fields fall into the following categories:
- scan parameters
- read and convert parameters
- operator display parameters
- alarm parameters
- run-time parameters
Scan Parameters
The binary input 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, Chapter 1, 1, 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
The read and convert fields determine from where the binary input gets its input from and how to convert the raw signal to engineering units. The INP field contains the address from where device support retrieves the value. If the binary input record gets its value from hardware, the address of the card must be entered in he INP field, and the name of the device support module must be entered in the DTYP field. See Address Specification, Chapter 1, 2, 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 (R3.13).
For records that specify the Soft Channel or Raw Soft Channel device support routines, the INP field can be a channel or database access link, or a constant. If a constant, VAL can be changed directly by dbPuts. See Address Specification, Chapter 1, 2, for information on the format of database and channel access addresses. Also, see Device Support for Soft Records in this chapter for more information on soft device support.
If the record gets its value from hardware or uses the Raw Soft Channel device support, the device support routines place the value into the RVAL field which is then converted using the process described in the next section.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| INP | Input Link | INLINK | Yes | 0 | No | No | N/A | No |
| DTYP | Device Type | DEVCHOICE | Yes | 0 | 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 |
| RVAL | Raw Value | ULONG | No | 0 | Yes | Yes | Yes | Yes |
| VAL | Value Field | ENUM | No | 0 | Yes | Yes | Yes | Yes |
Conversion Fields
The VAL field is set equal to (0, 1) if the RVAL field is (0, not 0), unless the device support module reads a value directly into VAL or the Soft Channel device support is used. The value can also be fetched as one of the strings specified in the ZNAM or ONAM fields. The ZNAM field has the string that corresponds to the 0 state, so when the value is fetched as this string, put_enum_str will return a 0 will. The ONAM field holds the string that corresponds to the 1 state, so when the value is fetched as this string, put_enum_str returns a 1.
| ZNAM | ASCII string defining state zero |
| ONAM | ASCII string defining state one |
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 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 if the binary input is in alarm condition and to determine the severity of that condition. The possible alarm conditions for binary inputs are the SCAN, READ state alarms, and change of state alarm. The SCAN and READ alarms are called by the device support routines.
The user can choose the severity for each state in the ZSV and OSV. 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 causes an alarm whenever the state changes between 0 and 1 and the severity is configured as MINOR or MAJOR.
See Alarm Specification, Chapter 1, 4, for a complete explanation of discrete alarm states. 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 | GBLCHOICE | Yes | 0 | Yes | Yes | No | Yes |
| OSV | One Severity | GBLCHOICE | Yes | 0 | Yes | Yes | No | Yes |
| COSV | Change of State Severity | GBLCHOICE | Yes | 0 | Yes | Yes | No | Yes |
Run-time Parameters and Simulation Mode Parameters
These parameters are used by the run-time code for processing the binary input. They are not configured using a database configuration tool.
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. This value is used to manipulate the record's value, but is only the concern of the hardware device support routines.
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| ORAW | Old Raw Value | ULONG | No | 0 | Yes | No | No | No |
| MASK | Hardware mask | ULONG | No | compute | 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 |
The following fields are used to operate the binary input 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 |
| SVAL | Simulation Value | DOUBLE | No | 0 | Yes | Yes | No | No |
| SIML | Simulation Mode Location | INLINK | Yes | 0 | No | No | N/A | No |
| SIMM | Simulation Mode | GBLCHOICE | No | 0 | Yes | Yes | No | No |
| SIMS | Simulation Mode Alarm Severity | GBLCHOICE | Yes | 0 | Yes | Yes | No | No |
Record Support Routines
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 routine is defined. If either does not exist, an error message is issued and processing is terminated.
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_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.
- readValue is called. See Input Records for details.
- If PACT has been changed to TRUE, the device support read routine has started but has not completed reading a new input value. In this case, the processing routine merely returns, leaving PACT TRUE.
- Convert
status=read_bi PACT = TRUE TIME = tslocaltime if status is 0, then set VAL=(0,1) if RVAL is (0, not 0) and UDF = False if status is 2, set status = 0
- Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV and NSTA and LALM are set. Note that if VAL is greater than 1, no checking is performed.
- 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 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 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 input value whenever read_bi 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 | |
| UDF | VAL Undefined | |
| NSEV | New Alarm Severity | |
| NSTA | New Alarm Status | |
| VAL | Value Field | This field is set by a device support routines only if it doesn't want record support to set it. |
| INP | Input Link | This field is used by the device support routines to locate its input. |
| RVAL | Raw Value | It is the responsibility of the device support routine to give this field a value. |
| MASK | Hardware mask. | The device support routine must give this field a value if it needs to use it. |
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_bi
read_bi(precord)
This routine must provide a new input value. It returns the following values:
- 0: Success. A new raw value is placed in RVAL. The record support module forces VAL to be (0,1) if RVAL is (0, not 0).
- 2: Success, but don't modify VAL.
- other: Error.
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
read_bi always returns a value of 2, which means that no conversion is performed.
If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. VAL can be changed via dbPut requests. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.
read_bi calls recGblGetLinkValue to read the current value of VAL. See Soft Input for details.
If the return status of recGblGetLinkValue is zero, then read_bi sets UDF to FALSE. The status of recGblGetLinkValue is returned.
Raw Soft Channel
This module is like the previous except that values are read into RVAL.
read_bi returns a value of 0. Thus the record processing routine will force VAL to be 0 or 1.
EPICS Record Reference Manual - 19 MAY 1998
