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:
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 .
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 {}
after the dot expressed as a JSON (JavaScript Object Notation) 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 "
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 {}
.
Given a record called test:channel
the following would apply a filter f
to the VAL field of that record, giving the filter two numeric parameters named lo
and hi
:
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 ' ... '
when typing it as an argument to a Unix shell command.
"ts"
This filter is used to set the timestamp of the value fetched through the channel to the time the value was fetched (or an update was sent), 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.
None, use an empty pair of braces.
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 <undefined> 0 UDF INVALID
"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.
"abs"
/"rel"
(shorthand)Mode and deadband can be specified in one definition (shorthand). The desired mode is given as parameter name ("abs"
or "rel"
), with the numeric size of the deadband (absolute value or numeric percentage) as value.
"d"
The size of the deadband to use. Relative deadband values are given as a numeric percentage, but without any trailing percent character.
"m"
(optional)A string (enclosed in double-quotes "
), which should contain either abs
or rel
. The default mode is abs
if no mode parameter is included.
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":{"abs":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
"arr"
This filter is used to retrieve parts of an array (subarrays and strided subarrays).
Note: Negative index numbers address from the end of the array, with -1
being the last element.
[s:i:e]
(shorthand)The familiar [s:i:e]
notation with square brackets can be used (shorthand).
"s"
Index of the first original array element to retrieve.
"i"
Index increment between retrieved elements of the original array; must be a positive number.
"e"
Index of the last original array element to retrieve.
Defaults (when parameters are omitted) are: s=0
(first element), i=1
(fetch all elements), e=-1
(last element)
Hal$ caget test:channel 'test:channel.{"arr":{"s":2,"i":2,"e":8}}' test:channel.[3:5] test:channel.[3:2:-3]
test:channel 10 0 1 2 3 4 5 6 7 8 9
test:channel.{"arr":{"s":2,"i":2,"e":8}} 4 2 4 6 8
test:channel.[3:5] 3 3 4 5
test:channel.[3:2:-3] 3 3 5 7
"sync"
This filter is used to dynamically enable or disable monitors according to a condition and a state variable declared by the IOC.
State variables have a boolean value and can be set by a binary output record, an iocsh command or by other software running in the IOC calling dbStateSet()
.
Mode and state can be specified in one definition (shorthand). The desired mode is given as parameter name ("before"
/ "first"
/ "while"
/ "last"
/ "after"
/ "unless"
), with the state name (enclosed in double quotes "
) as value.
"m"
A single word from the list below, enclosed in double quotes "
. This controls how the state value should affect the monitor stream.
"before"
— only the last value received before the state changes from false to true is forwarded to the client."first"
— only the first value received after the state changes from true to false is forwarded to the client."while"
— values are forwarded to the client as long as the state is true."last"
— only the last value received before the state changes from true to false is forwarded to the client."after"
— only the first value received after the state changes from true to false is forwarded to the client."unless"
— values are forwarded to the client as long as the state is false."s"
The name of a state variable, enclosed in double quotes "
.
Assuming there is a system state called "blue", that is being controlled by some other facility such as a timing system, updates could be restricted to periods only when "blue" is true by using
Hal$ camonitor 'test:channel' 'test:channel.{"while":"blue"}'
...