From 8175cc8e647f215ec93db968680b7b465239e346 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 10 Aug 2021 20:35:19 -0500 Subject: [PATCH] POD text updates to dbCommon and various record types --- modules/database/src/ioc/db/dbCommon.dbd.pod | 153 ++++++++++-------- modules/database/src/std/rec/aiRecord.dbd.pod | 14 +- modules/database/src/std/rec/biRecord.dbd.pod | 7 +- .../database/src/std/rec/calcRecord.dbd.pod | 9 +- .../src/std/rec/calcoutRecord.dbd.pod | 16 +- .../src/std/rec/dfanoutRecord.dbd.pod | 45 ++++-- .../src/std/rec/longoutRecord.dbd.pod | 16 +- .../database/src/std/rec/mbbiRecord.dbd.pod | 9 +- .../src/std/rec/mbboDirectRecord.dbd.pod | 18 ++- .../database/src/std/rec/seqRecord.dbd.pod | 46 +++--- 10 files changed, 197 insertions(+), 136 deletions(-) diff --git a/modules/database/src/ioc/db/dbCommon.dbd.pod b/modules/database/src/ioc/db/dbCommon.dbd.pod index 5ad4627c5..5033a362f 100644 --- a/modules/database/src/ioc/db/dbCommon.dbd.pod +++ b/modules/database/src/ioc/db/dbCommon.dbd.pod @@ -77,12 +77,12 @@ A set of periodic scan intervals =back Additional periodic scan rates may be defined for individual IOCs by making a -local copy of menuScan.dbd and adding more choices as required. Scan rates -should normally be defined in order, with the fastest rates appearing first. -Scan periods may now be specified in seconds, minutes, hours or Hertz/Hz, and -plural time units will also be accepted (seconds are used if no unit is -mentioned in the choice string). For example the rates given below are all -valid: +local copy of menuScan.dbd and adding more choices as required. Periodic scan +rates should normally be defined in order following the other scan types, with +the longest periods appearing first. Scan periods can be specified with a unit +string of C/C, C/C, C/C or +C/C. Seconds are used if no unit is included in the choice string. +For example these rates are all valid: 1 hour 0.5 hours @@ -97,7 +97,7 @@ initialization (before the normal scan tasks are started). The B field orders the records within a specific SCAN group. This is not meaningful for passive records. All records of a specified phase are processed -before those with higher phase number. Whenever possible it is better to use +before those with higher phase number. It is generally better practice to use linked passive records to enforce the order of processing rather than a phase number. @@ -109,23 +109,23 @@ The call to post_event is: post_event(short event_number). The B field specifies the scheduling priority for processing records with SCAN=C and asynchronous record completion tasks. -The B field specifies a "disable value". Record processing is -immediately terminated if the value of this field is equal to the value of the -DISA field, i.e. the record is disabled. Note that field values of a record -can be changed by database put or Channel Access, even if a record is +The B field specifies a "disable value". Record processing cannot +begin when the value of this field is equal to the value of the DISA +field, meaning the record is disabled. Note that field values of a record +can be changed by database or Channel Access puts, even if the record is disabled. -The B field contains the value that is compared with DISV to determine -if the record is disabled. The value of the DISA field is obtained via SDIS if -SDIS is a database or channel access link. If SDIS is not a database or -channel access link, then DISA can be set via dbPutField or dbPutLink. - -If the B field of a record is written to, the record is processed. +The B field contains the value that is compared with DISV to determine if +the record is disabled. A value is obtained for the DISA field from the B +link field before the IOC tries to process the record. If SDIS is not set, DISA +may be set by some other method to enable and disable the record. The B field defines the record's "disable severity". If this field is not NO_ALARM and the record is disabled, the record will be put into alarm with this severity and a status of DISABLE_ALARM. +If the B field of a record is written to, the record is processed. + The B field contains the lock set to which this record belongs. All records linked in any way via input, output, or forward database links belong to the same lock set. Lock sets are determined at IOC initialization time, and @@ -135,15 +135,18 @@ The B field counts the number of times dbProcess finds the record active during successive scans, i.e. PACT is TRUE. If dbProcess finds the record active MAX_LOCK times (currently set to 10) it raises a SCAN_ALARM. -The B field is TRUE while the record is being processed. For +The B field is TRUE while the record is active (being processed). For asynchronous records PACT can be TRUE from the time record processing is started until the asynchronous completion occurs. As long as PACT is TRUE, dbProcess will not call the record processing routine. See Application Developers Guide for details on usage of PACT. -The B field is a database link to another record (the "target" record). -Processing a record with a specified FLNK field will force processing of the -target record, provided the target record's SCAN field is set to C. +The B field is a link pointing to another record (the "target" record). +Processing a record with the FLNK field set will trigger processing of the +target record towards the end of processing the first record (but before PACT is +cleared), provided the target record's SCAN field is set to C. If the +FLNK field is a Channel Access link it must point to the PROC field of the +target record. The B field is for internal use by the scanning system. @@ -236,35 +239,46 @@ The B field is for internal use by the scanning system. =head3 Alarm Fields -These fields indicate the status and severity of alarms, or else determine the +Alarm fields indicate the status and severity of record alarms, or determine how and when alarms are triggered. Of course, many records have alarm-related -fields not common to all records. These fields are listed and explained in the +fields not common to all records. Those fields are listed and explained in the appropriate section on each record. The B field contains the current alarm status. The B field contains the current alarm severity. -These two fields are seen outside database access. The B and B -fields are used by the database access, record support, and device support -routines to set new alarm status and severity values. Whenever any software -component discovers an alarm condition, it uses the following macro function: -recGblSetSevr(precord,new_status,new_severity) This ensures that the current -alarm severity is set equal to the highest outstanding alarm. The file alarm.h -defines all allowed alarm status and severity values. +The B string field may contain more detailed information about the alarm. + +The STAT, SEVR and AMSG fields hold alarm information as seen outside of the +database. The B, B and B fields are used during record +processing by the database access, record support, and device support routines +to set new alarm status and severity values and message text. Whenever any +software component discovers an alarm condition, it calls one of these routines +to register the alarm: + + recGblSetSevr(precord, new_status, new_severity); + recGblSetSevrMsg(precord, new_status, new_severity, "Message", ...); + +These check the current alarm severity and update the NSTA, NSEV and NAMSG +fields if appropriate so they always relate to the highest severity alarm seen +so far during record processing. The file alarm.h defines the allowed alarm +status and severity values. Towards the end of record processing these fields +are copied into the STAT, SEVR and AMSG fields and alarm monitors triggered. The B field contains the highest unacknowledged alarm severity. -The B field specifies if it is necessary to acknowledge transient +The B field specifies whether it is necessary to acknowledge transient alarms. -The B indicates if the record's value is BnBeBined. Typically -this is caused by a failure in device support, the fact that the record has -never been processed, or that the VAL field currently contains a NaN (not a -number). UDF is initialized to TRUE at IOC initialization. Record and device -support routines which write to the VAL field are responsible for setting UDF. +The B indicates if the record's value is BnBeBined. Typically this +is caused by a failure in device support, the fact that the record has never +been processed, or that the VAL field currently contains a NaN (not a number) or +Inf (Infinite) value. UDF defaults to TRUE but can be set in a database file. +Record and device support routines which write to the VAL field are generally +responsible for setting and clearing UDF. -=fields STAT, SEVR, NSTA, NSEV, ACKS, ACKT, UDF +=fields STAT, SEVR, AMSG, NSTA, NSEV, NAMSG, ACKS, ACKT, UDF =cut @@ -422,9 +436,11 @@ The B field is is for private use of the device support modules. =head3 Debugging Fields -The B field is used for trace processing. If this field is non-zero a -message is printed whenever this record is processed, and when any other -record in the same lock-set is processed by a database link from this record. +The B field can be used to trace record processing. When this field is +non-zero and the record is processed, a trace message will be be printed for +this record and any other record in the same lock-set that is triggered by a +database link from this record. The trace message includes the name of the +thread doing the processing, and the name of the record being processed. The B field indicates if there is a breakpoint set at this record. This supports setting a debug breakpoint in the record processing. STEP through @@ -435,32 +451,26 @@ database processing can be supported using this. =head3 Miscellaneous Fields -The B field contains a character string value defining the access -security group for this record. If left empty, the record is placed in group -DEFAULT. +The B string field sets the name of the access security group used for this +record. If left empty, the record is placed in group C. -The B field is a field for private use of the access security system. +The B field is private for use by the access security system. -The B field controls dbPutFields to this record which are normally -issued by channel access. If the field is set to TRUE all dbPutFields -directed to this record are ignored except to the field DISP itself. +The B field controls whether puts from outside the IOC are allowed to +modify the fields of this record at all. If the field is set to TRUE all puts +directed to this record are ignored, except for puts to the field DISP itself. -The B field specifies the device type for the record. Each record type -has its own set of device support routines which are specified in -devSup.ASCII. If a record type does not have any associated device support, -DTYP and DSET are meaningless. +The B field specifies the device type for the record. Most record types +have their own set of device types which are specified in the IOC's database +definition file. If a record type does not call any device support routines, +the DTYP and DSET fields are not used. -The B field contains the monitor lock. The lock used by the monitor -routines when the monitor list is being used. The list is locked whenever -monitors are being scheduled, invoked, or when monitors are being added to or -removed from the list. This field is accessed only by the dbEvent routines. +The B field contains a mutex which is locked by the monitor routines in +dbEvent.c whenever the monitor list for this record is accessed. -The B field is the head of the list of monitors connected to this +The B field holds a linked list of client monitors connected to this record. Each record support module is responsible for triggering monitors for -any fields that change as a result of record processing. Monitors are present -if mlis count is greater than zero. The call to trigger monitors is: -db_post_event(precord,&data,mask), where "mask" is some combination of -DBE_ALARM, DBE_VALUE, and DBE_LOG. +any fields that change as a result of record processing. The B field contains the address of a putNotify callback. @@ -474,23 +484,24 @@ The B field contains the address of dbRecordType The B field specifies a reprocessing of the record when current processing completes. -The B