Transform Record and related software

Contents

• Overview
• Field Descriptions
• Expressions
• Files
• Restrictions
• Release notes

The TRANSFORM record combines features of the CALC and SEQUENCE records, with 16 sets of the following fields:

input link

INPA...INPP

input-link status

IAV...IPV

input/output value

A...P

expression

CLCA...CLCP

output link

OUTA...OUTP

output-link status

OAV...OAP

comment

CMTA...CMTP

There are guaranteed rules governing the sequence and conditions under which expressions are evaluated. Each time the record is processed, the following sequence occurs:

1. Values are fetched, in order A through P, from all valid input links. That is, if INPA is a valid input link, the value of the field pointed to by INPA will be placed into the field A, and so on.

   Note: If the record is in link alarm (.NSEV >= INVALID_ALARM) after all input-link values have been fetched, and if .IVLA == "Do Nothing", then the record will quit processing at this point. It will do some clean up, but it will not execute its forward link.

2. Valid expressions are evaluated in order CLCA through CLCP, and the resulting values are placed into the corresponding fields, A through P. Expressions are not always evaluated, however:

   If COPT=="Conditional" (0; the default value), then expression CLCx is evaluated only if x is "old", as defined below. In other words, new values are regarded as independent variables in the set of equations CLCA...CLCP, and unchanged/unwritten values are regarded as dependent variables.

   If COPT=="Always" (1), all valid expressions are evaluated unconditionally.

   The value field x is "old" if it has the same value it had after the last time the record was processed, and it was not written to (either by an outside agent or by the input link, INPx) since the last time the record was processed.

   Note that this means you cannot use both INPA and CLCA, unless you set COPT=="Always".

   Note that writes received while PACT==1 are special: they will change the field they write to, but they will not be regarded as writes for the purpose of determining whether a value is "new". This rule allows a transform record to write to itself (using database links) without messing up its notion of which values are new.

   Prior to version 5.8, there was no COPT field, and the record always behaved as though COPT=="Conditional".

3. Valid output links are triggered in order OUTA through OUTP---regardless of whether the corresponding values have changed. That is, if OUTA is a valid link, the value in field A is poked into the field pointed to by OUTA, and so on.

The transform record uses the expression-evaluation software sCalcPostfix.c and sCalcPerform.c, originally developed for the sCalcout record. An expression may contain any of the functions and constants that are valid for the sCalcout record (including string functions, though a final string result will of course be converted to double); any of the letters A-P, which stand for the values of the corresponding fields in the instant before the expression is evaluated; the expression @n, where n is an integer in [0-15], or an expression that yields such an integer, stands for a value A-P; and any of the constants PI (3.14159265), R2D (180/PI), D2R (PI/180), S2R (D2R/3600), and R2S (R2D*3600).

Background

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):

field	expression	comment
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.

Expressions

Synonyms

In addition to conventional expression, like "A+B", you can specify synonyms for the variables "A" through "P", as demonstrated below:

conventional expressions

expressions with user specified synonyms

To specify a synonym for the variable "A", you begin the comment field "CMTA" with the synonym, which must begin with '$', and which is terminated by the first nonalphanumeric character. For example, in the comment "$left:the left slit", the synonym is "$left".

Field Descriptions

Files

SOURCE CODE files to be placed in <top>/<app>App/src/
transformRecord.c	Record support code
transformRecord.dbd	Database definition file
sCalcPerform.c	string calculation support
sCalcPostfix.c	string calculation support
sCalcPostfix.h	string calculation support
sCalcPostfixPvt.h	string calculation support

DATABASES files to be placed in <top>/<app>App/Db/
userTransform.db	Sample transform-record database
userTransforms10.db	10 transforms and an enable switch
userTransforms10_settings.req	save-restore request file for userTransforms10.db

MEDM DISPLAY FILES files to be placed in <top>/<app>App/op/adl/
yyTransform.adl	Small control display for any transform record
yyTransform_full.adl	...with more detail
userTransform.adl	Small control display for transform record enabled by the switch in userTransforms10.db
userTransform_full.adl	...with more detail
userTransforms10.adl	Collection of userTransform callups, with overall enable switch
These files build medm screens to access the transform record. To use one of them from the command line, type, for example medm -x -macro "P=xxx:,T=userTran1" yyTransform_full.adl where xxx:userTran1 is the name of the transform record.

EPICS STARTUP FILES files to be placed in <top>/iocBoot/ioc<name>/
st.cmd	Startup script
This file is not included in the distribution. The following line added to st.cmd loads a single transform record. dbLoadRecords("xxxApp/Db/userTransform.db","P=xxx:,N=1")

BACKUP/RESTORE (BURT) REQUEST FILE files to be placed in <top>/<app>App/op/burt/
yyTransformSettings.req	save settings of a specified transform record. This file is normally #include'd (once for each transform record) by other request files.

AUTOSAVE/RESTORE REQUEST FILE file to be placed in your autosave search path
transform_settings.req	save settings of a specified transform record. This file is normally included once for each transform record by other request files, with a line of the following form: file transform_settings.req P=tmm:,T=userTran1 .
userTransforms10_settings.req	save settings of the userTransforms10.db database. .

Release notes

Versions earlier than 5.6 expected sCalcPostfix to allocate the postfix-expression array. sCalcPostfix no longer does this, and the transform record changed as a consequence.

Versions earlier than 5.5 ignored link errors. Beginning with version 5.5, you can choose to ignore link errors (the default) or to quit processing (after all input link values have been fetched and transferred to their respective value fields).

In versions earlier than 5.2, the test for old values did not correctly handle NaN values, which would always appear to be new, and would therefore never go away.

Versions earlier than 5.0 defined the additional fields APP...PPP, which determined whether or not a channel-access put to the value fields A...P, respectively, would cause the record to process. (The default value of these fields did not cause the record to process.) The mechanism used to accomplish this (scanOnce(), called from the transform record's special() routine) was incompatible with EPICS execution tracing software, dbPutNotify(), which must be able to discover from the .dbd file which fields of a record cause processing when written to via channel access. Because putNotify() has become an essential feature of EPICS in synchrotron-radiation applications (i.e., in synApps), the transform record was modified to remove the <x>PP fields, and the fields A..P were made process passive in transformRecord.dbd.