# Scanning Functions

The following information briefly describes the three scanning functions.

- n = Scan (source, formatstring, targetptr1, ..., targetptrn);
  Scan inspects the source argument and transforms it according to descriptions in the formatstring argument. Scan places the results of the transformations into the targetptr1, ..., targetptrn arguments.
- n = ScanFile (handle, formatstring, targetptr1, ..., targetptrn);
  ScanFile reads data from the file that corresponds to the handle argument and transforms it according to descriptions in the formatstring argument. ScanFile places the results of the transformations into the targetptr1, ..., targetptrn arguments.
- n = ScanIn (formatstring, targetptr1, ..., targetptrn);
  ScanIn reads data from the Standard Input and transforms it according to descriptions in the formatstring argument. ScanIn places the results of the transformations into the targetptr1, ..., targetptrn arguments.

Each of these scanning functions returns the number of target format specifiers satisfied. If an error exists in the format string, the functions return -1.

The scanning functions break apart a source item into component parts and store the parts in parameters passed to the functions. The only difference among the three functions is the location of the source data. For Scan, the source item is a data item in memory that you pass to the function. For ScanFile, the source item is a file, whose handle you pass as the first argument. Call OpenFile to obtain a file handle. For ScanIn, the function takes the source from the Standard Input, typically the keyboard, and omits the source argument present in the other two functions.

You must pass all target parameters for Scan by reference.

## Scanning Functions—Format String

Consider the following scanning function:

n = Scan(source, formatstring, targetptr1, ..., targetptrn);

where formatstring contains the information needed to transform the source argument into the targetptr arguments.

Format strings for the scanning functions follow the form:

"source_spec > target_specs_and_literals"

where source_spec is a format specifier that describes the nature of the source parameter and target_specs_and_literals is a sequence of format specifiers and literal characters that indicates how to divide and reformat the source argument into the desired target.

Examples of format strings for the scanning functions are as follows:

"%s > %i"

"%s > %20f[w10x]"

The character '>' serves as a visual reminder of the direction of the data transformation and separates the single source format specifier from the target format specifiers and literals. You can omit the source format specifier, in which case the functions assume a %s string format. If you omit the source format specifier, you can omit the '>' character or retain the character for clarity.

Notice that the source format specifier is located to the left of the '>' symbol, just as the source parameter is located to the left of the format string. Likewise, the target format specifiers are located to the right of the '>' symbol, just as the target parameters are located to the right of the format string.

Format specifiers describe the inputs and outputs of data transformations. Each format specifier is of the following form:

% [ rep ] formatcode [[ modifiers ]]

The character '%' introduces all format specifiers. rep indicates how many times the format repeats with respect to the arguments. formatcode is a code character that indicates the nature of the data items the functions format. modifiers is an optional bracket-enclosed sequence of codes that further describes the data format.

The following example demonstrates the use of format specifiers.

%s[t59] %100i[z] %f

| Note rep is not allowed when formatcode is s or l (string).

Use one of the codes in the following table to specify formatcode.

### Codes That Specify formatcode

formatcode | Meaning | Description
s | String | This source or target specifier indicates that the corresponding parameter is a character string. As a source specifier, the number of bytes of the source parameter that the functions consume depends on the target specifier. If the target specifier is %s, the functions consume bytes until they encounter a termination character. Refer to the t modifier for strings for more information about termination characters. If the target specifier is one of the numeric formats, the functions consume bytes as long as the bytes correspond to the pattern for the particular numeric item the functions are converting. The functions skip leading spaces and tabs unless you use the y modifier.
| Note When the functions fill in a target string, they always place an ASCII NUL in the string after the last byte.
l | String | This specifier is allowed only as a source specifier. This specifier is the same as the %s specifier, except that the function consumes bytes from the source argument only until it encounters a linefeed. You can modify this specifier with c, as in %l[c], to tell the functions to use a comma as the target string terminator instead of white space characters.
i | Integer | This source or target specifier indicates that the corresponding parameter is an integer or, if rep is present, an integer array. If you use i as a source specifier in conversions to string formats, the functions convert the integer into digits of the specified radix. The default is decimal. If you use i as a target specifier in conversions from string format, the functions consume bytes of the source parameter as long as they match the pattern of integer ASCII numbers in the appropriate radix or until the functions encounter the end of the string. The functions convert the scanned characters to integer values and place the values into the corresponding target parameter, which is an integer array or integer you pass by reference. The pattern for integer ASCII numbers consists of an optional sign (+ or -), followed by a series of one or more digits in the appropriate radix. The decimal digits are 0123456789. The octal digits are 01234567. The hexadecimal digits are 0123456789ABCDEFabcdef.
x | Integer (hexadecimal) | This specifier indicates a %i format with hexadecimal radix.
o | Integer (octal) | This specifier indicates a %i format with octal radix.
d | Integer (decimal) | This specifier is identical to %i and is included for compatibility with the C scanf family of functions.
f | Real number | As a source or target specifier, this specifier indicates that the corresponding parameter is a real number, or if rep is present, a real array. If you use f as a source specifier in conversions to string formats, the functions convert the floating-point value into ASCII form. If you use f as a target specifier in conversions from string format, the functions consume bytes of the source parameter as long as they match the pattern of floating-point ASCII numbers or until the functions encounter the end of the string. The functions convert the scanned characters to a floating-point value and place the values into the corresponding floating-point or floating-point array target parameter. The pattern for floating-point ASCII numbers is an optional sign (+ or -), a series of one or more decimal digits that can contain a decimal point, and an optional exponent that consists of an E or e followed by an optionally signed decimal integer value.
c | Character | As a source specifier, this specifier indicates that the source parameter is an integer with one significant byte or, if rep is present, an array of 1-byte integers. As a target specifier, this specifier indicates that the functions consume a byte of the source parameter and place the scanned character directly into the corresponding target parameter, which is an integer you pass by reference.

