Tektronix TekVISA Programmer

Programmer Manual

TekVIS A

077-0140-00

www.tektronix.com

Copyright © Tektronix. All rights reserved. Licensed software products are owned by Tektronix or its subsidiaries or suppliers, and are protected by national copyright laws and i nternational treaty provisions.

Tektronix products are covered by U.S. and foreign patents, issued and pending. Information in this publication supercedes that in all previously published material. Specifications a nd price change privileges reserved.

TEKTRONIX and TEK are registered trademarks of Tektronix, Inc.

Contacting Tektronix

Tektronix, Inc. 14200 SW Karl Braun Drive P.O. Box 500 Beaverton, OR 97077 USA

For product information, sales, service, and technical support:

H In North America, call 1-800-833-9200. H Worldwide, visit www.tektronix.com to find contacts in your area.

Getting Started

Reference

Preface xv...................................................

Who Should Read This Manual xv.....................................

About This Manual xv...............................................

Conventions xvi....................................................

Related Manuals and Information xvii...................................

Getting Started 1--1............................................

Product Description 1--1..............................................

Features and Benefits 1--2.........................................

Applications and Connectivity Supported by TekVISA 1--2...............

Terminology 1--5....................................................

Resources, INSTR Resource, SOCKET Resource, and Sessions 1--5........

Operations, Attributes, and Events 1--5...............................

The Resource Manager 1--5........................................

Virtual Instruments and Virtual GPIB 1--7.............................

WhatYouNeedtoGetStarted 1--8......................................

TekVISA Installation 1--8..........................................

The TekVISA Configuration Utility 1--9..............................

Operations Summary 2--1......................................

Operations 2--5...............................................

viAssertTrigger (vi, protocol) 2--5.......................................

viBufRead (vi, buf, count, retCount) 2--7.................................

viBufWrite (vi, buf, count, retCount) 2--8.................................

viClear (vi) 2--10.....................................................

viClose (vi) 2--12.....................................................

viDisableEvent (vi, eventType, mechanism) 2--13...........................

viDiscardEvents (vi, eventType, mechanism) 2--15..........................

viEnableEvent (vi, eventType, mechanism, context) 2--17....................

viEventHandler (vi, eventType, context, userHandle) 2--21....................

viFindNext (findList, instrDesc) 2--23....................................

viFindRsrc (sesn, expr, findList, retCount, i nstrDesc) 2--25....................

viFlush (vi, mask) 2--31................................................

viGetAttribute (vi, attribute, attrState) 2--33................................

viInstallHandler (vi, eventType, handler, userHandle) 2--35...................

viLock (vi, lockType, timeout, requestedKey, accessKey) 2--38................

viOpen (sesn, rsrcName, accessMode, timeout, vi) 2--41......................

viOpenDefaultRM (sesn) 2--44..........................................

viParseRsrc (sesn, rsrcName, intfType, intfNum) 2--46.......................

viPrintf (vi, writeFmt, <arg1, arg2, ...>) 2--48..............................

viQueryf (vi, writeFmt, readFmt, <arg1, arg2,...>) 2--55......................

viRead (vi, buf, count, retCount) 2--57....................................

viReadAsync (vi, buf, count, jobId) 2--61..................................

viReadSTB (vi, status) 2--66............................................

Tektronix TekVISA Programmer Manual

Table of Contents

viReadToFile (vi, fileName, count, retCount) 2--67..........................

viScanf (vi, readFmt, <arg1, arg2,...>) 2--70................................

viSetAttribute (vi, attribute, attrState) 2--78................................

viSetBuf (vi, mask, size) 2--80..........................................

viSPrintf (vi, buf, writeFmt, <arg1, arg2,...>) 2--81..........................

viSScanf (vi, buf, readFmt, <arg1, arg2,...>) 2--84...........................

viStatusDesc (vi, status, desc) 2--86......................................

viTerminate (vi, degree, jobId) 2--87......................................

viUninstallHandler (vi, eventType, handler, userHandle) 2--89.................

viUnlock (vi) 2--90....................................................

viUsbControlIn (vi, bmRequestType, bRequest, wValue,

wIndex, wLength, buffer, retCount) 2--92..............................

viUsbControlOut (vi, bmRequestType, bRequest, wValue,

wIndex, wLength, buffer) 2--95......................................

viVPrintf (vi, writeFmt, params) 2--98....................................

viVQueryf (vi, writeFmt, readFmt, params) 2--100...........................

viVScanf (vi, readFmt, params) 2--102.....................................

viVSPrintf (vi, buf, writeFmt, params) 2--104...............................

viVSScanf (vi, buf, readFmt, params) 2--106................................

viWaitOnEvent (vi, inEventType, timeout, outEventType, outContext) 2--107......

viWrite (vi, buf, count, retCount) 2--110....................................

viWriteAsync (vi, buf, count, jobId) 2--112.................................

viWriteFromFile (vi, fileName, count, retCount ) 2--116.......................

Attributes

Attributes Summary 3--1.......................................

Attributes 3--5................................................

VI_ATTR_ASRL_AVAIL_NUM 3--5....................................

VI_ATTR_ASRL_BAUD 3--5..........................................

VI_ATTR_ASRL_CTS_STATE 3--6.....................................

VI_ATTR_ASRL_DATA_BITS 3--6.....................................

VI_ATTR_ASRL_DCD_STATE 3--7....................................

VI_ATTR_ASRL_DSR_STATE 3--7.....................................

VI_ATTR_ASRL_DTR_STATE 3 --8....................................

VI_ATTR_ASRL_END_IN 3--8........................................

VI_ATTR_ASRL_END_OUT 3--9......................................

VI_ATTR_ASRL_FLOW_CNTRL 3--10..................................

VI_ATTR_ASRL_PARITY 3--11........................................

VI_ATTR_ASRL_REPLACE_CHAR 3--11................................

VI_ATTR_ASRL_RI_STATE 3--12......................................

VI_ATTR_ASRL_RTS_STATE 3--12.....................................

VI_ATTR_ASRL_STOP_BITS 3--13.....................................

