RRM 3-14 Transform

From EPICSWIKI

EPICS Record Reference Manual


Transform Record

The Transform record combines features of the Calcout and Seq records, with 16 sets of the following fields:

  • input link
  • input-link status
  • value (from input link or from calc expression)
  • calc expression
  • calc-expression status
  • output link
  • output-link status
  • comment

For concreteness, here is the first set of fields:

    INPA - link from which value for A will be read
    IAV  - status of INPA
    A    - value
    CLCA - expression whose value might be written to A
    CAV  - validity of expression CLCA
    OUTA - link to which A will be written
    OAV  - status of OUTA
    CMTA - comment (description)

The value fields A-P are "process-passive", which means that writing to one of them from a CA client, or via a "CA" link, will cause the record to process, if its scan state is "Passive". If the input link associated with a value field is not blank and is not an initialization constant, then writes to that value field are not permitted.

An expression is evaluated only if the associated value field has not been modified (either by a put from some external agent, or as the result of input-link execution) since the last time the record processed.

Background

The Transform record was originally intended to perform the sequences of conditional calculations required to implement bidirectional coordinate transformations.

Example: You have defined two records containing values we'll call "L" and "R" (the left and right edges of a slit, say). Sometimes the user wants to control L and R individually, and sometimes he wants to control a combination of L and R--say (L-R) and (L+R)/2, the width and center of the slit system. You can implement a bidirectional coordinate transformation with the following expressions (where position values are assumed to increase as we go from left to right):

fieldexpressioncomment
A C-D/2 position of left edge of slit
B C+D/2 position of right edge of slit
C (A+B)/2 position of center of slit
D B-A width of slit

Now, if a user command moves the left side of the slit (A changes) and causes the record to process, A will not be recalculated because it's value is new, the right side of the slit will remain still (B is unnecessarily recalculated from old values of C and D), the position of the slit center (C) will change as expected, and the slit width (D) will change as expected. Thus, all four fields will contain consistent information about the two degrees of freedom controlled by the record, and effectively we have two actual devices and two virtual devices.

We don't care which two fields (out of A..D) correspond to actual motion-control devices, and two channel-access clients that make different assumptions about how a slit should be implemented can control this slit without modification. With an additional, similar transform record driven from the readback fields of the actual motion-control devices, we can calculate readback values for the virtual devices as well.

We could have accomplished nearly the same effect with six CALC records and some FANOUTs, but two of the drive fields (A,B,C,D) would always be inconsistent with their readbacks.


Parameter Fields

The fields in this record fall into these categories:

  • scan parameters
  • read parameters
  • expression parameters
  • output parameters
  • operator display parameters
  • alarm parameters

Scan Parameters

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


Read Parameters

The read parameters for the Transform record consist of 16 input links INPA, INPB, ... INPP. 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, associated value fields will be initialized with the constants. These fields cannot be hardware addresses. In addition, the Transform record contains the IAV, IBV, . . . IPV fields which indicate the states of the link fields, for example, whether or not the specified PV was found and a link to it established. See Operator Display Parameters for an explanation of these fields.

See Address Specification for information on how to specify database links.


FieldSummaryTypeDCTInitialAccessModifyRec Proc Monitor
INPAInput Link AINLINKYes0YesYesYes
INPBInput Link BINLINKYes0YesYesYes
........................
INPPInput Link PINLINKYes0YesYesYes


Expression Parameters

Like the Calcout record, the Transform record has fields in which the developer or user can enter an infix expression to be evaluated when the record is processed. There are, in fact, 16 such fields, each of which is a member of its own (inputlink, value, expression, outputlink) group. For each group, if inputlink is not blank and is not simply a constant initializer, then expression may be evaluated when the record processes, and the result will be placed in value.

Transform-record expressions are very similar to Calcout-record expression described elsewhere in this manual. Instead of the standard EPICS calc engine (which does not permit an expression to reference more than 12 input fields), Transform-record expressions are handled by the sCalcout (string calculation and output) record's engine. The differences, between these engines, that matter for transform-record expressions are the following:

  • The constants S2R (arc-seconds-to-radians) and R2S are supported.
  • The functions MIN() and MAX() may have more than two arguments. (EPICS 3.14-compatible version only.)
  • The binary operators '>&' (larger of the operands) and '<&' (smaller) are supported. (EPICS 3.14-compatible version only.)
  • The binary operator '!=' (not equal) is a permitted alternatives '#'.
  • The unary operator '@' selects an input field by number. (E.g., '@0' means 'A'. If 'B' has the value 3, '@b' means 'D'.)
  • The values of the variables A...P used in expressions may be the results of previously evaluated expressions.

