Syntax
viPrintf(ViSession vi, ViString writeFmt, arg1, arg2,...);
Description
This formatted IO function converts, formats, and sends the parameters arg1, arg2, ... to the device as specified by the format string. Before sending the data, the function formats the arg characters in the parameter list as specified in the writeFmt string.
Note: The viWrite operation performs the actual low-level I/O to the device. Therefore, you should not use the viWrite and viPrintf operations in the same session.
Note: VISA functions that take a variable number of parameters (e.g., viPrintf, viScanf, and viQueryf) are not callable from Visual Basic. Use the corresponding viVPrintf, viVScanf, and viVQueryf functions instead.
Parameters
|
Name |
Dir |
Type |
Description |
|
vi |
IN |
ViSession |
Unique logical identifier to a session. |
|
writeFmt |
IN |
ViString |
String describing the format for arguments. |
|
arg1, arg2 |
IN |
N/A |
Parameters format string is applied to. |
The writeFmt string can include regular character sequences, special formatting characters, and format specifiers. The regular characters (including spaces) are written to the device unchanged. Special characters consist of a ‘\’ (backslash) followed by a character. The format specifier sequence consists of ‘%’ (percent) followed by an optional modifier, followed by a format code.
For example, writefmt could be the string: "The value is '%h5d'". In this example the characters "The value is " are sent to the device unchanged. Then there is the modifier "%h" and the format code" 5d" meaning the argument must be a short or unsigned short (%h) and a five digit integer (5d) .
writefmt Special Formatting Characters
The following table lists the possible writefmt special characters and what they send to the 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. |
|
|
\" |
Sends the ASCII double-quote (") character. |
|
|
\\ |
Sends a backslash (\) character. |
writeFmt Format Specifiers
Format specifiers consist of a % (percent) followed by an optional modifier, followed by a format code. It is in the form:
%[modifier]format code
where format code specifies which data type in which the argument is represented. The modifiers are optional codes that describe the target data.
writefmt Modifiers
Every format specifier starts with the % character and ends with a conversion character (format code). 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.
|
Modifier |
For use with |
|
|
|
An integer specifying field width. |
d, f, s |
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 on the right if a negative modifier is used, e.g., –5d). 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. Special case: For the @H, @Q, and @B flags, the field width includes the #H, #!, and #B strings, respectively. |
|
|
An integer specifying precision. |
d, f, s |
The precision string consists of a string of decimal digits. A . (decimal point) must prefix the precision string. 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. The precision string specifies the following:
|
|
|
h
|
d, b, B |
The h modifier promotes the argument to a short or unsigned short, depending on the format code type. |
|
|
l |
d, f, b, B |
The l modifier (lower case letter "L") promotes the argument to a long or unsigned long. |
|
|
L |
f |
The L modifier promotes the argument to a long double parameter. |
|
|
z |
b, B |
The z modifier promotes the argument to an array of floats. |
|
|
Z |
b, B |
The Z modifier promotes the argument to an array of doubles. |
|
|
A comma (,) followed by an integer n, where n represents the array size. |
%d, %f |
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 "," 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, %f |
Converts to an IEEE 488.2 defined NR1 compatible number, which is an integer without any decimal point (e.g., 123). |
|
|
@2 |
%d, %f |
Converts to an IEEE 488.2 defined NR2 compatible number. The NR2 number has at least one digit after the decimal point (e.g., 123.45). |
|
|
@3 |
%d, %f |
Converts to an IEEE 488.2 defined NR3 compatible number. An NR3 number is a floating point number represented in an exponential form (e.g., 1.2345E-67). |
|
|
@H |
%d, %f |
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 the form #HXXX.., where XXX.. is a hexadecimal number (e.g., #HAF35B). |
|
|
@Q |
%d, %f |
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 (e.g., #Q71234). |
|
|
@B |
%d, %f |
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 (e.g., #B011101001). |
writeFmt Format Codes
|
|
For use with |
|
|
|
% |
Send the ASCII percent (%) character. |
||
|
c |
Argument type: A character to be sent. |
||
|
d |
Argument type: An integer. |
||
|
Default functionality |
Print integer in NR1 format (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 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 |
||
|
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. |
||
|
b |
Argument type: A location of a block of data. |
||
|
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), the default being byte width. |
||
|
Length modifier h |
The data block is assumed to be 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 (big endian) format if native computer representation is different. |
||
|
Length modifier l |
The data block is assumed to be an array of unsigned long integers. The count corresponds to the number of longwords (32 bits). Each longword data is swapped and padded into standard IEEE 488.2 (big endian) format if native computer representation is different. |
||
|
Length modifier z |
The data block is assumed to be an array of floats. The count corresponds to the number of floating point numbers (32 bits). The numbers are represented in IEEE 754 (big endian) format if native computer representation is different. |
||
|
Length modifier Z |
The data block is assumed to be an array of doubles. The count corresponds to the number of double floats (64 bits). The numbers are represented in IEEE 754 (big endian) 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. |
||
|
y |
Argument type: A location of block binary data. |
||
|
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. |
||
|
* |
A* (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), the default being byte width. |
||
|
Length modifier h |
The data block is 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. Data will be byte swapped and padded as appropriate if native computer representation is different. |
||
|
Length Modifier l |
The data block is an array of unsigned long integers (32 bits) . The count corresponds to the number of longwords 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 IEE 488.2 format. Data will be byte swapped and padded as appropriate if native computer representation is different. |
||
|
Byte order modifier !ob |
Data is sent in standard IEE 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. |
Return Values
|
Type ViStatus |
This is the function return status. It returns either a completion code or an error code as follows. |
|
Completion Code |
Description |
|
VI_SUCCESS |
Parameters were successfully formatted. |
|
Error Codes |
Description |
|
VI_ERROR_ALLOC |
The system could not allocate a formatted I/O buffer because of insufficient resources. |
|
VI_ERROR_INV_FMT |
A format specifier in the writeFmt string is invalid. |
|
VI_ERROR_INV_SESSION |
The given session or object reference is invalid (both are the same value). |
|
VI_ERROR_IO |
Could not perform write function because of I/O error. |
|
VI_ERROR_NSUP_FMT |
A format specifier in the writeFmt string is not supported. |
|
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_TMO |
Timeout expired before write function completed. |
Additional Notes
- Up to four arg parameters may be required to satisfy a % format conversion request. In the case where multiple args are required, they must appear in the following order:
- field width (* with %d, %f, or %s) if used
- precision (* with %d, %f, or %s) if used
- array_size (* with %b, %B, %y, %d, or %f) if used
- value to convert
This assumes that a * is provided for both the field width and the precision
modifiers in a %s, %d, or %f. The third arg
parameter is used to satisfy a ",*" comma operator. The fourth arg parameter is the value to
be converted itself.
See Also