viScanf

Agilent VISA.NET

previous page next page

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
Format Codes


Description

  

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

               


Format Code   

For use with
Modifiers


Description

  

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
VI_ERROR_INV_OBJECT

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

viVScanf

 

previous page start next page