VI_ATTR_ASRL_XOFF_CHAR 3--13....................................

VI_ATTR_ASRL_XON_CHAR 3--14....................................

VI_ATTR_BUFFER 3--14..............................................

VI_ATTR_EVENT_TYPE 3--15.........................................

VI_ATTR_GPIB_PRIMARY_ADDR 3--15................................

VI_ATTR_GPIB_READDR_EN 3--16....................................

VI_ATTR_GPIB_SECONDARY_ADDR 3--16.............................

VI_ATTR_GPIB_UNADDR_EN 3--17....................................

VI_ATTR_INTF_INST_NAME 3--17.....................................

VI_ATTR_INTF_NUM 3--18...........................................

Tektronix TekVISA Programmer Manual

Table of Contents

VI_ATTR_INTF_TYPE 3--18...........................................

VI_ATTR_IO_PROT 3--19.............................................

VI_ATTR_JOB_ID 3--19...............................................

VI_ATTR_MAX_QUEUE_LENGTH 3--20................................

VI_ATTR_OPER_NAME 3--20.........................................

VI_ATTR_RD_BUF_OPER_MODE 3--21.................................

VI_ATTR_RET_COUNT 3--21..........................................

VI_ATTR_RM_SESSION 3--22.........................................

VI_ATTR_RSRC_IMPL_VERSION 3--22.................................

VI_ATTR_RSRC_LOCK_STATE 3--23...................................

VI_ATTR_RSRC_MANF_ID 3--23......................................

VI_ATTR_RSRC_MANF_NAME 3--24...................................

VI_ATTR_RSRC_NAME 3--24.........................................

VI_ATTR_RSRC_SPEC_VERSION 3--25.................................

VI_ATTR_SEND_END_EN 3--26.......................................

VI_ATTR_STATUS 3--26..............................................

VI_ATTR_SUPPRESS_END_EN 3--27...................................

VI_ATTR_TCPIP_ADDR 3--27.........................................

VI_ATTR_TCPIP_HOSTNAME 3--28....................................

VI_ATTR_TCPIP_KEEPALIVE 3--28....................................

VI_ATTR_TCPIP_NODELAY 3--29.....................................

VI_ATTR_TCPIP_PORT 3--29..........................................

VI_ATTR_TERMCHAR 3-- 30..........................................

VI_ATTR_TERMCHAR_EN 3--30.......................................

VI_ATTR_TMO_VALUE 3--31.........................................

VI_ATTR_TRIG_ID 3--31..............................................

VI_ATTR_USB_INTFC_NUM 3--32.....................................

VI_ATTR_USB_MAX_INTR_SIZE 3--32.................................

VI_ATTR_USB_PROTOCOL 3--33......................................

VI_ATTR_USB_RECV_INTR_DATA 3--33...............................

VI_ATTR_USB_RECV_INTR_SIZE 3--34................................

VI_ATTR_USB_SERIAL_NUM 3-- 34....................................

VI_ATTR_USER_DATA 3--35..........................................

VI_ATTR_WR_BUF_OPER_MODE 3--35................................

Events

Events 4--1...................................................

VI_EVENT_EXCEPTION 4--1.........................................

VI_EVENT_IO_COMPLETION 4-- 1....................................

VI_EVENT_SERVICE_REQ 4--2.......................................

Examples

Programming Examples 5--1....................................

Introduction 5--1....................................................

Compiling and Linking Examples 5--2...................................

Opening and Closing Sessions 5--3......................................

SIMPLE.CPP Example 5--4........................................

Finding Resources 5--5...............................................

Tektronix TekVISA Programmer Manual

iii

Table of Contents

Using Regular Expressions 5--5.....................................

SIMPLEFINDRSRC.CPP Example 5--6..............................

Using Attribute Matching 5--7......................................

FINDRSRCATTRMATCH.CPP Example 5--7.........................

Setting and Retrieving Attributes 5--9....................................

Retrieving Attributes 5 --9..........................................

Setting Attributes 5--9.............................................

ATTRACCESS.CPP Example 5--9...................................

Basic Input/Output 5--11...............................................

Reading and Writing Data 5--11......................................

Synchronous Read/Write 5--12.......................................

Extract from SIMPLE.CPP Example 5-- 12.............................

RWEXAM.CPP Example 5--12......................................

Asynchronous Read/Write 5--13......................................

Clear 5--13......................................................

Trigger 5--14.....................................................

Status/Service Request 5--14........................................

Reading and Writing Formatted Data 5--14................................

Formatted I/O Operations 5--16......................................

FORMATIO.CPP Example 5--16.....................................

Resizing the Formatted I/O Buffers 5--21..............................

BUFFERIO.CPP Example 5--21.....................................

Flushing the Formatted I/O Buffer 5 --23...............................

Buffered I/O Operations 5--24.......................................

Variable List Operations 5--24.......................................

Controlling the Serial I/O Buffers 5-- 24................................

Handling Events 5--25.................................................

Queueing Mechanism 5--25.........................................

SRQWAIT.CPP Example 5--26......................................

Callback Mechanism 5 --29..........................................

SRQ.CPP Example 5--30...........................................

Exception Handling 5-- 33...........................................

Generating an Error Condition on Asynchronous Operations 5--34..........

Locking and Unlocking Resources 5--34...................................

Locking Types and Access Privileges 5--35.............................

EXLOCKEXAM.CPP Example 5 -- 35.................................

Testing Exclusive Locking 5--37.....................................

Lock Sharing 5 --38................................................

Acquiring an Exclusive Lock While Owning a Shared Lock 5--39...........

Nested Locks 5--39................................................

SHAREDLOCK.CPP Example 5-- 40..................................

Testing Shared Locking 5--42........................................

Building a Graphical User Interface 5--43.................................

Appendices

Appendix A: VISA Data Type Assignments A--1....................

Appendix B: Completion and Error Codes B--1.....................

Tektronix TekVISA Programmer Manual

List of Figures

Table of Contents

Figure 1 --1: TekVISA Supports Multiple Development

Environments 1--3..........................................

