Systems Alliance
VPP-4.3: The VISA Library
February 26, 2016
Revision 5.7
Systems Alliance
VPP-4.3 Revision History
This section is an overview of the revision history of the VPP-4.3 specification.
Revision 1.0, December 29, 1995
Original VISA document. Changes from VISA Transition Library include locking, asynchronous I/O, 32-bit register access, block moves, shared memory operations, and serial interface support.
Revision 1.1, January 22, 1997
Added new attributes, error codes, events, and formatted I/O modifiers.
Revision 2.0, December 5, 1997
Added error handling event, more formatted I/O operations, more serial attributes and extended searching capabilities.
Revision 2.0.1, December 4, 1998
Added new types to visatype.h for instrument drivers. Added new modes to give more robust functionality to viGpibControlREN. Updated information regarding contacting the Alliance.
Revision 2.2, November 19, 1999
Added new resource classes for GPIB (INTFC and SERVANT), VXI (BACKPLANE and SERVANT), and TCPIP (INSTR, SOCKET, and SERVANT).
Revision 3.0 Draft, January 28, 2003
Added new resource class for USB (INSTR). Added extended parsing capability.
Revision 3.0, January 15, 2004
Approved at IVI Board of Directors meeting.
Revision 4.0 Draft, May 16, 2006
Added new resource class for PXI (INSTR) to incorporate PXISA extensions. Added 64-bit extensions for register-based operations. Added support for new WIN64 framework.
Revision 4.0, October 12, 2006
Approved at IVI Board of Directors meeting.
Revision 4.1, February 14, 2008
Updated the introduction to reflect the IVI Foundation organization changes. Replaced Notice with text used by IVI Foundation specifications.
Revision 4.1, April 14, 2008
Editorial change to update the IVI Foundation contact information in the Important Information section to remove obsolete address information and refer only to the IVI Foundation web site.
Revision 4.2, October 16, 2008
Tightened requirements for resource strings returned by viFindRsrc, viParseRsrc, and viParseRsrcEx to ensure that they return identical strings for use by the new VISA Router component.
Revision 5.0, June 9, 2010
Added support for HiSLIP devices under the TCPIP INSTR designation. This includes updates to the resource string and new attributes. Also added format specifiers for the long long type per ANSI C.
Revision 5.1, October 11, 2012
Added support extended VXIbus block transfer protocols and trigger capabilities according to VXI-1 4.0. Extensions for PXI INSTR, PXI BACKPLANE.
Revision 5.4, June 19, 2014
Added clarifications (rules and observations) to viOpen, viReadAsync, viWriteAsync and viMoveAsync. Added a new error codeVI_ERROR_LINE_NRESERVEDto facilitate better mapping of PXI-9 trigger error codes.Added clarifications (rules and permissions) to viMapTrigger and viUnmapTrigger. Extended viGpibControlREN to add support for TCPIP devices. Changed the version to 5.4 to ensure that all VISA specifications being voted on at the same time have the same version.
Revision 5.4Editorial Change, June19, 2015
Added VI_WARN_QUEUE_OVERFLOW as a possible error code returned by viWaitOnEvent. Added clarifications on the effect of the precision modifier with the %f specifier.Added clarifications on the value of failureIndex when viPxiReserveTriggers returns differentstatus codes. Added clarifications on the maximum length of VISA string attributes.
Revision 5.7, February 26, 2016
Add PXI trigger lines TTL8-TTL11.
NOTICE
VPP-4.3: The VISA Library is authored by the IVI Foundation member companies. For a vendor membership roster list, please visit the IVI Foundation web site at
The IVI Foundation wants to receive your comments on this specification. You can contact the Foundation through the web site at
Warranty
The IVI Foundation and its member companies make no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The IVI Foundation and its member companies shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Trademarks
Product and company names listed are trademarks or trade names of their respective companies.
No investigation has been made of common-law trademark rights in any work.
Table of Contents Page 1
Table of Contents
Section 1 Introduction to the VXIplug&play Systems Alliance and the IVI Foundation
Section 2 Overview of VISA Library Specification
2.1 Objectives of this Specification
2.2 Audience for this Specification
2.3 Scope and Organization of this Specification
2.4 Application of this Specification
2.5 References
2.6 Definition of Terms and Acronyms
2.7 Conventions
Section 3 VISA Resource Template
3.1 VISA Template Services
3.1.1 Control Services
3.1.2 Communication Services
3.2 VISA Template Interface Overview
3.2.1 VISA Template Attributes
3.2.2 VISA Template Operations
3.3 Lifecycle Services
3.3.1 Lifecycle Operations
3.3.1.1 viClose(vi)
3.4 Characteristic Control Services
3.4.1 Characteristic Control Operations
3.4.1.1 viGetAttribute(vi, attribute, attrState)
3.4.1.2 viSetAttribute(vi, attribute, attrState)
3.4.1.3 viStatusDesc(vi, status, desc)
3.5 Asynchronous Operation Control Services
3.5.1 Asynchronous Operation Control Operations
3.5.1.1 viTerminate(vi, degree, jobId)
3.6 Access Control Services
3.6.1 Session Access Control Service Model
3.6.1.1 Locking Mechanism
3.6.1.2 Lock Sharing
3.6.1.3 Access Privileges
3.6.1.4 Acquiring Exclusive Lock While Owning Shared Lock
3.6.1.5 Nested Locks
3.6.1.6 Locks on Remote Resources
3.6.2 Access Control Operations
3.6.2.1 viLock(vi, lockType, timeout, requestedKey, accessKey)
3.6.2.2 viUnlock(vi)
3.7 Event Services
3.7.1 Event Handling and Processing
3.7.1.1 Queuing Mechanism
3.7.1.2 Callback Mechanism
3.7.2 Exceptions
3.7.2.1 Exception Handling Model
3.7.2.2 Generating an Error Condition
3.7.2.3 VI_EVENT_EXCEPTION
3.7.3 Event Operations
3.7.3.1 viEnableEvent(vi, eventType, mechanism, context)
3.7.3.2 viDisableEvent(vi, eventType, mechanism)
3.7.3.3 viDiscardEvents(vi, eventType, mechanism)
3.7.3.4 viWaitOnEvent(vi, inEventType, timeout, outEventType, outContext)
3.7.3.5 viInstallHandler(vi, eventType, handler, userHandle)
3.7.3.6 viUninstallHandler(vi, eventType, handler, userHandle)
3.7.3.7 viEventHandler(vi, eventType, context, userHandle)
Section 4 VISA Resource Management
4.1 Organization of Resources
4.2 VISA Resource Manager Interface Overview
4.2.1 VISA Resource Manager Attributes
4.2.2 VISA Resource Manager Functions
4.2.3 VISA Resource Manager Operations
4.3 Access Services
4.3.1 Address String
4.3.1.1 Address String Grammar
4.3.2 System Configuration
4.3.3 Access Functions and Operations
4.3.3.1 viOpenDefaultRM(sesn)
4.3.3.2 viOpen(sesn, rsrcName, accessMode, timeout, vi)
4.3.3.3 viParseRsrc(sesn, rsrcName, intfType, intfNum)
4.3.3.4 viParseRsrcEx(sesn, rsrcName, intfType, intfNum, rsrcClass, unaliasedExpandedRsrcName, aliasIfExists)
4.4 Search Services
4.4.1 Resource Regular Expression
4.4.2 Search Operations
4.4.2.1 viFindRsrc(sesn, expr, findList, retcnt, instrDesc)
4.4.2.2 viFindNext(findList, instrDesc)
Section 5 VISA Resource Classes
5.1 Instrument Control Resource
5.1.1 INSTR Resource Overview
5.1.2 INSTR Resource Attributes
5.1.3 INSTR Resource Events
5.1.4 INSTR Resource Operations
5.1.5 Differences between VXI-11 and HiSLIP TCPIP INSTR Systems
5.2 Memory Access Resource
5.2.1 MEMACC Resource Overview
5.2.2 MEMACC Resource Attributes
5.2.3 MEMACC Resource Events
5.2.4 MEMACC Resource Operations
5.3 GPIB Bus Interface Resource
5.3.1 INTFC Resource Overview
5.3.2 INTFC Resource Attributes
5.3.3 INTFC Resource Events
5.3.4 INTFC Resource Operations
5.4 Mainframe Backplane Resource
5.4.1 BACKPLANE Resource Overview
5.4.2 BACKPLANE Resource Attributes
5.4.3 BACKPLANE Resource Events
5.4.4 BACKPLANE Resource Operations
5.5 Servant Device-Side Resource
5.5.1 SERVANT Resource Overview
5.5.2 SERVANT Resource Attributes
5.5.3 SERVANT Resource Events
5.5.4 SERVANT Resource Operations
5.6 TCP/IP Socket Resource
5.6.1 SOCKET Resource Overview
5.6.2 SOCKET Resource Attributes
5.6.3 SOCKET Resource Events
5.6.4 SOCKET Resource Operations
Section 6 VISA Resource-Specific Operations
6.1 Basic I/O Services
6.1.1 viRead(vi, buf, count, retCount)
6.1.2 viReadAsync(vi, buf, count, jobId)
6.1.3 viReadToFile(vi, fileName, count, retCount)
6.1.4 viWrite(vi, buf, count, retCount)
6.1.5 viWriteAsync(vi, buf, count, jobId)
6.1.6 viWriteFromFile(vi, fileName, count, retCount)
6.1.7 viAssertTrigger(vi, protocol)
6.1.8 viReadSTB(vi, status)
6.1.9 viClear(vi)
6.2 Formatted I/O Services
6.2.1 viSetBuf(vi, mask, size)
6.2.2 viFlush(vi, mask)
6.2.3 viPrintf(vi, writeFmt, arg1, arg2,...)
6.2.4 viVPrintf(vi, writeFmt, params)
6.2.5 viSPrintf(vi, buf, writeFmt, arg1, arg2, ...)
6.2.6 viVSPrintf(vi, buf, writeFmt, params)
6.2.7 viBufWrite(vi, buf, count, retCount)
6.2.8 viScanf(vi, readFmt, arg1, arg2,...)
6.2.9 viVScanf(vi, readFmt, params)
6.2.10 viSScanf(vi, buf, readFmt, arg1, arg2, ...)
6.2.11 viVSScanf(vi, buf, readFmt, params)
6.2.12 viBufRead(vi, buf, count, retCount)
6.2.13 viQueryf(vi, writeFmt, readFmt, arg1, arg2,...)
6.2.14 viVQueryf(vi, writeFmt, readFmt, params)
6.3 Memory I/O Services
6.3.1 viIn8(vi, space, offset, val8)
6.3.2 viIn16(vi, space, offset, val16)
6.3.3 viIn32(vi, space, offset, val32)
6.3.4 viIn64(vi, space, offset, val64)
6.3.5 viOut8(vi, space, offset, val8)
6.3.6 viOut16(vi, space, offset, val16)
6.3.7 viOut32(vi, space, offset, val32)
6.3.8 viOut64(vi, space, offset, val64)
6.3.9 viMoveIn8(vi, space, offset, length, buf8)
6.3.10 viMoveIn16(vi, space, offset, length, buf16)
6.3.11 viMoveIn32(vi, space, offset, length, buf32)
6.3.12 viMoveIn64(vi, space, offset, length, buf64)
6.3.13 viMoveIn8Ex(vi, space, offset64, length, buf8)
6.3.14 viMoveIn16Ex(vi, space, offset64, length, buf16)
6.3.15 viMoveIn32Ex(vi, space, offset64, length, buf32)
6.3.16 viMoveIn64Ex(vi, space, offset64, length, buf64)
6.3.17 viMoveOut8(vi, space, offset, length, buf8)
6.3.18 viMoveOut16(vi, space, offset, length, buf16)
6.3.19 viMoveOut32(vi, space, offset, length, buf32)
6.3.20 viMoveOut64(vi, space, offset, length, buf64)
6.3.21 viMoveOut8Ex(vi, space, offset64, length, buf8)
6.3.22 viMoveOut16Ex(vi, space, offset64, length, buf16)
6.3.23 viMoveOut32Ex(vi, space, offset64, length, buf32)
6.3.24 viMoveOut64Ex(vi, space, offset64, length, buf64)
6.3.25 viMove(vi, srcSpace, srcOffset, srcWidth, destSpace, destOffset, destWidth, length)
6.3.26 viMoveEx(vi, srcSpace, srcOffset64, srcWidth, destSpace, destOffset64, destWidth, length)
6.3.27 viMoveAsync(vi, srcSpace, srcOffset, srcWidth, destSpace, destOffset, destWidth, length, jobId)
6.3.28 viMoveAsyncEx(vi, srcSpace, srcOffset64, srcWidth, destSpace, destOffset64, destWidth, length, jobId)
6.3.29 viMapAddress(vi, mapSpace, mapBase, mapSize, access, suggested, address)
6.3.30 viMapAddressEx(vi, mapSpace, mapBase64, mapSize, access, suggested, address)
6.3.31 viUnmapAddress(vi)
6.3.32 viPeek8(vi, addr, val8)
6.3.33 viPeek16(vi, addr, val16)
6.3.34 viPeek32(vi, addr, val32)
6.3.35 viPeek64(vi, addr, val64)
6.3.36 viPoke8(vi, addr, val8)
6.3.37 viPoke16(vi, addr, val16)
6.3.38 viPoke32(vi, addr, val32)
6.3.39 viPoke64(vi, addr, val64)
6.4 Shared Memory Services
6.4.1 viMemAlloc(vi, size, offset)
6.4.2 viMemAllocEx(vi, size, offset64)
6.4.3 viMemFree(vi, offset)
6.4.4 viMemFreeEx(vi, offset64)
6.5 Interface Specific Services
6.5.1 viGpibControlREN(vi, mode)
6.5.2 viGpibControlATN(vi, mode)
6.5.3 viGpibSendIFC(vi)
6.5.4 viGpibCommand(vi, buf, count, retCount)
6.5.5 viGpibPassControl(vi, primAddr, secAddr)
6.5.6 viVxiCommandQuery(vi, mode, cmd, response)
6.5.7 viAssertIntrSignal(vi, mode, statusID)
6.5.8 viAssertUtilSignal(vi, line)
6.5.9 viMapTrigger(vi, trigSrc, trigDest, mode)
6.5.10 viUnmapTrigger(vi, trigSrc, trigDest)
6.5.11 viUsbControlOut (vi, bmRequestType, bRequest, wValue, wIndex, wLength, buf)
6.5.12 viUsbControlIn (vi, bmRequestType, bRequest, wValue, wIndex, wLength, buf, retCnt)
6.5.13 viPxiReserveTriggers (vi, cnt, trigBuses, trigLines, failureIndex)
Appendix A Required Attributes
A.1 Required Attribute Tables
Resource Template Attributes
INSTR Resource Attributes (Generic) (Continued)
INSTR Resource Attributes (Message Based)
INSTR Resource Attributes (GPIB and GPIB-VXI Specific)
INSTR Resource Attributes (VXI and GPIB-VXI Specific)
INSTR Resource Attributes (VXI and GPIB-VXI Specific)
INSTR Resource Attributes (ASRL Specific)
INSTR Resource Attributes (TCPIP Specific)
INSTR Resource Attributes (HiSLIP Specific)
INSTR Resource Attributes (VXI, GPIB-VXI, USB, and PXI Specific)
INSTR Resource Attributes (VXI, GPIB-VXI, and USB Specific)
INSTR Resource Attributes (USB Specific)
INSTR Resource Attributes (PXI Specific)
MEMACC Resource Attributes (Generic)
MEMACC Resource Attributes (VXI, GPIB-VXI, and PXI Specific)
MEMACC Resource Attributes (VXI and GPIB-VXI Specific)
MEMACC Resource Attributes (GPIB-VXI Specific)
INTFC Resource Attributes (Generic)
INTFC Resource Attributes (GPIB Specific)
BACKPLANE Resource Attributes (Generic)
BACKPLANE Resource Attributes (VXI and GPIB-VXI Specific)
SERVANT Resource Attributes (Generic)
SERVANT Resource Attributes (GPIB Specific)
SERVANT Resource Attributes (VXI Specific)
SERVANT Resource Attributes (TCPIP Specific)
SOCKET Resource Attributes (Generic)
SOCKET Resource Attributes (TCPIP Specific)
Appendix B Resource Summary Information
B.1 Summary of Attributes
B.2 Summary of Events
B.3 Summary of Operations
Figures
Figure 3.7.1State Diagram for the Queuing Mechanism
Figure 3.7.2State Diagram for the Callback Mechanism
Tables
Table 3.2.1VISA Template Required Attributes
Table 3.2.2ViVersion Description for VI_ATTR_RSRC_IMPL_VERSION and VI_ATTR_RSRC_SPEC_VERSION
Table 3.6.1Types of Locks Acquired When Requesting Session Has No Lock
Table 3.6.2Types of Locks Acquired When Requesting Session Has Exclusive Lock Only (Nesting)
Table 3.6.3Types of Locks Acquired When Requesting Session Has Shared Lock (Nesting)
Table 3.6.4Types of Locks Acquired When Requesting Session Has Shared and Exclusive Locks (Nesting)
Table 3.6.5Current Session Has No Lock
Table 3.6.6Current Session Has Exclusive Lock
Table 3.6.7Current Session Has Shared Lock
Table 3.7.1State Transitions for the Queuing Mechanism
Table 3.7.2State Transition Table for the Callback Mechanism
Table 3.7.3Special Values for eventType Parameter
Table 3.7.4Special Values for mechanism Parameter
Table 3.7.5Special Values for eventType Parameter
Table 3.7.6Special Values for mechanism Parameter
Table 3.7.7Special Values for eventType Parameter
Table 3.7.8Special Values for mechanism Parameter
Table 3.7.9Special Values for outEventType Parameter
Table 3.7.10Special Values for outContext Parameter
Table 3.7.11Special Values for handler Parameter
Table 4.3.1Explanation of Address String Grammar
Table 4.3.2Examples of Address Strings
Table 4.3.3Special Values for rsrcClass Parameter
Table 4.3.4Special Values for unaliasedExpandedRsrcName Parameter
Table 4.3.5Special Values for aliasIfExists Parameter
Table 4.4.1Special Characters
Table 4.4.2Literals
Table 4.4.3Regular Expression Characters and Operators
Table 4.4.4Examples
Table 4.4.5Special Values for findList Parameter
Table 4.4.6Special Values for retcnt Parameter
Table 4.4.7Special Characters and their Meaning
Table 4.4.8Examples
Table 6.1.1Special Values for retCount Parameter
Table 6.1.2Special Values for jobId Parameter
Table 6.1.3Special Values for retCount Parameter
Table 6.1.4Special Values for retCount Parameter
Table 6.1.5Special Values for jobId Parameter
Table 6.1.6Special Values for retCount Parameter
Table 6.2.1Special Values for retCount Parameter
Table 6.2.2Special Values for retCount Parameter
Table 6.3.1Special Values for jobId Parameter
Table 6.5.1Special Values for mode Parameter
Table 6.5.2Special Values for mode Parameter
Table 6.5.3Special Values for retCount Parameter
Table 6.5.4Special Values for mode Parameter
Table 6.5.5Special Values for mode Parameter
Table 6.5.6Special Values for trigSrc Parameters
Table 6.5.7Special Values for trigDest Parameters
Table 6.5.7Special Values for trigSrc Parameters
Table 6.5.8Special Values for trigDest Parameters
Table 6.5.9Special Values for retCnt Parameter
Table 6.5.9Special Values for failureIndex Parameter
VXIplug&play Systems AllianceVPP-4.3: The VISA Library
Section 1: Introduction to the VXIplug&play Systems Alliance and the IVI FoundationPage 1-1
Section 1 Introductionto the VXIplug&play Systems Alliance and the IVI Foundation
The VXIplug&play Systems Alliance was founded by members who shared a common commitment to end-user success with open, multivendor VXI systems. The alliance accomplished major improvements in ease of use by endorsing and implementing common standards and practices in both hardware and software, beyond the scope of the VXIbus specifications. The alliance used both formal and de facto standards to define complete system frameworks. These standard frameworks gave end-users "plug & play" interoperability at both the hardware and system software level.
The IVI Foundation is an organization whose members share a common commitment to test system developer success through open, powerful, instrument control technology. The IVI Foundation’s primary purpose is to develop and promote specifications for programming test instruments that simplify interchangeability, provide better performance, and reduce the cost of program development and maintenance.
In 2002, the VXIplug&play Systems Alliance voted to become part of the IVI Foundation. In 2003, the VXIplug&play Systems Alliance formally merged into the IVI Foundation. The IVI Foundation has assumed control of the VXIplug&play specifications, and all ongoing work will be accomplished as part of the IVI Foundation.
All references to VXIplug&play Systems Alliance within this document, except contact information, were maintained to preserve the context of the original document.
VXIplug&play Systems AllianceVPP-4.3: The VISA Library
Section 2: Overview of VISA Library SpecificationPage 2-1
Section 2 Overview of VISA Library Specification
This section introduces the VISA specification. The VISA specification is a document authored by the VXIplug&play Systems Alliance. The technical work embodied in this document and the writing of this document were performed by the VISA Technical Working Group.
This section provides a complete overview of the VISA specification, and gives readers general information that may be required to understand how to read, interpret, and implement individual aspects of this specification. This section is organized as follows:
•Objectives of this specification
•Audience for this specification
•Scope and organization of this specification
•Application of this specification
•References
•Definitions of terms and acronyms
•Conventions
•Communication
2.1 Objectives of this Specification
The VISA specification provides a common standard for the VXIplug&play System Alliance for developing multi-vendor software programs, including instrument drivers. This specification describes the VISA software model and the VISA Application Programming Interface (API).
VISA gives VXI and GPIB software developers, particularly instrument driver developers, the functionality needed by instrument drivers in an interface-independent fashion for MXI, embedded VXI, GPIB-VXI, GPIB, and asynchronous serial controllers. VXIplug&play drivers written to the VISA specifications can execute on VXIplug&play system frameworks that have the VISA I/O library.
2.2 Audience for this Specification
There are three audiences for this specification. The first audience is instrument driver developers—whether an instrument vendor, system integrator, or end user—who wish to implement instrument driver software that is compliant with the VXIplug&play standards. The second audience is I/O vendors who wish to implement VISAcompliant I/O software. The third audience is instrumentation end users and application programmers who wish to implement applications that utilize instrument drivers compliant with this specification.
2.3 Scope and Organization of this Specification
This specification is organized in sections, with each section discussing a particular aspect of the VISA model.
Section 1 explains the VXIplug&play Systems Allianceand its relation to the IVI Foundation.
Section 2 provides an overview of this specification, including the objectives, scope and organization, application, references, definition of terms and acronyms, and conventions.
Section 3 describes the VISA Resource Template.
Section 4 describes the VISA Resource Manager Resource.
Section 5 presents the VISA Instrument Control Resource and other I/O resource classes.
Section 6 presents the operations defined in Section 5 and describes a compliant implementation.
2.4 Application of this Specification
This specification is intended for use by developers of VXIplug&play instrument drivers and by developers of VISA I/O software. It is also useful as a reference for end users of VXIplug&play instrument drivers. This specification is intended to be used in conjunction with the VPP-3.x specifications, including the Instrument Drivers Architecture and Design Specification (VPP-3.1), the Instrument Driver Functional Body Specification (VPP-3.2), the Instrument Interactive Developer Interface Specification (VPP-3.3), and the Instrument Driver Programmatic Developer Interface Specification (VPP-3.4). These related specifications describe the implementation details for specific instrument drivers that are used with specific system frameworks. VXIplug&play instrument drivers developed in accordance with these specifications can be used in a wide variety of higher-level software environments, as described in the SystemFrameworks Specification (VPP-2).