RRM 3-14 Concepts

EPICS Record Reference Manual

Database Concepts

This chapter covers the general functionality that is found in all database records. The topics covered are I/O scanning, I/O address specification, data conversions, alarms, database monitoring, and continuous control:

• Scanning Specification describes the various conditions under which a record is processed.
• Address Specification explains the source of inputs and the destination of outputs.
• Conversion Specification covers data conversions from transducer interfaces to engineering units.
• Alarm Specification presents the many alarm detection mechanisms available in the database.
• Monitor Specification details the mechanism which notifies operators about database value changes.
• Control Specification explains the features available for achieving continuous control in the database.

These concepts are essential in order to understand how the database interfaces with the process.

The EPICS databases can be created using visual tools (VDCT, CapFast) or by manual creation of a database "myDatabase.db" text file. Visual Database Configuration Tool (VDCT), a java application from Cosylab, is a more modern tool for database creation/editing that runs on Linux, Windows, and Sun.

Scanning Specification

Scanning determines when a record is processed. A record is processed when it processes its data and performs any actions related to that data. For example, when an output record is processed, it fetches the value which it is to output, converts the value, and then writes that value to the specified location. Each record must specify the scanning method that determines when it will be processed. There are three scanning methods for database records: (1) periodic, (2) event, and (3) passive.

1. Periodic scanning occurs on set time intervals.
2. Event scanning occurs on either an I/O interrupt event or a user-defined event.
3. Passive scanning occurs when the records linked to the passive record are scanned, or when a value is "put" into a passive record through the database access routines.

For periodic or event scanning, the user can also control the order in which a set of records is processed by using the PHASE mechanism. For event scanning, the user can control the priority at which a record will process. In addition to the scan and the phase mechanisms, there are data links and forward processing links that can be used to cause processing in other records. This section explains these concepts.

Periodic Scanning

The following periods for scanning database records are available, though EPICS can be configured to recognize more scan periods:

• 10 second
• 5 second
• 2 second
• 1 second
• .5 second
• .2 second
• .1 second

The period that best fits the nature of the signal should be specified. A five-second interval is adequate for the temperature of a mass of water because it does not change rapidly. However, some power levels may change very rapidly, so they need to be scanned every 0.5 seconds. In the case of a continuous control loop, where the process variable being controlled can change quickly, the 0.1 second interval may be the best choice.

For a record to scan periodically, a valid choice must be entered in its SCAN field. Actually, the available choices depend on the configuration of the menuScan.dbd file. As with most other fields which consists of a menu of choices, the choices available for the SCAN field can be changed by editing the appropriate .dbd (database definition) file. dbd files are ASCII files that are used to generate header files that are, in turn, are used to compile the database code. Many dbd files can be used to configure other things besides the choices of menu fields.

Here is an example of a menuScan.dbd file, which has the default menu choices for all periods listed above as well as choices for event scanning, passive scanning, and I/O interrupt scanning:

menu(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")
}

The first three choices must appear first and in the order shown. The remaining definitions are for the periodic scan rates, which must appear in the order slowest to fastest (the order directly controls the thread priority assigned to the particular scan rate, and faster scan rates should be assigned higher thread priorities). At IOC initialization, the menu choice strings are read at scan initialization. The number of periodic scan rates and the period of each rate is determined from the menu choice strings. Thus periodic scan rates can be changed by changing menuScan.dbd and loading this version via dbLoadDatabase. The only requirement is that each periodic choice string must begin with a numeric value specified in units of seconds.For example, to add a choice for 0.019 seconds, add the following line after the 0.1 second choice:

	choice(menuScan_015_second, " .015 second")

The range of values for scan periods can be from one clock tick. (vxWorks out of the box supports 0.015 seconds or a maximum period of 60 Hz), to the maximum number of ticks available on the system. Note, however, that the order of the choices is essential. The first three choices must appear in the above order. Then the remaining choices should follow in descending order, the biggest time period first and the smallest last.

Event Scanning

There are two types of events supported in the input/output controller (IOC) database, the I/O interrupt event and the user-defined event. For each type of event, the user can specify the scheduling priority of the event using the PRIO or priority field. The scheduling priority refers to the priority the event has on the stack relative to other running tasks. There are three possible choices: LOW, MEDIUM, or HIGH. A low priority event has a priority a little higher than Channel Access. A medium priority event has a priority about equal to the median of periodic scanning tasks. A high priority event has a priority equal to the event scanning task.

I/O Interrupt Events

Scanning on I/O interrupt causes a record to be processed when a driver posts an I/O Event. In many cases these events are posted in the interrupt service routine. For example, if an analog input record gets its value from a Xycom 566 Differential Latched card and it specifies I/O interrupt as its scanning routine, then the record will be processed each time the card generates an interrupt (not all types of I/O cards can generate interrupts). Note that even though some cards cannot actually generate interrupts, some driver support modules can simulate interrupts. In order for a record to scan on I/O interrupts, its SCAN field must specify I/O Intr.

User-defined Events

The user-defined event mechanism processes records that are meaningful only under specific circumstances. User-defined events can be generated by the post_event() database access routine. Two records, the event record and the timer record, are also used to post events. For example, there is the timing output, generated when the process is in a state where a control can be safely changed. Timing outputs are controlled through Timer records, which have the ability to generate interrupts. Consider a case where the timer record is scanned on I/O interrupt and the timer record's event field (EVNT) contains an event number. When the record is scanned, the user-defined event will be posted. When the event is posted, all records will be processed whose SCAN field specifies event and whose event number is the same as the generated event. User-defined events can also be generated through software. Event numbers are configurable and should be controlled through the project engineer. They only need to be unique per IOC because they only trigger processing for records in the same IOC.

All records that use the user-defined event mechanism must specify Event in their SCAN field and an event number in their EVNT field.

Passive Scanning

Passive records are processed when the are referenced by other records through their link fields or when a channel access put is done to them.