Figure 1 --2: TekVISA Supports Local and

Remote Connectivity 1--4....................................

Figure 1--3: Key VISA Terminology for INSTR Resource 1--6.........

Figure 1--4: Key VISA Terminology for SOCKET Resource 1--7......

Figure 1--5: System Tray 1--9....................................

Figure 5--1: SIMPLE.CPP Example 5--5..........................

Figure 5--2: SIMPLEFINDRSRC.CPP Example 5--7................

Figure 5--3: FINDRSRCATTRMATCH.CPP Example 5--9...........

Figure 5--4: ATTRACCESS.CPP Example 5--11.....................

Figure 5--5: Read/Write Extract from SIMPLE.CPP Example 5--12....

Figure 5--6: RWEXAM.CPP Example 5--13.........................

Figure 5--7: Types of Formatted Read/Write Operations 5--16.........

Figure 5--8: FORMATIO.CPP Example 5--21.......................

Figure 5--9: BUFFERIO.CPP Example 5--23........................

Figure 5--10: SRQWAIT.CPP Example 5--29.......................

Figure 5--11: SRQ.CPP Example 5--33.............................

Figure 5--12: EXLOCKEXAM.CPP Example 5--37..................

Figure 5--13: SHAREDLOCK.CPP Example 5--41...................

Figure 5--14: VISAAPIDemo Graphical User Interface 5--43...........

Figure 5--15: C++ Controls Toolbar and Form, Code,

and Properties Windows 5--45.................................

Figure A--2: Your Program Can Use the Instrument

Driver API or VISA API A--2....................................

Tektronix TekVISA Programmer Manual

Table of Contents

List of Tables

Table ii: Table of Typographic Conventions xvi...................

Table 1--1: In stallin g TekVISA Software on a PC 1--8...............

Table 2--1: Table of VISA Operations by Category 2--1..............

T able 2--2: viAssertTrigger() Parameters 2--5......................

Table 2--3: viAssertTrigger() Completion Codes 2--5................

Table 2--4: viAssertTrigger() Error Codes 2--5.....................

Table 2--5: viBufRead() Parameters 2--7..........................

Table 2--6: viBufRead() Completion Codes 2--7....................

Table 2--7: viBufRead() Error Codes 2--7.........................

Table 2--8: Special Value for retCount Parameter

with viBufRead() 2--8......................................

T able 2--9: viBufWrite() Parameters 2--9..........................

T able 2--10: viBufWrite() Completion Codes 2--9...................

Table 2--11: viBufWrite() Error Codes 2--9........................

Table 2--12: Special Value for retCount Parameter

with viBufWrite() 2--10......................................

Table 2--13: viClear() Parameters 2--11............................

Table 2--14: viClear() Completion Codes 2--11......................

Table 2--15: viClear() Error Codes 2--11...........................

Table 2--16: viClose() Parameters 2--12............................

Table 2--17: viClose() Completion Codes 2--12......................

Table 2--18: viClose() Error Codes 2--13...........................

Table 2--19: viDisableEvent() Parameters 2--14.....................

Table 2--20: viDisableEvent() Completion Cod es 2--14...............

Table 2--21: viDisableEvent() Error Codes 2--14.....................

Table 2--22: Special Values for eventType Parameter

with viDisableEvent() 2--15...................................

T able 2--23: Special Values for mechanism Parameter

with viDisableEvent() 2--15...................................

Table 2--24: viDiscardEvents() Parameters 2--16....................

Table 2--25: viDiscardEvents() Completion Codes 2--16..............

Table 2--26: viDiscardEvents() Error Codes 2--16...................

Table 2--27: Special Values for eventType Parameter

with viDiscardEvents() 2--17..................................

Tektronix TekVISA Programmer Manual

Table of Contents

T able 2--28: Special Values for mechanism Parameter

with viDiscardEvents() 2--17..................................

Table 2--29: viEnableEvent() Parameters 2--17......................

Table 2--30: viEnableEvent() Completion Codes 2--18................

Table 2--31: viEnableEvent() Error Codes 2--18.....................

Table 2--32: Special Values for eventType Parameter

with viEnableEvent() 2--19...................................

T able 2--33: Special Values for mechanism Parameter

with viEnableEvent() 2--20...................................

Table 2--34: viEventHandler() Parameters 2-- 21.....................

Table 2--35: viEventHandler() Completion Cod es 2--21...............

T able 2--36: viFindNext() Parameters 2--23.........................

Table 2--37: viFindNext() Completion Cod es 2--24...................

Table 2--38: viFindNext() Error Codes 2--24........................

Table 2--39: viFindRsrc() Parameters 2--25.........................

Table 2--40: viFindRsrc() Completion Codes 2--26...................

Table 2--41: viFindRsrc() Error Codes 2--26........................

Table 2--42: Special Value for retCount Parameter

with viFindRsrc() 2--29......................................

Table 2--43: Special Value for findList Parameter

with viFindRsrc() 2--29......................................

Table 2--44: Regular Expression Special Characters

and Operators 2--29.........................................

Table 2--45: Examples of Regular Expression Matches 2--30..........

Table 2--46: Examples That Include Attribute

Expression Matches 2 --31....................................

Table 2--47: viFlush() Parameters 2--32............................

Table 2--48: viFlush() Completion Codes 2--32......................

Table 2--49: viFlush() Error Codes 2--32...........................

Table 2--50: viFlush Values for mask Parameter 2--33...............

Table 2--51: viGetAttribute() Parameters 2--34......................

Table 2--52: viGetAttribute() Completion Codes 2--34................

Table 2--53: viGetAttribute() Error Codes 2--34.....................

Table 2--54: viInstallHandler() Parameters 2--35....................

Table 2--55: viInstallHandler() Completion Cod es 2--35..............

Table 2--56: viInstallHandler() Error Codes 2--36...................

T able 2--57: viLock() Parameters 2--38............................

Table 2--58: viLock() Completion Codes 2--39......................

Table 2--59: viLock() Error Codes 2 --39............................

T able 2--60: viOpen() Parameters 2--41............................

