RRM 3-13 Archive
The Archive Record
The Archive record was developed to provide a way to store the values of a PV for use by an EPICS archiving client. A client that archives the states of one or more PVs typically uses Channel Access to establish monitors on a channel, or the client retrieves a PV's values directly using get requests, the client usually running on a different host than the host which is running the database. In the case that the network fails or the client or client's host crashes, then the Archive record provides a way to store values for the PV being archived within the IOC. In addition, the Archive record stores the time stamp for the value as well as the status and severity of the PV. The Archive record can then "flush" the stored values and time stamps out to the client the next time the record processes.
Each time the Archive record processes, it reads a value from the address specified by its input link (the INP field) and decides whether or not to store it in an array. Whether the Archive record stores the value depends on the configuration of the STIM, AVAR, RVAR, and PCAB fields. If the record decides to archive the value, the value will be written into the CVAL field, and then stored in an array of data structures, each structure having members for the value, time stamp, and status and severity. The value of the sample is also stored in another array. The seconds and nanoseconds parts of the time stamp for the value are also stored in separate arrays. Writing directly to the CVAL field will cause the record to process. The size of the arrays used by the Archive record is determined by the value of the NVAL field, which should be configured beforehand.
Each time the record is processed, it will determine if monitors should be posted for the Archive records arrays. That is, it will decide if the array of values and the time arrays should be flushed to the client. The Archive record flushes the arrays when the record is full, half-full, and when the number of seconds since the last flush exceeds the number of seconds specified in the FTIM field. FTIM should be configured before run-time.
Parameter Fields
The record's fields fall into the following categories:
- scan parameters
- read parameters
- archive and monitor parameters
- operator display parameters
- run-time and simulation mode parameters
Scan Parameters
The Archive 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 INP field determines where the Archive record gets its input. It can be a database or channel access link, or a constant. Each time the record is processed, it reads the value from the specified address and writes it into the RVAL field. If constant, the RVAL field is initialized with the constant and can be changed via dbPuts. The Archive record does not support device input.
See Address Specification for information on specifying links.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| RVAL | Raw Value | DOUBLE | No | 0 | Yes | Yes | No | No |
| INP | Input Link | INLINK | Yes | Null | Yes | No | N/A | No |
Archive and Monitor Parameters
These configurable parameters are the core of the archive record and basically determine how it operates at run-time. The STIM, AVAR, RVAR, and PCAB fields determine whether or not the record will archive the value read into the RVAL field. If the time since the last value archived is greater than the number of seconds specified in the STIM field, the value read into RVAL will be archived. Otherwise, the record will then use the PCAB, and RVAR or AVAR fields to determine whether or not to save the value. The PCAB field is a menu-type field that has seven choices:
- absolute
- relative
- abs && rel
- abs || rel
- on change
- allways
- never
If the PCAB field specifies absolute, when the record reads in a value to RVAL it will archive the value only if the difference between RVAL and the last value archived is greater than the value specified in the AVAR field. The difference between the RVAL and the last archived value is calculated as an absolute value. If the PCAB field specifies relative, the record will archive the value in RVAL only if the difference between RVAL and the last archived value is greater than n% of the last value archived, where n is the value specified in the RVAR field. The difference between RVAL and the last archived value is calculated as an absolute value. Thus, if PCAB specifies relative and the RVAR specifies 10%, and if the last archived value was 100.0, then if the current value is less than 90 or greater than 110, then that means the value has changed by more than 10% and the value will be archived.
If the PCAB field specifies abs && rel, then the record will archive the value in RVAL only if both the above absolute and relative conditions are true. If the PCAB field specifies abs || rel, then the value will be archived if either condition holds true. If on change is specified, then the record will archive the value if it has changed from the last value archived; if allways, the record will archive the value in RVAL every time the record processes; and if never, the record will never archive the value.
If a value is to be archived, it is written into the CVAL field.
When the archive record archives a value, it archives the value, a time stamp for the value, as well as the status and severity of the PV's value. This information is collectively called a sample. The record keeps track of each sample with a data structure. An array of these data structures is allocated when the record is initialized. The size of this array is configured by the developer/user in the NVAL field. It's the responsibility of the configurer to make sure NVAL specifies an array of the appropriate size. In addition to an array to hold the samples, three more arrays are allocated of size NVAL: the first holds the value part of each sample; the second holds the time of each sample, where the time is the number of seconds past the epoch of the sample; the third holds the nanoseconds part of the sample's time stamp. Although these arrays are not directly accessible at run-time through read or write operations, the record posts the latter three arrays using monitors.
The record posts the above three arrays--an array with the sample's values, an array with the seconds part of the sample's time stamp, and an array with the nanoseconds part of the time stamp--when the difference between the current time and the last time the values were posted exceeds the number of seconds specified in the FTIM field. In addition, the arrays are posted when the arrays are full and half-full. Of course, these conditions are only checked when the record processes
The MASK field changes the above algorithm somewhat. It was intended to enable a special digital reading of any input. It's an unsigned integer field which, if non-zero, changes the algorithm of the record in the following way. Firstly, if the MASK field is set to true, the following conversion is performed on RVAL: its value is typecast to an unsigned integer, RVAL being read as floating-point number. Then this integer is ANDed (&) with the value in MASK. In deciding to archive this integer, if the interval specified in STIM has been exceeded, the value is archived, just as when MASK is zero. However, if STIM hasn't been exceed, if MASK is true, the PCAB field is ignored, and the record simply checks to see if the converted value is not equal to the last value archived. If it isn't, the value is archived.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| STIM | Save Time in Secnds | ULONG | Yes | 900 | Yes | No | No | No |
| PCAB | Percent or Absolute | RECCHOICE | Yes | 0 | Yes | Yes | No | No |
| AVAR | Absolute Difference | FLOAT | Yes | 0 | Yes | Yes | No | No |
| RVAR | Percent Difference | FLOAT | Yes | 0 | Yes | Yes | No | No |
| CVAL | Current Value | DOUBLE | No | 0 | Yes | Yes | No | Yes |
| NVAL | Number of Values | ULONG | Yes | 100 | Yes | No | No | No |
| FTIM | Flush Time in Sec | ULONG | Yes | 900 | Yes | No | No | No |
| MASK | Bit Mask | USHORT | Yes | 0 | Yes | No | No | No |
Operator Display Parameters
These fields are used to give meaning to the record's data for the operator's sake. The HOPR and LOPR fields indicate the upper and lower limits for the CVAL and LVAL fields. In addition, the HOPR and LOPR fields determine the control limits for these fields. The PREC field determines the displayed precision for the CVAL, AVAR, and LVAL fields. The EGU field indicates the engineering units for the VAL, CVAL, AVAR, and LVAL fields.
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 |
|---|---|---|---|---|---|---|---|---|
| NAME | Record Name | STRING [29] | Yes | Null | Yes | No | No | No |
| DESC | Description | STRING [29] | 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 | Precision | SHORT | Yes | 0 | Yes | Yes | No | No |
| EGU | Engineering Units | STRING[16] | Yes | Null | Yes | Yes | No | No |
Run-time Parameters
These parameters are all used for the record's internal processing or to access the record's data, except for the RES field which can be written to at run-time to reset the record. The ARCH, VALS, TIMS, and NSCS are all array fields of size NVAL. Their arrays contain the archived data. The ARCH field points to an array of data structures, each of which contains the value of the PV, the time stamp when the value was taken, and the status and severity of the PV when the value was taken. The VALS field points to an array containing only the value part of each sample; the TIMS field points to an array containing only the seconds part of the time stamp of each sample, while the NSCS field points to an array containing only the nanoseconds part of each sample. Each array is of the size specified in the NVAL field. None of these array fields are directly accessible at run-time. However, the VALS and TIMS arrays are accessible through the VAL and TIM fields.
The FLSH field is an internal flag that indicates whether or not the VALS, TIMS, and NSCS fields are to be flushed when monitors are posted.
When the user changes the RES field to a non-zero value at run-time, the NUSE and CCNT fields are set equal to zero. In addition, the TIMS and NSCS pointers are set to NULL. RES is then set back to zero.
The LVAL field contains the last value archived. The LTIM field contains the time in seconds at which the last value was archived. The CCNT keeps track of the array index. When a sample is archived, it's values and time stamps are written into the CCNT index of the appropriate arrays. The NUSE field keeps track of the number of samples that have been archived, while the NUSB field keeps track of the number of samples that have been written into the current buffers/arrays. For example, if data for five samples has been written into the ARCH, VALS, TIMS, and NSCS fields, then NUSB will be five. The FTOF field is used as an offset when comparing the LTIM field with the current time. It will usually have the value of one.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| ARCH | Archive Array | NOACCESS | No | NA | No | No | No | No |
| VALS | Values Array | NOACCESS | No | NA | No | No | Yes | No |
| TIMS | Times Array Seconds | NOACCESS | No | NA | No | No | Yes | No |
| NSCS | Times Array Nanoseconds | NOACCESS | No | NA | No | No | Yes | No |
| VAL | Array Value | NOACCESS | No | NA | Yes | No | No | No |
| TIM | Array Times Seconds | NOACCESS | No | NA | Yes | No | No | No |
| NSC | Array Times Nanoseconds | NOACCESS | No | NA | No | No | No | No |
| FLSH | Flush Flag | ULONG | No | 0 | Yes | No | No | No |
| RES | Reset | SHORT | No | 0 | Yes | Yes | No | No |
| LVAL | Last Value Stored | DOUBLE | No | 0 | Yes | No | No | No |
| LTIM | Last Time Monitored | ULONG | No | 0 | Yes | No | No | No |
| CCNT | Current Buffer Counter | ULONG | No | 0 | Yes | No | No | No |
| NUSE | Number Used | ULONG | No | 0 | Yes | No | No | No |
| NUSB | Number Used in Buffer | ULONG | No | 0 | Yes | No | No | No |
| FTOF | Flush Time Offset | ULONG | No | 0 | Yes | No | No | No |
EPICS Record Reference Manual - 19 MAY 1998
