LabWindows/CVI

Content Type
Programming Language
Current manual

Scanning Functions

Scanning Functions

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. For ScanIn, the function takes the source from the Standard Input, which is typically the keyboard, and omits the source argument present in the other two functions.

You must pass all target parameters for Scan by reference.

Format Strings for Scanning Functions

The scanning functions have a formatString parameter that contains the information needed to transform the source argument into the target(s) arguments. Format strings for all the scanning functions are of the following form:

"source_spec > target_specs_and_literals"

  • source_spec is a format specifier that describes the nature of the source parameter.
  • 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.
  • 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.

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

"%s > %i"

"%s > %20f[w10x]"

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

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 Note  rep is not allowed when formatcode is s or l (string).

Codes That Specify formatcode

Use the codes in the following table to 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 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 tables. The first table lists the modifiers for integer specifiers, the second table lists the modifiers for floating-point specifiers, and the last table lists modifiers for string specifiers.

Scanning Integer Modifiers

Use the following modifiers for the following format codes: %i, %d, %x, %o, and %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 b2 modifier represents short integers. The b1 modifier represents single-byte integers. Use the b0 modifier to format arguments with size_t, ssize_t, ptrdiff_t, intptr_t, or uintptr_t data types. For 32-bit OSes, the b0 modifier represents 4 bytes. For 64-bit OSes, the b0 modifier represents 8 bytes.
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. Valid 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 Note  When you use both the bn and on modifiers on an integer specifier, the bn modifier must be first.
Scanning Floating-Point Modifiers

Use the following modifiers for the %f format code.

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.
Scanning String Modifiers

Use the following modifiers for the %s format code.

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.

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.

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 %.

Was this information helpful?