National Instruments 320682C

Chapter 2 Formatting and I/O Library

Each of these formatting functions return the number of source format specifiers satisfied. If

there is an error in the format string, -1 is returned.

The formatting functions are used to format and combine multiple source items into a single

target item. The only difference in the workings of the three functions is the location of the

target data. For the function Fmt, the target is a data item in memory which is passed to the

function by reference. For FmtFile, the target is a file whose handle is passed as the first

argument. The LabWindows/CVI function OpenFile returns this handle. For the function

FmtOut, the target is Standard Out (typically the display), and in this case the target argument

present in the other two functions is omitted. Except for these differences, the following

descriptions apply to all the formatting functions.

The target parameter for Fmt must be passed by reference (that is, must be a pointer).

Formatting Functions—Format String

Consider the following formatting function:

n = Fmt(target, formatstring, source1, ..., sourcen);

where formatstring contains the information to transform the source arguments to the target

argument.

Format strings for all the formatting functions are of the form:

"target_spec < source_specs_and_literals"

where target_spec is a format specifier that describes the nature of the target data item, and

source_specs_and_literals is a sequence of format specifiers and literal characters that

indicate how the source material is to be combined into the target.

Examples of format strings for the formatting functions are as follows.

"%s < RANGE %i"

"%s < %s; %i"

The character < is a visual reminder of the direction of the data transformation (that is, from the

sources to the target), and also separates the single target format specifier from the (perhaps

multiple) source format specifiers and literals. The target format specifier can be omitted, in

which case a %s string format is assumed. If the target format specifier is omitted, the

< character can be omitted also, or retained for clarity.

Notice that the target format specifier is located to the left of the < symbol, just as the target

parameter is located to the left of the format string. Likewise, the source format specifiers are

located to the right of the < symbol, just as the source parameters are located to the right of the

format string.