From eac3d2719b0697a6b03b275b7bea661843d8bcd5 Mon Sep 17 00:00:00 2001 From: Joao Paulo Martins Date: Fri, 6 Sep 2019 14:00:17 +0200 Subject: [PATCH] Add POD annotations to longoutRecord from Wiki --- src/std/rec/longoutRecord.dbd.pod | 434 +++++++++++++++++++++++++++++- 1 file changed, 433 insertions(+), 1 deletion(-) diff --git a/src/std/rec/longoutRecord.dbd.pod b/src/std/rec/longoutRecord.dbd.pod index c3ba0b977..5d8dd9320 100644 --- a/src/std/rec/longoutRecord.dbd.pod +++ b/src/std/rec/longoutRecord.dbd.pod @@ -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 + +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 + +=over + +=item * L + +=over + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=back + +=item * L + +=over + +=item * L + +=item * L + +=back + +=item * L + +=over + +=item * L + +=item * L + +=item * L + +=back + +=back + +=begin html + +

+ +=end html + +=recordtype longout + +=cut + recordtype(longout) { + +=head2 Parameter Fields + +The fields in this record fall into the following categories: + +=over + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=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. +In addition, L 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 DRVL. If they are not +set or DRVH E= 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
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 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 for a complete explanation of alarms and +these fields. For an explanation of the IVOA and IVOV fields, see L. L 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 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 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 + +

+ +=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, 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 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 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 + +

+ +=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 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 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 calls are made, with +the integer parameter C set to 0. +The second call happens after all of the C calls have been made, +with C set to 1. + +=head4 init_record + + init_record(precord) + +This routine is optional. If provided, it is called by the record support +C 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. + +write_longout calls recGblPutLinkValue to write the current value of VAL. + +See L for a further explanation. + +=cut + +} #end of the DBD file