NB: This manual documents a 20+ year old version of EPICS, see here for the EPICS 7 Record Reference documentation.

[Next] [Previous] [Top] [Contents] [Index]

EPICS Record Reference Manual

Chapter 10: Calcout - Calculation Output Record

1. Introduction

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

scan parameters

read parameters

expression parameters

output parameters

operator display parameters

alarm parameters

monitor parameters

run-time parameters

2. Scan Parameters

The Calcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in Scan Fields, Chapter 2, 2. In addition, Scanning Specification, Chapter 1, 1, explains how these fields are used. Since the Calcout record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be I/O Intr.

3. Read Parameters

The read parameters for the Calcout record consist of 12 input links--INPA, INPB, . . . INPL. The fields can be database links, channel access links, or constants. If they are links, they must specify another record's field. If they are constants, they will be initialized with the value they are configured with and can be changed via dbPuts. These fields cannot be hardware addresses. In addition, the Calcout record contains the INAV, INBV, . . . INLV fields which indicate the status of the link fields, for example, whether or not the specified PV was found and a link to it established. See Section 6, Operator Display Parameters for an explanation of these fields.

See Address Specification, Chapter 1, 2, for information on how to specify database links.
FieldSummaryTypeDCTInitialAccessModifyRec Proc Monitor

4. Expression

Like the Calc record, the Calcout record has a CALC field in which the developer can enter an infix expression which the record routine will evaluate when it processes the record. The resulting value is placed in the VAL field. This value can then be used by the OOPT field (see Section 5, Output Parameters) to determine whether or not to write to the output link or post an output event. It can also be the value that is written to the output link. The CALC expression is actually converted to opcode and stored in Reverse Polish Notation in the RPCL field. It is this expression which is actually used to calculate VAL. The Reverse Polish expression is evaluated more efficiently during run-time than an infix expression. CALC can be changed at run-time, and a special record routine will call a function to convert it to Reverse Polish Notation.

The range of expressions supported by the calculation record are separated into operands, algebraic operators, trigonometric operators, relational operators, logical operators, parentheses and commas, and the conditional '?:' operator. The expression can consist of any of these operators, as well as any of the values from the input links which are the operands.
FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
Also, the RNDM unary function can be included as an operand in the expression in order to generate a random number between 0 and 1.

4.1. Operands

The expression can use the values retrieved from the INPx links as operands, though constants can be used as operands too. These values retrieved from the input links are stored in the A-L fields. The values to be used in the expression are simply referenced by the field letter. For instance, the value obtained from the INPA link is stored in the field A, and the value obtained from INPB is stored in field B. The field names can be included in the expression which will operate on their respective values, as in A+B.
FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
AInput Value ADOUBLENo0YesYes/NoYesYes
BInput Value BDOUBLENo0YesYes/NoYesYes
CInput Value CDOUBLENo0YesYes/NoYesYes
DInput Value DDOUBLENo0YesYes/NoYesYes
EInput Value EDOUBLENo0YesYes/NoYesYes
FInput Value FDOUBLENo0YesYes/NoYesYes
GInput Value GDOUBLENo0YesYes/NoYesYes
HInput Value HDOUBLENo0YesYes/NoYesYes
IInput Value IDOUBLENo0YesYes/NoYesYes
JInput Value JDOUBLENo0YesYes/NoYesYes
KInput Value KDOUBLENo0YesYes/NoYesYes
LInput Value LDOUBLENo0YesYes/NoYesYes

4.2. Algebraic Operators

4.3. Trigonometric Operators

4.4. Relational Operators

4.5. Logical Operators

4.6. Bitwise Operators

4.7. Parentheses and Comma

The open and close parentheses are supported. Nested parenthesis are supported.

The comma is supported when used to separate the arguments of a binary function.

4.8. Conditional Expression

The C language's question mark operator is supported. The format is:

 (condition)? True result : False result

4.9. Examples


A + B + 10


(A + B) < (C + D)

Question Mark





5. Output Parameters

These parameters specify and control the output capabilities of the Calcout record. They determine when to write the output, where to write it, and what the output will be. The OUT link specifies the Process Variable to which the result will be written. The OOPT field determines the condition that causes the output link to be written to. It's a menu field that has six choices:

