Agilent IO Libraries Suite E2094P Agilent VISA User’s Guide Agilent Technologies
Notices © Agilent Technologies, Inc. 1995-1996, 1998, 2000-2005 No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from Agilent Technologies, Inc. as governed by United States and international copyright laws. Manual Part Number 5188-5798 Edition Eighth edition, August 2005 Agilent Technologies, Inc.
Agilent VISA User’s Guide 1 Introduction What’s in This Guide? 8 VISA Overview 9 Using VISA, VISA COM, and SICL VISA Support 10 VISA Documentation 10 Contacting Agilent 2 9 12 Building a VISA Application in Windows Building a VISA Program (C/C++) 14 Compiling and Linking VISA Programs (C/C++) Sample VISA Program (C/C++) 15 Building a VISA Program (Visual Basic) 19 Visual Basic Programming Considerations Sample VISA Program (Visual Basic) 21 14 19 Logging Error Messages 26 Using the Event Viewer 26
Closing a Session 40 Searching for Resources 40 Sending I/O Commands 43 Types of I/O 43 Using Formatted I/O 43 Using Non-Formatted I/O 54 Using Events and Handlers 57 Events and Attributes 57 Using the Callback Method 65 Using the Queuing Method 74 Trapping Errors 80 Trapping Errors 80 Exception Events 82 Using Locks 87 Lock Functions 87 viLock/viUnlock Functions VISA Lock Types 88 4 87 Programming via GPIB and VXI GPIB and VXI Interfaces Overview 94 General Interface Information 94 GPIB Interfaces Over
Using Low/High-Level Memory I/O Methods 115 Using Low-Level viPeek/viPoke 115 Using High-Level viIn/viOut 116 Using High-Level viMoveIn/viMoveOut Using the Memory Access Resource Memory I/O Services 121 MEMACC Attribute Descriptions Using VXI-Specific Attributes 128 Using the Map Address as a Pointer Setting the VXI Trigger Line 129 5 116 121 124 128 Programming via LAN LAN and Remote Interfaces Overview 132 Direct LAN Connection versus Remote IO Server/Client Connection 132 Remote IO Server/Client Archi
Agilent VISA User’s Guide
Agilent IO Libraries Suite Agilent VISA User’s Guide 1 Introduction This Agilent VISA User’s Guide describes the Agilent Virtual Instrument Software Architecture (VISA) library and shows how to use it to develop I/O applications and instrument drivers on Windows PCs. NOTE Before you can use VISA, you must install and configure VISA on your computer. See the Agilent IO Libraries Suite Getting Started for installation on Windows systems.
1 Introduction What’s in This Guide? This guide shows VISA programming techniques using C/C++ and Visual Basic. This chapter provides an overview of VISA and shows how to contact Agilent Technologies. Subsequent chapters in this guide address the following topics: • Chapter 2 - Building a VISA Application in Windows describes how to build a VISA application in a Windows environment. A sample program is provided to help you get started programming with VISA.
Introduction 1 VISA Overview VISA is an application programming interface (API) for instrument control. It allows you to programmatically send commands and receive data from instruments and other test and measurement devices (such as sources and switches). VISA is a part of the Agilent IO Libraries Suite product.
1 Introduction VISA Support This 32- bit version of VISA is supported on Microsoft Windows 2000 and Windows XP. (For information on support of older operating systems, see the Agilent IO Libraries Suite Online Help.) C, C++, and Visual Basic are supported on these Windows versions. C# and Visual Basic .NET are also supported via the visa32.cs and visa32.vb header files that are included with the Agilent VISA library. VISA is supported on the GPIB, VXI, GPIB- VXI, Serial (RS- 232), LAN, and USB interfaces.
Introduction Table 1 Agilent VISA Documentation VXIbus Consortium specifications (when using VISA over LAN) Agilent VISA User’s Guide 1 TCP/IP Instrument Protocol Specification VXI-11, Rev. 1.0 TCP/IP-VXIbus Interface Specification VXI-11.1, Rev. 1.0 TCP/IP-IEEE 488.1 Interface Specification VXI-11.2, Rev. 1.0 TCP/IP-IEEE 488.2 Instrument Interface Specification - VXI-11.3, Rev. 1.
1 Introduction Contacting Agilent • In the USA, you can reach Agilent Technologies by telephone at: USA: 1- 800- 829- 4444 • Outside the USA, contact your country’s Agilent support organization. A list of contact information for other countries is available on the Agilent Web site: http://www.agilent.com/find/assist • The Agilent Developer Network (ADN), http://www.agilent.
Agilent IO Libraries Suite Agilent VISA User’s Guide 2 Building a VISA Application in Windows This chapter provides guidelines for building a VISA application in a Windows environment. The chapter contains the following sections: • Building a VISA Program (C/C++) • Building a VISA Program (Visual Basic) • Logging Error Messages For information on building a VISA application in Visual Studio .NET, see the VISA Online Help.
2 Building a VISA Application in Windows Building a VISA Program (C/C++) This section provides guidelines for building VISA programs using the C/C++ language, including: • Compiling and Linking VISA Programs (C/C++) • Sample VISA Program (C/C++) Compiling and Linking VISA Programs (C/C++) This section provides a summary of important compiler- specific considerations when developing Win32 applications.
2 Building a VISA Application in Windows • Select Tools > Options from the menu. • Click the Directories tab to set the include file path. • Select Include Files from the Show Directories For list box. • Click at the bottom of the list box and type: C:\Program Files\VISA\winnt\include (This assumes that you used the default installation location for VISA.) • Select Library Files from the Show Directories For list box.
2 Building a VISA Application in Windows Sample C/C++ Program Source Code The source file idn.c follows. An explanation of the various function calls in the sample is provided directly after the program listing. If the program runs correctly and your PC is connected to a 54622A oscilloscope, the following is an example of the program output. AGILENT TECHNOLOGIES,54622A,987654312,A.01.50 If the program does not run, see the Event Viewer for a list of run- time errors. /*idn.
Building a VISA Application in Windows 2 %s\n", buf); /* Close session */ viClose(vi); viClose(defaultRM);} C/C++ Sample Program Contents A summary of the VISA function calls used in the preceding sample C/C++ program follows. For a more detailed explanation of VISA functionality, see Chapter 3, “Programming with VISA.” See the VISA Online Help for more detailed information on these VISA function calls. Table 2 Summary of VISA Function Calls Used in the C/C++ Sample Function(s) Description visa.
2 Building a VISA Application in Windows Table 2 18 Summary of VISA Function Calls Used in the C/C++ Sample viPrintf and viScanf These are the VISA formatted I/O functions that are patterned after those used in the C programming language. The viPrintf call sends the IEEE 488.2 *RST command to the instrument and puts it in a known state. The viPrintf call is used again to query for the device identification (*IDN?). The viScanf call is then used to read the results.
Building a VISA Application in Windows 2 Building a VISA Program (Visual Basic) This section provides guidelines for building a VISA program in the Microsoft Visual Basic (VB) language, including: • Visual Basic Programming Considerations • Sample VISA Program (Visual Basic) Visual Basic Programming Considerations Some considerations for programming in Visual Basic follow. This information applies to Microsoft Visual Basic version 6.
2 Building a VISA Application in Windows VISA cannot call back to a VB function. Thus, you can only use the VI_QUEUE mechanism in viEnableEvent. There is no way to install a VISA event handler in VB. VISA functions that take a variable number of parameters (viPrintf, viScanf, viQueryf) are not callable from VB. Use the corresponding viVPrintf, viVScanf and viVQueryf functions instead. You cannot pass variables of type Variant to VISA functions.
2 Building a VISA Application in Windows Dim flt_array(50) As Double status = viVPrintf(id, "%,50f", dbl_array(0)) Strings When reading in a string value with viVScanf or viVQueryf, you must pass a fixed length string as the params parameter. To declare a fixed length string, instead of using the normal variable length declaration: Dim strVal as String use the following declaration, where 40 is the fixed length.
2 Building a VISA Application in Windows 3 Start a new Visual Basic Standard .exe project. VB 6.0 will open a new project, Project1, with a blank Form, Form1. 4 From the menu, select Project > Add Module, select the Existing tab, and browse to the idn directory. If you used default installation paths, this directory is C:\ Program Files\Agilent\IO Libraries Suite\ ProgrammingSamples\VB6\VISA\idn. 5 Select the file idn.bas and click Open.
Building a VISA Application in Windows 2 If the program does not run, see the Event Viewer for a list of run- time errors. The source file idn.bas follows. Option Explicit '''''''''''''''''''''''''''''''''''''''''''''''' ''''''''''''''''''' ' idn.bas ' This example program queries a GPIB device for ' an identification string and prints the ' results. Note that you may have to change the ' VISA Interface Name and address for your ' device from "GPIB0" and "22",respectively.
2 Building a VISA Application in Windows Call viOpen(defrm, "GPIB0::22::INSTR", 0, 0, vi) ' Initialize device Call viVPrintf(vi, "*RST" + Chr$(10), 0) ' Ask for the device's *IDN string. Call viVPrintf(vi, "*IDN?" + Chr$(10), 0) ' Read the results as a string.
Building a VISA Application in Windows Table 3 viOpen 2 Summary of VISA Function Calls in Visual Basic Sample This function establishes a communication channel with the device specified. A session identifier (vi) that can be used with other VISA functions is returned. This call must be made for each device you will be using. viVPrintf and viVScanf These are the VISA formatted I/O functions. The viVPrintf call sends the IEEE 488.
2 Building a VISA Application in Windows Logging Error Messages When developing or debugging your VISA application, you may want to view internal VISA messages while your application is running. You can do this by using the Event Viewer utility or the Debug Window. There are three choices for VISA logging: • Off (default) for best performance • Event Viewer • Debug Window Using the Event Viewer The Event Viewer utility provides a way to view internal VISA error messages during application execution.
2 Building a VISA Application in Windows such as Microsoft Visual Studio. In this case, VISA messages will appear in the Visual Studio output window. The process for using the Debug Window is: 1 Enable VISA logging from the Agilent IO Control by clicking the blue IO icon on the taskbar and then clicking Agilent VISA Options > VISA Logging > Debug Window. 2 Run your VISA program from Microsoft Visual Studio (or equivalent application).
2 28 Building a VISA Application in Windows Agilent VISA User’s Guide
Agilent IO Libraries Suite Agilent VISA User’s Guide 3 Programming with VISA This chapter describes how to program with VISA. The basics of VISA are described, including formatted I/O, events and handlers, attributes, and locking. Sample programs are also provided and can be found in the ProgrammingSamples subdirectory (C:\Program Files\Agilent\IO Libraries Suite\ ProgrammingSamples in a default installation).
3 Programming with VISA VISA Resources and Attributes This section introduces VISA resources and attributes, including: • VISA Resources • VISA Attributes VISA Resources In VISA, a resource is defined as any device (such as a voltmeter) with which VISA can provide communication. VISA defines six resource classes that a complete VISA system, fully compliant with the VXIplug&play Systems Alliance specification, can implement.
Programming with VISA Table 4 3 Descriptions of Resource Classes Supported by Agilent VISA Resource Class Interface Types Resource Class Description Instrument Control (INSTR) Generic, GPIB, GPIB-VXI, Serial, TCPIP, USB, VXI Device operations (reading, writing, triggering, etc.). GPIB Bus Interface (INTFC) Generic, GPIB Raw GPIB interface operations (reading, writing, triggering, etc.). Memory Access (MEMACC) Generic, GPIB-VXI, VXI Address space of a memory-mapped bus such as the VXIbus.
3 Programming with VISA Sample: Reading a VISA Attribute This code sample reads the state of the VI_ATTR_TERMCHAR_EN attribute and changes it if it is not true.
3 Programming with VISA Using Sessions This section shows how to use VISA sessions, including: • Including the VISA Declarations File (C/C++) • Adding the visa32.bas File (Visual Basic) • Opening a Session to a Resource • Addressing a Session • Closing a Session • Searching for Resources Including the VISA Declarations File (C/C++) For C and C++ programs, you must include the visa.h header file at the beginning of every file that contains VISA function calls: #include "visa.
3 Programming with VISA Opening a Session A session is a channel of communication. Sessions must first be opened on the default resource manager, and then for each resource you will be using. • A resource manager session is used to initialize the VISA system. It is a parent session that knows about all the opened sessions. A resource manager session must be opened before any other session can be opened. • A resource session is used to communicate with a resource on an interface.
3 Programming with VISA The session returned from viOpenDefaultRM must be used in the sesn parameter of the viOpen function. The viOpen function then uses that session and the resource address specified in the rsrcName parameter to open a resource session. The vi parameter in viOpen returns a session identifier that can be used with other VISA functions. Your program may have several sessions open at the same time after creating multiple session identifiers by calling the viOpen function multiple times.
3 Programming with VISA Sample: Opening a Resource Session This code sample shows one way of opening resource sessions with a GPIB multimeter and a GPIB- VXI scanner. The sample first opens a session with the default resource manager. The sample then uses the session returned from the resource manager, and a VISA address, to open a session with the GPIB device at address 22. You can now identify that session as dmm when you call other VISA functions.
Programming with VISA 3 The following table illustrates the format of the rsrcName for different VISA interface types. INSTR is an optional parameter that indicates that you are communicating with a resource that is of type INSTR, meaning instrument. The keywords are: • ASRL - used for asynchronous serial devices. • GPIB - used for GPIB devices and interfaces. • GPIB- VXI - used for GPIB- VXI controllers. • TCPIP - used for LAN instruments. • VXI - used for VXI instruments.
3 Programming with VISA The following table describes the parameters used above. Table 7 Description of Parameters Parameter Description board This optional parameter is used if you have more than one interface of the same type. The default value for board is 0. host address The IP address (in dotted decimal notation) or the name of the host computer/gateway. LAN device name The assigned name for a LAN device. The default is inst().
3 Programming with VISA Table 8 Examples of Valid VISA Addresses GPIB::1::0::INSTR A GPIB device at primary address 1 and secondary address 0 in GPIB interface 0. ASRL1::INSTR A serial device located on port 1. VXI::MEMACC Board-level register access to the VXI interface. GPIB-VXI1::MEMACC Board-level register access to GPIB-VXI interface number 1. GPIB2::INTFC Interface or raw resource for GPIB interface 2.
3 Programming with VISA viOpenDefaultRM(&defaultRM); viOpen(defaultRM, "GPIB0::23::INSTR", VI_NULL, VI_NULL,&vi); . . viClose(vi); viClose(defaultRM); Closing a Session You must use the viClose function to close each session. You can close the specific resource session, which will free all data structures that had been allocated for the session. If you close the default resource manager session, all sessions opened using that resource manager session will be closed.
Programming with VISA 3 . viFindNext(findList, instrDesc); . . viClose (findList); The parameters are defined as follows. Table 9 Definitions of Parameters Parameter Description sesn The resource manager session. expr The expression that identifies what to search (see Table 10). findList A handle that identifies this search. This handle will then be used as an input to the viFindNext function when finding the next match. retcnt A pointer to the number of matches found.
3 Programming with VISA Table 10 Determining What to Use for the expr Parameter Interface expr Parameter GPIB GPIB[0-9]*::?*INSTR VXI VXI?*INSTR GPIB-VXI GPIB-VXI?*INSTR GPIB and GPIB-VXI GPIB?*INSTR All VXI ?*VXI[0-9]*::?*INSTR ASRL ASRL[0-9]*::?*INSTR All ?*INSTR Sample: Searching the VXI Interface for Resources This code sample searches the VXI interface for resources.
3 Programming with VISA Sending I/O Commands This section provides guidelines for sending I/O commands, including: • Types of I/O • Using Formatted I/O • Using Non- Formatted I/O Types of I/O Once you have established a communications session with a device, you can start communicating with that device using VISA's I/O routines. VISA provides both formatted and non- formatted I/O routines. • Formatted I/O converts mixed types of data under the control of a format string.
3 Programming with VISA These are raw I/O functions and do not intermix with the formatted I/O functions. See “Using Non- Formatted I/O” in this chapter for details. See the VISA Online Help for more information on how data is converted under the control of the format string. Formatted I/O Functions As noted, the VISA formatted I/O functions are viPrintf, viQueryf, and viScanf. • The viPrintf functions format according to the format string and send data to a device.
Programming with VISA 3 Formatted I/O Conversion The formatted I/O functions convert data under the control of the format string. The format string specifies how the argument is converted before it is input or output. The format specifier sequence consists of a % (percent) followed by an optional modifier(s), followed by a format code. %[modifiers]format code (See Table 11, “Descriptions of Format Codes,” on page 46.) Zero or more modifiers may be used to change the meaning of the format code.
3 Programming with VISA Sample: Using Field Width Modifier The following sample pads numb to six characters and sends it to the session specified by vi: int numb = 61; viPrintf(vi, "%6d\n", numb); Inserts four spaces, for a total of 6 characters: 61 .Precision Precision is an optional integer preceded by a period. This modifier is only used with the viPrintf and viQueryf (writeFmt) functions. The meaning of this argument is dependent on the conversion character used.
3 Programming with VISA Argument Length Modifier argument length modifier h, on the conversion character, table. Note that z and Z are modifiers. The meaning of the optional l, L, z, or Z is dependent as listed in the following not ANSI C standard Table 12 Argument Length Modifiers Argument Length Modifier Format Description Codes h d,b,B Corresponding argument is a short integer or a reference to a short integer for d.
3 Programming with VISA For viPrintf or viQueryf (writeFmt), you can use an asterisk (*) in place of the integer to indicate that the integer is taken from the next argument. For viScanf or viQueryf (readFmt), you can use a # sign to indicate that the next argument is a reference to the array size.
Programming with VISA 3 grouping operator, and the or operator | in a regular expression has the lowest precedence. The following table provides detailed descriptions of special characters and operators. Some example expressions follow in Table 14. Table 13 Agilent VISA User’s Guide Descriptions of Special Characters and Operators Special Characters and Operators Description ? Matches any one character. \ Makes the character that follows it an ordinary character instead of special character.
3 Programming with VISA Table 13 \" Sends the ASCII double quote character. \\ Sends a backslash character.
3 Programming with VISA Format Codes. This table summarizes the format codes for sending and receiving formatted I/O. Table 15 Format Codes for Sending and Receiving Formatted I/O Format Codes Description viPrintf/viVPrintf and viQueryf/viVqueryf (writeFmt) d, i Corresponding argument is an integer. f Corresponding argument is a double. c Corresponding argument is a character. s Corresponding argument is a pointer to a null terminated string. % Sends an ASCII percent (%) character.
3 Programming with VISA char data[180]; viScanf(vi, "%t", data); Formatted I/O Buffers The VISA software maintains both a read and write buffer for formatted I/O operations. Occasionally, you may want to control the actions of these buffers. You can modify the size of the buffer using the viSetBuf function. See the VISA Online Help for more information on this function. The write buffer is maintained by the viPrintf or viQueryf (writeFmt) functions.
Programming with VISA 3 You can manually flush the read and write buffers using the viFlush function. Flushing the read buffer also includes reading all pending response data from a device. If the device is still sending data, the flush process will continue to read data from the device until it receives an END indicator from the device. Sample: Sending and Receiving Formatted I/O This C sample program shows sending and receiving formatted I/O.
3 Programming with VISA /* Initialize device */ viPrintf(vi, "*RST\n"); /* Set up device and send a comma-separated list */ viPrintf(vi, "CALC:DBM:REF 50\n"); viPrintf(vi, "MEAS:VOLT:AC? %,2f\n", list); /* Read results */ viScanf(vi, "%lf", &res); /* Print results */ printf("Measurement Results: %lf\n", res); /* Close session */ viClose(vi); viClose(defaultRM); } Using Non-Formatted I/O There are two non- buffered, non- formatted I/O functions that synchronously transfer data called viRead and viWrite.
3 Programming with VISA viWrite. The viWrite function synchronously sends the data pointed to by buf to the device specified by vi. Only one synchronous write operation can occur at any one time. viWrite(vi, buf, count, retCount); viReadAsync. The viReadAsync function asynchronously reads raw data from the session specified by the vi parameter and stores the results in the location where buf is pointing. This operation normally returns before the transfer terminates.
3 Programming with VISA #include #include void main () { ViSession defaultRM, vi; char strres [20]; unsigned long actual; /* Open session to GPIB device at address 22 */ viOpenDefaultRM(&defaultRM); viOpen(defaultRM, "GPIB0::22::INSTR", VI_NULL,VI_NULL, &vi); /* Initialize device */ viWrite(vi, (ViBuf)"*RST\n", 5, &actual); /* Set up device and take measurement */ viWrite(vi, (ViBuf)"CALC:DBM:REF 50\n", 16, &actual); viWrite(vi, (ViBuf)"MEAS:VOLT:AC? 1, 0.
3 Programming with VISA Using Events and Handlers This section provides guidelines to using events and handlers, including: • Events and Attributes • Using the Callback Method • Using the Queuing Method Events and Attributes Events are special occurrences that require attention from your application. Event types include Service Requests (SRQs), interrupts, and hardware triggers. Events will not be delivered unless the appropriate events are enabled.
3 Programming with VISA • Enable one or several events with viEnableEvent and call the viWaitOnEvent function. The viWaitOnEvent function will suspend the program execution until the specified event occurs or the specified timeout period is reached. This is called queuing. The queuing and callback mechanisms are suitable for different programming styles. The queuing mechanism is generally useful for non- critical events that do not need immediate servicing.
Programming with VISA Table 16 3 . Instrument Control (INSTR) Resource Events VI_EVENT_SERVICE_REQUEST Notification that a service request was received from the device. Event Attribute Description AP Data Type Range VI_ATTR_EVENT_TYPE Unique logical identifier of the event. RO ViEventType VI_EVENT_SERVICE_REQ VI_EVENT_VXI_SIGP Notification that a VXIbus signal or VXIbus interrupt was received from the device.
3 Programming with VISA Table 16 Instrument Control (INSTR) Resource Events VI_ATTR_STATUS Return code of the asynchronous I/O operation that has completed. RO ViStatus N/A VI_ATTR_JOB_ID Job ID of the asynchronous operation that has completed. RO ViJobId N/A VI_ATTR_BUFFER Address of a buffer that was used in an asynchronous operation. RO ViBuf N/A VI_ATTR_RET_COUNT Actual number of elements that were asynchronously transferred.
Programming with VISA Table 16 Instrument Control (INSTR) Resource Events VI_ATTR_STATUS Table 17 3 Specifies the status of the read operation from the USB interrupt-IN pipe. If the device sent more data than the user specified in VI_ATTR_USB_MAX_INTR_SIZE, then this attribute value will contain an error code.
3 Programming with VISA Table 18 GPIB Bus Interface (INTFC) Resource Events VI_EVENT_GPIB_CIC Notification that the GPIB controller has gained or lost CIC (controller in charge) status Event Attribute Description AP Data Type Range VI_ATTR_EVENT_TYPE Unique logical identifier of the event. RO ViEventType VI_EVENT_GPIB_CIC VI_ATTR_GPIB_RECV_CIC_ STATE Controller has become controller-in-charge.
Programming with VISA Table 18 3 GPIB Bus Interface (INTFC) Resource Events VI_ATTR_EVENT_TYPE Unique logical identifier of the event. RO ViEventType VI_EVENT_TRIG VI_ATTR_RECV_TRIG_ID The identifier of the triggering mechanism on which the specified trigger event was received. RO ViInt16 VI_TRIG_SW VI_EVENT_IO_COMPLETION Notification that an asynchronous operation has completed. Event Attribute Description AP Data Type Range VI_ATTR_EVENT_TYPE Unique logical identifier of the event.
3 Programming with VISA Table 19 VXI Mainframe Backplane (BACKPLANE) Resource Events VI_ATTR_RECV_TRIG_ID The identifier of the triggering mechanism on which the specified trigger event was received. RO ViInt16 VI_TRIG_TTL0 to VI_TRIG_TTL7; VI_TRIG_ECL0 to VI_TRIG_ECL1 RO ViEventType VI_EVENT_VXI_VME_ SYSFAIL VI_EVENT_VXI_VME_SYSFAIL Notification that the VXI/VME SYSFAIL* line has been asserted. VI_ATTR_EVENT_TYPE Unique logical identifier of the event.
3 Programming with VISA Table 20 TCPIP Socket (SOCKET) Resource Event VI_ATTR_OPER_NAME Name of the operation generating the event. RO ViString N/A Sample: Reading Event Attributes Once you have decided which attribute to check, you can read the attribute using the viGetAttribute function. The following sample shows one way you could check which trigger line fired when the VI_EVENT_TRIG event was delivered.
3 Programming with VISA ViStatus _VI_FUNCH my_handler (ViSession vi, ViEventType eventType, ViEvent context, ViAddr usrHandle) { /* your event handling code here */ return VI_SUCCESS; } main(){ ViSession vi; ViAddr addr=0; . . viInstallHandler(vi, VI_EVENT_SERVICE_REQ, my_handler, addr); viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI_HNDLR, VI_NULL); . /* your code here */ . viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_HNDLR); viUninstallHandler(vi, VI_EVENT_SERVICE_REQ, my_handler, addr); .
Programming with VISA 3 viInstallHandler(vi, eventType, handler, userHandle); These parameters are defined as follows. Table 21 Parameters Used to Install a Handler Parameter Description vi The session on which the handler will be installed. eventType The event type that will activate the handler. handler The name of the handler to be called. userHandle A user value that uniquely identifies the handler for the specified event type.
3 Programming with VISA Use the viUninstallHandler function to uninstall a specific handler, or you can use wildcards (VI_ANY_HNDLR in the handler parameter) to uninstall groups of handlers. See viUninstallHandler in the VISA Online Help for more details on this function. Writing the Handler The handler installed needs to be written by the programmer. The event handler typically reads an associated attribute and performs some sort of action.
3 Programming with VISA Table 22 Description of Parameters Used to Install a Handler mechanism The mechanism by which the event will be enabled. It can be enabled in several different ways. You can use VI_HNDLR in this parameter to specify that the installed handler will be called when the event occurs. Use VI_SUSPEND_HNDLR in this parameter, which puts the events in a queue and waits to call the installed handlers until viEnableEvent is called with VI_HNDLR specified in the mechanism parameter.
3 Programming with VISA This sample program is installed on your system in the ProgrammingSamples subdirectory. See the IO Libraries Suite Online Help for locations of sample programs. /* evnthdlr.c This example program illustrates installing an event handler to be called when a trigger interrupt occurs. Note that you may need to change the address. */ #include #include
Programming with VISA 3 return VI_SUCCESS; } void main(){ ViSession defaultRM,vi; /* open session to VXI device */ viOpenDefaultRM(&defaultRM); viOpen(defaultRM, "VXI0::24::INSTR", VI_NULL, VI_NULL, &vi); /* select trigger line TTL0 */ viSetAttribute(vi, VI_ATTR_TRIG_ID, VI_TRIG_TTL0); /* install the handler and enable it */ viInstallHandler(vi, VI_EVENT_TRIG, myHdlr, (ViAddr)10); viEnableEvent(vi, VI_EVENT_TRIG, VI_HNDLR, VI_NULL); /* fire trigger line, twice */ viAssertTrigger(vi, VI_TRIG_PROT_SYNC); vi
3 Programming with VISA This program is installed on your system in the ProgrammingSamples subdirectory. See the IO Libraries Suite Online Help for locations of sample programs. /* srqhdlr.c This example program illustrates installing an event handler to be called when an SRQ interrupt occurs. Note that you may need to change the address. */ #include #include #if defined (_WIN32) #include /* for Sleep() */ #define YIELD Sleep( 10 ) #elif defined (_WINDOWS) #include
Programming with VISA 3 /* print the event information */ printf("\nSRQ Event Occurred!\n"); printf("...Original Device Session = %ld\n", vi); /* get the status byte */ viReadSTB(vi, &statusByte); printf("...
3 Programming with VISA /* Wait a while for the SRQ to be generated and for the handler to be called. Print something while we wait */ printf("Waiting for an SRQ to be generated."); for (count = 0 ; (count < 10) && (srqOccurred == 0);count++) { long count2 = 0; printf( ".
3 Programming with VISA If the specified event has occurred, the event information is retrieved and the program returns immediately. If the specified event has not occurred, the program suspends execution until a specified event occurs or until the specified timeout period is reached. Sample: Using the Queuing Method This sample program shows one way you can use the queuing method. main(); ViSession vi; ViEventType eventType; ViEvent event; . .
3 Programming with VISA Table 23 Descriptions of Parameters Used to Enable Events Parameter Description vi The session the handler will be installed on. eventType The type of event to enable. mechanism The mechanism by which the event will be enabled. Specify VI_QUEUE to use the queuing method. context Not used in VISA 1.0. Use VI_NULL. When you use VI_QUEUE in the mechanism parameter, you are specifying that the events will be put into a queue.
3 Programming with VISA The event must have previously been enabled with VI_QUEUE specified as the mechanism parameter. Sample: Wait on Event for SRQ This sample shows how to install a wait on event for service requests. viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE, VI_NULL); viWaitOnEvent(vi, VI_EVENT_SERVICE_REQ, VI_TMO_INFINITE, &eventType, &event); . . viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE); Every time a wait on event is invoked, an event context object is created.
3 Programming with VISA /* evntqueu.c This sample program illustrates enabling an event queue using viWaitOnEvent. Note that you must change the device address. */ #include #include
3 Programming with VISA /* print the event information */ printf("Trigger Event Occurred!\n"); printf("...
3 Programming with VISA Trapping Errors This section provides guidelines for trapping errors, including: • Trapping Errors • Exception Events Trapping Errors The sample programs in this guide show specific VISA functionality and do not include error trapping. Error trapping, however, is good programming practice and is recommended in all your VISA application programs. To trap VISA errors you must check for VI_SUCCESS after each VISA function call.
Programming with VISA 3 Sample: Printing Error Code The following error handler prints a user- readable string describing the error code passed to the function: void err_handler(ViSession vi, ViStatus err){ char err_msg[1024]={0}; viStatusDesc (vi, err, err_msg); printf ("ERROR = %s\n", err_msg); return; } Sample: Checking Instrument Errors When programming instruments, it is good practice to check the instrument to ensure there are no instrument errors after each instrument function.
3 Programming with VISA Exception Events An alternative to trapping VISA errors by checking the return status after each VISA call is to use the VISA exception event. On sessions where an exception event handler is installed and VI_EVENT_EXCEPTION is enabled, the exception event handler is called whenever an error occurs while executing an operation.
Programming with VISA 3 For example, the C++ try/catch block can be used in an application in conjunction with the C++ throw mechanism from within the VISA exception handler. When using the C++ try/catch/throw or other exception- handling mechanisms, the control will not return to the VISA system.
3 Programming with VISA Using the VI_EVENT_EXCEPTION Event You can use the VI_EVENT_EXCEPTION event as notification that an error condition has occurred during an operation invocation. The following table describes the VI_EVENT_EXCEPTION event attributes. Table 24 VI_EVENT_EXCEPTION Event Attributes.
3 Programming with VISA /* Get the function name from the exception context */ viGetAttribute( context, VI_ATTR_OPER_NAME, functionName ); errStrBuffer[0] = 0; viStatusDesc( vi, exceptionErrNbr, errStrBuffer ); printf("ERROR: Exception Handler reports\n" "(%s)\n","VISA function '%s' failed with error 0x%lx\n", "functionName, exceptionErrNbr, errStrBuffer ); return VI_SUCCESS; } void main(){ ViStatus status; ViSession drm; ViSession vi; ViAddr myUserHandle = 0; status = viOpenDefaultRM( &drm ); if ( status
3 Programming with VISA printf( "ERROR: viEnableEvent failed with error 0x%lx\n", status ); } /* Generate an error to demonstrate that the handler will be called */ status = viOpen( drm, "badVisaName", NULL, NULL, &vi ); if ( status < VI_SUCCESS ) { printf("ERROR: viOpen failed with error 0x%lx\n" "Exception Handler should have been called\n" "before this message was printed.
3 Programming with VISA Using Locks In VISA, applications can open multiple sessions to a VISA resource simultaneously. Applications can, therefore, access a VISA resource concurrently through different sessions. However, in certain cases, applications accessing a VISA resource may want to restrict other applications from accessing that resource.
3 Programming with VISA viLock(vi, lockType, timeout, requestedKey, accessKey); The VI_ATTR_RSRC_LOCK_STATE attribute specifies the current locking state of the resource on the given session, which can be either VI_NO_LOCK, VI_EXCLUSIVE_LOCK, or VI_SHARED_LOCK. The VISA viUnlock function is then used to release the lock on a resource. If a resource is locked and the current session does not have the lock, the error VI_ERROR_RSRC_LOCKED is returned.
Programming with VISA 3 a lock on that resource. Thus, locking a resource prevents other, subsequent sessions from acquiring an exclusive lock on that resource. Yet, when multiple sessions have acquired a shared lock, VISA allows one of the sessions to acquire an exclusive lock along with the shared lock it is holding. Also, VISA supports nested locking. That is, a session can lock the same VISA resource multiple times (for the same lock type) via multiple invocations of the viLock function.
3 Programming with VISA /* Open session to GPIB device at address 22 */ viOpenDefaultRM (&defaultRM); viOpen (defaultRM, "GPIB0::22::INSTR", VI_NULL,VI_NULL, &vi); /* Initialize device */ viPrintf (vi, "*RST\n"); /* Make sure no other process or thread does anything to this resource between viPrintf and viScanf calls */ viLock (vi, VI_EXCLUSIVE_LOCK, 2000, VI_NULL, VI_NULL); /* Send an *IDN? string to the device */ viPrintf (vi, "*IDN?\n"); /* Read results */ viScanf (vi, "%t", &buf); /* Unlock this sessi
3 Programming with VISA When the session holding the exclusive lock unlocks the resource via the viUnlock function, all the sessions sharing the lock again have all the access privileges associated with the shared lock. /* lockshr.c This example program queries a GPIB device for an identification string and prints the results. Note that you must change the address. */ #include #include
3 Programming with VISA /* Make sure no other process or thread does anything to this resource between the viPrintf() and the viScanf()calls Note: this also locks out the processes with which we shared our 'shared lock' key.
Agilent IO Libraries Suite Agilent VISA User’s Guide 4 Programming via GPIB and VXI VISA supports three interfaces you can use to access GPIB (General Purpose Interface Bus) and VXI (VME eXtension for Instrumentation) instruments: GPIB, VXI, and GPIB- VXI.
4 Programming via GPIB and VXI GPIB and VXI Interfaces Overview This section provides an overview of the GPIB, GPIB- VXI, and VXI interfaces, including: • General Interface Information • GPIB Interfaces Overview • VXI Interfaces Overview General Interface Information VISA supports three interfaces you can use to access instruments or devices: GPIB, VXI, and GPIB- VXI. The GPIB interface can be used to access VXI instruments via a Command Module.
4 Programming via GPIB and VXI using VISA, you can place the SCPI command within your VISA output function call. Then, the message- based device interprets the SCPI command. In this case you can use the VISA formatted I/O or non- formatted I/O functions and program the message- based device as you would a GPIB device. However, if the message- based device has shared memory, you can access the device's shared memory by doing register peeks and pokes.
4 Programming via GPIB and VXI GPIB Interface (82350 PCI GPIB Cards) Windows PC GPIB Cable GPIB Instruments 5 82350 GPIB Card #1 82350 GPIB Card #2 3 3 Example: GPIB (82350) Interface The GPIB interface system in the following figure consists of a Windows PC with two 82350 GPIB cards connected to three GPIB instruments via GPIB cables. For this system, Agilent Connection Expert has been used to assign GPIB card #1 a VISA name of GPIB0 and to assign GPIB card #2 a VISA name of GPIB1.
Programming via GPIB and VXI 4 GPIB Interface (82350 PCI GPIB Cards) Windows PC Interface VISA Names GPIB Cable GPIB Instruments 5 VISA Name "GPIB0" 82350 GPIB Card #1 "GPIB1" 82350 GPIB Card #2 3 3 VISA Addressing viOpen (... "GPIB0::5::INSTR"...) viOpen (... "GPIB0::3::INSTR"...) viOpen (... "GPIB1::3::INSTR"...
4 Programming via GPIB and VXI VXI Interfaces Overview As shown in the following figure, a typical VXI (E8491) interface consists of an E8491 PC Card in a Windows PC that is connected to an E8491B IEEE- 1394 Module in a VXI mainframe via an IEEE- 1394 to VXI cable. The VXI mainframe also includes one or more VXI instruments. VXI (E8491) Interfaces Windows PC E8491 PC Card VXI Mainframe IEEE-1394 to VXI E 8 4 9 1 B V X I V X I I n s t r . . I. n s t r V X I ..
Programming via GPIB and VXI 4 VXI Interface (E8491B IEEE-1394 to VXI Module) Interface VISA Name Windows PC IEEE-1394 to VXI VISA Name "VXI0" E8491 PC Card VXI Mainframe E 8 4 9 1 B V X I I n s t r LA 8 V X I V X I I . .n. s t r LA 24 .. I n s t r LA 16 VISA Addressing viOpen (... "VXI0::24::INSTR"...
4 Programming via GPIB and VXI NOTE For a GPIB-VXI interface, VISA uses a DLL supplied by the Command Module vendor to translate the VISA VXI calls to Command Module commands that are vendor-specific. The DLL required for Agilent Command Modules is installed by the Agilent IO Libraries Suite installer. This DLL is installed by default when Agilent VISA is installed. GPIB-VXI (E1406A) Interfaces Windows PC GPIB Card GPIB VXI Mainframe E 1 4 0 6 A V X I V X I I n s t r . . I. n s t r V X I ..
4 Programming via GPIB and VXI The Connection Expert utility has been used to assign the GPIB- VXI driver a VISA name of GPIB-VXI0 and to assign the 82350 GPIB card a VISA name of GPIB0. VISA addressing is as shown in the figure. For information on the E1406A Command Module, see the Agilent E1406A Command Module User’s Guide. For information on VXI instruments, see the applicable instrument’s User’s Guide.
4 Programming via GPIB and VXI Using High-Level Memory Functions High- level memory functions allow you to access memory on the interface through simple function calls. There is no need to map memory to a window. Instead, when high- level memory functions are used, memory mapping and direct register access are automatically done. The trade- off, however, is speed. High- level memory functions are easier to use.
Programming via GPIB and VXI Table 25 4 Summary of High-Level Memory Functions viOut16(vi, space, offset, val16); Writes 16 bits of data to the specified offset. viOut32(vi, space, offset, val32); Writes 32 bits of data to the specified offset. viMoveIn8(vi, space, offset, length, buf8); Moves an 8-bit block of data from the specified offset to local memory. viMoveIn16(vi, space, offset, length, buf16); Moves a 16-bit block of data from the specified offset to local memory.
4 Programming via GPIB and VXI The val32 parameter is a pointer to where the data read will be stored. If instead you write to the registers via the viOut32 function, the val32 parameter is a pointer to the data to write to the specified registers. If the device specified by vi does not have memory in the specified address space, an error is returned. The following code sample uses viIn16. ViSession defaultRM, vi; ViUInt16 value; .
Programming via GPIB and VXI 4 High-Level Memory Functions: Sample Programs Two sample programs follow that use the high- level memory functions to read the ID and Device Type registers of a device at the VXI logical address 24. The contents of the registers are then printed out. The first program uses the VXI interface; the second program accesses the backplane with the GPIB- VXI interface. These two programs are identical except for the string passed to viOpen.
4 Programming via GPIB and VXI /* Read device type register contents */ viIn16(dmm, VI_A16_SPACE, 0x02, &devtype_reg); /* Print results */ printf ("ID Register = 0x%4X\n", id_reg); printf ("Device Type Register = 0x%4X\n", devtype_reg); /* Close sessions */ viClose(dmm); viClose(defaultRM); } Sample: Using GPIB-VXI Interface (High-Level) Memory Functions This program uses high- level memory functions and the GPIB- VXI interface to read the ID and Device Type registers of a device at GPIB- VXI0::24.
Programming via GPIB and VXI 4 /* Read instrument id register contents */ viIn16(dmm, VI_A16_SPACE, 0x00, &id_reg); /* Read device type register contents */ viIn16(dmm, VI_A16_SPACE, 0x02, &devtype_reg); /* Print results */ printf ("ID Register = 0x%4X\n", id_reg); printf ("Device Type Register = 0x%4X\n", devtype_reg); /* Close sessions */ viClose(dmm); viClose(defaultRM); } Agilent VISA User’s Guide 107
4 Programming via GPIB and VXI Using Low-Level Memory Functions Low- level memory functions allow direct access to memory on the interface just as do high- level memory functions. However, with low- level memory function calls, you must map a range of addresses and directly access the registers with low- level memory functions, such as viPeek32 and viPoke32. There is more programming effort required when using low- level memory functions. However, the program execution speed can increase.
4 Programming via GPIB and VXI Table 26 Summary of Low-Level Memory Functions viMapAddress(vi, mapSpace, mapBase, mapSize, access, suggested, address); Maps the specified memory space. viPeek8(vi, addr, val8); Reads 8 bits of data from address specified. viPeek16(vi, addr, val16); Reads 16 bits of data from address specified. viPeek32(vi, addr, val32); Reads 32 bits of data from address specified. viPoke8(vi, addr, val8); Writes 8 bits of data to address specified.
4 Programming via GPIB and VXI A pointer to the address space where the memory was mapped is returned in the address parameter. If the device specified by vi does not have memory in the specified address space, an error is returned. Some sample viMapAddress function calls follow.
4 Programming via GPIB and VXI VI_FALSE, VI_NULL, &address); viPeek16(vi, addr, &value) Unmapping Memory Space Make sure you use the viUnmapAddress function to unmap the memory space when it is no longer needed. Unmapping memory space makes the window available for the system to reallocate. Low-Level Memory Functions: Code Samples Two sample programs follow that use the low- level memory functions to read the ID and Device Type registers of the device at VXI logical address 24.
4 Programming via GPIB and VXI /* Open session to VXI device at address 24 */ viOpenDefaultRM(&defaultRM); viOpen(defaultRM, "VXI0::24::INSTR", VI_NULL, VI_NULL, &dmm); /* Map into memory space */ viMapAddress(dmm, VI_A16_SPACE, 0x00, 0x10, VI_FALSE,VI_NULL, &address); /* Read instrument id register contents */ viPeek16(dmm, address, &id_reg); /* Read device type register contents */ /* ViAddr is defined as a void so we must cast /* it to something else to do pointer arithmetic */ viPeek16(dmm, (ViAddr)((
4 Programming via GPIB and VXI registers of the device at GPIB-VXI0::24. Change this address if necessary. Register contents are then displayed.*/ #include #include #include
4 Programming via GPIB and VXI /* Close sessions */ viClose(dmm); viClose(defaultRM); } 114 Agilent VISA User’s Guide
4 Programming via GPIB and VXI Using Low/High-Level Memory I/O Methods VISA supports three different memory I/O methods for accessing memory on the VXI backplane, as shown. All three of these access methods can be used to read and write VXI memory in the A16, A24, and A32 address spaces. The best method to use depends on the VISA program characteristics.
4 Programming via GPIB and VXI • viPeek/viPoke calls do not return status codes. • Only one active viMapAddress is allowed per vi session. • There may be a limit to the number of simultaneous active viMapAddress calls per process or system. Using High-Level viIn/viOut High- level viIn/viOut calls are best in situations where a few widely scattered memory accesses are required and speed is not a major consideration. The advantages of high- level viIn/viOut are: • It is the simplest method to implement.
4 Programming via GPIB and VXI • They provide the best performance when transferring large blocks of data. • They support both block and FIFO mode. The disadvantage of viMoveIn/viMoveOut calls is that they have higher initial overhead than viPeek/viPoke. Sample: Using VXI Memory I/O This program demonstrates using various types of VXI memory I/O. /* memio.c This example program demonstrates the use of various memory I/O methods in VISA. */ #include #include #include
4 Programming via GPIB and VXI */ /* Map into memory space */ viMapAddress (vi, VI_A16_SPACE, 0x00, 0x10, VI_FALSE,VI_NULL, &address); /* ================================================ = Using viPeek ================================================ */ Read instrument id register contents */ viPeek16 (vi, address, &id_reg); /* Read device type register contents ViAddr is defined as a (void *) so we must cast it to something else in order to do pointer arithmetic.
4 Programming via GPIB and VXI /* Print results */ printf ("dereference: ID Register = 0x%4X\n",id_reg); printf ("dereference: Device Type Register =0x%4X\n", devtype_reg); } /* Unmap memory space */ viUnmapAddress (vi); /*============================================== High Level memory I/O = viIn16 ==============================================*/ /* Read instrument id register contents */ viIn16 (vi, VI_A16_SPACE, 0x00, &&id_reg); /* Read device type register contents */ viIn16 (vi, VI_A16_SPACE, 0x02,&d
4 Programming via GPIB and VXI If the value of VI_ATTR_DEST_INCREMENT is 1 (the default),viMoveOut does a block write. If the value of VI_ATTR_DEST_INCREMENT is 0, viMoveOut does a FIFO write. ============================================= */ /* Demonstrate block read. Read instrument id register and device type register into an array.
4 Programming via GPIB and VXI Using the Memory Access Resource For VISA 1.1 and later, the Memory Access (MEMACC) resource type has been added to VXI and GPIB- VXI. VXI::MEMACC and GPIB- VXI::MEMACC allow access to all of the A16, A24, and A32 memory by providing the controller with access to arbitrary registers or memory addresses on memory- mapped buses. The MEMACC resource, like any other resource, starts with the basic operations and attributes of other VISA resources.
4 Programming via GPIB and VXI Although the resource handles the allocation and operation of the window, the programmer must free the window via viUnMapAddress when finished. This makes the window available for the system to reallocate. Sample: MEMACC Resource Program This program demonstrates one way to use the MEMACC resource to open the entire VXI A16 memory and then calculate an offset to address a specific device. /* peek16.c */ #include #include #include
4 Programming via GPIB and VXI ViUInt16*addr16; ViStatusstatus; ViUInt16offset; status = viOpenDefaultRM ( &drm ); checkError( 0, status, "viOpenDefaultRM", EXIT ); /* Open a session to the VXI MEMACC Resource*/ status = viOpen( drm, "vxi0::memacc", VI_NULL, VI_NULL, &vi ); checkError (0, status, "viOpen", EXIT ); /* Calculate the A16 offset of the VXI REgisters for the device at VXI logical address 8. */ offset = 0xc000 + 64 * 8; /* Open a map to all of A16 memory space.
4 Programming via GPIB and VXI /* Print the results. */ printf( "inData16 : 0x%04hx\n", inData16 ); printf( "peekData16: ox%04hx\n", peekData16 ); viClose( vi ); viClose (drm ); } MEMACC Attribute Descriptions Generic MEMACC Attributes The following read- only attributes (VI_ATTR_TMO_VALUE is read/write) provide general interface information. Table 27 124 Attributes That Provide General Interface Information Attribute Description VI_ATTR_INTF_TYPE Interface type of the given session.
4 Programming via GPIB and VXI VXI and GPIB-VXI Specific MEMACC Attributes The following attributes, most of which are read/write, provide memory window control information. Table 28 Attributes That Provide Memory Window Control Information Attribute Description VI_ATTR_VXI_LA Logical address of the local controller. VI_ATTR_SRC_INCREMENT Used in viMoveInxx operation to specify how much the source offset is to be incremented after every transfer.
4 Programming via GPIB and VXI Table 28 Attributes That Provide Memory Window Control Information VI_ATTR_SRC_BYTE_ORDER Specifies the byte order used in high-level access operations, such as viInxx and viMoveInxx, when reading from the source. VI_ATTR_DEST_BYTE_ORDER Specifies the byte order used in high level access operations, such as viOutxx and viMoveOutxx, when writing to the destination.
4 Programming via GPIB and VXI Table 29 Attributes that Provide Specific Address Information VI_ATTR_GPIB_SECONDARY_ADDR Secondary address of the GPIB-VXI controller used by the session. MEMACC Resource Event Attribute The following read- only events provide notification that an asynchronous operation has completed. Table 30 Agilent VISA User’s Guide Events Providing Notification About Asynchronous Operations Attribute Description VI_ATTR_EVENT_TYPE Unique logical identifier of the event.
4 Programming via GPIB and VXI Using VXI-Specific Attributes VXI- specific attributes can be useful to determine the state of your VXI system. Attributes are read- only and read/write. Read- only attributes specify things such as the logical address of the VXI device and information about where your VXI device is mapped. This section shows how you might use some of the VXI- specific attributes. See VISA Resource Classes in the VISA Online Help for information on VISA attributes.
Programming via GPIB and VXI 4 Sample: Determining Window Mapping ViAddr address; Vi UInt16 access; ViUInt16 value; . . . viMapAddress(vi, VI_A16_SPACE, 0x00, 0x04, VI_FALSE, VI_NULL, &address); viGetAttribute(vi, VI_ATTR_WIN_ACCESS, &access); . . If(access==VI_USE_OPERS) { viPeek16(vi, (ViAddr)(((ViUInt16 *)address) + 4/sizeof(ViUInt16)), &value) }else if (access==VI_DEREF_ADDR){ value=*((ViUInt16 *)address+4/sizeof(ViUInt16)); }else if (access==VI_NMAPPED){ return error; } . .
4 Programming via GPIB and VXI The above function sets the VXI trigger line to TTL trigger line 0 (VI_TRIG_TTL0). The following are valid VXI trigger lines. (Panel In is an Agilent extension of the VISA specification.
Agilent IO Libraries Suite Agilent VISA User’s Guide 5 Programming via LAN This chapter provides guidelines for programming via a LAN (Local Area Network). A LAN allows you to extend the control of instrumentation beyond the limits of typical instrument interfaces.
5 Programming via LAN LAN and Remote Interfaces Overview This section provides an overview of LAN (Local Area Network) interfaces. A LAN is a way to extend the control of instrumentation beyond the limits of typical instrument interfaces. To communicate with instruments over the LAN, you must first configure a LAN interface or a remote GPIB, USB, or serial interface, using the Agilent Connection Expert.
Programming via LAN 5 Client/Server Model The IO Libraries Suite software uses the client/server model of computing. Client/server computing refers to a model in which an application (the client) does not perform all necessary tasks of the application itself. Instead, the client makes requests of another computing device (the remote I/O server) for certain services.
5 Programming via LAN Windows PCs Client LAN E5810 LAN/GPIB Gateway Remote I/O Server Series 700 workstation or Windows PC GPIB Instrument 134 GPIB bus GPIB bus (or other) LAN Instruments (VXI-11.2 GPIB Emulation or VXI-11.
5 Programming via LAN Addressing LAN-Connected Devices VISA can communicate with LAN- connected devices in one of two ways: • TCPIP interface type • Remote interface type (available only with Agilent IO Libraries Suite) Using the TCPIP Interface Type for LAN Access VISA provides the TCPIP interface type to communicate with LAN- connected devices.
5 Programming via LAN string of alphanumeric characters, starting with a letter. Table 33 Some examples of TCPIP resource strings follow. Example TCPIP Resource Strings String Description TCPIP0::testMachine@agilent.com::gpib0,2::INSTR A VXI-11.2 GPIB device at hostname testMachine@agilent.com. TCPIP0::123.456.0.21::gpib0,2::INSTR A VXI-11.2 GPIB device at a machine whose IP address is 123.456.0.21. TCPIP0::myMachine::inst0::INSTR A VXI-11.3 LAN instrument at hostname myMachine.
5 Programming via LAN NOTE A LAN session to a remote interface provides the same VISA function support as if the interface were local, except that VXI-specific functions are not supported over LAN. Addressing a Session Using the TCPIP Interface Type This sample shows one way to open a device session with a GPIB device at primary address 23 on a remote PC that is running a LAN server. The hostname of the remote PC is myMachine.
5 Programming via LAN as if it were connected to a local interface. If, for example, the GPIB2 interface is configured as a remote GPIB interface, a program controlling the devices GPIB2::5::INSTR and GPIB2::7::INSTR would not be aware of the fact that these devices are actually connected via LAN and not to a GPIB interface connected to the local machine. See the Agilent IO Libraries Suite Online Help for specific information on configuring remote interfaces.
5 Programming via LAN Note that if you have defined a VISA alias for a USB device on the remote I/O server, you must either define the same (or another) alias for the remote USB device on the client PC, or use the full USB resource string. Alias definitions are not shared between the remote I/O server and the client. Addressing a Session Using a Remote Interface In general, the rules to address a remote session are the same as to address a local session.
5 140 Programming via LAN Agilent VISA User’s Guide
Agilent IO Libraries Suite Agilent VISA User’s Guide 6 Programming via USB This chapter provides guidelines for VISA programming of USB instruments that conform to USBTMC (Universal Serial Bus Test and Measurement Class) and/or USBTMC- USB488 (Universal Serial Bus Test and Measurement Class, Subclass USB488 Specification).
6 Programming via USB USB Interfaces Overview USBTMC/USBTMC- USB488 instruments are detected and automatically configured by Agilent VISA when they are plugged into the computer. The Agilent IO Libraries Suite Online Help describes the USB instrument configuration process in more detail. NOTE Do not confuse the Agilent 82357 USB/GPIB Interface with a USBTMC device. The 82357 is automatically configured as a GPIB interface, not as a USBTMC device, when it is plugged into the computer.
6 Programming via USB Communicating with a USB Instrument Using VISA To establish communications with a USB device using VISA, you can either use the full VISA resource string for the device or use the alias provided by VISA. Using the alias is recommended, for reasons described below. Using the full VISA resource string, a viOpen call would look something like this: viOpen( . . ., "USB0::2391::1031::0000000123::0::INSTR", . . . ); Following is a summary of the components of this call.
6 Programming via USB Although the case of a VISA alias is preserved, case is ignored when the alias is used in place of the full resource string in a viOpen call. For example, UsbDevice1, usbdevice1 and USBDEVICE1 all refer to the same device. Using the alias, a viOpen call would look something like this: viOpen( . . ., "UsbDevice1", . . . ); As you can see, this is much simpler than having to use the full resource string for a USB device. Using the alias in a program also makes it more portable.
Agilent IO Libraries Suite Agilent VISA User’s Guide access board The GPIB interface to which a particular device is connected. Active Controller See "Controller in Charge". address A string (or other language construct) that uniquely locates and identifies a resource. VISA defines an ASCII- based grammar that associates address strings with particular physical devices or interfaces and VISA resources.
attribute In VISA and SICL, a value that indicates the operational state of a resource. Some attributes can be changed; others are read- only. board A GPIB interface. It may be a physical board, an adapter (such as the 82357 USB/GPIB adapter), or a remote GPIB interface. board descriptor A handle, returned from ibfind, that uniquely identifies a GPIB interface (board) in Agilent 488 original API calls. Also called an interface descriptor or board unit descriptor.
command bytes GPIB commands encoded as individual bytes. Also called GPIB commands or interface messages. commander In test- system architectures, a device that has the ability to control another device. In a specialized case, a commander may also be the device that has sole control over another device (as with the VXI Commander/Servant hierarchy). commander session A session that communicates to the interface’s commander. Commander sessions are used when an interface is in a non- Controller role.
Controller in Charge The device currently in control of the GPIB. device A unit that receives commands from a Controller. A device is typically an instrument, but can also be a computer acting in a non- Controller role or another peripheral such as a printer or plotter. In VISA, a device is logically represented by the association of several VISA resources. device descriptor A handle, returned from ibdev or ibfind, that uniquely identifies a device in Agilent 488 original API calls.
direct I/O Programmatic communication with instruments not involving an instrument driver. Direct I/O may be accomplished by using an IO Library (VISA, VISA COM, SICL, or Agilent 488) or by using direct I/O tools such as those provided by Agilent VEE and Agilent T&M Toolkit. driver See instrument driver and device driver. explorer view The tree view within the Connection Expert window that shows all devices connected to a test system.
interface A connection and medium of communication between devices and controllers. Interfaces include mechanical, electrical, and protocol connections. interface descriptor A handle, returned from ibfind, that uniquely identifies a GPIB interface (board) in Agilent 488 original API calls. Also called a board descriptor or board unit descriptor. interface driver Software that communicates with an interface. The interface driver also handles commands used to perform communications on an interface.
IO Libraries Application programming interfaces (APIs) for direct I/O communication between applications and devices. There are four Agilent IO Libraries in the Agilent IO Libraries Suite: VISA, VISA COM, SICL, and Agilent 488. Listener A device that can receive data from the bus when instructed (addressed to listen) by the System Controller. lock A state that prohibits other users from accessing a resource such as a device or interface. logical unit A number associated with an interface.
operation A defined action that can be performed on a resource. primary VISA The VISA installation that controls the visa32.dll file. The primary VISA will be used by default in VISA applications. See also secondary VISA. process An operating system component that shares a system's resources. A single- process computer system allows only a single program to execute at any given time.
resource (or resource instance) In VISA, an implementation of a resource class (in object- oriented terms, an instance of a resource class). For example, an instrument is represented by a resource instance. resource class The definition of a particular resource type (a class in object- oriented terms). For example, the VISA Instrument Control resource classes define how to create a resource to control a particular capability of a device.
SICL Standard Instrument Control Library. SICL is an Agilent- defined API for instrument I/O. Agilent SICL is one of the IO Libraries installed with Agilent IO Libraries Suite. side-by-side A side- by- side installation allows two vendors' implementations of VISA to be used on the same computer. See also primary VISA and secondary VISA. SRQ An IEEE- 488 Service Request. This is an asynchronous request (an interrupt) from a remote device that requires service.
System Controller One Controller on a GPIB is the System Controller. This is a master Controller; it has the ability to demand control and to assert the IFC (Interface Clear) and REN (remote enable) lines. system tray See notification area. Talker A device that transmits data onto the bus when instructed (addressed to talk). task guide The information and logic represented in the left pane of the Connection Expert window.
ViFind32 A console application that uses the viFindRsrc and viFindNext VISA functions to enumerate all resources visible to VISA. This application is useful for verifying that all expected interfaces have been configured by Connection Expert, and that the expected devices have been attached. ViFind32 is part of the Agilent IO Libraries Suite.
VISA COM The VXIplug&play specification for a COM- compliant VISA I/O library and its implementation. Agilent VISA COM is part of the Agilent IO Libraries Suite. VISA Instrument Control Resources The VISA definition of device- specific resource classes. VISA Instrument Control Resources include all VISA- defined device and interface capabilities for direct, low- level instrument control. VISA name The prefix of a VISA address, also called the VISA interface ID. The VISA name specifies the interface.
Agilent VISA User’s Guide
Index A addressing addressing device sessions, 36 devices, 36 Agilent 488, 145 Agilent web site, 12 attributes setting VXI trigger lines, 129 VXI, 128 B buffers formatted I/O, 53 C callbacks and events, 57, 65 closing device sessions, 40 conversion, formatted I/O, 45 D declarations file, 33 default resource manager, 34 device sessions addressing, 36 closing, 40 opening, 34 E enable events for callback, 68 enable events for queuing, 75 event handler, 68 events callback, 57, 65 enable for callback, 68 ena
Index L LAN hardware architecture, 132 interfaces overview, 132 locking, 35, 87 locks using, 87 low-level memory functions, 108 low-level memory functions for VXI, 108 M MEMACC attribute descriptions, 124 memory functions, high-level, 102 memory functions, low-level, 108 N NI-488, 145 non-formatted I/O mixing with formatted I/O, 54 sessions device, 34 opening, 34 resource manager, 34 SRQs, 57 starting the resource manager, 34 T timeout, 35, 77 trigger lines, 130 triggers and events, 57 U USB communica
