viPrintf

NI-VISA 15.0 Help

Edition Date: June 2015

Part Number: 370131S-01

»View Product Info

Purpose

Converts, formats, and sends the parameters (designated by...) to the device as specified by the format string.

C Syntax

ViStatus viPrintf(ViSession vi, ViString writeFmt, ...)

Visual Basic Syntax

N/A

Resource Classes

GPIB INSTR, GPIB INTFC, Serial INSTR, TCPIP INSTR, TCPIP SOCKET, USB INSTR, USB RAW, VXI INSTR, VXI SERVANT

Parameters

Name Direction Description

vi

IN

Unique logical identifier to a session.

writeFmt

IN

String describing the format for arguments.

...

IN

Parameters to which the format string is applied.

Return Values

Completion Codes Description

VI_SUCCESS

Parameters were successfully formatted.

Error Codes Description

VI_ERROR_INV_OBJECT

The given session reference is invalid.

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_IO

Could not perform write operation because of I/O error.

VI_ERROR_TMO

Timeout expired before write operation completed.

VI_ERROR_INV_FMT

A format specifier in the writeFmt string is invalid.

VI_ERROR_NSUP_FMT

A format specifier in the writeFmt string is not supported.

VI_ERROR_ALLOC

The system could not allocate a formatted I/O buffer because of insufficient resources.

Description

The viPrintf() operation sends data to a device as specified by the format string. Before sending the data, the operation formats the arguments in the parameter list as specified in the writeFmt string. The viWrite() operation performs the actual low-level I/O to the device. As a result, you should not use the viWrite() and viPrintf() operations in the same session.

The writeFmt string can include regular character sequences, special formatting characters, and special format specifiers. The regular characters (including white spaces) are written to the device unchanged. The special characters consist of '\' (backslash) followed by a character. The format specifier sequence consists of '%' (percent) followed by an optional modifier (flag), followed by a format code.

Special Formatting Characters

Special formatting character sequences send special characters. The following table lists the special characters and describes what they send to the device.

Formatting Character Character Sent to Device

\n

Sends the ASCII LF character. The END identifier will also be automatically sent.

\r

Sends an ASCII CR character.

\t

Sends an ASCII TAB character.

\###

Sends the ASCII character specified by the octal value.

\x##

Sends the ASCII character specified by the hexadecimal value.

\"