Channel Access Puts to Passive Scanned Records

In this case where a channel access put is done to a record, the field being written has an attribute that determines if this put causes record processing. In the case of all records, putting to the VAL field causes record processing. Consider a binary output that has a SCAN of Passive. If an operator display has a button on the VAL field, every time the button is pressed, a channel access put is sent to the record. When the VAL field is written, the Passive record is processed and the specified device support is called to write the newly converted RVAL to the device specified in the OUT field through the device support specified by DTYP. Fields determined to change the way a record behaves, typical cause the record to process. Another field that would cause the binary output to process would be the ZSV; which is the alarm severity if the binary output record is in state Zero (0). If the record was in state 0 and the severity of being in that state changed from No Alarm to Minor Alarm, the only way to catch this on a SCAN Passive record is to process it. Fields are configured to cause binary output records to process in the bo.dbd file. The OSV severity is configured as follows:

field(ZSV,DBF_MENU) {

prompt("Zero Error Severity")

promptgroup(GUI_ALARMS)

pp(TRUE)

interest(1)

menu(menuAlarmSevr)

}

where the line "pp(TRUE)" is the indication that this record is processed when a channel access put is done.

Database Links to Passive Record

The records in the process database use link fields to configure data passing and scheduling (or processing). These fields are either INLINK, OUTLINK, or FWDLINK fields.

Forward Links

In the database definition file (.dbd) these fields are defined as follows:

field(FLNK,DBF_FWDLINK) {

prompt("Forward Process Link")

promptgroup(GUI_LINKS)

interest(1)

}

If the record that is referenced by the FLNK field has a SCAN field of Passive, then the record is processed after the record with the FLNK. The FLNK field only causes record processing, no data is passed. In the Figure 2, three records are shown. The ai record "Input_2" is processed periodically. At each interval, Input_2 is processed. After Input_2 has read the new input, converted it to engineering units, checked the alarm condition, and posted monitors to Channel Access, then the calc record "Calculation_2" is processed. Calculation_2 reads the input, performs the calculation, checked the alarm condition, and posted monitors to Channel Access, then the ao record "Output_2" is processed. Output_2 reads the desired output, rate limits it, clamps the range, calls the device support for the OUT field, checks alarms, posts monitors and then is complete.

Figure 1

A more complex use of passive scanning causes passive records to inherit the scan traits of the records to which they are connected. Let's look at the simple case (Figure 2) where two analog input records (AI) get their input from the VAL field of a calculation record (CALC). Each analog input (Record_3, Record_4) has a forward link (FLNK) pointing to the calculation record (Record_5). In VDCT, FLNKs connect directly to another record, unlike CapFast where FLNK connects to SLNK field. However, this is just a way to specify to which record FLNK points to. In EPICS, a FLNK of Record_3 and Record_4 merely contains the name of another record (Record_5).

Input Links

Input links normally fetch data from one field into a field in the referring record. For instance, if the INPA field of a CALC record is set to Input_2.VAL, then the VAL field is fetched from the Input_2 record and placed in the A field of the CALC record. These data links have an attribute that can cause the record to be processed before the field is returned. In figure 2,

Figure 1

For example, Figure 1 presents a VDCT schematic of two records, Record_1 and Record_2. Record_1 is an analog output record. Most output records have a DOL or Desired Output Link, from which they can retrieve the value that they output. Thus, the DOL link is an input link which can be process passive. The blue line connecting the records is a data link. In this case it means that the DOL link is connected to the VAL field of Record_2. In other words, Record_1 retrieves its value, the value that it outputs, from Record_2. When Record_1 begins processing, it will first retrieve the value from the field connected to DOL, which, in this case, is the VAL field of Record_2. If DOL is process passive, it will cause Record_1 to be processed when the value is retrieved. Record_2 will then process. After Record_1 finishes processing, the value from its VAL field will be retrieved by DOL. Record_1 will then finish its processing.

If NPP is specified as an input link's attribute, the value is retrieved as is from the other record without causing the other record to process. So in the above example, if DOL didn't specify process passive, record 1 would not cause record 2 to process.

Let's consider a few more examples of passive scanning.

Consider a case where an analog output is controlled only by the operator. There is no reason to process this record until the operator changes the desired output. (This is done by writing to the VAL field.) If this record is passive, the database access routine that places the new desired output into the record will cause it to be processed immediately.

The calculation record's SCAN field specifies Passive, the SCAN field of the analog input Record_3 specifies 2 second, and the SCAN field of the analog input Record_4 specifies I/O Intr. In this example the calculation will be processed every two seconds and whenever the I/O card interrupts. Thus, the calculation inherits the periodic scanning trait of the first analog input record and the I/O event scanning trait of the second. Each time the calc record Record_5 is processed, it will retrieve values from the locations specified in its input links and perform its calculation.

Description

Next, let's look at a continuous control loop (Figure 3). In this case the analog input Record_6, which is scanned every 0.1 seconds, has a forward link to the calculation record Record_7, and the calculation record, in turn, has a forward link to the analog output Record_8. Every 0.1 seconds the analog input will process, converting its value and causing the calc record to process. The calc record will make its calculation, causing the analog output record to process. The analog output will then write its output after fetching, if necessary, its desired output. If the operator changes a value in the calculation, this will also cause the calc record to perform its calculation and the analog output to write its output, since the calc and the analog output record are passive.

Figure 3

Let's consider a case (Figure 4) where values are fetched from other records via input links. When a record fetches a value from another record, the other record is first processed, only if the other record is passive and only if the link specifies process passive or PP. As an example, suppose a calculation record Record_11 has two input links, each of which specifies an analog input record (Record_9, Record_10) and each of which specifies process passive (PP). Suppose also that the calculation record specifies 1 second in its SCAN field, meaning that it is scanned every second. Every second, the calc record will cause each analog input to process before fetching the values, provided that each analog input specifies Passive in its SCAN field.

Figure 4

