NAME

DESCRIPTION

For versions of spec compiled for the EPICS environment (as used at the Advanced Photon Source and elsewhere), the three functions epics_get(), epics_put() and epics_par() provide generic channel access to EPICS process variables.

The EPICS version of spec also includes built-in support for the standard EPICS motor, scaler, MCA and generic-serial records which allows access to EPICS motors, scalers, MCAs and serial devices through spec's hardware independent functions and commands.

FUNCTIONS

In the epics_get() and epics_put() functions below, note the special considerations given when the process variable is a byte array (EPICS type DBF_CHAR). The special treatment is given as these arrays are often used to hold strings since the maximum length of the EPICS DBF_STRING type is only 40 bytes. Many EPICS records use arrays of DBF_CHAR where longer strings are needed. (The special treatment for DBF_CHAR arrays is as of spec release 5.08.06-5.)

Note also that prior to EPICS 3.14, the maximum size of a data transfer was 16,384 bytes. With release 3.14 and later, one can set the EPICS_CA_MAX_ARRAY_BYTES environment variable to larger values to overcome that limit.

The following functions for generic EPICS access are available:

epics_get(ca_name [, type] [, count])

Returns the result of a channel-access get of the process variable ca_name, as in print epics_get("ioc:m1.VAL"). By default, the native data type of the process variable will be retrieved over channel access. However, a different data type can be specified using the optional second argument. Possible types are "char", "short", "long", "float", "double", "enum" and "string". For DBF_ENUM data types, the string value of the process variable is returned, unless another type is specified. For array types, the entire array is retrieved and returned, unless the optional argument count specifies fewer elements (as of spec release 5.00.04).
 When requesting "string" for types other than DBF_CHAR, arrays will be returned as a spec string data array consisting of 40-byte rows, with as many rows as elements in the EPICS array. Each row will contain an ASCII representation of the corresponding value, with the rest of the row padded with null bytes. For DBF_CHAR data, the return value will be converted to an ordinary string (as of release 5.10.01-8). Note, any bytes following a null byte in the DBF_CHAR array will be lost.
 If a "monitor" has been set for the process variable using the "monitor_set" option below, the returned result will be the most recent value as set by the monitor call back. Otherwise (or if there has been no monitor call back), spec will access the process variable value using the standard channel access ca_array_get().

epics_put(ca_name, value [, wait_time])

Does a channel-access put of value, which can be either a string or a number, to the process variable ca_name. If the optional wait_time argument is set, spec will wait for a channel-access "callback" to indicate the value has been sent. spec will wait up to the specified number of seconds for that response. Such a feature might come in handy if the channel-access put is to start an acquisition device and one wants to insure the device is started before continuing.
 If the process variable is an array of a DBF_CHAR type, any non-array value, whether number or string, will be sent via channel access as a string, filling as many elements of the array as the string is long.

epics_par(ca_name, what)

Returns parameters associated with the process variable ca_name, according to the value of the string what, which may have the following values:

"connect"

Queues the call to make the initial connection for the designated process variable, but doesn't force a network packet to be sent. If many process variables are to be accessed from user level, it will be more efficient in terms of network access to use this "connect" option for each, before the individual epics_get() and epics_put() calls. (Available as of spec release 5.08.01-4.)

"count"

Returns the element count associated with ca_name.

"host"

Returns the host name for ca_name (EPICS 3.12 and above).

"monitor_set"

Creates a "monitor" for the indicated process variable.

"monitor_check"

If the indicated process variable has a monitor, returns the value 1 if the value of the process variable has changed since last read with epics_get(). Returns -1 if no monitor has been created and for other EPICS errors. Otherwise returns zero.

"monitor_clear"

Removes the monitor for the indicated process variable.

"read_access"

Returns nonzero if ca_name has read access (EPICS 3.12 and above).

"timeout"

Returns the value spec uses for the ca_pend_io() time-out parameter.

"type"

Returns a string (such as "string", "double", "short", etc.) indicating the data type of ca_name.

"write_access"

Returns nonzero if ca_name has write access (EPICS 3.12 and above).

epics_par(ca_name, what, value)

Sets parameters associated with the process variable ca_name, according to the value of the string what, which may have the following values:

"timeout"

Sets the value spec uses for the ca_pend_io() time-out parameter.

ERRORS

When linked with the EPICS channel-access libraries, spec creates two built-in global variables, EPICS_ERR and EPICS_ERR_MSG (as of spec release 5.08.01-1). If one of the above functions results in an error generated by the channel-access calls, the value of the error will be assigned to EPICS_ERR and the corresponding message, as provided by the ca_message() function, will be assigned to EPICS_ERR_MSG. In addition, for certain errors at the spec level, including errors associated with failure to connect to an EPICS server, will result in a -1 assigned to EPICS_ERR and, in some cases, a message assigned to EPICS_ERR_MSG.

MONITORS

To avoid excess network traffic, monitors can be created for selected process variables. With a monitor, epics_get() calls will return a cached value of the process variable, rather than calling out over the network to fetch a value. The EPICS database will update spec when the value of the process variable changes. The "monitor_check" option to epics_par() allows for testing whether the value has changed since the last time the process variable was read with epics_get().

Note, a reconfig (or config) call reinitializes the hardware connections and clears all monitors. Use the config_mac feature to set up macros to have monitors automatically created when hardware is initialized or reinitialized.

DEFAULT TIMEOUT

The default timeout for the channel access calls is 0.5 seconds. The timeout for individual process variables can be changed using the epics_par() function, as described above. It also possible to change the default timeout for all newly created connections using the spec_par() function with the "epics_timeout" option. (See the spec_par help file.) The parameters set with spec_par() are saved in the user's state file, so will be restored when spec is restarted, except, of course when starting fresh (with the -f flag).

USING EPICS SCALERS

spec supports counter/timers using the standard EPICS scaler record. In addition, spec allows configuration of arbitrary process variables as counters. For process-variable counters, the value of the PV will be fetched as a DBF_DOUBLE and assigned to the corresponding element of the built-in scaler array S[] when the spec getcounts command is executed.

EPICS counter-related controllers are configured on Devices screen of the configuration editor as follows: