HP-UX

NAME

viScanf − Recieves data from a device according to the format string

SYNOPSIS

viScanf(ViSession vi, ViString readFmt, arg1, arg2,...);

Description

 
This function receives data from a device, formats it by using the format string, and stores the data in the arg parameter list.  The format string can have format specifier sequences, white space 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 conversion characters, in that sequence.  It is of the form:
 
%[modifiers]conversion character
 
where the optional modifier describes the data format, while conversion character indicates the nature of data (data type).  One and only one conversion character 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 asterisk (*) assignment-suppressing character is given.  In such a case, no arg is used, and the results are ignored.
 
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 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 function.
 

Parameters

vi An input parameter.  Unique logical identifier to a session. 
 

readFmt An input parameter. String describing the format for arguments. 
 

arg1, arg2 Output parameters.   A list with the variable number of parameters into which the data is read and the format string is applied. 
 
 

ANSI C Standard Modifiers

An integer representing the field width
 %s, %c, %[ ] are supported conversion characters.  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 refer ence 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 (l or h).  Supported conversion characters are h (d conversion character) l (d, f conversion characters) L (f conversion character).  The argument length modifiers specify one of the following:
 
  1. The h modifier indicates the argument is a reference to a short integer or unsigned short integer, depending on the conversion character.
 
  2. The l modifier indicates the argument is a reference to a long integer or unsigned long integer.
 
  3. The L modifier indicates the argument is a reference to a long double floating point  parameter.  * (asterisk)  All conversion characters  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

A comma (,) followed by an integer n, where n represents the array size.  %d and %f only are supported conversion characters.  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 comma (,) followed by an integer n, where n represents the array size.  %d 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 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. 
 
 
 
 

c Argument type: A reference to a character.

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 White space in the device input stream is not ignored when using %c.
 
 

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 IEEE 488.2 format NR1 (an integer without a decimal point). 
 

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. 
 

, 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

Default functionality Characters are read from the device until an entire number is read. The number read must be in IEEE 488.2 formats NR1 (an integer without a decimal point) or NR2 (a number with at least one digit after the decimal point). 
 

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 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 read are stored back in the integer pointed to by the first argument. 
 
 

t Argument type: A reference to a string.

Default functionality It is similar to %s, except that characters are read until the first END indicator is received, rather than the first white space character. 
 

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.  # field width has the same meaning as in %s. 
 
 

Return Values

 
This is the functional return status.  It returns either a completion code or an error code as follows.
 

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

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_TMO Timeout expired before read function 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. 
 

See Also

 
viVScanf
 

AUTHOR

viScanf was developed by HP
 

Hewlett-Packard Comapny  —  September 29, 1999