diff --git a/src/std/filters/filters.dbd b/src/std/filters/filters.dbd index 69a40b9fc..9dbc97feb 100644 --- a/src/std/filters/filters.dbd +++ b/src/std/filters/filters.dbd @@ -1,137 +1,141 @@ -#=head1 Channel Filters -# -# Channel Filters can be applied to Channel Access channels by a client, using -# a JSON Field Modifier to select the filter and any parameters. -# The following filters are available in this release: -# -#=over 4 -# -#=item * L -# -#=item * L -# -#=item * L -# -#=item * L -# -#=back -# -#=head2 Using Filters -# -# Channel filters can be added to any Channel Access channel name. -# There can be more than one filter applied to the same channel, in which case the -# order that they are specified will control the order in which they are applied -# to the resulting data-stream. -# The filter specification must appear after the field name, or if the default -# (VAL) field is used after a dot C<.> appended to the record name. -# With the exception of the array short-hand which is described below, all filters -# must appear inside a pair of braces C< {} > after the dot expressed as a JSON -# (L) object, which allows filter -# parameters to be included as needed. -# -# Each filter is given as a name/value pair. The filter name (given in parentheses -# in the titles below) is a string, and must be enclosed inside double-quotes C<"> -# characters as per the JSON specification. -# Parameters to that filter are provided as the value part of the name/value pair, -# and will normally appear as a child JSON object consisting of name/value pairs -# inside a nested pair of braces C< {} >. -# -#=head4 Example Filter -# -# Given a record called C the following would apply a filter C to -# the VAL field of that record, giving the filter two numeric parameters named C -# and C: -# -# test:channel.{"f":{"lo":0,"hi":10}} -# -# Note that due to the required presence of the double-quote characters in the JSON -# strings in the name string, it will usually be necessary to enclose a filtered name -# within single-quotes C<< ' E ' >> when typing it as an argument to a Unix -# shell command. -# -#=head2 Filter Reference -# +=head1 Channel Filters + +Channel Filters can be applied to Channel Access channels by a client, using +a JSON Field Modifier to select the filter and any parameters. +The following filters are available in this release: + +=over 4 + +=item * L + +=item * L + +=item * L + +=item * L + +=back + +=head2 Using Filters + +Channel filters can be added to any Channel Access channel name. +There can be more than one filter applied to the same channel, in which case the +order that they are specified will control the order in which they are applied +to the resulting data-stream. +The filter specification must appear after the field name, or if the default +(VAL) field is used after a dot C<.> appended to the record name. +With the exception of the array short-hand which is described below, all filters +must appear inside a pair of braces C< {} > after the dot expressed as a JSON +(L) object, which allows filter +parameters to be included as needed. + +Each filter is given as a name/value pair. The filter name (given in parentheses +in the titles below) is a string, and must be enclosed inside double-quotes C<"> +characters as per the JSON specification. +Parameters to that filter are provided as the value part of the name/value pair, +and will normally appear as a child JSON object consisting of name/value pairs +inside a nested pair of braces C< {} >. + +=head4 Example Filter + +Given a record called C the following would apply a filter C to +the VAL field of that record, giving the filter two numeric parameters named +C and C: + + test:channel.{"f":{"lo":0,"hi":10}} + +Note that due to the required presence of the double-quote characters in the +JSON strings in the name string, it will usually be necessary to enclose a +filtered name within single-quotes C<< ' E ' >> when typing it as an +argument to a Unix shell command. + +=head2 Filter Reference + +=cut registrar(tsInitialize) -#=head3 TimeStamp Filter C<"ts"> -# -# This filter is used to set the timestamp of the (first) value fetched through the -# channel to the connection time, rather than the time the record last processed -# which could have been days or even weeks ago for some records, or set to the -# EPICS epoch if the record has never processed. -# -#=head4 Parameters -# -# None, use an empty pair of braces. -# -#=head4 Example -# -# Hal$ caget -a 'test:channel.{"ts":{}}' -# test:channel.{"ts":{}} 2012-08-28 22:10:31.192547 0 UDF INVALID -# Hal$ caget -a 'test:channel' -# test:channel 0 UDF INVALID -# +=head3 TimeStamp Filter C<"ts"> + +This filter is used to set the timestamp of the (first) value fetched through +the channel to the connection time, rather than the time the record last +processed which could have been days or even weeks ago for some records, or set +to the EPICS epoch if the record has never processed. + +=head4 Parameters + +None, use an empty pair of braces. + +=head4 Example + + Hal$ caget -a 'test:channel.{"ts":{}}' + test:channel.{"ts":{}} 2012-08-28 22:10:31.192547 0 UDF INVALID + Hal$ caget -a 'test:channel' + test:channel 0 UDF INVALID + +=cut registrar(dbndInitialize) -#=head3 Deadband Filter C<"dbnd"> -# -# This filter implements a channel-specific monitor deadband, which is applied -# after any deadbands implemented by the record itself (it can only drop updates -# that the unfiltered channel generates, never add additional updates). -# -# The deadband can be specified as an absolute value change, or as a relative -# percentage. -# -#=head4 Parameters -# -#=over 4 -# -#=item Deadband C<"d"> -# -# The size of the deadband to use. -# Relative deadband values are given as a numeric percentage, but without any -# trailing percent character. -# -#=item Mode C<"m"> (optional) -# -# A string (enclosed in double-quotes C<">), which should contain either -# C or C. -# The default mode is absolute if no mode parameter is included. -# -#=back -# -#=head4 Example -# -# Hal$ camonitor 'test:channel' -# test:channel 2012-09-01 22:10:19.600595 1 LOLO MAJOR -# test:channel 2012-09-01 22:10:20.600661 2 LOLO MAJOR -# test:channel 2012-09-01 22:10:21.600819 3 LOW MINOR -# test:channel 2012-09-01 22:10:22.600905 4 LOW MINOR -# test:channel 2012-09-01 22:10:23.601023 5 -# test:channel 2012-09-01 22:10:24.601136 6 HIGH MINOR -# ^C -# Hal$ camonitor 'test:channel.{"dbnd":{"d":1.5}}' -# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:49.613341 1 LOLO MAJOR -# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:51.613615 3 LOW MINOR -# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:53.613804 5 -# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:55.614074 7 HIGH MINOR -# test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:57.614305 9 HIHI MAJOR -# ^C -# +=head3 Deadband Filter C<"dbnd"> + +This filter implements a channel-specific monitor deadband, which is applied +after any deadbands implemented by the record itself (it can only drop updates +that the unfiltered channel generates, never add additional updates). + +The deadband can be specified as an absolute value change, or as a relative +percentage. + +=head4 Parameters + +=over 4 + +=item Deadband C<"d"> + +The size of the deadband to use. +Relative deadband values are given as a numeric percentage, but without any +trailing percent character. + +=item Mode C<"m"> (optional) + +A string (enclosed in double-quotes C<">), which should contain either +C or C. +The default mode is absolute if no mode parameter is included. + +=back + +=head4 Example + + Hal$ camonitor 'test:channel' + test:channel 2012-09-01 22:10:19.600595 1 LOLO MAJOR + test:channel 2012-09-01 22:10:20.600661 2 LOLO MAJOR + test:channel 2012-09-01 22:10:21.600819 3 LOW MINOR + test:channel 2012-09-01 22:10:22.600905 4 LOW MINOR + test:channel 2012-09-01 22:10:23.601023 5 + test:channel 2012-09-01 22:10:24.601136 6 HIGH MINOR + ^C + Hal$ camonitor 'test:channel.{"dbnd":{"d":1.5}}' + test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:49.613341 1 LOLO MAJOR + test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:51.613615 3 LOW MINOR + test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:53.613804 5 + test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:55.614074 7 HIGH MINOR + test:channel.{"dbnd":{"d":1.5}} 2012-09-01 22:11:57.614305 9 HIHI MAJOR + ^C + +=cut registrar(arrInitialize) -#=head3 Array Filter C<"arr"> -# -# ... -# +=head3 Array Filter C<"arr"> + +... + +=cut registrar(syncInitialize) -#=head3 Synchronize Filter C<"sync"> -# -# ... -# +=head3 Synchronize Filter C<"sync"> +... + +=cut diff --git a/src/std/rec/aiRecord.dbd b/src/std/rec/aiRecord.dbd index 7b54fe89d..cc5171cf4 100644 --- a/src/std/rec/aiRecord.dbd +++ b/src/std/rec/aiRecord.dbd @@ -7,149 +7,151 @@ # in file LICENSE that is included with this distribution. #************************************************************************* recordtype(ai) { - #=head1 Analog Input (ai) - # - # This record type is normally used to obtain an analog value from - # a hardware input and convert it to engineering units. The record - # supports linear and break-point conversion to engineering units, - # smoothing, alarm limits, alarm filtering, and graphics and control - # limits. - # - #=head2 Parameter Fields - # - # The record fields are described below grouped by functionality. - # - #=head3 Input Specification - # - # These fields control where (if anywhere) the record reads data from - # when it is processed: - # - #=fields INP, DTYP - # - # I - # - #=head3 Units Conversion - # - # These fields control how the raw input value gets converted into - # engineering units: - # - #=fields RVAL, ROFF, ASLO, AOFF, LINR, ESLO, EOFF, EGUL, EGUF - # - # These fields are not used if the device support layer reads its - # value in engineering units and puts it directly into the VAL field. - # - # If the device support sets the RVAL field, the LINR field controls - # how this gets converted into engineering units and placed in the - # VAL field as follows: - # - #=over 4 - # - #=item 1. RVAL is converted to a double and ROFF is added to it - # - #=item 2. If ASLO is non-zero the value is multiplied by ASLO - # - #=item 3. AOFF is added - # - #=item 4. If LINR is C the units conversion is finished - # after the above steps - # - #=item 5. If LINR is C or C, the value from step 3 - # above is multiplied by ESLO and EOFF is added to complete the units - # conversion process - # - #=item 6. Any other value for LINR selects a particular breakpoint - # table to be used on the value from step 3 above - # - #=back - # - # The distinction between the C and C settings for the - # LINR field are in how the conversion parameters are calculated: - # - #=over 4 - # - #=item * - # With C conversion the user must set EGUL and EGUF to the - # lowest and highest possible engineering units values respectively - # that can be converted by the hardware. The device support knows - # the range of the raw data and calculates ESLO and EOFF from them. - # - #=item * - # C conversion requires the user to calculate the appropriate - # scaling and offset factors and put them directly in ESLO and EOFF. - # - #=back - # - #=head3 Smoothing Filter - # - # This filter is usually only used if the device support sets the RVAL - # field and the Units Conversion process is used. Device support that - # directly sets the VAL field may implement the filter if desired. - # - # The filter is controlled with a single parameter field: - # - #=fields SMOO - # - # The SMOO field should be set to a number between 0 and 1. If set to - # zero the filter is not used (no smoothing), while if set to one the - # result is infinite smoothing (the VAL field will never change). The - # calculation performed is: - # - # VAL = VAL * SMOO + (1 - SMOO) * New Data - # - # where C was the result from the Units Conversion above. - # This implements a first-order infinite impulse response (IIR) - # digital filter with z-plane pole at SMOO. The equivalent - # continuous-time filter time constant E is given by - # - #=over 4 - # - # E = ET / ln(SMOO) - # - #=back - # - # where T is the time between record processing. - # - #=head3 Undefined Check - # - # If after applying the smoothing filter the VAL field contains a NaN - # (Not-a-Number) value, the UDF field is set to indicate that the - # record value is undefined, which triggers a C with - # severity C. - # - #=fields UDF - # - #=head3 Operator Display Parameters - # - # These parameters are used to present meaningful data to the operator. - # - #=over 4 - # - #=item * - # DESC is a string that is usually used to briefly describe the record. - # - #=item * - # EGU is a string of up to 16 characters giving the units that the - # analog input measures. - # - #=item * - # The HOPR and LOPR fields set the upper and lower display limits for - # the VAL, HIHI, HIGH, LOW, and LOLO fields. - # - #=item * - # The PREC field determines the floating point precision with which - # to display VAL. - # - #=back - # - #=fields DESC, EGU, HOPR, LOPR, PREC - # - #=head3 Alarm Parameters - # - # ... - # - #=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, AFTC - # - #=cut + +=head1 Analog Input (ai) + +This record type is normally used to obtain an analog value from +a hardware input and convert it to engineering units. The record +supports linear and break-point conversion to engineering units, +smoothing, alarm limits, alarm filtering, and graphics and control +limits. + +=head2 Parameter Fields + +The record fields are described below grouped by functionality. + +=head3 Input Specification + +These fields control where (if anywhere) the record reads data from +when it is processed: + +=fields INP, DTYP + +I + +=head3 Units Conversion + +These fields control how the raw input value gets converted into +engineering units: + +=fields RVAL, ROFF, ASLO, AOFF, LINR, ESLO, EOFF, EGUL, EGUF + +These fields are not used if the device support layer reads its +value in engineering units and puts it directly into the VAL field. + +If the device support sets the RVAL field, the LINR field controls +how this gets converted into engineering units and placed in the +VAL field as follows: + +=over 4 + +=item 1. RVAL is converted to a double and ROFF is added to it + +=item 2. If ASLO is non-zero the value is multiplied by ASLO + +=item 3. AOFF is added + +=item 4. If LINR is C the units conversion is finished +after the above steps + +=item 5. If LINR is C or C, the value from step 3 +above is multiplied by ESLO and EOFF is added to complete the units +conversion process + +=item 6. Any other value for LINR selects a particular breakpoint +table to be used on the value from step 3 above + +=back + +The distinction between the C and C settings for the +LINR field are in how the conversion parameters are calculated: + +=over 4 + +=item * +With C conversion the user must set EGUL and EGUF to the +lowest and highest possible engineering units values respectively +that can be converted by the hardware. The device support knows +the range of the raw data and calculates ESLO and EOFF from them. + +=item * +C conversion requires the user to calculate the appropriate +scaling and offset factors and put them directly in ESLO and EOFF. + +=back + +=head3 Smoothing Filter + +This filter is usually only used if the device support sets the RVAL +field and the Units Conversion process is used. Device support that +directly sets the VAL field may implement the filter if desired. + +The filter is controlled with a single parameter field: + +=fields SMOO + +The SMOO field should be set to a number between 0 and 1. If set to +zero the filter is not used (no smoothing), while if set to one the +result is infinite smoothing (the VAL field will never change). The +calculation performed is: + + VAL = VAL * SMOO + (1 - SMOO) * New Data + +where C was the result from the Units Conversion above. +This implements a first-order infinite impulse response (IIR) +digital filter with z-plane pole at SMOO. The equivalent +continuous-time filter time constant E is given by + +=over 4 + +E = ET / ln(SMOO) + +=back + +where T is the time between record processing. + +=head3 Undefined Check + +If after applying the smoothing filter the VAL field contains a NaN +(Not-a-Number) value, the UDF field is set to indicate that the +record value is undefined, which triggers a C with +severity C. + +=fields UDF + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. + +=over 4 + +=item * +DESC is a string that is usually used to briefly describe the record. + +=item * +EGU is a string of up to 16 characters giving the units that the +analog input measures. + +=item * +The HOPR and LOPR fields set the upper and lower display limits for +the VAL, HIHI, HIGH, LOW, and LOLO fields. + +=item * +The PREC field determines the floating point precision with which +to display VAL. + +=back + +=fields DESC, EGU, HOPR, LOPR, PREC + +=head3 Alarm Parameters + +... + +=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, AFTC + +=cut + include "dbCommon.dbd" field(VAL,DBF_DOUBLE) { prompt("Current EGU Value") diff --git a/src/std/rec/compressRecord.dbd b/src/std/rec/compressRecord.dbd index 96190331c..54d1625e5 100644 --- a/src/std/rec/compressRecord.dbd +++ b/src/std/rec/compressRecord.dbd @@ -3,8 +3,7 @@ # National Laboratory. # Copyright (c) 2002 The Regents of the University of California, as # Operator of Los Alamos National Laboratory. -# EPICS BASE Versions 3.13.7 -# and higher are distributed subject to a Software License Agreement found +# EPICS BASE is distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* menu(compressALG) { @@ -16,11 +15,13 @@ menu(compressALG) { choice(compressALG_N_to_1_Median,"N to 1 Median") } recordtype(compress) { - #=head1 Compress Record (compress) - # - #=fields VAL - # - #=cut + +=head1 Compress Record (compress) + +=fields VAL + +=cut + include "dbCommon.dbd" field(VAL,DBF_NOACCESS) { prompt("Value")