RRM 3-14 SubArray

EPICS Record Reference Manual

subArray

The normal use for the subArray record type is to obtain sub-arrays from waveform records. Setting either the number of elements (NELM) or index (INDX) fields causes the record to be processed anew so that applications in which the length and position of a sub-array in a waveform record vary dynamically can be implemented using standard EPICS operator interface tools.

The first element of the sub-array, that at location INDX in the referenced waveform record, can be displayed as a scalar, or the entire subarray (of length NELM) can be displayed in the same way as a waveform record. If there are fewer than NELM elements in the referenced waveform after the INDX, only the number of elements actually available are returned, and the number of elements read field (NORD) is set to reflect this. This record type does not support writing new values into waveform records.

Parameter Fields

The subArray's fields fall into the following categories:

• scan parameters
• read parameters
• array parameters
• operator display parameters
• run-time parameters

Scan Parameters

The subArray 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.

Read Parameters

The subArray's input link (INP) should be configured to reference the Waveform record. It should specify the VAL field of a Waveform record. The INP field can be a channel access link, in addition to a database link. See Address Specification for information on specifying links.

In addition, the DTYP field must specify a device support module. Currently, the only device support module is Soft Channel.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
INP	Input Link	INLINK	Yes	0	Yes	Yes	No	No
DTYP	Device Type	DEVCHOICE	Yes	0	Yes	No	No	No

Array Parameters

These parameters determine the number of array elements (the array length) and the data type of those elements. The Field Type of Value (FTVL) field determines the data type of the array.

The user specifies the maximum number of elements allowed in the subarray in the MALM field. Generally, the number should be equal to the number of elements of the Waveform array (found in the Waveform's NELM field). The MALM field is used to allocate memory. The subArray's Number of Elements (NELM) field is where the user specifies the actual number of elements that the subArray will contain. It should of course be no greater than MALM; if it is, the record processing routine sets it equal to MALM.

The INDX field determines the offset of the subArray record's array in relation to the Waveform's. For instance, if INDX is 2, then the subArray will read NELM elements starting with the third element of the Waveform's array. Thus, it equals the index number of the Waveform's array.

The actual sub-array is referenced by the VAL field.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
FTVL	Field Type of Value	GBLCHOICE	Yes	0	Yes	No	No	No
VAL	Value Field	(See FTVL)	No	0	Yes	Yes	Yes	No
MALM	Maximum Number of Elements In Sub-array	ULONG	Yes	1	Yes	No	No	No
NELM	Number of Elements In Sub-array	ULONG	Yes	1	Yes	Yes	No	Yes
INDX	Index Into Referenced Array	ULONG	Yes	0	Yes	Yes	No	Yes

Operator Display Parameters

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

EGU is a string of up to 16 characters describing the engineering units (if any) of the values which the subArray holds. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the sub-array elements. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

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

See 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	null	Yes	Yes	No	No
HOPR	High Operating Range	FLOAT	Yes	0	Yes	Yes	No	No
LOPR	Low Operating Range	FLOAT	Yes	0	Yes	Yes	No	No
PREC	Display Precision	SHORT	Yes	0	Yes	Yes	No	No
NAME	Record Name	STRING [29]	Yes	0	Yes	No	No	No
DESC	Description	STRING [29]	Yes	Null	Yes	Yes	No	No

Alarm Parameters

The subarray record has the alarm parameters common to all record types. Alarm Fields lists other fields related to a alarms that are common to all record types.

Run-time Parameters

These fields are not configurable by the user. They are used for the record's internal processing or to represent the current state of the record.

The NORD field holds a counter of the number of elements read into the array. It can be less than NELM even after the array is full if NELM exceeds the number of existing elements in the referenced array, i.e., the Waveform's array.

BPTR contains a pointer to the record's array.

Field	Summary	Type	DCT	Initial	Access	Modify	Rec Proc Monitor	PP
NORD	Number of Elements Read	LONG	No	0	Yes	No	No	No
BPTR	Buffer Pointer	NOACCESS	No	null	Yes	No	No	No

Record Support

Record Support Routines

init_record

Using MALM and FTVL, space for the array is allocated. The array address is stored in BPTR. This routine checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated. If device support includes init_record, it is called.

process

See next section.

get_value

Fills in the values of struct valueDes so that they refer to the sub-array.

cvt_dbaddr

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

get_array_info

Retrieves NELM.

put_array_info

Sets NORD.

get_graphic_double

For the elements in the array, this routine routines HOPR and LOPR. For the INDX field, this routine returns MALM - 1 and 0. For NELM, it returns MALM and 1. For other fields, it calls recGblGetGraphicDouble().

get_control_double

For array elements, this routine retrieves HOPR and LOPR. Otherwise, recGblGetControlDouble() is called.

get_units

Retrieves EGU.

get_prec

Retrieves PREC.

Record Processing

Routine process implements the following algorithm:

1. Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
2. Sanity check NELM and INDX. If NELM is greater than MALM it is set to MALM. If INDX is greater than or equal to MALM it is set to MALM-1.
3. Call device support read routine. This routine is expected to place the desired sub-array at the beginning of the buffer and set NORD to the number of elements of the sub-array that were read.
4. If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE. Otherwise, process sets PACT TRUE at this time. This asynchronous processing logic is not currently used but has been left in place.
5. 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 always invoked.
   • NSEV and NSTA are reset to 0.
6. Scan forward link if necessary, set PACT FALSE, and return.

Device Support

Fields Of Interest To Device Support

The device support routines are primarily interested in the following fields:

Name	Summary	Description
PACT	Processing Active	See Fields Common to All Record Types for an explanation of these fields.
DPVT	Device Private
UDF	VAL Undefined
NSEV	New Alarm Severity
NSTA	New Alarm Status
INP	Input Link	This field is used by the device support routines to locate its input.
FTVL	Field Type of Value	This is DBF_STRING, ... ,DBF_ENUM. The device support routine should check that this is correctly defined.
MALM	Maximum Number Of Elements in Sub-array	Number of elements that will fit in the array the record allocates. Device support must never return more elements than this.
NELM	Number Sub-array Elements	Number of elements in desired sub-array.
INDX	Index Into Referenced Array	Index of beginning of desired sub-array in source array.
BPTR	Buffer Pointer	Address of array device support must copy the source array into.
NORD	Number Of Elements Read	Device support must set this value when it completes.

Device Support Routines

Device support consists of the following routines:

report

report(FILE fp, paddr)

not currently used.

init

init()

Not currently used.

init_record

init_record(precord)

This routine is called by the record support init_record routine.

read_sa

read_sa(precord)

Enough of the source waveform is read into BPTR, from the beginning of the source, to include the requested sub-array. The sub-array is then copied to the beginning of the buffer. NORD is set to indicate how many elements of the sub-array were acquired.

Device Support For Soft Records

Only the device support module Soft Channel is currently provided. The INP link type must be either DB_LINK or CA_LINK.

Soft Channel

INP is expected to point to a waveform record.

---

EPICS Record Reference Manual - 19 MAY 1998