DESCRIPTION

spec user-level VXI-11 functions connect and communicate with instruments (such as many digital oscilloscopes) that use the VXI-11 protocol. The client/server protocol uses the remote procedure call (RPC) model and is described in the document VXI 11 Revision (7/17/1995) TCP/IP Instrument Protocol Specification, available at vxibus.org. The support in spec currently consists of the device_read and device_write messages over the core channel. The abort and interrupt channels described by the protocol are not used.

The user-level access is through the functions vxi11_get(), vxi11_put() and vxi11_par().

C library RPC support is required to use spec's VXI-11 functions. RPC support was removed from the GNU glibc version 2.32 (August 2020). An alternative library, libtirpc, is available, but not always installed with default Linux platform configurations. If not linked with a library that supports RPC, spec's VXI-11 functions will display an error message. On Redhat, CentOS, Rocky, Fedora, Scientific Linux, Vine, openSUSE and similar platforms, the needed package is "libtirpc-devel". On Debian, Ubuntu, Mint and similar platforms, the package is "libtirpc-dev".

BUILT-IN FUNCTIONS

Most of the function calls require a string in the form "host" or "host:instrument" as the first argument. The host can be specified by a symbolic name or by an IP address. For most devices, there is only one instrument per IP address (or host), and it is not necessary to specify the instrument name. spec supplies the placeholder name inst0. When an instrument name is required, the syntax is as above, where a colon separates the host name from the instrument name. In the syntax description below, the symbol name will be used to represent both options.

The default timeout for the RPC clnt_call() operations is set to two seconds. It doesn't appear possible to abort a nonresponsive RPC call prior to the expiration of the timeout with a ^C. Thus, do not make the timeout too large.

The following functions are available. The syntax and behavior for the vxi11_get() and vxi11_put() functions is very similar to spec's corresponding user level I/O functions for serial, socket and gpib interfaces.

vxi11_get("name")

Reads up 8192 bytes from the device. A device will usually indicate a read is finished by setting the end bit, resulting in the transfer of less than the maximum number.

vxi11_get("name", n)

Reads up to n bytes.

vxi11_get("name", d)

Reads incoming bytes into the data array d. The size of d determines how many bytes are to be read. Sub-array syntax can be used to limit the number of bytes. The function returns the number of array elements read, or zero if the read times out. Note, no byte re-ordering is done for short- or long-integer data, and no format conversions are done for float or double data.

vxi11_get("name", mode)

If mode is the string "byte", reads and returns one unsigned binary byte. If mode is the string "short", reads two binary bytes and returns the short integer so formed. If mode is the string "long", reads four binary bytes and returns the long integer so formed. The last two modes work the same on both big-endian and little-endian platforms. On both, the incoming data is treated as big endian. If the incoming data is little endian, use "short_swap" or "long_swap".

vxi11_put(name, s)

Writes the string s to the device. Returns the number of bytes written.

vxi11_put(name, d, [cnt])

Writes the contents of the data array d to the device. By default, the entire array (or subarray, if specified) will be sent. The optional third argument cnt can be used to specify the number of array elements to send. For short and long integer arrays, the data will be sent using native byte order. The "swap" option of the array_op() function can be used to change the byte order, if necessary. No format conversions are available for float or double data. Returns the number of bytes written.

vxi11_par("show")

Lists the current open clients.

vxi11_par("info")

Returns a string that lists the current open clients.

vxi11_par("timeout" [, t])

Returns or sets the default timeout for the RPC calls. The units are seconds.

vxi11_par("name", "timeout" [, t])

Returns or sets the timeout for the named device. This value overrides the global default. The units are seconds.

vxi11_par("name", "connect")

Opens the RPC connection to the named device. Returns true if successful and false for failure. Connections are created automatically with the vxi11_get() and vxi11_put() functions. It is not necessary to use the "connect" option. However, it may be useful to check if a connection is possible. There is no difference in behavior for a connection opened using this "connect" option or one opened automatically with vxi11_get() or vxi_put().

vxi11_par("name", "close")

Closes the RPC connection to the named device and frees associated resources. Returns true whether or not the named device is open. All connections are closed during a reconfig.