The DOPT field determines what data is written to the output link when the output is executed. The field is a menu field with two options: Use CALC or Use OCAL. If Use CALC is specified, when the record writes its output it will write the result of the expression in the CALC record, that is, it will write the value of the VAL field. If Use OCAL is specified, the record will instead write the result of the expression in the OCAL field, which is contained in the OVAL field. The OCAL field is exactly like the CALC field and has the same functionality: it can contain the string representation of an expression which is evaluated at run-time. Thus, if necessary, the record can use the result of the CALC expression to determine if data should be written and can use the result of the OCAL expression as the data to write.

If the OEVT field specifies a non-zero integer and the condition in the OOPT field is met, the record will post a corresponding event. If the ODLY field is non-zero, the record pauses for the specified number of seconds before executing the OUT link or posting the output event. During this waiting period the record is "active" and will not be processed again until the wait is over. The field DLYA is equal to 1 during the delay period. The resolution of the delay entry is 1/60 of a second (it uses the VxWorks tickLib).

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are Continue normally, Don't drive outputs, and Set output to IVOV. If the IVOA field is Set output to IVOV, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.
FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
OUTOutput SpecificationOUTLINKYes0YesYesN/ANo
OOPTOutput Execute OptionRECCHOICEYes0YesYesNoNo
DOPTOutput Data OptionRECCHOICEYes0YesYesNoNo
OCAL Output CalculationSTRING[36]YesNullYesYesNoNo
OVALOutput ValueDOUBLENo0YesYesYesYes
OEVTEvent To IssueSHORTYes0YesYesNoNo
ODLYOutput Execution DelayFLOATYes0YesYesNoNo
IVOVInvalid Output ActionGBLCHOICEYes0YesYesNoNo
IVOAInvalid Output ValueDOUBLEYes0YesYesNoNo

6. Operator Display Parameters

These parameters are used to present meaningful data to the operator. Some are also meant to represent the status of the record at run-time. An example of an interactive MEDM display screen that displays the status of the Calcout record is located here.

The EGU field contains a string of up to 16 characters which is supplied by the user and which describes the values being operated upon. The string is retrieved whenever the routine get_units is called. The EGU string is solely for an operator's sake and does not have to be used.

The HOPR and LOPR fields only refer to the limits of the VAL, HIHI, HIGH, LOW, and LOLO fields. PREC controls the precision of the VAL field.

The INAV-INLV fields indicate the status of the link to the PVs specified in the INPA-INPL fields, respectively. The field can have three possible values:

The OUTV field indicates the status of the OUT link. It has the same possible values as the INAV-INLV fields.

The CLCV and OLCV fields indicate the validity of the expression in the CALC and OCAL fields, respectively. If the expression is invalid, the field is set to one.

The DLYA field is set to one during the delay interval specified in ODLY.

See Chapter 2, Fields Common to All Record Types, for more on the record name (NAME) and description (DESC) fields.
FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
EGUEngineering UnitsSTRING [16]YesNullYesYesNoNo
PRECDisplay PrecisionSHORTYes0YesYesNoNo
HOPRHigh Operating RangeFLOATYes0YesYesNoNo
LOPRLow Operating RangeFLOATYes0YesYesNoNo
DLYAOutput Delay ActiveUSHORTNo0YesNoNoNo
NAMERecord NameSTRING [29]Yes0YesNoNoNo
DESCDescriptionSTRING [29]YesNullYesYesNoNo

7. Alarm Parameters

The possible alarm conditions for the Calc record are the SCAN, READ, Calculation, and limit alarms. The SCAN and READ alarms are called by the record support routines. The Calculation alarm is called by the record processing routine when the CALC expression is an invalid one, upon which an error message is generated.

The following alarm parameters which are configured by the user define the limit alarms for the VAL field and the severity corresponding to those conditions.

The HYST field defines an alarm deadband for each limit. See Alarm Specification, Chapter 1, 4, for a complete explanation of alarms and these fields. Alarm Fields, Chapter 2, 3, lists other fields related to a alarms that are common to all record types.
FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
HIHIHihi Alarm LimitFLOATYes0YesYesNoYes
HIGHHigh Alarm LimitFLOATYes0YesYesNoYes
LOWLow Alarm LimitFLOATYes0YesYesNoYes
LOLOLolo Alarm LimitFLOATYes0YesYesNoYes
HHSVSeverity for a Hihi AlarmGBLCHOICEYes0YesYesNoYes
HSVSeverity for a High AlarmGBLCHOICEYes0YesYesNoYes
LSVSeverity for a Low AlarmGBLCHOICEYes0YesYesNoYes
LLSVSeverity for a Lolo AlarmGBLCHOICEYes0YesYesNoYes
HYSTAlarm DeadbandDOUBLEYes0YesYesNoNo

8. Monitor Parameters

These parameters are used to determine when to send monitors for the value fields. The monitors are sent when the value field exceeds the last monitored field by the appropriate deadband, the ADEL for archiver monitors and the MDEL field for all other types of monitors. If these fields have a value of zero, every time the value changes, monitors are triggered; if they have a value of -1, every time the record is scanned, monitors are triggered. See Monitor Specification, Chapter 1, 5, for a complete explanation of monitors.
FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
ADELArchive DeadbandDOUBLEYes0YesYesNoNo
MDELMonitor, i.e. value change, DeadbandDOUBLEYes0YesYesNoNo

9. Run-time Parameters

These fields are not configurable using a configuration too and none are modifiable at run-time. They are used to process the record.

The LALM field is used to implement the hysteresis factor for the alarm limits.

The LA-LL fields are used to decide when to trigger monitors for the corresponding fields. For instance, if LA does not equal the value for A, monitors for A are triggered. The MLST and MLST fields are used in the same manner for the VAL field.
FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
LALMLast Alarmed ValueDOUBLENo0YesNoNoNo
ALSTArchive Last ValueDOUBLENo0YesNoNoNo
MLSTMonitor Last ValueDOUBLENo0YesNoNoNo
LAPrevious Input Value for ADOUBLENo0YesNoNoNo
LBPrevious Input Value for ADOUBLENo0YesNoNoNo
LCPrevious Input Value for ADOUBLENo0YesNoNoNo
LDPrevious Input Value for ADOUBLENo0YesNoNoNo
LEPrevious Input Value for ADOUBLENo0YesNoNoNo
LFPrevious Input Value for ADOUBLENo0YesNoNoNo
LGPrevious Input Value for ADOUBLENo0YesNoNoNo
LHPrevious Input Value for ADOUBLENo0YesNoNoNo
LIPrevious Input Value for ADOUBLENo0YesNoNoNo
LJPrevious Input Value for ADOUBLENo0YesNoNoNo
LKPrevious Input Value for ADOUBLENo0YesNoNoNo
LLPrevious Input Value for ADOUBLENo0YesNoNoNo

10. Record Support Routines


For each constant input link, the corresponding value field is initialized with the constant value if the input link is CONSTANT or a channel access link is created if the input link is PV_LINK.

A routine postfix is called to convert the infix expression in CALC and OCAL to reverse polish notation. The result is stored in RPCL and ORPC, respectively.


See next section.


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


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


Retrieves EGU.


Retrieves PREC.


Sets the upper display and lower display limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.


Sets the upper control and the lower control limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.


Sets the following values:

upper_alarm_limit = HIHI

upper_warning_limit = HIGH

lower_warning_limit = LOW

lower_alarm_limit = LOLO

11. Record Processing

11.1. process()

The process() routine implements the following algorithm:

1. Fetch all arguments.

2. Call routine calcPerform(), which calculates VAL from the postfix version of the expression given in CALC. If calcPerform() returns success, UDF is set to FALSE.

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. It also honors the alarm hysteresis factor (HYST). Thus the value must change by at least HYST before the alarm status and severity changes.

4. Determine if the Output Execution Option (OOPT) is met. If it is met, either execute the output link (and output event) immediately (if ODLY = 0), or schedule a callback after the specified interval. See the explanation for the execOutput() routine below.

5. Check to see if monitors should be invoked.

6. If no output delay was specified, scan forward link if necessary, set PACT FALSE, and return.

11.2. execOutput()

1. If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.

2. If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.

3. If the Alarm Severity is not INVALID or IVOA specifies "Continue Normally", put the value of OVAL to the OUT link and post the event in OEVT (if non-zero).

4. If an output delay was implemented, process the forward link.

1. - Introduction
2. - Scan Parameters
3. - Read Parameters
4. - Expression
4.1. - Operands
4.2. - Algebraic Operators
4.3. - Trigonometric Operators
4.4. - Relational Operators
4.5. - Logical Operators
4.6. - Bitwise Operators
4.7. - Parentheses and Comma
4.8. - Conditional Expression
4.9. - Examples
Question Mark
5. - Output Parameters
6. - Operator Display Parameters
7. - Alarm Parameters
8. - Monitor Parameters
9. - Run-time Parameters
10. - Record Support Routines
11. - Record Processing
11.1. - process()
11.2. - execOutput()

EPICS Record Reference Manual - 19 MAY 1998
[Next] [Previous] [Top] [Contents] [Index]

Generated with Harlequin WebMaker