DESCRIPTION

TANGO is an object-oriented distributed control system using CORBA, developed as a collaborative effort among the Alba, Desy, Elettra, ESRF and Soleil institutes. See http://www.tango-controls.org/ for complete details. The support built into spec requires the C-binding library for TANGO.

In addition to generic access to TANGO properties via the tango_io() function and TANGO attributes with the tango_put() and tango_get() functions, spec also supports the TANGO GPIB server as a standard GPIB interface.

PROPERTIES

tango_io(dev, "?")

Lists the command properties for dev in a concise format, showing the input and output data types for each available command.

tango_io(dev, "??")

Lists the command properties for dev in a more verbose format, showing not only the input and output data types, but also the command description, as supplied by the TANGO server.

tango_io(dev, cmd [, argin [, argout])

Allows general access to TANGO devices. If cmd returns a scalar, the argout argument is optional. If present, the return value for cmd will be placed there and tango_io() will return zero on success. If absent, tango_io() will return the value for cmd. If cmd returns an array, the argout array argument is required. On success, tango_io() returns the number of elements in the array.

tango_io(dev, "timeout")

Returns the current connection timeout for dev in seconds.

tango_io(dev, "timeout", sec)

Sets the connection timeout for dev in seconds.

tango_io(dev, "source")

Returns the data source for dev. A value of 0 indicates data is read directly from the device. A value of 1 means data is read from the polling cache. A value of 2 indicates data is read from the cache or the device.

tango_io(dev, "source", value)

Sets the data source for dev. Allowed values are 0, 1 and 2, with meanings as described above.

ATTRIBUTES

tango_get(dev, "?") or tango_put(dev, "?")

Lists the attributes, the read-write permissions and data type for dev in a concise format.

tango_get(dev, "??") or tango_put(dev, "??")

Lists the attributes, the read-write permissions, data type and command description for dev.

tango_get(dev, "?", attr)

Displays elements of the attribute information structure for the selected attribute.

tango_get(dev, "?", attr, info)

Fills the associative array info with the elements of the attribute information structure for the selected attribute. Elements are indexed as shown:

info["data_format"]	Scalar, spectrum or image
info["data_name"]	Data type as a string
info["data_type"]	Data type code number
info["description"]	Description text
info["disp_level"]	Operator or expert
info["display_unit"]	Conversion factor to GUI display unit
info["format"]	Format specification string for GUI display
info["label"]	GUI label
info["max_alarm"]	Max value, checked when reading
info["max_dim_x"]	Max data size in X
info["max_dim_y"]	Max data size in Y
info["max_value"]	Max value, checked when writing
info["min_alarm"]	Min value, checked when reading
info["min_value"]	Min value, checked when writing
info["name"]	Attribute name
info["standard_unit"]	Conversion factor to MKS units
info["unit"]	Unit string
info["writable"]	Read, write, read_write or read_with_write
info["writable_attr_name"]	Needed for read_with_write

In addition, the function returns an associative array containing the information.

tango_get(dev, "timeout") or tango_put(dev, "timeout")

Returns the current connection timeout for dev in seconds.

tango_get(dev, "timeout", sec) or tango_put(dev, "timeout", sec)

Sets the connection timeout for dev in seconds. Returns -1 on error, otherwise returns the new timeout value.

tango_get(dev, attr [, argout ] [, extras])

Reads one device attribute. If the attribute is a SPECTRUM or IMAGE type, then the argout argument is needed and is the name of an associative or data array that will receive the attribute data.

For SCALAR data types, the argout argument is optional. If present, argout will be assigned the value. If absent, the tango_get() call will return the value. With the optional argout argument, barring other errors, the return value of tango_get() will be zero unless the data quality is INVALID, in which case the return value is 1. Without the optional argout argument, if the data quality is INVALID the return value will be the string "invalid".

For SPECTRUM and IMAGE data types, the return value will be the number of array elements returned and the string "invalid" if the data quality is INVALID.

If there is a TANGO error, the function returns -1, with the TANGO_ERR global variable set to the error message.

If the optional argument extras is included, it must be an associative array. The elements of the extras array will be assigned attribute data elements indexed as follows:

extras["data_name"]	String name of data type
extras["data_type"]	Data scalar-type code
extras["dim_x"]	Data dimension for X
extras["dim_y"]	Data dimension for Y
extras["name"]	Attribute name
extras["quality"]	Data quality factor
extras["time_stamp"]	Time stamp

For scalar data "dim_y" is zero. The quality factor values are as follows:

0	VALID
1	INVALID
2	ALARM
3	CHANGING
4	WARNING

The "time_stamp" element contains the time in seconds and milliseconds from the UNIX epoch.

tango_get(dev, at1, argout1, at2, argout2 [, ... ]] [, extras])