Tektronix TekVISA Programmer Manual

vii

Table of Contents

Table 2--61: viOpen() Completion Codes 2--42......................

Table 2--62: viOpen() Error Codes 2--42...........................

Table 2--63: Resource Address String Grammar

and Examples with viOpen() 2--43.............................

T able 2--64: Special Values for accessMode Parameter

with viOpen() 2--43.........................................

T able 2--65: viOpenDefaultRM() Parameters 2--44..................

Table 2--66: viOpenDefaultRM() Completion Codes 2--44.............

Table 2--67: viOpenDefaultRM() Error Codes 2--44..................

T able 2--68: viParseRsrc() Parameters 2--46........................

T able 2--69: viParseRsrc() Completion Codes 2--46..................

Table 2--70: viParseRsrc() Error Codes 2--46.......................

T able 2--71: viPrintf() Parameters 2--48............................

T able 2--72: viPrintf() Completion Codes 2--48......................

T able 2--73: viPrintf() Error Codes 2--48...........................

T able 2--74: Special Characters used with viPrintf() 2--49.............

Table 2--75: ANSI C Standard Modifiers used

with viPrintf() 2--50.........................................

Table 2--76: Enhanced Modifiers to ANSI C Standards

used with viPrintf() 2--52....................................

Table 2--77: Modifiers used with Argument Types

%, c, and d with viPrintf() 2--53..............................

Table 2--78: Modifiers used with Argument Type f

with viPrintf() 2--53........................................

Table 2--79: Modifiers used with Argument

Types s and b with viPrintf() 2--54............................

Table 2--80: Modifiers used with Argument

Types B and y with viPrintf() 2--55............................

T able 2--81: viQueryf() Parameters 2--56...........................

Table 2--82: viQueryf() Completion Codes 2--56.....................

Table 2--83: viQueryf() E rror Codes 2--56..........................

Table 2--84: viRead() Parameters 2--58............................

Table 2--85: viRead() Completion Codes 2--58......................

Table 2--86: viRead() Error Codes 2--58...........................

T able 2--87: Success Code Conditions for GPIB Interfaces

with ViRead() 2--61.........................................

Table 2--88: viReadAsync() Parameters 2--61.......................

Table 2--89: viReadAsync() Completion Cod es 2--61.................

Table 2--90: viReadAsync() Error Codes 2--62......................

viii

Tektronix TekVISA Programmer Manual

Table of Contents

Table 2--91: Special Value for jobId Parameter

with viReadAsync() 2--65....................................

Table 2--92: viReadSTB() Parameters 2--66.........................

Table 2--93: viReadSTB() Completion Codes 2--66...................

Table 2--94: viReadSTB() Error Codes 2--66........................

Table 2--95: viReadToFile() Parameters 2--68.......................

Table 2--96: viReadToFile() Completion Codes 2--68.................

Table 2--97: viReadToFile() Error Codes 2--68......................

Table 2--98: Special Value for the retCount Parameter

with viReadToFile() 2--69.....................................

Table 2--99: viScanf() Parameters 2--70............................

Table 2--100: viScanf() Completion Cod es 2--70.....................

Table 2--101: viScanf() Error Codes 2--70..........................

Table 2--102: ANSI C Standard Modifiers used

with viScanf() 2--73.........................................

Table 2--103: Enhanced Modifiers to ANSI C Standards

used with viScanf() 2--73.....................................

Table 2--104: Modifiers used with Argument Type c

with viScanf() 2--74.........................................

Table 2--105: Modifiers used with Argument Type d

with viScanf() 2--74.........................................

Table 2--106: Modifiers used with Argument Type f

with viScanf() 2--74.........................................

Table 2--107: Modifiers used with Argument Type s

with viScanf() 2--75.........................................

Table 2--108: Modifiers used with Argument Type b

with viScanf() 2--76.........................................

Table 2--109: Modifiers used with Argument Type t

with viScanf() 2--76.........................................

Table 2--110: Modifiers used with Argument Type T

with viScanf() 2--77.........................................

Table 2--111: Modifiers used with Argument Type y

with viScanf() 2--77.........................................

Table 2--112: viSetAttribute() Parameters 2--78.....................

Table 2--113: viSetAttribute() Completion Codes 2--78...............

Table 2--114: viSetAttribute() Error Codes 2--79....................

T able 2--115: viSetBuf() Parameters 2--80..........................

T able 2--116: viSetBuf() Completion Codes 2--80....................

Table 2--117: viSetBuf() Error Codes 2--80.........................

Table 2--118: Flags used with Mask Parameter

with viSetBuf() 2--81........................................

Tektronix TekVISA Programmer Manual

Table of Contents

T able 2--119: viSPrintf() Parameters 2--82..........................

Table 2--120: viSPrintf() Completion Codes 2--82....................

Table 2--121: viSPrintf() Error Codes 2--82.........................

Table 2--122: viSScanf() Parameters 2--84..........................

Table 2--123: viSScanf() Completion Codes 2--84....................

Table 2--124: viSScanf() Error Codes 2--85.........................

Table 2--125: viStatusDesc() Parameters 2--87......................

Table 2--126: viStatusDesc() Completion Codes 2--87.................

Table 2--127: viTerminate() Parameters 2--88.......................

Table 2--128: viTerminate() Completion Codes 2--88.................

Table 2--129: viTerminate() Error Codes 2--88......................

Table 2--130: viUninstallHandler() Parameters 2--89.................

Table 2--131: viUninstallHandler() Completion Codes 2--89...........

Table 2--132: viUninstallHandler() Error Codes 2--89................

Table 2--133: Special Values for handler Parameter

with viUninstallHandler() 2--90...............................

Table 2--134: viUnlock() Parameters 2--90..........................

Table 2--135: viUnlock() Completion Codes 2--91....................

Table 2--136: viUnlock() Error Codes 2--91.........................

Table 2--137: viUsbContrlIn() Parameters 2--92.....................

Table 2--138: viUsbContrlIn() Completion Codes 2--92...............

Table 2--139: viUsbContrlIn() Error Codes 2--93....................