In a variation of this example (Figure 5), suppose one of the analog inputs Record_13 specifies 2 second in its SCAN field which means it would no longer be a passive record. Thus, the periodically scanned analog input will not be processed every time the calculation is processed. Its current value will simply be fetched as is; then the other analog input Record_12 will be processed and the calculation performed. The same thing would occur if the calculation's INPB link of calc Record_14 specified NPP or no process passive. In this case, even if the analog input's SCAN field specified Passive, the value would be fetched as is without causing the analog input to process.

Figure 5

Passive Scanning and Channel Access Links

Passive scanning differs somewhat for Channel Access links. A Channel Access link is an input link or output link that specifies a link to a record located in another IOC (a forward processing link can be a CA link under certain circumstances). In addition, as of Release 3.13 input and output links can be forced to be Channel Access links even if they reference a record located in the same database. Input links can specify CA, CP, or CPP. If the input link specifies CA, it will be forced to be a Channel Access link. If the input link specifies CP, it will also be forced to be a Channel Access link; in addition, it will cause the record containing the input link to process whenever a monitor is posted, no matter what the record's SCAN field specifies. If the input link specifies CPP, it means the same thing as CP, except that the record will be processed if and only if the record itself specifies passive in its SCAN field. Output links can specify CA, which will simply cause them to be Channel Access links.

Channel Access links, be they between records located in different IOCs or between records located in the same IOC, cannot be process passive, e.g., they cannot cause the record they specify to process when written to or read from.

Phase

The PHAS field is used to order the processing of records that are scanned at the same time, i.e., records that are scanned periodically at the same interval and priority, or that are scanned on the same event. In this manner records dependent upon other records can be assured of using current data.

To illustrate this we will look at an example from the previous section, with the records, however, being scanned periodically instead of passively (Figure 6). In this example each of these records specifies .1 second; thus, the records are synchronous. The phase sequence is used to assure that the analog input is processed first, meaning that it fetches its value from the specified location and places it in the VAL field (after any conversions). Next, the calc record will be processed, retrieving its value from the analog input and performing its calculation. Lastly, the analog output will be processed, retrieving its desired output value from the calc record's VAL field (the VAL field contains the result of the calc record's calculations) and writing that value to the location specified it its OUT link. In order for this to occur, the PHAS field of the analog input record must specify 0, the PHAS field of the calculation record must specify 1, and the analog output's PHAS field must specify 2.

Figure 6

It is important to understand that in the above example, no record causes another to be processed. The phase mechanism instead causes each to process in sequence.

Forward Process Links

When the forward processing link field (FLNK) of one record contains an address of a second record, it causes the second record to be processed after the first record is itself processed.

We discussed forward links in the section on passive processing. To reiterate, this field causes the record that it specifies to be scanned when the record that contains the forward link is scanned. It is thus used to cause related records to process. (For more on specifying records in link fields, see Address Specification).

If a forward link references the PROC field of a record in another IOC, a Channel Access " put" request is directed to the specified record, causing it to process.

One record type exists solely to propagate forward processing: the fanout record. The fanout record is used when there is more than one record which needs to be processed as a result of another record being processed. It can specify as many as six forward links. Let's look at an example where an analog input's value is used in two different calculations (Figure 7). Because there is only one forward processing link in the analog input record, it is used to process the fanout record. Here two of the fanout records forward links are used to link to two calculation records. In the example, when the I/O interrupt occurs, the analog input is processed, then the fanout record is processed, causing each of the calculation records to be processed. Note that the fanout record simply causes the specified records to process. It does not send values to other records. The data fanout record, on the other hand, does send values to other records. Refer to Fanout, and dfanout, for more information on the fanout and data fanout records.

Figure 7

Address Specification

Address parameters specify where an input record obtains input, where an output record obtains its desired output values, and where an output record writes its output. They are used to identify links between records, and to specify the location of hardware devices. The most common link fields are OUT, an output link, INP, an input link, and DOL (desired output location), also an input link.

There are three basic types of address specifications which can appear in these fields: hardware addresses, database addresses, and constants.

Note: Not all links support all three types, though some do. However, this doesn't hold true for algorithmic records, which cannot specify hardware addresses. Algorithm records are records like the Calculation, PID, and Select records. These records are used to process values retrieved from other records. Consult the documentation for each record consult.

Hardware Addresses

Hardware addresses are used to specify input and output connections to hardware devices. They give the information needed by the IOC to interface to the instrumentation. There are currently eight I/O buses supported: VME, Allen-Bradley, CAMAC, GPIB, BITBUS, INST, VXI, and RF. The input specification for each of these is different.

VME Bus

The VME address specification format differs between the various devices. In all of these specifications the '#' character designates a hardware address. The three formats are:

#Cx Sy @parm

For analog in, analog out, and timer

• C precedes the card number x
• S precedes the signal number y
• @ precedes optional string parm

The card number in the VME addresses refers to the logical card number. Card numbers are assigned by address convention; their position in the backplane is of no consequence. The addresses are assigned by the technician who populates the backplane, with the logical numbers well-documented. The logical card numbers start with 0 as do the signal numbers. parm refers to an arbitrary string of up to 31 characters and is device specific.

Allen-Bradley Bus

The Allen-Bradley address specification is a bit more complicated as it has several more fields. The '#' designates a hardware address. The format is:

#La Ab Cc Sd @parm'

All record types

• L precedes the serial link number a and is optional - default 0
• A precedes the adapter number b and is optional - default 0
• C precedes the card number c
• S precedes the signal number d
• @ precedes optional string parm

The card number for Allen-Bradley I/O refers to the physical slot number, where 0 is the slot directly to the right of the adapter card. The Allen-Bradley I/O has 12 slots available for I/O cards numbered 0 through 11. Allen-Bradley I/O may use double slot addresses which means that slots 0,2,4,6,8, and 10 are used for input modules and slots 1,3,5,7,9 and 11 are used for output modules. It's required to use the double slot addressing mode when the 1771IL card is used as it only works in double slot addressing mode. This card is required as it provides Kilovolt isolation.