## Scanning Modifiers

Modifiers are optional codes you use to describe the nature of the source or target data. If you use modifiers, you must enclose them in square brackets and place them immediately after the format code they modify. If one format specifier requires more than one modifier, enclose all modifiers in the same set of brackets.

A different set of modifiers exists for each possible format specifier as shown in the following table, Table 3, and Table 4.

## Scanning Integer Modifiers (%i, %d, %x, %o, %c)

Modifier | Meaning | Description
bn | Specify length | The b integer modifier specifies the length of the integer argument or the length of an individual integer array element in bytes. The default length is 4 bytes; therefore, simple 4-byte integers do not need this modifier. The modifier b2 represents short integers. The modifier b1 represents single-byte integers.
in | Specify array offset | The i integer modifier specifies an offset within an integer array argument. This modifier indicates the location within the array where processing begins. n is the zero-based index of the first element to process. Thus, %10d[i2] applied to a source integer array processes the 10 integer values from the third through the 12th element of the array. The i modifier is valid only if rep is present. If you use the i modifier with the z modifier, n is in terms of bytes.
z | Treat string as integer array | The z integer modifier indicates that the data type of the corresponding argument is a string. Nevertheless, the functions treat the data in the string as an integer array. The z modifier is valid only if rep is present.
rn | Specify radix | The r integer modifier specifies the radix of the integer argument, which is important if the functions convert the integer from a string format. Legal radixes are 8 (octal), 10 (decimal, the default), 16 (hexadecimal), and 256 (a special radix that represents single 8-bit ASCII characters).
wn | Specify string size | The w integer modifier specifies the exact number of bytes occupied by a string representation of the integer argument, in the event that the functions convert the integer from a string format. You can enter any non-negative value here. If n is less than the number of digits required to represent the integer, the functions insert an asterisk (*) into the string to signify an overflow. The default for n is zero, which indicates that the integer can occupy as much space as necessary.
s | Specify as two’s complement | The s integer modifier indicates that the functions consider the integer argument a signed two’s complement number. This is the default interpretation of integers, so the functions do not require the s modifier.
u | Specify as non-negative | The u integer modifier indicates that the functions consider the integer to be a non-negative integer.
x | Discard terminator | The x integer modifier causes the functions to discard the character that terminates the numeric data. In this way, the functions can skip the terminator characters when reading lists of numeric input. Thus, %3i[x] reads three integer numbers, disregarding the terminator character that appears after each one. You can use this specifier to scan the string 3, 7, -32.
d | Discard data | When applied to a target specifier, the d integer modifier indicates that no target argument corresponds to the target specifier. The functions discard the data the functions would otherwise place in the target argument. The count the functions return includes the target specifier even if you use the d modifier.
onnnn | Specify byte ordering | The o integer modifier specifies the byte ordering of raw data so that LabWindows/CVI can map the data to the appropriate byte order. The number of n’s must be equal to the byte size of the integer argument as specified by the bn modifier, which must precede the o modifier. In the case of a four-byte integer, o0123 indicates that the bytes are in ascending order of precedence, and o3210 indicates that the bytes are in descending order of precedence.