Reads multiple device attributes. An argout argument must be provided for each attribute, whether scalar or array.

When reading multiple attributes, if there are no errors, the return value of tango_get() will be the number of attributes that have INVALID quality. If no attributes have INVALID quality, the return value is zero. The extras array will be needed to sort out which attributes have INVALID data.

If there is a TANGO error, the function returns -1, with the TANGO_ERR global variable set to the error message.

If present, the extras array will be two dimensional, with the first index being the attribute name and the second index as above.

tango_put(dev, attr1, argin1 [, attr2, argin2 [, ...]])

Writes one or more device attributes. Each attribute is followed by its value. Attributes can be scalar or arrays.

On success, the return value is 0.

If there is a TANGO error, the function returns -1, with the TANGO_ERR global variable set to the error message.

ERROR CONSIDERATIONS

For all the TANGO functions, spec will assign values to the built-in variables TANGO_ERR and TANGO_ERR_STACK on TANGO errors. The former is a string-type variable containing the lowest-level reason given by the TANGO library for an error or the null string if no error occurred. The variable TANGO_ERR_STACK is an associative array containing the complete error stack for commands generating an error. The elements of the stack are indexed as:

TANGO_ERR_STACK[0]["reason"]

TANGO_ERR_STACK[0]["origin"]

TANGO_ERR_STACK[0]["desc"]

TANGO_ERR_STACK[0]["severity"]

TANGO_ERR_STACK[1]["reason"]

TANGO_ERR_STACK[1]["origin"]

TANGO_ERR_STACK[1]["desc"]

TANGO_ERR_STACK[1]["severity"]

...

If there is no TANGO error the array will be empty.

If the built-in variable TANGO_ERR is set to -1 prior to the call of tango_io(), tango_put() or tango_get(), and if there is a TANGO error, the function will not print the error message but will return -1. The error message will be available in TANGO_ERR. If there is no error, TANGO_ERR will be reset to zero.

In general, TANGO errors are those conditions caught by the TANGO libraries, in contrast to the errors caught by spec and described below. One error that is caught by spec but is treated as a TANGO error is requesting an attribute or property that doesn't exist on the device. For such errors, spec sets TANGO_ERR with a message containing the device name and the requested attribute and returns -1.

A number of errors in the tango_io(), tango_get() and tango_put() calls will cause spec to print an error message and reset to command level. These are generally the type of errors where there is little point in continuing, since there is a problem with the syntax of the call.

Errors with tango_io() that cause a reset to command level include:

• need additional arguments
• bad value for "source"
• needs unsupported input type
• missing input argument
• need numeric assoc array indicies - when sending an array
• need a 1D assoc array
• needs an array input arg
• needs unsupported output type
• missing output argument
• need array for output argument
• unsupported encoded format
• unrecognized encoded magic number
• inconsistent dimensions
• impossible data type
• data length inconsistency

Errors with tango_get() that cause a reset to command level include:

• needs unsupported data type
• missing value argument
• attribute is write only
• missing argument for return
• Various errors associated with using an unassignable variable (such as a constant) or an array when a scalar is needed.
• need array for return

Errors with tango_put() that cause a reset to command level include:

• needs unsupported data type
• attribute is read only
• missing value argument
• needs scalar input value - when the ret parameter is an array.
• need numeric assoc array indicies - when sending an array for SPECTRUM or IMAGE attribute types.
• need a consistent 1D or 2D assoc array - when sending an array and some associative array elements are one dimensional and some are two dimensional.
• too many rows in input assoc array
• too many columns in input assoc array
• too many rows in input string array
• too many columns in input array
• too many rows in input array