Sending I/O Commands
This topic contains guidelines for sending I/O commands, including:
- Types of I/O
- Using Formatted I/O
- Using Non-Formatted I/O
Types of I/O
Once you have established a communications session with a device, you can start communicating with that device using VISA's I/O routines. VISA provides both formatted and non-formatted I/O routines.
- Formatted I/O converts mixed types of data under the control of a format string. The data is buffered, thus optimizing interface traffic.
- Non-formatted I/O sends or receives raw data to or from a device. With non-formatted I/O, no format or conversion of the data is performed. Thus, if formatted data is required, it must be done by the user.
You can choose between VISA's formatted and non-formatted I/O routines. However, you should not mix formatted I/O and non-formatted I/O in the same session. See the following sections for descriptions and code examples using formatted I/O and non-formatted I/O in VISA.
The VISA formatted I/O mechanism is similar to the C stdio mechanism. The VISA formatted I/O functions are viPrintf, viQueryf, and viScanf. Two non-buffered and non-formatted I/O functions, viRead and viWrite, synchronously transfer data. Two additional functions, viReadAsync and viWriteAsync, asynchronously transfer data. These are raw I/O functions and do not intermix with the formatted I/O functions. See Using Non-Formatted I/O for details.
Using Formatted I/O
As noted, the VISA formatted I/O functions are viPrintf, viQueryf, and viScanf.
viPrintf formats data according to the format string (writeFmt) and sends the data to a device. viPrintf sends separate arg parameters, while the viVPrintf function sends a list of parameters in params:
viPrintf(vi, writeFmt[, arg1][, arg2][, ...]);
viVPrintf(vi, writeFmt, params);
viScanf receives and converts data from a device according to the format string (readFmt). The viScanf function receives separate arg parameters, while the viVScanf function receives a list of parameters in params:
viScanf(vi, readFmt[, arg1][, arg2][, ...]);
viVScanf(vi, readFmt, params);
viQueryf formats and sends data to a device and then immediately receives and converts the response data. Hence, viQueryf is a combination of both viPrintf and viScanf functions. Similarly, viVQueryf is a combination of viVPrintf and viVScanf. viQueryf sends and receives separate arg parameters, while the viVQueryf function sends and receives a list of parameters in params:
viQueryf(vi, writeFmt, readFmt[, arg1] [, arg2][, ...]);
viVQueryf(vi, writeFmt, readFmt, params);
Formatted I/O Conversion
Formatted I/O functions convert data under the control of the format specifier. The format specifier consists of a % (percent) symbol, optional modifier, and a format code. Both readFmt and writeFmt have the form:
%[modifier]formatCode
Example: Receiving Data From a Session
The following example uses viScanf to receive data from the session specified by the vi parameter and converts the data to a string.
char data[180];
viScanf(vi, "%t", data);
Formatted I/O Buffers
The VISA software maintains both a read and write buffer for formatted I/O operations. Occasionally, you may want to control the actions of these buffers. You can modify the size of the buffer using the viSetBuf function. See viSetBuf for more information on this function.
The write buffer is maintained by the viPrintf or viQueryf (writeFmt) functions. The buffer queues characters to send to the device so that they are sent in large blocks, thus increasing performance. The write buffer automatically flushes when it sends a new line character from the format string. It may occasionally be flushed at other non-deterministic times, such as when the buffer fills.
When the write buffer flushes, it sends its contents to the device. If you set the VI_ATTR_WR_BUF_OPER_MODE attribute to VI_FLUSH_ON_ACCESS, the write buffer will also be flushed every time a viPrintf or viQueryf operation completes. See VISA Attributes for information on setting VISA attributes.
The read buffer is maintained by the viScanf and viQueryf (readFmt) functions. It queues the data received from a device until it is needed by the format string. Flushing the read buffer destroys the data in the buffer and guarantees that the next call to viScanf or viQueryf reads data directly from the device rather than data that was previously queued.
If you set the VI_ATTR_RD_BUF_OPER_MODE attribute to VI_FLUSH_ON_ACCESS, the read buffer will be flushed every time a viScanf or viQueryf operation completes. See VISA Attributes for information on setting VISA attributes.
You can manually flush the read and write buffers using the viFlush function. Flushing the read buffer also includes reading all pending response data from a device. If the device is still sending data, the flush process will continue to read data from the device until it receives an END indicator from the device.
Example: Sending and Receiving Formatted I/O
The following C sample program demonstrates sending and receiving formatted I/O. The program opens a session with a GPIB device and sends a comma operator to send a comma-separated list. This program shows specific VISA functionality and does not include error trapping.
The formatio.c sample program is installed on your system in the ProgrammingSamples subdirectory.
Using Non-Formatted I/O
There are two non-buffered, non-formatted I/O functions that synchronously transfer data, called viRead and viWrite. Also, there are two non-formatted I/O functions that asynchronously transfer data, called viReadAsync and viWriteAsync. These are raw I/O functions and do not intermix with the formatted I/O functions.
Non-Formatted I/O Functions
The non-formatted I/O functions follow. For more information, see viRead, viWrite, viReadAsync, viWriteAsync, or viTerminate.
viRead. The viRead function synchronously reads raw data from the session specified by the vi parameter and stores the results in the location where buf is pointing. Only one synchronous read operation can occur at any one time.
viRead(vi, buf, count, retCount);
viWrite. The viWrite function synchronously sends the data pointed to by buf to the device specified by vi. Only one synchronous write operation can occur at any one time.
viWrite(vi, buf, count, retCount);
Example: Using Non-Formatted I/O Functions
The nonfmtio.c sample program illustrates using non-formatted I/O functions to communicate with a GPIB device. It is intended to show specific VISA functionality and does not include error trapping. Error trapping, however, is good programming practice and is recommended in your VISA applications. See Trapping Errors for more information.