Camac Bus

The CAMAC address specification is similar to the Allen-Bradley address specification. The '#' signifies a hardware address. The format is:

#Ba Cb Nc Ad Fe @parm

For waveform digitizers

• B precedes the branch number a
• C precedes the crate number b
• N precedes the station number c
• A precedes the subaddress d (optional)
• F precedes the function e (optional)
• @ precedes optional string parm

The waveform digitizer supported is only one channel per card; no channel was necessary.

Others

The GPIB, INST, BITBUS, RF, and VXI card-types have been added to the supported I/O cards. A brief description of the address format for each follows. For a further explanation, see the specific documentation on each card.

#La Ab @parm

For GPIB I/O

• L precedes the link number a
• A precedes the GPIB address b
• @ precedes optional string parm

#La Nb Pc Sd @parm

For BITBUS I/O

• L precedes the link a, i.e., the VME bitbus interface
• N precedes the bitbus node b
• P precedes the port on node c
• S precedes the signal on port d
• @ precedes optional string parm

#@parm

For INST I/O

• @ precedes optional string parm

#Va Cb Sc @parm

For VXI I/O, dynamic addressing

• V precedes the VXI frame number a
• C precedes the slot within VXI frame b
• S precedes the signal number c
• @ precedes optional string parm

#Va Sb @parm

For VXI I/O, static addressing

• V precedes the logical address a
• S precedes the signal number b
• @ precedes optional string parm

Database Addresses

Database addresses are used to specify input links, desired output links, output links, and forward processing links. The format in each case is the same:

<RecordName>.<FieldName>

where RecordName is simply the name of the record being referenced and FieldName is the name of the field within the record.

The record name and field name specification are case sensitive. The record name entered in Capfast (or whatever other configuration tool) can be a mix of upper and lower case letters. The field name is always upper case. If no field name is specified as part of an address, the value field (VAL) of the record is assumed. Forward processing links do not need to include the field name because no value is returned when a forward processing link is used; therefore, a forward processing link need only specify a record name.

For inputs and desired output links, the specified record is processed before the value has been read, and for output links the specified record is processed after the value has been written. In the case of the forward processing link, the record being referenced is processed after the record making the link is processed.

Remember that input links such as INP and DOL (desired output location), can specify process passive (PP) or no process passive (NPP). When a record's input link specifies a database address, the record specified by the address will process only if the input link specifies process passive and only if the addressed record specifies Passive in its SCAN field. If the input link specifies no process passive (NPP), the addressed record will not be processed even if it is a passive record. Because output links such as OUT are always process passive, they always cause the specified record to be processed, provided that the specified record's SCAN field is configured as Passive.

Basic typecast conversions are made automatically when a value is retrieved from another record--integers are converted to floating point numbers and floating point numbers are converted to integers. For example, a calculation record which uses the value field of a binary input will get a floating point 1 or 0 to use in the calculation, because a calculation record's value fields are floating point numbers. If the value of the calculation record is used as the desired output of a multi-bit binary output, the floating point result is converted to an integer, because multi-bit binary outputs use integers.

Be aware that other types of conversions may not be made when a value is retrieved from another record. Whether it does or doesn't depends on the record and the device support routine which the record specifies. Most records must specify a device support routine in their DTYP field. Device support routines take care of the specifics of input and output. For such records, there are device support routines for hardware I/O, and other routines for I/O between records. For example, the analog input has many device support routines for input from hardware, and two routines specific for retrieving input from other records: Soft Channel and Raw Soft Channel. Raw Soft Channel retrieves the input value and performs the specified linear conversions on the value (that is, if the record is configured to perform linear conversions). The Soft Channel device support routine, on the other hand, reads the value directly into the VAL field and doesn't perform any linear conversions on the value.

Records that use soft device support routines or have no hardware device support routines are called soft records. See the chapter on each record for information about that record's device support.

Channel Access Links

Note: Link fields can reference records in a different database, that is, a database that resides in a different IOC. Records residing on different IOCs connect through channel access, so any link that refers to a record in another IOC is called a channel access link. The format of a channel access link does not differ from that of a regular database link. Channel access links are created when the database is initialized. When the initialization routines cannot find the link in the local database, a channel access link is created.

As of Release 3.13.0, input and output links can also be forced to be Channel Access links, even when they are located in the same IOC. Input links can specify either CA, CP, or CPP. Specifying CA forces the input link to be a Channel Access link. When an input link becomes a Channel Access link, a Channel Access monitor is established on the field and a buffer is allocated for the field using the field type and the element count of the field. In addition to the value of the input link, the alarm status of the link is monitored. Specifying CP or CPP also forces the input link to be a Channel Access link, but in addition, CP or CPP will force the record that contains the link to be processed when a monitor occurs, that is, if the record is process passive.

Output links can also specify CA, in which case they will be forced to be Channel Access links. When an output link becomes a Channel Access link, a buffer is allocated the first time a "put" operation occurs on the record containing the link. Each time a "put" occurs for the record, the data is retrieved from the buffer. And the buffer is updated. The CP and CPP options are not available for output links.

Forward links can also be Channel Access links, either when they specify a record located in another IOC or when they specify the CA attributes. However, forward links will only be made Channel Access links if they specify the PROC field of another record.

Because of the nature of Channel Access links, they cannot be process passive. For example, if an input link that specifies another record in another IOC but also specifies PP, the PP attribute will be ignored. Another aspect of Channel Access links is that they are never placed in the same lock set as the records they link to.

Constants

Input link fields and desired output location fields can specify a constant instead of a hardware or database address. A constant, which is not really an address, can be an integer value in whatever format (hex, decimal, etc.) or a floating-point value. The value field is initialized to the constant when the database is initialized, and at run-time the value field can be changed by a database access routine. For instance, a constant may be used in an input link of a calculation record. For non-constant links, the calc record retrieves the values from the input links, and places them in a corresponding value field. For constant links, the value fields are initialized with the constant, and the values can be changed by modifying the value field, not the link field. Thus, because the calc record uses its value fields as the operands of its expression, the constant becomes part of the calculation.