Table 2--140: viUsbContrlOut() Parameters 2--95...................

Table 2--141: viUsbContrlOut() Completion Cod es 2--96.............

Table 2--142: viUsbContrlOut() Error Codes 2--96...................

Table 2--143: viVPrintf() Parameters 2--98.........................

Table 2--144: viVPrintf() Completion Codes 2--98...................

Table 2--145: viVPrintf() Error Codes 2--98........................

Table 2--146: viVQueryf() Parameters 2--100........................

Table 2--147: viVQueryf() Completion Codes 2--101..................

Table 2--148: viVQueryf() E rror Codes 2--101.......................

Table 2--149: viVScanf() Parameters 2--102..........................

Table 2--150: viVScanf() Completion Cod es 2--102....................

Table 2--151: viVScanf() Error Codes 2--103.........................

Table 2--152: viVSPrintf() Parameters 2--104........................

Table 2--153: viVSPrintf() Completion Codes 2--104..................

Table 2--154: viVSPrintf() Error Codes 2--104.......................

Table 2--155: viVSScanf() Parameters 2--106........................

Table 2--156: viVSScanf() Completion Codes 2--106..................

Tektronix TekVISA Programmer Manual

Table of Contents

Table 2--157: viVSScanf() Error Codes 2--106........................

Table 2--158: viWaitOnEvent() Parameters 2--108....................

Table 2--159: viWaitOnEvent() Completion Codes 2--108..............

Table 2--160: viWaitOnEvent() Error Codes 2--108...................

Table 2--161: Special Values for inEventType Parameter

with viWaitOnEvents() 2--109.................................

Table 2--162: Special Values for timeout Parameter

with viWaitOnEvents() 2--109.................................

Table 2--163: Special Values for outEventType Parameter

with viWaitOnEvents() 2--109.................................

Table 2--164: Special Values for outContext Parameter

with viWaitOnEvents() 2--110.................................

Table 2--165: viWrite() Parameters 2--110...........................

Table 2--166: viWrite() Completion Codes 2--110.....................

Table 2--167: viWrite() Error Codes 2--111..........................

Table 2--168: Special Value for retCount Parameter

with viWrite() 2--111.........................................

Table 2--169: viWriteAsync() Parameters 2--112......................

Table 2--170: viWriteAsync() Completion Codes 2--112................

Table 2--171: viWriteAsync() Error Codes 2--112.....................

Table 2--172: Special Value for jobId Parameter

with viWriteAsync() 2--115....................................

Table 2--173: viWriteFromFile Parameters 2--116....................

Table 2--174: viWriteFromFile Completion Codes 2--116..............

Table 2--175: viWriteFromFile() Error Codes 2--116..................

Table 2--176: Special Value for retCount Parameter

with viWriteFromFile() 2--117.................................

Table 3--1: Table of VISA Attributes by Category 3-- 1...............

Table 3--2: VI_ATTR_ASRL_AVAIL_NUM Attribute 3--5...........

Table 3--3: VI_ATTR_ASRL_BAUD Attribute 3--5.................

Table 3--4: VI_ATTR_ASRL_CTS_STATE Attribute 3--6...........

Table 3--5: VI_ATTR_ASRL_DATA_BITS Attribute 3--6............

Table 3--6: VI_ATTR_ASRL_DCD_STATE Attribute 3--7...........

Table 3--7: VI_ATTR_ASRL_DSR_STATE Attribute 3--7...........

Table 3--8: VI_ATTR_ASRL_DTR_STATE Attribute 3--8...........

Table 3--9: VI_ATTR_ASRL_END_IN Attribute 3--8...............

Table 3--10: VI_ATTR_ASRL_END_OUT Attribute 3--9............

Table 3--11: VI_ATTR_ASRL_FLOW_CNTRL Attribute 3--10........

Table 3--12: VI_ATTR_ASRL_PARITY Attribute 3--11..............

Tektronix TekVISA Programmer Manual

Table of Contents

Table 3--13: VI_ATTR_ASRL_REPLACE_CHAR

Attribute 3--11.............................................

Table 3--14: VI_ATTR_ASRL_RI_STATE Attribute 3--12............

Table 3--15: VI_ATTR_ASRL_RTS_STATE Attribute 3--12..........

Table 3--16: VI_ATTR_ASRL_STOP_BITS Attribute 3--13...........

Table 3--17: VI_ATTR_ASRL_XOFF_CHAR Attribute 3--13.........

Table 3--18: VI_ATTR_ ASRL_XON_CHAR Attribute 3--14..........

Table 3--19: VI_ATTR_BUFFER Attribute 3--14....................

Table 3--20: VI_ATTR_EVENT_TYPE Attribute 3--15...............

Table 3--21: VI_ATTR_GPIB_PRIMARY_ADDR Attribute 3--15......

Table 3--22: VI_ATTR_GPIB_READDR_EN Attribute 3--16..........

Table 3--23: VI_ATTR_GPIB_SECONDARY_ADDR

Attribute 3--16.............................................

Table 3--24: VI_ATTR_GPIB_UNADDR_EN Attribute 3--17..........

Table 3--25: VI_ATTR_INTF_INST_NAME Attribute 3--17..........

Table 3--26: VI_ATTR_INTF_NUM Attribute 3--18.................

Table 3--27: VI_ATTR_INTF_TYPE Attribute 3--18.................

Table 3--28: VI_ATTR_IO_PROT Attribute 3--19...................

Table 3--29: VI_ATTR_Job_ID Attribute 3--19......................

Table 3--30: VI_ATTR_MAX_QUEUE_LENGTH Attribute 3--20.....

Table 3--31: VI_ATTR_OPER_NAME Attribute 3--20...............

Table 3--32: VI_ATTR_RD_BUF_OPER_MODE Attribute 3--21......

Table 3--33: VI_ATTR_RET_COUNT Attribute 3--21................

Table 3--34: VI_ATTR_RM_SESSION Attribute 3--22...............

Table 3--35: VI_ATTR_RSRC_IMPL_VERSION Attribute 3--22......

