Add POD annotations to seqRecord from Wiki

2019-09-06 11:26:39 +02:00
parent 83458421aa
commit b93f92c843
1 changed files with 282 additions and 0 deletions
@@ -6,12 +6,294 @@
 # EPICS BASE is distributed subject to a Software License Agreement found
 # in file LICENSE that is included with this distribution. 
 #*************************************************************************
+
+=title Sequence Record (seq)
+
+The Sequence record is used to trigger the processing of up to ten other records
+and send values to those records. It is similar to the fanout record, except
+that it will fetch an input value and write an output value instead of simply
+processing a collection of forward links. It can also specify one of several
+selection algorithms that determine which values to write. It has no associated
+device support.
+
+=recordtype seq
+
+=cut
+
 menu(seqSELM) {
    choice(seqSELM_All,"All")
    choice(seqSELM_Specified,"Specified")
    choice(seqSELM_Mask,"Mask")
 }
+
 recordtype(seq) {
+
+=pod
+
+=head1 Contents
+
+=over
+
+=item * L<Parameter Fields>
+
+=over
+
+=item * L<Scan Parameters>
+
+=item * L<Desired Output Parameters>
+
+=item * L<Output Parameters>
+
+=item * L<Selection Algorithm Parameters>
+
+=item * L<Delay Parameters>
+
+=item * L<Operator Display Parameters>
+
+=item * L<Alarm Parameters>
+
+=back
+
+=item * L<Record Support>
+
+=back
+
+=begin html
+
+<br><hr><br>
+
+=end html
+
+=head2 Parameter Fields
+
+The fields fall into the following categories:
+
+=over
+
+=item * L<Scan Parameters>
+
+=item * L<Desired Output Parameters>
+
+=item * L<Output Parameters>
+
+=item * L<Selection Algorithm Parameters>
+
+=item * L<Delay Parameters>
+
+=item * L<Operator Display Parameters>
+
+=item * L<Alarm Parameters>
+
+=back
+
+=head3 Scan Parameters
+
+The sequence 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.
+
+=head3 Desired Output Parameters
+
+These fields determine where the record retrieves the values it is to write to
+other records. All of these values are not necessarily used, depending on the
+selection algorithm.
+
+The sequence record can retrieve up to 16 values from 16 locations. The user
+specifies the locations in the Desired Output Link fields (DOL0-DOLF), which can
+be either constants, database links, or channel access links. If a Desired
+Output Link is a constant, the corresponding value field for that link is
+initialized to the constant value and ''cannot'' be changed via dbputs.
+Otherwise, if the Desired Output Link is a database or channel access link, a
+value is fetched from the link each time the record is processed (provided that
+the output link is part of the record's selection algorithm). See L<Address
+Specification> for information on how to specify database links.
+
+The value fetched from the Desired Output Links are stored in the corresponding
+Desired Output Value fields (DO0-DOF). These fields can be initialized to a
+constant value, but they cannot be changed via dbPuts.
+
+=head4 Desired Output Link Fields
+
+=fields DOL0, DOL1, DOL2, DOL3, DOL4, DOL5, DOL6, DOL7, DOL8, DOL9, DOLA, DOLB, DOLC, DOLD, DOLE, DOLF
+
+=head4 Desired Output Value Fields
+
+=fields DO0, DO1, DO2, DO3, DO4, DO5, DO6, DO7, DO8, DO9, DOA, DOB, DOC, DOD, DOE, DOF
+
+=head3 Output Parameters
+
+When the record is processed, the desired output values are retrieved for the
+links in the record's selection algorithm and are written to the corresponding
+output link (LNK0-LNKF). These output links can be database links or channel
+access links; they cannot be device addresses. There are sixteen output links, one
+for each desired output link. Only those that are defined are used.
+
+=fields LNK0, LNK1, LNK2, LNK3, LNK4, LNK5, LNK6, LNK7, LNK8, LNK9, LNKA, LNKB, LNKC, LNKD, LNKE, LNKF
+
+=head3 Selection Algorithm Parameters
+
+When the sequence record is processed, it uses a selection algorithm similar to
+that of the selection record to decide which links to process.The select
+mechanism field (SELM) has three algorithms to choose from: C<<< All >>>,
+C<<<Specified >>> or C<<< Mask >>>.
+
+=head4 Record fields related to the Selection Algorithm
+
+=fields SELM, SELN, SELL, SHFT, OFFS
+
+=head4 Fields Description
+
+B<SELM - Selection Mode>
+
+=menu seqSELM
+
+See L<Selection Algorithms Description> below;
+
+B<SELL - Link Selection Location>
+
+This field can be initialized as a CONSTANT or as a LINK to any other record. SELN will fetch its value from this field when the seq record is processed.
+Thus, when using I<Mask> or I<Specified> modes, the links that seq will process can be dinamically changed by the record pointed by SELL.
+
+B<SELN - Link Selection>
+
+When B<C<SELM = Specified>> this is the index number of the link that will be processed, used in combination with the C<OFFS> field:
+
+  SELN = SELN + OFFS
+
+
+I<(By default, the OFFS is initalized to ZERO)>
+
+When B<C<SELM = Mask>> this field is the bitmask that will be used to determine which links will be processed by the seq record,
+in combination with the C<SHFT> field:
+
+  if (SHFT >= 0)
+    SELN = SELN << -SHFT
+  else
+    SELN = SELN >> SHFT
+
+I<(By default, the SHFT is initalized to -1)>
+
+=head4 B<Note about SHFT and OFFS fields>
+
+The first versions of seq record had DO, DOL, LNK and DLY fields starting with index ONE (DO1, DOL1, LNK1 and DLY1).
+New version of the seq record now supports 16 links, starting by index ZERO (DO0, DOL0, LNK0 and DLY0). The SHFT and OFFS fields
+were introduced to keep compatibility of old databases that used seq record with its links indexed from one onwards.
+
+B<If one wants to use DO0, DOL0, LNK0, DLY0 fields when SELM = Mask, SHFT field must be set to ZERO>
+
+=head4 Selection Algorithms Description
+
+B<All>
+
+The C<<< All >>> algorithm causes the record to process each input and output
+link each time the record is processed, in order from 0 to 15. So when SELM is
+C<<< All >>>, the desired output value from DOL0 will fetched and sent to LNK0,
+then the desired output value from DOL1 will be fetched and sent to the location
+in LNK1, and so on until the last input and output link DOF and LNKF. (Note that
+undefined links are not used.) If DOLI<x> is a constant, the current value
+field is simply used and the desired output link is ignored. The SELN field is
+not used when C<<< All >>> is the algorithm.
+
+B<Specified>
+
+When the C<<< Specified >>> algorithm is chosen, each time the record is
+processed it gets the integer value in the Link Selection (SELN) field and uses
+that as the index of the link to process. For instance, if SELN is 4, the
+desired output value from DO4 will be retrieved and sent to LNK4. If DOLI<x> is
+a constant, DOI<x> is simply used without the value being fetched from the
+input link.
+
+B<Mask>
+
+When C<<< Mask >>> is chosen, the record uses the individual bits of the SELN
+field to determine the links to process. When bit 0 of SELN is set, the value
+from DO0 will be written to the location in LNK0; when bit 1 is set, the valud
+from DO1 will be written to the location in LNK1 etc. Thus for example if SELN
+is 3, the record will retrieve the values from DO0 and DO1 and write them to the
+locations in LNK0 and LNK1, respectively. If SELN is 63, DO0...DO5 will be
+written to LNK0...LNK5.
+
+
+=head3 Delay Parameters
+
+The delay parameters consist of 16 fields, one for each I/O link discussed
+above. These fields can be configured to cause the record to delay processing
+the link. For instance, if the user gives the DLY1 field a value of 3.0, each
+time the record is processed at run-time, the record will delay processing the
+DOL1, DOV1, and LNK1 fields for three seconds. That is, the desired output value
+will not be fetched and written to the output link until three seconds have
+lapsed.
+
+=fields DLY0, DLY1, DLY2, DLY3, DLY4, DLY5, DLY6, DLY7, DLY8, DLY9, DLYA, DLYB, DLYC, DLYD, DLYE, DLYF
+
+=head3 Operator Display Parameters
+
+These parameters are used to present meaningful data to the operator. The
+Precision field (PREC) determines the decimal precision for the VAL field when
+it is displayed. It is used when the C<<< get_precision >>> record routine is
+called.
+
+See L<Fields Common to All Record Types> for more on the record name (NAME) and
+description (DESC) fields.
+
+=fields PREC, NAME, DESC
+
+=head3 Alarm Parameters
+
+The sequence 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.
+
+=head2 Record Support
+
+=head3 Record Processing
+
+Routine process implements the following algorithm:
+
+=over
+
+=item 1.
+
+First, PACT is set to TRUE, and the link selection is fetched. Depending on the
+selection mechanism, the link selection output links are processed in order from
+LNK0 to LNKF. When LNKI<x> is processed, the corresponding DLYI<x> value is
+used to generate a delay via watchdog timer.
+
+=item 2.
+
+After DLYI<x> seconds have expired, the input value is fetched from DOI<x> (if
+DOLI<x> is constant) or DOLI<x> (if DOLI<x> is a database link or channel
+access link) and written to LNKI<x>.
+
+=item 3.
+
+When all links are completed, an asynchronous completion call back to dbProcess
+is made (see the Application Developer's Guide for more information on
+asynchronous processing.)
+
+=item 4.
+
+Then UDF is set to FALSE.
+
+=item 5.
+
+Monitors are checked.
+
+=item 6.
+
+The forward link is scanned, PACT is set FALSE, and the process routine returns.
+
+=back
+
+For the delay mechanism to operate properly, the record is processed
+asynchronously. The only time the record will not be processed asynchronously is
+when there are no non-NULL output links selected (i.e. when it has nothing to
+do.) The processing of the links is done via callback tasks at the priority set
+in the PRIO field in dbCommon (see the Application Developer's Guide for more
+information on call
+
+=cut
+
    include "dbCommon.dbd" 
    field(VAL,DBF_LONG) {
        prompt("Used to trigger")