Output Parameters

The Transform record has 16 output links, executed in order from OUTA to OUTP. Unlike the Calcout record, these links are not conditional; they execute every time the record processes.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
OUTAOutput SpecificationOUTLINKYes0YesYesN/ANo
OUTBOutput SpecificationOUTLINKYes0YesYesN/ANo
...........................
OUTPOutput SpecificationOUTLINKYes0YesYesN/ANo

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.

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. This field is not very useful, because it's unlikely to pertain to all 16 value fields.

The IAV-IPV fields indicate the states of the links INPA-INPP. These fields can have three possible values:

  • Ext PV NC -- the PV wasn't found on this IOC and a Channel Access link hasn't been established.
  • Ext PV OK -- the PV wasn't found on this IOC and a Channel Access link has been established.
  • Local PV -- the PV was found on this IOC.
  • Constant -- the corresponding link field is a constant.

The OAV-OPV fields indicate the states of the OUTA-OUTP links. They have the same possible values as the IAV-ILV fields.

The CAV-CPV fields indicate the validity of the expressions in the CLCA-CLCP fields, respectively. If an expression is invalid, its status field is set to one.

The IVLA field specifies how the record should behave if any of its input links references a record that is in alarm. There are two possibilities:

  • "Ignore Error" - Use whatever value was gotten from the link, and proceed as if there had not been any error indication.
  • "Do Nothing" - Stop after all input values have been retrieved: do not evaluate expressions, and do not execute output or forward links.

See Fields Common to All Record Types for more on the record name (NAME) and description (DESC) fields.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
EGUEngineering UnitsSTRING [16]YesNullYesYesNoNo
PRECDisplay PrecisionSHORTYes0YesYesNoNo
IAVLink Status of INPARECCHOICENo1YesNoNoNo
IBVLink Status of INPBRECCHOICENo1YesNoNoNo
...........................
IPVLink Status of INPPRECCHOICENo1YesNoNoNo
OAVLink Status of OUTARECCHOICENo0YesNoNoNo
OBVLink Status of OUTBRECCHOICENo0YesNoNoNo
...........................
OPVLink Status of OUTPRECCHOICENo0YesNoNoNo
CAVCLCA ValidLONGNo0YesYesNoNo
CBVCLCB ValidLONGNo0YesYesNoNo
...........................
CPVCLCP ValidLONGNo0YesYesNoNo
NAMERecord NameSTRING [29]Yes0YesNoNoNo
DESCDescriptionSTRING [29]YesNullYesYesNoNo


Alarm Parameters

The Transform record has no record-type-specific alarm fields. See Alarm Fields for the list of alarm fields common to all record types.

Record Support

Record Support Routines

init_record

For each constant input link, the corresponding value field is initialized with the constant.

A routine sCalcPostfix is called to convert the infix expression in CLCA-CLCV to postfix notation. The results are stored in RPCA-RPCP.

process

See next section.

special

This is called if any of the fields A-P, CLCA-CLCP, INPA-INPP, OUTA-OUTP are changed. For expressions fields, special() calls sCalcPostfix. For value fields, special() keeps track of which fields have changed, because expressions will not be evaluated for fields that have been written to. For link fields, special() starts the process of checking link status.

get_precision

Retrieves PREC.

Record Processing

process()

The process() routine implements the following algorithm:


  1. Fetch values from all valid input links.
  2. For each value field x, in order from A to P: if the value has not been written to since the last time the record processed, call sCalcPerform(), which evaluates the expression specified in CLCx and stores the result in x.
  3. Post all fields the record has changed.
  4. Execute all valid output links, in order from OUTA to OUTP.
  5. Execute the forward link, set PACT FALSE, and return.


Availability

The Transform record is not included with EPICS base. An EPICS 3.13-compatible version of this record is available as part of the std module, which is part of the synApps package of EPICS-based synchrotron-beamline software.



EPICS Record Reference Manual - 7 JUNE 2006