Navigation

cvt - The Convert Record

Introduction

The normal use for this record type is to convert one or two floating point values into a resulting floating point value which is then forwarded through the record’s OUT link. It contains features from ai, ao, and sub record types. The conversion can be specified according to four different methods (linear, subroutine, 1-dimensional and 2-dimensional tables) which themselves can be fully specified and also changed and re-initialized at runtime. This record type has no device support. The fields fall into the following categories:

Scan Parameters

The cvt record has the standard fields for specifying under what circumstances the record will be processed. See the Record Reference Manual, Scan Fields. In addition, Record Reference Manual, Scanning Specification, explains how these fields are used. Note that I/O event scanning is not supported.

Input and Output Parameters

The convert record has two input links (INPX, INPY) to specify where the values to be converted should originate. In addition, the input values can be written directly into the record’s fields X and Y. The input values are then converted, for details see Conversion Parameters. The result value is written into the VAL field. The VAL field’s value is forced to be within the limits specified in the fields DRVH and DRVL, which are configured by the designer:

DRVL ≤ VAL ≤ DRVH

It follows that if nothing is entered for DRVH and DRVL, the output value will never change.

If the address contained in the output link (see Conversion Parameters) is a channel access or database link, the value in VAL is sent to the address in the OUT field.

See Record Reference Manual, Address Specification, for information on how to specify links. Record Reference Manual, Scanning Specification, explains the effect of database linkage on scanning.

Field Summary Type DCT Initial Access Modify Rec Proc Monitor PP
X Input Value X DOUBLE No 0 Yes Yes Yes Yes
Y Input Value Y DOUBLE No 0 Yes Yes Yes Yes
VAL Output Value DOUBLE No 0 Yes No Yes Yes
INPX Input X Location INLINK Yes   Yes Yes No No
INPY Input Y Location INLINK Yes   Yes Yes No No
OUT Output Link OUTLINK Yes   Yes Yes No No
DRVH Drive High DOUBLE Yes 0 Yes Yes No Yes
DRVL Drive Low DOUBLE Yes 0 Yes Yes No Yes

Conversion Parameters

The field METH, of type menuCvtMethod, specifies the conversion method:

  • LINEAR: Linear conversion with two inputs:

    VAL = XSLO * X + YSLO * Y + VOFF

  • SUBROUTINE: Custom conversion via an arbitrary subroutine whose name is given in SPEC. It is called with three arguments: The input values X and Y, and the address of the record’s DPVT field. It should return the result value of the conversion. Symbolically:

    VAL = SPEC(X, Y, &DPVT)

    The subroutine may use the third parameter as it sees fit, which includes writing any pointer-sized value to the given address.

  • 1D TABLE: Table-driven conversion with one input value. SPEC should be the filename of a one-dimensional table as specified by the csm module. The BDIR and TDIR field specify parts of the directory of the file, the complete path of the table file is BDIR/TDIR/SPEC. X is used as input to the csm routine csm_y. The value of Y is ignored.

  • 1D TABLE INVERTED: Same as 1D TABLE, except conversion direction is backwards: Input is Y and conversion uses the csm routine csm_x. The value of X is ignored.

  • 2D TABLE: Table-driven conversion with two input values. SPEC should be the filename of a two-dimensional table as specified by the csm module. BDIR and TDIR togetehr determine the directory of the file, see case 1D TABLE above. Both X and Y are used as inputs to the csm routine csm_z.

The fields METH, SPEC, BDIR, and TDIR are read-only and always represent the conversion currently in effect.

CVSR is used to implement the non-LINEAR conversions.

Field Summary Type DCT Initial Access Modify Rec Proc Monitor PP
METH Conversion Method menuCvtMethod Yes LINEAR Yes No Yes No
SPEC Conversion Specification STRING[40] Yes   Yes No Yes No
BDIR Base Directory STRING[40] Yes   Yes No No No
TDIR Table Directory STRING[40] Yes   Yes No No No
XSLO Slope in X direction DOUBLE Yes 0 Yes Yes No Yes
YSLO Slope in Y direction DOUBLE Yes 0 Yes Yes No Yes
VOFF Value Offset DOUBLE Yes 0 Yes Yes No Yes
CVSR Conversion Subroutine void* No   No No No No

Conversion Re-Initialization

The method and other parameters of conversion can be changed at runtime without interrupting operation. If conversion method is LINEAR, new values written to XSLO, YSLO, or VOFF will take immediate effect. For other conversion types, or if the conversion type itself needs to be changed, new conversion type values should be written to NMET and new conversion specification strings to NSPE, new table directory parts to NBDI and NTDI. These new values will not take immediate effect. Instead, conversion will be re-initialized only after writing a non- zero value to the field INIT or if the value retrieved by the input link INIL is non-zero.

Field Summary Type DCT Initial Access Modify Rec Proc Monitor PP
NMET New Conversion Method menuCvtMethod No LINEAR Yes Yes Yes No
NBDI New Base Directory STRING[40] No   Yes Yes No No
NTDI New Table Directory STRING[40] No   Yes Yes No No
NSPE New Conversion Specification STRING[40] No   Yes Yes No No
ISTA Initialization State menuCvtInitState No Done Yes No Yes No
INIT Re-Initialize Conversion UCHAR No 0 Yes Yes No No
INIL Re-Init Conversion Location INLINK Yes   Yes Yes No No

During re-initialization, the old conversion method and parameters remain effective and record processing proceeds in the normal way. Field ISTA contains the status of the last (re-)initialization attempt. STAT and SEVR of the record are adjusted according to ISTA:

