Add POD annotations from Wiki to subArrayRecord and menuAlarmStat
This commit is contained in:
Saeed Haghtalab
committed by
Andrew Johnson
Andrew Johnson
parent
96e3e678e9
commit
f70c17ee69
@@ -7,6 +7,17 @@
|
||||
# and higher are distributed subject to a Software License Agreement found
|
||||
# in file LICENSE that is included with this distribution.
|
||||
#*************************************************************************
|
||||
|
||||
=head1 Menu menuAlarmStat
|
||||
|
||||
This menu defines the possible alarm statuses that EPICS records can exhibit
|
||||
which is used for C<STAT> and C<NSTA> fields of all record types.
|
||||
See L<Alarm Status> for more information.
|
||||
|
||||
=menu menuAlarmStat
|
||||
|
||||
=cut
|
||||
|
||||
menu(menuAlarmStat) {
|
||||
choice(menuAlarmStatNO_ALARM,"NO_ALARM")
|
||||
choice(menuAlarmStatREAD,"READ")
|
||||
|
||||
@@ -6,7 +6,372 @@
|
||||
# EPICS BASE is distributed subject to a Software License Agreement found
|
||||
# in file LICENSE that is included with this distribution.
|
||||
#*************************************************************************
|
||||
|
||||
=head1 Sub-Array Record (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.
|
||||
|
||||
=head2 Contents
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Parameter Fields>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Scan Parameters>
|
||||
|
||||
=item * L<Read Parameters>
|
||||
|
||||
=item * L<Array Parameters>
|
||||
|
||||
=item * L<Operator Display Parameters>
|
||||
|
||||
=item * L<Alarm Parameters>
|
||||
|
||||
=item * L<Run-time Parameters>
|
||||
|
||||
=back
|
||||
|
||||
=item * L<Record Support>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Record Support Routines (subArrayRecord.c)>
|
||||
|
||||
=item * L<Record Processing>
|
||||
|
||||
=item * L<Example Synchronous Subroutine>
|
||||
|
||||
=item * L<Example Asynchronous Subroutine>
|
||||
|
||||
=back
|
||||
|
||||
=item * L<Device Support>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Fields Of Interest To Device Support>
|
||||
|
||||
=item * L<Device Support Routines (devSASoft.c)>
|
||||
|
||||
=item * L<Device Support For Soft Records>
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=begin html
|
||||
|
||||
<br>
|
||||
<hr>
|
||||
<br>
|
||||
|
||||
=end html
|
||||
|
||||
=recordtype subArray
|
||||
|
||||
=cut
|
||||
|
||||
recordtype(subArray) {
|
||||
|
||||
=head2 Parameter Fields
|
||||
|
||||
=head3 Scan Parameters
|
||||
|
||||
The subArray record has the standard fields for specifying under what
|
||||
circumstances the record will be processed. These fields are listed in
|
||||
L<Scan Fields>.
|
||||
In addition,
|
||||
L<Scanning Specification>
|
||||
explains how these fields are used.
|
||||
|
||||
=head3 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
|
||||
L<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 C<<< Soft Channel >>>.
|
||||
|
||||
=fields INP, DTYP
|
||||
|
||||
=head3 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.
|
||||
|
||||
=fields FTVL, VAL, MALM, NELM, INDX
|
||||
|
||||
=head3 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 C<<< get_units
|
||||
>>> record support routine.
|
||||
|
||||
The HOPR and LOPR fields set the upper and lower display limits for the
|
||||
sub-array elements. Both the C<<< get_graphic_double >>> and C<<<
|
||||
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 C<<< get_precision >>> record support routine is
|
||||
called.
|
||||
|
||||
See L<Fields Common to All Record Types>
|
||||
for more on the record name (NAME) and description (DESC) fields.
|
||||
|
||||
=fields EGU, HOPR, LOPR, PREC, NAME, DESC
|
||||
|
||||
=head3 Alarm Parameters
|
||||
|
||||
The subarray record has the alarm parameters common to all record types.
|
||||
L<Alarm Fields> lists other fields related to a alarms that are common to all
|
||||
record types.
|
||||
|
||||
=head3 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.
|
||||
|
||||
=fields NORD, BPTR
|
||||
|
||||
=begin html
|
||||
|
||||
<br>
|
||||
<hr>
|
||||
<br>
|
||||
|
||||
=end html
|
||||
|
||||
=head2 Record Support
|
||||
|
||||
=head3 Record Support Routines (subArrayRecord.c)
|
||||
|
||||
=head4 init_record
|
||||
|
||||
long (*init_record)(struct dbCommon *precord, int pass)
|
||||
|
||||
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
|
||||
C<init_record()>, it is called.
|
||||
|
||||
=head4 process
|
||||
|
||||
long (*process)(struct dbCommon *precord)
|
||||
|
||||
See L<Record Processing>.
|
||||
|
||||
=head4 cvt_dbaddr
|
||||
|
||||
long (*cvt_dbaddr)(struct dbAddr *paddr)
|
||||
|
||||
This is called by dbNameToAddr. It makes the dbAddr structure refer to the
|
||||
actual buffer holding the result.
|
||||
|
||||
=head4 get_array_info
|
||||
|
||||
long (*get_array_info)(struct dbAddr *paddr, long *no_elements, long *offset)
|
||||
|
||||
Retrieves NELM.
|
||||
|
||||
=head4 put_array_info
|
||||
|
||||
long (*put_array_info)(struct dbAddr *paddr, long nNew)
|
||||
|
||||
Sets NORD.
|
||||
|
||||
=head4 get_graphic_double
|
||||
|
||||
long (*get_graphic_double)(struct dbAddr *paddr, struct dbr_grDouble *p)
|
||||
|
||||
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 C<<< recGblGetGraphicDouble() >>>.
|
||||
|
||||
=head4 get_control_double
|
||||
|
||||
long (*get_control_double)(struct dbAddr *paddr, struct dbr_ctrlDouble *p)
|
||||
|
||||
For array elements, this routine retrieves HOPR and LOPR. Otherwise, C<<<
|
||||
recGblGetControlDouble() >>> is called.
|
||||
|
||||
=head4 get_units
|
||||
|
||||
long (*get_units)(struct dbAddr *paddr, char *units)
|
||||
|
||||
Retrieves EGU.
|
||||
|
||||
=head4 get_precision
|
||||
|
||||
long (*get_precision)(const struct dbAddr *paddr, long *precision)
|
||||
|
||||
Retrieves PREC.
|
||||
|
||||
=head3 Record Processing
|
||||
|
||||
Routine process implements the following algorithm:
|
||||
|
||||
=over
|
||||
|
||||
=item 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.
|
||||
|
||||
=item 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.
|
||||
|
||||
=item 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.
|
||||
|
||||
=item 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.
|
||||
|
||||
=item 5.
|
||||
|
||||
Check to see if monitors should be invoked.
|
||||
|
||||
=over
|
||||
|
||||
=item *
|
||||
|
||||
Alarm monitors are invoked if the alarm status or severity has changed.
|
||||
|
||||
=item *
|
||||
|
||||
Archive and value change monitors are always invoked.
|
||||
|
||||
=item *
|
||||
|
||||
NSEV and NSTA are reset to 0.
|
||||
|
||||
=back
|
||||
|
||||
=item 6.
|
||||
|
||||
Scan forward link if necessary, set PACT FALSE, and return.
|
||||
|
||||
=back
|
||||
|
||||
=begin html
|
||||
|
||||
<br>
|
||||
<hr>
|
||||
<br>
|
||||
|
||||
=end html
|
||||
|
||||
=head2 Device Support
|
||||
|
||||
=head3 Fields Of Interest To Device Support
|
||||
|
||||
The device support routines are primarily interested in the following fields:
|
||||
|
||||
=fields PACT, DPVT, UDF, NSEV, NSTA, INP, FTVL, MALM, NELM, INDX, BPTR, NORD
|
||||
|
||||
=head3 Device Support Routines (devSASoft.c)
|
||||
|
||||
Device support consists of the following routines:
|
||||
|
||||
=head4 long report(int level)
|
||||
|
||||
This optional routine is called by the IOC command C<dbior> and is passed the
|
||||
report level that was requested by the user.
|
||||
It should print a report on the state of the device support to stdout.
|
||||
The C<level> parameter may be used to output increasingly more detailed
|
||||
information at higher levels, or to select different types of information with
|
||||
different levels.
|
||||
Level zero should print no more than a small summary.
|
||||
|
||||
=head4 long init(int after)
|
||||
|
||||
This optional routine is called twice at IOC initialization time.
|
||||
The first call happens before any of the C<init_record()> calls are made, with
|
||||
the integer parameter C<after> set to 0.
|
||||
The second call happens after all of the C<init_record()> calls have been made,
|
||||
with C<after> set to 1.
|
||||
|
||||
=head4 init_record
|
||||
|
||||
long init_record(subArrayRecord *prec)
|
||||
|
||||
This routine is called by the record support C<init_record()> routine.
|
||||
|
||||
=head4 read_sa
|
||||
|
||||
long read_sa(subArrayRecord *prec)
|
||||
|
||||
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.
|
||||
|
||||
=head3 Device Support For Soft Records
|
||||
|
||||
Only the device support module C<<< Soft Channel >>> is currently provided. The
|
||||
INP link type must be either DB_LINK or CA_LINK.
|
||||
|
||||
=head4 Soft Channel
|
||||
|
||||
INP is expected to point to a waveform record.
|
||||
|
||||
=cut
|
||||
|
||||
include "dbCommon.dbd"
|
||||
field(VAL,DBF_NOACCESS) {
|
||||
prompt("Value")
|
||||
|
||||
Reference in New Issue
Block a user