NI-488.2 ™ NI-488.2 User Manual for Windows NI-488.
Worldwide Technical Support and Product Information www.natinst.
Important Information Warranty The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives notice of such defects during the warranty period.
Contents About This Manual Using the NI-488.2 Documentation...............................................................................xi Accessing the NI-488.2 Online Help...............................................................xi Conventions ...................................................................................................................xii Related Documentation..................................................................................................
Contents Access Additional Help and Resources......................................................................... 2-14 NI-488.2 Online Help ..................................................................................... 2-14 National Instruments GPIB Web Site ............................................................. 2-15 View or Change GPIB-ENET Network Settings (Windows 98/95 Only) .................... 2-15 Assign IP Address ..................................................................
Contents Chapter 4 Debugging Your Application NI Spy ............................................................................................................................4-1 Global Status Variables .................................................................................................4-2 Existing Applications.....................................................................................................4-3 NI-488.2 Error Codes ..........................................................
Contents Chapter 7 NI-488.2 Programming Techniques Termination of Data Transfers ...................................................................................... 7-1 High-Speed Data Transfers (HS488)............................................................................. 7-2 Enabling HS488 .............................................................................................. 7-2 System Configuration Effects on HS488 ........................................................
Contents Appendix E Windows 2000/NT: Common Questions Appendix F Technical Support Resources Glossary Index Figures Figure 1-1. Figure 1-2. Linear and Star System Configuration ..................................................1-1 Example of Multiboard System Configuration .....................................1-2 Figure 2-1. Figure 2-2. Figure 2-3. Figure 2-4. Figure 2-5. Figure 2-6. Figure 2-7. Measurement & Automation Explorer ..................................................
Contents Table 6-2. Table 6-3. Table 6-4. Syntax for Board-Level Traditional NI-488.2 Calls in Interactive Control ................................................................................ 6-7 Syntax for Multi-Device NI-488.2 Calls in Interactive Control ........... 6-8 Auxiliary Functions in Interactive Control ........................................... 6-9 Table A-1. Table A-2. GPIB Handshake Lines.........................................................................
About This Manual This manual describes the features and functions of the NI-488.2 software for Windows. You can use the NI-488.2 software for Windows with Windows 95, Windows 98, Windows NT version 4.0, or Windows 2000. This manual assumes that you are already familiar with Windows. Using the NI-488.2 Documentation The following NI-488.2 documentation is available on your NI-488.2 for Windows CD: • The Getting Started card briefly describes how to install the NI-488.2 software and your GPIB hardware.
About This Manual Conventions The following conventions appear in this manual: » The » symbol leads you through nested menu items and dialog box options to a final action. The sequence File»Page Setup»Options directs you to pull down the File menu, select the Page Setup item, and select Options from the last dialog box. This icon denotes a note, which alerts you to important information.
1 Introduction This chapter describes how to set up your GPIB system. Setting up and Configuring Your System Devices are usually connected with a cable assembly consisting of a shielded 24-conductor cable with both a plug and receptacle connector at each end. With this design, you can link devices in a linear configuration, a star configuration, or a combination of the two configurations. Figure 1-1 shows the linear and star configurations.
Chapter 1 Introduction Controlling More Than One Interface Figure 1-2 shows an example of a multiboard system configuration. gpib0 is the access interface for the voltmeter, and gpib1 is the access interface for the plotter and printer. The control functions of the devices automatically access their respective interfaces. One GPIB Digital Voltometer gpib0 Plotter Another GPIB gpib1 Printer Figure 1-2.
Chapter 1 Introduction For high-speed operation, the following restrictions apply: • All devices in the system must be powered on. • Cable lengths must be as short as possible with up to a maximum of 15 m of cable for each system. • There must be at least one equivalent device load per meter of cable. If you want to exceed these limitations, you can use a bus extender to increase the cable length or a bus expander to increase the number of device loads.
2 Measurement & Automation Explorer This chapter describes Measurement & Automation Explorer, an interactive utility you can use with the NI-488.2 software. To start Measurement & Automation Explorer, select Start»Programs»National Instruments NI-488.2»Explore GPIB. Overview You can perform the following GPIB-related tasks in Measurement & Automation Explorer: • Establish basic communication with your GPIB instruments. • Scan for instruments connected to your GPIB interface. • Launch the NI-488.
Chapter 2 Measurement & Automation Explorer Starting Measurement & Automation Explorer To start Measurement & Automation Explorer, select Start»Programs»National Instruments NI-488.2»Explore GPIB. Figure 2-1 shows Measurement & Automation Explorer. Figure 2-1. Measurement & Automation Explorer Getting Started with NI-488.2 To get started with GPIB instrument communication using Measurement & Automation Explorer, complete the following steps: 1. Refer to your Getting Started card and install the NI-488.
Chapter 2 b. Measurement & Automation Explorer When the NI-488.2 Software for Windows screen appears, select the View Documentation option, as shown in Figure 2-2. Figure 2-2. Viewing Documentation on Your CD The View Documentation Wizard helps you find the documentation that you want to view. 2. Use the NI-488.2 Getting Started Wizard to verify the installation and establish basic communication with your GPIB instruments. After you install the NI-488.2 software and restart your system, the NI-488.
Chapter 2 Measurement & Automation Explorer Troubleshoot NI-488.2 Problems To troubleshoot NI-488.2 problems, run the NI-488.2 Troubleshooting Wizard, as follows: 1. Select Start»Programs»National Instruments NI-488.2»Explore GPIB to start Measurement & Automation Explorer. 2. Select Help»Troubleshooting»NI-488.2 Troubleshooting Wizard. The Troubleshooting Wizard tests your GPIB interface and displays the results, as shown in Figure 2-3. Figure 2-3. NI-488.
Chapter 2 5. Measurement & Automation Explorer Use either the Add GPIB Hardware Wizard or the NI-488.2 Configuration utility to add your interface. Delete a GPIB Interface Before you physically remove a GPIB interface from your system, you must remove the hardware information, as follows: If your interface is a PCMCIA-GPIB, click on the PC Card icon on the taskbar to stop the PC Card. When you stop the PC Card, the system removes the hardware information from the Device Manager. Note 1.
Chapter 2 Measurement & Automation Explorer Instruments Not Found If the Instruments not Found message appears in the right window pane, Measurement & Automation Explorer did not find any instruments. To solve this problem, make sure that your GPIB instruments are powered on and properly connected to the GPIB interface with a GPIB cable. Then, scan for instruments again, as described in the previous section, Scan for GPIB Instruments.
Chapter 2 Measurement & Automation Explorer 3. Expand the Devices and Interfaces directory by clicking on the + next to the folder. 4. Select your GPIB interface. Measurement & Automation Explorer displays the connected instruments in the right window pane. 5. Right-click on your GPIB instrument and select Communicate with Instrument from the drop-down menu that appears. The NI-488.2 Communicator dialog box appears, as shown in Figure 2-4. Figure 2-4. NI-488.2 Communicator 6.
Chapter 2 Measurement & Automation Explorer 3. Right-click on your GPIB interface and select Interactive Control from the drop-down menu that appears. 4. At the command prompt, type NI-488.2 API calls to communicate interactively with the your instrument. For example, you might use ibdev, ibclr, ibwrt, ibrd, and ibonl. To view the online help for Interactive Control, type help at the Interactive Control command prompt. View NI-488.2 Software Version To view the NI-488.
Chapter 2 Measurement & Automation Explorer NI Spy records and displays all NI-488.2 calls, as shown in Figure 2-5. Figure 2-5. NI-488.2 Calls Recorded by NI Spy For more information about using NI Spy, select Help»Help Topics in NI Spy or refer to Chapter 5, NI Spy Utility. View or Change GPIB Interface Settings To view or change the settings of your GPIB interface, refer to one of the following sections.
Chapter 2 Measurement & Automation Explorer The Properties dialog box appears. Figure 2-6 shows the Properties dialog box for an AT-GPIB/TNT (Plug and Play) interface. Figure 2-6. Properties Dialog Box in Windows 98/95 If you need more information about a field in the Properties dialog box, click on the ? button in the upper-right corner of the dialog box, then click on the field. 4. (Optional) Change the settings for your interface.
Chapter 2 Measurement & Automation Explorer The GPIB Configuration dialog box appears. Figure 2-7 shows the GPIB Configuration dialog box for an AT-GPIB/TNT (Plug and Play) interface in Windows NT. Figure 2-7. GPIB Configuration Utility in Windows NT 4. Select your GPIB Board and click on the Configure button. 5. (Optional) Change the settings for your interface. For more information about changing the settings for your interface, click on the Help button.
Chapter 2 Measurement & Automation Explorer instrument information that Measurement & Automation Explorer displays. Table 2-1.
Chapter 2 Measurement & Automation Explorer Windows 2000/NT To reconfigure GPIB device templates in Windows 2000/NT, complete the following steps: 1. Select Start»Programs»National Instruments NI-488.2»Explore GPIB to start Measurement & Automation Explorer. 2. Expand the Devices and Interfaces directory by clicking on the + next to the folder. 3. Right-click on any GPIB interface and select Properties from the drop-down menu that appears. 4.
Chapter 2 Measurement & Automation Explorer 3. Expand the Devices and Interfaces directory by clicking on the + next to the folder. 4. Click on your GPIB interface and select Tools»Settings»NI-488.2 from the Explorer menu. 5. Enable or disable DOS support in the NI-488.2 Settings dialog box and click on the OK button. 6. If you are prompted to do so, restart your system. Windows 2000/NT To enable NI-488.2 DOS support in Windows 2000/NT, complete the following steps: 1. Open your config.
Chapter 2 3. Measurement & Automation Explorer Right-click on your GPIB interface and select NI-488.2 Help from the drop-down menu that appears. National Instruments GPIB Web Site To access the National Instruments Web site for GPIB, select Start»Programs»National Instruments NI-488.2»Explore GPIB to start Measurement & Automation Explorer. Then, select Help»National Instruments on the Web»GPIB Home Page.
Chapter 2 Measurement & Automation Explorer 3. Expand the Devices and Interfaces directory by clicking on the + next to the folder. 4. Right-click on your GPIB-ENET interface and select Advanced IP Settings from the drop-down menu that appears. To view the built-in, context-sensitive help for the Advanced IP Settings utility, click on the Help button. Update GPIB-ENET Firmware You can run the Update Firmware utility in Measurement & Automation Explorer, as follows: 1.
Developing Your NI-488.2 Application 3 This chapter describes how to develop an NI-488.2 application using the NI-488.2 API. Simple Instrument Control To establish basic communication with your instrument, use the NI-488.2 Communicator, as follows: 1. If you have not already done so, scan for connected instruments as described in the Scan for GPIB Instruments section in Chapter 2, Measurement & Automation Explorer. 2. Select Start»Programs»National Instruments NI-488.
Chapter 3 Developing Your NI-488.2 Application The NI-488.2 Communicator dialog box appears, as shown in Figure 3-1. Figure 3-1. NI-488.2 Communicator 6. Type a command in the Send String field and do one of the following: • To write a command to the instrument then read a response back, click on the Query button. • To write a command to the instrument, click on the Write button. • To read a response from the instrument, click on the Read button.
Chapter 3 Developing Your NI-488.2 Application For advanced interactive communication with GPIB instruments, use the Interactive Control utility, as follows: 1. Select Start»Programs»National Instruments NI-488.2»Explore GPIB to start Measurement & Automation Explorer. 2. Expand the Devices and Interfaces directory by clicking on the + next to the folder. 3. Right-click on your GPIB interface and select Interactive Control from the drop-down menu that appears. 4. At the command prompt, type NI-488.
Chapter 3 Developing Your NI-488.2 Application Choosing How to Use the NI-488.2 API The NI-488.2 API has two subsets of calls to meet your application needs. Both of these sets, the traditional calls and the multi-device calls, are compatible across computer platforms and operating systems, so you can port programs to other platforms with little or no source code modification. For most applications, the traditional NI-488.2 calls are sufficient.
Chapter 3 Developing Your NI-488.2 Application Board-level functions that an NI-488.2 application might use include the following—ibcmd, ibrd, ibwrt, and ibconfig. For a detailed list, refer to the NI-488.2 online help. For instructions on accessing the online help, refer to the Using the NI-488.2 Documentation section in About This Manual. Using Multiple Interfaces and/or Multiple Devices When your system includes an interface that must access multiple devices, use the multi-device NI-488.
Chapter 3 Developing Your NI-488.2 Application you check for possible errors after each call using the ibsta ERR bit, debugging your application is much easier. ibsta is a 16-bit value. A bit value of one (1) indicates that a certain condition is in effect. A bit value of zero (0) indicates that the condition is not in effect. Each bit in ibsta can be set for device-level traditional NI-488.2 calls (dev), board-level traditional NI-488.2 calls and multi-device NI-488.2 calls (brd), or all (dev, brd).
Chapter 3 Developing Your NI-488.2 Application The language header file defines each of the ibsta status bits. You can test for an ibsta status bit being set using the bitwise and operator (& in C/C++). For example, the ibsta ERR bit is bit 15 of ibsta. To check for an NI-488.2 error, use the following statement after each NI-488.2 call: if (ibsta & ERR) printf("NI-488.2 error encountered"); Error Variable (iberr) If the ERR bit is set in ibsta, an NI-488.2 error has occurred.
Chapter 3 Developing Your NI-488.2 Application Programming Models Applications That Communicate with a Single GPIB Device This section describes items you should include in your application and provides general program steps with an NI-488.2 example. Items to Include Include the following items in your application: • Header files—In a C application, include the header files windows.h and decl-32.h. The standard Windows header file, windows.h, contains definitions used by decl-32.h, and decl-32.
Chapter 3 Developing Your NI-488.2 Application GPIB address of your GPIB device, as described in Step 2. Determine the GPIB Address of Your Device in the section Applications That Use Multiple Interfaces or Communicate with Multiple GPIB Devices later in this chapter). • Secondary address for the GPIB instrument (0 if the GPIB instrument does not use secondary addressing). • Timeout period (typically set to T10s, which is 10 seconds).
Chapter 3 Developing Your NI-488.2 Application Applications That Use Multiple Interfaces or Communicate with Multiple GPIB Devices This section describes items you should include in your application and provides general program steps with an NI-488.2 example. Items to Include Include the following items in your application: • Header files—In a C application, include the header files windows.h and decl-32.h. The standard Windows header file, windows.h, contains definitions used by decl-32.h, and decl-32.
Chapter 3 Developing Your NI-488.2 Application Step 2. Determine the GPIB Address of Your Device Use FindLstn to find all the devices attached to the GPIB. The FindLstn function requires the following parameters: • Interface number (typically 0, for GPIB0). • A list of primary addresses, terminated with the NOADDR constant. • A list for reported GPIB addresses of devices found listening on the GPIB. • Limit, which is the number of the GPIB addresses to report.
Chapter 3 Developing Your NI-488.2 Application Step 4a. Use SendList to send the "*IDN?" query command to multiple GPIB devices. The address is the list of GPIB devices to be queried. The buffer that you pass to SendList is the command message to the device. Step 4b. Use Receive for each device to read the responses from each device. Continue communicating with the GPIB devices until you are finished. Cleanup Step 5.
Chapter 3 Developing Your NI-488.2 Application Visual Basic (Version 4.0 or Later) With Visual Basic, you can access the traditional NI-488.2 calls as subroutines, using the BASIC keyword CALL followed by the traditional NI-488.2 call name, or you can access them using the il set of functions. With some of the NI-488.
Chapter 3 Developing Your NI-488.2 Application support 16-bit wide characters, use only the 8-bit ASCII versions, named ibbnaA, ibfindA, ibrdfA, and ibwrtfA. The Unicode versions are named ibbnaW, ibfindW, ibrdfW, and ibwrtfW. You can use either the Unicode or ASCII versions of these functions with Windows 2000/NT, but only the ASCII versions with Windows 98/95. In addition to pointers to the status variables and a handle to the loaded gpib-32.
Chapter 3 Developing Your NI-488.2 Application For the prototypes for each function, refer to the NI-488.2 online help. For instructions on accessing the online help, refer to the Using the NI-488.2 Documentation section in About This Manual. For functions that return an integer value, like ibdev or ibwrt, the pointer to the function needs to be cast as follows: int (_stdcall *Pname) where *Pname is the name of the pointer to the function.
Chapter 3 Developing Your NI-488.2 Application Pibcntl = (long *) GetProcAddress(Gpib32Lib, (LPCSTR)"user_ibcnt"); Pibdev = (int (__stdcall *) (int, int, int, int, int, int)) GetProcAddress(Gpib32Lib, (LPCSTR)"ibdev"); Pibonl = (int (__stdcall *)(int, int)) GetProcAddress(Gpib32Lib, (LPCSTR)"ibonl"); If GetProcAddress fails, it returns a NULL pointer.
Chapter 3 Developing Your NI-488.2 Application Running Existing NI-488.2 Applications Running Existing Win32 and Win16 NI-488.2 Applications The NI-488.2 software includes the necessary components to allow existing Win32 and Win16 NI-488.2 applications to run properly. Running Existing DOS NI-488.2 Applications Under Windows 98/95 To configure the NI-488.2 software to run existing DOS NI-488.2 applications, complete the following steps: 1. Make sure that no older version of the NI-488.
Chapter 3 Developing Your NI-488.2 Application Running Existing DOS NI-488.2 Applications under Windows 2000/NT To run DOS NI-488.2 applications, you must enable NI-488.2 DOS support under Windows 2000/NT. To enable NI-488.2 DOS support in Windows 2000/NT, complete the following steps: 1. 2. Open your config.nt file, located in the Windows 2000/NT system32 directory (for example, c:\windows\system32).
4 Debugging Your Application This chapter describes several ways to debug your application. NI Spy The NI Spy utility monitors NI-488.2 API calls made by NI-488.2 applications. It records NI-488.2 API input and output values from all Win32, Win16, and DOS NI-488.2 applications. To start NI Spy, complete the following steps: 1. Select Start»Programs»National Instruments NI-488.2»Explore GPIB to start Measurement & Automation Explorer. 2.
Chapter 4 Debugging Your Application NI Spy records and displays all NI-488.2 calls, as shown in Figure 4-1. Figure 4-1. NI-488.2 Calls Recorded by NI Spy For more information about using NI Spy, select Help»Help Topics in NI Spy or refer to Chapter 5, NI Spy Utility. Global Status Variables At the end of each NI-488.2 call, the global status variables (ibsta, iberr, ibcnt, and ibcntl) are updated. If you are developing an NI-488.2 application, you should check for errors after each NI-488.2 call.
Chapter 4 Debugging Your Application Existing Applications If the application does not have built-in error detection handling, you can use NI Spy to determine which NI-488.2 call is failing. To start NI Spy, refer to the NI Spy section earlier in this chapter. After you have an NI Spy capture file, you can use NI Spy to search for failed NI-488.2 calls by searching for calls with the ERR bit set. Once you know which NI-488.
Chapter 4 Debugging Your Application Timing Errors If your application fails, but the same calls issued interactively in the Interactive Control utility are successful, your program might be issuing the NI-488.2 calls too quickly for your device to process and respond to them. This problem can also result in corrupted or incomplete data. This should only be a problem with older, non-standard GPIB devices. To check if your interactively issued NI-488.2 calls succeed, use the Interactive Control utility.
Chapter 4 Debugging Your Application Communication Errors The following sections describe communication errors you might encounter in your application. Repeat Addressing Devices adhering to the IEEE 488.2 standard should remain in their current state until specific commands are sent across the GPIB to change their state. However, some devices require GPIB addressing before any GPIB activity. Therefore, you might need to configure your NI-488.
5 NI Spy Utility This chapter introduces you to NI Spy, a utility that monitors and records multiple National Instruments APIs (for example, NI-488.2 and VISA). Overview NI Spy monitors, records, and displays the NI-488.2 calls made from Win32, Win16, and DOS NI-488.2 applications. It is a useful tool for troubleshooting errors in your application and for verifying that the communication with your GPIB instrument is correct. Starting NI Spy To start NI Spy, complete the following steps: 1.
Chapter 5 NI Spy Utility NI Spy records and displays all NI-488.2 calls, as shown in Figure 5-1. Figure 5-1. NI-488.2 Calls Recorded by NI Spy Using the NI Spy Online Help To view the built-in, context-sensitive online help for the NI Spy utility, select Help»Help Topics in NI Spy. You can also view the online help by clicking on the question mark button on the NI Spy toolbar, and then clicking on the area of the screen about which you have a question. Locating Errors with NI Spy All NI-488.
Chapter 5 NI Spy Utility Exiting NI Spy When you exit NI Spy, its current configuration is saved and used to configure NI Spy when you start it again. Unless you save the data captured in NI Spy before you exit, that information is lost. To save the captured data, click on the red circled X button on the toolbar and select File»Save As to save the data in a .spy file. After you save your data, select File»Exit to exit the NI Spy utility.
6 Interactive Control Utility This chapter introduces you to the Interactive Control utility, which lets you communicate with GPIB devices interactively. Overview With the Interactive Control utility, you communicate with the GPIB devices through functions you interactively type in at the keyboard. For specific information about communicating with your particular device, refer to the documentation that came with the device.
Chapter 6 Interactive Control Utility 3. Right-click on your GPIB interface and select Interactive Control from the drop-down menu that appears. For help on any Interactive Control command, type help followed by the command. For example, type help ibdev or help set. 4. Open either an interface handle or device handle to use for further NI-488.2 calls. Use ibdev to open a device handle, ibfind to open an interface handle, or the set 488.2 command to switch to a 488.2 prompt.
Chapter 6 5. Interactive Control Utility After you successfully complete ibdev, you have a ud prompt. The new prompt, ud0, represents a device-level handle that you can use for further NI-488.2 calls. To clear the device, use ibclr, as follows: ud0: ibclr [0100] (cmpl) 6. To write data to the device, use ibwrt. Make sure that you refer to the documentation that came with your GPIB instrument for recognized command messages.
Chapter 6 Interactive Control Utility The ibonl command properly closes the device handle and the ud0 prompt is no longer available. 9. To exit Interactive Control, type q. Interactive Control Syntax The following special rules apply to making calls from the Interactive Control utility: • The ud or BoardId parameter is implied by the Interactive Control prompt, therefore it is never included in the call.
Chapter 6 Interactive Control Utility Special symbols—Some instruments require special termination or end-of-string (EOS) characters that indicate to the device that a transmission has ended. The two most common EOS characters are \r and \n. \r represents a carriage return character and \n represents a linefeed character. You can use these special characters to insert the carriage return and linefeed characters into a string, as in "*IDN?\r\n". Address Syntax Some of the NI-488.
Chapter 6 Interactive Control Utility Table 6-1. Syntax for Device-Level Traditional NI-488.
Chapter 6 Interactive Control Utility Table 6-2. Syntax for Board-Level Traditional NI-488.
Chapter 6 Interactive Control Utility Table 6-2. Syntax for Board-Level Traditional NI-488.
Chapter 6 Interactive Control Utility Table 6-3. Syntax for Multi-Device NI-488.
Chapter 6 Interactive Control Utility Table 6-4. Auxiliary Functions in Interactive Control (Continued) Function Description + Turn ON display. n * function Execute function n times where function represents the correct Interactive Control function syntax. n * ! Execute previous function n times. $ filename Execute indirect file where filename is the pathname of a file that contains Interactive Control functions to be executed. buffer option Set type of display used for buffers.
Chapter 6 Interactive Control Utility In this example, the addressing command bytes could not be transmitted to the device. This indicates that either the GPIB device is powered off or the GPIB cable is disconnected. For a detailed list of the error codes and their meanings, refer to Chapter 4, Debugging Your Application.
NI-488.2 Programming Techniques 7 This chapter describes techniques for using some NI-488.2 calls in your application. For more information about each function, refer to the NI-488.2 online help. For instructions on accessing the online help, refer to the Using the NI-488.2 Documentation section in About This Manual.
Chapter 7 NI-488.2 Programming Techniques • EOS read method—If this is enabled, ibrd, ibrda, and ibrdf calls are terminated when the EOS byte is detected on the GPIB, when the GPIB EOI line is asserted, or when the specified count is reached. If the EOS read method is disabled, ibrd, ibrda, and ibrdf calls terminate only when the GPIB EOI line is asserted or the specified count has been read.
Chapter 7 NI-488.2 Programming Techniques If you are using device-level calls, the NI-488.2 software automatically sends the HS488 configuration message to devices. If you enabled the HS488 protocol in the NI-488.2 Configuration utility, the NI-488.2 software sends out the HS488 configuration message when you use ibdev to bring a device online. If you call ibconfig to change the GPIB cable length, the NI-488.2 software sends out the HS488 message again, the next time you call a device-level function.
Chapter 7 NI-488.2 Programming Techniques Waiting for GPIB Conditions You can use the ibwait function to obtain the current ibsta value or to suspend your application until a specified condition occurs on the GPIB. If you use ibwait with a parameter of zero, it immediately updates ibsta and returns. If you want to use ibwait to wait for one or more events to occur, pass a wait mask to the function.
Chapter 7 NI-488.2 Programming Techniques GPIB device to request service, you might choose to pass ibnotify a mask with RQS (for device-level) or SRQI (for board-level). The callback function that you register with the ibnotify call is invoked by the NI-488.2 driver when one or more of the mask bits passed to ibnotify is TRUE.
Chapter 7 NI-488.2 Programming Techniques because of the way they are used in the application: only a single thread is writing the global values and that thread only adds information (increases the count or adds another reading to the array of floats).
Chapter 7 NI-488.2 Programming Techniques if (ibsta & ERR) { printf ("ibnotify call failed.\n"); return 0; } while ((ReadingsTaken < 1000) && !(DeviceError)) { // Your application does useful work here. For example, it // might process the device readings or do any other useful work. } // disable notification ibnotify (ud, 0, NULL, NULL); // Call the ibonl function to disable the hardware and software.
Chapter 7 NI-488.2 Programming Techniques // condition to report. if (SpollByte != expectedResponse) { printf("Device returned invalid response. Status byte = 0x%x\n", SpollByte); DeviceError = TRUE; return 0; } // Read the data from the device. If the ERR bit is set in ibsta, // then print an error message and return. LocalIbsta = ibrd (LocalUd, ReadBuffer, 40L); if (LocalIbsta & ERR) { printf ("ibrd failed. No more callbacks.
Chapter 7 NI-488.2 Programming Techniques return 0; } else { return RQS; } } } Writing Multithreaded Win32 NI-488.2 Applications If you are writing a multithreaded NI-488.2 application and you plan to make all of your NI-488.2 calls from a single thread, you can safely continue to use the traditional NI-488.2 global variables (ibsta, iberr, ibcnt, ibcntl). The NI-488.2 global variables are defined on a per-process basis, so each process accesses its own copy of the NI-488.2 globals.
Chapter 7 NI-488.2 Programming Techniques modified by the call. For more information about the use of synchronization primitives, refer to the documentation about using Win32 synchronization objects that came with your development tools. If you choose not to use process-global variables, you can access per-thread copies of the NI-488.2 global variables using a special set of NI-488.2 calls. Whenever a thread makes a NI-488.2 call, the driver keeps a private copy of the NI-488.2 globals for that thread.
Chapter 7 NI-488.2 Programming Techniques Device-Level Calls and Bus Management The device-level traditional NI-488.2 calls are designed to perform all of the GPIB management for your application. However, the NI-488.2 driver can handle bus management only when the GPIB interface is CIC (Controller-In-Charge). Only the CIC is able to send command bytes to the devices on the bus to perform device addressing or other bus management activities.
Chapter 7 NI-488.2 Programming Techniques the application could monitor the status bits TACS (Talker Active State) and LACS (Listener Active State) to determine when to send data to or receive data from the Controller. The application could also monitor the DCAS (Device Clear Active State) and DTAS (Device Trigger Active State) bits to determine if the Controller has sent the device clear (DCL or SDC) or trigger (GET) messages to the interface.
Chapter 7 NI-488.2 Programming Techniques Automatic Serial Polling You can enable automatic serial polling if you want your application to conduct a serial poll automatically when the SRQ line is asserted. The autopolling procedure occurs as follows: 1. To enable autopolling, use the configuration function, ibconfig, with option IbcAUTOPOLL, or the NI-488.2 Configuration utility. (Autopolling is enabled by default.) 2.
Chapter 7 NI-488.2 Programming Techniques Autopolling and Interrupts If autopolling and interrupts are both enabled, the NI-488.2 software can perform autopolling after any device-level NI-488.2 call provided that no GPIB I/O is currently in progress. In this case, an automatic serial poll can occur even when your application is not making any calls to the NI-488.2 software. Autopolling can also occur when a device-level ibwait for RQS is in progress.
Chapter 7 NI-488.2 Programming Techniques char SerialPollResponse = 0; ibwait ( DeviceHandle, TIMO | RQS ); if ( ibsta & RQS ) { printf ( "Device asserted SRQ.\n" ); /* Use ibrsp to retrieve the serial poll response. */ ibrsp ( DeviceHandle, &SerialPollResponse ); } return SerialPollResponse; } SRQ and Serial Polling with Multi-Device NI-488.2 Calls The NI-488.2 software includes a set of multi-device NI-488.2 calls that you can use to conduct SRQ servicing and serial polling.
Chapter 7 NI-488.2 Programming Techniques Example 1: Using FindRQS This example shows you how to use FindRQS to find the first device that is requesting service: void GetASerialPollResponse ( char *DevicePad, char *DeviceResponse ) { char SerialPollResponse = 0; int WaitResult; Addr4882_t Addrlist[4] = {3,4,5,NOADDR}; WaitSRQ (0, &WaitResult); if (WaitResult) { printf ("SRQ is asserted.\n"); FindRQS ( 0, AddrList, &SerialPollResponse ); if (!(ibsta & ERR)) { printf ("Device at pad %x returned byte %x.
Chapter 7 NI-488.2 Programming Techniques return; } Parallel Polling Although parallel polling is not widely used, it is a useful method for obtaining the status of more than one device at the same time. The advantage of parallel polling is that a single parallel poll can easily check up to eight individual devices at once. In comparison, eight separate serial polls would be required to check eight devices for their serial poll response bytes.
Chapter 7 NI-488.2 Programming Techniques The following example code configures a device for parallel polling using traditional NI-488.2 calls. The device asserts DIO7 if its ist is 0. In this example, the ibdev command opens a device that has a primary address of 3, has no secondary address, has a timeout of 3 s, asserts EOI with the last byte of a write operation, and has EOS characters disabled.
Chapter 7 NI-488.2 Programming Techniques Parallel Polling with Multi-Device NI-488.2 Calls Complete the following steps to implement parallel polling the using multi-device NI-488.2 calls. Each step contains example code. 1. Configure the device for parallel polling using the PPollConfig call, unless the device can configure itself for parallel polling. The following example configures a device at address 3 to assert data line 5 (DIO5) when its ist value is 1. #include "decl-32.
A GPIB Basics The ANSI/IEEE Standard 488.1-1987, also known as General Purpose Interface Bus (GPIB), describes a standard interface for communication between instruments and controllers from various vendors. It contains information about electrical, mechanical, and functional specifications. GPIB is a digital, 8-bit parallel communications interface with data transfer rates of 1 Mbyte/s and higher, using a three-wire handshake.
Appendix A GPIB Basics GPIB Addressing All GPIB devices and interfaces must be assigned a unique GPIB address. A GPIB address is made up of two parts: a primary address and an optional secondary address. The primary address is a number in the range 0 to 30. The Controller uses this address to form a talk or listen address that is sent over the GPIB when communicating with a device. A talk address is formed by setting bit 6, the TA (Talk Active) bit of the GPIB address.
Appendix A GPIB Basics Handshake Lines Three hardware handshake lines asynchronously control the transfer of message bytes between devices. This process is a three-wire interlocked handshake, and it guarantees that devices send and receive message bytes on the data lines without transmission error. Table A-1 summarizes the GPIB handshake lines. Table A-1. GPIB Handshake Lines Line Description NRFD (not ready for data) Listening device is ready/not ready to receive a message byte.
B Status Word Conditions This appendix gives a detailed description of the conditions reported in the status word, ibsta. For information about how to use ibsta in your application program, refer to the NI-488.2 online help. For instructions on accessing the online help, refer to the Using the NI-488.2 Documentation section in About This Manual. Each bit in ibsta can be set for device calls (dev), board calls (brd), or both (dev, brd). Table B-1 shows the status word layout. Table B-1.
Appendix B Status Word Conditions ERR (dev, brd) ERR is set in the status word following any call that results in an error. You can determine the particular error by examining the error variable iberr. Appendix C, Error Codes and Solutions, describes error codes that are recorded in iberr along with possible solutions. ERR is cleared following any call that does not result in an error. TIMO (dev, brd) TIMO indicates that the timeout period has expired.
Appendix B Status Word Conditions SRQI (brd) SRQI indicates that a GPIB device is requesting service. SRQI is set whenever the GPIB interface is CIC, the GPIB SRQ line is asserted, and the automatic serial poll capability is disabled. SRQI is cleared either when the GPIB interface ceases to be the CIC or when the GPIB SRQ line is unasserted. RQS (dev) RQS appears in the status word only after a device-level call and indicates that the device is requesting service.
Appendix B Status Word Conditions REM (brd) REM indicates whether the interface is in the remote state. REM is set whenever the Remote Enable (REN) GPIB line is asserted and the GPIB interface detects that its listen address has been sent either by the GPIB interface or by another Controller. REM is cleared in the following situations: • When REN becomes unasserted.
Appendix B Status Word Conditions LACS (brd) LACS indicates whether the GPIB interface is addressed as a Listener. LACS is set whenever the GPIB interface detects that its listen address (and secondary address, if enabled) has been sent either by the GPIB interface itself or by another Controller. LACS is also set whenever the GPIB interface shadow handshakes as a result of the ibgts function.
C Error Codes and Solutions This appendix lists a description of each error, some conditions under which it might occur, and possible solutions. Table C-1 lists the GPIB error codes. Table C-1.
Appendix C Error Codes and Solutions EDVR (0) EDVR is returned when the interface or device name passed to ibfind, or the interface index passed to ibdev, cannot be accessed. The global variable ibcntl contains an error code. This error occurs when you try to access an interface or device that is not installed or configured properly. EDVR is also returned if an invalid unit descriptor is passed to any traditional NI-488.2 call.
Appendix C Error Codes and Solutions • ibcac and ibgts. • Any NI-488.2 multi-device calls that issue GPIB command bytes: SendCmds, PPoll, Send, and Receive. Solutions Possible solutions for this error are as follows: • Use ibsic or SendIFC to make the GPIB interface become CIC on the GPIB. • Use ibrsc 1 to make sure your GPIB interface is configured as System Controller.
Appendix C Error Codes and Solutions EADR (3) EADR occurs when the GPIB interface is CIC and is not properly addressing itself before read and write functions. This error is usually associated with board-level functions. EADR is also returned by the function ibgts when the shadow-handshake feature is requested and the GPIB ATN line is already unasserted. In this case, the shadow handshake is not possible and the error is returned to notify you of that fact.
Appendix C Error Codes and Solutions ESAC (5) ESAC results when ibsic, ibsre, SendIFC, or EnableRemote is called when the GPIB interface does not have System Controller capability. Solutions Give the GPIB interface System Controller capability by calling ibrsc 1 or by using the NI-488.2 Configuration utility to configure that capability into the software. EABO (6) EABO indicates that an I/O operation has been canceled, usually due to a timeout condition.
Appendix C Error Codes and Solutions Solutions Make sure there is a GPIB interface in your computer that is properly configured both in hardware and software using a valid base I/O address by running the NI-488.2 Troubleshooting Wizard, as follows: 1. Select Start»Programs»National Instruments NI-488.2»Explore GPIB. 2. Select Help»Troubleshooting»NI-488.2 Troubleshooting Wizard. The Troubleshooting Wizard tests your GPIB interface and displays the results.
Appendix C Error Codes and Solutions ibwait If the returned ibsta contains CMPL, the driver and application are resynchronized. ibstop The I/O is canceled; the driver and application are resynchronized. ibonl The I/O is canceled and the interface is reset; the driver and application are resynchronized.
Appendix C Error Codes and Solutions EBUS (14) EBUS results when certain GPIB bus errors occur during device functions. All device functions send command bytes to perform addressing and other bus management. Devices are expected to accept these command bytes within the time limit specified by the default configuration or the ibtmo function. EBUS results if a timeout occurred while sending these command bytes.
Appendix C Error Codes and Solutions ESRQ (16) ESRQ can only be returned by a device-level ibwait call with RQS set in the mask. ESRQ indicates that a wait for RQS is not possible because the GPIB SRQ line is stuck on. This situation can be caused by the following events: • Usually, a device unknown to the software is asserting SRQ. Because the software does not know of this device, it can never serial poll the device and unassert SRQ.
Windows 98/95: Troubleshooting and Common Questions D This appendix describes how to troubleshoot problems and answers some common questions about the NI-488.2 software for Windows 98/95. Troubleshooting EDVR Error Conditions In some cases, NI-488.2 calls may return with the ERR bit set in ibsta and the value EDVR in iberr. The value stored in ibcntl is useful in troubleshooting the error condition.
Appendix D Windows 98/95: Troubleshooting and Common Questions EDVR Error Condition with ibcntl Set to 0xE0140035 (–535560139) If a call is made with a device name that is not listed in the logical device templates that are part of the NI-488.2 Configuration utility, an EDVR error condition occurs with ibcntl set to 0xE0140035.
Appendix D Windows 98/95: Troubleshooting and Common Questions Troubleshooting Device Manager Problems If you are having trouble with your GPIB interface, use the Windows Device Manager to troubleshoot your problems. To do so, complete the following steps: 1. Select Start»Settings»Control Panel. 2. Double-click on the System icon. 3. Select the Device Manager tab and click on the View devices by type button. 4.
Appendix D Windows 98/95: Troubleshooting and Common Questions Enabling Interrupts In Windows 98/95, you can use your GPIB interface without interrupts, but the NI-488.2 software performance is significantly slower without interrupts. For example, transfer sizes between 1 and 10 bytes transfer at a rate of only 2% of the transfer rate with enabled interrupts.
Appendix D 7. Windows 98/95: Troubleshooting and Common Questions Click on the OK button to save your changes. On the Device Manager tab, the disabled device has a red X overlaid on it. The red X indicates that the device is disabled. Step 2. Remove Your GPIB Interface from the Device Manager To remove your GPIB interface from the Device Manager, complete the following steps: 1. On the Device Manager tab, double-click on the National Instruments GPIB Interfaces item.
Appendix D Windows 98/95: Troubleshooting and Common Questions How can I determine which version of the NI-488.2 software I have installed? To view the NI-488.2 software version, complete the following steps: 1. Select Start»Programs»National Instruments NI-488.2»Explore GPIB to start Measurement & Automation Explorer. 2. Select Help»About Measurement & Automation Explorer. The Value column in the About Measurement & Automation Explorer dialog box displays the version number of the NI-488.2 software.
Appendix D Windows 98/95: Troubleshooting and Common Questions Are interrupts and DMA required for the NI-488.2 software? Neither interrupts nor DMA are required. However, if you are using a GPIB interface with Analyzer capability (PCMCIA-GPIB+ or AT-GPIB/TNT+), at least one interrupt level is required for the GPIB Analyzer driver. In Windows 98/95, you can use your GPIB interface without interrupts, but the NI-488.2 software performance is significantly slower without interrupts.
Appendix D Windows 98/95: Troubleshooting and Common Questions How can I start communicating with my GPIB instrument? For simple instrument communication, use the NI-488.2 Communicator. For instructions on how to use the NI-488.2 Communicator, refer to the Basic Communication (Query/Write/Read) section in Chapter 2, Measurement & Automation Explorer. How do I check for errors in my NI-488.2 application? Examine the value of ibsta after each NI-488.2 call.
E Windows 2000/NT: Common Questions This appendix answers some common questions about the NI-488.2 software for Windows 2000/NT. Common Questions How do I get started? To get started with your GPIB hardware and the NI-488.2 software, use the NI-488.2 Getting Started Wizard. To do so, select Start»Programs» National Instruments NI-488.2»Getting Started Wizard. How do I troubleshoot problems? Run the NI-488.2 Troubleshooting Wizard. To do so, select Start»Programs»National Instruments NI-488.
Appendix E Windows 2000/NT: Common Questions How can I determine which type of GPIB hardware I have installed? Select Start»Programs»National Instruments NI-488.2»Explore GPIB and expand the Devices and Interfaces directory by clicking on the + next to the folder. Measurement & Automation Explorer lists your installed GPIB hardware under Devices and Interfaces. How many GPIB interfaces can I configure for use with the NI-488.2 software? You can configure the NI-488.
Appendix E Windows 2000/NT: Common Questions How do I use an NI-488.2 language interface? For information about using NI-488.2 language interfaces, refer to Chapter 3, Developing Your NI-488.2 Application. What do I need to know to communicate properly with my GPIB instrument? Refer to the documentation that came with your instrument. The command sequences that you use depend on the specific instrument.
Technical Support Resources F This appendix describes the comprehensive resources available to you in the Technical Support section of the National Instruments Web site and provides technical support telephone numbers for you to use if you have trouble connecting to our Web site or if you do not have internet access. NI Web Support To provide you with immediate answers and solutions 24 hours a day, 365 days a year, National Instruments maintains extensive online technical support resources.
Appendix F Technical Support Resources Software-Related Resources • Instrument Driver Network—A library with hundreds of instrument drivers for control of standalone instruments via GPIB, VXI, or serial interfaces. You also can submit a request for a particular instrument driver if it does not already appear in the library. • Example Programs Database—A database with numerous, non-shipping example programs for National Instruments programming environments.
Glossary Prefix Meaning Value n- nano- 10 –9 m- milli- 10 –3 M- mega- 10 6 A acceptor handshake Listeners use this GPIB interface function to receive data, and all devices use it to receive commands. See source handshake and handshake. access board The GPIB board that controls and communicates with the devices on the bus that are attached to it. ANSI American National Standards Institute. API Application Programming Interface ASCII American Standard Code for Information Interchange.
Glossary C CFE Configuration Enable. The GPIB command which precedes CFGn and is used to place devices into their configuration mode. CFGn These GPIB commands (CFG1 through CFG15) follow CFE and are used to configure all devices for the number of meters of cable in the system so HS488 transfers occur without errors. CIC Controller-In-Charge. The device that manages the GPIB by sending interface messages to other devices. CPU Central processing unit. D DAV Data Valid.
Glossary EOS or EOS Byte A 7- or 8-bit end-of-string character that is sent as the last byte of a data message. EOT End of transmission. ESB The Event Status bit. Part of the IEEE 488.2-defined status byte which is received from a device responding to a serial poll. F FIFO First-in-first-out. G GET Group Execute Trigger. The GPIB command used to trigger a device or internal function of an addressed Listener.
Glossary hex Hexadecimal; a number represented in base 16. For example, decimal 16 is hex 10. high-level function See device-level function. HS488 A high-speed data transfer protocol for IEEE 488. This protocol increases performance for GPIB reads and writes up to 8 Mbytes/s, depending on your system. Hz Hertz. I ibcnt After each NI-488.2 I/O call, this global variable contains the actual number of bytes transmitted.
Glossary ISA Industry Standard Architecture. ist An Individual Status bit of the status byte used in the Parallel Poll Configure function. L LAD Listen Address. See MLA. language interface Code that enables an application program that uses NI-488.2 calls to access the driver. Listener A GPIB device that receives data messages from a Talker. LLO Local Lockout.
Glossary N NDAC Not Data Accepted. One of the three GPIB handshake lines. See handshake. NRFD Not Ready For Data. One of the three GPIB handshake lines. See handshake. P parallel poll The process of polling all configured devices at once and reading a composite poll response. See serial poll. PC Personal computer. PCI Peripheral Component Interconnect. PIO See programmed I/O. PPC Parallel Poll Configure. The GPIB command used to configure an addressed Listener to participate in polls.
Glossary S s Seconds. SDC Selected Device Clear. The GPIB command used to reset internal or device functions of an addressed Listener. See DCL. semaphore An object that maintains a count between zero and some maximum value, limiting the number of threads that are simultaneously accessing a shared resource. serial poll The process of polling and reading the status byte of one device at a time. See parallel poll. service request See SRQ.
Glossary T TAD Talk Address. See MTA. Talker A GPIB device that sends data messages to Listeners. TCT Take Control. The GPIB command used to pass control of the bus from the current Controller to an addressed Talker. timeout A feature of the GPIB driver that prevents I/O functions from hanging indefinitely when there is a problem on the GPIB. TLC An integrated circuit that implements most of the GPIB Talker, Listener, and Controller functions in hardware. U ud Unit descriptor.
Index Numbers/Symbols using Interactive Control utility, 3-7 using NI-488.2 Communicator, 3-1 to 3-2 interactive instrument control, 3-2 to 3-3 language-specific instructions, 3-12 to 3-16 Borland C/C++, 3-12 direct entry with C, 3-13 to 3-16 directly accessing gpib-32.dll exports, 3-14 to 3-16 gpib-32.
Index CIC. See Controller-in-Charge (CIC). CIC Protocol, 7-11 CIC status word condition bit position, hex value, and type (table), 3-6 description, B-4 CMPL status word condition bit position, hex value, and type (table), 3-6 description, B-3 common questions. See troubleshooting and common questions.
Index documentation accessing NI-488.2 Online Help, xi conventions used in manual, xii related documentation, xii using NI-488.2 documentation, xi DOS NI-488.2 applications enabling/disabling support Windows 98/95, 2-13 to 2-14 Windows 2000/NT, 2-14 running under Windows 98/95, 3-17 under Windows 2000/NT, 3-18 DTAS status word condition bit position, hex value, and type (table), 3-6 description, B-5 Talker/Listener applications, 7-12 dynamic link library, GPIB. See NI-488.2 DLL.
Index ESRQ error code, C-8 to C-9 ESTB error code, C-8 ETAB error code, C-9 event notification. See asynchronous event notification in Win32 applications. Event Status bit (ESB), 7-12 to 7-13 execute function n times (n *) function, Interactive Control utility, 6-10 execute indirect file ($) function, Interactive Control utility, 6-10 execute previous function n times (n * !) function, Interactive Control utility, 6-10 existing applications, running DOS NI-488.
Index H definition, A-1 overview, A-1 sending messages across, A-2 to A-3 data lines, A-2 handshake lines, A-3 interface management lines, A-3 Talkers, Listeners, and Controllers, A-1 gpib-32.
Index device-level traditional NI-488.2 calls (table), 6-5 to 6-6 multi-device NI-488.
Index Microsoft Windows. See Windows 98/95; Windows 2000/NT. multi-device NI-488.2 calls. See NI-488.2 calls. multiple interfaces or multiple devices, 3-5 multithreaded Win32 GPIB applications, writing, 7-9 to 7-10 changing GPIB device templates, 2-12 to 2-13 Windows 98/95, 2-12 Windows 2000/NT, 2-13 communicating with instrument, 2-6 to 2-8 deleting GPIB interface, 2-5 enabling/disabling NI-488.
Index NI-488.2 software language interfaces, 3-3 viewing version, 2-8 NI Spy utility debugging applications, 4-1 exiting, 5-3 locating errors, 5-2 online help, 5-2 overview, 5-1 performance considerations, 5-3 starting, 5-1 to 5-2 viewing properties for recorded calls, 5-2 NRFD (not ready for data) line (table), A-3 number syntax, in Interactive Control utility, 6-4 NI-488.2 DLL choosing access method, 3-3 direct entry access, 3-3 NI-488.2 language interfaces, 3-3 NI-488.2 DOS support. See DOS NI-488.
Index Q service requests from IEEE 488 devices, 7-12 from IEEE 488.2 devices, 7-12 SRQ and serial polling device-level traditional NI-488.2 calls, 7-14 to 7-15 multi-device NI-488.2 calls, 7-15 to 7-17 service requests serial polling IEEE 488 devices, 7-12 IEEE 488.2 devices, 7-12 stuck SRQ state, 7-13 set 488.2 v function, Interactive Control utility, 6-9 set udname function, Interactive Control utility, 6-9 setting up your system. See configuration.
Index Device Manager device status code, D-3 EDVR error conditions, D-1 to D-2 enabling interrupts, D-4 to D-5 Windows 2000/NT, E-1 to E-3 turn OFF display (-) function, Interactive Control utility, 6-9 turn ON display (+) function, Interactive Control utility, 6-10 LACS, 7-12, B-5 LOK, B-3 programming considerations, 3-5 to 3-7 REM, B-4 RQS, B-3 SRQI, B-3 status word layout (table), 3-6, B-1 TACS, 7-12, B-4 TIMO, B-2 string syntax, in Interactive Control utility, 6-4 to 6-5 stuck SRQ state, 7-13 System C
Index troubleshooting and common questions, D-1 to D-8 common questions, D-5 to D-8 Device Manager device status code, D-3 EDVR error conditions, D-1 to D-2 enabling interrupts, D-4 to D-5 viewing or changing settings GPIB-ENET network, 2-15 to 2-16 GPIB interface, 2-9 to 2-10 Windows 2000/NT autopolling and interrupts, 7-14 changing GPIB device templates, 2-13 enabling/disabling NI-488.2 DOS support, 2-13 to 2-14 running existing DOS NI-488.
