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

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 variable ca_name, as in print epics_get("tmm:m1.VAL"). By default, the native data type of the variable is specified when retrieving the value over channel access. However, you can specify a different data type in the optional second argument. Possible types are "char", "short", "long", "float", "double", "enum" and "string". For ENUM data types, the string value of the variable is returned, unless another type is specified. If the variable is an array type, by default, the entire array is retrieved and returned. The optional argument count limits the number of elements returned (as of spec release 5.00.04).

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 channel access 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.

epics_par(ca_name, what)

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

"type"

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

"count"

Returns the element count associated with ca_name.

"timeout"

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

"host"

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

"read_access"

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

"write_access"

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

"monitor_set"

Creates a "monitor" for the indicated channel access variable.

"monitor_check"

If the indicated channel access variable has a monitor, returns the value 1 if the value of the 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 channel access variable.

epics_par(ca_name, what, value)

Sets parameters associated with the channel access 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.

MONITORS

To avoid excess network traffic, monitors can be created for selected channel access variables. With a monitor, epics_get() calls will return a cached value of the variable, rather than calling out over the network to fetch a value. The EPICS database will update spec when the value of the variable changes. The "monitor_check" option to epics_par() allows for testing whether the value has changed since the last time the 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 MOTORS

spec supports motors under EPICS using the standard EPICS motor record. spec provides two flavors of support. With the first (the EPICS_M1 motors), spec takes all the motor parameters, such as step size, velocity, acceleration, etc., from spec's own configuration file. With the second (the EPICS_M2 motors), the parameters are taken from the EPICS data base, and the parameters in the spec configuration file are ignored. Most sites configure the spec motors as EPICS_M2 so that spec will not cause conflicts with other EPICS utilities.

Note, EPICS_M1 motors write all the parameters configured in the spec configuration file to the EPICS data base when spec reads its configuration file, ignoring values currently set in the EPICS data base. However, spec will accept the position of the motor when first connecting to the data base, if the motor position is nonzero. If the motor position is zero and spec's settings file contains a nonzero position, spec will ask which position should be used.

For EPICS_M2 motors, spec will only change motor parameters in the EPICS data base with the motor_par() function. (See the motors help file.)

Each set of motors with the same EPICS prefix should be entered on a separate line on the devices screen of the configuration editor:

MOTORS     DEVICE   ADDR  <>MODE  NUM                     <>TYPE
    YES      ioc1:                  44     EPICS Motor Controller
    YES      ioc2:                  12     EPICS Motor Controller


Number: <>Controller  0:EPICS_M2 1:EPICS_M2 2:EPICS_M2 3:EPICS_M2
Unit/Channel                 0/1        0/2        0/3        0/4
Name                   Two Theta      Theta        Chi        Phi
Mnemonic                     tth         th        chi        phi


The APS EPICS motor naming convention appends m1, m2, etc., to the prefix defined on the motor controller screen.

An alternative naming scheme can be selected by entering a string value for the optional "Generic Parameter 1" on the second optional motor parameter screen. That string value will be appended to the prefix string defined on the motor controller screen.

With the following configuration:

MOTORS     DEVICE   ADDR  <>MODE  NUM                     <>TYPE
    YES X04SA-ES2-                  44     EPICS Motor Controller


Number: <>Controller  0:EPICS_M2 1:EPICS_M2 2:EPICS_M2 3:EPICS_M2
Unit/Channel                 0/1        0/2        0/3        0/4
Name                   Two Theta      Theta        Chi        Phi
Mnemonic                     tth         th        chi        phi
...
Generic parameter 1      SAM:TTH     SAM:TH    SAM:CHI    SAM:PHI