EPICSWIKI - User contributions [en]

RRM 3-13 Calculation

2014-06-19T15:16:50Z

RalphLange: /* Operands */ RNDM unary -> nullary

[[RRM 3-13|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls 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 question mark or '?:' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. Also, the RNDM nullary function can be included as an operand in the expression in order to generate a random number between 0 and 1.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

Also, the RNDM nullary function can be included as an operand in the expression in order to generate a random number between 0 and 1.

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (binary function)
* MAX: Maximum (binary function)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

(condition)? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-13 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-13 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-13 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calculation

2014-06-19T15:09:07Z

RalphLange: /* Operands */ RNDM unary -> nullary

[[RRM 3-14|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls a function to convert it to Reverse Polish Notation.

The infix expressions that can be used are very similar to the C expression syntax, but with some additions and subtle differences in operator meaning and precedence. The string may contain a series of expressions separated by a semi-colon character ';' any one of which may actually provide the calculation result; however all of the other expressions included must assign their result to a variable. All alphabetic elements described below are case independent, so upper and lower case letters may be used and mixed in the variable and function names as desired. Spaces may be used anywhere within an expression except between the characters that make up a single expression element.

The range of expressions supported by the calculation record are separated into literals, constants, operands, algebraic operators, trigonometric operators, relational operators, logical operators, the assignment operator, parentheses and commas, and the question mark or '?:' operator.

-----
'''NOTE:''' A complete up-to-date description of the calculation expression can be found in the '''Application Developer's Guide''', chapter libCom / calc / Infix Expression Syntax (19.2.1 for EPICS 3.14.11).
-----

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Literals ====

* Standard double precision floating point numbers
* Inf: Infinity
* Nan: Not a Number

==== Constants ====

* PI: returns the mathematical constant π
* D2R: evaluates to π/180 which, when used as a multiplier, converts an angle from degrees to radians
* R2D: evaluates to 180/π which as a multiplier converts an angle from radians to degrees

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. Also, the RNDM nullary function can be included as an operand in the expression in order to generate a random number between 0 and 1.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword VAL returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

Also, the RNDM nullary function can be included as an operand in the expression in order to generate a random number between 0 and 1.

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* LN: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

==== Assignment Operator ====

* := : assigns a value (right hand side) to a variable (i.e. field)

==== Parentheses, Comma, and Semicolon ====

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.

The semicolon is used to separate expressions. Although only one traditional calculation expression is allowed, multiple assignment expressions are allowed.

==== Conditional Expression ====

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

condition ? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

Prior to Base 3.14.9 it was legal to omit the : and the second (else) part of the conditional, like this:

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

From 3.14.9 onwards this expression must be rewritten as

(A+B)<(C+D)?E:VAL

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

==== Assignment ====

sin(a); a:=a+d2r

* Causes the CALC record to output the successive values of a sine curve in 1 degree intervals

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host

2014-04-02T08:18:32Z

RalphLange: Fix RedHat script for Fedora/RHEL ifconfig variations

== UDP Name Resolution: Broadcast vs. Unicast ==

Running multiple IOCs on one host has an annoying side effect: Clients that are using that host's IP address in their EPICS_CA_ADDR_LIST with EPICS_CA_AUTO_ADDR_LIST=NO will only reach one of the IOCs - usually the one that was started last. All clients have to use broadcasts to reach all IOCs.

The same is true for CA Gateway machines that are set up in a way that makes multiple Gateway processes serve channels into the same network.

The reason is that the kernel delivers UDP broadcasts to ''all'' processes that are listening to the IP port, while UDP unicast messages will only be delivered to ''one'' of those processes.

== Fix Using iptables ==

Here's a little helper (for Linux hosts) that I recently was playing around with - based on an idea by Rodrigo Bongers (CNPEM, Brazil).

If you drop the right script in the right place (depending on your Linux distribution, see further down), it will automatically create/delete an iptables rule that replaces the destination address of all incoming CA UDP traffic on each interface with the broadcast address of that interface.

A simple and effective trick: the kernel will see all incoming name resolution requests as broadcasts, and delivers them to all IOCs instead of one.

Note: This will not work for clients on the same host. (Adding that feature makes things a lot more complicated, and I like things to be simple.)

If you need connections between IOCs on one host, I would suggest adding the broadcast address of the loopback interface (usually 127.255.255.255) to each IOC's EPICS_CA_ADDR_LIST setting.

=== On Debian and Derivatives ===

Drop/link the following script into <tt>/etc/network/if-up.d/</tt> and <tt>/etc/network/if-down.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

[ "$METHOD" != "none" ] || exit 0
[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet addr"`
addr=`echo $line | sed -e 's/.*inet addr:$[0-9\.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9\.]*$.*/\1/'`

[ -z "$addr" -o -z "$bcast" ] && return 1

if [ "$MODE" = "start" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "stop" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

=== On RedHat and Derivatives ===

On systems using NetworkManager, drop the following script into <tt>/etc/NetworkManager/dispatcher.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

IFACE=$1
MODE=$2

[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet "`

# Fedora ifconfig output
addr=`echo $line | sed -e 's/.*inet $[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*broadcast $[0-9.]*$.*/\1/'`

if [ -z "$addr" -o -z "$bcast" ]
then
# RHEL ifconfig output
addr=`echo $line | sed -e 's/.*inet addr:$[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9.]*$.*/\1/'`
fi

[ -z "$addr" -o -z "$bcast" ] && return 1

if [ "$MODE" = "up" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "down" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

Enjoy!

[[User:RalphLange|Ralph]] 03:18, 2 April 2014 (CDT)

How to Configure Channel Access

2014-04-01T09:38:38Z

RalphLange: Add pointer to iptables trick.

= How to Configure Channel Access =

== Basic Operation, One IOC on same subnet ==
Assume an IOC has a record "fred", and you want to use "caget fred" or a similar CA client to read it.

When starting out with one IOC on the network, things are simple:

CA clients will by default broadcast name search requests to UDP port 5064 on the subnet.
As long as the IOC is running on on any computer on that subnet, it should receive those search requests. Server and client will then establish a TCP connection, and data is exchanged.

== Multiple IOCs on different computers, but same subnet ==
If running multiple IOCs, each on their own computer, on the same subnet, the basic broadcast name search will still succeed, no change necessary.

== IOCs on different subnets ==
The default broadcast name search is limited to the subnet of the computer running the CA client.
To reach IOCs on one or more additional subnets, the environment variable EPICS_CA_ADDR_LIST needs to be configured.
It can list either the specific IP addresses of each IOC, or the broadcast address of their subnet.
Note, however, that routers will often not forward broadcast requests, which suggests using specific IP addresses.

== Multiple IOCs on the same computer ==
When starting the first IOC on a computer, it will listen to name searches on UDP port 5064.
When starting a second IOC on the same computer, it will also listen to name searches on UDP port 5064.
Due to limitations in most network kernels, however, only the IOC started ''last'' will actually receive UDP search requests that are sent to that computer, port 5064. As a workaround, you need to configure the EPICS_CA_ADDR_LIST to use the broadcast address of the respective subnet.

Alternatively, you can automatically set up iptables rules that will circumvent the problem. (See [[How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host]].)

== Multiple IOCs on the same computer but on a different subnet ==
Combining the last two points results in a problem:
To reach multiple IOCs on the same computer, EPICS_CA_ADDR_LIST must be set to the broadcast address of that computer's subnet.
If the IOCs' subnet is different from the CA client's subnet however, the broadcast search packets will not usually be forwarded by the intermediate network routers.

There are several options to solve this:

=== Channel Access Gateway ===
The PV gateway, running on the subnet that has the desired IOCs, will use the broadcast address of that subnet in its EPICS_CA_ADDR_LIST, so it can reach all IOCs, including multiple IOCs running on the same computer, throughout that subnet.
A CA client on a different subnet uses only EPICS_CA_ADDR_LIST=ip-of-the-gateway to directly reach the gateway, which is possible via routers.

In addition to establishing the basic connectivity, the gateway also offers IOC load reduction and it can add access security, for example limit write access.

=== CA Nameserver ===
You can run a CA Name Server in the GUI subnet which knows about the IOCs and responds to search requests; in this case you would ''not'' set the EPICS_CA_ADDR_LIST variables. This is almost equivalent to running a CA Gateway, but is slightly more robust because if the Nameserver process dies it wouldn't kill any existing connections.

=== UDP Broadcast Packet Relay ===
If you have access to a machine with a network interface on both subnets you can run a program on it called [https://www.joachim-breitner.de/udp-broadcast-relay/ UDP Broadcast Packet Relay] to forward UDP broadcast packets between the subnets. For best performance you should run it twice, once for port 5064 and again for 5065. The first one will forward CA search requests between the subnets, while the second redistributes CA beacons which help channels reconnect faster after an IOC has been turned off for some time.

== Firewalls ==
Firewalls may need to be configured to pass UDP and TCP traffic on both ports 5064 and 5065.

The [http://www.aps.anl.gov/epics/base/R3-14/12-docs/CAref.html Channel Access Reference Manual] provides a lot more detail.

How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host

2014-04-01T09:34:56Z

RalphLange:

== UDP Name Resolution: Broadcast vs. Unicast ==

Running multiple IOCs on one host has an annoying side effect: Clients that are using that host's IP address in their EPICS_CA_ADDR_LIST with EPICS_CA_AUTO_ADDR_LIST=NO will only reach one of the IOCs - usually the one that was started last. All clients have to use broadcasts to reach all IOCs.

The same is true for CA Gateway machines that are set up in a way that makes multiple Gateway processes serve channels into the same network.

The reason is that the kernel delivers UDP broadcasts to ''all'' processes that are listening to the IP port, while UDP unicast messages will only be delivered to ''one'' of those processes.

== Fix Using iptables ==

Here's a little helper (for Linux hosts) that I recently was playing around with - based on an idea by Rodrigo Bongers (CNPEM, Brazil).

If you drop the right script in the right place (depending on your Linux distribution, see further down), it will automatically create/delete an iptables rule that replaces the destination address of all incoming CA UDP traffic on each interface with the broadcast address of that interface.

A simple and effective trick: the kernel will see all incoming name resolution requests as broadcasts, and delivers them to all IOCs instead of one.

Note: This will not work for clients on the same host. (Adding that feature makes things a lot more complicated, and I like things to be simple.)

If you need connections between IOCs on one host, I would suggest adding the broadcast address of the loopback interface (usually 127.255.255.255) to each IOC's EPICS_CA_ADDR_LIST setting.

=== On Debian and Derivatives ===

Drop/link the following script into <tt>/etc/network/if-up.d/</tt> and <tt>/etc/network/if-down.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

[ "$METHOD" != "none" ] || exit 0
[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet addr"`
addr=`echo $line | sed -e 's/.*inet addr:$[0-9\.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9\.]*$.*/\1/'`

if [ "$MODE" = "start" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "stop" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

=== On RedHat and Derivatives ===

On systems using NetworkManager, drop the following script into <tt>/etc/NetworkManager/dispatcher.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

IFACE=$1
MODE=$2

[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet "`
addr=`echo $line | sed -e 's/.*inet $[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*broadcast $[0-9.]*$.*/\1/'`

if [ "$MODE" = "up" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "down" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

Enjoy!

[[User:RalphLange|Ralph]] 04:34, 1 April 2014 (CDT)

How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host

2014-04-01T09:27:10Z

RalphLange: /* How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host */

== UDP Name Resolution: Broadcast vs. Unicast ==

Running multiple IOCs on one host has an annoying side effect: Clients that are using that host's IP address in their EPICS_CA_ADDR_LIST with EPICS_CA_AUTO_ADDR_LIST=NO will only reach one of the IOCs - usually the one that was started last. All clients have to use broadcasts to reach all IOCs.

The same is true for CA Gateway machines that are set up in a way that makes multiple Gateway processes serve channels into the same network.

The reason is that the kernel delivers UDP broadcasts to ''all'' processes that are listening to the IP port, while UDP unicast messages will only be delivered to ''one'' of those processes.

== Fix Using iptables ==

Here's a little helper (for Linux hosts) that I recently was playing around with - based on an idea by Rodrigo Bongers (CNPEM, Brazil).

If you drop the right script in the right place (depending on your Linux distribution, see further down), it will automatically create/delete an iptables rule that replaces the destination address of all incoming CA UDP traffic on each interface with the broadcast address of that interface.

A simple and effective trick: the kernel will see all incoming name resolution requests as broadcasts, and delivers them to all IOCs instead of one.

Note: This will not work for clients on the same host. (Adding that feature makes things a lot more complicated, and I like things to be simple.)

If you need connections between IOCs on one host, I would suggest adding the broadcast address of the loopback interface (usually 127.255.255.255) to each IOC's EPICS_CA_ADDR_LIST setting.

=== On Debian and Derivatives ===

Drop/link the following script into <tt>/etc/network/if-up.d/</tt> and <tt>/etc/network/if-down.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

[ "$METHOD" != "none" ] || exit 0
[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet addr"`
addr=`echo $line | sed -e 's/.*inet addr:$[0-9\.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9\.]*$.*/\1/'`

if [ "$MODE" = "start" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "stop" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

=== On RedHat and Derivatives ===

On systems using NetworkManager, drop the following script into <tt>/etc/NetworkManager/dispatcher.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

IFACE=$1
MODE=$2

[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet "`
addr=`echo $line | sed -e 's/.*inet $[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*broadcast $[0-9.]*$.*/\1/'`

if [ "$MODE" = "up" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "down" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host

2014-04-01T09:26:12Z

RalphLange: Created page with "= How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host = == UDP Name Resolution: Broadcast vs. Unicast == Running multiple IOCs on one host has an annoying side ..."

= How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host =

== UDP Name Resolution: Broadcast vs. Unicast ==

Running multiple IOCs on one host has an annoying side effect: Clients that are using that host's IP address in their EPICS_CA_ADDR_LIST with EPICS_CA_AUTO_ADDR_LIST=NO will only reach one of the IOCs - usually the one that was started last. All clients have to use broadcasts to reach all IOCs.

The same is true for CA Gateway machines that are set up in a way that makes multiple Gateway processes serve channels into the same network.

The reason is that the kernel delivers UDP broadcasts to ''all'' processes that are listening to the IP port, while UDP unicast messages will only be delivered to ''one'' of those processes.

== Fix Using iptables ==

Here's a little helper (for Linux hosts) that I recently was playing around with - based on an idea by Rodrigo Bongers (CNPEM, Brazil).

If you drop the right script in the right place (depending on your Linux distribution, see further down), it will automatically create/delete an iptables rule that replaces the destination address of all incoming CA UDP traffic on each interface with the broadcast address of that interface.

A simple and effective trick: the kernel will see all incoming name resolution requests as broadcasts, and delivers them to all IOCs instead of one.

Note: This will not work for clients on the same host. (Adding that feature makes things a lot more complicated, and I like things to be simple.)

If you need connections between IOCs on one host, I would suggest adding the broadcast address of the loopback interface (usually 127.255.255.255) to each IOC's EPICS_CA_ADDR_LIST setting.

== Debian and Derivatives ==

Drop/link the following script into <tt>/etc/network/if-up.d/</tt> and <tt>/etc/network/if-down.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

[ "$METHOD" != "none" ] || exit 0
[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet addr"`
addr=`echo $line | sed -e 's/.*inet addr:$[0-9\.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9\.]*$.*/\1/'`

if [ "$MODE" = "start" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "stop" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

== RedHat and Derivatives ==

On systems using NetworkManager, drop the following script into <tt>/etc/NetworkManager/dispatcher.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

IFACE=$1
MODE=$2

[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet "`
addr=`echo $line | sed -e 's/.*inet $[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*broadcast $[0-9.]*$.*/\1/'`

if [ "$MODE" = "up" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "down" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

HowTo Documents

2014-04-01T08:47:56Z

RalphLange: /* Infrastructure and Other Stuff */

This is a directory of various How-To documents written by members of the EPICS collaboration. Contributions to this page are most welcome!

=== EPICS Base on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]
* [[How To Use Posix Thread Priority Scheduling under Linux]]
* [[How To cross compile EPICS and a IOC to an old x86 Linux system]]
* [http://prjemian.github.io/epicspi/ Installing EPICS on a Raspberry Pi]

=== Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/HowToDoSerial_StreamDevice.html How To Do Serial (using Asyn Driver and StreamDevice)] (also covers VXI-11)
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-15/HowToDoSerial/tutorial.pdf How To Do Serial (using Asyn Driver and devGPIB)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]
* [[How to avoid copying arrays with waveformRecord]]

=== Applications ===

* [[Common Database patterns]]
* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]
* [[How to Add a New Breakpoint Table]]
* [["Best Practice" Guidelines]]
* [[How do I get EPICS applications to work with a Mac OS X firewall?]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Configure Channel Access]]
* [[How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]

=== Collaboration Stuff ===

* [[How to run an EPICS Collaboration Meeting]]

RRM 3-14 Compression

2012-12-03T12:29:29Z

RalphLange: HOPR, LOPR fields FLOAT -> DOUBLE

[[RRM 3-14|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are six possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>
* <CODE>N to 1 Median</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of every element of the array obtained from INP over time; that is, the entire array referenced by INP is retrieved, and for each element the new average is calculated and placed in the corresponding element of the value buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the buffer. Thus, VAL[0] holds the average of the first element of INP over N samples, VAL[1] holds the average of the next element of INP over N samples, and so on. The following shows the equation:

[[Image:RRM 3-14 Compression-1.gif]]

If any of the <CODE>N to 1</CODE>algorithms are chosen, then VAL is a circular buffer of NSAM samples.

The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (Lowest, Highest, or Average), is written to the circular buffer referenced by VAL. If <CODE>Low Value</CODE> the lowest value of all the samples is written; if <CODE>High Value</CODE> the highest value is written; and if <CODE>Average</CODE>, the average of all the samples are written. The <CODE>Median</CODE> setting behaves like <CODE>Average</CODE> with scalar input data.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value.
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value.
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average value.
; <CODE>N to 1 Median</CODE>
: Compress N to 1 samples, taking the median value.

The compression record keeps NSAM data samples.

The field N determines the number of elements to compress into each result.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-14 Compression-2.gif]]

IHIL and ILIL can be set to provide an initial value filter on the input array. If ILIL < IHIL input elements will be skipped until a value is found that is in the range ILIL to IHIL.

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Compression

2012-12-03T12:28:47Z

RalphLange: IHIL, ILIL fields FLOAT -> DOUBLE

[[RRM 3-14|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are six possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>
* <CODE>N to 1 Median</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of every element of the array obtained from INP over time; that is, the entire array referenced by INP is retrieved, and for each element the new average is calculated and placed in the corresponding element of the value buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the buffer. Thus, VAL[0] holds the average of the first element of INP over N samples, VAL[1] holds the average of the next element of INP over N samples, and so on. The following shows the equation:

[[Image:RRM 3-14 Compression-1.gif]]

If any of the <CODE>N to 1</CODE>algorithms are chosen, then VAL is a circular buffer of NSAM samples.

The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (Lowest, Highest, or Average), is written to the circular buffer referenced by VAL. If <CODE>Low Value</CODE> the lowest value of all the samples is written; if <CODE>High Value</CODE> the highest value is written; and if <CODE>Average</CODE>, the average of all the samples are written. The <CODE>Median</CODE> setting behaves like <CODE>Average</CODE> with scalar input data.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value.
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value.
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average value.
; <CODE>N to 1 Median</CODE>
: Compress N to 1 samples, taking the median value.

The compression record keeps NSAM data samples.

The field N determines the number of elements to compress into each result.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-14 Compression-2.gif]]

IHIL and ILIL can be set to provide an initial value filter on the input array. If ILIL < IHIL input elements will be skipped until a value is found that is in the range ILIL to IHIL.

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

Conversion Code Clean-Up

2010-10-18T16:25:30Z

RalphLange: First version of Conversion Code Clean-Up description

== Conversion Code Clean-Up ==

=== Current Situation ===

There are two codes for conversion, a full version in '''db/dbConvert.c''' and a "fast" version in '''db/dbFastLinkConv.c'''.

Both contain the full matrix of conversions as a large set of almost identical C functions.

=== Possible Improvements ===

Using templated functions in C++ would greatly reduce the source code, still allowing for source level optimization by providing explicit instantiations for simple cases (e.g. same type).

The new functions could also be changed to not use dbAddr as parameter (explicitly name the parts needed from dbAddr instead), so they can be used for non-V3-record applications.

The array interface could be improved:
* Start/End/Increment parameters would allow extracting sub arrays
* Chunked array storage could be supported

=== Approach ===

First step should be adding test code that verifies all conversions, and takes performance numbers. That way the existing code could be tested for both function and performance.

Then, the new conversion routines should be implemented, with simple wrappers that map the existing (array of function pointer) interfaces to use the new code.

The test code should be used to verify and spec the new implementation.

Future Development Ideas

2010-10-18T16:24:33Z

RalphLange: /* Conversion Code Clean-Up */

These are projects that can/should be added to EPICS V3 using an evolutionary process. The ordering is not necessarily accurate.

__TOC__

== Tasks which could be done now ==

These items can be worked on immediately as they do not depend on any other work to have been completed, and could even be included in the next 3.14 release if appropriate.

<blockquote>

=== Bug Fixes ===

Bugs tagged 'codeathon' are especially appropriate.

=== Documentation (3.14/3.15) ===

Lots we can do here:

<blockquote>

==== Record Reference Manual ====

* Extend the DBD to HTML converter so we can move detailed record reference documentation into the record.dbd and/or record.c files. Should we attempt to embed the RRM text inside the DBD files?

==== Application Developers Guide ====

* Write a "Building and Porting EPICS" chapter
* Restructure the AppDevGuide to make it more accessible
** Combine the libCom and libCom/osi chapters
** Maybe have a separate section for all callable APIs
** Consider moving API documentation into the appropriate source files and using Doxygen or perldoc to extract it.

==== Other Documents ====

* Look at all the documentation we have and see what's missing
* Data Access, other new CA-related documentation...

</blockquote>

=== More test programs ===

There are test programs in libCom/test which cover quite a lot of the libCom functionality, but they are by far from complete. Writing test code is a very good way to learn the capabilities of the code being tested, and is not usually hard to to, so this would be a good "getting started" project.

Check the Diamond code coverage report as part of their Base Autotests for ideas what code to tackle.

Priority: Medium

=== IOC Test Framework in Perl ===

Once we have good test coverage for libCom we should look at IOC-level testing, including tests for individual record types. This needs code to start a soft IOC with a particular database file, make channel connections over CA and perform the necessary tests, then close down the IOC and clean up. Tests should be automatable, e.g. by generating TAP output and run under the standard Perl Test::Harness, as used by the 'make runtests' target.

Once the framework exists, write test programs for each core record type and device support. Look at the Soft-Test suite and implement those tests too, although a complete rewrite might be appropriate for them...

=== Convert makeBpt into Perl (3.15) ===

The makeBpt tool in src/bpt generates non-linear break-point tables from data files. A fair bit of the C code is concerned with parsing the input file. There is no particular need for this code to be written in C, speed is not an issue, and eventually I hope to convert all programs needed for building EPICS into Perl code. Maybe start this project by writing a program to test the output, then convert the C code into Perl.

=== Database diagnostics ===

When an IOC is too busy to service CA, the engineers need a way to find out what records are causing the problem. Something like a dbSpy command might be helpful, which would keep a count of the records processed by each scan thread and give periodic reports. Would need to be designed carefully so it doesn't eat RAM or slow down the machine too much.

Other diagnostics could also be added: dbProcess rate, ...

Priority: Medium<br>
Libs affected: db, dbStatic.

=== Record aliases in VDCT ===

EPICS Base R3.14.11 supports record aliases, but AFAIK VDCT does not (not sure about the new version of VDCT though). Both preserving the aliases attached to a record loaded from a .db file, and providing creation and editing capabilities for them through the GUI. This is a Java programming task which will need prior communication with CosyLab.

=== Move alarm*.h headers ===

A first step towards a more packagable build system would be to move the alarm.h and alarmString.h headers out of src/dbStatic; they are the only thing currently preventing src/catools and src/cap5 from being built immediately after src/ca.

=== RSRV Using EPICS_CAS_INTF_ Variables ===

Change the socket binding in rsrv to use the EPICS_CAS_INTF_ variable(s) so we can limit IOCs to a subset of the interfaces of the host it's running on.

=== Packagable Build System ===

The EPICS Build system currently does not distinguish between programs that are needed by IOC developers (e.g. dbToMenuH) and end-user programs (e.g. caget). We could divide our build targets into these very easily, which would make packaging EPICS Base much more straight-forward. I see the following parts:

<blockquote>

==== End-user Binaries ====

* catools
* Shared libraries
* SoftIoc (requires compiled-in DBD data though)

These could be installed into /usr/local from an RPM or equivalent packaging system.

==== Developer Tools ====

* flex, antelope binaries etc.
* static libraries
* DBD and header files
* Build system components

These could be packaged into a -devel RPM or equivalent.

</blockquote>

=== Extended Device Support (3.15) ===

Converting Asyn's device support layers to Extended support exposed the need to clean up the extended interface, i.e. reduce the code duplication which is currently required since the record knows nothing about the device change.

Libs affected: db, rec.

=== New Record Types ===

From Bob: Add record types - valve record, improved control records for PID and Lead/Lag (if we had a good process control guy to design the record).

Enhancements to PID should start from the most advanced implementation currently available, which is ''not'' the old PID record type from Base 3.13. There's a PID record in synApps, and there may be others available from other sites too.

Priority: Dalesio<br>
Libs affected: (external app)

=== CA support for Array with Timebase ===

From Bob: Add a new dbr_type into the channel access database - new array that includes time base and offset at least. One that also supports up to 3 dimensions (or better n).

Priority: Dalesio<br>
Libs affected: Many...

=== More flexible Access Security ===

The AS design defines each field's security level in the record description, and limits us to only levels 0 and 1. Some sites may want finer control over accesses: being able to put individual fields of a specific record into a different level, and having additional static levels (use a bitmask?) would help in a number of situations. It is not clear how much work this would entail though.

Priority: Low<br>
Libs affected: dbStatic, db, as, ...

=== Authentication ===

From Ralph: Two or three institutes need a way to password-protect access to certain databases. The usual encryption libraries are freely available, but I guess this issue needs a lot more thinking. Granularity: by record, by connection = IOC, or centralised? Should the authentication last for the client's lifetime or should a short form (some security token or key) be sent with every CA data package?

=== Secure CA ===

Secure channel access protocol - add SSL wrappers around CA to make it secure.

The CA-over-TCP branch should form the basis of this work.

Priority: R3.15<br>
Libs affected: ca, cas, rsrv

=== Online Record Creation ===

It might be possible to add new record instances at runtime, although delete would need a change to the record interface to support. The tricky thing is to do this in a manner which is completely thread-safe since the pdbbase structure does not have many locks, and adding them could significantly affect operation of the IOC.

Priority: Dalesio<br>
Libs affected: dbStatic, db, misc

=== Conversion Code Clean-Up ===

The existing conversion routines (i.e. the fast and full versions in db) could be significantly cleaned up by using C++ templated functions. There would probably be minor savings in object code size, but major savings in terms of source code size and clarity.

Here's a [[Conversion Code Clean-Up|more detailed description]] of how this could be done.

Priority: 3.15<br>
Libs affected: dbStatic, db

</blockquote>

== Tasks which are already under way ==

These tasks are already being worked on but may have stalled. They might be hard for someone else to take over at this stage.

<blockquote>

=== CA Event Rate Limiting (3.15) ===

A CA client can specify a maximum event rate for each channel subscription it creates.

Waiting for: JSON field modifiers

=== CA Event Filtering (3.15) ===

A CA client can specify an event filter with the channel subscription which must be true for events to be posted to the client.

Waiting for: JSON field modifiers

=== Compiling DBD Files (3.15) ===

A Perl implementation of the DBD file parser exists and provides working dbdToRecordH and dbdToMenuH scripts. I'm working to revive my plans to convert all DBD file information into C tables that get compiled into the IOC executable or its shared libraries.

With this parser written in Perl, it is much easier to add new facilities to DBD files, such as adding new field types (see Variable Length Strings below).

Libs affected: dbStatic, +dbHost, db.

</blockquote>

== Things which can't be completed yet ==

These are tasks are waiting on other people or for other tasks to be completed before they can be finished, although there may be infrastructure to support them that can be worked on in parallel.

<blockquote>

=== IOCSH Command Registration (3.15) ===

Add DBD file syntax to convert DBD file information into a C header file which declares the command functions (similar to how we do record types in the current code-base). This header would then be included by the C file that defines those functions, thus the C compiler would do the work of ensuring that the routine implemented actually matches the command that will call it.

The command information in the DBD file will also be useful for future versions of the IRMIS parser for st.cmd scripts, where we need to be able to tie the device support configuration commands into IRMIS' need to map hardware devices to record addresses.

This should be done in the compiled-dbd branch.

Libs affected: dbHost, all libs Registrar code.

=== DBE_PROPERTY event generation (3.15) ===

Extend the DBD syntax to link all fields that contain property values with the fields that the property is supplied with, then have dbPut() post a DBE_PROPERTY monitor on those fields whenever the property value changes.

Libs affected: dbHost, dbStatic, db
Waiting for: Perl DBD Processing

=== Link Support (3.15+) ===

See original proposal by ANJ, which needs to be modified to add notify interfaces.

=== Array Field Support (3.16++) ===

Make it easier to add array fields to record types without having to do as much coding in the record support. See [http://www.aps.anl.gov/epics/core-talk/2007/msg00078.php Ben Franksen email] and the work done by Nick Rees at the 2009 Codeathon.

Libs affected: dbHost, dbStatic, db, rec.

=== Unbundling (3.15/++) ===

Split Base into three or more independent modules. Each module would have its own version number, and the modules can therefore each have an independent existance, although there would obviously be specific dependencies associated with particular versions.

If we adopt this, we should bundle working subsets of modules together and release the complete bundle as a tarfile.

I see the unbundled modules as follows:

<blockquote>

==== Core ====

Depends on: Nothing

These are the common parts used by everything:

* Build system
* libCom & OSI layer
** Basic registry routines
** IOC shell
* Antelope
* Flex
* makeApp tool

==== Channel Access Client ====

Depends on: Core

Jeff Hill's responsibility.

* CA-specific build rules (probably none)
* CA client library
* CA Tools
* CA application makeApp templates

==== Channel Access Server ====

Depends on: Core, IOC, CAC?

Jeff Hill's responsibility.

* CAS-specific build rules (probably none)
* GDD
* The CAS server tool
* RSRV (the old CA server code)
* CAS application makeApp templates

==== IOC ====

Depends on: Core, CAC, CAS

The rest is code that runs on the IOC.

* IOC-specific build rules
* Static and runtime database access
* Runtime database
* Standard record types
* Soft device support
* The registry (device, driver, record, function)
* IOC application makeApp templates

</blockquote>

=== Variable Length Strings (3.15++) ===

3.15 already includes the BaseString C++ classes in libCom, a set of C wrapper routines is needed for the base class operations. This can form the basis of a new variable length string type for use in the database in addition to DBF_STRING.

Libs affected: dbHost, dbStatic, db, ...

=== Device Status String Field ===

DESY want a string field in dbCommon for device support to post signal-specific status information to. Once we have variable-length string types it would be reasonable to add this (if not used/set it would only add one pointer to each record instance).

=== Alternate DB File Formats (3.15++) ===

There are calls to replace the existing DB file format with an XML-based format. Currently the DB file parser is too highly integrated into the process of record creation to easily add a second format, but it would be feasible to separate these two and hence allow an expat-based or similar parser to be written. This would probably require a close analysis and upgrade to the locking arrangements of the database. Alternative to XML would be JSON, for which a parser is already being included in the jsonfm branch.

Libs affected: dbHost?, dbStatic.

=== New Record API ===

These requests all need a significant change to the record support API. They are also fairly closely related, so should be used as input into any new API that gets devised.

<blockquote>

==== Asynchronous Gets (3.16++) ====

From Tim Mooney: It would be great if an input link could initiate processing, and get a value that is known to be the result of that processing, even if
records to be processed are asynchronous. Currently, a record that needs completion-qualified data must know how to trigger the processing that generates that data.

From Ben Franksen: Implemented an asyncronous dbGetLinkCallback() routine. To do this properly though needs an upgrade to the record support API, but maybe could be shoe-horned into the the existing API by adding a dbGetLinkCallback() with a private callback pointer, and we'd require new record types to use this. What does this do to the device support interface though? Implications need study.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Blocking Puts (3.16++) ====

From Tim Mooney: It would be nice to have a link attribute that could put, request processing, and wait for completion. We have this capability now, in dbCaPutCallback(), but it's selectable only at DCT time.

The idea is for a version of the SEQ record where rather than a fixed delay, the second link would wait for the completion callback from the first link. This should be possible today with a special record type, but Tim suggests it should be possible with any link field of any record type.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Multiple Master problem (3.16++) ====

From Jeff: Changes to output values in a PLC or similar device initiated outside of the output record. This could be resolved adding a new routine to the RSET that the device support calls back when it has a new raw ouptut value to back-propagate to the VAL field. Currently done by some devices that set PACT and call the record's process() routine to use its second-half processing only.

==== Records Can't Block (3.16++) ====

From Tim Mooney: I think almost half the code in the sscan record is devoted to
bookmarking. In the middle of some algorithm, the record needs to wait for external events; the only way back in is process(), and so the record has to
have a complicated arrangement of switches that get it back into the
algorithm it was executing, with enough state information to decide what to do
next. At the same time, the record must check to see if it's now processing
because of some out-of-band request from the user. Normal and exceptional processing must, therefore, be mixed together in the switch
arrangement, and adding new behaviors to the record becomes a very hairy undertaking.

But what the record would really like to do is just wait with its
context intact for events, and allow special() to release it from the wait
if the user has requested something that requires this. I guess this means the record should include author-defined event types in the wait mask, and special() should be able to generate author-defined events.

</blockquote>

=== Dynamically Loaded Modules (3.16++) ===

After converting the DBD load process into table registration, it should become easier to allow support modules (containing record types, device support and other drivers) to be discovered and loaded dynamically. Unloading is a very different matter though, we don't have the shutdown facilities to allow that.

=== Atomic Operations through CA (3.16++) ===

This is related to the Asynch Gets issue above; implement Read-Write (Swap, permits semaphores), Process-Read and Write-Process-Read (Command/Response) as atomic operations available through Channel Access.

</blockquote>

Future Development Ideas

2010-10-18T16:06:41Z

RalphLange: /* Conversion Code Clean-Up */

These are projects that can/should be added to EPICS V3 using an evolutionary process. The ordering is not necessarily accurate.

__TOC__

== Tasks which could be done now ==

These items can be worked on immediately as they do not depend on any other work to have been completed, and could even be included in the next 3.14 release if appropriate.

<blockquote>

=== Bug Fixes ===

Bugs tagged 'codeathon' are especially appropriate.

=== Documentation (3.14/3.15) ===

Lots we can do here:

<blockquote>

==== Record Reference Manual ====

* Extend the DBD to HTML converter so we can move detailed record reference documentation into the record.dbd and/or record.c files. Should we attempt to embed the RRM text inside the DBD files?

==== Application Developers Guide ====

* Write a "Building and Porting EPICS" chapter
* Restructure the AppDevGuide to make it more accessible
** Combine the libCom and libCom/osi chapters
** Maybe have a separate section for all callable APIs
** Consider moving API documentation into the appropriate source files and using Doxygen or perldoc to extract it.

==== Other Documents ====

* Look at all the documentation we have and see what's missing
* Data Access, other new CA-related documentation...

</blockquote>

=== More test programs ===

There are test programs in libCom/test which cover quite a lot of the libCom functionality, but they are by far from complete. Writing test code is a very good way to learn the capabilities of the code being tested, and is not usually hard to to, so this would be a good "getting started" project.

Check the Diamond code coverage report as part of their Base Autotests for ideas what code to tackle.

Priority: Medium

=== IOC Test Framework in Perl ===

Once we have good test coverage for libCom we should look at IOC-level testing, including tests for individual record types. This needs code to start a soft IOC with a particular database file, make channel connections over CA and perform the necessary tests, then close down the IOC and clean up. Tests should be automatable, e.g. by generating TAP output and run under the standard Perl Test::Harness, as used by the 'make runtests' target.

Once the framework exists, write test programs for each core record type and device support. Look at the Soft-Test suite and implement those tests too, although a complete rewrite might be appropriate for them...

=== Convert makeBpt into Perl (3.15) ===

The makeBpt tool in src/bpt generates non-linear break-point tables from data files. A fair bit of the C code is concerned with parsing the input file. There is no particular need for this code to be written in C, speed is not an issue, and eventually I hope to convert all programs needed for building EPICS into Perl code. Maybe start this project by writing a program to test the output, then convert the C code into Perl.

=== Database diagnostics ===

When an IOC is too busy to service CA, the engineers need a way to find out what records are causing the problem. Something like a dbSpy command might be helpful, which would keep a count of the records processed by each scan thread and give periodic reports. Would need to be designed carefully so it doesn't eat RAM or slow down the machine too much.

Other diagnostics could also be added: dbProcess rate, ...

Priority: Medium<br>
Libs affected: db, dbStatic.

=== Record aliases in VDCT ===

EPICS Base R3.14.11 supports record aliases, but AFAIK VDCT does not (not sure about the new version of VDCT though). Both preserving the aliases attached to a record loaded from a .db file, and providing creation and editing capabilities for them through the GUI. This is a Java programming task which will need prior communication with CosyLab.

=== Move alarm*.h headers ===

A first step towards a more packagable build system would be to move the alarm.h and alarmString.h headers out of src/dbStatic; they are the only thing currently preventing src/catools and src/cap5 from being built immediately after src/ca.

=== RSRV Using EPICS_CAS_INTF_ Variables ===

Change the socket binding in rsrv to use the EPICS_CAS_INTF_ variable(s) so we can limit IOCs to a subset of the interfaces of the host it's running on.

=== Packagable Build System ===

The EPICS Build system currently does not distinguish between programs that are needed by IOC developers (e.g. dbToMenuH) and end-user programs (e.g. caget). We could divide our build targets into these very easily, which would make packaging EPICS Base much more straight-forward. I see the following parts:

<blockquote>

==== End-user Binaries ====

* catools
* Shared libraries
* SoftIoc (requires compiled-in DBD data though)

These could be installed into /usr/local from an RPM or equivalent packaging system.

==== Developer Tools ====

* flex, antelope binaries etc.
* static libraries
* DBD and header files
* Build system components

These could be packaged into a -devel RPM or equivalent.

</blockquote>

=== Extended Device Support (3.15) ===

Converting Asyn's device support layers to Extended support exposed the need to clean up the extended interface, i.e. reduce the code duplication which is currently required since the record knows nothing about the device change.

Libs affected: db, rec.

=== New Record Types ===

From Bob: Add record types - valve record, improved control records for PID and Lead/Lag (if we had a good process control guy to design the record).

Enhancements to PID should start from the most advanced implementation currently available, which is ''not'' the old PID record type from Base 3.13. There's a PID record in synApps, and there may be others available from other sites too.

Priority: Dalesio<br>
Libs affected: (external app)

=== CA support for Array with Timebase ===

From Bob: Add a new dbr_type into the channel access database - new array that includes time base and offset at least. One that also supports up to 3 dimensions (or better n).

Priority: Dalesio<br>
Libs affected: Many...

=== More flexible Access Security ===

The AS design defines each field's security level in the record description, and limits us to only levels 0 and 1. Some sites may want finer control over accesses: being able to put individual fields of a specific record into a different level, and having additional static levels (use a bitmask?) would help in a number of situations. It is not clear how much work this would entail though.

Priority: Low<br>
Libs affected: dbStatic, db, as, ...

=== Authentication ===

From Ralph: Two or three institutes need a way to password-protect access to certain databases. The usual encryption libraries are freely available, but I guess this issue needs a lot more thinking. Granularity: by record, by connection = IOC, or centralised? Should the authentication last for the client's lifetime or should a short form (some security token or key) be sent with every CA data package?

=== Secure CA ===

Secure channel access protocol - add SSL wrappers around CA to make it secure.

The CA-over-TCP branch should form the basis of this work.

Priority: R3.15<br>
Libs affected: ca, cas, rsrv

=== Online Record Creation ===

It might be possible to add new record instances at runtime, although delete would need a change to the record interface to support. The tricky thing is to do this in a manner which is completely thread-safe since the pdbbase structure does not have many locks, and adding them could significantly affect operation of the IOC.

Priority: Dalesio<br>
Libs affected: dbStatic, db, misc

=== Conversion Code Clean-Up ===

The existing conversion routines (i.e. the fast and full versions in db) could be significantly cleaned up by using C++ templated functions. There would probably be minor savings in object code size, but major savings in terms of source code size and clarity.

Here's a [[Conversion Code Clean-up|more detailed description]] of how this could be done.

Priority: 3.15<br>
Libs affected: dbStatic, db

</blockquote>

== Tasks which are already under way ==

These tasks are already being worked on but may have stalled. They might be hard for someone else to take over at this stage.

<blockquote>

=== CA Event Rate Limiting (3.15) ===

A CA client can specify a maximum event rate for each channel subscription it creates.

Waiting for: JSON field modifiers

=== CA Event Filtering (3.15) ===

A CA client can specify an event filter with the channel subscription which must be true for events to be posted to the client.

Waiting for: JSON field modifiers

=== Compiling DBD Files (3.15) ===

A Perl implementation of the DBD file parser exists and provides working dbdToRecordH and dbdToMenuH scripts. I'm working to revive my plans to convert all DBD file information into C tables that get compiled into the IOC executable or its shared libraries.

With this parser written in Perl, it is much easier to add new facilities to DBD files, such as adding new field types (see Variable Length Strings below).

Libs affected: dbStatic, +dbHost, db.

</blockquote>

== Things which can't be completed yet ==

These are tasks are waiting on other people or for other tasks to be completed before they can be finished, although there may be infrastructure to support them that can be worked on in parallel.

<blockquote>

=== IOCSH Command Registration (3.15) ===

Add DBD file syntax to convert DBD file information into a C header file which declares the command functions (similar to how we do record types in the current code-base). This header would then be included by the C file that defines those functions, thus the C compiler would do the work of ensuring that the routine implemented actually matches the command that will call it.

The command information in the DBD file will also be useful for future versions of the IRMIS parser for st.cmd scripts, where we need to be able to tie the device support configuration commands into IRMIS' need to map hardware devices to record addresses.

This should be done in the compiled-dbd branch.

Libs affected: dbHost, all libs Registrar code.

=== DBE_PROPERTY event generation (3.15) ===

Extend the DBD syntax to link all fields that contain property values with the fields that the property is supplied with, then have dbPut() post a DBE_PROPERTY monitor on those fields whenever the property value changes.

Libs affected: dbHost, dbStatic, db
Waiting for: Perl DBD Processing

=== Link Support (3.15+) ===

See original proposal by ANJ, which needs to be modified to add notify interfaces.

=== Array Field Support (3.16++) ===

Make it easier to add array fields to record types without having to do as much coding in the record support. See [http://www.aps.anl.gov/epics/core-talk/2007/msg00078.php Ben Franksen email] and the work done by Nick Rees at the 2009 Codeathon.

Libs affected: dbHost, dbStatic, db, rec.

=== Unbundling (3.15/++) ===

Split Base into three or more independent modules. Each module would have its own version number, and the modules can therefore each have an independent existance, although there would obviously be specific dependencies associated with particular versions.

If we adopt this, we should bundle working subsets of modules together and release the complete bundle as a tarfile.

I see the unbundled modules as follows:

<blockquote>

==== Core ====

Depends on: Nothing

These are the common parts used by everything:

* Build system
* libCom & OSI layer
** Basic registry routines
** IOC shell
* Antelope
* Flex
* makeApp tool

==== Channel Access Client ====

Depends on: Core

Jeff Hill's responsibility.

* CA-specific build rules (probably none)
* CA client library
* CA Tools
* CA application makeApp templates

==== Channel Access Server ====

Depends on: Core, IOC, CAC?

Jeff Hill's responsibility.

* CAS-specific build rules (probably none)
* GDD
* The CAS server tool
* RSRV (the old CA server code)
* CAS application makeApp templates

==== IOC ====

Depends on: Core, CAC, CAS

The rest is code that runs on the IOC.

* IOC-specific build rules
* Static and runtime database access
* Runtime database
* Standard record types
* Soft device support
* The registry (device, driver, record, function)
* IOC application makeApp templates

</blockquote>

=== Variable Length Strings (3.15++) ===

3.15 already includes the BaseString C++ classes in libCom, a set of C wrapper routines is needed for the base class operations. This can form the basis of a new variable length string type for use in the database in addition to DBF_STRING.

Libs affected: dbHost, dbStatic, db, ...

=== Device Status String Field ===

DESY want a string field in dbCommon for device support to post signal-specific status information to. Once we have variable-length string types it would be reasonable to add this (if not used/set it would only add one pointer to each record instance).

=== Alternate DB File Formats (3.15++) ===

There are calls to replace the existing DB file format with an XML-based format. Currently the DB file parser is too highly integrated into the process of record creation to easily add a second format, but it would be feasible to separate these two and hence allow an expat-based or similar parser to be written. This would probably require a close analysis and upgrade to the locking arrangements of the database. Alternative to XML would be JSON, for which a parser is already being included in the jsonfm branch.

Libs affected: dbHost?, dbStatic.

=== New Record API ===

These requests all need a significant change to the record support API. They are also fairly closely related, so should be used as input into any new API that gets devised.

<blockquote>

==== Asynchronous Gets (3.16++) ====

From Tim Mooney: It would be great if an input link could initiate processing, and get a value that is known to be the result of that processing, even if
records to be processed are asynchronous. Currently, a record that needs completion-qualified data must know how to trigger the processing that generates that data.

From Ben Franksen: Implemented an asyncronous dbGetLinkCallback() routine. To do this properly though needs an upgrade to the record support API, but maybe could be shoe-horned into the the existing API by adding a dbGetLinkCallback() with a private callback pointer, and we'd require new record types to use this. What does this do to the device support interface though? Implications need study.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Blocking Puts (3.16++) ====

From Tim Mooney: It would be nice to have a link attribute that could put, request processing, and wait for completion. We have this capability now, in dbCaPutCallback(), but it's selectable only at DCT time.

The idea is for a version of the SEQ record where rather than a fixed delay, the second link would wait for the completion callback from the first link. This should be possible today with a special record type, but Tim suggests it should be possible with any link field of any record type.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Multiple Master problem (3.16++) ====

From Jeff: Changes to output values in a PLC or similar device initiated outside of the output record. This could be resolved adding a new routine to the RSET that the device support calls back when it has a new raw ouptut value to back-propagate to the VAL field. Currently done by some devices that set PACT and call the record's process() routine to use its second-half processing only.

==== Records Can't Block (3.16++) ====

From Tim Mooney: I think almost half the code in the sscan record is devoted to
bookmarking. In the middle of some algorithm, the record needs to wait for external events; the only way back in is process(), and so the record has to
have a complicated arrangement of switches that get it back into the
algorithm it was executing, with enough state information to decide what to do
next. At the same time, the record must check to see if it's now processing
because of some out-of-band request from the user. Normal and exceptional processing must, therefore, be mixed together in the switch
arrangement, and adding new behaviors to the record becomes a very hairy undertaking.

But what the record would really like to do is just wait with its
context intact for events, and allow special() to release it from the wait
if the user has requested something that requires this. I guess this means the record should include author-defined event types in the wait mask, and special() should be able to generate author-defined events.

</blockquote>

=== Dynamically Loaded Modules (3.16++) ===

After converting the DBD load process into table registration, it should become easier to allow support modules (containing record types, device support and other drivers) to be discovered and loaded dynamically. Unloading is a very different matter though, we don't have the shutdown facilities to allow that.

=== Atomic Operations through CA (3.16++) ===

This is related to the Asynch Gets issue above; implement Read-Write (Swap, permits semaphores), Process-Read and Write-Process-Read (Command/Response) as atomic operations available through Channel Access.

</blockquote>

Future Development Ideas

2010-10-18T16:05:35Z

RalphLange: /* Conversion Code Clean-Up */

These are projects that can/should be added to EPICS V3 using an evolutionary process. The ordering is not necessarily accurate.

__TOC__

== Tasks which could be done now ==

These items can be worked on immediately as they do not depend on any other work to have been completed, and could even be included in the next 3.14 release if appropriate.

<blockquote>

=== Bug Fixes ===

Bugs tagged 'codeathon' are especially appropriate.

=== Documentation (3.14/3.15) ===

Lots we can do here:

<blockquote>

==== Record Reference Manual ====

* Extend the DBD to HTML converter so we can move detailed record reference documentation into the record.dbd and/or record.c files. Should we attempt to embed the RRM text inside the DBD files?

==== Application Developers Guide ====

* Write a "Building and Porting EPICS" chapter
* Restructure the AppDevGuide to make it more accessible
** Combine the libCom and libCom/osi chapters
** Maybe have a separate section for all callable APIs
** Consider moving API documentation into the appropriate source files and using Doxygen or perldoc to extract it.

==== Other Documents ====

* Look at all the documentation we have and see what's missing
* Data Access, other new CA-related documentation...

</blockquote>

=== More test programs ===

There are test programs in libCom/test which cover quite a lot of the libCom functionality, but they are by far from complete. Writing test code is a very good way to learn the capabilities of the code being tested, and is not usually hard to to, so this would be a good "getting started" project.

Check the Diamond code coverage report as part of their Base Autotests for ideas what code to tackle.

Priority: Medium

=== IOC Test Framework in Perl ===

Once we have good test coverage for libCom we should look at IOC-level testing, including tests for individual record types. This needs code to start a soft IOC with a particular database file, make channel connections over CA and perform the necessary tests, then close down the IOC and clean up. Tests should be automatable, e.g. by generating TAP output and run under the standard Perl Test::Harness, as used by the 'make runtests' target.

Once the framework exists, write test programs for each core record type and device support. Look at the Soft-Test suite and implement those tests too, although a complete rewrite might be appropriate for them...

=== Convert makeBpt into Perl (3.15) ===

The makeBpt tool in src/bpt generates non-linear break-point tables from data files. A fair bit of the C code is concerned with parsing the input file. There is no particular need for this code to be written in C, speed is not an issue, and eventually I hope to convert all programs needed for building EPICS into Perl code. Maybe start this project by writing a program to test the output, then convert the C code into Perl.

=== Database diagnostics ===

When an IOC is too busy to service CA, the engineers need a way to find out what records are causing the problem. Something like a dbSpy command might be helpful, which would keep a count of the records processed by each scan thread and give periodic reports. Would need to be designed carefully so it doesn't eat RAM or slow down the machine too much.

Other diagnostics could also be added: dbProcess rate, ...

Priority: Medium<br>
Libs affected: db, dbStatic.

=== Record aliases in VDCT ===

EPICS Base R3.14.11 supports record aliases, but AFAIK VDCT does not (not sure about the new version of VDCT though). Both preserving the aliases attached to a record loaded from a .db file, and providing creation and editing capabilities for them through the GUI. This is a Java programming task which will need prior communication with CosyLab.

=== Move alarm*.h headers ===

A first step towards a more packagable build system would be to move the alarm.h and alarmString.h headers out of src/dbStatic; they are the only thing currently preventing src/catools and src/cap5 from being built immediately after src/ca.

=== RSRV Using EPICS_CAS_INTF_ Variables ===

Change the socket binding in rsrv to use the EPICS_CAS_INTF_ variable(s) so we can limit IOCs to a subset of the interfaces of the host it's running on.

=== Packagable Build System ===

The EPICS Build system currently does not distinguish between programs that are needed by IOC developers (e.g. dbToMenuH) and end-user programs (e.g. caget). We could divide our build targets into these very easily, which would make packaging EPICS Base much more straight-forward. I see the following parts:

<blockquote>

==== End-user Binaries ====

* catools
* Shared libraries
* SoftIoc (requires compiled-in DBD data though)

These could be installed into /usr/local from an RPM or equivalent packaging system.

==== Developer Tools ====

* flex, antelope binaries etc.
* static libraries
* DBD and header files
* Build system components

These could be packaged into a -devel RPM or equivalent.

</blockquote>

=== Extended Device Support (3.15) ===

Converting Asyn's device support layers to Extended support exposed the need to clean up the extended interface, i.e. reduce the code duplication which is currently required since the record knows nothing about the device change.

Libs affected: db, rec.

=== New Record Types ===

From Bob: Add record types - valve record, improved control records for PID and Lead/Lag (if we had a good process control guy to design the record).

Enhancements to PID should start from the most advanced implementation currently available, which is ''not'' the old PID record type from Base 3.13. There's a PID record in synApps, and there may be others available from other sites too.

Priority: Dalesio<br>
Libs affected: (external app)

=== CA support for Array with Timebase ===

From Bob: Add a new dbr_type into the channel access database - new array that includes time base and offset at least. One that also supports up to 3 dimensions (or better n).

Priority: Dalesio<br>
Libs affected: Many...

=== More flexible Access Security ===

The AS design defines each field's security level in the record description, and limits us to only levels 0 and 1. Some sites may want finer control over accesses: being able to put individual fields of a specific record into a different level, and having additional static levels (use a bitmask?) would help in a number of situations. It is not clear how much work this would entail though.

Priority: Low<br>
Libs affected: dbStatic, db, as, ...

=== Authentication ===

From Ralph: Two or three institutes need a way to password-protect access to certain databases. The usual encryption libraries are freely available, but I guess this issue needs a lot more thinking. Granularity: by record, by connection = IOC, or centralised? Should the authentication last for the client's lifetime or should a short form (some security token or key) be sent with every CA data package?

=== Secure CA ===

Secure channel access protocol - add SSL wrappers around CA to make it secure.

The CA-over-TCP branch should form the basis of this work.

Priority: R3.15<br>
Libs affected: ca, cas, rsrv

=== Online Record Creation ===

It might be possible to add new record instances at runtime, although delete would need a change to the record interface to support. The tricky thing is to do this in a manner which is completely thread-safe since the pdbbase structure does not have many locks, and adding them could significantly affect operation of the IOC.

Priority: Dalesio<br>
Libs affected: dbStatic, db, misc

=== Conversion Code Clean-Up ===

The existing conversion routines (i.e. the fast and full versions in db) could be significantly cleaned up by using C++ templated functions. There would probably be minor savings in object code size, but major savings in terms of source code size and clarity.

Here's a [[conversion code clean-up|more detailed description]] of how this could be done.

Priority: 3.15<br>
Libs affected: dbStatic, db

</blockquote>

== Tasks which are already under way ==

These tasks are already being worked on but may have stalled. They might be hard for someone else to take over at this stage.

<blockquote>

=== CA Event Rate Limiting (3.15) ===

A CA client can specify a maximum event rate for each channel subscription it creates.

Waiting for: JSON field modifiers

=== CA Event Filtering (3.15) ===

A CA client can specify an event filter with the channel subscription which must be true for events to be posted to the client.

Waiting for: JSON field modifiers

=== Compiling DBD Files (3.15) ===

A Perl implementation of the DBD file parser exists and provides working dbdToRecordH and dbdToMenuH scripts. I'm working to revive my plans to convert all DBD file information into C tables that get compiled into the IOC executable or its shared libraries.

With this parser written in Perl, it is much easier to add new facilities to DBD files, such as adding new field types (see Variable Length Strings below).

Libs affected: dbStatic, +dbHost, db.

</blockquote>

== Things which can't be completed yet ==

These are tasks are waiting on other people or for other tasks to be completed before they can be finished, although there may be infrastructure to support them that can be worked on in parallel.

<blockquote>

=== IOCSH Command Registration (3.15) ===

Add DBD file syntax to convert DBD file information into a C header file which declares the command functions (similar to how we do record types in the current code-base). This header would then be included by the C file that defines those functions, thus the C compiler would do the work of ensuring that the routine implemented actually matches the command that will call it.

The command information in the DBD file will also be useful for future versions of the IRMIS parser for st.cmd scripts, where we need to be able to tie the device support configuration commands into IRMIS' need to map hardware devices to record addresses.

This should be done in the compiled-dbd branch.

Libs affected: dbHost, all libs Registrar code.

=== DBE_PROPERTY event generation (3.15) ===

Extend the DBD syntax to link all fields that contain property values with the fields that the property is supplied with, then have dbPut() post a DBE_PROPERTY monitor on those fields whenever the property value changes.

Libs affected: dbHost, dbStatic, db
Waiting for: Perl DBD Processing

=== Link Support (3.15+) ===

See original proposal by ANJ, which needs to be modified to add notify interfaces.

=== Array Field Support (3.16++) ===

Make it easier to add array fields to record types without having to do as much coding in the record support. See [http://www.aps.anl.gov/epics/core-talk/2007/msg00078.php Ben Franksen email] and the work done by Nick Rees at the 2009 Codeathon.

Libs affected: dbHost, dbStatic, db, rec.

=== Unbundling (3.15/++) ===

Split Base into three or more independent modules. Each module would have its own version number, and the modules can therefore each have an independent existance, although there would obviously be specific dependencies associated with particular versions.

If we adopt this, we should bundle working subsets of modules together and release the complete bundle as a tarfile.

I see the unbundled modules as follows:

<blockquote>

==== Core ====

Depends on: Nothing

These are the common parts used by everything:

* Build system
* libCom & OSI layer
** Basic registry routines
** IOC shell
* Antelope
* Flex
* makeApp tool

==== Channel Access Client ====

Depends on: Core

Jeff Hill's responsibility.

* CA-specific build rules (probably none)
* CA client library
* CA Tools
* CA application makeApp templates

==== Channel Access Server ====

Depends on: Core, IOC, CAC?

Jeff Hill's responsibility.

* CAS-specific build rules (probably none)
* GDD
* The CAS server tool
* RSRV (the old CA server code)
* CAS application makeApp templates

==== IOC ====

Depends on: Core, CAC, CAS

The rest is code that runs on the IOC.

* IOC-specific build rules
* Static and runtime database access
* Runtime database
* Standard record types
* Soft device support
* The registry (device, driver, record, function)
* IOC application makeApp templates

</blockquote>

=== Variable Length Strings (3.15++) ===

3.15 already includes the BaseString C++ classes in libCom, a set of C wrapper routines is needed for the base class operations. This can form the basis of a new variable length string type for use in the database in addition to DBF_STRING.

Libs affected: dbHost, dbStatic, db, ...

=== Device Status String Field ===

DESY want a string field in dbCommon for device support to post signal-specific status information to. Once we have variable-length string types it would be reasonable to add this (if not used/set it would only add one pointer to each record instance).

=== Alternate DB File Formats (3.15++) ===

There are calls to replace the existing DB file format with an XML-based format. Currently the DB file parser is too highly integrated into the process of record creation to easily add a second format, but it would be feasible to separate these two and hence allow an expat-based or similar parser to be written. This would probably require a close analysis and upgrade to the locking arrangements of the database. Alternative to XML would be JSON, for which a parser is already being included in the jsonfm branch.

Libs affected: dbHost?, dbStatic.

=== New Record API ===

These requests all need a significant change to the record support API. They are also fairly closely related, so should be used as input into any new API that gets devised.

<blockquote>

==== Asynchronous Gets (3.16++) ====

From Tim Mooney: It would be great if an input link could initiate processing, and get a value that is known to be the result of that processing, even if
records to be processed are asynchronous. Currently, a record that needs completion-qualified data must know how to trigger the processing that generates that data.

From Ben Franksen: Implemented an asyncronous dbGetLinkCallback() routine. To do this properly though needs an upgrade to the record support API, but maybe could be shoe-horned into the the existing API by adding a dbGetLinkCallback() with a private callback pointer, and we'd require new record types to use this. What does this do to the device support interface though? Implications need study.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Blocking Puts (3.16++) ====

From Tim Mooney: It would be nice to have a link attribute that could put, request processing, and wait for completion. We have this capability now, in dbCaPutCallback(), but it's selectable only at DCT time.

The idea is for a version of the SEQ record where rather than a fixed delay, the second link would wait for the completion callback from the first link. This should be possible today with a special record type, but Tim suggests it should be possible with any link field of any record type.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Multiple Master problem (3.16++) ====

From Jeff: Changes to output values in a PLC or similar device initiated outside of the output record. This could be resolved adding a new routine to the RSET that the device support calls back when it has a new raw ouptut value to back-propagate to the VAL field. Currently done by some devices that set PACT and call the record's process() routine to use its second-half processing only.

==== Records Can't Block (3.16++) ====

From Tim Mooney: I think almost half the code in the sscan record is devoted to
bookmarking. In the middle of some algorithm, the record needs to wait for external events; the only way back in is process(), and so the record has to
have a complicated arrangement of switches that get it back into the
algorithm it was executing, with enough state information to decide what to do
next. At the same time, the record must check to see if it's now processing
because of some out-of-band request from the user. Normal and exceptional processing must, therefore, be mixed together in the switch
arrangement, and adding new behaviors to the record becomes a very hairy undertaking.

But what the record would really like to do is just wait with its
context intact for events, and allow special() to release it from the wait
if the user has requested something that requires this. I guess this means the record should include author-defined event types in the wait mask, and special() should be able to generate author-defined events.

</blockquote>

=== Dynamically Loaded Modules (3.16++) ===

After converting the DBD load process into table registration, it should become easier to allow support modules (containing record types, device support and other drivers) to be discovered and loaded dynamically. Unloading is a very different matter though, we don't have the shutdown facilities to allow that.

=== Atomic Operations through CA (3.16++) ===

This is related to the Asynch Gets issue above; implement Read-Write (Swap, permits semaphores), Process-Read and Write-Process-Read (Command/Response) as atomic operations available through Channel Access.

</blockquote>

Future Development Ideas

2010-10-18T16:01:12Z

RalphLange: /* Tasks which could be done now */ add conversion code clean-up

These are projects that can/should be added to EPICS V3 using an evolutionary process. The ordering is not necessarily accurate.

__TOC__

== Tasks which could be done now ==

These items can be worked on immediately as they do not depend on any other work to have been completed, and could even be included in the next 3.14 release if appropriate.

<blockquote>

=== Bug Fixes ===

Bugs tagged 'codeathon' are especially appropriate.

=== Documentation (3.14/3.15) ===

Lots we can do here:

<blockquote>

==== Record Reference Manual ====

* Extend the DBD to HTML converter so we can move detailed record reference documentation into the record.dbd and/or record.c files. Should we attempt to embed the RRM text inside the DBD files?

==== Application Developers Guide ====

* Write a "Building and Porting EPICS" chapter
* Restructure the AppDevGuide to make it more accessible
** Combine the libCom and libCom/osi chapters
** Maybe have a separate section for all callable APIs
** Consider moving API documentation into the appropriate source files and using Doxygen or perldoc to extract it.

==== Other Documents ====

* Look at all the documentation we have and see what's missing
* Data Access, other new CA-related documentation...

</blockquote>

=== More test programs ===

There are test programs in libCom/test which cover quite a lot of the libCom functionality, but they are by far from complete. Writing test code is a very good way to learn the capabilities of the code being tested, and is not usually hard to to, so this would be a good "getting started" project.

Check the Diamond code coverage report as part of their Base Autotests for ideas what code to tackle.

Priority: Medium

=== IOC Test Framework in Perl ===

Once we have good test coverage for libCom we should look at IOC-level testing, including tests for individual record types. This needs code to start a soft IOC with a particular database file, make channel connections over CA and perform the necessary tests, then close down the IOC and clean up. Tests should be automatable, e.g. by generating TAP output and run under the standard Perl Test::Harness, as used by the 'make runtests' target.

Once the framework exists, write test programs for each core record type and device support. Look at the Soft-Test suite and implement those tests too, although a complete rewrite might be appropriate for them...

=== Convert makeBpt into Perl (3.15) ===

The makeBpt tool in src/bpt generates non-linear break-point tables from data files. A fair bit of the C code is concerned with parsing the input file. There is no particular need for this code to be written in C, speed is not an issue, and eventually I hope to convert all programs needed for building EPICS into Perl code. Maybe start this project by writing a program to test the output, then convert the C code into Perl.

=== Database diagnostics ===

When an IOC is too busy to service CA, the engineers need a way to find out what records are causing the problem. Something like a dbSpy command might be helpful, which would keep a count of the records processed by each scan thread and give periodic reports. Would need to be designed carefully so it doesn't eat RAM or slow down the machine too much.

Other diagnostics could also be added: dbProcess rate, ...

Priority: Medium<br>
Libs affected: db, dbStatic.

=== Record aliases in VDCT ===

EPICS Base R3.14.11 supports record aliases, but AFAIK VDCT does not (not sure about the new version of VDCT though). Both preserving the aliases attached to a record loaded from a .db file, and providing creation and editing capabilities for them through the GUI. This is a Java programming task which will need prior communication with CosyLab.

=== Move alarm*.h headers ===

A first step towards a more packagable build system would be to move the alarm.h and alarmString.h headers out of src/dbStatic; they are the only thing currently preventing src/catools and src/cap5 from being built immediately after src/ca.

=== RSRV Using EPICS_CAS_INTF_ Variables ===

Change the socket binding in rsrv to use the EPICS_CAS_INTF_ variable(s) so we can limit IOCs to a subset of the interfaces of the host it's running on.

=== Packagable Build System ===

The EPICS Build system currently does not distinguish between programs that are needed by IOC developers (e.g. dbToMenuH) and end-user programs (e.g. caget). We could divide our build targets into these very easily, which would make packaging EPICS Base much more straight-forward. I see the following parts:

<blockquote>

==== End-user Binaries ====

* catools
* Shared libraries
* SoftIoc (requires compiled-in DBD data though)

These could be installed into /usr/local from an RPM or equivalent packaging system.

==== Developer Tools ====

* flex, antelope binaries etc.
* static libraries
* DBD and header files
* Build system components

These could be packaged into a -devel RPM or equivalent.

</blockquote>

=== Extended Device Support (3.15) ===

Converting Asyn's device support layers to Extended support exposed the need to clean up the extended interface, i.e. reduce the code duplication which is currently required since the record knows nothing about the device change.

Libs affected: db, rec.

=== New Record Types ===

From Bob: Add record types - valve record, improved control records for PID and Lead/Lag (if we had a good process control guy to design the record).

Enhancements to PID should start from the most advanced implementation currently available, which is ''not'' the old PID record type from Base 3.13. There's a PID record in synApps, and there may be others available from other sites too.

Priority: Dalesio<br>
Libs affected: (external app)

=== CA support for Array with Timebase ===

From Bob: Add a new dbr_type into the channel access database - new array that includes time base and offset at least. One that also supports up to 3 dimensions (or better n).

Priority: Dalesio<br>
Libs affected: Many...

=== More flexible Access Security ===

The AS design defines each field's security level in the record description, and limits us to only levels 0 and 1. Some sites may want finer control over accesses: being able to put individual fields of a specific record into a different level, and having additional static levels (use a bitmask?) would help in a number of situations. It is not clear how much work this would entail though.

Priority: Low<br>
Libs affected: dbStatic, db, as, ...

=== Authentication ===

From Ralph: Two or three institutes need a way to password-protect access to certain databases. The usual encryption libraries are freely available, but I guess this issue needs a lot more thinking. Granularity: by record, by connection = IOC, or centralised? Should the authentication last for the client's lifetime or should a short form (some security token or key) be sent with every CA data package?

=== Secure CA ===

Secure channel access protocol - add SSL wrappers around CA to make it secure.

The CA-over-TCP branch should form the basis of this work.

Priority: R3.15<br>
Libs affected: ca, cas, rsrv

=== Online Record Creation ===

It might be possible to add new record instances at runtime, although delete would need a change to the record interface to support. The tricky thing is to do this in a manner which is completely thread-safe since the pdbbase structure does not have many locks, and adding them could significantly affect operation of the IOC.

Priority: Dalesio<br>
Libs affected: dbStatic, db, misc

=== Conversion Code Clean-Up ===

The existing conversion routines (i.e. the fast and full versions in db) could be significantly cleaned up by using C++ templated functions. There would probably be minor savings in object code size, but major savings in terms of source code size and clarity.

Priority: 3.15<br>
Libs affected: dbStatic, db

</blockquote>

== Tasks which are already under way ==

These tasks are already being worked on but may have stalled. They might be hard for someone else to take over at this stage.

<blockquote>

=== CA Event Rate Limiting (3.15) ===

A CA client can specify a maximum event rate for each channel subscription it creates.

Waiting for: JSON field modifiers

=== CA Event Filtering (3.15) ===

A CA client can specify an event filter with the channel subscription which must be true for events to be posted to the client.

Waiting for: JSON field modifiers

=== Compiling DBD Files (3.15) ===

A Perl implementation of the DBD file parser exists and provides working dbdToRecordH and dbdToMenuH scripts. I'm working to revive my plans to convert all DBD file information into C tables that get compiled into the IOC executable or its shared libraries.

With this parser written in Perl, it is much easier to add new facilities to DBD files, such as adding new field types (see Variable Length Strings below).

Libs affected: dbStatic, +dbHost, db.

</blockquote>

== Things which can't be completed yet ==

These are tasks are waiting on other people or for other tasks to be completed before they can be finished, although there may be infrastructure to support them that can be worked on in parallel.

<blockquote>

=== IOCSH Command Registration (3.15) ===

Add DBD file syntax to convert DBD file information into a C header file which declares the command functions (similar to how we do record types in the current code-base). This header would then be included by the C file that defines those functions, thus the C compiler would do the work of ensuring that the routine implemented actually matches the command that will call it.

The command information in the DBD file will also be useful for future versions of the IRMIS parser for st.cmd scripts, where we need to be able to tie the device support configuration commands into IRMIS' need to map hardware devices to record addresses.

This should be done in the compiled-dbd branch.

Libs affected: dbHost, all libs Registrar code.

=== DBE_PROPERTY event generation (3.15) ===

Extend the DBD syntax to link all fields that contain property values with the fields that the property is supplied with, then have dbPut() post a DBE_PROPERTY monitor on those fields whenever the property value changes.

Libs affected: dbHost, dbStatic, db
Waiting for: Perl DBD Processing

=== Link Support (3.15+) ===

See original proposal by ANJ, which needs to be modified to add notify interfaces.

=== Array Field Support (3.16++) ===

Make it easier to add array fields to record types without having to do as much coding in the record support. See [http://www.aps.anl.gov/epics/core-talk/2007/msg00078.php Ben Franksen email] and the work done by Nick Rees at the 2009 Codeathon.

Libs affected: dbHost, dbStatic, db, rec.

=== Unbundling (3.15/++) ===

Split Base into three or more independent modules. Each module would have its own version number, and the modules can therefore each have an independent existance, although there would obviously be specific dependencies associated with particular versions.

If we adopt this, we should bundle working subsets of modules together and release the complete bundle as a tarfile.

I see the unbundled modules as follows:

<blockquote>

==== Core ====

Depends on: Nothing

These are the common parts used by everything:

* Build system
* libCom & OSI layer
** Basic registry routines
** IOC shell
* Antelope
* Flex
* makeApp tool

==== Channel Access Client ====

Depends on: Core

Jeff Hill's responsibility.

* CA-specific build rules (probably none)
* CA client library
* CA Tools
* CA application makeApp templates

==== Channel Access Server ====

Depends on: Core, IOC, CAC?

Jeff Hill's responsibility.

* CAS-specific build rules (probably none)
* GDD
* The CAS server tool
* RSRV (the old CA server code)
* CAS application makeApp templates

==== IOC ====

Depends on: Core, CAC, CAS

The rest is code that runs on the IOC.

* IOC-specific build rules
* Static and runtime database access
* Runtime database
* Standard record types
* Soft device support
* The registry (device, driver, record, function)
* IOC application makeApp templates

</blockquote>

=== Variable Length Strings (3.15++) ===

3.15 already includes the BaseString C++ classes in libCom, a set of C wrapper routines is needed for the base class operations. This can form the basis of a new variable length string type for use in the database in addition to DBF_STRING.

Libs affected: dbHost, dbStatic, db, ...

=== Device Status String Field ===

DESY want a string field in dbCommon for device support to post signal-specific status information to. Once we have variable-length string types it would be reasonable to add this (if not used/set it would only add one pointer to each record instance).

=== Alternate DB File Formats (3.15++) ===

There are calls to replace the existing DB file format with an XML-based format. Currently the DB file parser is too highly integrated into the process of record creation to easily add a second format, but it would be feasible to separate these two and hence allow an expat-based or similar parser to be written. This would probably require a close analysis and upgrade to the locking arrangements of the database. Alternative to XML would be JSON, for which a parser is already being included in the jsonfm branch.

Libs affected: dbHost?, dbStatic.

=== New Record API ===

These requests all need a significant change to the record support API. They are also fairly closely related, so should be used as input into any new API that gets devised.

<blockquote>

==== Asynchronous Gets (3.16++) ====

From Tim Mooney: It would be great if an input link could initiate processing, and get a value that is known to be the result of that processing, even if
records to be processed are asynchronous. Currently, a record that needs completion-qualified data must know how to trigger the processing that generates that data.

From Ben Franksen: Implemented an asyncronous dbGetLinkCallback() routine. To do this properly though needs an upgrade to the record support API, but maybe could be shoe-horned into the the existing API by adding a dbGetLinkCallback() with a private callback pointer, and we'd require new record types to use this. What does this do to the device support interface though? Implications need study.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Blocking Puts (3.16++) ====

From Tim Mooney: It would be nice to have a link attribute that could put, request processing, and wait for completion. We have this capability now, in dbCaPutCallback(), but it's selectable only at DCT time.

The idea is for a version of the SEQ record where rather than a fixed delay, the second link would wait for the completion callback from the first link. This should be possible today with a special record type, but Tim suggests it should be possible with any link field of any record type.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Multiple Master problem (3.16++) ====

From Jeff: Changes to output values in a PLC or similar device initiated outside of the output record. This could be resolved adding a new routine to the RSET that the device support calls back when it has a new raw ouptut value to back-propagate to the VAL field. Currently done by some devices that set PACT and call the record's process() routine to use its second-half processing only.

==== Records Can't Block (3.16++) ====

From Tim Mooney: I think almost half the code in the sscan record is devoted to
bookmarking. In the middle of some algorithm, the record needs to wait for external events; the only way back in is process(), and so the record has to
have a complicated arrangement of switches that get it back into the
algorithm it was executing, with enough state information to decide what to do
next. At the same time, the record must check to see if it's now processing
because of some out-of-band request from the user. Normal and exceptional processing must, therefore, be mixed together in the switch
arrangement, and adding new behaviors to the record becomes a very hairy undertaking.

But what the record would really like to do is just wait with its
context intact for events, and allow special() to release it from the wait
if the user has requested something that requires this. I guess this means the record should include author-defined event types in the wait mask, and special() should be able to generate author-defined events.

</blockquote>

=== Dynamically Loaded Modules (3.16++) ===

After converting the DBD load process into table registration, it should become easier to allow support modules (containing record types, device support and other drivers) to be discovered and loaded dynamically. Unloading is a very different matter though, we don't have the shutdown facilities to allow that.

=== Atomic Operations through CA (3.16++) ===

This is related to the Asynch Gets issue above; implement Read-Write (Swap, permits semaphores), Process-Read and Write-Process-Read (Command/Response) as atomic operations available through Channel Access.

</blockquote>

RRM 3-13 Compression

2010-09-30T16:33:06Z

RalphLange: /* Algorithms and Related Fields */ Fix description of Average algorithm

[[RRM 3-13|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are five possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-13 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of every element of the array obtained from INP over time; that is, the entire array referenced by INP is retrieved, and for each element the new average is calculated and placed in the corresponding element of the value buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the buffer. Thus, VAL[0] holds the average of the first element of INP over N samples, VAL[1] holds the average of the next element of INP over N samples, and so on. The following shows the equation:

[[Image:RRM 3-13 Compression-1.gif]]

If <CODE>N to 1 Low Value</CODE>, <CODE>N to 1 High Value</CODE>, or <CODE>N to 1 Average</CODE> are chosen, then VAL is a circular buffer of NSAM samples. The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (LOW, HIGH, or AVE), is written to the circular buffer referenced by VAL. If LOW, the lowest value is written; if HIGH, the highest value of all the samples is written; and if AVE, the average of all the samples are written.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average

The compression record keeps (NSAM) data samples.

The N field determines the number of fields to compress into 1.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-13 Compression-2.gif]]

OFF number of samples are ignored at the beginning of the array being compressed. IHIL and ILIL are used as initial value filters when compressing arrays; that is, the compression does not begin until a value is found that is either greater than IHIL or less than ILIL

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Compression

2010-09-30T16:32:56Z

RalphLange: /* Algorithms and Related Fields */ Fix description of Average algorithm

[[RRM 3-14|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are five possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of every element of the array obtained from INP over time; that is, the entire array referenced by INP is retrieved, and for each element the new average is calculated and placed in the corresponding element of the value buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the buffer. Thus, VAL[0] holds the average of the first element of INP over N samples, VAL[1] holds the average of the next element of INP over N samples, and so on. The following shows the equation:

[[Image:RRM 3-14 Compression-1.gif]]

If <CODE>N to 1 Low Value</CODE>, <CODE>N to 1 High Value</CODE>, or <CODE>N to 1 Average</CODE> are chosen, then VAL is a circular buffer of NSAM samples. The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (LOW, HIGH, or AVE), is written to the circular buffer referenced by VAL. If LOW, the lowest value is written; if HIGH, the highest value of all the samples is written; and if AVE, the average of all the samples are written.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average

The compression record keeps (NSAM) data samples.

The N field determines the number of fields to compress into 1.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-14 Compression-2.gif]]

OFF number of samples are ignored at the beginning of the array being compressed. IHIL and ILIL are used as initial value filters when compressing arrays; that is, the compression does not begin until a value is found that is either greater than IHIL or less than ILIL

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

How to check out EPICS Base with Bazaar

2010-05-26T14:18:12Z

RalphLange: Added bzr+ssh: spec hint (might work through firewall when lp: doesn't)

Bazaar can support several different approaches; the one you should use depends on what you expect to do with the code-base. It usually allows you to change your mind later though, so don't worry if you pick the wrong model to start with, you can modify your configuration as you need later on (although I'm not going to give instructions on how to do that here, read the documentation).

You must have Bazaar version 2.x installed; older versions do not support the same repository format. I'm using version 2.0.1 at the time of writing this, but any release in the 2.x series should be fine.

Bazaar has extensive built-in help text, just type 'bzr help <command>' for more information on <command> or 'bzr help topics' for a list of other help topics. The complete documentation for the tool can be found online [http://doc.bazaar.canonical.com/bzr.2.0/en/ here].

If you have problems connecting to launchpad and your network requires you to use an HTTP proxy server, make sure that you have both the http_proxy and https_proxy environment variables set appropriately.

If you are behind a firewall and the 'lp:' shorthand does not work, try the following transport specification:
bzr checkout bzr+ssh://<lp-user-name>@bazaar.launchpad.net/~epics-core/epics-base/3.14/

__TOC__

== Check out a working tree (for users, CVS model, remote history) ==

Use this option if you just want to a copy of the latest version of Base from the repository (for example to build and test) but don't expect to modify the code at all, or to look at its history much. This approach is very similar to using CVS since you only download a copy of the particular revision you're interested in, but it require network connectivity for all activities that access the repository in any way. An EPICS Base 3.14 working tree uses about 12MB of disk space at the time of writing.

The following command will create a directory tree called base-3.14 containing the latest code that was checked in to the 3.14 branch of Base:
bzr checkout --lightweight lp:epics-base/3.14 base-3.14

The lp: path above specifies a branch to check out from the launchpad server. The branch at lp:epics-base/3.14 is a branch containing all the development work for the R3.14 releases of Base. There are similar branches for the older series, although we're not expecting anyone to check any of these out; they're provided for historical reasons. The development on the branch called trunk will eventually become the 3.15 series.

If you want to check out a specific tagged version, in this case we're requesting the R3.14.11 release, use this command instead:
bzr checkout --lightweight -r tag:R3.14.11 lp:epics-base/3.14 base-3.14

To update a lightweight working tree at a later date with the latest changes from the branch, use this command inside the tree:
bzr update

You can use the command 'bzr tags' from inside the working tree to list all the tags known on this branch.

Unlike CVS, 'bzr update' cannot apply changes that move your tree to a different historical revision; for that you use the command below, in this case to move to the R3.14.10 release tag:
bzr revert -r tag:R3.14.10

If you made any local changes to the files in the working tree your changes will be retained through a 'bzr update' or 'bzr revert' operation. Any local changes that overlap with changes from the repository will create a conflict and have to be resolved by hand, just as happens with CVS.

If you find yourself using Bazaar commands inside the tree more than once or twice, you should probably check out a branch instead, which makes a local copy of the complete history of the branch and removes the need for network activity to access that history.

== Check out a branch (for users, local history) ==

This option is similar to the previous one but also gives you a local copy of the complete history of the branch. This speeds up all activities that need to examine the repository history, but since the local branch is still bound to the central repository at launchpad.net you can't commit any changes to it without write permission for the repository branch. A 3.14 branch needs about 28MB of disk space at the time of writing.

The following command will create a directory tree called base-3.14 containing the latest code and all of the history that was checked in to the 3.14 branch of Base:
bzr checkout lp:epics-base/3.14 base-3.14

The lp: path above specifies a branch to check out from the launchpad server. The branch at lp:epics-base/3.14 is a branch containing all the development work for the R3.14 releases of Base. There are similar branches for the older series, although we're not expecting anyone to check any of these out; they're provided for historical reasons. The development on the branch called trunk will eventually become the 3.15 series.

If you want to check out a particular tagged version, use this command instead:
bzr checkout -r tag:R3.14.11 lp:~epics-core/epics-base/3.14 base-3.14

Inside the working tree, Bazaar supports the expected commands 'bzr log' and 'bzr diff' to examine file history. Use 'bzr help revisionspec' for information on specifying particular revisions to examine.

To update your working tree with the latest changes from the parent branch at some later date, use this command inside the tree:
bzr update
Note that if you're working in a regular branch and not a checkout, the command to use is
bzr pull
and if you have committed changes to your branch that are not in the parent
bzr merge

Note that 'bzr pull' or 'bzr update' cannot move your tree to a different historical revision like in CVS, for that you use this command:
bzr revert -r tag:R3.14.10

You can use 'bzr tags' when inside the working tree to list all the tags known on this branch.

If you made any local changes to the files in the working tree your changes will be retained through a 'bzr update' or 'bzr revert' operation. Any local changes that overlap with changes from the repository will create a conflict and have to be resolved by hand, just as happens with CVS.

If you want to keep some permanent local changes, consider unbinding your tree from the central repository branch, which converts it to a regular branch. This will allow you to check local changes into the local repository while still permitting 'bzr update' to fetch changes as before. The 'bzr unbind' command does this, and can be undone again with 'bzr bind'.

== Developer Branches ==

Developers have a more complex configuration since they usually want to be able to commit their changes to a local repository and later on merge those changes into the branch in the central repository. The model described here corresponds to the "decentralized with shared mainline" workflow given in the [http://doc.bazaar.canonical.com/bzr.2.0/en/user-guide/distributed_intro.html Bazaar User Guide].

=== Initial Checkout ===

First initialize a local repository in a parent directory which will be used as the backing-store to hold the history of all your development work on EPICS Base, then inside this directory checkout a mirror branch of Base from Launchpad:
bzr init-repo ~/epics-base
cd ~/epics-base
bzr checkout lp:epics-base/3.14 mirror-3.14

This mirror branch should never be used directly for developing new code or major bug fixing, but can be used for "obviously correct" changes to things like comments or string literals. Major work should take place in a different tree usually called a ''feature'' or ''task branch''. The mirror branch allows you to merge tested sets of changes from your feature branches into the central repository. Performing a commit in the mirror branch will immediately push the change to the official branch on the Launchpad website.

=== Creating a Task Branch ===

Bazaar encourages developers to create a separate branch for each separate feature or bug fix being developed, which would normally be created as a sibling to the mirror branch we checked out above. While working on the fix you are free to commit changes whenever you like, which are recorded in your local repository:
cd ~/epics-base
bzr branch mirror-3.14 fix-123
cd fix-123
# ''Hack...''
bzr ci -m 'Hacked the frooz-bodger to stop it wibbling'

If a commit fixes a bug registered on Launchpad, you can have Bazaar record that fact like this:
bzr ci --fixes=lp:123

=== Merges: Updating ===

While you're working other developers may be committing changes into the central branch. To incorporate those changes into your task branches is a two-stage process: First update your mirror branch to fetch those changes from the central repository, then merge and commit them into each of your working trees. Note that you should either shelve (see below) or check in any local modifications into the task branch before doing the merge step (if you use --force you risk mixing up your changes with someone else's):
cd ~/epics-base
bzr update mirror-3.14
# ''For each task branch:''
cd fix-123
bzr merge
# ''Fix any conflicts and tell bzr like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m 'Merged with 3.14'

If you have not committed any changes to your fix-123 branch yet, you can skip the shelve step and combine the merge and commit phases above into a single command, so that after updating the mirror-3.14 tree as above, you just do this:
cd fix-123
bzr pull
# ''Should report any conflicts''

If you're not sure whether you've made any commits or not, you can ask Bazaar:
cd fix-123
bzr missing
# ''Reports commit differences between trees''

=== Merges: Committing Changes ===

The ability to commit changes to the central repository is restricted to members of the epics-core team at [https://launchpad.net/ Launchpad.net], but Bazaar and Launchpad will still allow you to publish branches containing your own development even if you do not belong to that team; a team-member can subsequently merge and commit the changes from your branch into the official one.

For epics-core members, a feature branch is merged and committed to the central branch as follows:
cd ~/epics-base/mirror-3.14
bzr update
bzr missing ../fix-123
# ''Check that you're about to merge the right changes''
bzr merge ../fix-123
# ''Fix any conflicts and tell Bazaar like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m 'Fixed bug #123'

If you're merging someone else's branch which is published on Launchpad, you can use the lp:~user/epics-base/branch-name URL for their branch directly, it is not necessary to download or checkout a copy of a branch to merge it:
cd ~/epics-base/mirror-3.14
bzr update
bzr missing lp:~mdavidsaver/epics-base/rec-init
# ''Check that you're about to merge the right changes''
bzr merge lp:~mdavidsaver/epics-base/rec-init
bzr ci -m "Merged Michael Davidsaver's 'rec-init' branch."

To apply a bug-fix change to more than one series branch, say to both 3.14 and the main trunk, Bazaar's merge command allows you to cherry-pick commits from a different branch. If it's just one check-in this is very easy, especially if it's the last commit you made to that source branch. In that case, you would use these commands to merge those changes to the trunk:
cd ~/epics-base/mirror-trunk
bzr update
bzr merge -c -1 ../fix-123
# ''Fix any conflicts and tell bzr like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m 'Fixed bug #123'
The '-c -1' option to 'bzr merge' means "cherry-pick just the last commit", '-c -2' would be the penultimate commit and so on. You can use 'bzr log' in the feature branch to find a specific absolute revision number on that branch and use that instead of the negative numbers. If there were several commits you can give 'bzr merge' a range using the option '-r 44..47' instead, but note that '-r 44' means "merge all changes up to and including revision 44." If you get it wrong, you can always use 'bzr revert' to undo.

After you have merged and committed your changes from a feature branch into the central branch(es) at launchpad, you may delete the branch directory as necessary ('rm -rf fix-123').

=== Shelving Local Changes ===

If you have some local changes that you don't want to commit, say some CONFIG_SITE changes needed to build the code at your site, you can use 'bzr shelve configure/CONFIG_SITE' to temporarily hide them before committing or merging, and 'bzr unshelve' later to bring them back. The shelve command will show you each of the changes in the named file(s) in turn and ask whether you want to shelve it or not. Read the 'bzr help shelve' output for more details.

=== Publishing a Branch ===

If you're not a member of epics-core, you can still publish your own branches of the epics-base project on Launchpad where other people can find and use them. You must have registered for an account at [https://launchpad.net/ Launchpad.net] first and uploaded your ssh public-key.
bzr launchpad-login ''userid''
cd ~/epics-base/fix-123
bzr push lp:~''user-id''/epics-base/fix-123

If you are a member of epics-core, you can create a shared branch that other members can also commit to by using the group name as the user-id in the Bazaar target path:
bzr push lp:~epics-core/epics-base/feature-xyz

CA over TCP

2010-04-15T20:55:52Z

RalphLange: Adde status section with links to Launchpad

: ''Initial changes: [[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''
: ''Rebase/merge to 3.14 and additional fixes: [[User:RalphLange|Ralph Lange]], April 2010''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

A possible implementation would be a client-side caRepeater which connects through a 5065/TCP connection to a server-side caRepeater. That way neither client nor server code would have to be changed.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement friend SearchDest::searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback::notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
* casStrmClient changes
** add private client addr member (init'd through constructor arg)
** add casStrmClient::searchAction that does roughly the same as the casDGClient::searchAction ''(maybe this could be refactored and moved to a separate name resolver class to avoid code repetition)''
** add casStrmClient::asyncSearchResponse and casStrmClient::searchResponse ''(again: same as casDGClient methods)''
* casStreamIO changes
** add private client address member
** add public methods to get client host name and address

=== rsrv ===
* camessage.c changes
** rename search_reply() to search_reply_udp()
** add search_reply_tcp() with similar functionality
** change jump table accordingly

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

== Status ==

The original changes (against 3.15 aka CVS trunk) have been pulled out and merged into a development branch.

Development branch: https://code.launchpad.net/~ralph-lange/epics-base/ca-over-tcp

Blueprint: https://blueprints.launchpad.net/epics-base/+spec/ca-over-tcp

Core Developer Pages

2010-04-15T20:50:22Z

RalphLange: Put CA over TCP back to current development

== Developing EPICS Base ==

* [[How to check out EPICS Base with Bazaar]]

== Development Plans ==

* [[Future Development Ideas]]

=== Current Development Work ===

* [[Migrate from CVS to Bazaar]]
* [[CA over TCP]] - Allow Channel Access to be run through an SSH tunnel

=== Completed Development Work ===

I think these are done now:

CA over TCP

2010-04-15T20:48:31Z

RalphLange: Added header note

CA over TCP

2010-04-15T20:44:47Z

RalphLange: /* Beacons */ Added low-impact idea for beacons over TCP

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

A possible implementation would be a client-side caRepeater which connects through a 5065/TCP connection to a server-side caRepeater. That way neither client nor server code would have to be changed.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement friend SearchDest::searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback::notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
* casStrmClient changes
** add private client addr member (init'd through constructor arg)
** add casStrmClient::searchAction that does roughly the same as the casDGClient::searchAction ''(maybe this could be refactored and moved to a separate name resolver class to avoid code repetition)''
** add casStrmClient::asyncSearchResponse and casStrmClient::searchResponse ''(again: same as casDGClient methods)''
* casStreamIO changes
** add private client address member
** add public methods to get client host name and address

=== rsrv ===
* camessage.c changes
** rename search_reply() to search_reply_udp()
** add search_reply_tcp() with similar functionality
** change jump table accordingly

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T20:41:41Z

RalphLange: /* CA Client */

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement friend SearchDest::searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback::notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
* casStrmClient changes
** add private client addr member (init'd through constructor arg)
** add casStrmClient::searchAction that does roughly the same as the casDGClient::searchAction ''(maybe this could be refactored and moved to a separate name resolver class to avoid code repetition)''
** add casStrmClient::asyncSearchResponse and casStrmClient::searchResponse ''(again: same as casDGClient methods)''
* casStreamIO changes
** add private client address member
** add public methods to get client host name and address

=== rsrv ===
* camessage.c changes
** rename search_reply() to search_reply_udp()
** add search_reply_tcp() with similar functionality
** change jump table accordingly

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T20:40:45Z

RalphLange: /* CAS */

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
* casStrmClient changes
** add private client addr member (init'd through constructor arg)
** add casStrmClient::searchAction that does roughly the same as the casDGClient::searchAction ''(maybe this could be refactored and moved to a separate name resolver class to avoid code repetition)''
** add casStrmClient::asyncSearchResponse and casStrmClient::searchResponse ''(again: same as casDGClient methods)''
* casStreamIO changes
** add private client address member
** add public methods to get client host name and address

=== rsrv ===
* camessage.c changes
** rename search_reply() to search_reply_udp()
** add search_reply_tcp() with similar functionality
** change jump table accordingly

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T20:30:15Z

RalphLange: /* CAS */

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
* casStrmClient changes
** add private client addr member (init'd through constructor arg)
** add casStrmClient::searchAction that does roughly the same as the casDGClient::searchAction ''(probably this should be moved to separate name resolver class to avoid code repetition)''
** add casStrmClient::asyncSearchResponse and casStrmClient::searchResponse ''(again: same as casDGClient methods, should be moved to a resolver than both can use)''
* casStreamIO changes
** add private client address member
** add public methods to get client host name and address

=== rsrv ===
* camessage.c changes
** rename search_reply() to search_reply_udp()
** add search_reply_tcp() with similar functionality
** change jump table accordingly

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T19:28:21Z

RalphLange: /* rsrv */ Added changes to rsrv

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
* casStrmClient changes
** add private client addr member (init'd through constructor arg)
** add casStrmClient::searchAction that does roughly the same as the casDGClient::searchAction ''(probably this could be moved to a base class. casCoreClient?)''
** add casStrmClient::asyncSearchResponse and casStrmClient::searchResponse ''(again: same as casDGClient methods)''
* casStreamIO changes
** add private client address member
** add public methods to get client host name and address

=== rsrv ===
* camessage.c changes
** rename search_reply() to search_reply_udp()
** add search_reply_tcp() with similar functionality
** change jump table accordingly

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T19:25:17Z

RalphLange: /* CAS */ Added changes in cas

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
* casStrmClient changes
** add private client addr member (init'd through constructor arg)
** add casStrmClient::searchAction that does roughly the same as the casDGClient::searchAction ''(probably this could be moved to a base class. casCoreClient?)''
** add casStrmClient::asyncSearchResponse and casStrmClient::searchResponse ''(again: same as casDGClient methods)''
* casStreamIO changes
** add private client address member
** add public methods to get client host name and address

=== rsrv ===
None.

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T19:10:01Z

RalphLange: /* CA Client */

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor)
** creates SearchDestTCP and adds it to the search list
** creates tcpiiu specifying the SeachDestTCP to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
''to be identified''

=== rsrv ===
None.

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T19:08:00Z

RalphLange: /* CA Client */

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor?)
** creates tcpiiu specifying nameService is true to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
''to be identified''

=== rsrv ===
None.

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T19:03:57Z

RalphLange: /* ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks */

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** private member class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor?)
** creates tcpiiu specifying nameService is true to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
''to be identified''

=== rsrv ===
None.

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix: (2010-04-15)'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T19:03:32Z

RalphLange: /* ''Fixed:'' TCP Nameserver Connections Do Not Reconnect */

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** private member class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor?)
** creates tcpiiu specifying nameService is true to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
''to be identified''

=== rsrv ===
None.

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix (2010-04-09):'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix:'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

CA over TCP

2010-04-15T17:53:14Z

RalphLange: /* Issues */ Added "Fixed: TCP Nameserver Connection Down Blocks All Callbacks"

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** private member class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor?)
** creates tcpiiu specifying nameService is true to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
''to be identified''

=== rsrv ===
None.

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix:'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

=== ''Fixed:'' TCP Nameserver Connection Down Blocks All Callbacks ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client's TCP receive thread tries to reconnect in an endless loop, doing a epicsThreadSleep(cac.connectionTimeout) between attempts.
While the receive thread is sleeping, no other CA callbacks are executed.

''Fix:'' tcpRecvThread::connect() holds the cac mutex lock. That lock must be released during the epicsThreadSleep().

RRM 3-14 Calcout

2010-04-13T18:57:52Z

RalphLange: /* Expression */ Added ';', literals, constants, assignment

[[RRM 3-14|EPICS Record Reference Manual]]

= Calcout - Calculation Output Record =

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.

== Parameter Fields ==

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

=== Scan Parameters ===

The Calcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] 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 <CODE>I/O Intr</CODE>.

=== 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 <CODE>dbPuts</CODE>. 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 [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== 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 [[#Output Parameters|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 infix expressions that can be used are very similar to the C expression syntax, but with some additions and subtle differences in operator meaning and precedence. The string may contain a series of expressions separated by a semi-colon character ';' any one of which may actually provide the calculation result; however all of the other expressions included must assign their result to a variable. All alphabetic elements described below are case independent, so upper and lower case letters may be used and mixed in the variable and function names as desired. Spaces may be used anywhere within an expression except between the characters that make up a single expression element.

The range of expressions supported by the calculation record are separated into literals, constants, operands, algebraic operators, trigonometric operators, relational operators, logical operators, the assignment operator, parentheses and commas, and the question mark or '?:' operator.

-----
'''NOTE:''' A complete up-to-date description of the calculation expression can be found in the '''Application Developer's Guide''', chapter libCom / calc / Infix Expression Syntax (19.2.1 for EPICS 3.14.11).
-----

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Literals ====

* Standard double precision floating point numbers
* Inf: Infinity
* Nan: Not a Number

==== Constants ====

* PI: returns the mathematical constant π
* D2R: evaluates to π/180 which, when used as a multiplier, converts an angle from degrees to radians
* R2D: evaluates to 180/π which as a multiplier converts an angle from radians to degrees

==== Operands ====

The expression can use the values retrieved from the INP''x'' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the expression's result field, i.e. the VAL field for the CALC expression and the OVAL field for the OCAL expression. (These fields can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

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.

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

==== Assignment Operator ====

* := : assigns a value (right hand side) to a variable (i.e. field)

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

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

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 <CODE>Use OCAL</CODE> 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 system dependent.

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 <CODE>get_units</CODE> 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:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

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 [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# 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 <CODE>execOutput()</CODE> routine below.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, set PACT FALSE, and return.

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# 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).
# If an output delay was implemented, process the forward link.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calculation

2010-04-13T18:57:42Z

RalphLange: /* Expression */ Added ';', literals, constants, assignment

[[RRM 3-14|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls a function to convert it to Reverse Polish Notation.

The infix expressions that can be used are very similar to the C expression syntax, but with some additions and subtle differences in operator meaning and precedence. The string may contain a series of expressions separated by a semi-colon character ';' any one of which may actually provide the calculation result; however all of the other expressions included must assign their result to a variable. All alphabetic elements described below are case independent, so upper and lower case letters may be used and mixed in the variable and function names as desired. Spaces may be used anywhere within an expression except between the characters that make up a single expression element.

The range of expressions supported by the calculation record are separated into literals, constants, operands, algebraic operators, trigonometric operators, relational operators, logical operators, the assignment operator, parentheses and commas, and the question mark or '?:' operator.

-----
'''NOTE:''' A complete up-to-date description of the calculation expression can be found in the '''Application Developer's Guide''', chapter libCom / calc / Infix Expression Syntax (19.2.1 for EPICS 3.14.11).
-----

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Literals ====

* Standard double precision floating point numbers
* Inf: Infinity
* Nan: Not a Number

==== Constants ====

* PI: returns the mathematical constant π
* D2R: evaluates to π/180 which, when used as a multiplier, converts an angle from degrees to radians
* R2D: evaluates to 180/π which as a multiplier converts an angle from radians to degrees

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

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.

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

==== Assignment Operator ====

* := : assigns a value (right hand side) to a variable (i.e. field)

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calcout

2010-04-13T18:24:11Z

RalphLange: /* Operands */ Fix: VAL keyword returns OVAL for OCAL

[[RRM 3-14|EPICS Record Reference Manual]]

= Calcout - Calculation Output Record =

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.

== Parameter Fields ==

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

=== Scan Parameters ===

The Calcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] 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 <CODE>I/O Intr</CODE>.

=== 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 <CODE>dbPuts</CODE>. 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 [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== 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 [[#Output Parameters|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.

-----
'''NOTE:''' A complete description of the calculation expression can be found in the '''Application Developer's Guide''', chapter libCom / calc / Infix Expression Syntax (19.2.1 for EPICS 3.14.11).
-----

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE> 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.

==== Operands ====

The expression can use the values retrieved from the INP''x'' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the expression's result field, i.e. the VAL field for the CALC expression and the OVAL field for the OCAL expression. (These fields can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

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

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 <CODE>Use OCAL</CODE> 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 system dependent.

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 <CODE>get_units</CODE> 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:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

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 [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# 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 <CODE>execOutput()</CODE> routine below.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, set PACT FALSE, and return.

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# 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).
# If an output delay was implemented, process the forward link.

----

EPICS Record Reference Manual - 19 MAY 1998

CA over TCP

2010-04-09T14:28:48Z

RalphLange: Added issue found - and the fix applied.

: ''[[User:JeffHill|Jeff Hill]] and [[User:RalphLange|Ralph Lange]], Codeathon 2008''

: (This refers to the [[User:AndrewJohnson/V3_Evolution#CA_over_TCP| CA over TCP]] topic of Andrew's project list.)

== Goal ==

Provide a way to run CA on TCP circuits. Intended use: Run CA clients remotely that use an ssh tunnel to safely and securely connect to the control system. For security reasons these tunneled connections should connect to a CA Gateway.

== Approach ==

TCP connections can easily be tunneled through ssh. To allow CA connections through a TCP tunnel, the use of UDP (currently for name resolution and server beacons) must be avoided.

=== Beacons ===
We are just ignoring the beacon topic for the time being. With the current EPICS release, CA clients do not raise the search interval above a certain limit. Even without beacon anomalies being detected, all unresolved channels will connect sooner or later. That should be good enough for a start.

=== Name Resolution ===
A new environment variable EPICS_CA_NAME_SERVERS will be used to configure TCP name resolution. This variable takes a list of IP addresses. The client will open regular TCP connections (default port 5064) to those servers at init time and issue name resolution requests over TCP in addition to issuing the UDP requests to addresses in EPICS_CA_ADDR_LIST.

The CA server will be changed to forward the name resolution requests coming from TCP directly to the server tool.

Servers that are not capable of handling name requests over TCP (e.g. older rsrv or CAS version) will be ignored, i.e. the client will not see the requested channels through TCP and not connect unless a different (name) server answers the request.

== List of Necessary Changes ==

=== CA Client ===
* tcpiiu changes
** add bool _nameService private member data flag
** pass bool nameService arg to tcpiiu constructor (setting private bool flag)
** if _nameService, constructor registers member SearchDest with cac
** if _nameService, destructor unregisters member SearchDest with cac
** if _nameService flag is set send thread sleeps and then tries to connect again if connect fails
** if _nameService flag set the receive thread, upon receiving disconnect notification from the socket
*** command send thread to exit
*** waits for send thread exit
*** (clear all buffers)
*** sleep
*** restarts the send thread
*** exits
** private member class deriving from SearchDest called SearchDestTCP
** private member of type SearchDestTCP called _searchDest
** implement code calling Callback :: notify () when resp to search request arrives
** implement SearchDest :: searchRequest () that issues a tcp search request if server is capable, else directly calls the Callback :: notify ()

* udpiiu changes
** private member class deriving from SearchDest called SearchDestUDP
*** instances on the search list
** private member class deriving from SearchDest :: Callback called SearchRespCallback
*** implement SearchRespCallback :: notify ()
** implement code calling Callback :: notify () when resp to search request arrives
** build udp search dest objects
*** remove "dest" member data
*** add private tsDLLList < SearchDest > list called _searchDestList
*** build address list ELLLIST using iocinf.c code parsing addr list and traversing NICs
*** for each member of this list create private SearchDest derived objects
*** install the SearchDest derived objects in _searchDestList
*** destroy ELLLIST members
** add public register/unregister SearchDest to udpiiu (called by cac)

* cac changes
** code parsing EPICS_CA_NAME_SERVERS (in constructor?)
** creates tcpiiu specifying nameService is true to its constructor
** add public register/unregister SearchDest to cac (called by tcpiiu const and dest)
** in destructor guarantee that udpiiu is shutdown prior to deleting nameService tcpiiu

=== CAS ===
''to be identified''

=== rsrv ===
None.

== Issues ==

=== ''Fixed:'' TCP Nameserver Connections Do Not Reconnect ===
When a TCP nameserver connection goes away (e.g. if the nameserver dies), the client does not reconnect when the connection comes back (e.g. the nameserver is restarted).

''Fix:'' The private member SearchDestTCP::_addr must be an osiSockAddr, not a reference to it. The constructor cac::cac() frees the list of destinations after creating the SearchDestTCP instances. The SearchDestTCP couldn't reconnect, because it had lost the target address.

RRM 3-13 Compression

2010-04-08T15:08:12Z

RalphLange: /* Read Parameters and Algorithm Parameters */ Fix: ALG and N are SPC_RESET, not SPC_NOMOD.

[[RRM 3-13|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are five possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-13 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of all the elements of the array obtained from INP; that is, the entire array referenced by INP is retrieved, and the average of the elements is placed in the next element of the circular buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the circular buffer. Thus, VAL[0] holds the average of the first sampling of INP, VAL[1] holds the average of the next sampling of INP, and so on. The following shows the equation:

[[Image:RRM 3-13 Compression-1.gif]]

If <CODE>N to 1 Low Value</CODE>, <CODE>N to 1 High Value</CODE>, or <CODE>N to 1 Average</CODE> are chosen, then VAL is a circular buffer of NSAM samples. The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (LOW, HIGH, or AVE), is written to the circular buffer referenced by VAL. If LOW, the lowest value is written; if HIGH, the highest value of all the samples is written; and if AVE, the average of all the samples are written.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average

The compression record keeps (NSAM) data samples.

The N field determines the number of fields to compress into 1.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-13 Compression-2.gif]]

OFF number of samples are ignored at the beginning of the array being compressed. IHIL and ILIL are used as initial value filters when compressing arrays; that is, the compression does not begin until a value is found that is either greater than IHIL or less than ILIL

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Compression

2010-04-08T15:08:06Z

RalphLange: /* Read Parameters and Algorithm Parameters */ Fix: ALG and N are SPC_RESET, not SPC_NOMOD.

[[RRM 3-14|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are five possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of all the elements of the array obtained from INP; that is, the entire array referenced by INP is retrieved, and the average of the elements is placed in the next element of the circular buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the circular buffer. Thus, VAL[0] holds the average of the first sampling of INP, VAL[1] holds the average of the next sampling of INP, and so on. The following shows the equation:

[[Image:RRM 3-14 Compression-1.gif]]

If <CODE>N to 1 Low Value</CODE>, <CODE>N to 1 High Value</CODE>, or <CODE>N to 1 Average</CODE> are chosen, then VAL is a circular buffer of NSAM samples. The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (LOW, HIGH, or AVE), is written to the circular buffer referenced by VAL. If LOW, the lowest value is written; if HIGH, the highest value of all the samples is written; and if AVE, the average of all the samples are written.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average

The compression record keeps (NSAM) data samples.

The N field determines the number of fields to compress into 1.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-14 Compression-2.gif]]

OFF number of samples are ignored at the beginning of the array being compressed. IHIL and ILIL are used as initial value filters when compressing arrays; that is, the compression does not begin until a value is found that is either greater than IHIL or less than ILIL

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Compression

2010-04-08T15:05:20Z

RalphLange: /* special */ Fix: ALG and N are SPC_RESET, not SPC_NOMOD.

[[RRM 3-14|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are five possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of all the elements of the array obtained from INP; that is, the entire array referenced by INP is retrieved, and the average of the elements is placed in the next element of the circular buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the circular buffer. Thus, VAL[0] holds the average of the first sampling of INP, VAL[1] holds the average of the next sampling of INP, and so on. The following shows the equation:

[[Image:RRM 3-14 Compression-1.gif]]

If <CODE>N to 1 Low Value</CODE>, <CODE>N to 1 High Value</CODE>, or <CODE>N to 1 Average</CODE> are chosen, then VAL is a circular buffer of NSAM samples. The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (LOW, HIGH, or AVE), is written to the circular buffer referenced by VAL. If LOW, the lowest value is written; if HIGH, the highest value of all the samples is written; and if AVE, the average of all the samples are written.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average

The compression record keeps (NSAM) data samples.

The N field determines the number of fields to compress into 1.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-14 Compression-2.gif]]

OFF number of samples are ignored at the beginning of the array being compressed. IHIL and ILIL are used as initial value filters when compressing arrays; that is, the compression does not begin until a value is found that is either greater than IHIL or less than ILIL

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-13 Compression

2010-04-08T15:05:17Z

RalphLange: /* special */ Fix: ALG and N are SPC_RESET, not SPC_NOMOD.

[[RRM 3-13|EPICS Record Reference Manual]]

= compress - Compression =

The data compression record is used to collect and compress data from arrays. When the INP field references a data array field, it immediately compresses the entire array into an element of an array using one of several algorithms, overwriting the previous element. If the INP field obtains its value from a scalar-value field, the compression record will collect a new sample each time the record is processed and add it to the compressed data array as a circular buffer.

The INP link can also specify a constant; however, if this is the case, the compression algorithms are ignored, and the record support routines merely return after checking the FLNK field.

== Parameter Fields ==

The data compression fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scanning Parameters ===

The compression record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-13 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-13 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the compression record supports no direct interfaces to hardware, its SCAN field cannot specify <CODE>I/O Intr</CODE>.

=== Read Parameters and Algorithm Parameters ===

These fields determine what channel to read and how to compress the data. The user specifies the algorithm to be used in the ALG field. There are five possible algorithms which can be specified as follows:

* <CODE>Circular Buffer</CODE>
* <CODE>Average</CODE>
* <CODE>N to 1 Low Value</CODE>
* <CODE>N to 1 High Value</CODE>
* <CODE>N to 1 Average</CODE>

These algorithms are explained in one of the sections below.

The RES field can be accessed at run time to cause the algorithm to reset itself.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>RES<TD>Reset<TD>SHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ALG<TD>Algorithm<TD>[[RRM 3-13 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NSAM<TD>Number in Sample<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>N<TD>Number<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ILIL<TD>Initial Low Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IHIL<TD>Initial High Interest Value<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

The input specification should be a database or channel access link. Though INP can be a constant, the data compression algorithms are supported only when INP is a database link. See [[RRM 3-13 Concepts#Address Specification|Address Specification]] for information on specifying links.

==== Algorithms and Related Fields ====

As stated above, the ALG field specifies which algorithm to be performed on the data. The rest of the fields--NSAM, N, ILIL, IHIL, and OFF--are used in the compressions, though N is not used in the <CODE>Circular Buffer</CODE> algorithm and ILIL, IHIL, and OFF are used neither in the <CODE>Circular Buffer</CODE> algorithm nor in the <CODE>Average</CODE> algorithm.

The <CODE>Circular Buffer</CODE> algorithm keeps a circular buffer of length NSAM. Each time the record is processed, it gets the data referenced by INP and puts it into the circular buffer referenced by VAL. Note that when INP refers to a scalar, VAL is just a time ordered circular buffer of values obtained from INP.

<CODE>Average</CODE> takes an average of all the elements of the array obtained from INP; that is, the entire array referenced by INP is retrieved, and the average of the elements is placed in the next element of the circular buffer. The retrieved array is truncated to be of length NSAM. N successive arrays are averaged and placed in the circular buffer. Thus, VAL[0] holds the average of the first sampling of INP, VAL[1] holds the average of the next sampling of INP, and so on. The following shows the equation:

[[Image:RRM 3-13 Compression-1.gif]]

If <CODE>N to 1 Low Value</CODE>, <CODE>N to 1 High Value</CODE>, or <CODE>N to 1 Average</CODE> are chosen, then VAL is a circular buffer of NSAM samples. The actual algorithm depends on whether INP references a scalar or an array. If INP refers to a scalar, then N successive time ordered samples of INP are taken. After the Nth sample is obtained a new value, determined by the algorithm (LOW, HIGH, or AVE), is written to the circular buffer referenced by VAL. If LOW, the lowest value is written; if HIGH, the highest value of all the samples is written; and if AVE, the average of all the samples are written.

If INP refers to an array, then the following applies:

; <CODE>N to 1 Low Value</CODE>
: Compress N to 1 samples, keeping the lowest value
; <CODE>N to 1 High Value</CODE>
: Compress N to 1 samples, keeping the highest value
; <CODE>N to 1 Average</CODE>
: Compress N to 1 samples, taking the average

The compression record keeps (NSAM) data samples.

The N field determines the number of fields to compress into 1.

Thus, if NSAM was 3, and N was also equal to 3, then the algorithms would work as in the following diagram:

[[Image:RRM 3-13 Compression-2.gif]]

OFF number of samples are ignored at the beginning of the array being compressed. IHIL and ILIL are used as initial value filters when compressing arrays; that is, the compression does not begin until a value is found that is either greater than IHIL or less than ILIL

RES resets the algorithm before the maximum number of samples are reached.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the record either textually or graphically.

The HOPR and LOPR fields only specify the range for VAL, HIHI, HIGH, LOLO and LOW fields.

PREC controls the floating-point precision whenever <CODE>get_precision</CODE> is called, and the field being referenced is the VAL field (i.e., one of the values contained in the circular buffer).

The EGU field should be given a string that describes the value of VAL, but is used whenever the <CODE>get_units</CODE> record support routine is called.

See [[RRM 3-13 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The compression record has the alarm parameters common to all record types. [[RRM 3-13 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the data compression algorithm. They are not configurable by the user, though some are accessible at run-time. They can represent the current state of the waveform or of the record whose field is referenced by the INP field.

NUSE holds the number of elements currently stored in VAL.

BPTR is a pointer that refers to the buffer referenced by VAL.

The SPTR field pointer to an array that is used for array averages.

WPTR is used by the dbGetlinks routines.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NUSE<TD>Number Used<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>SPTR<TD>Summing Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>WPTR<TD>Work Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>CVB<TD>Compress Value Buffer<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INX<TD>Current Index of Circular Buffer<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Space for all necessary arrays is allocated. The addresses are stored in the appropriate fields in the record.

==== process ====

See next section.

==== special ====

This routine is called when RSET, ALG, or N are set. It performs a reset.

==== get_value ====

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

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the circular buffer referenced by VAL.

==== put_array_info ====

Writes values into the circular buffer referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, 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.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, 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.

=== Record Processing ===

Routine process implements the following algorithm:

# If INP is not a database link, check monitors and the forward link and return.
# Get the current data referenced by INP.
# Perform the appropriate algorithm:
#* Average: Read N successive instances of INP and perform an element by element average. Until N instances have been obtained it just return without checking monitors or the forward link. When N instances have been obtained complete the algorithm, store the result in the VAL array, check monitors and the forward link, and return.
#* Circular Buffer: Write the values obtained from INP into the VAL array as a circular buffer, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to a scalar: Obtain N successive values from INP and apply the NTO1xxx algorithm to these values. Until N values are obtained monitors and forward links are not checked. When N successive values have been obtained, complete the algorithm, check monitors and the forward link, and return.
#* N to 1 xxx and INP refers to an array: The ILIL and IHIL are honored if ILIL < IHIL. The input array is divided into subarrays of length N. The specified N to 1 xxx compression algorithm is applied to each sub-array and the result stored in the array referenced by VAL. The monitors and forward link are checked.
# If success, set UDF to FALSE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

CA over TCP

2010-04-08T14:58:51Z

RalphLange: /* CA Client */ Adapted to first implementation

RRM 3-14 Calcout

2010-04-02T21:47:01Z

RalphLange: /* Expression */ Added pointer for calc expression to AppDevGuide.

[[RRM 3-14|EPICS Record Reference Manual]]

= Calcout - Calculation Output Record =

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.

== Parameter Fields ==

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

=== Scan Parameters ===

The Calcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] 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 <CODE>I/O Intr</CODE>.

=== 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 <CODE>dbPuts</CODE>. 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 [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== 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 [[#Output Parameters|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.

-----
'''NOTE:''' A complete description of the calculation expression can be found in the '''Application Developer's Guide''', chapter libCom / calc / Infix Expression Syntax (19.2.1 for EPICS 3.14.11).
-----

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE> 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.

==== Operands ====

The expression can use the values retrieved from the INP''x'' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

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

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 <CODE>Use OCAL</CODE> 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 system dependent.

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 <CODE>get_units</CODE> 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:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

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 [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# 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 <CODE>execOutput()</CODE> routine below.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, set PACT FALSE, and return.

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# 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).
# If an output delay was implemented, process the forward link.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calculation

2010-04-02T21:45:26Z

RalphLange: /* Expression */ Added pointer for calc expression to AppDevGuide

[[RRM 3-14|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls 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 question mark or '?:' 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.

-----
'''NOTE:''' A complete description of the calculation expression can be found in the '''Application Developer's Guide''', chapter libCom / calc / Infix Expression Syntax (19.2.1 for EPICS 3.14.11).
-----

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calculation

2010-03-31T13:46:48Z

RalphLange: /* Bitwise Operators */

[[RRM 3-14|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls 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 question mark or '?:' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calculation

2010-03-31T13:46:39Z

RalphLange: /* Relational Operators */

[[RRM 3-14|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls 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 question mark or '?:' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calculation

2010-03-31T13:46:29Z

RalphLange: /* Trigonometric Operators */

[[RRM 3-14|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls 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 question mark or '?:' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calculation

2010-03-31T13:46:20Z

RalphLange: /* Algebraic Operators */

[[RRM 3-14|EPICS Record Reference Manual]]

= Calc - Calculation =

The calculation or "Calc" record is used to perform algebraic, relational, and logical operations on values retrieved from other records. The result of its operations can then be accessed by another record so that it can be used.

== Parameter Fields ==

The fields in this record fall into these categories:

* scan parameters
* read parameters
* expression parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The Calc record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Since the Calc record supports no direct interfaces to hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot be <CODE>I/O Intr</CODE>.

=== Read Parameters ===

The read parameters for the Calc 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 or a channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via <CODE>dbPuts</CODE>. They cannot be hardware addresses.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== Expression ===

At the core of the Calc record lie the CALC and RPCL fields. The CALC field contains the infix expression which the record routine will use when it processes the record. The resulting value is placed in the VAL field and can be accessed from there. The CALC expression is actually converted to opcode and stored as 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 calls 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 question mark or '?:' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>DBF_STRING<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>RPCL<TD>Reverse Polish<TD>DBF_NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE>

==== Operands ====

The expression uses the values retrieved from the INP''x'' 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. 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Expression Examples ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

(A+B)<(C+D)?E

* Result is E if (A+B) < (C+D)
* Result is unchanged if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display VAL and the other parameters of the calculation record either textually or graphically.

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 <CODE>get_units</CODE> 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.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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, everytime the value changes, monitors are triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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 to reverse polish notation. The result is stored in RPCL.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calcout

2010-03-31T13:41:36Z

RalphLange: /* Relational Operators */

[[RRM 3-14|EPICS Record Reference Manual]]

= Calcout - Calculation Output Record =

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.

== Parameter Fields ==

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

=== Scan Parameters ===

The Calcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] 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 <CODE>I/O Intr</CODE>.

=== 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 <CODE>dbPuts</CODE>. 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 [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== 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 [[#Output Parameters|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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE> 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.

==== Operands ====

The expression can use the values retrieved from the INP''x'' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

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

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 <CODE>Use OCAL</CODE> 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 system dependent.

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 <CODE>get_units</CODE> 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:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

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 [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# 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 <CODE>execOutput()</CODE> routine below.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, set PACT FALSE, and return.

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# 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).
# If an output delay was implemented, process the forward link.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calcout

2010-03-31T13:41:17Z

RalphLange: /* Bitwise Operators */

[[RRM 3-14|EPICS Record Reference Manual]]

= Calcout - Calculation Output Record =

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.

== Parameter Fields ==

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

=== Scan Parameters ===

The Calcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] 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 <CODE>I/O Intr</CODE>.

=== 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 <CODE>dbPuts</CODE>. 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 [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== 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 [[#Output Parameters|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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE> 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.

==== Operands ====

The expression can use the values retrieved from the INP''x'' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

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

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 <CODE>Use OCAL</CODE> 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 system dependent.

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 <CODE>get_units</CODE> 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:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

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 [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# 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 <CODE>execOutput()</CODE> routine below.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, set PACT FALSE, and return.

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# 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).
# If an output delay was implemented, process the forward link.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Calcout

2010-03-31T13:40:28Z

RalphLange: /* Logical Operators */

[[RRM 3-14|EPICS Record Reference Manual]]

= Calcout - Calculation Output Record =

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.

== Parameter Fields ==

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

=== Scan Parameters ===

The Calcout record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] 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 <CODE>I/O Intr</CODE>.

=== 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 <CODE>dbPuts</CODE>. 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 [[#Operator Display Parameters|Operator Display Parameters]] for an explanation of these fields.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>INPA<TD>Input Link A<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPB<TD>Input Link B<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPC<TD>Input Link C<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPD<TD>Input Link D<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPE<TD>Input Link E<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPF<TD>Input Link F<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPG<TD>Input Link G<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPH<TD>Input Link H<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPI<TD>Input Link I<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPJ<TD>Input Link J<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPK<TD>Input Link K<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TR>
<TD>INPL<TD>Input Link L<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A
</TABLE>

=== 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 [[#Output Parameters|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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>CALC<TD>Calculation<TD>STRING[36]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>RPCL<TD>Reverse Polish<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>N/A<TD>No
</TABLE> 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.

==== Operands ====

The expression can use the values retrieved from the INP''x'' 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.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>A<TD>Input Value A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input Value B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input Value C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input Value D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input Value E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input Value F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input Value G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input Value H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input Value I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input Value J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input Value K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input Value L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

The keyword <tt>VAL</tt> returns the current contents of the VAL field (which can be written to by a CA put, so it might ''not'' be the result from last time the expression was evaluated).

==== Algebraic Operators ====

* ABS: Absolute value (unary)
* SQR: Square root (unary)
* MIN: Minimum (any number of args)
* MAX: Maximum (any number of args)
* FINITE: returns non-zero if none of the arguments are NaN or Inf (any number of args)
* ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number of args)
* CEIL: Ceiling (unary)
* FLOOR: Floor (unary)
* LOG: Log base 10 (unary)
* LOGE: Natural log (unary)
* EXP: Exponential function (unary)
* ^: Exponential (binary)
* ** : Exponential (binary)
* + : Addition (binary)
* - : Subtraction (binary)
* * : Multiplication (binary)
* / : Division (binary)
* % : Modulo (binary)
* NOT: Negate (unary)

==== Trigonometric Operators ====

* SIN: Sine
* SINH: Hyperbolic sine
* ASIN: Arc sine
* COS: Cosine
* COSH: Hyperbolic cosine
* ACOS: Arc cosine
* TAN: Tangent
* TANH: Hyperbolic tangent
* ATAN: Arc tangent

==== Relational Operators ====

* >= : Greater than or equal to
* > : Greater than
* <= : Less than or equal to
* <: Less than
* # : Not equal to
* = : Equal to

==== Logical Operators ====

* && : And
* || : Or
* ! : Not

==== Bitwise Operators ====

* | : Bitwise Or
* & : Bitwise And
* OR : Bitwise Or
* AND: Bitwise And
* XOR: Bitwise Exclusive Or
* ~ : One's Complement
* << : Left shift
* >> : Right shift

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

==== Conditional Expression ====

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

condition ? True result : False result

=== Example Expressions ===

==== Algebraic ====

A + B + 10

* Result is A + B + 10

==== Relational ====

(A + B) < (C + D)

* Result is 1 if (A+B) < (C+D)
* Result is 0 if (A+B) >= (C+D)

==== Question Mark ====

(A+B)<(C+D)?E:F+L+10

* Result is E if (A+B) < (C+D)
* Result is F+L+10 if (A+B) >= (C+D)

==== Logical ====

A&B

* Causes the following to occur:
** Convert A to integer
** Convert B to integer
** Bit-wise And A and B
** Convert result to floating point

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

* <CODE>Every Time</CODE> -- write output every time record is processed.
* <CODE>On Change</CODE> -- write output every time VAL changes, i.e., every time the result of the expression changes.
* <CODE>When Zero</CODE> -- when record is processed, write output if VAL is zero.
* <CODE>When Non-zero</CODE> -- when record is processed, write output if VAL is non-zero.
* <CODE>Transition To Zero</CODE> -- when record is processed, write output only if VAL is zero and last value was non-zero.
* <CODE>Transition To Non-zero</CODE> -- when record is processed, write output only if VAL is non-zero and last value was zero.

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: <CODE>Use CALC</CODE> or <CODE>Use OCAL</CODE>. If <CODE>Use CALC</CODE> 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 <CODE>Use OCAL</CODE> 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 system dependent.

The IVOA field specifies what action to take with the OUT link if the Calcout record enters an INVALID alarm status. The options are <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. If the IVOA field is <CODE>Set output to IVOV</CODE>, the data entered into the IVOV field is written to the OUT link if the record alarm severity is INVALID.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Specification<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>N/A<TD>No<TR>
<TD>OOPT<TD>Output Execute Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOPT<TD>Output Data Option<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCAL<TD> Output Calculation<TD>STRING[36]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OEVT<TD>Event To Issue<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ODLY<TD>Output Execution Delay<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Output Value<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 <CODE>get_units</CODE> 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:

* <CODE>Ext PV NC</CODE> -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
* <CODE>Ext PV OK</CODE> -- the PV wasn't found on this IOC and a Channel Access link has been established.
* <CODE>Local PV</CODE> -- the PV was found on this IOC.
* <CODE>Constant</CODE> -- the corresponding link field is a constant.

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 [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INAV<TD>Link Status of INPA<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INBV<TD>Link Status of INPB<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INCV<TD>Link Status of INPC<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INDV<TD>Link Status of INPD<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INEV<TD>Link Status of INPE<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INFV<TD>Link Status of INPF<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INGV<TD>Link Status of INPG<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INHV<TD>Link Status of INPH<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIV<TD>Link Status of INPI<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INJV<TD>Link Status of INPJ<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INKV<TD>Link Status of INPK<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INLV<TD>Link Status of INPL<TD>RECCHOICE<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OUTV<TD>OUT PV Status<TD>RECCHOICE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>CLCV<TD>CALC Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OCLV<TD>OCAL Valid<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Output Delay Active<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Severity for a Hihi Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>Severity for a High Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Severity for a Low Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Severity for a Lolo Alarm<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== 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 [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

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

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarmed Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Previous Input Value for A<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Previous Input Value for B<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Previous Input Value for C<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Previous Input Value for D<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Previous Input Value for E<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Previous Input Value for F<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Previous Input Value for G<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Previous Input Value for H<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Previous Input Value for I<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Previous Input Value for J<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Previous Input Value for K<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Previous Input Value for L<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

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.

==== process ====

See next section.

==== special ====

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

==== get_value ====

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

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

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.

==== get_control_double ====

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.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

==== process() ====

The <CODE>process()</CODE> routine implements the following algorithm:

# Fetch all arguments.
# 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.
# 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.
# 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 <CODE>execOutput()</CODE> routine below.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# If no output delay was specified, scan forward link if necessary, set PACT FALSE, and return.

==== execOutput() ====

# If DOPT field specifies the use of OCAL, call the routine calcPerform for the postfix version of the expression in OCAL. Otherwise, use VAL.
# If the Alarm Severity is INVALID, follow the option as designated by the field IVOA.
# 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).
# If an output delay was implemented, process the forward link.

----

EPICS Record Reference Manual - 19 MAY 1998