Conventions Throughout this specification you will see the following headings on certain paragraphs. These headings instill special meaning on these paragraphs. Rules must be followed to ensure compatibility with the System Framework. A rule is characterized by the use of the words SHALL and SHALL NOT in bold upper case characters. These words are not used in this manner for any other purpose other than stating rules. Recommendations consist of advice to implementers that will affect the usability of the final device. They are included in this standard to draw attention to particular characteristics that the authors believe to be important to end user success. Permissions are included to authorize specific implementations or uses of system components. A permission is characterized by the use of the word MAY in bold upper case characters. These permissions are granted to ensure specific System Framework components are well defined and can be tested for compatibility and interoperability. Observations spell out implications of rules and bring attention to things that might otherwise be overlooked. They also give the rationale behind certain rules, so that the reader understands why the rule must be followed. A Note on the text of the specification: Any text that appears without heading should be considered as description of the standard and how the architecture was intended to operate. The purpose of this text is to give the reader a deeper understanding of the intentions of the specification including the underlying model and specific required features. As such, the implementer of this standard should take great care to ensure that a particular implementation does not conflict with the text of the standard.
GpibAddressedState public enum GpibAddressedState { Unaddressed = 0, Talker = 1, Listener = 2 } The GpibAddressedState enumeration indicates the GPIB interface is currently addressed to talk or listen, or is not addressed. This enumeration corresponds to the defined values for the VISA VI_ATTR_GPIB_ADDR_STATE attribute.
VISA C implementation, that exception’s StatusCode property SHALL match the value of the status code returned by VISA C. A VISA.NET I/O implementation SHALL NOT throw Ivi.Visa.NativeVisaException or any exception that derives from Ivi.Visa.NativeVisaException unless the VISA.NET implementation is based on an underlying VISA C implementation. Except as noted in RULE 6.1.1, if a VISA.NET I/O session’s implementation is layered over a VISA C implementation, any operation may throw an Ivi.Visa.NativeVisaException with a vendor specific status code that is not listed in the VISA C specifications. VISA.NET implementations may define vendor specific VISA.NET exceptions. Vendor defined VISA.NET exceptions SHALL derive from VisaException directly or indirectly, as appropriate. Vendors should not create a vendor specific VISA.NET exception if there is an applicable .NET framework exception. For example vendors should not define vendor specific VISA.NET exceptions to replace System.ArgumentNullException or System.ArgumentOutOfRangeException. Except as noted in RULE 6.1.1, vendor specific VISA.NET implementations may allow exceptions thrown by the .NET Framework to propagate up to the calling program. Any VISA.NET operation may throw exceptions, particularly .NET Framework exceptions or exceptions, not listed in this specification. In light of the previous two permissions, it is important that calling programs (1) follow .NET guidelines for handling exceptions, (2) not assume that particular exceptions will be returned for a particular error condition (except as noted in RULE 6.1.1), since different vendors may return different errors in the same situation, and (3) not restrict error processing to VISA status codes defined by the VISA sepcifications when an Ivi.Visa.NativeVisaException is caught. Ivi.Visa.NativeVisaException is only thrown when the underlying implementation delegates to a VISA C implementation. A VISA.NET I/O session SHALL NOT throw System.NotImplementedException.
Nearly all session interfaces are either message-based or register-based. All message-based elements are defined in the interface IMessageBasedSession. All VISA.NET message-based session interfaces derive from IMessageBasedSession, and so include this common functionality. Message-based sessions provide access to two different ways of performing message-based I/O. The first is raw I/O, which leaves formatting and parsing tasks (including format buffering) to the calling program. Raw I/O supports asynchronous I/O. The second is formatted I/O, which is capable of some very complex formatting tasks, and supports a wide variety of formatting options. While it migh be tempting to think of formatted I/O for convenience and raw I/O for performance, in fact formatted I/O is highly optimized for performance. Likewise, all register-based elements are defined in the interface IRegisterBasedSession. All VISA.NET register-based session interfaces derive from IRegisterBasedSession, and so include this common functionality. Locking Calling programs can open multiple sessions to a VISA.NET I/O resource simultaneously. Applications can access the VISA.NET I/O resource through these different sessions concurrently. To avoid conflicting behavior, a session accessing a VISA.NET I/O resource might want to restrict other sessions from accessing that resource. VISA defines a locking mechanism to restrict how multiple session access the same resource. These mechanisms are supported by the resource manager Open() method and by the LockResource() and UnlockResource() methods in the IVisaSession interface.
readStatus Indicates how the read terminated. If an END was received, ReadStatus.EndReceived is returned. Otherwise, if a termination character was received and TerminationCharacterEnabled is true, is returned. Otherwise ReadStatus.MaximumCountReached is returned. ReadStatus Name Description Type return value An array of bytes allocated by the method, into which bytes returned by the device are placed. The size of the array returned is the number of bytes actually read. Byte[] The number of bytes that were read and placed into the data array. Int64 This method uses the Ivi.Visa.IoTimeoutException to report a timeout. RETURN
For a particular asynchronous write operation, IVisaAsyncResult.Buffer SHALL contain the bytes that will actually be written to the instrument. For overloads of BeginWrite that take string buffer arguments, IVisaAsyncResult.Buffer contains the equivalent ASCII string after it has been converted from UNICODE. For a particular asynchronous read or write operation, IAsyncResult.AsyncWaitHandle SHALL be signaled after the operation completes.
TypeFormatter A reference to the ITypeFormatter interface implemented by the type formatter that will be used by Printf and Scanf to format and parse the types that it supports. ITypeFormatter TypeFormatter { get; set; }
Printf Writes formatted data to the formatted write buffer. The data is created by replacing each format specifier in the format parameter with the corresponding parameter argument formatted according the format specifier. The data is formatted as ASCII strings, IEEE-488.2 arbitrary blocks, and raw binary blocks. void Printf(String data); void Printf(String format, params object[] args); Name Description Type format The format string, including all format specifiers. String data The string literal to be printed. String args[] A variable number of arguments, each of which is either data to be formatted into the format string using the corresponding format specifiers in the format string, or width, precision, or array size values to be substituted for occurrences of ‘*’ in format specifiers object Printf SHALL throw appropriate exceptions for the following conditions: The format argument is null or an empty string. One or more of the format specifiers in format is not supported. One or more of the format specifiers is not valid. One or more of the format specifiers does not match the data type of the corresponding input argument. The number of format specifiers exceeds the number of input arguments All characters placed in the formatted I/O write buffer SHALL be formatted as ASCII strings, IEEE-488.2 blocks, or raw binary blocks. All characters copied directly from the format parameter SHALL be formatted as ASCII strings. If Printf fails to write a character to the write buffer because it cannot convert the character to an ASCII character, it SHALL throw an exception that describes the problem and identifies the character. For IEEE-488.2 block format specifier types ‘b’, ‘B’, and ‘y’, if the type of the input argument array does not match the size modifier of the block format specifier, the method SHALL throw an ArgumentException exception.
Introduction to Formatted Write Methods Formatted write methods include Write, WriteList, WriteLine, WriteLineList, WriteBinary, and WriteBinaryAndFlush in the IMessageBasedFormattedIO interface. The section that describes each method also includes the equivalent Printf format specifier. To determine the equivalent behavior, refer to sections 9.4.8.3, Printf Format Specifier Usage Summary and 9.4.9, Printf for details.
WriteLine Performs the following operations in order: Converts the data specified to an ASCII string. The data is followed by a new line. Appends the resulting string to the write buffer. Writes the buffer to the instrument. Sends an END to the instrument if SendEndEnabled is true. Flushes the buffer. void WriteLine(); void WriteLine(Char data); void WriteLine(String data); void WriteLine(Int64 data); void WriteLine(UInt64 data); void WriteLine(Double data); Name Description Type data A single character, string, integer, or real number to be converted to an ASCII string and sent to the instrument. Char, String, Int64, UInt64, Double PRINTF The WriteLine method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Printf, as shown in the following table. WriteLine Method Equivalent Printf Call void WriteLine(Char data); Printf(“%c\n”), data) void WriteLine(String data); Printf(“%s\n”), data) void WriteLine(Int64 data); Printf(“%@1d\n”), data) void WriteLine(UInt64 data); Printf(“%@1u\n”), data) void WriteLine(Double data); Printf(“%@2f\n”), data)
data An array of numbers to be converted to an ASCII separated list sent to the instrument. The separator character is a comma. Byte[], SByte[], Int16[], UInt16[], Int32[], UInt32[], Int64[], Uint64[], Single[], Double[] index The index of the first element from data to be sent to the instrument. Int64 count The number of elements from data to be sent to the instrument, starting from index. count must be positive, and index + count <= data.length. Int64 PRINTF The WriteList method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Printf, as shown in the following table. WriteList Method Equivalent Printf Call void WriteList(Byte[] data); void WriteList(UInt16[] data); void WriteList(UInt32[] data); void WriteList(UInt64[] data); Printf(“%@1,u”, data) void WriteList(SByte[] data); void WriteList(Int16[] data); void WriteList(Int32[] data); void WriteList(Int64[] data); Printf(“%@1,d”, data) void WriteList(Single[] data); void WriteList(Double[] data); Printf(“%@2,f”, data)
data An array of numbers to be converted to an ASCII separated list sent to the instrument. The separator character is a comma. Byte[], SByte[], Int16[], UInt16[], Int32[], UInt32[], Int64[], Uint64[], Single[], Double[] index The index of the first element from data to be sent to the instrument. Int64 count The number of elements from data to be sent to the instrument, starting from index. count must be positive, and index + count <= data.length. Int64 PRINTF The WriteLineList method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Printf, as shown in the following table. WriteLineList Method Equivalent Printf Call void WriteLineList(Byte[] data); void WriteLineList(UInt16[] data); void WriteLineList(UInt32[] data); void WriteLineList(UInt64[] data); Printf(“%@1,u\n”, data) void WriteLineList(SByte[] data); void WriteLineList(Int16[] data); void WriteLineList(Int32[] data); void WriteLineList(Int64[] data); Printf(“%@1,d\n”, data) void WriteLineList(Single[] data); void WriteLineList(Double[] data); Printf(“%@2,f\n”, data)
Read Reads the specified data from the formatted read buffer, and converts it to the type specified by the return type of the method. Char ReadChar(); Int64 ReadInt64(); UInt64 ReadUInt64(); Double ReadDouble(); Type Description Char, Int64, UInt64, Double The value read from the formatted read buffer, converted to the specified type. The ReadType method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Scanf, as shown in the following table. ReadType Method Equivalent Scanf Call Char ReadChar(); Scanf(“%c”, out result); (return result) UInt64 ReadUInt64(); Int64 ReadInt64(); Scanf(“%d”, out result); (return result) Double ReadDouble(); Scanf(“%g”, out result); (return result)
ReadLine (String) Reads a string from the formatted read buffer. The read stops when an EOL character is reached. String ReadLine(); Int32 ReadLine(StringBuilder data); Name Description Type data A StringBuilder object created by the calling program to hold the string to be read from the formatted read buffer. This method appends the output string to data. StringBuilder RETURN Type Description String The string actually read from the formatted read buffer. Int32 The number of characters actually appended to the StringBuilder parameter. The ReadLine method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Scanf, as shown in the following table. ReadLine Method Equivalent Scanf Call String ReadLine(); Scanf(“%T”, out result); (return result) Int32 ReadLine(StringBuilder data); Scanf(“%T”, out data); (return data.Length)
Type Description Byte[], SByte[], Int16[], UInt16[], Int32[], UInt32[], Int64[], UInt64[], Single[], Double[] The values read from the formatted read buffer, converted to the specified type. Int64 The number of elements in the list actually read from the formatted read buffer. The ReadLineListOfType method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Scanf, as shown in the following table. ReadLineListOfType Method Equivalent Scanf Call Byte[] ReadLineListOfByte(); UInt16[] ReadLineListOfUInt16(); UInt32[] ReadLineListOfUInt32(); UInt64[] ReadLineListOfUInt64(); Scanf(“%,u%*T”, out result); (return result) SByte[] ReadLineListOfSByte(); Int16[] ReadLineListOfInt16(); Int32[] ReadLineListOfInt32(); Int64[] ReadLineListOfInt64(); Scanf(“%,d%*T”, out result); (return result) Single[] ReadLineListOfSingle(); Double[] ReadLineListOfDouble(); Scanf(“%,g%*T”, out result); (return result)
Int16[] ReadBinaryBlockOfInt16(); UInt16[] ReadBinaryBlockOfUInt16(); Scanf(“%!olhy”, out result) (return result) Int32[] ReadBinaryBlockOfInt32(); UInt32[] ReadBinaryBlockOfUInt32(); Scanf(“%!olly”, out result) (return result) Int64[] ReadBinaryBlockOfInt64(); UInt64[] ReadBinaryBlockOfUInt64(); Scanf(“%!ollly”, out result) (return result) Single[] ReadBinaryBlockOfSingle(); ReadBinaryBlockOfSingle() for raw little endian arrays and the corresponding Scanf format specifier (%!olzy) are not supported at this time. Double[] ReadBinaryBlockOfDouble(); ReadBinaryBlockOfDouble() for raw little endian arrays and the corresponding Scanf format specifier (%!olZy) are not supported at this time. The way that the binary data is treated is not affected by the value of the seekToBlock parameter.
ReadUntilEnd Reads an arbitrary number of characters until an END or termination character is found. The method stops reading at the first END or termination character. The string returned includes the character with the END indicator or termination character. If the underlying protocol does not support END or the termination character, this method may time out or exhibit other implementation-specific behavior. String ReadUntilEnd(); RETURN Type Description String The string actually read from the formatted read buffer. The ReadUntilEnd method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Scanf, as shown in the following table. ReadUntilEnd Method Equivalent Scanf Call String ReadUntilEnd(); Scanf(“%t”, out result); (return result)
Skip Reads and removes up to count characters from the formatted read buffer. The method will read additional characters from the instrument to perform this operation, if necessary, but will not skip over an END. void Skip(Int64 count); Name Description Type count The number of characters to remove from the buffer. Int64 The Skip method implementations exhibit exactly the same behavior (but not necessarily implemented exactly as shown) as a corresponding call to Scanf, as shown in the following table, where the data read is discarded as indicated by the ‘*’ flag. Skip Method Equivalent Scanf Call void Skip(Int64 count); Scanf(“%*<count>c”);
MessageBasedFormattedIO Constructors Create an instance of the MessageBasedFormattedIO class. public MessageBasedFormattedIO(IMessageBasedSession session) Name Description Type session A reference to the message based session to be used by formatted I/O to perform lower level I/O operations. IMessageBasedSession The session parameter must reference a complete implementation of IMessageBasedSession, as this is required for the proper operation of the MessageBasedFormattedIO class.
IF a vendor-specific resource manager can create any particular resource on a given hardware interface, THEN it SHALL be capable of creating all available resources on that interface. The vendor-specific resource manager’s Find() method, with an pattern argument equal to “*”, will return all of the available resources for the vendor’s VISA.NET implementation. The vendor-specific resource manager SHALL be registered as described in Section 18.2.3, VISA.NET Registry Entries.