T able 3--36: ViVersion Description for

VI_ATTR_RSRC_IMPL_VERSION 3--22......................

Table 3--37: VI_ATTR_RSRC_LOCK_STATE Attribute 3--23........

Table 3--38: VI_ATTR_RSRC_MANF_ID Attribute 3--23............

Table 3--39: VI_ATTR_RSRC_MANF_NAME Attribute 3--24........

Table 3--40: VI_ATTR_RSRC_NAME Attribute 3--24...............

Table 3--41: Resource Address String Grammar 3--25...............

Table 3--42: VI_ATTR_RSRC_SPEC_VERSION Attribute 3--25......

T able 3--43: ViVersion Description for

VI_ATTR_RSRC_SPEC_VERSION 3-- 25......................

Table 3--44: VI_ATTR_SEND_END_EN Attribute 3--26..............

Table 3--45: VI_ATTR_STATUS Attribute 3--26....................

Table 3--46: VI_ATTR_SUPPRESS_END_EN Attribute 3--27.........

Table 3--47: VI_ATTR_TCPIP_ADDR Attribute 3--27...............

xii

Tektronix TekVISA Programmer Manual

Table of Contents

Table 3--48: VI_ATTR_TCPIP_HOSTNAME Attribute 3--28.........

Table 3--49: VI_ATTR_TCPIP_KEEPALIVE Attribute 3--28.........

Table 3--50: VI_ATTR_TCPIP_NODELAY Attribute 3--29...........

Table 3--51: VI_ATTR_TCPIP_PORT Attribute 3--29...............

Table 3--52: VI_ATTR_TERMCHAR Attribute 3--30................

Table 3--53: VI_ATTR_TERMCHAR_EN Attribute 3--30............

Table 3--54: VI_ATTR_TMO_VALUE Attribute 3--31...............

Table 3--55: VI_ATTR_TRIG_ID Attribute 3--31....................

Table 3--56: VI_ATTR_USB_INTFC_NUM Attribute 3--32..........

Table 3--57: VI_ATTR_USB_MAX_INTR_SIZE Attribute 3--32......

Table 3--58: VI_ATTR_USB_PROTOCOL Attribute 3--33...........

Table 3--59: VI_ATTR_USB_RECV_INTR_DATA Attribute 3--33....

Table 3--60: VI_ATTR_USB_RECV_INTR_SIZE Attribute 3--34.....

Table 3--61: VI_ATTR_USB_SERIAL_NUM Attribute 3--34..........

Table 3--62: VI_ATTR_USER_DATA Attribute 3--35................

Table 3--63: VI_ATTR_WR_BUF_OPER_MODE Attribute 3--35......

Table 4--1: VI_EVENT_EXCEPTION Related Attributes 4--1........

Table 4--2: VI_EVENT_IO_COMPLETION

Related Attributes 4--1.....................................

Table 4--3: VI_EVENT _SERVICE_REQ Related

Attributes 4--2............................................

Table A--1: Type Assignments for VISA and Instrument

Driver APIs A--2...........................................

Table A--2: Type Assignments for VISA APIs Only A--6.............

Table B--1: Completion Codes B--1...............................

TableB--2:ErrorCodes B--2....................................

Tektronix TekVISA Programmer Manual

xiii

Table of Contents

xiv

Tektronix TekVISA Programmer Manual

Preface

Who Should Read This Manual

This manual is both a reference and a tutorial. It is intended for use by Tektronix instrumentation end users and application programmers who wish to develop or modify

About This Manual

H VISA

H Applications that use VISA

This programming manual describes TekVISA, the Tektronix implementation of the Virtual Instrument Software Architecture (VISA) Library, an interface pendent software interface endorsed by the VXIplug&play Systems Alliance. The manual is organized as follows:

H The Preface and Getting Started sections briefly cover the audience and

H The Reference section presents TekVISA operations, attributes, and events in

-compliant instrument driver software.

-inde-

conventions for this guide, present overview concepts, summarize TekVISA features and applications, and explain how to configure TekVISA resources.

alphabetical order.

H The Operations Summary chapter summarizes the VISA operations

implemented by Tektronix.

H The Operations chapter describes each VISA operation including its

syntax and sample usage.

H The Attributes Summary chapter summarizes the VISA attributes

H The Attributes chapter describes each VISA attribute including its syntax

H The Events chapter describes each VISA event implemented by

H The Programming Examples section contains short programs that illustrate

usage of VISA operations, attributes, and events to accomplish specific tasks.

H Appendices contain summary information for quick reference.

Tektronix TekVISA Programmer Manual

implemented by Tektronix.

and usage.

Tektronix including its syntax and usage.

Preface

Conventions

H The VISA Data Type Assignments appendix lists VISA data types in

alphabetical order

H The Completion and Error Codes appendix lists operation completion

codes and error codes in alphabetical order.

H A Glossary and Index appear at the end of the manual.

This manual makes use of certain notational conventions and typefaces in distinctive ways, as summarized in Table i.

Table i: Table of Typographic Conventions

Typeface Meaning Example

italics Used to introduce terms or to

specify variables for which actual values should be substituted.

A common I/O library called the Virtual Instrument

Software Architecture (VISA)

boldface Used to emphasize important

points or to denote exact characters to type or buttons to click in step-by-step procedures.

NOTE Used to call attention to notes

or tips in text.

<item1, item2, ...> This notation is used to desig-

nate a variable list of one or more items separated by commas.

Code This font is used to designate

blocks of code.

Menu > Submenu This notation is used to desig-

nate a series of cascading menus.

The requestedKey will be copied into the user buffer referredtobytheaccess-

Key.

The viFindRsrc() operation matches an expression against the resources available for a particular interface.

1. Click OK.

NOTE. Read this carefully.

viScanf (vi, readFmt, <arg1, arg2, ...>)

*result = m_ViStatus;

1. Choose File > Open.

xvi

The example here means: from the File menu, choose Open.

Tektronix TekVISA Programmer Manual

Related Manuals and Information

Refer to the following manuals for information regarding related products, manuals, and programming specifications.

