Formatting Basics

Formatted I/O can convert or parse a variety of .NET standard data types to and from instrument-friendly formats:

Write methods format one item at a time; Printf methods can format multiple items at a time.
Read methods parse one item at a time; Scanf methods can format multiple items at a time.
In general, Printf and Scanf are more flexible, but require knowledge of format specifiers, while Write and Read methods are simpler, but allow less formatting control.

Formatted I/O assumes that all string data being passed to an instrument is formatted as 8-bit ASCII strings. All characters are single-byte characters. While it's possible to send multi-byte characters to instruments using Formatted I/O with raw binary arrays, it is not intuitive.

Formatting with Printf Methods

Each overload of Printf accepts a format string as the first parameter. The format string may include zero or more format specifiers. For each format specifier, there is a corresponding parameter to the Printf method. Printf places characters from the format string into the write buffer until it reaches a format specifier. It then formats the data from the corresponding parameter according to the format specifier and places the results in the write buffer. In most cases the characters in the write buffer are single-character ASCII strings, but you can place binary data in the buffer by using IEEE 488.2 arbitrary block or raw binary format specifiers.

There are two relatively simple Printf methods, Printf(String, Object[]) and PrintfAndFlush(String, Object[]), each of which takes a variable number of arguments. These are as efficient as possible except in the case where arrays are sent to an instrument in raw binary form. In this case the arrays are copied out of the parameter and into the buffer. To eliminate the redundant copy, two additional methods are available that allow passing in an array reference; the referenced array is written directly to the output stream. PrintfArray and PrintfArrayAndFlush can only write one array to the output stream per call. Note that PrintfArray and PrintfArrayAndFlush are inherently unsafe in .NET terms.

Parsing with Scanf Methods

As with Printf, each overload of Scanf accepts a format string as the first parameter. The format string may include zero or more format specifiers. For each format specifier, there is a corresponding out argument to the Scanf method. Scanf matches characters from the format string to characters in the read buffer until it reaches a format specifier. It then parses data from the read buffer according to the format specifier and places the resulting value in the corresponding output argument. In most cases the characters in the read buffer are single-character ASCII strings, but binary arrays may be read from the buffer by using IEEE 488.2 arbitrary block or raw binary format specifiers.

There is one relatively simple Scanf method, Scanf. However, there are 14 overloads of this method, each with one to seven data output parameters for formatted values. This is because .NET does not support variable output arguments.

Scanf is as efficient as possible except in the case where arrays are being read from an instrument in raw binary form. In this case, the arrays are copied out of the read buffer and into the corresponding output variable. To eliminate the redundant copy, an additional method with several overloads is available that passes array references directly back to the calling program. ScanfArray can only read and return one array to the calling program. Note that ScanfArray is inherently unsafe in .NET terms.

Formatting with Read and Write Methods

Write and Read methods format or read one item of data at a time. For Read methods, the name of the method generally tells what type of data the method handles. For example, ReadDouble returns a double. For Write methods, the data type of the first input parameter generally tells what type of data the method handles. For example, Write(Double) formats a double.

In general, each Write and Read method corresponds to Printf or Scanf with a particular format specifier. The reference documentation for each Write and Read method indicates the corresponding format specifier. As with Scanf and Printf, some overloads of Write and Read methods use direct array references for performance, and are inherently unsafe in .NET terms.

Formatted I/O Method Overloads

VISA.NET uses quite a few method overloads throughout, but the most extensive use of overloads is in the Formatted I/O interface. Printf, Scanf, Write, and Read methods are all overloaded.

Method overloads must have different argument lists. The argument names do not matter; the types must be different. For example, overloads void Foo(int Bob), void Foo(int Bob, int Fred), and void Foo(string Bob) are allowed to coexist as overloads of Foo because the list of argument types is different for each overload. On the other hand, void Foo(int Bob) and void Foo(int Fred) cannot both be overloads of Foo because both take a single int argument.

Methods cannot be overloaded if the only difference between them is the return type. For example, int Foo() and string Foo() cannot both be overloads of Foo.

In general, methods that write to an instrument have more overloads than methods that read from an instrument. Consider the Write method. There are five overloads to Write that take a single Char, Double, Int64, String, or UInt64 argument, respectively. That argument is written to the instrument, and so is necessarily input to the method.

On the other hand, there are five different read methods that correspond to the write methods. Read methods read a single value from the instrument, and that value is naturally a return value. (Out arguments should only be used if more than one value needs to be returned from a method.) Since methods cannot be overloaded unless the argument lists differ, the Read methods have different names. The list of Read methods that correspond to the Write overloads listed above are:

The type of data being read or written is not the only reason for overloads. Other reasons include overloads that specify a certain number of array elements, those that specify a starting index in an array, etc.

In general, when using a Formatted I/O method, be sure to understand what overloads are available, and what each overload does. There are usually patterns to the overloads that exist for groups of methods, and understanding the patterns will help you choose the right overload.