Sends the ASCII double-quote (") character.

\\

Sends a backslash (\) character.

Format Specifiers

The format specifiers convert the next parameter in the sequence according to the modifier and format code, after which the formatted data is written to the specified device. The format specifier takes the following syntax:

%[modifiers]format code

where format code specifies which data type the argument is represented in. Modifiers are optional codes that describe the target data.

In the following tables, a 'd' format code refers to all conversion codes of type integer ('d', 'i', 'o', 'u', 'x', 'X'), unless specified as %d only. Similarly, an 'f' format code refers to all conversion codes of type float ('f', 'e', 'E', 'g', 'G'), unless specified as %f only.

Every conversion command starts with the % character and ends with a conversion character (format code). Between the % character and the format code, the following modifiers can appear in the sequence.

ANSI C Standard Modifiers

Modifier

Supported with Format Code Description

An integer specifying field width.

d, f, s format codes

This specifies the minimum field width of the converted argument. If an argument is shorter than the field width, it will be padded on the left (or the right if the - flag is present).

Special case:

For the @H, @Q, and @B flags, the field width includes the #H, #Q, and #B strings, respectively.

An asterisk (*) may be present in lieu of a field width modifier, in which case an extra arg is used. This arg must be an integer representing the field width.

An integer specifying precision.

d, f, s format codes

The precision string consists of a string of decimal digits. A decimal point (.) must prefix the precision string. The precision string specifies the following:

  1. The minimum number of digits to appear for the @1, @H, @Q, and @B flags and the i, o, u, x, and X format codes.
  2. The maximum number of digits after the decimal point in case of f format codes.
  3. The maximum numbers of characters for the string (s) specifier.
  4. Maximum significant digits for g format code.

An asterisk (*) may be present in lieu of a precision modifier, in which case an extra arg is used. This arg must be an integer representing the precision of a numeric field.

An argument length modifier.

h, l, ll, L, z, and Z are legal values. (z and Z are not ANSI C standard modifiers.)


h (d, b, B format codes)

l (d, f, b, B format codes)

ll (d, b, B format codes)

L (f format code)

z (b, B format codes)

Z (b, B format codes)

The argument length modifiers specify one of the following:

  1. The h modifier promotes the argument to a short or unsigned short, depending on the format code type.
  2. The l modifier promotes the argument to a long or unsigned long.
  3. The ll modifier promotes the argument to a long long or unsigned long long.
  4. The L modifier promotes the argument to a long double parameter.
  5. The z modifier promotes the argument to an array of floats.
  6. The Z modifier promotes the argument to an array of doubles.

Enhanced Modifiers to ANSI C Standards

Modifier Supported with Format Code Description

A comma (,) followed by an integer n, where n represents the array size.

%d (plus variants) 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 format code.

An asterisk (*) may be present after the comma (,) 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 (plus variants) and %f only

Converts to an IEEE 488.2 defined NR1 compatible number, which is an integer without any decimal point (for example, 123).

@2

%d (plus variants) and %f only

Converts to an IEEE 488.2 defined NR2 compatible number. The NR2 number has at least one digit after the decimal point (for example, 123.45).

@3

%d (plus variants) and %f only

Converts to an IEEE 488.2 defined NR3 compatible number. An NR3 number is a floating point number represented in an exponential form (for example, 1.2345E-67).

@H

%d (plus variants) and %f only

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 form #HXXX.., where XXX.. is a hexadecimal number (for example, #HAF35B).

@Q

%d (plus variants) and %f only

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 (for example, #Q71234).

@B

%d (plus variants) and %f only

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 (for example, #B011101001).

The following are the allowed format code characters. A format specifier sequence should include one and only one format code.

ANSI C Standard Format Codes

% Send the ASCII percent (%) character.

c Argument type: A character to be sent.

d Argument type: An integer.

Modifier Interpretation

Default functionality

Print an integer in NR1 format (an integer without a decimal point).

@2 or @3

The integer is converted into a floating point number and output in the correct format.

field width

Minimum field width of the output number. Any of the six IEEE 488.2 modifiers can also be specified with field width.

Length modifier l

arg is a long integer.

Length modifier ll

arg is a long long integer.

Length modifier h

arg is a short integer.

,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 are separated by array size - 1 commas and output in the specified format.

f Argument type: A floating point number.

Modifier Interpretation

Default functionality

Print a floating point number in NR2 format (a number with at least one digit after the decimal point).

@1

Print an integer in NR1 format. The number is truncated.

@3

Print a floating point number in NR3 format (scientific notation). Precision can also be specified.

field width

Minimum field width of the output number. Any of the six IEEE 488.2 modifiers can also be specified with field width.

Length modifier l

arg is a double float.

Length modifier L

arg is a long double.

,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 are separated by array size - 1 commas and output in the specified format.

s Argument type: A reference to a NULL-terminated string that is sent to the device without change.

Enhanced Format Codes

b Argument type: A location of a block of data.

Flag or Modifier Interpretation

Default functionality

The data block is sent as an IEEE 488.2 <DEFINITE LENGTH ARBITRARY BLOCK RESPONSE DATA>. A count (long integer) must appear as a flag that specifies the number of elements (by default, bytes) in the block. A field width or precision modifier is not allowed with this format code.

* (asterisk)

An asterisk may be present instead of the count. In such a case, two args are used, the first of which is a long integer specifying the count of the number of elements in the data block. The second arg is a reference to the data block. The size of an element is determined by the optional length modifier (see below), and the default is byte width.

Length modifier h

arg points to an array of unsigned short integers (16 bits). The count corresponds to the number of words rather than bytes. The data is swapped and padded into standard IEEE 488.2 format, if native computer representation is different.

Length modifier l

arg points to an array of unsigned long integers. The count specifies the number of long words (32 bits). Each longword data is swapped and padded into standard IEEE 488.2 format, if native computer representation is different.

Length modifier ll

arg points to an array of unsigned long long integers. The count specifies the number of long long words (64 bits). Each longword data is swapped and padded into standard IEEE 488.2 format, if native computer representation is different.

Length modifier z

arg points to an array of floats. The count specifies the number of floating point numbers (32 bits). The numbers are represented in IEEE 754 format, if native computer representation is different.

Length modifier Z

arg points to an array of doubles. The count specifies the number of double floats (64 bits). The numbers will be represented in IEEE 754 format, if native computer representation is different.

B  Argument type: A location of a block of data. The functionality is similar to b, except the data block is sent as an IEEE 488.2 <INDEFINITE LENGTH ARBITRARY BLOCK RESPONSE DATA>. This format involves sending an ASCII LF character with the END indicator set after the last byte of the block.

The END indicator is not appended when LF(\n) is part of a binary data block, as with %b or %B.

y  Argument type: A location of a block of binary data.

Modifier Interpretation

Default functionality

The data block is sent as raw binary data. A count (long integer) must appear as a flag that specifies the number of elements (by default, bytes) in the block. A field width or precision modifier is not allowed with this format code.

* (asterisk)

An asterisk may be present instead of the count. In such a case, two args are used, the first of which is a long integer specifying the count of the number of elements in the data block. The second arg is a reference to the data block. The size of an element is determined by the optional length modifier (see below), and the default is byte width.

Length modifier h

arg points 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 is sent in little endian format; otherwise, the data is sent in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate if native computer representation is different.

Length modifier l

arg points to an array of unsigned long integers (32 bits). The count specifies the number of long words rather than bytes. If the optional !ol byte order modifier is present, the data is sent in little endian format; otherwise, the data is sent in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate if native computer representation is different.

Length modifier ll

arg points to an array of unsigned long long integers (64 bits). The count specifies the number of long long words rather than bytes. If the optional !ol byte order modifier is present, the data is sent in little endian format; otherwise, the data is sent in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate if native computer representation is different.

Length modifier z

arg points to an array of floats. The count specifies the number of floating-point numbers (32 bits). If the optional !ol modifier is present, the data is sent in little endian format; otherwise, the data sent in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate to native computer format.

Length modifier Z

arg points to an array of doubles. The count specifies the number of double floats (64 bits). If the optional !ol modifier is present, the data is sent in little endian format; otherwise, the data sent in standard IEEE 488.2 format. The data will be byte swapped and padded as appropriate to native computer format.

Byte order modifier !ob

Data is sent in standard IEEE 488.2 (big endian) format. This is the default behavior if neither !ob nor !ol is present.

Byte order modifier !ol

Data is sent in little endian format.

Other ANSI C Conversion Codes

For ANSI C compatibility, VISA also supports the following conversion codes for output codes: 'i', 'o', 'u', 'n', 'x', 'X', 'e', 'E', 'g', 'G', and 'p'. For further explanation of these conversion codes, see the ANSI C Standard.

Also refer to your ANSI C documentation for information on the printf function.

Note  VISA will not send out the data across the bus, by default, until a '\n' character is encountered in the format string (not the data stream). You can modify this behavior with the VI_ATTR_WR_BUF_OPER_MODE attribute or with the viFlush() operation.


Related Topics

INSTR Resource

INTFC Resource

SERVANT Resource

SOCKET Resource

VI_ATTR_WR_BUF_OPER_MODE

viFlush

viScanf

viSPrintf

viVPrintf

viVSPrintf

WAS THIS ARTICLE HELPFUL?

Not Helpful