Table of Contents Previous Chapter Chapter 36: subArray

Chapter 36: subArray

1. Introduction

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.

2. Field Summary

Field  Type        DCT  Initial  Access  Modify  Rec Proc   PP   
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                                            

3. Field Descriptions

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

4. Record Support Routines


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.


See next section.


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


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


Retrieves NELM.


Sets NORD.


Retrieves EGU.


Retrieves PREC.

5. 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 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.
  6. Scan forward link if necessary, set PACT FALSE, and return.

6. 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 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.                      
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(FILE fp, paddr)
Not currently used.


Not currently used.


This routine is called by the record support init_record routine.


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.

7. Device Support For Soft Records

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