VISA函数Vscanf

语法：

ViStatus viScanf(ViSession vi, ViString readFmt, ...)

功能：

使用格式说明符读取，转换和格式化数据。将格式化的数据存储在参数中。

参数：

vi-唯一的逻辑标识符到会话。

readFmt-描述参数的格式的字符串。

...-读取数据的可变数量的列表以及应用格式字符串。

具体如下：

viScanf

Table of Contents

NI-VISA 15.0 Help

Edition Date: June 2015

Part Number: 370131S-01

»View Product Info

Purpose

Reads, converts, and formats data using the format specifier. Stores the formatted data in the parameters (designated by ...).

C Syntax

ViStatus viScanf(ViSession vi, ViString readFmt, ...)

Visual Basic Syntax

N/A

Resource Classes

GPIB INSTR, GPIB INTFC, Serial INSTR, TCPIP INSTR, TCPIP SOCKET, USB INSTR, USB RAW, VXI INSTR, VXI SERVANT

Parameters

Name	Direction	Description
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.

Return Values

Completion Codes	Description
VI_SUCCESS	Data was successfully read and formatted into ... parameter(s).

Error Codes	Description
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.

Description

The viScanf() operation receives data from a device, formats it by using the format string, and stores the resulting data in the arg parameter list. The viRead() operation is used for the actual low-level read from the device. As a result, you should not use the viRead() and viScanf() operations in the same session.

Note  Because the prototype for this function cannot provide complete type-checking, remember that all output parameters must be passed by reference.

The format string can have format specifier sequences, white characters, and ordinary characters. The white 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 format string consists of a %, followed by optional modifier flags, followed by one of the format codes in that sequence. It is of the form:

%[modifier]format code

where the optional modifier describes the data format, while format code indicates the nature of data (data type). One and only one format code should be performed at the specifier sequence. A format specification 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 * assignment-suppressing character is given. In such a case, no arg is used and the results are ignored.

The viScanf() operation accepts input until an END indicator is read or all the format specifiers in the readFmt string are satisfied. Thus, detecting an END indicator before the readFmt string is fully consumed will result in ignoring the rest of the format string. Also, 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() operation.

When viScanf() times out, the next call to viScanf() will read from an empty buffer and force a read from the device.

Notice that when an END indicator is received, not all arguments in the format string may be consumed. However, the operation still returns a successful completion code.

The following two tables describe optional modifiers that can be used in a format specifier sequence.

ANSI C Standard Modifiers

Modifier	Supported with Format Code	Description
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. Note  The # modifier is a VISA extension.
A length modifier ('h', 'l', 'll', 'L', 'z', or 'Z'). z and Z are not ANSI C standard modifiers.	h (d, b format codes) l (d, f, b format codes) ll (d and b format codes) L (f format code) z (b format code) Z (b format code)	The argument length modifiers specify one of the following: The h modifier promotes the argument to be a reference to a short integer or unsigned short integer, depending on the format code. The l modifier promotes the argument to point to a long integer or unsigned long integer. The ll modifier promotes the argument to a long long or unsigned long long. The L modifier promotes the argument to point to a long double floats parameter. The z modifier promotes the argument to point to an array of floats. 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.

Enhanced Modifiers to ANSI C Standards

Modifier	Supported with Format Code	Description
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).

ANSI C Standard Format Codes

c Argument type: A reference to a character.

Flags or Modifiers	Interpretation
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.

Note  This format code does not ignore white space in the device input stream.

d Argument type: A reference to an integer.

Flags or Modifiers	Interpretation
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 ll	arg is a reference to a long 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.

f Argument type: A reference to a floating point number.

Flags or Modifiers	Interpretation
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.

s Argument type: A reference to a string.

Flags or Modifiers	Interpretation
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.

Enhanced Format Codes

b Argument type: A reference to a data array.

Flags or Modifiers	Interpretation
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 long words, and count specifies the number of long 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 ll	arg points to an array of 64-bit long long words, and count specifies the number of long long 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 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.

t Argument type: A reference to a string.

Flags or Modifiers	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.

T Argument type: A reference to a string.

Flags or Modifiers	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.

y  Argument type: A location of a block of binary data.

Modifier	Interpretation
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.

Other ANSI C Format Specifiers

For ANSI C compatibility, VISA also supports the following format specifiers for input codes: 'i', 'o', 'u', 'n', 'x', 'X', 'e', 'E', 'g', 'G', 'p', '[...]', and '[^...]'. For further explanation of these conversion codes, see the ANSI C Standard.