When using the Scan function to transfer raw instrument data to or from a C integer or integer array, you must use the o modifier on the buffer that contains the raw instrument data. Do not use the o modifier on the buffer that contains the C integer or integer array. LabWindows/CVI determines the byte ordering of the buffer without the o modifier based on the architecture on which your program is running.

For example, if a GPIB instrument sends 2-byte binary data in Intel-byte order, the code appears as follows:

short int instr_buf[100];
short int prog_buf[100];
status = ibrd (ud, instr_buf, 200);
Scan (instr_buf, "%100d[b2o01]>%100d[b2]", prog_buf);

If, instead, the GPIB instrument sends 2-byte binary data in Motorola byte order, Scan appears as follows:

Scan (instr_buf, "%100d[b2o10]>%100d[b2]", prog_buf);

In either case, you use the o modifier only on the buffer that contains the raw data from the instrument (instr_buf). LabWindows/CVI ensures that the program buffer (prog_buf) is in the proper byte order for the host processor.

| Note When you use both the bn and on modifiers on an integer specifier, the bn modifier must be first.

### Table 3. Scanning Floating-Point Modifiers (%f)

Modifier | Meaning | Description
bn | Specify length | The b floating-point modifier specifies the length of the floating-point argument or the length of an individual array element, in bytes. The default length is 8 bytes; therefore, double-precision values do not need this modifier. Single-precision floating-point values are indicated by b4. The only valid values for n are 8 and 4.
in | Specify array offset | The i floating-point modifier specifies an offset within a floating-point array argument. This modifier indicates the location within the array where processing begins. n is the zero-based index of the first element to process. Thus, %10f[i2] applied to a source floating-point array processes the 10 floating-point values from the third through the 12th element of the array. The i modifier is valid only if rep is present. If you use the i modifier with the z modifier, n is in terms of bytes.
z | Treat string as floating point | The z floating-point modifier indicates that the data type of the corresponding argument is a string. Nevertheless, the functions treat the data in the string as a floating-point array. The z modifier is valid only if rep is present.
wn | Specify string size | The w floating-point modifier specifies the exact number of bytes occupied by a string representation of the floating-point argument, in the event that the functions convert the value from a string format. You can enter any non-negative value here. If n is less than the number of digits required to represent the floating-point number, the functions insert an asterisk (*) into the string to signify an overflow. The default for n is zero, which indicates that the value can occupy whatever space is necessary.
pn | Specify precision | The p floating-point modifier specifies the number of digits to the right of the decimal point in a string representation of the floating-point number. You can lose significant digits by attempting to conform to the precision specification. If you omit the pn modifier, the default is p6. The p modifier is valid for sources only.
en | Specify as scientific notation | The e floating-point modifier indicates that the string representation of the floating-point value is in scientific notation. If you omit the modifier, the functions use non-scientific notation. n is optional and specifies the number of digits to use in the exponent. For example, %f[e2] causes the functions to format 10.0 as 1.0e+01. If you omit n, the functions use a default of three. The e modifier is valid for sources only.
f | Specify as floating point | The f floating-point modifier indicates that the string representation of the floating-point value is not in scientific notation. This is the default even when the f modifier is absent.
x | Discard terminator | The x floating-point modifier causes the functions to discard the character that terminates the numeric data. In this way, the functions can skip terminator characters when reading lists of numeric input. Thus, %3f[x] reads three floating-point numbers, disregarding the terminator character that appears after each one. You can use this specifier to scan the string 3.5, 7.6, -32.4.
d | Discard data | When applied to a target specifier, the d modifier indicates no target argument exists to correspond to the target specifier. The functions discard the data the functions would otherwise place in the target argument. The count the functions return includes the target specifier even if you use the d modifier.

### Table 4. Scanning String Modifiers (%s)