When nothing is specified in a link field, it is a NULL link. Before Release 3.13, the value fields associated with the NULL link were initialized with the value of zero. As of Release 3.13, the value fields associated with the links are not initialized

A constant may also be used in the desired output location or DOL field of an output record. In such a case, the initial desired output value (VAL) will be that constant. Any specified conversions are performed on the value before it is written as long as the device support module supports conversions (the Soft Channel device support routine does not perform conversions). The desired output value can be changed by an operator at run-time by writing to the value field.

A constant can be used in an output link field, but no output will be written if this is the case. Be aware that this is not considered an error by the database checking utilities.

Conversion Specification

Conversion parameters are used to convert transducer data into meaningful data. Discrete signals require converting between levels and states (i.e., on, off, high, low, etc.). Analog conversions require converting between levels and engineering units (i.e., pressure, temperature, level, etc.). These conversions are made to provide operators and application codes with values in meaningful units.

The following sections discuss these types of conversions. The actual field names appear in capital letters.

Discrete Conversions

The most simple type of discrete conversion would be the case of a discrete input that indicates the on/off state of a device. If the level is high it indicates that the state of the device is on. Conversely, if the level is low it indicates that the device is off. In the database, parameters are available to enter strings which correspond to each level, which, in turn, correspond to a state (0,1). By defining these strings, the operator is not required to know that a specific transducer is on when the level of its transmitter is high or off when the level is low. In a typical example, the conversion parameters for a discrete input would be entered as follows:

Zero Name (ZNAM):

Off

One Name (ONAM):

On

The equivalent discrete output example would be an on/off controller. Let's consider a case where the safe state of a device is On, the zero state. The level being low drives the device on, so that a broken cable will drive the device to a safe state. In this example the database parameters are entered as follows:

Zero Name (ZNAM):

On

One Name (ONAM):

Off

By giving the outside world the device state, the information is clear. Binary inputs and binary outputs are used to represent such on/off devices.

A more complex example involving discrete values is one that has many states such as a multi-bit binary output record. Consider a motor which has four states--off, low, medium, and high. A device of this type may have three control lines and three more monitor lines. Each line represents one of the on states (low, medium, or high). The bit pattern for each control state is entered into the database with the string that describes that state. The database parameters for the monitor would be entered as follows:

Number of Bits (NOBT):

3

First Input Bit Spec (INP):

Address of the least significant bit

Zero Value (ZRVL):

0

One Value (ONVL):

1

Two Value (TWVL):

2

Three Value (THVL):

4

Zero String (ZRST):

Off

One String (ONST):

Low

Two String (TWST):

Medium

Three String (THST):

High

In this case, when the database record is scanned, the monitor bits are read and compared with the bit patterns for each state. When the bit pattern is found, the device is set to that state. For instance, if the three monitor bits read equal 0100 (4), the three value is the corresponding value, and the device would be set to state 3 which drives the device to its high level. The value can be displayed as an integer, in which case the value would be 3, or as a string, in which case the value would be 'High'.

If the bit pattern is not found, the device is in an unknown state. For instance, if the three monitor bits read equal 0111 (7) and there are no equivalent values, then the value is set to -1, the condition of the record is set to UNKNOWN alarm, and the alarm severity is set to whatever alarm severity is configured for the unknown state (see Alarm Specification).

In addition, the DOL fields of binary output records (bo and mbbo) will accept values in strings. When they retrieve the string or when the value field is given a string via put_enum_strs, a match is sought with one of the states. If a match is found, the value for that state is written.

Analog Conversions

Analog conversions require knowledge of the transducer, the filters, and the I/O cards. Together they measure the process, transmit the data, and interface the data to the IOC. Smoothing is available to filter noisy signals. The smoothing argument is a constant between 0 and 1 and is specified in the SMOO field. It is applied to the converted hardware signal as follows:

eng units = (new eng units × (1 - smoothing)) + (old eng units × smoothing)

The analog conversions from raw values to engineering units can be either linear or breakpoint conversions.

Whether an analog record performs linear conversions, breakpoint conversions, or no conversions at all depends on how the record's LINR field is configured. The possible choices for the LINR field are as follows:

• LINEAR
• NO CONVERSION
• typeKdegF
• typeKdegC
• typeJdegF
• typeJdegC