H This programming manual resides in Adobe Acrobat format on the TekVISA

Product Software CD.

Preface

H The AD007 GPIB

related information if you are controlling your instrumentation from a remote PC over an Ethernet GPIB AD007 Product Software CD.

H Refer to the Online Help and Programmer Online Guide for information to

use and program each instrument.

H General information and specifications for Virtual Instrument Software

Architecture (VISA) are available from the web site of the VXIplug&play System Alliance at http://www.vxipnp.org to the Tektronix implementation of VISA:

NOTE. Some of the latest VISA specifications are now available at the IVI Foundation web site at http://www.ivifoundation.org

H VPP

H All related specifications for the VXIplug&play are available at

-4.3: The VISA Library Revision 3.0. This specification is intended

to be used in conjunction with the VPP instrument driver development.

http://www.vxipnp.org

-LAN Adapter User Manual (071-0245-XX) provides

-LAN connection. This guide is located on the

. The following document relates

-3.X specifications supporting

H All related specifications for the IVI are available at

Tektronix TekVISA Programmer Manual

http://www.ivifoundation.org

xvii

Preface

xviii

Tektronix TekVISA Programmer Manual

Getting Started

Product Description

Test and measurement applications require some kind of I/O library to communicate with test instrumentation. As a step toward industry compatibility, the VXIplug&play S ystems Alliance developed a common I/O library called the Virtual Instrument Software Architecture (VISA).VISA provides a common standard for software developers so that software from multiple vendors, such as instrument drivers, can run on the same platform.

An instrument driver is a library of functions that handles the details of controlling and communicating with a specific instrument such as a Tektronix oscilloscope. Instrumentation end users have been writing their own instrument drivers for years.

This manual describes T ekVISA, the Tektronix implementation of the VISA Application Programming Interface (API). TekVISA is industry software, available with selected Tektronix instrument models, for writing interoperable instrument drivers in a variety of Application Development Environments (ADEs).

TekVISA implements a subset of Version 3.0 of the VISA specification for controlling GPIB, USB, and serial (RS remotely via an Ethernet LAN connection. TekVISA provides the interface pendent functionality needed to control and access the embedded software of Tektronix test and measurement equipment in the following ways:

-232) instrument interfaces locally or

-wide software

-compliant

-inde-

H Using virtual GPIB software running locally on Windows

sation

H Using physical GPIB controller hardware

H Using asynchronous serial controller hardware

H Over a Local Area Network (LAN) that uses VXI

Socket, and one of the following:

H An AD007 LAN

H An Ethernet connection together with VXI

H An Ethernet connection together with Socket server running on

Tektronix TekVISA Programmer Manual

-based instrument-

-11 protocol, TCP/IP

-to-GPIB adapter to GPIB controller hardware

-11 server running on

Windows Series Oscilloscopes

Windows--based instruments such as the DPO/DSA7000 Series Oscilloscopes

-based instruments such as the TDS7000 and TDS/CSA8000

1- 1

Getting Started

H Using a USB connection for USB instruments such as the TDS1000B and

TDS2000B series

H Using TekLink hardware to TekLink-enabled instruments

Features and Benefits

Applications and

Connectivity Supported

by TekVISA

TekVISA offers the following features and benefits:

H Improves ease of use for end users by providing a consistent methodology

for using instrument drivers from a variety of vendors

H Provides language interface libraries for programmers using multiple

Application Development Environments as shown in Figure 1--1, including:

H Microsoft C/C++

H Microsoft Visual Basic

H LabVIEW graphics software using the G language

ATLAB analysis software

H M

H Provides an Instrument Manager utility for setting up and searching

additional VISA resources

H Provides debugging utilities such as TalkerListener and CallMonitor

H Allows software installation on any number of PCs

TekVISA is beneficial in a variety of situations and applications:

H A single instrument driver can be used by multiple Application Development

Environments.

1- 2

H Instrument drivers from several vendors can be combined in a single user

application.

H User programs running on Windows

-based instrumentation can use TekVISA

to control instrument operation via a virtual GPIB software connection,

without using any external GPIB hardware.

H User programs running on remote PCs networked toWindows

-based

instrumentation can use TekVISA to control instrument operation via a

virtual GPIB, VXI

GPIB

-LAN hardware is needed. Only an Ethernet LAN connection is

-11 server, and Socket server connection. No external

required.

H User programs connected locally or remotely to other non

-Windows-based

Tektronix instrumentation can use TekVISA to control instrument operation

via a GPIB, USB, or serial (RS232) connection locally, or remotely via

TCPIP directly or via a Tektronix AD007 GPIB

-LAN adapter.

Tektronix TekVISA Programmer Manual

Figures 1--1 and 1--2 illustrate the variety of software, local hardware, and network connections to embedded instrumentation supported by TekVISA.

Application Development Environments (ADE)

C, C++

Program

Visual Basic

Program

LabVIEW and

LabWindows

MATLAB

Getting Started

Virtual GPIB

(GPIB8)

IVI--COM

GPIB

(GPIB0--GPIB3)

VXIplug &

play

TekVISA Input/Output Library API

ASRL

(RS232 COM1,

COM2)

Test and Measurement Instruments

LAN

(VXI--11, Socket)

TVC

Tek LinkUSB

Figure 1- 1: TekVISA Supports Multiple Development Environment s

Tektronix TekVISA Programmer Manual

1- 3

Getting Started

Remote

UNIX- based Controller

User

Application

Socket

Client

Windows- based

Oscilloscope

Windows--side of Instrument

Socket

Client

Tek Link

User

Application

VXI--11

Client

VXI--11

Server

Ethernet

LAN

Remote

Windows- based Controller

User

Application

VISA Library

Socket

Client

Ethernet

LAN

VXI--11

Client

Embedded Software side

of Instrument

GPIB--LAN Adapter

w/VXI--11 / Ethernet Lan

Local

Windows- based Controller

User

Application

VISA Library

ASRL

GPIB

Hardwave

GPIB

Hardwave

RS--232

Hardwave

USB

VXI--11

Client

