From 6664ccfc6494040cac45a00489fb1ab71a23969d Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Thu, 29 Nov 2018 16:35:53 -0600 Subject: [PATCH] Wiki to POD conversions for bi, bo, calc, calcout and dfanout These still need going through to update and edit. Conversions by Tony Pietryla, Argonne. --- src/std/rec/biRecord.dbd.pod | 357 ++++++++++++++ src/std/rec/boRecord.dbd.pod | 429 +++++++++++++++++ src/std/rec/calcRecord.dbd.pod | 626 ++++++++++++++++++++++++- src/std/rec/calcoutRecord.dbd.pod | 743 +++++++++++++++++++++++++++++- src/std/rec/dfanoutRecord.dbd.pod | 250 ++++++++++ 5 files changed, 2403 insertions(+), 2 deletions(-) diff --git a/src/std/rec/biRecord.dbd.pod b/src/std/rec/biRecord.dbd.pod index fb3588fb1..a711435ba 100644 --- a/src/std/rec/biRecord.dbd.pod +++ b/src/std/rec/biRecord.dbd.pod @@ -6,7 +6,164 @@ # EPICS BASE is distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* + +=title Binary Input Record (bi) + +This record type is normally used to obtain a binary value of 0 or 1. Most +device support modules obtain values from hardware and place the value in +RVAL. For these devices, record processing sets VAL = (0,1) if RVAL is (0, +not 0). Device support modules may optionally read a value directly from +VAL. + +Soft device modules are provided to obtain input via database or channel +access links via dbPutField or dbPutLink requests. Two soft device support +modules are provided: C and C. The first +allows VAL to be an arbitrary unsigned short integer. The second reads the +value into RVAL just like normal hardware modules. + +=head2 Parameter Fields + +The binary input's fields fall into the following categories: + +=over + +=item * +scan Parameters + +=item * +read and convert parameters + +=item * +operator display parameters + +=item * +alarm parameters + +=item * +run-time parameters + +=back + +=recordtype bi + +=cut + recordtype(bi) { + +=head3 Scan Parameters + +The binary input record has the standard fields for specifying under what +circumstances the record 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. + +=fields SCAN + +=head3 Read and Convert Parameters + +The read and convert fields determine where the binary input gets its +input from and how to convert the raw signal to engineering units. The INP +field contains the address from where device support retrieves the value. +If the binary input record gets its value from hardware, the address of the +card must be entered in the INP field, and the name of the device support +module must be entered in the DTYP field. See L
for +information on the format of the hardware address. Be aware that the format +differs between types of cards. You can see a list of device support +modules currently supported at the user's local site by using C +utility (R3.13). + +For records that specify C or C device +support routines, the INP field can be a channel or a database link, or a +constant. If a constant, VAL can be changed directly by dbPuts. See +L
for information on the format of database and +channel access addresses. Also, see L in +this chapter for information on soft device support. + +If the record gets its values from hardware or uses the C +device support, the device support routines place the value in the RVAL +field which is then converted using the process described in the next +section. + +=fields INP, DTYP, ZNAM, ONAM, RVAL, VAL + +=head3 Conversion Fields + +The VAL field is set equal to (0,1) if the RVAL field is (0, not 0), unless +the device support module reads a value directly into VAL or the +C device support is used. The value can also be fetched as one of +the strings specified in the ZNAM or ONAM fields. The ZNAM field has a +string that corresponds to the 0 state, so when the value is fetched as +this string, C will return a 0. The ONAM field hold the +string that corresponds to the 1 state, so when the value is fetched as +this string, C returns a 1. + +=fields ZNAM, ONAM + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. The +C record support routine can retrieve the state string +corresponding to the VAL's state. If the value is 1, C will +return the string in the ONAM field; and if 0, C will return +the ZNAM string. + +See L for more on the record name (NAME) +and description (DESC) fields. + +=fields ZNAM, ONAM, NAME, DESC + +=head3 Alarm Parameters + +These parameters are used to determine if the binary input is in alarm +condition and to determine the severity of that condition. The possible +alarm conditions for binary inputs are the SCAN, READ state alarms, and the +change of state alarm. The SCAN and READ alarms are called by the device +supprt routines. + +The user can choose the severity of each state in the ZSV and OSV fields. +The possible values for these fields are C, C, and +C. The ZSV field holds the severity for the zero state; OSV, for +the one state. COSV causes an alarm whenever the state changes between +0 and 1 and the severity is configured as MINOR or MAJOR. + +See L for a complete explanation of the discrete alarm +states. L lists other fields related to alarms that are +common to all record types. + +=fields ZSV, OSV, COSV + +=head3 Run-time Parameters and Simulation Mode Parameters + +These parameters are used by the run-time code for processing the binary +input. They are not configured using a database configuration tool. + +ORAW is used to determine if monitors should be triggered for RVAL at the same +time they are triggered for VAL. + +MASK is given a value by ithe device support routines. This value is used to +manipulate the record's value, but is only the concern of the hardware device +support routines. + +The LALM fields holds the value of the last occurence of the change of +state alarm. It is used to implement the change of state alarm, and thus +only has meaning if COSV is MAJOR or MINOR. + +The MSLT field is used by the C record support routine to +determine if archive and value change monitors are invoked. They are if MSLT +is not equal to VAL. + +=fields ORAW, MASK, LALM, MLST + +The following fields are used to operate the binary input in simulation +mode. See L for more information on +these fields. + +=fields SIOL, SVAL, SIML, SIMM, SIMS + + +=cut + include "dbCommon.dbd" field(INP,DBF_INLINK) { prompt("Input Specification") @@ -104,4 +261,204 @@ recordtype(bi) { interest(2) menu(menuAlarmSevr) } + +=head2 Record Support + +=head3 Record Support Routines + +=head2 C + +This routine initializes SIMM with the value of SIML if SIML type is a +CONSTANT link or creates a channel access link if SIML type is PV_LINK. +SVAL is likewise initialized if SIOL is a CONSTANT or PV_LINK. + +This routine next checks to see that device support is available and a +device support routine is defined. If neither exist, an error is issued and +processing is terminated. + +If device support includes C, it is called. + +=head2 C + +See next section. + +=head2 C + +Fills in the values of struct valueDes so that they refer to VAL. + +=head2 C + +Retrieves ASCII string corresponding to VAL. + +=head2 C + +Retrieves ASCII strings for ZNAM and ONAM. + +=head2 C + +Check if string matches ZNAM or ONAM, and if it does, sets VAL. + +=head2 Record Processing + +Routine process implements the following algorithm: + +=over 1 + +=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. +C is called. See L for details. + +=item 3. +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. + +=item 4. +Convert. + +=back + +=over 1 + +=item * +status = read_bi + +=item * +PACT = TRUE + +=item * +TIME = tslocaltime + +=item * +if status is 0, then set VAL=(0,1) if RVAL is (0, not 0) and UDF = False. + +=item * +if status is 2, set status = 0 + +=back + +=over 1 + +=item 5. +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. Note +that if VAL is greater than 1, no checking is performed. + +=item 6. +Check if monitors should be invoked: + +=back + +=over 1 + +=item * +Alarm monitors are invoked if the alarm status or severity has changed. + +=item * +Archive and value change monitors are invoked if MSLT is not equal to VAL. + +=item * +Monitors for RVAL are checked whenever other monitors are invoked. + +=item * +NSEV and NSTA are reset to 0. + +=back + +=over 1 + +=item 7. +Scan forward link if necessary, set PACT FALSE, and return. + +=back + +=head2 Device Support + +=head3 Fields of Interest to Device Support + +Each binary input record must have an associated set of device support +routines. The primary resposibility of the device support routines is to +obtain a new raw input value whenever C is called. The device +support routines are primarily interested in the following fields: + +=fields PACT, DPVT, UDF, NSEV, NSTA, VAL, INP, RVAL, MASK + +=head3 Device Support routines + +Device support consists of the following routines: + +=head2 C + +Not currently used. + +=head2 C + +This routine is called once during IOC initialization. + +=head2 C + +This routine is optional. If provided, it is called by the record support +C routine. + +=head2 C + +This routine is called by the C 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) and I/O event list. It must be +provided for any device type that can use the ioEvent scanner. + +=head2 C + +This routine must provide a new input value. It returns the following +values: + +=over + +=item 0: +Success. A new raw value is placed in RVAL. The record support module +forces VAL to be (0,1) if RVAL is (0, not 0). + +=item 2: +Success, but don't modify VAL. + +=item Other: +Error. + +=back + +=head3 Device Support for Soft Records + +Two soft device support modules, Soft Channel and Raw Soft Channel, are +provided for input records not related to actual hardware devices. The INP +link type must be either CONSTANT, DB_LINK, or CA_LINK. + +=head3 Soft Channel + +C always returns a value of 2, which means that no conversion is +performed. + +If the INP link type is CONSTANT, then the constant value is stored in VAL +by C, and the UDF is set to FALSE. VAL can be changed via +C requests. If the INP link type is PV_LINK, the C is +called by C. + +C calls C to read the current value of VAL. +See L for details. + +If the return status of C is zero, then C sets +UDF to FALSE. The status of C is returned. + +=head3 Raw Soft Channel + +This module is like the previous except that values are read into RVAL. + +C returns a value of 0. Thus the record processing routine will +force VAL to be 0 or 1. + +=cut } diff --git a/src/std/rec/boRecord.dbd.pod b/src/std/rec/boRecord.dbd.pod index fd002c368..cbeee1abf 100644 --- a/src/std/rec/boRecord.dbd.pod +++ b/src/std/rec/boRecord.dbd.pod @@ -6,7 +6,210 @@ # EPICS BASE is distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* + +=title Binary Output Record (bo) + +The normal use for this record type is to store a simple bit (0 or 1) value +to be sent to a Digital Output module. It can also be used to write binary +values into other records via database or channel access links. This record +can implement both latched and momentary binary outputs depending on how +the HIGH field is configured. + +=head2 Parameter Fields + +The binary output's fields fall into the following categories: + +=over 1 + +=item * +scan parameters + +=item * +convert and write parameters + +=item * +operator display parameters + +=item * +alarm parameters + +=item * +run-time parameters + +=back + +=recordtype bo + +=cut + recordtype(bo) { + +=head3 Scan Parameters + +The binary output record has the standard fields for specifying under what +circumstances the record will be processed. The 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. + +=fields SCAN + +=head3 Desired Output Parameters + +The binary output record must specify where its desired output originates. +The desired output needs to be in engineering units. + +The first field that determines where the desired output originates is the +output mode select (OMSL) field, which can have two possible values: +C or C. If C is specified, the value +in the VAL field can be set externally via dbPuts at run-time. If +C is specified, the VAL field's value is obtained from the +address specified in the desired output location (DOL) field which can be a +database link, a channel access link, or a constant. To achieve continuous +control, a database link to a control algorithm record should be entered in +the DOL field. + +L
presents more information on database addresses +and links. L explaines the effect of database +linkage on scanning. + +=fields DOL, OMSL + +=head3 Convert and Write Parameters + +These parameters are used to determine where the binary output writes to +and how to convert the engineering units to a raw signal. After VAL is set +and forced to be either 1 or 0, as the result of either a dbPut or a new +value being retrieved from the link in the DOL field, then what happens +next depends on which device support routine is used and how the HIGH field +is configured. + +If the C device support routine is specified, then the device +support routine writes the VAL field's value to the address specified in +the OUT field. Otherwise, RVAL is the value written by the device support +routines after being converted. + +If VAL is equal to 0, then the record processing routine sets RVAL equal to +zero. When VAL is not equal to 0, then RVAL is set equal to the value +contained in the MASK field. (MASK is set by the device support routines +and is of no concern to the user.) Also, when VAL is not 0 and after RVAL is +set equal to MASK, the record processing routine checks to see if the HIGH +field is greater than 0. If it is, then the routine will process the record +again with VAL set to 0 after the number of seconds specified by HIGH. +Thus, HIGH implements a momentary output which changes the state of the +device back to 0 after I number of seconds. + +=fields DTYP, OUT, VAL, RVAL, HIGH, ZNAM, ONAM + +=head3 Conversion Parameters + +The ZNAM field has the string that corresponds to the 0 state, and the ONAM +field holds the string that corresponds to the 1 state. These fields, other +than being used to tell the operator what each state represents, are used +to perform conversions if the value fetched by DOL is a string. If it is, +VAL is set to the state which corresponds to that string. For instance, if the +value fetched is the string "Off" and the ZNAM string is "Off," then VAL is +set to 0. + +After VAL is set, if VAL is equal to 0, then the record processing routine +sets RVAL equal to zero. When VAL is not equal to 0, then RVAL is set equal +to the value contained in the MASK field. (Mask is set by the device +support routines and is of no concern to the user.) Also when VAL is equal +to 1 and after RVAL is set equal to MASK, the record processing routine checks +to see if the HIGH field is greater than 0. If it is, then the routine +processes the record again with VAL=0 after the number of seconds specified +by HIGH. Thus, HIGH implements a latched output which changes the state of +the device or link to 1, then changes it back to 0 after I number of seconds. + +=fields ZNAM, ONAM, HIGH + +=head3 Output Specification + +The OUT field specifies where the binary output record writes its output. +It must specify the address of an I/O card if the record sends its output +to hardware, and the DTYP field must contain the corresponding device +support module. Be aware that the address format differs according to the +I/O bus used. See L
for information on the format of +hardware addresses. You can see a list of device support modules currently +supported at the user's local site by using the C utility in R3.13. + +Otherwise, if the record is configured to use the soft device support +modules, then it can be either a database link, a channel access link, or a +constant. Be aware that nothing will be written when OUT is a constant. See +L
for information on the format of the database and +channel access addresses. Also, see L in +this chapter for more on output to other records. + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator, The +C record support routine can retrieve the state string +corresponding to the VAL's state. So, if the value is 1, C +will return the string in the ONAM field: and if 0, C will +return the ZNAM string. + +See L for more on the record name (NAME) +and description (DESC) fields. + +=fields ZNAM, ONAM, NAME, DESC + +=head3 Alarm Parameters + +These parameters are used to determine the binary output's alarm condition +and to determine the severity of that condition. The possible alarm +conditions for binary outputs are the SCAN, READ, INVALID and state alarms. +The user can configure the state alarm conditions using these fields. + +The possible values for these fields are C, C, and +C. The ZSV holds the severity for the zero state; OSV for the one +state. COSV is used to cause an alarm whenever the state changes between +states (0-1, 1-0) and its severity is configured as MINOR or MAJOR. + +See L for more information on the IVOA and +IVOV fields. L lists other fields related to alarms that are +common to all record types. + +=fields ZSV, OSV, COSV, IVOA, IVOV + +=head3 Run-Time and Simulation Mode Parameters + +These parameters are used by the run-time code for processiong the binary +output. They are not configurable using a configuration tool. They +represent the current state of the binary output. + +ORAW is used to determine if monitors should be triggered for RVAL at the +same time they are triggered for VAL. + +MASK is given a value by the device support routines and should not concern +the user. + +The RBV field is also set by device support. It is the actual read back +value obtained from the hardware itself or from the associated device +driver. + +The ORBV field is used to decide if monitors should be triggered +for RBV at the same time monitors are triggered for changes in VAL. + +The LALM field holds the value of the last occurrence of the change of +state alarm. It is used to implement the change of state alarm, and thus +only has meaning if COSV is MINOR or MAJOR. + +The MLST is used by the C record support routine to determine if +archive and value change monitors are invoked. They are if MLST is not +equal to VAL. + +The WPDT field is a private field for honoring seconds to hold HIGH. + +=fields ORAW, MASK, RBV, ORBV, LALM, MLST, RPVT, WDPT + +The following fields are used to operate the binary output in the +simulation mode. See L for more +information on these fields. + +=fields SIOL, SIML, SIMM, SIMS + +=cut + include "dbCommon.dbd" field(VAL,DBF_ENUM) { prompt("Current Value") @@ -149,6 +352,232 @@ recordtype(bo) { promptgroup("50 - Output") interest(2) } + + +=head2 Record Support + +=head3 Record Support Routines + +=head2 C + +This routine initializes SIMM if SIML is a constant or creates a channel +access link if SIML is PV_LINK. If SIOL is a 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, and error message is issued and processing is terminated. + +If DOL is a constant, then VAL is initialized to 1 if its value is nonzero +or initialzed to 0 if DOL is zero, and UDF is set to FALSE. + +If device support includes C, it is called. VAL is set using +RVAL, and UDF is set to FALSE. + +=head2 C + +See next section. + +=head2 C + +Fills in the values of struct valueDes so that they refer to VAL. + +=head2 C + +Retrieves ASCII string corresponding to VAL. + +=head2 C + +Retrieves ASCII strings for ZNAM and ONAM. + +=head2 C + +Checks if string matches ZNAM or ONAM, and if it does, sets VAL. + +=head2 Record Processing + +Routine process implements the following algorithm: + +=over 1 + +=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 + +=back + +=over + +=item * +If DOL is DB_LINK and OMSL is CLOSED_LOOP + +=over + +=item * +get values from DOL + +=item * +check for link alarm + +=item * +force VAL to be 0 or 1 + +=item * +if MASK is defined + +=over + +=item * +if VAL is 0 set RVAL = 0 + +=back + +=item * +else set RVAL = MASK + +=back + +=back + +=over + +=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. + +=item 4. +Check severity and write the new value. See L +for more information on how INVALID alarms affect output. + +=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 WAIT. If VAL is 1 and WAIT is greater than 0, process again with a +VAL=0 after WAIT seconds. + +=item 7. +Check to see if monitors should be invoked. + +=back + +=over 1 + +=item * +Alarm monitors are invoked if the alarm status or severity has changed. + +=item * +Archive and value change monitors are invoked if MLST is not equal to VAL. + +=item * +Monitors for RVAL and for RBV are checked whenever other monitors are +invoked. + +=item * +NSEV and NSTA are reset to 0. + +=back + +=over + +=item 8 +Scan forward link if necessary, set PACT FALSE, and return + +=back + +=head2 Device support + +=head3 Fields Of Interest To Device Support + +Each binary output record must have an associated set of device support +routines. The primary responsibility of the device support routines is to +write a new value whenever C is called. The device support routines +are primarily interested in the following fields: + +=fields PACT, DPVT, NSEV, NSTA, VAL, OUT, RVAL, MASK, RBV + +=head3 Decive Support Routines + +Device support consists of the following routines: + +=head2 C + +Not currently used. + +=head2 C + +This routine is called once during IOC initialization. + +=head2 C + +This routine is optional. If provided, it is called by record support +C routine. It should determine MASK if it is needed. + +=over + +=item * +0: Success. RVAL modified (VAL will be set accordingly) + +=item * +2: Success. VAL modified + +=item * +other: Error + +=back + +=head2 C + +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. + +=head2 C + +This routine must output a new value. It returns the following values: + +=over + +=item * +0: Success + +=item * +other: Error. + +=back + +=head2 Device Support For Soft Records + +Two soft device support modules C and C are +provided for output records not related to actual hardware devices. The OUT +link type must be either CONSTANT, DB_LINK, or CA_LINK. + +=head3 Soft Channel + +This module writes the current value of VAL. + +If the OUT link type is PV_LINK, then C is called by +C. C always returns a value of 2, which means +that no conversion will ever be attempted. C calls +C to write the current value of VAL. See L +for details. + +=head3 Raw Soft Channel + +This module is like the previous except that it writes the current value of +RVAL + +=cut } variable(boHIGHprecision, int) diff --git a/src/std/rec/calcRecord.dbd.pod b/src/std/rec/calcRecord.dbd.pod index e7eb0eee3..c50667fb3 100644 --- a/src/std/rec/calcRecord.dbd.pod +++ b/src/std/rec/calcRecord.dbd.pod @@ -4,9 +4,517 @@ # Copyright (c) 2002 The Regents of the University of California, as # Operator of Los Alamos National Laboratory. # EPICS BASE is distributed subject to a Software License Agreement found -# in file LICENSE that is included with this distribution. +# in file LICENSE that is included with this distribution. #************************************************************************* + +=title Calculation Record (calc) + +The calculation or "Calc" record is used to perform algebraic, relational, +and logical operations on values retrieved from other records. The result +of its operations can then be accessed by another record so that it can +then be used. + +=head2 Parameter Fields + +The fields in the record fall into the following categories: + +=over 1 + +=item * +scan parameters + +=item * +read parameters + +=item * +expression parameters + +=item * +operator display parameters + +=item * +alarm parameters + +=item * +monitor parameters + +=item * +run-time parameters + +=back + +=recordtype calc + +=cut + recordtype(calc) { + +=head3 Scan Parameters + +The Calc record has the standard fields for specifying under what +circumstances the record will be processed. These fields are listed in +L. In addition, L explains how these +fields are used. Since the Calc record supports no direct interfaces to +hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot +be C. + +=fields SCAN + + +=head3 Read Parameters + +The read parameters for the Calc record consist of 12 input links INPA, +INPB, ... INPL. The fields can be database links, channel access links, or +constants. If they are links, they must specify another record's field or a +channel access link. If they are constants, they will be initialized with +the value they are configured with and can be changed via C. They +cannot be hardware addresses. + +See L
for information on how to specify database +links. + +=fields INPA, INPB, INPC, INPD, INPE, INPF, INPG, INPH, INPI, INPJ, INPK, INPL + +=head3 Expression + +At the core of the Calc record lies the CALC and RPCL fields. The CALC field +contains the infix expresion which the record routine will use when it +processes the record. The resulting value is placed in the VAL field and +can be accessed from there. The CALC expression is actually converted to +opcode and stored as Reverse Polish Notation in the RPCL field. It is this +expression which is actually used to calculate VAL. The Reverse Polish +expression is evaluated more efficiently during run-time than an infix +expression. CALC can be changed at run-time, and a special record routine +calls a function to convert it to Reverse Polish Notation. + +The infix expressions that can be used are very similar to the C expression +syntax, but with some additions and subtle differences in operator meaning +and precedence. The string may contain a series of expressions separated by +a semi-colon character ";" any one of which may actually provide the +calculation result; however, all of the other expressions included must +assign their result to a variable. All alphabetic elements described below +are case independent, so upper and lower case letters may be used and mixed +in the variable and function names as desired. Spaces may be used anywhere +within an expression except between characters that make up a single +expression element. + +The range of expressions supported by the calculation record are separated +into literals, constants, operands, algebraic operators, trigonometric operators, +relational operators, logical operators, the assignment operator, +parentheses and commas, and the question mark or '?:' operator. + +=fields CALC, RPCL + +=head3 Literals + +=over 1 + +=item * +Standard double precision floating point numbers + +=item * +Inf: Infinity + +=item * +Nan: Not a Number + +=back + +=head3 Constants + +=over 1 + +=item * +PI: returns the mathematical constant E + +=item * +D2R: evaluates to E/180 which, when used as a multiplier, converts an +angle from degrees to radians + +=item * +R2D: evaluates to 180/E which as a multiplier converts an angle from +radians to degrees + +=back + +=head3 Operands + +The expression uses the values retrieved from the INPx links as operands, +though constants can be used as operands too. These values retrieved from +the input links are stored in the A-L fields. The values to be used in the +expression are simply referenced by the field letter. For instance, the +value obtained from INPA link is stored in the field A, and the value +obtained from INPB is stored in field B. The field names can be included in +the expression which will operate on their respective values, as in A+B. +Also, the RNDM nullary function can be included as an operand in the +expression in order to generate a random number between 0 and 1. + +=fields A, B, C, D, E, F, G, H, I, J, K, L + +The keyword VAL returns the current contents of the VAL field (which can be +written to by a CA put, so it might I be the result from the last time +the expression was evaluated). + +=head3 Algebraic Operators + +=over 1 + +=item * +ABS: Absolute value (unary) + +=item * +SQR: Square root (unary) + +=item * +MIN: Minimum (any number of args) + +=item * +MAX: Maximum (any number of args) + +=item * +FINITE: returns non-zero if none of the arguments are NaN or Inf (any +number of args) + +=item * +ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number +of args) + +=item * +CEIL: Ceiling (unary) + +=item * +FLOOR: Floor (unary) + +=item * +LOG: Log base 10 (unary) + +=item * +LOGE: Natural log (unary) + +=item * +LN: Natural log (unary) + +=item * +EXP: Exponential function (unary) + +=item * +^ : Exponential (binary) + +=item * +** : Exponential (binary) + +=item * ++ : Addition (binary) + +=item * +- : Subtraction (binary) + +=item * +* : Multiplication (binary) + +=item * +/ : Division (binary) + +=item * +% : Modulo (binary) + +=item * +NOT: Negate (unary) + +=back + +=head3 Trigonometric Operators + +=over 1 + +=item * +SIN: Sine + +=item * +SINH: Hyperbolic sine + +=item * +ASIN: Arc sine + +=item * +COS: Cosine + +=item * +COSH: Hyperbolic cosine + +=item * +ACOS: Arc cosine + +=item * +TAN: Tangent + +=item * +TANH: Hyperbolic tangent + +=item * +ATAN: Arc tangent + +=back + +=head3 Relational Operators + +=over 1 + +=item * +>= : Greater than or equal to + +=item * +> : Greater than + +=item * +<= : Less than or equal to + +=item * +< : Less than + +=item * +# : Not equal to + +=item * += : Equal to + +=back + +=head3 Logical Operators + +=over 1 + +=item * +&& : And + +=item * +|| : Or + +=item * +! : Not + +=back + +=head3 Bitwise Operators + +=over 1 + +=item * +| : Bitwise Or + +=item * +& : Bitwise And + +=item * +OR : Bitwise Or + +=item * +AND : Bitwise And + +=item * +XOR : Bitwise Exclusive Or + +=item * +~ : One's Complement + +=item * +<< : Left shift + +=item * +>> : Right shift + +=back + +=head3 Assignment Operator + +=over 1 + +=item * +:= : assigns a value (right hand side) to a variable (i.e. field) + +=back + +=head3 Parantheses, Comma, and Semicolon + +The open and close parentheses are supported. Nested parentheses are +supported. + +The comma is supported when used to separate the arguments of a binary +function. + +The semicolon is used to separate expressions. Although only one +traditional calculation expression is allowed, multiple assignment +expressions are allowed. + +=head3 Conditional Expression + +The C language's question mark operator is supported. The format is: +C + +=head3 Expression Examples + +=head3 Algebraic + +C + +=over 1 + +=item * +Result is A + B + 10 + +=back + +=head3 Relational + +C<(A + B) < (C + D)> + +=over 1 + +=item * +Result is 1 if (A + B) < (C + D) + +=item * +Result is 0 if (A + B) >= (C + D) + +=back + +=head3 Question Mark + +C<(A + B) < (C + D) ? E : F + L + 10> + +=over 1 + +=item * +Result is E if (A + B) < (C + D) + +=item * +Result is F + L + 10 if (A + B) >= (C + D) + +=back + +Prior to Base 3.14.9 it was legal to omit the : and the second (else) part +of the conditional, like this: + +C<(A + B)<(C + D) ? E> + +=over 1 + +=item +Result is E if (A + B)<(C + D) + +=item +Result is unchanged if (A + B)>=(C + D) + +From 3.14.9 onwards, this expresion must be written as +C<(A + B) < (C + D) ? E : VAL> + +=back + +=head3 Logical + +C + +=over 1 + +=item * +Causes the following to occur: + +=over 1 + +=item * +Convert A to integer + +=item * +Convert B to integer + +=item * +Bitwise And A and B + +=item * +Convert result to floating point + +=back + +=back + +=head3 Assignment + +C + +=over 1 + +=item * +Causes the Calc record to output the successive values of a sine curve in +1 degree intervals. + +=back + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. These +fields are used to display VAL and other parameters of the calculation +record either textually or graphically. + +The EGU field contains a string of up to 16 characters which is supplied by +the user and which describes the values being operated upon. The string is +retrieved whenever the routine C is called. The EGU string is +solely for an operator's sake and does not have to be used. + +The HOPR and LOPR fields only refer to the limits of the VAL, HIHI, HIGH, +LOW and LOLO fields. PREC controls the precision of the VAL field. + +See L for more on the record name (NAME) +and description (DESC) fields. + +=fields EGU, PREC, HOPR, LOPR, NAME, DESC + +=head3 Alarm Parameters + +The possible alarm conditions for the Calc record are the SCAN, READ, +Calculation, and limit alarms. The SCAN and READ alarms are called by the +record support routines. The Calculation alarm is called by the record +processing routine when the CALC expression is an invalid one, upon which +an error message is generated. + +The following alarm parameters which are configured by the user, define the +limit alarms for the VAL field and the severity corresponding to those +conditions. + +The HYST field defines an alarm deadband for each limit. See L +for a complete explanation of alarms of these fields. L +lists other fields related to alarms that are common to all record types. + +=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST + +=head3 Monitor Parameters + +These paramaeters are used to determine when to send monitors for the value +fields. These monitors are sent when the value field exceeds the last +monitored field by the appropriate deadband, the ADEL for archiver monitors +and the MDEL field for all other types of monitors. If these fields have a +value of zero, everytime the value changes, monitors are triggered; if they have a +value of -1, everytime the record is scanned, monitors are triggered. See +L for a complete explanation of monitors. + +=fields ADEL, MDEL + +=head3 Run-time Parameters + +These fields are not configurable using a configuration tool and none are +modifiable at run-time. They are used to process the record. + +The LALM field is used to implement the hysteresis factor for the alarm +limits. + +The LA-LL fields are used to decide when to trigger monitors for the +corresponding fields. For instance, if LA does not equal the value A, +monitors for A are triggered. The MLST and ALST fields are used in the same +manner for the VAL field. + +=fields LALM, ALST, MLST, LA, LB, LC, LD, LE, LF, LG, LH, LI, LJ, LK, LL + +=cut + include "dbCommon.dbd" field(VAL,DBF_DOUBLE) { prompt("Result") @@ -321,4 +829,120 @@ recordtype(calc) { interest(4) extra("char rpcl[INFIX_TO_POSTFIX_SIZE(80)]") } + +=head2 Record Support + +=head3 Record Support Routines + +=head2 C + +For each constant input link, the corresponding value field is initialized +with the constant value if the input link is CONSTANT or a channel access +link is created if the input link is a PV_LINK. + +A routine postfix is called to convert the infix expression in CALC to +Reverse Polish Notation. The result is stored in RPCL. + +=head2 C + +See next section. + +=head2 C + +This is called if CALC is changed. C calls postfix. + +=head2 C + +Fills in the values of struct valueDes so that the refer to VAL. + +=head2 C + +Retrieves EGU. + +=head2 C + +Retrieves PREC. + +=head2 C + +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 will be used. + +=head2 C + +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. + +=head2 C + +Sets the following values: + +=over 1 + +upper_alarm_limit = HIHI + +upper_warning_limit = HIGH + +lower_warning_limit = LOW + +lower_alarm_limit = LOLO + +=back + +=head3 Record Processing + +Routine process implements the following algorithm: + +=over 1 + +=item 1. +Fetch all arguments. + +=item 2. +Call routine C, which calculates VAL from the postfix version of +the expression given in CALC. If C returns success 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 +at least HYST before the alarm status and severity changes. + +=item 4. +Check to see if monitors should be invoked. + +=back + +=over 1 + +=item * +Alarm monitors are invoked if the alarm status or severity has changed. + +=item * +Archive and values change monitors are invoked if ADEL and MDEL conditions +are met. + +=item * +Monitors for A-L are checked whenever other monitors are invoked. + +=item * +NSEV and NSTA are reset to 0. + +=back + +=over + +=item 5. +Scan forward link if necessary, set PACT FALSE, and return. + +=back + +=cut + } diff --git a/src/std/rec/calcoutRecord.dbd.pod b/src/std/rec/calcoutRecord.dbd.pod index 5bf2e54de..6289f9043 100644 --- a/src/std/rec/calcoutRecord.dbd.pod +++ b/src/std/rec/calcoutRecord.dbd.pod @@ -4,8 +4,58 @@ # Copyright (c) 2002 The Regents of the University of California, as # Operator of Los Alamos National Laboratory. # EPICS BASE is distributed subject to a Software License Agreement found -# in file LICENSE that is included with this distribution. +# in file LICENSE that is included with this distribution. #************************************************************************* + +=title Calculation Output Record (calcout) + +The Calculation Output or "Calcout" record is similar to the Calc record +with the added feature of having outputs (an "output link" and an "output +event") which are conditionally executed based on the result of the +calculation. This feature allows conditional branching to be implemented +within an EPICS database (e.g. process Record_A only if Record_B has a +value of 0). The Calcout record is also similar to the Wait record (with +additional features) but uses EPICS standard INLINK and OUTLINK fields +rather than the DBF_STRING fields used in the Wait record. For new +databases, it is recommended that the Calcout record be used instead of the +Wait record. + +=head2 Parameter Fields + +The fields in this record fall into these categories: + +=over 1 + +=item * +scan parameters + +=item * +read parameters + +=item * +expression parameters + +=item * +output parameters + +=item * +operator display parameters + +=item * +alarm parameters + +=item * +monitor parameters + +=item * +run-time parameters + +=back + +=recordtype calcout + +=cut + menu(calcoutOOPT) { choice(calcoutOOPT_Every_Time,"Every Time") choice(calcoutOOPT_On_Change,"On Change") @@ -24,7 +74,556 @@ menu(calcoutINAV) { choice(calcoutINAV_LOC,"Local PV") choice(calcoutINAV_CON,"Constant") } + recordtype(calcout) { + +=head3 Scan Parameters + +The Calcout record has the standard fields for specifying under what +circumstances the record will be processed. The fields are listed in +L. In addition, L explains how these +fields are used. Since the Calcout record supports no direct interfaces to +hardware, it cannot be scanned on I/O interrupt, so its SCAN field cannot +be C. + +=head3 Read Parameters + +The read parameters for the Calcout record consists of 12 input links INPA, +INPB, ... INPL. The fields can be database links, channel access links, or +constants. If they are links, they must specify another record's field. If +they are constants, they will be initialized with the value they are +configured with and can be changed via C. These fields cannot be +hardware addresses. In addition, the Calcout record contains the INAV, +INBV, ... INLV fields which indicate the status of the link fields, for +example, whether or not the specified PV was found and a link to it +established. See L for an explanation of these +fields. + +See L
for information on how to specify database +links. + +=fields INPA, INPB, INPC, INPD, INPE, INPF, INPG, INPH, INPI, INPJ, INPK, INPL + +=head3 Expression + +Like the Calc record, the Calcout record has a CALC field in which the +developer can enter an infix expression which the record routine will +evaluate when it processes the record. The resulting value is placed in the +VAL field. This value can then be used by the OOPT field (see +L) to determine whether or not to write to the output +link or post an output event. It can also be the value that is written to +the output link. The CALC expression is actually converted to opcode and +stored in Reverse Polish Notation in the RPCL field. It is this expression +which is actually used to calculate VAL. The Reverse Polish expression is +evaluated more efficiently during run-time than an infix expression. CALC +can be changes at run-time, and a special record routine will call a +function to convert it to Reverse Polish Notation. + +The infix expressions that can be used are very similar to the C expression +syntax, but with some additions and subtle differences in operator meaning +and precedence. The string may contain a series of expressions separated by +a semi-colon character ';' any one of which may actually provide the +calculation result; however all of the other expressions included must +assign their result to a variable. All alphabetic elements described below +are case independent, so upper and lower case letters may be used and mixed +in the variable and function names as desired. Spaces may be used anywhere +within an expression except between the characters that make up a single +expression element. + +The range of expressions supported by the calculation record are separated into +literals, constants, operands, algebraic operators, trigonometric operators, +relational operators, logical operator, the assignment operator, +parentheses and commas, and the question mark or '?:' operator. + +=fields CALC, VAL, RPCL + +=head3 Literals + +=over 1 + +=item * +Standard double precision floating point numbers + +=item * +Inf: Infinity + +=item * +Nan: Not a Number + +=back + +=head3 Constants + +=over + +=item * +PI: returns the mathematical constant E + +=item * +D2R: evaluates to E/180 which, when used as a multiplier, converts an +angle from degrees to radians + +=item * +R2D: evaluates to 180/E which, when used as a multiplier, converts an +angle from radians to degrees + +=back + +=head3 Operands + +The expression can use the values retrieved from the INPx links as +operands, though constants can be used as operands too. These values +retrieved from the input links are stored in the A-L fields. The values to +be used in the expression are simple references by the field letter. For +instance, the value obtained from the INPA link is stored in field A, and +the values obtained from the INPB link is stored in the field B. The names +can be included in the expression will operate on their respective values, +as in A+B. + +=fields A, B, C, D, E, F, G, H, I, J, K, L + +The keyword VAL returns the current contents of the expression's result +field, i.e. the VAL field for the CALC expression and the OVAL field for +the OCAL expression. (These fields can be written to by CA put, so it might +I be the result from the last time the expression was evaluated). + +=head3 Algebraic Operations + +=over 1 + +=item * +ABS: Absolute value (unary) + +=item * +SQR: Square root (unary) + +=item * +MIN: Minimum (any number of args) + +=item * +MAX: Maximum (any number of args) + +=item * +FINITE: returns non-zero if none of the arguments are NaN or Inf (any +number of args) + +=item * +ISNAN: returns non-zero if any of the arguments is NaN or Inf (any number +of args) + +=item * +CEIL: Ceiling (unary) + +=item * +FLOOR: Floor (unary) + +=item * +LOG: Log base 10 (unary) + +=item * +LOGE: Natural log (unary) + +=item * +LN: Natural log (unary) + +=item * +EXP: Exponential function (unary) + +=item * +^ : Exponential (binary) + +=item * +** : Exponential (binary) + +=item * ++ : Addition (binary) + +=item * +- : Subtraction (binary) + +=item * +* : Multiplication (binary) + +=item * +/ : Division (binary) + +=item * +% : Modulo (binary) + +=item * +NOT: Negate (unary) + +=back + +=head3 Trigonometric Operators + +=over 1 + +=item * +SIN: Sine + +=item * +SINH: Hyperbolic sine + +=item * +ASIN: Arc sine + +=item * +COS: Cosine + +=item * +COSH: Hyperbolic cosine + +=item * +ACOS: Arc cosine + +=item * +TAN: Tangent + +=item * +TANH: Hyperbolic tangent + +=item * +ATAN: Arc tangent + +=back + +=head3 Relational Operators + +=over 1 + +=item * +>= : Greater than or equal to + +=item * +> : Greater than + +=item * +<= : Less than or equal to + +=item * +< : Less than + +=item * +# : Not equal to + +=item * += : Equal to + +=back + +=head3 Logical Operators + +=over 1 + +=item * +&& : And + +=item * +|| : Or + +=item * +! : Not + +=back + +=head3 Bitwise Operators + +=over 1 + +=item * +| : Bitwise Or + +=item * +& : Bitwise And + +=item * +OR : Bitwise Or + +=item * +AND : Bitwise And + +=item * +XOR : Bitwise Exclusive Or + +=item * +~ : One's Complement + +=item * +<< : Left shift + +=item * +>> : Right shift + +=back + +=head3 Assignment Operator + +=over 1 + +=item * +:= : assigns a value (right hand side) to a variable (i.e. field) + +=back + +=head3 Parentheses and Comma + +The open and close parentheses are supported. Nested parentheses are +supported. + +The comma is supported when used to separate the arguments of a binary +function. + +=head3 Conditional Expression + +The C language's question mark operator is supported. The format is: +C + +=head3 Expression Examples + +=head3 Algebraic + +C + +=over 1 + +=item * +Result is A + B + 10 + +=back + +=head3 Relational + +C<(A + B) < (C + D)> + +=over 1 + +=item * +Result is 1 if (A + B) < (C + D) + +=item * +Result is 0 if (A + B) >= (C + D) + +=back + +=head3 Question Mark + +C<(A + B) < (C + D) ? E : F + L + 10> + +=over 1 + +=item * +Result is E if (A + B) < (C + D) + +=item * +Result is F + L + 10 if (A + B) >= (C + D) + +=back + +=head3 Logical + +C + +=over 1 + +=item * +Causes the following to occur: + +=over 1 + +=item * +Convert A to integer + +=item * +Convert B to integer + +=item * +Bitwise And A and B + +=item * +Convert result to floating point + +=back + +=back + +=head3 Output Parameters + +These parameters specify and control the output capabilities of the Calcout +record. They determine when to write the output, where to write it, and what +the output will be. The OUT link specifies the Process Variable to which +the result will be written. + +=head4 Menu calcoutOOPT + +The OOPT field determines the condition that causes the output link to be +written to. It's a menu field that has six choices: + +=menu calcoutOOPT + +=over + +=item * +C -- write output every time record is processed. + +=item * +C -- write output every time VAL changes, i.e., every time the +result of the expression changes. + +=item * +C -- when record is preocessed, write output if VAL is zero. + +=item * +C -- when record is processed, write output if VAL is +non-zero. + +=item * +C -- when record is processed, write output only if VAL +is zero and the last value was non-zero. + +=item * +C -- when record is processed, write output only if +VAL is non-zero and last value was zero. + +=back + +=head4 Menu calcoutDOPT + +The DOPT field determines what data is written to the output link when the +output is executed. The field is a menu field with two options: + +=menu calcoutDOPT + +If C is specified, when the record writes its +output it will write the result of the expression in the CALC field, that +is, it will write the value of the VAL field. If C is specified, +the record will instead write the result of the expresion in the OCAL +field, which is contained in the OVAL field. The OCAL field is exactly like +the CALC field and has the same fuctionality it can contain the string +representation of an expression which is evaluated at run-time. Thus, if +necessary, the record can use the result of the CALC expression to +determine if data should be written and can use the result of the OCAL +expression as the data to write. + +If the OEVT field specifies a non-zero integer and the condition in the +OOPT field is met, the record will post a corresponding event. If the ODLY +field is non-zero, the record pauses for the specified number of seconds +before executing the OUT link or posting the output event. During this +waiting period the record is "active" and will not be processed again until +the wait is over. The field DLYA is equal to 1 during the delay period. The +resolution of the delay entry system dependent. + +The IVOA field specifies what action to take with the OUT link if the +Calcout record eneters an INVALID alarm status. The options are +C, C, and C. +If the IVOA field is C, the data entered into the +IVOV field is written to the OUT link if the record alarm severity is +INVALID. + +=fields OUT, OOPT, DOPT, OCAL, OVAL, OEVT, ODLY, IVOA, IVOV + +=head3 Operator Display Parameter + +These parameters are used to present meaningful data to the operator. Some +are also meant to represent the status of the record at run-time. + +The EGU field contains a string of up to 16 characters which is supplied by +the user and which describes the values being operated upon. The string is +retrieved whenever the routine C is called. The EGU string is +solely for an operator's sake and does not have to be used. + +The HOPR and LOPR fields on;y refer to the limits if the VAL, HIHI, HIGH, +LOW, and LOLO fields. PREC controls the precision of the VAL field. + +=head4 Menu calcoutINAV + +The INAV-INLV fields indicate the status of the link to the PVs specified +in the INPA-INPL fields, respectfully. These field can have four possible +values: + +=menu calcoutINAV + +=over 1 + +=item * +C -- the PV wasn't found on this IOC and a Channel Access link +hasn't been established. + +=item * +C -- the PV wasn't found on this IOC and a Channel Access link +has been established. + +=item * +C -- the PV was found on this IOC. + +=item * +C -- the corresponding link field is a constant. + +=back + +The OUTV field indicates the status of the OUT link. If has the same +possible values as the INAV-INLV fields. + +The CLCV and OLCV fields indicate the validity of the expression in the +CALC and OCAL fields respectfully. If the expression in invalid, the field +is set to one. + +The DYLA field is set to one during the delay specified in ODLY. + +See L for more information on the record +name (NAME) and description (DESC) fields. + +=fields EGU, PREC, HOPR, LOPR, INAV, INBV, INCV, INDV, INEV, INFV, INGV, INHV, INIV, INJV, INKV, INLV, OUTV, CLCV, OCLV, DLYA, NAME, DESC + +=head3 Alarm Parameters + +The possible alarm conditions for the Calcout record are the SCAN, READ, +Calculation, and limit alarms. The SCAN and READ alarms are called by the +record support routines. The Calculation alarm is called by the record +processing routine when the CALC expression is an invalid one, upon which +an error message is generated. + +The following alarm parametersi, which are configured by the user, define the +limit alarms for the VAL field and the severity corresponding to those +conditions. + +The HYST field defines an alarm deadband for each limit. See +L for a complete explanation of alarms and these +fields. C lists other fields related to alarms that are +common to all record types. + +=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST + +=head3 Monitor Parameters + +These parameters are used to determine when to send monitors for the value +fields. These monitors are sent when the value field exceeds the last +monitored field by the appropriate deadband, the ADEL for archiver monitors +and the MDEL field for all aother types of monitors. If these fields have a +value of zero, every time the value changes, monitors are triggered; if +they have a value of -1, every time the record is scanned, monitors are +triggered. See L for a complete explanation of +monitors. + +=fields ADEL, MDEL + +=head3 Run-time Parameters + +These fields are not configurable using a configuration tool and none are +modifiable at run-time. They are used to process the record. + +The LALM field is used to implement the hysteresis factor for the alarm +limits. + +The LA-LL fields are used to decide when to trigger monitors for the +corresponding fields. For instance, if LA does not equal the value for A, +monitors for A are triggered. The MLST and ALST fields are used in the same +manner for the VAL field. + +=fields LALM, ALST, MLST, LA, LB, LC, LD, LE, LF, LG, LH, LI, LJ, LK, LL + +=cut + include "dbCommon.dbd" field(RPVT,DBF_NOACCESS) { prompt("Record Private") @@ -524,6 +1123,148 @@ recordtype(calcout) { interest(4) extra("char orpc[INFIX_TO_POSTFIX_SIZE(80)]") } + +=head2 Record Support + +=head3 Record Support Routines + +=head2 C + +For each constant input link, the corresponding value field is initialized +with the constant value if the input link is CONSTANT or a channel access +link is created if the input link is PV_LINK. + +A routine postfix is called to convert the infix expression in CALC and +OCAL to Reverse Polish Notation. The result is stored in RPCL and ORPC, +respectively. + +=head2 C + +See next section. + +=head2 C + +This is called id CALC or OCAL is changed. C calls postfix. + +=head2 C + +Fills in the values of struct valueDes so that they refer to VAL. + +=head2 C + +Retrieves EGU. + +=head2 C + +Retrieves PREC. + +=head2 C + +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 macimum values for the field type will be used. + +=head2 C + +Sets the upper control and lower control limits for a field. If the VAL, +HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the +field has upper and lower limits defimed they will be used, else the upper +and lower maximum values for the field will be used. + +=head2 C + +Sets the following values: + +=over + +upper_alarm_limit = HIHI + +upper_warning_limit = HIGH + +lower warning_limit = LOW + +lower_alarm_limit = LOLO + +=back + +=head3 Record Processing + +=head2 C + +The C routine implements the following algorithm: + +=over + +=item 1. +Fetch all arguments. + +=item 2. +Call routine C, which calculates VAL from the prefix version +of the expression given in CALC. If C returns success, 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. If also +honors the alarm hysteresis factor (HYST). Thus the value must change by at +least HYST before the alarm status and severity changes. + +=item 4. +Determin if the Output Execution Option (OOPT) is met. If it met, either +execute the output link (and output event) immediately (if ODLY = 0), or +schedule a callback after the specified interval. See the explanation for +the C routine below. + +=item 5. +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 * +Monitors for A-L are checked whenever other monitors are invoked. + +=item * +NSEV and NSTA are reset to 0 + +=back + +=item 6. +If no output delay was specified, scan forwark link if necessaru, set PACT +FALSE, and return. + +=back + +=head2 C + +=over + +=item 1. +If DOPT field specifies the use of OCAL, call the routine C +for the postfix version of the expression in OCAL. Otherwise, use VAL. + +=item 2. +If the Alarm Severity is INVALID, follow the option as designated by the +field IVOA. + +=item 3. +The Alarm Severity is not INVALID or IVOA specifies "Continue Normally", +put the value of OVAL to the OUT link and post the event in OEVT (if +non-zero). + +=item 4. +If an output delay was implemented, process the forwark link. + +=back + +=cut } variable(calcoutODLYprecision, int) diff --git a/src/std/rec/dfanoutRecord.dbd.pod b/src/std/rec/dfanoutRecord.dbd.pod index c2eb42a75..0d0487666 100644 --- a/src/std/rec/dfanoutRecord.dbd.pod +++ b/src/std/rec/dfanoutRecord.dbd.pod @@ -6,12 +6,175 @@ # EPICS BASE is distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* + +=title Data Fanout Record (dfanout) + +The Data Fanout or "dfanout" record is used to forward data to up to +eight other records. It's similar to the fanout record except that the +capability to forward data has been added to it. If has no associated +device support. + +=head2 Parameter Fields + +The fields in this record can be classified into the following categories: + +=over + +=item * +scan parameters + +=item * +desired output parameters + +=item * +write parameters + +=item * +operator display parameters + +=item * +alarm parameters + +=item * +monitor parameters + +=item * +run-time and simulation mode parameters + +=back + +=recordtype dfanout + +=cut + menu(dfanoutSELM) { choice(dfanoutSELM_All,"All") choice(dfanoutSELM_Specified,"Specified") choice(dfanoutSELM_Mask,"Mask") } + recordtype(dfanout) { + +=head3 Scan Parameters + +The data fanout 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. Since the data fanout record supports no direct interfaces +to hardware, it cannot be scanned on I/O interrupt, so its SCAN field +cannot be C. + +=head3 Desired Output Parameters + +The data fanout record must specify where the desired output value +originates, i.e., the data which is to be fowarded to the records in its +output links. The output mode select (OMSL) field determines whether the +output originates from another record or from run-time database access. +When set to C, the desired output is retrieved from the link +specified in the desired output (DOL) field, which can specify either a +database or a channel access link, and placed into the VAL field. When set +to C, the desired output can be written to the VAL field via +dbPuts at run-time. + +The DOL field can also be a constant in which case the VAL field is +initialized to the constant value. + +Note that there are no conversion parameters, so the desired output value +undergoes no conversions before it is sent out to the output links. + +=fields DOL, OMSL, VAL + +=head3 Write Parameters + +The OUTA-OUTH fields specify where VAL is to be sent. Each field that is to +forward data must specify an address to another record. See +L
for information on specifying links. + +The SELL, SELM, and SELN fields specify which output links are to be +used. + +=head4 Menu dfanoutSELM + +SELM is a menu, with three choices: + +=menu dfanoutSELM + +If SELM=="All", then all output links are used, and the values of +SELL and SELN are ignored. + +If SELM=="Specified", then the value of SELN is used to specify a single +link which will be used. If SELN==0, then no link will be used; if SELN==1, +then OUTA will be used, and so on. + +SELN can either have its value set directly, or have its values retrieved +from another EPICS PV. If SELL is a valid PV link, then SELN will be set to +the values of the linked PV. + +If SELM=="Mask", then SELN will be treated as a bit mask. If bit one of +SELN is set, then OUTA will be used, if bit two is set, OUTB will be used. +Thus if SELN==5, OUTC and OUTA will be used. + +=fields OUTA, OUTB, OUTC, OUTD, OUTE, OUTF, OUTG, OUTH + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. They +display the value and other parameters of the data fanout record either +textually or graphically. + +The EGU field can contain a string of up to 16 characters describing the +value on the VAL field. + +The HOPR and LOPR fields determine the upper and lower display limits for +graphic displays and the upper and lower control limits for control +displays. They apply to the VAL, HIHI, HIGH, LOW, and LOLO fields. The +record support routines C or C +retrieve HOPR and LOPR. + +See L for more on the record name (NAME) +and description (DESC) fields. + +=fields EGU, HOPR, LOPR, NAME, DESC + +=head3 Alarm Parameters + +The possible alarm conditions for data fanouts are the SCAN, READ, INVALID, +and limit alarms. The SCAN and READ alarms are called by the record +routines. The limit alarms are configured by the user in the HIHI, LOLO, +HIGH, and LOW fields using floating point values. The limit alarms apply +only to the VAL field. The severity for each of these limits is specified +in the corresponding field (HHSV, LLSV, HSV, LSV) and can be either +NO_ALARM, MINOR, or MAJOR. In the hysteresis field (HYST) can be entered a +number which serves as the deadband on the limit alarms. + +See L for a complete explanation of alarms and these +fields. L lists other fields related to alarms that are +common to all record types. + +=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST + +=head3 Monitor Parameters + +These parameters are used to determine when to send monitors placed on the +VAL field. These monitors are sent when the value field exceeds the last +monitored fields by the specified deadband, ADEL for archivers monitors and +MDEL for all other types of monitors. 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. See +L for a complete explanation of monitors. + +=fields ADEL, MDEL + +=head3 Run-Time Parameters and Simulation Mode Parameters + +These parameters are used by the run-time code for processing the data +fanout record. Ther are not configurable. They are used to implement the +hysteresis factors for monitor callbacks. + +=fields LALM, ALST, MLST + +=cut + include "dbCommon.dbd" field(VAL,DBF_DOUBLE) { prompt("Desired Output") @@ -201,4 +364,91 @@ recordtype(dfanout) { special(SPC_NOMOD) interest(3) } + +=head2 Record Support + +=head3 Record Support Routines + +=head2 C + +This routine initializes all output links that are defined. Then it initializes +DOL if DOL is a constant or a PV_LINK. When initializing the output links +and the DOL link, a non-zero value is returned if an error occurs. + +=head2 C + +See next section. + +=head2 C + +This routine fills in the members of C with the VAL fields +value and characteristics. + +=head2 C + +The routine copies the string specified in the EGU field to the location +specified by a pointer which is passed to the routine. + +=head2 C + +If the referenced field is VAL, HIHI, HIGH, LOW, or LOLO, this routine sets +the C member of the C structure to the +HOPR and the C member to the LOPR. If the referenced +field is not one of the above fields, then C +routine is called. + +=head2 C + +Same as the C routine except that it uses the +C structure. + +=head2 C + +This sets the members of the C structure to the specified +alarm limits if the referenced field is VAL: + +=over + +upper_alarm_limit = HIHI + +upper_warning_limit = HIGH + +lower_warning_limit = LOW + +lower_alarm_limit = LOLO + +=back + +If the referenced field is not VAL, the C routine +is called. + +=head3 Record Processing + +=over + +=item 1. +The C routine first retrieves a value for DOL and places it in +VAL if OMSL is set to colsed loop mode. If an error occurs, then UDF is set +to FALSE. + +=item 2. +PACT is set TRUE + +=item 3. +VAL is then sent to all the records specified in the OUTA-OUTH fields by +calling C for each link. + +=item 4. +Alarms are checked and monitors are called if conditions apply. + +=item 5. +The data fanout's own forward link is then processed. + +=item 6. +PACT is set FALSE, and the C routine returns. A -1 is returned +if there was an error writing values to one of the output links. + +=back + +=cut }