If LINEAR is chosen, the record performs a linear conversion on the data. If NO CONVERSION is chosen, the record performs no conversion on its data. The other choices are the names of breakpoint tables. When one of these is specified in the LINR field, the record uses the specified table to convert its data. (Note that additional breakpoint tables are often added at specific sites, so more breakpoint tables than are listed here may be available at the user's site.) The following sections explain linear and breakpoint conversions.

Linear Conversions

There are three formulas to know when considering the linear conversion parameters. The conversion from measured value to engineering units is as follows:

eng units = eng units low + (	measured A/D counts	) × (eng units full scale - eng units low)
	----------------------------
	full scale A/D counts

The engineering units full scale and low scale are specified in the EGUF and EGUL fields, respectively. The values of the EGUF and EGUL fields correspond to the maximum and minimum values of the transducer, respectively. Thus, the value of these fields is device dependent. For example, if the transducer has a range of -10 to +10 volts, then the EGUF field should be 10 and the EGUL field should be -10.

In the following examples the determination of engineering units full scale and low scale is shown. The conversion to engineering units is also shown to familiarize the reader with the signal conversions from signal source to database engineering units.

Note: The engineering units field (EGU) in an analog record has nothing to do with the conversions. The EGU field simply contains a string that should describe the engineering units used by the record, such as PSI for an analog input that reads values from a device that transmits pressure. Thus, the EGU field is meant for the operator's sake.

Transducer Matches the I/O module

First let us consider a linear conversion. In this example, the transducer transmits 0-10 Volts, there is no amplification, and the I/O card uses a 0-10 Volt interface.

The transducer transmits pressure: 0 PSI at 0 Volts and 175 PSI at 10 Volts. The engineering units full scale and low scale are determined as follows:

eng. units full scale = 17.5 × 10.0
eng. units low scale = 17.5 × 0.0

The field entries in an analog input record to convert this pressure will be as follows:

LINR:

Linear

EGUF:

175.0

EGUL:

0

EGU:

PSI

The conversion will also take into account the precision of the I/O module. In this example (assuming a 12 bit analog input card) the conversion is as follows:

eng units = 0 + (	measured A/D counts	) × (175 - 0)
	----------------------------
	4095

When the pressure is 175 PSI, 10 Volts is sent to the I/O module. At 10 Volts the signal is read as 4095. When this is plugged into the conversion, the value is 175 PSI.

Transducer Lower than the I/O module

Let's consider a variation of this linear conversion where the transducer is 0-5 Volts.

In this example the transducer is producing 0 Volts at 0 PSI and 5 Volts at 175 PSI. The engineering units full scale and low scale are determined as follows:

eng. units low scale = 35 × 10
eng. units full scale = 35 × 0

The field entries in an analog record to convert this pressure will be as follows:

LINR:

Linear

EGUF:

350

EGUL:

0

EGU:

PSI

The conversion will also take into account the precision of the I/O module. In this example (assuming a 12 bit analog input card) the conversion is as follows:

eng units = 0 + (	measured A/D counts	) × (350 - 0)
	----------------------------
	4095

Notice that at full scale the transducer will generate 5 Volts to represent 175 PSI. This is only half of what the input card accepts; input is 2048. Let's plug in the numbers to see the result:

0 + (2048 / 4095) * (350 - 0) = 175

In this example we had to adjust the engineering units full scale to compensate for the difference between the transmitter and the analog input card.

Transducer Positive and I/O module bipolar

Let's consider another variation of this linear conversion where the input card accepts -10 Volts to 10 Volts (i.e. Bipolar instead of Unipolar).

In this example the transducer is producing 0 Volts at 0 PSI and 10 Volts at 175 PSI. The input module has a different range of voltages and the engineering units full scale and low scale are determined as follows:

eng. units full scale = 17.5 × 10
eng. units low scale = 17.5 × (-10)

The database entries to convert this pressure will be as follows:

LINR:

Linear

EGUF:

175

EGUL:

-175

EGU:

PSI

The conversion will also take into account the precision of the I/O module. In this example (assuming a 12 bit analog input card) the conversion is as follows:

eng units = -175 + (	measured A/D counts	) × (175 - (-175))
	----------------------------
	4095

Notice that at low scale the transducer will generate 0 Volts to represent 0 PSI. Because this is half of what the input card accepts, it is input as 2048. Let's plug in the numbers to see the result:

-175 + (2048 / 4095) * (175 - -175) = 0

In this example we had to adjust the engineering units low scale to compensate for the difference between the unipolar transmitter and the bipolar analog input card.

Combining Linear Conversion with an Amplifier

Let's consider another variation of this linear conversion where the input card accepts -10 Volts to 10 Volts, the transducer transmits 0 - 2 Volts for 0 - 175 PSI and a 2x amplifier is on the transmitter.

At 0 PSI the transducer transmits 0 Volts. This is amplified to 0 Volts. At half scale, it is read as 2048. At 175 PSI, full scale, the transducer transmits 2 Volts, which is amplified to 4 Volts. The analog input card sees 4 Volts as 70 percent of range or 2867 counts. The engineering units full scale and low scale are determined as follows:

eng units full scale = 43.75 × 10
eng units low scale = 43.75 × (-10)

(175 / 4 = 43.75) The record's field entries to convert this pressure will be as follows:

LINR:

Linear

EGUF:

437.5

EGUL:

-437.5

EGU:

PSI

The conversion will also take into account the precision of the I/O module. In this example (assuming a 12 bit analog input card) the conversion is as follows:

eng units = -437.5 + (	measured A/D counts	) × (437.5 - (-437.5))
	----------------------------
	4095

Notice that at low scale the transducer will generate 0 Volts to represent 0 PSI. Because this is half of what the input card accepts, it is input as 2048. Let's plug in the numbers to see the result:

-437.5 + (2048 / 4095) * (437.5 - -437.5) = 0

Notice that at full scale the transducer will generate 2 volts which represents 175 PSI. The amplifier will change the 2 Volts to 4 Volts. 4 Volts is 14/20 or 70 percent of the I/O card's scale. The input from the I/O card is therefore 2866 (i.e., 0.7 * 4095). Let's plug in the numbers to see the result:

-437.5 + (2866 / 4095) * (437.5 - -437.5) = 175 PSI

We had to adjust the engineering units full scale to adjust for the difference between the transducer with the amplifier affects and the range of the I/O card. We also adjusted the low scale to compensate for the difference between the unipolar transmitter/amplifier and the bipolar analog input card.

Breakpoint Conversions

Now let us consider a non-linear conversion, otherwise known as a breakpoint conversion. In this example the transducer is a thermocouple which transmits 0-20 milliAmps. An amplifier is present which amplifies milliAmps to volts. The I/O card uses a 0-10 Volt interface.

The transducer is transmitting temperature. The database entries in the analog input record that are needed to convert this temperature will be as follows:

LINR:

typeJdegC

EGUF:

0

EGUL:

0

EGU:

DGC

For analog records that use breakpoint tables, the EGUF and EGUL fields are not used in the conversion, so they do not have to be given values. Instead, this conversion is completed by performing a table lookup. The value read from the device is known as the raw value, which is initially read into the RVAL (raw value) field. This raw value is then used to identify the line segment in which this value falls. Each entry of the table includes a beginning point for the segment, the floating engineering units value at the point, and the slope of the line segment. The conversion to the engineering units is as follows:

final value = eng. units + (raw value - first point) × slope

There are currently lookup tables for J and K thermocouples in degrees F and degrees C.

Other applications for a lookup table are the remainder of the thermocouples, logarithmic output controllers, and exponential transducers. We have chosen the piece-wise linearization of the signals to perform the conversion, as they provide a mechanism for conversion that minimizes the amount of floating point arithmetic required to convert non-linear signals. Additional breakpoint tables can be added to the existing breakpoints.

There are two ways to create a new breakpoint table:

1. Simply type in the data for each segment, giving the raw and corresponding engineering unit value for each point in the following format.

breaktable(<tablename>) {
	<first point> <first eng units>
	<next point> <next eng units>
	<etc.> <...>
	}

where the <tablename> is the name of the table, such as typeKdegC, and <first point> is the raw value of the beginning point for each line segment, and <first eng units> is the corresponding engineering unit value. The slope is calculated by the software and should not be specified.

2. Create a file consisting of a table of an arbitrary number of values in engineering units and use the utility called makeBpt to convert the table into a breakpoint table. As an example, the contents data file to create the typeJdegC breakpoint table look like this:

!header
"typeJdegC" 0 0 700 4095 .5 -210 760 1
!data
-8.096 -8.076 -8.057 many more numbers

The file must have the extension .data. The file must first have a header specifying these nine things:

1. Name of breakpoint table in quotes: "typeJdegC"
2. Engineering units for 1st breakpoint table entry: 0
3. Raw value for 1st breakpoint table entry: 0
4. Highest value desired in engineering units: 700
5. Raw value corresponding to high value in engineering units: 4095
6. Allowed error in engineering units: .5
7. Engineering units corresponding to first entry in data table: -210
8. Engineering units corresponding to last entry in data table: 760
9. Change in engineering units between data table entries: 1

The rest of the file contains lines of equally spaced engineering values, with each line no more than 160 characters before the new-line character. The header and the actual table should be specified by !header and !data, respectively. The file for this data table is called typeJdegC.data, and can be converted to a breakpoint table with the makeBpt utility as follows:

unix% makeBpt TypeJdegC.data

4. Alarm Specification

There are two elements to an alarm condition: the alarm status and the severity of that alarm. Each database record contains its current alarm status and the corresponding severity for that status. The scan task which detects these alarms is also capable of generating a message for each change of alarm state. The types of alarms available fall into these categories: scan alarms, read/write alarms, limit alarms, and state alarms. Some of these alarms are configured by the user, and some are automatic which means that they are called by the record support routines on certain conditions, and cannot be changed or configured by the user.

Alarm Severity

An alarm severity is used to give weight to the current alarm status. There are four severities:

• NO_ALARM
• MINOR
• MAJOR
• INVALID

NO_ALARM means no alarm has been triggered. An alarm state that needs attention but is not dangerous is a MINOR alarm. In this instance the alarm state is meant to give a warning to the operator. A serious state is a MAJOR alarm. In this instance the operator should give immediate attention to the situation and take corrective action. An INVALID alarm means there's a problem with the data, which can be any one of several problems; for instance, a persons trips over some wires, unplugging them, which disables the sensors, which means that a new value couldn't be scanned for the record. In that case, an alarm of INVALID severity will be triggered. When a system is being tested, an INVALID alarm can point to a simple configuration problem. However, when the system is actually on-line, an INVALID alarm can signal a much more serious problem.

For limit alarms and state alarms, the severity can be configured by the user to be MAJOR or MINOR for the a specified state. For instance, an analog record can be configured to trigger a MAJOR alarm when its value exceeds 175.0. In addition to the MAJOR and MINOR severities, the user can choose the NO_ALARM severity, in which case no alarm is generated for that state.

For the other alarm types (i.e., scan, read/write), the severity is always INVALID and not configurable by the user.

Scan Alarm

A scan alarm is generated if a record is not successfully placed in the desired scan list, or if it is found by the scan task to be locked in ten successive attempts to process it. When a scan alarm occurs, the alarm severity is always set to INVALID.

Read Alarm

This alarm status is returned when the value is fetched from hardware or from a database field. If the read routine fails, the READ_ALARM condition exists. The severity of this alarm condition is always set to INVALID.

Write Alarm

This alarm status is returned when the value is written either to hardware or to a database field. If the write fails, the WRITE_ALARM condition exists. The severity of this alarm condition is always set to INVALID.

Limit Alarms

For analog records (this includes such records as the stepper motor record), there are configurable alarm limits. There are two limits for above normal operating range and two limits for the below-limit operating range. Each of these limits has an associated alarm severity which is configured in the database. If the record's value drops below the low limit and an alarm severity of MAJOR was specified for that limit, then a MAJOR alarm is triggered. When the severity of a limit is set to NO_ALARM, none will be generated, even if the limit entered has been violated.

There are two limits at each end, two low values and two high values, so that a warning can be set off before the value goes into a dangerous condition.

Analog records also contain a hysteresis field, which is also used when determining limit violations. The hysteresis field is the deadband around the alarm limits. The deadband keeps a signal that is hovering at the limit from generating too many alarms. Let's take an example (Figure 8) where the range is -100 to 100 volts, the high alarm limit is 30 Volts, and the hysteresis is 10 Volts. If the value is normal and approaches the HIGH alarm limit, an alarm is generated when the value reaches 30 Volts. This will only go to normal if the value drops below the limit by more than the hysteresis. For instance, if the value changes from 30 to 28 this record will remain in HIGH alarm. Only when the value drops to 20 will this record return to normal state.

Figure 8

State Alarms

For discrete values there are configurable state alarms. In this case a user may configure a certain state to be an alarm condition. Let's consider a cooling fan whose discrete states are high, low, and off. The off state can be configured to be an alarm condition so that whenever the fan is off the record is in a STATE alarm. The severity of this error is configured for each state. In this example, the low state could be a STATE alarm of MINOR severity, and the off state a STATE alarm of MAJOR severity.

Discrete records also have a field in which the user can specify the severity of an unknown state to NO_ALARM, MINOR or MAJOR. Thus, the unknown state alarm is not automatic.

Discrete records also have a field which can specify an alarm when the record's state changes. Thus, an operator can know when the record's alarm state has changed. If this field specifies NO_ALARM, then a change of state will not trigger a change of state alarm. However, if it specifies either MINOR or MAJOR, a change of state will trigger an alarm with the corresponding severity.

Alarm Handling

A record handles alarms with the NSEV, NSTA, SEVR, and STAT fields. When a software component wants to raise an alarm, it first checks the new alarm state fields: NSTA, new alarm state, and NSEV, new alarm severity. If the severity in the NSEV field is higher than the severity in the current severity field (SEVR), then the software component sets the NSTA and NSEV fields to the severity and alarm state that corresponds to the outstanding alarm. When the record process routine next processes the record, it sets the current alarm state (STAT) and current severity (SEVR) to the values in the NSEV and NSTA fields. This method of handling alarms ensures that the current severity (STAT) reflects the highest severity of outstanding alarm conditions instead of simply the last raised alarm. This also means that the if multiple alarms of equal severity are present, the alarm status indicates the first one detected.

In addition, the get_alarm_double() routine can be called to format an alarm message and send it to an alarm handler. The alarm conditions may be monitored by the operator interface by explicitly monitoring the STAT and SEVR fields. All values monitored by the operator interface are returned from the database access with current status information.

Monitor Specification

---

Monitors are a mechanism that provide a user program with data from the database without the user having to constantly poll the database. Through channel access, monitors inform the operator interface, archivers, alarm handlers and other user programs when a database field changes. Monitors can be placed on any field that can be accessed through the database access layer: floats, integers, strings, enumerated, and link fields. The fields involved with monitoring fall into two categories: determining when to notify a user and maintaining the list of monitors. For more information about using monitors, see the Channel Access Reference Guide.

Notification

For most fields that are accessible through the database access layer, users are notified whenever the field changes. The exception is the VAL or value field found in most records. Monitors on the value fields are sent when either the value changes or the alarm condition changes. Value fields of the floating-point type are special in that there are two deadbands around the monitor notification: one for archive monitors, ADEL, and one for all other monitors, MDEL. These deadbands are provided to aid the user in reducing the amount of processing by filtering out negligible value changes. These numbers should be set after considering the precision required by the application. Setting these deadbands carefully could considerably extend the capability of an I/O Controller.

To implement the deadbands, each record that has deadbands for the value field or fields (not all records have deadbands for value fields) will have fields that contain the value for the monitored field from the last time the record was processed. For instance, an analog output has the ALST and MLST fields. The first implements the deadband for the archivers; the second, for all other monitors on the value field. Each time the record is processed, the last value is compared to the current value, and if the change is greater than the deadband, monitors for the field are sent.

if ((current value - last value) > deadband)
	send monitors

Of course, the formula is a little bit more complicated in order to deal with negative numbers and other subtleties, but the basic idea is the same.

List Maintenance

Each record keeps track of all the monitors that are active as a result of Channel Access monitor requests. A Channel Access monitor request occurs when a client has requested to monitor a specific record or field. The head of the list of monitors for a record currently active is found in the monitor list field (MLIS). Monitors are active when the value of MLIS is greater than 0.

Control Specification

---

Closed loop control is achieved by linking output records to other records. In all output records there are a set of fields available to specify a location from which the desired output should come. After the desired output value is retrieved, it is converted and then written. Usually, these fields are called DOL, or desired output location field, and the OMSL, or output mode select field. The OMSL field has two mode choices: closed_loop or supervisory. When the closed loop mode is chosen, the desired output is retrieved from the location specified by the DOL field and placed into the VAL field. When the supervisory mode is chosen, the desired output value is simply taken from VAL and is not retrieved from DOL. In the supervisory mode, VAL can be changed externally via the database access routines.

The DOL field, like most other link fields, can be a link or a constant. When a constant, the VAL field is initialized to its value. Thus, if the desired output of the record is to be controlled externally by the operator, the DOL field can be given a value with which the VAL field will be initialized.

When an output record is set to closed loop mode, new desired outputs can be retrieved from algorithm records so that the output required can achieve a desired affect. Using this capability, closed control loops can be implemented. A closed control loop usually consists of an input record which retrieves a value from a process variable, an algorithm record which retrieves its value from the input record and manipulates the data in some way, and then an output record which retrieves the changed value from the algorithm record and sends out to a controller that will determine the input. This section will look at an example of closed loop control.

Closing an Analog Control Loop

In a simple control loop an analog input record reads the value of a process variable or PV. Then, a PID record retrieves the value from the analog input record. A PID record reads a value, determine if the value is in error, and if so, corrects the error to conform with the desired output. Then this value can be used an output record to write the value to the same PV. In this case, an analog output record gets the value from the PID and writes it to the PV. In the database, the PID record gets the current value from the analog input record, and the analog output record gets the desired output from the PID record.

For a closed control loop, closed_loop should be chosen in the analog output's OMSL field, in which case the desired output is retrieved from the DOL field which should specify the DM field of the PID record. The PID record determines the difference between the desired value and the current process value gotten from the analog input, and also determines how the output should change to get the process value to the desired value. The result of the PID calculation is an output delta. The analog output needs to be configured to accept incremental changes when tied to a PID that calculates change only. This can be done in the OIF field, which has two choices: Full or Incremental.

The analog output record, like most output records, can be taken out of the closed control loop by changing closed_loop to supervisory in its OMSL field, which is accessible and modifiable at run-time. Doing this, of course, suspends the closed control loop until the OMSL field is set back to supervisory,

Figure 9

---

EPICS Record Reference Manual - 19 MAY 1998