Modifier | Meaning | Description
in | Specify array offset | The i string modifier specifies an offset within a string. This modifier indicates the location within the string where processing begins. n is the zero-based index of the first byte to process. Thus, %s[i2] applied to a target string begins placing data in the third byte of the string.
a | Append | When applied to a target format specifier, the a string modifier specifies that all formatted data be appended to the target string, beginning at the first occurrence of an ASCII NUL in the target string.
wn | Specify string size | When applied to a source format specifier, the w string modifier specifies the maximum number of bytes from the source string to use for filling the target arguments. You can enter any non-negative value here. The default is zero, which indicates that the entire string can be used. In this case, the ScanFile and ScanIn functions consume the entire source string even if the w modifier restricts the number of bytes used to fill in the target arguments. When modifying a target format specifier, the w modifier specifies the exact number of bytes to store in the string, excluding the terminating ASCII NUL. If n is zero or omitted, the functions store as many bytes as are called for by the sources. When n is greater than the number of bytes available from the source, the remaining bytes are filled with ASCII NULs if you use the q modifier or blanks if you do not use the q modifier. When you use the w modifier in conjunction with the a modifier, n indicates the number of bytes to append to the string, excluding the terminating ASCII NUL.
q | Append NULs | When applied to a target string in conjunction with the w string modifier, the q string modifier specifies that the functions set unfilled bytes at the end of the target string to ASCII NULs instead of blanks.
y | Append with spacing | When the source is a string and you apply the y modifier to a target string format specifier, the functions fill the target string with bytes from the source string without skipping leading spaces or tabs.
tn | Terminate on character | When applied to a source string, the t modifier specifies that the source string terminates on the first occurrence of the character n, where n is the ASCII value of the character. Thus, %s[t44] stops the reading of the source string on an ASCII comma. More than one t modifier can occur in the same specifier, in which case the string terminates when any of the terminators occur. If no t modifier exists, the functions stop reading the source string on an ASCII NUL. When applied to a target string that the functions fill from a source string, the t modifier specifies that the functions stop filling the target on the first occurrence of the character n, where n is the ASCII value of the character. Thus, %s[t59] causes the functions to stop reading the source string on an ASCII semicolon. More than one t modifier can occur in the same specifier, in which case the functions stop filling the target when any of the terminators occur. If no t modifier exists, the functions stop filling the target on any whitespace character.
t- | Terminate when full | This modifier is similar to tn except that t- specifies that there are no terminating characters. When applied to a source string, t- specifies that the functions stop reading the source string when all the targets are full or when the functions have read the number of bytes you specify with the w modifier. When applied to a target string, t- specifies that the functions stop filling the target string when the source is exhausted or when the functions have placed into the target the number of bytes you specify with the w modifier.
t# | Terminate on number | This modifier is equivalent to repeating the t modifier with the ASCII values of the characters +, -, and 0-9. When applied to a source, this modifier specifies that the functions stop reading the source string when a numeric expression occurs. Thus, if you use %s>%s[t#]%d with the source string "ab567", the functions place "ab" in the first target and the integer 567 in the second target. When applied to a target, this modifier specifies that the functions stop filling the target string when a numeric expression occurs.
x | Discard terminator | When applied to a target string, the x modifier specifies that the functions discard the terminating character before filling in the next target. If the functions use %s>%s[xt59]%s[xt59] with the source string "abc;XYZ;", the functions place "abc" in the first target and "XYZ" in the second target.
d | Discard data | When applied to a target specifier, the d modifier indicates that no target argument corresponds to the target specifier. The functions discard the data the functions would otherwise place in the target argument. The count the functions return includes the target specifier even if you use the d modifier.

### Scan, ScanFile, ScanIn—Using Asterisks (*) Instead of Constants in Format Specifiers

Often, a format specifier requires one or more integer values. The format specifier for an integer array, for example, requires the number of elements (rep). You can use constants for these integer values in format specifiers. You also can use an argument in the argument list to specify an integer value. When you use an argument to specify an integer value, substitute an asterisk (*) for the constant in the format specifier.

Use the asterisk in the following format specifier elements:

rep | For integer or floating-point arrays
in | For integer or floating-point arrays, or strings
wn | For any format specifier
pn | For floating-point specifiers only
en | For floating-point specifiers only
rn | For integer specifiers only

When you use one or more asterisks instead of constants in a source specifier, the arguments that correspond to the asterisks must appear after the format string in the same order as the corresponding asterisks appear in the format specifier.

When you use one or more asterisks instead of constants in a target specifier, the arguments that correspond to the asterisks must precede the target argument and must be in the same order as the corresponding asterisks in the format specifier.

### Scan, ScanFile, ScanIn—Using Literals in the Format String

Literal characters that appear in a scanning function format string indicate that the functions expect the literal characters in the source parameter. The functions do not store them in any target parameter but skip over them when encountered. If a literal character you specify in the format string fails to appear in the source in the expected position, the scanning function returns without processing the target specifiers that appear to the right of the unmatched literal. The scanning functions return the number of target parameters the input actually fulfilled. NumFmtdBytes returns the number of bytes consumed from the source parameter.

Because the left side of the > symbol must be a single format specifier, literal characters, if present, must be on the right side of the symbol. Literals on the left side or more than one format specifier on the left side result in a -1 error, indicating a faulty format string. If you receive this error, you can use GetFmtErrNdx to determine exactly where there is an error in the format string.

The characters %, [, ], <, and > have special meaning in the format strings. To specify that these characters be taken literally, precede them with %.