Appendix D. Channel Access control-system support

Table of Contents
1. Configuration
1.1. Clock source option
1.2. Enabling channel option
1.3. Maximum clock skew option
1.4. Maximum update period option
1.5. Meta-data monitor mask option
1.6. Minimum update period option
1.7. Monitor mask option
1.8. Write sample when disabled option
1.9. Write sample when disconnected option
2. Decimated samples
2.1. Aggregation
2.2. Decimation
3. CQL table layout

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” ).

1. Configuration

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 controlSystemchannelAccess 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.

1.1. Clock source option

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.

1.2. Enabling channel option

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.

1.3. Maximum clock skew option

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.

1.4. Maximum update period option

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.

1.5. Meta-data monitor mask option

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.

1.6. Minimum update period option

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.

1.7. Monitor mask option

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.

1.8. Write sample when disabled option

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.

1.9. Write sample when disconnected 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.