vi

IN

Unique logical identifier to a session.

readFmt

IN

String describing the format for arguments.

...

OUT

Parameters into which the data is read and the format string is applied.

VI_SUCCESS

Data was successfully read and formatted into ... parameter(s).

VI_ERROR_INV_OBJECT

The given session reference is invalid.

VI_ERROR_RSRC_LOCKED

Specified operation could not be performed because the resource identified by vi has been locked for this kind of access.

VI_ERROR_IO

Could not perform read operation because of I/O error.

VI_ERROR_TMO

Timeout expired before read operation completed.

VI_ERROR_INV_FMT

A format specifier in the readFmt string is invalid.

VI_ERROR_NSUP_FMT

A format specifier in the readFmt string is not supported.

VI_ERROR_ALLOC

The system could not allocate a formatted I/O buffer because of insufficient resources.

An integer representing the field width

%s, %c, %[] format codes

It specifies the maximum field width that the argument will take. A '#' may also appear instead of the integer field width, in which case the next arg is a reference to the field width. This arg is a reference to an integer for %c and %s. The field width is not allowed for %d or %f.

A length modifier ('h',
'l', 'L', 'z', or
'Z'). z and Z are not ANSI C standard modifiers.

h (d, b format codes)

l (d, f, b format codes)

L (f format code)

z (b format code)

Z (b format code)

The argument length modifiers specify one of the following:

1. The h modifier promotes the argument to be a reference to a short integer or unsigned short integer, depending on the format code.
2. The l modifier promotes the argument to point to a long integer or unsigned long integer.
3. The L modifier promotes the argument to point to a long double floats parameter.
4. The z modifier promotes the argument to point to an array of floats.
5. The Z modifier promotes the argument to point to an array of double floats.

*

All format codes

An asterisk (*) acts as the assignment suppression character. The input is not assigned to any parameters and is discarded.

A comma (,) followed by an integer n, where n represents the array size.

%d (plus variants) and %f only

The corresponding argument is interpreted as a reference to the first element of an array of size n. The first n elements of this list are printed in the format specified by the format code.

