Merge branch '3.15' into 7.0
* 3.15: (28 commits) update RELEASE_NOTES add option EPICS_NO_CALLBACK replace CALLBACK -> epicsCallback Update dbTest.c Remove links to wiki-ext Add POD annotations from Wiki to subArrayRecord and menuAlarmStat Rename subArrayRecord.dbd and menuAlarmStat.dbd to .pod Add POD annotations to longoutRecord from Wiki Rename longoutRecord.dbd longoutRecord.dbd.pod Add POD annotations to longinRecord from Wiki Rename longinRecord.dbd longinRecord.dbd.pod Add POD annotations to subRecord from Wiki Rename subRecord.dbd subRecord.dbd.pod Add POD annotations to selRecord from Wiki Rename selRecord.dbd selRecord.dbd.pod Add POD annotations to seqRecord from Wiki Rename seqRecord.dbd seqRecord.dbd.pod Fix menu declaration test too Add redefinition guard to menu-generated typedefs Updates to existing .dbd.pod texts, add event and fanout from wiki ... # Conflicts: # documentation/README.1st # documentation/README.html # modules/database/src/ioc/db/callback.h # modules/database/src/ioc/db/dbNotify.c # modules/database/src/ioc/db/menuAlarmStat.dbd # modules/database/src/ioc/db/menuFtype.dbd # modules/database/src/std/rec/compressRecord.dbd.pod # modules/database/src/std/rec/eventRecord.dbd # modules/database/src/std/rec/fanoutRecord.dbd # modules/database/src/std/rec/longinRecord.dbd # modules/database/src/std/rec/longoutRecord.dbd # modules/database/src/std/rec/selRecord.dbd # modules/database/src/std/rec/seqRecord.dbd # modules/database/src/std/rec/subArrayRecord.dbd # modules/database/src/std/rec/subRecord.dbd # modules/libcom/src/iocsh/menuAlarmStat.dbd.pod # modules/libcom/src/iocsh/menuFtype.dbd.pod # src/ioc/db/menuAlarmStat.dbd # src/ioc/db/menuFtype.dbd Manually fix some move+rename Make additional CALLBACK -> epicsCallback preserve INT64 in menuFtype preserve OLDSIM et al
This commit is contained in:
Michael Davidsaver
455
modules/database/src/std/rec/subArrayRecord.dbd.pod
Normal file
455
modules/database/src/std/rec/subArrayRecord.dbd.pod
Normal file
@@ -0,0 +1,455 @@
|
||||
#*************************************************************************
|
||||
# Copyright (c) 2002 The University of Chicago, as Operator of Argonne
|
||||
# National Laboratory.
|
||||
# Copyright (c) 2002 The Regents of the University of California, as
|
||||
# Operator of Los Alamos National Laboratory.
|
||||
# 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")
|
||||
asl(ASL0)
|
||||
special(SPC_DBADDR)
|
||||
pp(TRUE)
|
||||
extra("void * val")
|
||||
#=type Set by FTVL
|
||||
#=read Yes
|
||||
#=write Yes
|
||||
}
|
||||
field(PREC,DBF_SHORT) {
|
||||
prompt("Display Precision")
|
||||
promptgroup("80 - Display")
|
||||
interest(1)
|
||||
prop(YES)
|
||||
}
|
||||
field(FTVL,DBF_MENU) {
|
||||
prompt("Field Type of Value")
|
||||
promptgroup("30 - Action")
|
||||
special(SPC_NOMOD)
|
||||
interest(1)
|
||||
menu(menuFtype)
|
||||
}
|
||||
field(INP,DBF_INLINK) {
|
||||
prompt("Input Specification")
|
||||
promptgroup("40 - Input")
|
||||
interest(1)
|
||||
}
|
||||
field(EGU,DBF_STRING) {
|
||||
prompt("Engineering Units")
|
||||
promptgroup("80 - Display")
|
||||
interest(1)
|
||||
size(16)
|
||||
prop(YES)
|
||||
}
|
||||
field(HOPR,DBF_DOUBLE) {
|
||||
prompt("High Operating Range")
|
||||
promptgroup("80 - Display")
|
||||
interest(1)
|
||||
prop(YES)
|
||||
}
|
||||
field(LOPR,DBF_DOUBLE) {
|
||||
prompt("Low Operating Range")
|
||||
promptgroup("80 - Display")
|
||||
interest(1)
|
||||
prop(YES)
|
||||
}
|
||||
field(MALM,DBF_ULONG) {
|
||||
prompt("Maximum Elements")
|
||||
promptgroup("30 - Action")
|
||||
special(SPC_NOMOD)
|
||||
interest(1)
|
||||
initial("1")
|
||||
}
|
||||
field(NELM,DBF_ULONG) {
|
||||
prompt("Number of Elements")
|
||||
promptgroup("30 - Action")
|
||||
pp(TRUE)
|
||||
initial("1")
|
||||
}
|
||||
field(INDX,DBF_ULONG) {
|
||||
prompt("Substring Index")
|
||||
promptgroup("30 - Action")
|
||||
pp(TRUE)
|
||||
}
|
||||
field(BUSY,DBF_SHORT) {
|
||||
prompt("Busy Indicator")
|
||||
special(SPC_NOMOD)
|
||||
}
|
||||
field(NORD,DBF_LONG) {
|
||||
prompt("Number elements read")
|
||||
special(SPC_NOMOD)
|
||||
}
|
||||
field(BPTR,DBF_NOACCESS) {
|
||||
prompt("Buffer Pointer")
|
||||
special(SPC_NOMOD)
|
||||
interest(4)
|
||||
extra("void * bptr")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user