viScanf
Syntax
viScanf(ViSession vi, ViString readFmt, arg1, arg2,...);
Description
This formatted IO function receives data from a device, formats it according to a format specifier (readFmt) , and stores the data in the arg parameter list. The format specifier can have white-space characters and ordinary characters. The whit-space characters — blank, vertical tabs, horizontal tabs, form feeds, new line/linefeed, and carriage return — are ignored except in the case of %c and %[ ]. All other ordinary characters except % should match the next character read from the device.
Note: VISA functions that take a variable number of parameters (e.g., viPrintf, viScanf, and viQueryf) are not callable from Visual Basic. Use the corresponding viVPrintf, viVScanf, and viVQueryf functions instead.
Parameters
|
Name |
Dir |
Type |
Description |
|
vi |
IN |
ViSession |
Unique logical identifier to a session. |
|
readFmt |
IN |
ViString |
String describing the format for arguments. Refer to the tables below for readFmt modifiers and format codes. |
|
arg1, arg2 |
OUT |
N/A |
A list with the variable number of parameters into which the data is read and the format string is applied. |
readFmt Format Specifiers
The readFmt string consists of a %, optional modifier flags,and a format code, in that sequence. It is of the form:
%[modifier]format code
where the optional modifier describes the data format, and format code indicates the data type. One and only one format code should be performed at the specifier sequence. A format specifier directs the conversion to the next input arg.
The results of the conversion are placed in the variable that the corresponding argument points to, unless the asterisk (*) assignment-suppressing character is given. In such a case, no arg is used and the results are ignored.
readFmt Modifiers
|
Modifier |
For use with |
|
|
|
An integer (representing the field width) |
%s,% c, % [ ] |
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 format codes. |
|
|
h |
d, b
|
The h modifier promotes the argument to be a reference to a short integer or unsigned short integer, depending on the format code. |
|
|
l |
d, f, b
|
The l (lower case "L") modifier promotes the argument to point to a long integer or unsigned long integer. |
|
|
L |
f
|
The L modifier promotes the argument to point to a long double floating point parameter. |
|
|
z |
b
|
The z modifier promotes the argument to point to an array of floats. |
|
|
Z |
b
|
The Z modifier promotes the argument to point to an array of double floats. |
|
|
* (asterisk) |
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, %f
|
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 conversion character. A number sign (#) may be present after the" ," 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,%f
|
Converts to an IEEE 488.2 defined NR1 compatible number, which is an integer without any decimal point (e.g., 123). |
|
|
@2 |
%d,% f
|
Converts to an IEEE 488.2 defined NR2 compatible number. The NR2 number has at least one digit after the decimal point (e.g., 123.45). |
|
|
@H |
%d, %f
|
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 the form #HXXX.., where XXX.. is a hexadecimal number (e.g., #HAF35B). |
|
|
@Q |
%d,% f
|
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 (e.g., #Q71234). |
|
|
@B |
%d, %f
|
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 (e.g., #B011101001). |
readFmt Format Codes
|
|
For use with |
|
|
|
c |
|
Argument type: A reference to a character. White space in the device input stream is not ignored when using c. |
|
|
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. |
||
|
d |
Argument type: A reference to an integer. |
||
|
Default Functionality |
Characters are read from the device until an entire number is read. The number read must be in one of the following IEEE 488.2 formats: <DECIMAL NUMERIC PROGRAM DATA>, also known as NRf. Flexible numeric representation (NR1, NR2, NR3, ...). <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. |
|
|
f |
Argument type: A reference to a floating point number. |
||
|
|
Default functionality |
Characters are read from the device until an entire number is read. The number read must 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 number 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 doubles or long doubles, 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. |
|
|
s |
Argument type: A reference to a string. |
||
|
|
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 # sign, two arguments are used. The first argument read gives the maximum string size. The second should be a reference to a string. In the 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 the case of #field width, the actual number of characters that were copied into the user array, not counting the trailing NULL character, read are stored back in the integer pointed to by the first argument. |
|
|
b |
Argument type: A reference to a data array. |
||
|
|
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 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 specifying the maximum number of elements that the array can hold. The second one should be a reference to an array. Also in this case, 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 |
The array is assumed to be an array of 16-bit words, and count refers to the number of words. The data read from the interface is assumed to be in IEEE 488.2 (big endian) byte ordering. It will be byte swapped and padded as appropriate to the native computer format. |
|
|
|
Length modifier l |
The array is assumed to be a block of 32-bit longwords rather than bytes, and count refers to the number of longwords. The data read from the interface is assumed to be in IEEE 488.2 (big endian) byte ordering. It will be byte swapped and padded as appropriate to the native computer format. |
|
|
|
Length modifier z |
The data block is assumed to be a reference to an array of floats, and count refers to the number of floating point numbers. The data block received from the device is an array of 32-bit IEEE 754 format floating point numbers. |
|
|
|
Length modifier Z |
The data block is assumed to be a reference to an array of doubles, and the count refers to the number of floating point numbers. The data block received from the device is an array of 64-bit IEEE 754 format floating point numbers |
|
|
t |
Argument type: A reference to a string |
||
|
|
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. |
|
|
T |
Argument type: A reference to a string. | ||
|
|
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. |
|
|
y |
Argument type: A location of block binary data. |
||
|
|
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 specifying the maximum number of elements that the array can hold. The second argument should be a reference to an array. Also, in this case, the actual number of elements read is stored back in the first argument. In the 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 |
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 byte order modifier is present, the data being read is assumed to be in little endian format; otherwise, the data being read is assumed to be in standard IEE 488.2 format. 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 byte order modifier is present, the data being read is assumed to be in little endian format. Otherwise, the data being read is assumed to be in standard IEE 488.2 format. Data will be byte swapped and padded as appropriate if native computer representation is different. |
|
|
|
Byte order modifier !ob |
Data being read is assumed to be in standard IEE 488.2 (big endian) format. This is the default behavior if neither !ob nor !ol is present. |
|
|
|
Byte order modifier !ol |
Data being read is assumed to be in little endian format. |
Return Values
|
Type ViStatus |
This is the function return status. It returns either a completion code or an error code as follows. |
|
Completion Code |
Description |
|
VI_SUCCESS |
Data were successfully read and formatted into arg parameter(s). |
|
Error Codes |
Description |
|
VI_ERROR_ALLOC |
The system could not allocate a formatted I/O buffer because of insufficient resources. |
|
VI_ERROR_INV_FMT |
A format specifier in the readFmt string is invalid. |
|
VI_ERROR_INV_SESSION |
The given session or object reference is invalid (both are the same value). |
|
VI_ERROR_IO |
Could not perform read function because of I/O error. |
|
VI_ERROR_NSUP_FMT |
A format specifier in the readFmt string is not supported. |
|
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_TMO |
Timeout expired before read function completed. |
Additional Notes
- White-space characters (blank, vertical tabs, horizontal tabs, form feeds,
new line/linefeed, and carriage return) are ignored except in the case
of %c and %[ ].
All other ordinary characters except % should match the next character
read from the device.
- The viScanf function accepts
input until an END indicator is read or all the format specifiers in the readFmt string are satisfied.
It also terminates if the format string character does not match the incoming
character. Thus, detecting an END indicator before the readFmt
string is fully consumed results in ignoring the rest of the format
string.
- If some data remains in the buffer after all format specifiers
in the readFmt string are satisfied,
the data will be kept in the buffer and will be used by the next viScanf function.
- There is a one-to-one correspondence between % format conversions and
arg parameters in formatted I/O
read operations except:
- If a * is present, no arg parameters are used.
- If a # is present instead of field width, two arg parameters are used. The first arg is a reference to an integer (%c, %s, %t, %T). This arg defines the maximum size of the string being read. The second arg points to the buffer that will store the read data.
- If a # is present instead of array_size,
two arg parameters are used.
The first arg is a reference
to an integer (%d, %f)
or a reference to a long integer (%b,
%y). This arg
defines the number of elements in the array. The second arg
points to the array that will store the read data.
- If a size is present in field width for the %s,
%t, and %T
format conversions in formatted I/O read operations either as an integer
or a # with a corresponding arg,
the size defines the maximum number of characters to be stored in the
resulting string.
- For ANSI C compatibility the following conversion codes are also supported
for input codes. These codes are 'i,' 'o,' 'u,' 'n,' 'x,' 'X,' 'e,' 'E,'
'g,' 'G,' 'p,' '[...],' and '[^...].' For further explanation of these
conversion codes, see the ANSI C Standard.
- If viScanf times out, the read buffer is cleared before viScanf returns. When viScanf times out, the next call to viScanf will read from an empty buffer and force a read from the device. The following tables describe optional modifiers that can be used in a format specifier sequence.
See Also