ASRL

VISA Library

GPIB

Socket Server

Virtual

GPIB

software

GPIB

connection

Figure 1- 2: TekVISA Supports Local and Remote Connectivity

Non Windows- based

Instruments

1- 4

Tektronix TekVISA Programmer Manual

Terminology

Getting Started

The VISA specification introduces a number of new terms. Refer to the Glossary at the end of this manual for a complete list of terms and definitions. Some key terms are discussed in the following paragraphs and illustrated in Figure 1--3.

Resources, INSTR

Resource, SOCKET

Resource, and Sessions

VISA defines an architecture consisting of many resources that encapsulate device functionality. In VISA, every defined software module is a resource. In general, the term resource is synonymous with the word object in objec architectures. For VISA, resource more specifically refers to a particular implementation or instance, in object is the definition for how to create a particular resource.

A specialized type of resource class is a VISA instrument control (INSTR) resource class, which defines how to control a particular device. An INSTR resource class encapsulates the various operations for a particular device together (reading, writing, triggering, and so on) so that a program can interact with that device through a single resource. TekVISA supports many kinds of devices associated with the INSTR resource class: GPIB, ASRL (serial) devices, USB, TCPIP/LAN, and TekLink.

The TCP/IP Socket (SOCKET) Resource encapsulates the operations and properties of the capabilities of a raw network socket connection using TCP/IP. A VISA Socket Resource like the INSTR resource, starts with the basic operations and attributes of the VISA Resource Template. The SOCKET Resource exposes the capability of a raw network socket connection over TCP/IP.

Applications that use VISA can access device resources by opening sessions to them. A session is a communication path between a software element and a resource. Every session in VISA is unique and has its own life cycle. VISA defines a locking mechanism to restrict access to resources for special circumstances.

-oriented terms, of a resource class, which

t-oriented

Operations, Attributes,

and Events

The Resource Manager

Tektronix TekVISA Programmer Manual

After establishing a session, an application can communicate with a resource by invoking operations associated with the resource or by updating characteristics of resources called attributes. Some attributes depict the instantaneous state of the resource and others define changeable parameters that modify the behavior of resources. A VISA system also allows information exchange through events.

VISA Resource Manager is the name given to the part of VISA that manages resources. This management includes support for opening, closing, and finding resources; setting and retrieving resource attributes; generating events on resources; and so on.

1- 5

Getting Started

The VISA Resource Manager provides access to all resources registered with it. It is therefore at the root of a subsystem of connected resources. Currently, one Resource Manager is available by default after initialization. This is called the Default Resource Manager. This identifier is used when opening resources, finding available resources, and performing other operations on device resources.

raise/respond to

INSTR

Default

Resource

Manager

provides access to

Resources

(Virtual

Instruments)

operate within

Figure 1- 3: Key VISA Terminology for INSTR Resource

Events

have Attributes

perform

Operations

Sessions

1- 6

Tektronix TekVISA Programmer Manual

Default Resource Manager

provides access to

Getting Started

have Attributes

SOCKET

Resources

(Virtual

Instruments)

Virtual Instruments and

Virtual GPIB

perform

operate within

Operations

Sessions

Figure 1- 4: Key VISA Terminology for SOCKET Resource

NOTE. SOCKET connections do not support VISA Events. SOCKET connections automatically perform a viLock() of the interface and cannot be shared like other VISA bus types.

A virtual instrument is a name given to the grouping of software modules (VISA resources with any associated or required hardware) to give the functionality of a traditional stand

-alone instrument. Within VISA, a virtual instrument is

the logical grouping of any of the VISA resources. TekVISA supports USB, ASRL (serial) and GPIB virtual instruments, which work with accompanying USBTMC, RS

-232 and GPIB hardware respectively.

In addition, TekVISA includes a specialized type of GPIB resource called virtual GPIB. User programs running on oscilloscopes with Windows

tation, or running on a remote PC connected by LAN to such an instrument, can access the embedded instrument software by using a virtual GPIB software connection, without the need for any GPIB controller hardware or cables.

Tektronix TekVISA Programmer Manual

-based instrumen-

1- 7

Getting Started

What You Need to Get Started

TekVISA Installation

VISA applications that communicate with Tektronix instrumentation should use TekVISA, the Tektronix version of VISA. You should install and configure TekVISA on each PC that communicates with Tektronix instrumentation using the VISA standard.

The software installation includes a utility to help you configure TekVISA resources. The VISA Instrument Manager allows you to detect USB, GPIB, and serial (ASRL) resource assignments, and to add or remove remote hosts (such as VXI

-11 or Socket clients connected by Ethernet LAN or by an AD007 adapter

and associated GPIB hardware).

NOTE. If you are connecting to a network just to print screen hardcopy data, you do not need to install or configure TekVISA software.

TekVISA comes installed on current Tektronix MS-Windows oscilloscopes as part of the Product Software.

To install TekVISA software on a PC connected to your Tektronix oscilloscope, follow the steps shown below on Table 1--1.

Table 1- 1: Installing TekVISA Software on a PC

Alternative Locations for Finding TekVISA Software

The product software CD for your MS-Windows oscilloscope

The TDSPCS1 OpenChoice PC Communications Software CD

The OpenChoice Solutions Software Developers’ Kit CD

The current TekVISA installation download from the Tektronix Web site

Instructions for Installing TekVISA Software on a PC

In your MS-Windows computer, select Start > Run, browse the CD to the TekVISA folder, and run setup.exe.

Follow the instructions in the installation wizard.

Click on the Developers’ Kit browser button for Software Drivers and then for TekVISA

Unzip the downloaded file in a temporary directory of your choice and run setup.exe.

NOTE. If you have already installed TekVISA from an earlier version of the Tektronix Software Solutions CD or with Wavestar, you should uninstall that version first, and then r einstall TekVISA from the most recent source.

1- 8

Tektronix TekVISA Programmer Manual

+ 234 hidden pages

Tektronix TekVISA Programmer

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

List of Figures

List of Tables

Preface

Getting Started

Product Description

Terminology

What You Need to Get Started