The Channel Access control-system support is bundled with the standard
distribution of the Cassandra PV Archiver server.
It provides support for process variables that can be accessed through the
Channel Access protocol, which is the protocol typically used by
control systems that are based on
EPICS.
The Channel Access control-system support is identified by the ID
channel_access.
This control-system support is based on the EPICS Jackie library, which is internally used for implementing the Channel Access protocol. This way, the control-system support works on all platforms without having dependencies on any platform-specific libraries.
This appendix describes how the control-system support is configured (see Section 1, “Configuration”), how the sample decimation is implemented (see Section 2, “Decimated samples”), and how it stores samples in the database (see Section 3, “CQL table layout”).
The Channel Access control-system support offers a number of configuration options that can be specified for each channel. The same options can also be specified in the server’s configuration file (see Chapter III, Cassandra PV Archiver server, Section 3, “Server configuration”). When specified in the server’s configuration file, the options serve as defaults that are used when an option is not specified for a specific channel that is managed by the respective server.
When specified in the server’s configuration file, the options must be
specified in the controlSystem →
channelAccess section of the file or the prefix
controlSystem.channelAccess must be added to the
option name.
When specified for a channel, the option names are used without any
prefix being added.
Option names are case-sensitive.
The clockSource option specifies which time stamp
is used when archiving samples.
When set to local, the time of the archiving
server’s system clock is used.
When set to origin, the time that is sent by the
Channel Access server (together with the sample’s value) is used and
the
maxClockSkew option
controls when a sample is discarded without being archived.
When set to prefer_origin (the default), the
original time (as sent by the Channel Access server) is preferred.
However, when the difference between the time specified by the
archiving server’s system clock and the original time is greater than
the limit specified by the
maxClockSkew option,
the time from the local system clock is used instead.
The prefer_origin setting is used as the default
because it provides a reasonable balance between preferring a
time-stamp that is close to the point in time when the value was
actually measured and avoiding the use of completely bogus time-stamps
(or discarding samples) when a device server’s clock is not properly
synchronized.
The enablingChannel option specifies the name of a
channel that controls whether archiving is enabled.
This option is useful when a channel should only be archived when
certain conditions are met (e.g. the facility is in a certain state of
operation).
By default, the enablingChannel option is not set,
meaning that a channel is always archived (unless it has explicitly
been disabled in the configuration).
The channel name specified as the value of the
enablingChannel option can be any valid Channel
Access channel.
That channel does not have to be present in the Cassandra PV
Archiver’s configuration.
When the enabling channel is not connected, archiving is disabled.
When the enabling channel is connected, archiving is enabled depending
on the enabling channel’s value.
When the enabling channel’s value is of an integer type, the target
channel is enabled if the enabling channel’s value is non-zero.
When the enabling channel’s value is of a floating-point type, the
target channel is enabled when the enabling channel’s value is neither
zero nor not-a-number.
When the enabling channel’s value is of a string type, the target
channel is enabled when the enabling channel’s value is neither the
empty string, nor “0”, “false”, “no”, or “off”.
Leading and trailing white-space is ignored for this comparison and
the comparison is not case sensitive.
If this option is not set or set to the empty string (the default), archiving is always enabled. If a channel has been disabled in the archiving configuration, this option does not have any effect and archiving always stays disabled, regardless of the enabling channel’s connection state and value.
The maxClockSkew option specifies the maximum
difference that is allowed between the time sent by the Channel Access
server (together with the sample’s value) and the local system clock
of the archiving server.
The specified value must be a finite, non-negative floating point
number that specifies the maximum clock skew in seconds. The default
value is 30 seconds.
The effects of this option depend on the
clockSource option.
When the clockSource option is set to “local”, this
option does not have any effects.
When the clockSource option is set to
“prefer_origin”, this option controls which clock source is selected.
When this option is set to zero or the difference between the time
specified by the Channel Access server and the time specified by the
archiving server’s system clock is less than the limit specified by
this option, the time provided by the Channel Access server is used as
the sample’s time stamp.
When this option is non-zero and the difference between the time
specified by the Channel Access server and the time specified by the
archiving server’s system clock is greater than the limit specified by
this option, the time provided by the archiving server’s system clock
is used as the sample’s time stamp.
When the clockSource option is set to “origin”,
this option controls when a sample is discarded.
When this option is set to zero or the difference between the time
specified by the Channel Access server and the time specified by the
archiving server’s system clock is less than the limit specified by
this option, the sample is archived and the time provided by the
Channel Access server is used as the sample’s time stamp.
When this option is non-zero and the difference between the time
specified by the Channel Access server and the time specified by the
archiving server’s system clock is greater than the limit specified by
this option, the sample is discarded without being archived.
The maxUpdatePeriod option specifies the longest
period that may pass between writing two samples.
The specified value must be a finite, non-negative floating point
number that specifies the maximum period (specified in seconds)
between writing two samples.
The default value is zero, which means that a sample is only written
when the Channel Access server sends an update.
By using this option, one can ensure that a new sample repeating the
value of the previous sample is written when no new sample is received
from the Channel Access server within the specified period of time.
Typically, it makes sense to combine this option with the
writeSampleWhenDisabled
and
writeSampleWhenDisconnected
options.
Due to processing delays, the actual period between writing the two
samples might be slightly greater than the specified period.
For obvious reasons, the time stamp used when writing a sample without
having received an update from the Channel Access server is always
generated using the archiving server’s system clock, regardless of the
clockSource option.
Mixing samples that use the archiving server’s system clock for
generating the time-stamp with samples that use the time stamp
provided by the Channel Access server can have the effect that
updates that are received from the Channel Access server are actually
not archived because a previously written sample has a (slightly)
greater time stamp and the newer sample is therefore discarded (the
Cassandra PV Archiver server never writes samples that have a time
stamp less than or equal to a previously archive sample).
For this reason, it is recommended to set the
clockSource option to local
when setting this option to a non-zero value.
The metaDataMonitorMask option specifies the
monitor mask that is used for monitoring a channel for meta-data
(engineering units, alarm and display limits, etc.) changes.
The bit of the monitor mask is set when the corresponding token (one
of “value”, “archive”, “alarm”, and “property”) is present.
Tokens can be separated by commas, pipes, or spaces.
Please refer to the
Channel Access Reference Manual
for details about the meaning of this mask bits.
The event mask used when monitoring a channel for value changes is
specified separately through the
monitorMask option.
The default value for this option is “property”, which should
typically have the effect that an update is sent by the server when
one of the meta-data properties changes.
The minUpdatePeriod option specifies the shortest
period that must pass between writing two samples.
The specified value must be a finite, non-negative floating point
number that specifies the minimum period (in seconds) between writing
two samples.
The default value is zero, which means that a sample is always written
when the Channel Access server sends an update, regardless of the time
that has passed since receiving the last update.
By using this option, one can limit the rate at which samples are written. This is useful when a Channel Access server sends updates at a much higher rate than they should be archived. However, for very high update rates, samples might still be lost if the system cannot process them as quickly as they arrive.
The monitorMask option specifies the
monitor mask that is used for monitoring a channel for value and alarm
state changes.
The bit of the monitor mask is set when the corresponding token (one
of “value”, “archive”, “alarm”, and “property”) is present.
Tokens can be separated by commas, pipes, or spaces.
Please refer to the
Channel Access Reference Manual
for details about the meaning of this mask bits.
The event mask used when monitoring a channel for value changes is
specified separately through the
monitorMask option.
The default value for this option is “archive|alarm”.
When not using the
minUpdatePeriod option,
a sample is written for each update that is received from the Channel
Access server.
For this reason, the monitor mask has an effect on the rate at which
samples are written.
Most Channel Access servers send updates at a lower rate when setting
the “archive” instead of the “value” bit, which is why this bit is
used in the default value for this option.
The “alarm” bit, on the other hand, triggers an update each time the
channel’s alarm state changes.
The writeSampleWhenDisabled option allows for
writing a sample when a channel is disabled.
This option is enabled by setting it to “true”.
By default, it is set to “false”, which disables this option.
Typically, it makes sense to combine this option with the
maxUpdatePeriod
and
writeSampleWhenDisconnected
options.
When this option is enabled, a special sample acting as a marker for the disabled state is written to the archive when a channel is disabled. A channel can be disabled in the archive configuration or through an enabling channel. By writing such a marker sample, one can tell from the archived data whether a value simply did not change for an extended period of time or no samples where written because archiving was disabled.
When writing a marker sample to indicate that archiving is disabled,
the time from the archiving server’s system clock is used, regardless
of the
clockSource option.
Mixing samples that use the archiving server’s system clock for
generating the time-stamp with samples that use the time stamp
provided by the Channel Access server can have the effect that
updates that are received from the Channel Access server are actually
not archived because a previously written sample has a (slightly)
greater time stamp and the newer sample is therefore discarded (the
Cassandra PV Archiver server never writes samples that have a time
stamp less than or equal to a previously archive sample).
For this reason, it is recommended to set the
clockSource option to local
when enabling this option.
The writeSampleWhenDisconnected option allows for
writing a sample when a channel is disconnected.
This option is enabled by setting it to “true”.
By default, it is set to “false”, which disables this option.
When this option is enabled, a special sample acting as a marker for
the disconnected state is written to the archive when a channel is
disconnected.
By writing such a marker sample, one can tell from the archived data
whether a value simply did not change for an extended period of time
or no samples where written because the channel was not connected.
Typically, it makes sense to combine this option with the
maxUpdatePeriod
and
writeSampleWhenDisabled
options.
When writing a marker sample to indicate that the channel is
disconnected, the time from the archiving server’s system clock is
used, regardless of the
clockSource option.
Mixing samples that use the archiving server’s system clock for
generating the time-stamp with samples that use the time stamp
provided by the Channel Access server can have the effect that
updates that are received from the Channel Access server are actually
not archived because a previously written sample has a (slightly)
greater time stamp and the newer sample is therefore discarded (the
Cassandra PV Archiver server never writes samples that have a time
stamp less than or equal to a previously archive sample).
For this reason, it is recommended to set the
clockSource option to local
when enabling this option.