AddressSpace public enum AddressSpace { VxiA16 = 0, VxiA24 = 1, VxiA32 = 2, VxiA64 = 3, PxiConfiguration = 4, PxiBar0 = 5, PxiBar1 = 6, PxiBar2 = 7, PxiBar3 = 8, PxiBar4 = 9, PxiBar5 = 10, PxiAllocation = 11 } The AddressSpace enumeration indicates the bus address space used by VXI or PXI devices. This enumeration corresponds to the defined values for the space parameter that all register based operation include.
IOProtocol public enum IOProtocol { Normal = 0, Fdc = 1, HS488 = 2, Ieee4882 = 3, UsbTmcVendor = 4 } The IOProtocol enumeration indicates which protocol to use on a particular session. Choices are dependent on the session. This enumeration corresponds to the defined values for VISA’s VI_ATTR_IO_PROT attribute.
SerialFlowControlModes [Flags] public enum SerialFlowControlModes { None = 0, XOnXOff = 1, RtsCts = 2, DtrDsr = 4 } The SerialFlowControlModes enumeration indicates the type of flow control used by the Serial connection. This enumeration corresponds to the defined values for the VISA attribute VI_ATTR_ASRL_FLOW_CNTRL.
message A message appropriate to the error being reported. For the two constructors with args arguments, the message is a format string capable of formatting the accompanying arguments. StatusCodes innerException The exception that is the cause of the current exception. If the innerException parameter is not null, the current exception is raised in a catch block that handles the inner exception. System.Exception or derived type TypeFormatterException is intended for use by objects that implement the ITypeFormatter interface. Note that while the ITypeFormatter interface and TypeFormatterException are defined in the VISA.NET Shared Components, objects that implement the ITypeFormatter interface are not provided. The following guidelines are provided for selecting an appropriate constructor when throwing TypeFormatterException from an object that implements ITypeFormatter. The first two constructors in the above list, and the last, will typically not be used. The two constructors that take a type argument without the instrumentResponse argument, and the two constructors that take an obj argument, are typically used to throw Printf formatting errors. The two constructors that take a type argument with the instrumentResponse argument are typically used to throw Scanf parsing errors.
GetMacroNameFromStatusCode() Given a VISA C error status code, this method returns the name of the VISA C defined constant with the leading “VI_” removed. static String GetMacroNameFromStatusCode(Int32 status) {…} Name Description Base Type status The error status code. System.Int32 Return Value The name of the VISA C defined constant with the leading “VI_” removed System.String
VISA.NET Hardware Events VISA.NET hardware events are used by VISA.NET sessions to report things that the calling program may need to know about. For the most part, these events are related to the I/O hardware associated with the session – interrupts, service requests, triggers, and so on. (These events are designated hardware events to distinguish them from notifications connected with asynchronous I/O. Asynchronous I/O is described in Section 9.2.2, , along with associated notification mechanisms.)
INativeVisaEventArgs Interface The VisaEventArgs class communicates the event being fired. For events defined as part of this specification, the event is identified by a member of the EventType enumeration. For vendor specific events, each event is identified by a unique integer. Inputs Description Type attribute A constant that identifies a VISA standard attribute. The type of the method must match the type of the attribute. NativeVisaAttribute A constant that identifies a VISA standard or vendor-defined attribute. The type of the method must match the type of the attribute. Int32 Inputs Description Type EventArgs An event args reference for the native C event. This may reference an object that derives from EventArgs, if the event handler for the event specified by the EventArg.EventType or EventArg.CustomEventType properties uses a derived class. EventArgs VISA
Event Methods As mentioned above, VISA.NET event methods include EnableEvent(), DisableEvent(), DiscardEvent(), and WaitOnEvent(), which exactly correspond to the C functions viEnableEvent() (called with an event mechanism of VI_QUEUE), viDisableEvent(), viDiscardEvent(), and viWaitOnEvent(). These methods are part of IVisaSession, and so are included with every type of VISA.NET session. Refer to VPP-3.4: The VISA Library, section 3.7, Event Services, and particularly section 3.7.1, Event Handling and Processing, section 3.7.31, viEnableEvent, section 3.7.3.2, viDisableEvent, section 3.7.3.3, viDiscardEvent, and section 3.7.3.4, viWaitOnEvent, for details. For the definition of the event methods in VISA.NET, refer to section 8.3, When using event methods, the event mechanism is always a queue (VI_QUEUE). The return type of the WaitOnEvent method is defined as VisaEventArgs, which gives the client information about the event from the server. This is the same VisaEventArgs that is the base class for all of the event args defined for VISA.NET’s .NET events. The data returned by the WaitOnEvent method is either VisaEventArgs or derived from VisaEventArgs. The exact return type can be inferred from the value of VisaEventArgs.EventType and VisaEventArgs.CustomEventType.
Read All overloads of the Read method read bytes from the device and return them as an array of bytes. The overloads of the Read method that return an array of bytes allocate the array themselves. When using the overload of the Read method that returns an Int64, the calling program must allocate the array before making the call, and the array must contain at least index + count elements. Bytes are returned exactly as they are read from the device, in exactly the same order. Reading continues until one of the following conditions is met: An END indicator is read from the data coming from the device. This will only happen if END is supported by the protocol being used, and is enabled. A termination character is read in the data coming from the device, and IMessageBasedSession.TerminationCharacterEnabled is true. In this case, the termination character is included in the data buffer. Exactly count bytes have been read from the device, if the overload includes the count argument. The amount of time spent reading (or trying to read) data from the device exceeds IVisaSession.TimeoutMilliseconds, in which case an exception is thrown. Byte[] Read(); Byte[] Read(Int64 count); Byte[] Read(Int64 count, out ReadStatus readStatus); void Read(Byte[] buffer, Int64 index, Int64 count, out Int64 actualCount, out ReadStatus readStatus); unsafe void Read(Byte* buffer, Int64 index, Int64 count, out Int64 actualCount, out ReadStatus readStatus); Name Description Type count The maximum number of bytes to be returned from the device. The default is to read until an end condition is received. Int64 actualCount The actual count of bytes stored in the buffer parameter during the read operation. Int64 index In the array, the index where the method places the first byte returned from the device. The default is 0. Int64 buffer An array of bytes allocated by the calling program, into which bytes returned by the device are placed. A reference to the array Byte[] Byte*
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.
BeginRead Begins an asynchronous read. The calling program must call EndRead exactly once for every call to BeginRead. Failing to end an asynchronous operation before beginning another one can cause undesirable behavior such as a memory leak. IVisaAsyncResult BeginRead(Int32 count); IVisaAsyncResult BeginRead(Int32 count, Object state); IVisaAsyncResult BeginRead(Int32 count, VisaAsyncCallback callback, Object state); IVisaAsyncResult BeginRead(Byte[] buffer); IVisaAsyncResult BeginRead(Byte[] buffer, Object state); IVisaAsyncResult BeginRead(Byte[] buffer, Int64 index, Int64 count); IVisaAsyncResult BeginRead(Byte[] buffer, Int64 index, Int64 count, Object state); IVisaAsyncResult BeginRead(Byte[] buffer, VisaAsyncCallback callback, Object state); IVisaAsyncResult BeginRead(Byte[] buffer, Int64 index, Int64 count, VisaAsyncCallback callback, Object state); Name Description Type buffer The buffer to read data into. For overloads that include buffer, the calling program is expected to allocate the buffer. For overloads that do not include buffer, the implementation of this method allocates the buffer. Byte[] count The maximum number of bytes to read. For overloads that do not include count, the default is the buffer size. Int64 index The byte offset in buffer at which to begin writing the data read. For overloads that do not include index, the default is 0. Int64 callback The method to be called when the asynchronous read operation is completed. Overloads that do not include callback leave it to the calling program to check for completion. . IVisaAsyncCallback
state A reference to an object that contains arbitrary information of interest to the calling program, and related to the asynchronous operation. This allows the asynchronous operation to provide the reference back to the calling program (as context) when the operation is complete. This is particularly useful when callbacks are used. Note that the object is not used by the asynchronous operation. Object Return Value Description Type return value An object that implements IVisaAsyncResult, which represents the status of an asynchronous operation. The object is constructed by this method. The meaning of IVisaAsyncResult members in this context is listed below: IVisaAsyncResult .AsyncState A reference to the state object passed as a parameter to this method. This will be null if no state object was passed to this method. Object .AsyncWaitHandle A handle that can be used to wait for the read to complete. WaitHandle true if the read operation completed synchronously, otherwise false. Boolean .IsCompleted true if the asynchronous operation is complete, otherwise false. Boolean .IsAborted IsAborted is always false when returned by this method since this method begins the asynchronous read operation. Boolean .Buffer Undefined. Byte[] .Count Undefined. Int64 Some exceptions (such as argument exceptions) are thrown immediately from this method. Errors that occur during an asynchronous read request, such as an instrument communication failure during the IO request, occur on the thread pool thread and become visible upon a call to EndRead. If a call by a session class to the callback method fails, the failure may be ignored. VISA.NET I/O implementations should not assume a client callback will return in any timeframe. Calling programs may execute blocking waits from callbacks. If a VISA.NET I/O resource component calls a callback, and the callback blocks in the same thread on which the callback was called, the callback will not return until the block completes. The callback and state parameters are allowed to be null. If CompletedSynchronously is true when this method returns, IsCompleted shall also be true.
EndWrite Waits for the pending asynchronous write to complete. This method is always blocking. void EndWrite(IVisaAsyncResult result); The following table reflects the value of the result parameter upon completion of this method. Name Description Type result The reference to the asynchronous request. The meaning of IVisaAsyncResult members after the call completes is listed below: IVisaAsyncResult .AsyncState Unaffected by this method. Object .AsyncWaitHandle Not specified after this method completes. WaitHandle Unaffected by this method. Boolean .IsCompleted IsCompleted is always true when returned by this method since this method waits until the asynchronous operation ends. Boolean .IsAborted Unaffected by this method. Boolean .Buffer The buffer that was passed into the call to BeginWrite that initiated this asynchronous operation, or a buffer that includes only the bytes that were actually to be written by this asynchronous operation. Byte[] .Count The number of bytes actually written by this operation. Int64 Some exceptions (such as argument exceptions) are thrown immediately from this method. In addition, any errors detected during the asynchronous operation will be thrown as exceptions from this method. This method uses the Ivi.Visa.IoTimeoutException to report a timeout. The Buffer value returned as part of the IVisaAsyncResult return value for this method is the same as the Buffer value returned as part of the IVisaAsyncResult return value for BeginWrite().
Parse Returns an object of type type, the value of which is determined by parsing the data string. Object Parse(Type objectType, String data); Name Description Type type The data type of the returned object. Type data The string data which is parsed to create the object returned by this method. The type formatter object must be able to parse data and convert it to an object of type type. String Return Value Description Type return value An object of type type, the value of which is determined by parsing the data string. Object This method throws the Ivi.Visa. TypeFormatterException when data cannot be parsed to an object of type type by the type formatter object.
IMessageBasedFormattedIO This section summarizes IMessageBasedFormattedIO. Note that IMessageBasedFormattedIO allows calling programs to use a variety of common data types. Given the necessary formatting direction, formatted I/O methods format and parse instrument string or buffer data appropriately. IMessageBasedFormattedIO is all synchronous. IMessageBasedSession provides a property that returns a reference to IMessageBasedFormattedIO. This property is the recommended way to access the IMessageBasedFormattedIO interface from a message-based session. The IMessageBasedFormattedIO interface declaration is shown below. The body of the interface is documented in the sections that document individual properties and methods. public interface IMessageBasedFormattedIO Refer to section 9.5, FormattedIO Implementations, for information about formatted I/O implementation options, and the standard IVI implementation of IMessageBasedFormattedIO in particular. VISA The IMessageBasedFormattedIO interface has several .NET properties that correspond to attributes defined in VISA. The following table shows property-attribute equivalence for IMessageBasedFormattedIO. Property Name VISA Attribute Name BinaryEncoding N/A ReadBufferSize VI_ATTR_RD_BUF_SIZE WriteBufferSize VI_ATTR_WR_BUF_SIZE TypeFormatter N/A The IMessageBasedFormattedIO interface has several .NET methods that correspond to functions defined in VISA. The following table shows method-function correspondence for IMessageBasedFormattedIO. Method Name VISA Method Name DiscardBuffers viFlush FlushWrite viFlush Skip, SkipUntilEnd viScanf with %* modifier Printf viPrintf PrintfAndFlush PrintArray PrintArrayAndFlush Scanf viScanf ScanfArray Write viPrintf with specific format specifiers. WriteLine viPrintf with specific format specifiers. WriteList viPrintf with specific format specifiers.
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; }
FlushWrite Flushes all the data from the write buffer and sends it to the instrument. If an exception occurs during this method, the buffer will be cleared. The calling program does not need to explicitly call FlushWrite or DiscardBuffers before attempting another Write or Printf operation. void FlushWrite(Boolean sendEnd); The FlushWritemethod SHALL send the buffer to the instrument with END if sendEnd is true, otherwise it shall send the buffer without END. If the SendEndEnabled property is different from the value of the sendEnd parameter, the FlushWrite method SHALL change it on the I/O session, commit the write buffer, and then restore it. FlushWrite method SHALL NOT change the characters in the buffer. For example, it will not add a termchar to the contents of the buffer.
PrintfAndFlush The behavior for PrintfAndFlush is the same as Printf followed by a FlushWrite with sendEnd equal to true. If an exception occurs during this method, the buffer will be cleared. The calling program does not need to explicitly call FlushWrite or DiscardBuffers before attempting another Write or Printf operation. void PrintfAndFlush(String data); void PrintfAndFlush(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
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 implementated 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 implementated 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)
ReadString Reads a string from the formatted read buffer. String ReadString(); String ReadString(Int32 count); Int32 ReadString(StringBuilder data); Int32 ReadString(StringBuilder data, Int32 count); 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 count The number of characters to be read from the read buffer. Int32 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 ReadString method implementations exhibit exactly the same behavior (but not necessarily implementated exactly as shown) as a corresponding call to Scanf, as shown in the following table. ReadString Method Equivalent Scanf Call String ReadString(); Scanf(“%s”, out result); (return result) Int32 ReadString(StringBuilder data); Scanf(“%s”, out data); (return data.Length) String ReadString(Int32 count); Scanf(“%#s”, count, out result); (return result) Int32 ReadString(StringBuilder data, Int32 count); Scanf(“%#s”, count, out data); (return data.Length)
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 implementated 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)
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 ReadListOfType method implementations exhibit exactly the same behavior (but not necessarily implementated exactly as shown) as a corresponding call to Scanf, as shown in the following table. ReadListOfType Method Equivalent Scanf Call Byte[] ReadListOfByte(); UInt16[] ReadListOfUInt16(); UInt32[] ReadListOfUInt32(); UInt64[] ReadListOfUInt64(); Scanf(“%,u”, out result); (return result) SByte[] ReadListOfSByte(); Int16[] ReadListOfInt16(); Int32[] ReadListOfInt32(); Int64[] ReadListOfInt64(); Scanf(“%,d”, out result); (return result) Single[] ReadListOfSingle(); Double[] ReadListOfDouble(); Scanf(“%,g”, out result); (return result)
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 implementated 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.
Byte[] ReadLineBinaryBlockOfByte(); SByte[] ReadLineBinaryBlockOfSByte(); Scanf(“%!oly%*T”, out result) (return result) Int16[] ReadLineBinaryBlockOfInt16(); UInt16[] ReadLineBinaryBlockOfUInt16(); Scanf(“%!olhy%*T”, out result) (return result) Int32[] ReadLineBinaryBlockOfInt32(); UInt32[] ReadLineBinaryBlockOfUInt32(); Single[] ReadLineBinaryBlockOfSingle(); Scanf(“%!olly%*T”, out result) (return result) Int64[] ReadLineBinaryBlockOfInt32(); UInt64[] ReadLineBinaryBlockOfUInt32(); Double[] ReadLineBinaryBlockOfDouble(); Scanf(“%!ollly%*T”, out result) (return result) Single[] ReadLineBinaryBlockOfSingle(); ReadLineBinaryBlockOfSingle() for raw little endian arrays and the corresponding Scanf format specifier (%!olzy) are not supported at this time. Double[] ReadLineBinaryBlockOfDouble(); ReadLineBinaryBlockOfDouble() 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.
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.