Value Description Status Severity
Done Initialization was successful NO_ALARM NO_ALARM
InProgress Initialization is in progress but not yet completed SOFT MINOR
Again Initialization is in progress but must be done again after completion SOFT MINOR
Error Initialization was aborted due to some error SOFT MAJOR

Operator Display Parameters

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

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, X, and Y. It is used whenever the get_precision record support routine is called.

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

Field Summary Type DCT Initial Access Modify Rec Proc Monitor PP
EGU Engineering Units STRING [16] Yes   Yes Yes No No
HOPR High Operating Range DOUBLE Yes 0 Yes Yes No No
LOPR Low Operating Range DOUBLE Yes 0 Yes Yes No No
PREC Display Precision SHORT Yes 0 Yes Yes No No
NAME Record Name STRING [29] Yes   Yes No No No
DESC Description STRING [29] Yes   Yes Yes No No

Alarm Parameters

The possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See Record Reference Manual, Alarm Specification, for a complete explanation of alarms and these fields. See Record Reference Manual, Invalid Alarm Output Action, for more information on the IVOA and IVOV fields. Record Reference Manual, Alarm Fields, lists other fields related to a alarms that are common to all record types.

Field Summary Type DCT Initial Access Modify Rec Proc Monitor PP
HIHI Hihi Alarm Limit DOUBLE Yes 0 Yes Yes No Yes
HIGH High Alarm Limit DOUBLE Yes 0 Yes Yes No Yes
LOW Low Alarm Limit DOUBLE Yes 0 Yes Yes No Yes
LOLO Lolo Alarm Limit DOUBLE Yes 0 Yes Yes No Yes
HHSV Hihi Alarm Severity menuAlarmSevr Yes 0 Yes Yes No Yes
HSV High Alarm Severity menuAlarmSevr Yes 0 Yes Yes No Yes
LSV Low Alarm Severity menuAlarmSevr Yes 0 Yes Yes No Yes
LLSV Lolo Alarm Severity menuAlarmSevr Yes 0 Yes Yes No Yes
HYST Alarm Deadband DOUBLE Yes 0 Yes Yes No No
IVOA Invalid Alarm Output Action menuIvoa Yes 0 Yes Yes No No
IVOV Invalid Alarm Output Value DOUBLE Yes 0 Yes Yes No No

Monitor Parameters

The fields ADEL and MDEL are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See Record Reference Manual, Monitor Specification, for a complete explanation of monitors.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks on VAL.

The DRTY field is used to implement monitors for the fields METH, SPEC, and ISTA.

Field Summary Type DCT Initial Access Modify Rec Proc Monitor PP
ADEL Archive Deadband DOUBLE Yes 0 Yes Yes No No
MDEL Monitor Deadband DOUBLE Yes 0 Yes Yes No No
LALM Last Alarm Monitor Trigger Value DOUBLE No 0 Yes No No No
ALST Last Archiver Monitor Trigger Value DOUBLE No 0 Yes No No No
MLST Last Value Change Monitor Trigger Value DOUBLE No 0 Yes No No No
DRTY Dirty Bits (internal) UCHAR No 0 No No No No

Inactive Mode Parameters

The convert record is either in active or inactive mode, depending on the IAOM field. If the value is non-zero, the record will be inactive, otherwise it will be active. The IAML link field can be used to input this value. An inactive record does not perform any conversion. Instead VAL is set to the value of the IAOV field. The IAVL link field can be used to input this value.

Field Summary Type DCT Initial Access Modify Rec Proc Monitor PP
IAML Inactive Mode Location INLINK Yes   Yes Yes No No
IAOM Inactive Mode menuYesNo Yes 0 Yes Yes No Yes
IAVL Inactive Value Location INLINK Yes   Yes Yes No No
IAOV Inactive Value DOUBLE Yes 0 Yes Yes No Yes

Record Support Routines

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double routines.

init_record

This routine does nothing in pass 0. In pass 1, it does following:

  • If INPX and INPY are constant links, fields X and Y are initialized to the respective values.
  • NMET is set to METH, NSPE to SPEC, NBDI to BDIR, and NTDI to TDIR.
  • Conversion is initialized according to METH and SPEC. If an error occurs, conversion method falls back to LINEAR.

process

See Record Processing.

special

This routine is invoked whenever the field INIT is changed. If INIT was changed to a non-zero value, then

  • Set INIT to zero.
  • If ISTA is Done or Error, set ISTA to InProgress and start re-initialization.
  • If ISTA is InProgress, set ISTA to Again.

get_value

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

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:

  1. Set PACT to 1.
  2. Get value of INIT from input link INIL and proceed as in special.
  3. Read inputs:
    • Get values of X and Y from INPX and INPY.
    • Get inactive mode IAOM from IAML.
    • If inactive, get inactive value IAOV from IAVL.
  4. Convert and write result to VAL.
  5. Check alarms: This routine checks to see if either the UDF field, the ISTA field, or the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y are set. For status and severity changes caused by VAL exeeding alarm limits, the alarm hysteresis factor HYST is also honored. Thus the value must change by at least HYST before the alarm status and severity is reduced.
  6. Check severity and write the new value. See Record Reference Manual, Invalid Alarm Output Action, for details on how invalid alarms affect output records.
  7. 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 RVAL and for RBV are checked whenever other monitors are invoked.
    • NSEV and NSTA are reset to 0.
  8. Scan forward link if necessary, set PACT to 0, and return.

Table Of Contents

Previous topic

EPICS csm Module

Next topic

Release Notes

Navigation

© Copyright 2010, Ben Franksen. Created using Sphinx 1.2.3.