Synchronous Read/Write Services

The most straightforward of the operations are viRead() and viWrite(), which perform the actual receiving and sending of strings. Notice that these operations look upon the data as a string and do not interpret the contents. For this reason, the data could be messages, commands, or binary encoded data, depending on how the device has been programmed. For example, the IEEE 488.2 command *IDN? is a message that is sent in ASCII format. However, an oscilloscope returning a digitized waveform may take each 16-bit data point and put it end to end as a series of 8-bit characters. The following code segment shows a program requesting the waveform that the device has captured.

status = viWrite(instr, "READ:WAVFM:CH1", 14, &retCount);
status = viRead(instr, buffer, 1024, &retCount);

Now the character array buffer contains the data for the waveform, but you still do not know how the data is formatted. For example, if the data points were 1, 2, 3, ...the buffer might be formatted as "1,2,3,...". However, if the data were binary encoded 8-bit values, the first byte of buffer would be 1—not the ASCII character 1, but the actual value 1. The next byte would be neither a comma nor the ASCII character 2, but the actual value 2, and so on. Refer to the documentation that came with the device for information on how to program the device and interpret the responses.

The various ways that a string can be sent is the next issue to consider in message-based communication. For example, the actual mechanism for sending a byte differs drastically between GPIB and VXI; however, both have similar mechanisms to indicate when the last byte has been transferred. Under both systems, a device can specify an actual character, such as linefeed, to indicate that no more data will be sent. This is known as the End Of String (EOS) character and is common in older GPIB devices. The obvious drawback to this mechanism is that you must send an extra character to terminate the communication, and you cannot use this character in your messages. However, both GPIB and VXI can specify that the current byte is the last byte. GPIB uses the EOI line on the bus, and VXI uses the END bit in the Word Serial command that encapsulates the byte.

You need to determine how to inform the VISA driver which mechanism to use. As was discussed in VISA Overview, VISA uses a technique known as attributes to hold this information. For example, to tell the driver to use the EOI line or END bit, you set the VI_ATTR_SEND_END_EN attribute to true.

status = viSetAttribute(instr, VI_ATTR_SEND_END_EN, VI_TRUE);

You can terminate reads on a carriage return by using the following code.

status = viSetAttribute(instr, VI_ATTR_TERMCHAR, 0x0D);
status = viSetAttribute(instr, VI_ATTR_TERMCHAR_EN, VI_TRUE);

Refer to Common Considerations for Using Attributes for the default values of these attributes. Refer to Attributes for a complete list and description of the available attributes.