A number sign (#) may be present after the comma (,) modifier, in which case an extra arg is used. This arg must be an integer representing the array size of the given type.

@1

%d (plus variants) and %f only

Converts to an IEEE 488.2 defined NR1 compatible number, which is an integer without any decimal point (for example, 123).

@2

%d (plus variants) and %f only

Converts to an IEEE 488.2 defined NR2 compatible number. The NR2 number has at least one digit after the decimal point (for example, 123.45).

@H

%d (plus variants) and %f only

Converts to an IEEE 488.2 defined <HEXADECIMAL NUMERIC RESPONSE DATA>. The number is represented in a base of sixteen form. Only capital letters should represent numbers. The number is of form #HXXX.., where XXX.. is a hexadecimal number (for example, #HAF35B).

@Q

%d (plus variants) and %f only

Converts to an IEEE 488.2 defined <OCTAL NUMERIC RESPONSE DATA>. The number is represented in a base of eight form. The number is of the form #QYYY.., where YYY.. is an octal number (for example, #Q71234).

@B

%d (plus variants) and %f only

Converts to an IEEE 488.2 defined <BINARY NUMERIC RESPONSE DATA>. The number is represented in a base two form. The number is of the form #BZZZ.., where ZZZ.. is a binary number (for example, #B011101001).

Default functionality

A character is read from the device and stored in the parameter.

field width

field width number of characters are read and stored at the reference location (the default field width is 1). No NULL character is added at the end of the data block.

Default functionality

Characters are read from the device until an entire number is read. The number read may be in either IEEE 488.2 formats <DECIMAL NUMERIC PROGRAM DATA>, also known as NRf; flexible numeric representation (NR1, NR2, NR3...); or <NON-DECIMAL NUMERIC PROGRAM DATA> (#H, #Q, and #B).

field width

The input number will be stored in a field at least this wide.

Length modifier l

arg is a reference to a long integer.

Length modifier h

arg is a reference to a short integer. Rounding is performed according to IEEE 488.2 rules (0.5 and up).

,array size

arg points to an array of integers (or long or short integers, depending on the length modifier) of size array size. The elements of this array should be separated by commas. Elements will be read until either array size number of elements are consumed or they are no longer separated by commas. If the array size contains a number sign (#), two arguments are used. The first arg read is a pointer to an integer specifying the maximum number of elements that the array can hold. The second arg should be a reference to an array. Also, the actual number of elements read is stored back in the first argument.

Default functionality

Characters are read from the device until an entire number is read. The number read may be in either IEEE 488.2 formats <DECIMAL NUMERIC PROGRAM DATA> (NRf) or <NON-DECIMAL NUMERIC PROGRAM DATA> (#H, #Q, and #B)

field width

The input will be stored in a field at least this wide.

Length modifier l

arg is a reference to a double floating point number.

Length modifier L

arg is a reference to a long double number.

,array size

arg points to an array of floats (or double or long double, depending on the length modifier) of size array size. The elements of this array should be separated by commas. Elements will be read until either array size number of elements are consumed or they are no longer separated by commas. If the array size contains a number sign (#), two arguments are used. The first arg read is a pointer to an integer specifying the maximum number of elements that the array can hold. The second arg should be a reference to an array. Also, the actual number of elements read is stored back in the first argument.

Default functionality

All leading white space characters are ignored. Characters are read from the device into the string until a white space character is read.

field width

This flag gives the maximum string size. If the field width contains a number sign (#), two arguments are used. The first argument read is a pointer to an integer specifying the maximum array size. The second should be a reference to an array. In case of field width characters already read before encountering a white space, additional characters are read and discarded until a white space character is found. In case of # field width, the actual number of characters that were copied into the user array, not counting the trailing NULL character, are stored back in the integer pointed to by the first argument.

Default functionality

The data must be in IEEE 488.2 <ARBITRARY BLOCK PROGRAM DATA> format. The format specifier sequence should have a flag describing the field width, which will give a maximum count of the number of bytes (or words or longwords, depending on length modifiers) to be read from the device. If the field width contains a # sign, two arguments are used. The first arg read is a pointer to a long integer specifying the maximum number of elements that the array can hold. The second arg should be a reference to an array. Also, the actual number of elements read is stored back in the first argument. In absence of length modifiers, the data is assumed to be of byte-size elements. In some cases, data might be read until an END indicator is read.

Length modifier h

arg points to an array of 16-bit words, and count specifies the number of words. Data that is read is assumed to be in IEEE 488.2 byte ordering. It will be byte swapped and padded as appropriate to native computer format.

Length modifier l

arg points to an array of 32-bit longwords, and count specifies the number of longwords. Data that is read is assumed to be in IEEE 488.2 byte ordering. It will be byte swapped and padded as appropriate to native computer format.

Length modifier z

arg points to an array of floats, and count specifies the number of floating point numbers. Data that is read is an array of 32-bit IEEE 754 format floating point numbers.

Length modifier Z

arg points to an array of doubles, and the count specifies the number of floating point numbers. Data that is read is an array of 64-bit IEEE 754 format floating point numbers.

Interpretation

Default functionality

Characters are read from the device until the first END indicator is received. The character on which the END indicator was received is included in the buffer.

field width

This flag gives the maximum string size. If an END indicator is not received before field width number of characters, additional characters are read and discarded until an END indicator arrives. #field width has the same meaning as in %s.

Interpretation

Default functionality

Characters are read from the device until the first linefeed character (\n) is received. The linefeed character is included in the buffer.

field width

This flag gives the maximum string size. If a linefeed character is not received before field width number of characters, additional characters are read and discarded until a linefeed character arrives. #field width has the same meaning as in %s.

Default functionality

The data block is read as raw binary data. The format specifier sequence should have a flag describing the array size, which will give a maximum count of the number of bytes (or words or longwords, depending on length modifiers) to be read from the device. If the array size contains a # sign, two arguments are used. The first argument read is a pointer to a long integer that specifies the maximum number of elements that the array can hold. The second argument should be a reference to an array. Also, the actual number of elements read is stored back in the first argument. In absence of length modifiers, the data is assumed to be byte-size elements. In some cases, data might be read until an END indicator is read.

Length modifier h

The data block is assumed to be a reference to an array of unsigned short integers (16 bits). The count corresponds to the number of words rather than bytes. If the optional !ol modifier is present, the data read is assumed to be in little endian format; otherwise, the data read is assumed to be in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate to native computer format.

Length modifier l

The data block is assumed to be a reference to an array of unsigned long integers (32 bits). The count corresponds to the number of longwords rather than bytes. If the optional !ol modifier is present, the data read is assumed to be in little endian format; otherwise, the data read is assumed to be in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate to native computer format.

Length modifier z

The data block is assumed to be a reference to an array of single-precision floating-point numbers (32 bits). The count corresponds to the number of floats rather than bytes. If the optional !ol modifier is present, the data read is assumed to be in little endian format; otherwise, the data read is assumed to be in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate to native computer format.

Length modifier Z

The data block is assumed to be a reference to an array of double-precision floating-point numbers (64 bits). The count corresponds to the number of double floats rather than bytes. If the optional !ol modifier is present, the data read is assumed to be in little endian format; otherwise, the data read is assumed to be in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate to native computer format.

Byte order modifier !ob

The data being read is assumed to be in standard IEEE 488.2 (big endian) format. This is the default behavior if neither !ob nor !ol is present.

Byte order modifier !ol

The data being read is assumed to be in little endian format.