diff --git a/modules/database/src/std/rec/eventRecord.dbd.pod b/modules/database/src/std/rec/eventRecord.dbd.pod index 964c3973c..131eb7b89 100644 --- a/modules/database/src/std/rec/eventRecord.dbd.pod +++ b/modules/database/src/std/rec/eventRecord.dbd.pod @@ -9,9 +9,12 @@ =title Event Record (event) -The normal use for this record type is to post an event and/or process a -forward link. Device support for this record can provide a hardware interrupt -handler routine for I/O Event-scanned records. +The normal use for this record type is to post a soft-event and/or process a +forward link. +C device support is provided to allow the soft-event name to be +read from an input link. +Hardware device support for this record can provide an interrupt handler routine +to trigger processing of the record when an I/O Intr event occurs. =head2 Parameter Fields @@ -37,18 +40,31 @@ recordtype(event) { =head3 Scan Parameters The event record has the standard fields for specifying under what circumstances -it will be processed. +it should be processed. These fields are described in L. =fields SCAN, PHAS, EVNT, PRIO, PINI -=head3 Event Number Parameters +=head3 Event Name Parameters -The VAL field contains the event number read by the device support routines. It -is this number which is posted. For records that use C device -support, it can be configured before run-time or set via dbPuts. +The VAL field is a string (prior to the Base-3.15.1 release it was a short +integer) providing the name of an IOC soft-event. +This named soft-event gets posted whenever the record is processed. -=fields VAL +When the soft-event name is known at design time, the VAL field should be set to +the name in a loaded database file. +Soft-event names do not have to be registered before use, a handle for the name +is automatically created and stored when a name is first seen and the same +handle returned later if the same name is re-used. + +The EPVT field holds the handle for the soft-event named in the VAL field. +Looking up the handle for a soft-event name is fast and uses a hash table. + +For records that use the default C device support, the soft-event +name can be fetched through the INP field link, written to the VAL field and the +handle looked up during record processing. + +=fields VAL, EPVT =cut @@ -69,16 +85,18 @@ support, it can be configured before run-time or set via dbPuts. =head3 Input Specification -The device support routines use the address in this record to obtain input. For -records that provide an interrupt handler, the INP field should specify the +The device support routines use the address in this record to obtain input. +For records that provide an interrupt handler, the INP field should specify the address of the I/O card, and the DTYP field should specify a valid device -support module. Be aware that the address format differs according to the card -type used. See L
for information on the format of hardware addresses and specifying links. For soft records, the INP field can be a constant, a database link, or a channel -access link. For soft records, the DTYP field should specify C. +access link, and the DTYP field should be empty or set to C. =fields INP, DTYP @@ -93,24 +111,27 @@ access link. For soft records, the DTYP field should specify C. =head3 Operator Display Parameters See L for more on the record name (NAME) and description (DESC) fields. - +Parameters> +for more on the record name (NAME) and description (DESC) fields. =fields NAME, DESC =head3 Alarm Parameters -The Event record has the alarm parameters common to all record types. L lists other fields related to alarms that are common to all record -types. +The Event record has the alarm parameters common to all record types. +L lists other fields related to alarms +that are common to all record types. + +=fields STAT, SEVR, AMSG, NSTA, NSEV, NAMSG, ACKS, ACKT, UDF =head3 Simulation Mode Parameters The following fields are used to operate the event record in the simulation -mode. See L for more information on these -fields. +mode. +See L +for more information on these fields. -=fields SIOL, SVAL, SIML, SIMM, SIMS +=fields SIOL, SVAL, SIML, SIMM, SIMS, SSCN, SDLY =cut @@ -179,38 +200,50 @@ initialized if SIOL is CONSTANT or PV_LINK. If device support includes C, it is called. +The string in VAL is converted to a soft-event handle in EPVT. + =head4 process See next section. +=head4 special + +When the VAL field is set, the new string is converted to a soft-event handle in +EPVT. + =head3 Record Processing -Routine process implements the following algorithm: +Routine C implements the following algorithm: =over =item 1. -readValue is called. See L for more information. +C is called. +See L for more information. =item 2. -If PACT has been changed to TRUE, the device support read routine has started -but has not completed reading a new input value. In this case, the processing -routine merely returns, leaving PACT TRUE. +If PACT has changed to TRUE, the device support read routine has started +but has not completed reading a new soft-event name. +In this case, the processing routine returns immediately, leaving PACT TRUE. =item 3. -If VAL E 0, post event number VAL. +Set PACT to TRUE. =item 4. -Check to see if monitors should be invoked. Alarm monitors are invoked if the -alarm status or severity has chanet to 0. +Post the soft-event whose handle is in EPVT. =item 5. -Scan forward link if necessary, set PACT FALSE, and return. +Check to see if monitors should be invoked. +Alarm monitors are invoked if the new alarm status or severity are non-zero. + +=item 6. + +Scan forward link if set, set PACT to FALSE, and return. =back @@ -221,13 +254,15 @@ Scan forward link if necessary, set PACT FALSE, and return. Each record must have an associated set of device support routines. The device support routines are primarily interested in the following fields: -=fields PACT, DPVT, UDF, NSEV, NSTA, INP, PRIO +=fields PACT, DPVT, UDF, NSEV, NSTA, INP, PRIO, VAL, EPVT =head3 Device Support Routines Device support consists of the following routines: -=head4 long report(int level) +=head4 report + + 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. @@ -235,9 +270,11 @@ 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. +Level zero should print only a 1-line summary. -=head4 long init(int after) +=head4 init + + 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 @@ -247,23 +284,25 @@ with C set to 1. =head4 init_record - init_record(precord) + long 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) + long 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. C 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. +This routine is called by the dbScan system each time the record is added +or deleted from an I/O event scan list. +C has the value (0, 1) if the record is being (added to, deleted from) an +I/O event list. +The C routine is optional, but must be provided by any device +support that implements C scanning for the event record type. =head4 read_event - read_event(precord) + long read_event(precord) This routine returns the following values: @@ -281,15 +320,13 @@ Other: Error. =head3 Device Support For Soft Records -The C device support module is available. The INP link type must -be either CONSTANT, DB_LINK, or CA_LINK. +A C device support module is available. +The INP link field is used to fetch the soft-event name. -If the INP link type is CONSTANT, then the constant value is stored into VAL by -C, and UDF is set to FALSE. If the INP link type is PV_LINK, then -dbCaAddInlink is called by C. +The C routine reads a string through INP and stores it in VAL, +then looks up the named soft-event handle and sets EPVT. -C calls recGblGetLinkValue to read the current value of VAL. See -L for details on soft input. +See L for details on soft input. =cut