Table of Contents 
Previous Chapter Chapter 36: subArray
The normal use for the subArray record type is to obtain sub-arrays from waveform records. Setting either the NELM or INDX fields causes the record to be processed with the new value, so that applications in which the length and position of a subarray of a waveform record are dynamically varied 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 that number of elements actually available are returned, and NORD is set to reflect this. This record type does not support writing new values into waveform records.
---------------------------------------------------------------
Field Type DCT Initial Access Modify Rec Proc PP
Monitor
---------------------------------------------------------------
VAL (See FTVL) No 0 Yes Yes Yes No
PREC SHORT Yes 0 Yes Yes No No
FTVL GBLCHOICE Yes 0 Yes No No
INP INLINK Yes 0 No N/A
EGU STRING Yes Null Yes Yes No No
HOPR FLOAT Yes 0 Yes Yes No No
LOPR FLOAT Yes 0 Yes Yes No No
MALM ULONG Yes 1 Yes No No
NELM ULONG Yes 1 Yes Yes No Yes
INDX ULONG Yes 0 Yes Yes No Yes
NORD LONG No 0 Yes No No
BPTR NOACCESS No
---------------------------------------------------------------
-------------------------------------------------------------------------------------------
Name Summary Description
-------------------------------------------------------------------------------------------
VAL Value Field This is used to reference the sub-array.
PREC Display Precision Precision with which to display VAL. This field is not
used by record support other than to supply a value when
get_precision is called.
FTVL Field Type of Value This is DBF_STRING, ... ,DBF_ENUM.
INP Input Link This field is used by the device support routines to obtain
input. It can be a database link, or a channel access link.
EGU Engineering Units ASCII string describing Engineering units. This field is
used by record support to supply a units description string
when get_units is called.
HOPR High Operating Range These fields determine the upper and lower display limits
for graphics displays and the upper and lower control
limits for control displays. The fields are used by record
support to honor calls to get_graphic_double or
get_control_double.
LOPR Low Operating Range
MALM Maximum Number Of Generally this should be set to the NELM of the waveform
Elements In Sub-array record being pointed to.
NELM Number Of Elements
In Sub-array
INDX Index Into Referenced Index of (offset into) waveform record being referenced;
Array used as first element of sub-array.
NORD Number of Elements Number of elements that were read of the desired
Read subarray. This could be less than NELM depending on
INDX and the NELM of the referenced waveform record.
BPTR Buffer Pointer Holds address of sub-array.
-------------------------------------------------------------------------------------------
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_units
Retrieves EGU.
get_prec
Retrieves PREC.
Routine process implements the following algorithm:
- 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.
- Sanity check NELM and INDX. If NELM is greater than MALM it is set to MALM. If INDX is greater than MALM it is set to MALM-1.
- 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.
- 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.
- 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.
- Scan forward link if necessary, set PACT FALSE, and return.
Fields Of Interest To Device Support
The device support routines are primarily interested in the following fields:
---------------------------------------------------------------------------------------
Name Summary Description
---------------------------------------------------------------------------------------
PACT Processing Active See Chapter 2 Section "Database Common: Field
Descriptions" on page 4 for descriptions.
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 Number of elements that will fit in the array the record
Of Elements In allocates. Device support must never return more
Sub-array elements than this
NELM Number Sub-array Number of elements in desired sub-array.
Elements
INDX Index Into Index of beginning of desired sub-array in source array.
Referenced Array
BPTR Buffer Pointer Address of array device support must copy the source
array into.
NORD Number Of Device support must set this value when it completes.
Elements Read
---------------------------------------------------------------------------------------
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.
Only the device support module Soft Channel is provided. The INP link type must be either DB_LINK or CA_LINK.
Soft Channel
INP is expected to point to a waveform record.
Table of Contents 
Next Chapter