Add POD annotations to longoutRecord from Wiki
This commit is contained in:
Joao Paulo Martins
committed by
Andrew Johnson
Andrew Johnson
parent
a3d0699b84
commit
eac3d2719b
@@ -6,7 +6,149 @@
|
||||
# EPICS BASE is distributed subject to a Software License Agreement found
|
||||
# in file LICENSE that is included with this distribution.
|
||||
#*************************************************************************
|
||||
|
||||
=head1 B<Long Output Record (longout)>
|
||||
|
||||
The normal use for the long output or "longout" record type is to store long
|
||||
integer values of up to 32 bits and write them to hardware devices. The C<<<
|
||||
Soft Channel >>> device support routine can also be used to write values to
|
||||
other records via database or channel access links. The OUT field determines how
|
||||
the record is used. The record supports alarm limits and graphics and control
|
||||
limits.
|
||||
|
||||
=head1 L<Contents>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Parameter Fields>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Scan Parameters>
|
||||
|
||||
=item * L<Desired Output Parameters>
|
||||
|
||||
=item * L<Write Parameters>
|
||||
|
||||
=item * L<Operator Display Parameters>
|
||||
|
||||
=item * L<Alarm Parameters>
|
||||
|
||||
=item * L<Monitor Parameters>
|
||||
|
||||
=item * L<Simulation Mode Parameters>
|
||||
|
||||
=back
|
||||
|
||||
=item * L<Record Support>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Record Support Routines>
|
||||
|
||||
=item * L<Record Processing>
|
||||
|
||||
=back
|
||||
|
||||
=item * L<Device Support>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Fields Of Interest To Device Support>
|
||||
|
||||
=item * L<Device Support Routines>
|
||||
|
||||
=item * L<Device Support For Soft Records>
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=begin html
|
||||
|
||||
<br><hr><br>
|
||||
|
||||
=end html
|
||||
|
||||
=recordtype longout
|
||||
|
||||
=cut
|
||||
|
||||
recordtype(longout) {
|
||||
|
||||
=head2 Parameter Fields
|
||||
|
||||
The fields in this record fall into the following categories:
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Scan Parameters>
|
||||
|
||||
=item * L<Desired Output Parameters>
|
||||
|
||||
=item * L<Write Parameters>
|
||||
|
||||
=item * L<Operator Display Parameters>
|
||||
|
||||
=item * L<Alarm Parameters>
|
||||
|
||||
=item * L<Monitor Parameters>
|
||||
|
||||
=item * L<Simulation Mode Parameters>
|
||||
|
||||
=back
|
||||
|
||||
=head3 Scan Parameters
|
||||
|
||||
The longout record has the standard fields for specifying under what
|
||||
circumstances it will be processed. These fields are listed in L<Scan Fields>.
|
||||
In addition, L<Scanning Specification> explains how these fields are used. Note
|
||||
that I/O event scanning is only supported for those card types that
|
||||
interrupt.
|
||||
|
||||
=head3 Desired Output Parameters
|
||||
|
||||
The record must specify where the desired output originates, i.e., the 32 bit
|
||||
integer value it is to write. The output mode select (OMSL) field determines
|
||||
whether the output originates from another record or from database access. When
|
||||
set to C<<< closed_loop >>>, the desired output is retrieved from the link
|
||||
specified in the desired output (DOL) field (which can specify either a database
|
||||
or channel access link) and placed into the VAL field. When set to C<<<
|
||||
supervisory >>>, the desired output can be written into the VAL field via dpPuts
|
||||
at run-time.
|
||||
|
||||
A third type of value for the DOL field is a constant in which case, when the
|
||||
record is initialized, the VAL field will be initialized with this constant
|
||||
value.
|
||||
|
||||
The VAL field's value will be clipped within limits specified in the fields DRVH
|
||||
and DRVL if these have been configured by the database designer:
|
||||
|
||||
DRVL <= VAL <= DRVH
|
||||
|
||||
Note: These limits are only enforced as long as DRVH E<gt> DRVL. If they are not
|
||||
set or DRVH E<lt>= DRVL they will not be used.
|
||||
|
||||
=fields DOL, OMSL, DRVH, DRVL, VAL
|
||||
|
||||
=head3 Write Parameters
|
||||
|
||||
The OUT link field determines where the record is to send its output. For
|
||||
records that write values to hardware devices, the OUT output link field must
|
||||
specify the address of the I/O card, and the DTYP field must specify the
|
||||
name of the corresponding device support module.
|
||||
|
||||
For soft records, the OUT output link can be a constant, a database link, or a
|
||||
channel access link. If the link is a constant, the result is no output. The
|
||||
DTYP field must then specify the C<<< Soft Channel >>> device support routine.
|
||||
|
||||
See L<Address Specification> for information on the format of hardware addresses
|
||||
and database links.
|
||||
|
||||
=fields OUT, DTYP
|
||||
|
||||
=cut
|
||||
|
||||
include "dbCommon.dbd"
|
||||
field(VAL,DBF_LONG) {
|
||||
prompt("Desired Output")
|
||||
@@ -30,6 +172,27 @@ recordtype(longout) {
|
||||
interest(1)
|
||||
menu(menuOmsl)
|
||||
}
|
||||
|
||||
=head3 Operator Display Parameters
|
||||
|
||||
These parameters are used to present meaningful data to the operator. They
|
||||
display the value and other parameters of the long output either textually or
|
||||
graphically.
|
||||
|
||||
EGU is a string of up to 16 characters describing the units that the long output
|
||||
measures. 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 VAL,
|
||||
HIHI, HIGH, LOW, and LOLO fields. Both the C<<< get_graphic_double >>> and C<<<
|
||||
get_control_double >>> record support routines retrieve these fields.
|
||||
|
||||
See L<Fields Common to All Record Types> for more on the record name (NAME) and
|
||||
description (DESC) fields.
|
||||
|
||||
=fields EGU, HOPR, LOPR, NAME, DESC
|
||||
|
||||
=cut
|
||||
|
||||
field(EGU,DBF_STRING) {
|
||||
prompt("Engineering Units")
|
||||
promptgroup("80 - Display")
|
||||
@@ -63,6 +226,29 @@ recordtype(longout) {
|
||||
interest(1)
|
||||
prop(YES)
|
||||
}
|
||||
|
||||
=head3 Alarm Parameters
|
||||
|
||||
The possible alarm conditions for long inputs are the SCAN, READ, INVALID, and
|
||||
limit alarms. The SCAN and READ alarms are not configurable by the user because
|
||||
their severity is always MAJOR. The INVALID alarm is called by the record
|
||||
support routine when the record or device support routines cannot write the
|
||||
record's output. The IVOA field specifies the action to take in this case.
|
||||
|
||||
The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW
|
||||
fields using floating-point values. For each of these fields, there is a
|
||||
corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. The
|
||||
HYST field contains the alarm deadband around each limit alarm.
|
||||
|
||||
See the See L<Alarm Specification> for a complete explanation of alarms and
|
||||
these fields. For an explanation of the IVOA and IVOV fields, see L<Output
|
||||
Records>. L<Alarm Fields> lists other fields related to a alarms that are common
|
||||
to all record types.
|
||||
|
||||
=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, IVOA, IVOV
|
||||
|
||||
=cut
|
||||
|
||||
field(HIHI,DBF_LONG) {
|
||||
prompt("Hihi Alarm Limit")
|
||||
promptgroup("70 - Alarm")
|
||||
@@ -124,6 +310,22 @@ recordtype(longout) {
|
||||
promptgroup("70 - Alarm")
|
||||
interest(1)
|
||||
}
|
||||
|
||||
=head3 Monitor Parameters
|
||||
|
||||
These parameters are used to determine when to send monitors placed on the value
|
||||
field. The monitors are sent when the value field exceeds the last monitored
|
||||
field by the appropriate delta. If these fields have a value of zero, everytime
|
||||
the value changes, a monitor will be triggered; if they have a value of -1,
|
||||
everytime the record is scanned, monitors are triggered. The ADEL field is the
|
||||
delta for archive monitors, and the MDEL field is the delta for all other types
|
||||
of monitors. See L<Monitor Specification> for a complete explanation of
|
||||
monitors.
|
||||
|
||||
=fields ADEL, MDEL
|
||||
|
||||
=cut
|
||||
|
||||
field(ADEL,DBF_LONG) {
|
||||
prompt("Archive Deadband")
|
||||
promptgroup("80 - Display")
|
||||
@@ -149,6 +351,25 @@ recordtype(longout) {
|
||||
special(SPC_NOMOD)
|
||||
interest(3)
|
||||
}
|
||||
|
||||
=head3 Run-time and Simulation Mode Parameters
|
||||
|
||||
The LALM, MLST, and ALST fields are used to implement the hysteresis factors for
|
||||
monitor callbacks. Only if the difference between these fields and the
|
||||
corresponding value field is greater than the appropriate delta (MDEL, ADEL,
|
||||
HYST)--only then are monitors triggered. For instance, only if the difference
|
||||
between VAL and MLST is greater than MDEL are the monitors triggered for VAL.
|
||||
|
||||
=fields LALM, ALST, MLST
|
||||
|
||||
The following fields are used to operate the long output in the simulation mode.
|
||||
See L<Fields Common to Many Record Types> for more information on the simulation
|
||||
mode fields
|
||||
|
||||
=fields SIOL, SIML, SIMM, SIMS
|
||||
|
||||
=cut
|
||||
|
||||
field(SIOL,DBF_OUTLINK) {
|
||||
prompt("Sim Output Specifctn")
|
||||
promptgroup("90 - Simulate")
|
||||
@@ -181,4 +402,215 @@ recordtype(longout) {
|
||||
promptgroup("50 - Output")
|
||||
interest(2)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
=begin html
|
||||
|
||||
<br><hr><br>
|
||||
|
||||
=end html
|
||||
|
||||
=head2 Record Support
|
||||
|
||||
=head3 Record Support Routines
|
||||
|
||||
=head4 init_record
|
||||
|
||||
This routine initializes SIMM if SIML is a constant or creates a channel access
|
||||
link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.
|
||||
|
||||
This routine next checks to see that device support is available. The routine
|
||||
next checks to see if the device support write routine is defined.
|
||||
|
||||
If either device support or the device support write routine does not exist, an
|
||||
error message is issued and processing is terminated.
|
||||
|
||||
If DOL is a constant, then VAL is initialized to its value and UDF is set to
|
||||
FALSE. If DOL type is a PV_LINK then dbCaAddInlink is called to create a channel
|
||||
access link.
|
||||
|
||||
If device support includes C<init_record()>, it is called.
|
||||
|
||||
=head4 process
|
||||
|
||||
See next section.
|
||||
|
||||
=head4 get_units
|
||||
|
||||
Retrieves EGU.
|
||||
|
||||
=head4 get_graphic_double
|
||||
|
||||
Sets the upper display and lower display limits for a field. If the field is
|
||||
VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the
|
||||
field has upper and lower limits defined they will be used, else the upper and
|
||||
lower maximum values for the field type will be used.
|
||||
|
||||
=head4 get_control_double
|
||||
|
||||
Sets the upper control and the lower control limits for a field. If the field is
|
||||
VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the
|
||||
field has upper and lower limits defined they will be used, else the upper and
|
||||
lower maximum values for the field type will be used.
|
||||
|
||||
=head4 get_alarm_double
|
||||
|
||||
Sets the following values:
|
||||
|
||||
upper_alarm_limit = HIHI
|
||||
upper_warning_limit = HIGH
|
||||
lower_warning_limit = LOW
|
||||
lower_alarm_limit = LOLO
|
||||
|
||||
|
||||
=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.
|
||||
|
||||
If PACT is FALSE and OMSL is CLOSED_LOOP recGblGetLinkValue is called to read
|
||||
the current value of VAL. See L<Output Records> for more information. If the
|
||||
return status of recGblGetLinkValue is zero then UDF is set to FALSE.
|
||||
|
||||
=item 3.
|
||||
|
||||
Check alarms. This routine checks to see if the new VAL causes the alarm status
|
||||
and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the
|
||||
alarm hysteresis factor (HYST). Thus the value must change by more than HYST
|
||||
before the alarm status and severity is lowered.
|
||||
|
||||
=item 4.
|
||||
|
||||
Check severity and write the new value. See L<Invalid Alarm Output Action> for
|
||||
information on how INVALID alarms affect output records.
|
||||
|
||||
=item 5.
|
||||
|
||||
If PACT has been changed to TRUE, the device support write output routine has
|
||||
started but has not completed writing the new value. In this case, the
|
||||
processing routine merely returns, leaving PACT TRUE.
|
||||
|
||||
=item 6.
|
||||
|
||||
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 invoked if ADEL and MDEL conditions are
|
||||
met.
|
||||
|
||||
=item *
|
||||
|
||||
NSEV and NSTA are reset to 0.
|
||||
|
||||
=back
|
||||
|
||||
=item 7.
|
||||
|
||||
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
|
||||
|
||||
Each long output record must have an associated set of device support routines.
|
||||
The primary responsibility of the device support routines is to output a new
|
||||
value whenever write_longout is called. The device support routines are
|
||||
primarily interested in the following fields:
|
||||
|
||||
=fields PACT, DPVT, NSEV, NSTA, OUT
|
||||
|
||||
=head3 Device Support Routines
|
||||
|
||||
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
|
||||
|
||||
init_record(precord)
|
||||
|
||||
This routine is optional. If provided, it is called by the record support
|
||||
C<init_record()> routine.
|
||||
|
||||
=head4 get_ioint_info
|
||||
|
||||
get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)
|
||||
|
||||
This routine is called by the ioEventScan system each time the record is added
|
||||
or deleted from an I/O event scan list. cmd has the value (0,1) if the
|
||||
record is being (added to, deleted from) an I/O event list. It must be
|
||||
provided for any device type that can use the ioEvent scanner.
|
||||
|
||||
=head4 write_longout
|
||||
|
||||
write_longout(precord)
|
||||
|
||||
This routine must output a new value. It returns the following values:
|
||||
|
||||
=over
|
||||
|
||||
=item *
|
||||
|
||||
0: Success.
|
||||
|
||||
=item *
|
||||
|
||||
Other: Error.
|
||||
|
||||
=back
|
||||
|
||||
=head3 Device Support For Soft Records
|
||||
|
||||
The C<<< Soft Channel >>> module writes the current value of VAL.
|
||||
|
||||
If the OUT link type is PV_LINK, then dbCaAddInlink is called by
|
||||
C<init_record()>.
|
||||
|
||||
write_longout calls recGblPutLinkValue to write the current value of VAL.
|
||||
|
||||
See L<Soft Output> for a further explanation.
|
||||
|
||||
=cut
|
||||
|
||||
} #end of the DBD file
|
||||
|
||||
Reference in New Issue
Block a user