ESP-488 Software Reference Manual for the GPIB-ENET

Transcription

1 ESP-488 Software Reference Manual for the GPIB-ENET February 1995 Edition Part Number A-01 Copyright 1995 National Instruments Corporation. All Rights Reserved.

2 National Instruments Corporate Headquarters 6504 Bridge Point Parkway Austin, TX (512) Technical support fax: (800) (512) Branch Offices: Australia (03) , Austria (0662) , Belgium 02/ , Canada (Ontario) (519) , Canada (Québec) (514) , Denmark , Finland (90) , France (1) , Germany 089/ , Italy 02/ , Japan (03) , Mexico , Netherlands , Norway , Singapore , Spain (91) , Sweden , Switzerland 056/ , Taiwan , U.K

3 Limited Warranty The GPIB-ENET is warranted against defects in materials and workmanship for a period of two years from the date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace equipment that proves to be defective during the warranty period. This warranty includes parts and labor. 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. National Instruments does not warrant that the operation of the software shall be uninterrupted or error free. A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before any equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are covered by warranty. National Instruments believes that the information in this manual is accurate. The document has been carefully reviewed for technical accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected. In no event shall National Instruments be liable for any damages arising out of or related to this document or the information contained in it. EXCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. CUSTOMER'S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE CUSTOMER. N ATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR DAMAGES RESULTING FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of the liability of National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against National Instruments must be brought within one year after the cause of action accrues. National Instruments shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein does not cover damages, defects, malfunctions, or service failures caused by owner's failure to follow the National Instruments installation, operation, or maintenance instructions; owner's modification of the product; owner's abuse, misuse, or negligent acts; and power

4 failure or surges, fire, flood, accident, actions of third parties, or other events outside reasonable control. Copyright Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National Instruments Corporation. Trademarks NI is a trademark of National Instruments Corporation. Product and company names listed are trademarks or trade names of their respective companies. WARNING REGARDING MEDICAL AND CLINICAL USE OF NATIONAL INSTRUMENTS PRODUCTS National Instruments products are not designed with components and testing intended to ensure a level of reliability suitable for use in treatment and diagnosis of humans. Applications of National Instruments products involving medical or clinical treatment can create a potential for accidental injury caused by product failure, or by errors on the part of the user or application designer. Any use or application of National Instruments products for or involving medical or clinical treatment must be performed by properly trained and qualified medical personnel, and all traditional medical safeguards, equipment, and procedures that are appropriate in the particular situation to prevent serious injury or death should always continue to be used when National Instruments products are being used. National Instruments products are NOT intended to be a substitute for any form of established process, procedure, or equipment used to monitor or safeguard human health and safety in medical or clinical treatment.

5 Contents About This Manual... ix Organization of This Manual... ix Conventions Used in This Manual... x Related Documentation... xi Customer Communication... xi Chapter 1 Introduction What Your Kit Should Contain Optional Equipment GPIB-ENET Hardware Kits Ethernet Cables Shielded GPIB Cables Hardware Description Software Description File Description Chapter 2 Configuring the Hardware Step 1. Determine IP and Ethernet Addresses Step 2. Configure the GPIB-ENET Operating Characteristics Configure the Slide Switch Configure the 8-Bit DIP Switch Step 3. Connect the Cables Step 4. Switch on Your GPIB-ENET Step 5. Configure Subnet Information Chapter 3 The ESP-488 C Language Library Global Variables Status Variable: ibsta Error Variable: iberr Count Variable: ibcntl ESP-488 Function Descriptions Chapter 4 ESP-488 Functions Function Names Purpose Input and Output Description Possible Errors Examples National Instruments Corp. v ESP-488 SRM for the GPIB-ENET

6 Contents ibcmd ibconfig ibfind ibonl ibrd ibrpp ibrsp ibsic ibwait ibwrt Chapter 5 Using Your ESP-488 Software Helpful Source Code Rules Programming Considerations Compiling a C Program with the ESP-488 Package ESP-488 Example Chapter 6 Verification and Troubleshooting Verify the Hardware Installation Troubleshooting Hardware Problems Common Questions Appendix A Multiline Interface Messages... A-1 Appendix B Hardware Specifications... B-1 Appendix C GPIB-ENET 8-Bit DIP Switch... C-1 8-Bit DIP Switch Descriptions... C-1 Appendix D GPIB-ENET Configuration Utilities... D-1 IPassign Utility... D-1 Update Utility... D-2 IPsetup Utility... D-3 Appendix E READY LED Signaling... E-1 READY LED Overview... E-1 Step 1. Count the Long Flashes... E-1 Step 2. Count the Short Flashes... E-2 Step 3. Record Your Status Code Number... E-2 ESP-488 SRM for the GPIB-ENET vi National Instruments Corp.

7 Contents Appendix F Customer Communication... F-1 Glossary... G-1 Index... I-1 Figures Figure 1-1. GPIB-ENET Top Panel and LEDs Figure 2-1. GPIB-ENET Bottom Panel Identification Label Figure 2-2. GPIB-ENET Back Panel Switches Figure 2-3. Default Switch Setting for Ethernet Port Configuration Figure 2-4. Switch Setting for AUI Ethernet Port Configuration Figure C-1. GPIB-ENET Back Panel Switches... C-1 Tables Table 1-1. LED Descriptions Table 3-1. Interface Status Word Bits Table 3-2. iberr Descriptions Table 3-3. List of Device-Level Functions Table 3-4. List of Board-Level Functions Table 4-1. ibconfig Board Configuration Parameter Options Table 4-2. ibconfig Device Configuration Parameter Options Table 4-3. Wait Mask Layout Table 5-1. ibic Commands Table B-1. Electrical Characteristics... B-1 Table B-2. Environmental Characteristics... B-1 Table B-3. Physical Characteristics... B-1 Table C-1. DIP Switch Settings for Modes of Operation... C-2 Table E-1. Sample READY LED Signals and the Corresponding Status Code Numbers... E-2 National Instruments Corp. vii ESP-488 SRM for the GPIB-ENET

8 About This Manual This manual describes the ESP-488 software in C for the GPIB-ENET and advanced GPIB-ENET programming information. This manual assumes that you are familiar with the IEEE 488 (GPIB) standard and the IEEE messaging protocols. You should use the IEEE 488 (GPIB) standard and the IEEE messaging protocols when you develop your software. Organization of This Manual This manual is organized as follows: Chapter 1, Introduction, lists your kit contents and optional equipment, and briefly describes the GPIB-ENET hardware and ESP-488 software. Chapter 2, Configuring the Hardware, explains how to configure your GPIB-ENET hardware. Chapter 3, The ESP-488 C Language Library, contains a general description of the C language programming interface used in the ESP-488 software. Chapter 4, ESP-488 Functions, describes the purpose, format, input and output parameters, and possible errors for each function available with the ESP-488 software. Chapter 5, Using Your ESP-488 Software, describes ESP-488 coding conventions, explains other programming considerations, and discusses the sample code included on your ESP-488 distribution diskette. Chapter 6, Verification and Troubleshooting, describes how to verify the hardware and installation and troubleshoot problems. Appendix A, Multiline Interface Messages, contains a multiline interface message reference list, which describes the mnemonics and messages that correspond to the interface functions. Appendix B, Hardware Specifications, lists the electrical, environmental, and physical characteristics of the GPIB-ENET and the recommended operating conditions. Appendix C, GPIB-ENET 8-Bit DIP Switch, describes how the DIP switch on the back panel affects the operation of the GPIB-ENET. National Instruments Corp. ix ESP-488 SRM for the GPIB-ENET

9 About This Manual Appendix D, GPIB-ENET Configuration Utilities, contains information on the GPIB-ENET IPassign, Update, and IPsetuputilities. Appendix E, READY LED Signaling, describes how to interpret the READY LED error codes. Appendix F, Customer Communication, contains forms you can use to request help from National Instruments or to comment on our products and manuals. The Glossary contains an alphabetical list and a description of the terms, such as abbreviations, acronyms, metric prefixes, mnemonics, and symbols, that this manual uses. The Index contains an alphabetical list of the key terms and topics that this manual uses, and it includes the page number where you can locate each term and topic. Conventions Used in This Manual This manual uses the following conventions. italic bold italic monospace bold monospace italic monospace Italic text denotes emphasis, a cross reference, or an introduction to a key concept. Bold italic text denotes a note, caution, or warning. Lowercase text in this font denotes text or characters that you literally input from the keyboard. It also denotes sections of code, programming examples, syntax examples, the proper names of disk drives, paths, directories, programs, subprograms, subroutines, device names, functions, variables, filenames, extensions, parameters, and statements and comments taken from program code. Bold lowercase text in this font denotes the messages and responses that the computer automatically prints to the screen. Italic lowercase text in this font denotes that you must supply the appropriate words or values in the place of these items. IEEE 488 and IEEE 488 and IEEE refer to the ANSI/IEEE Standard IEEE and the ANSI/IEEE Standard , respectively, which define the GPIB. The Glossary lists abbreviations, acronyms, metric prefixes, mnemonics, symbols, and terms. ESP-488 SRM for the GPIB-ENET x National Instruments Corp.

10 About This Manual Related Documentation The following documents contain information that you may find helpful as you read this manual. ANSI/IEEE Standard , IEEE Standard Digital Interface for Programmable Instrumentation ANSI/IEEE Standard , IEEE Standard Codes, Formats, Protocols, and Common Commands ANSI/IEEE Standard , Information Processing Systems, Local Area Networks, Part 3 In addition, you might need to refer to the documentation that came with your system for network programming information. Customer Communication National Instruments wants to receive your comments on our products and manuals. We are interested in the applications you develop with our products, and we want to help if you have problems with them. To make it easy for you to contact us, this manual contains comment and configuration forms for you to complete. These forms are in Appendix F, Customer Communication, at the end of this manual. National Instruments Corp. xi ESP-488 SRM for the GPIB-ENET

11 Chapter 1 Introduction This chapter lists your kit contents and optional equipment, and briefly describes the GPIB-ENET hardware and ESP-488 (Engineering Software Package) software. What Your Kit Should Contain Your kit should contain the following components: DOS-formatted, high-density diskette containing ESP-488 in C for the GPIB-ENET ESP-488 Software Reference Manual for the GPIB-ENET Optional Equipment You can call National Instruments to order the following optional equipment to use with your ESP-488 in C for the GPIB-ENET kit. GPIB-ENET Hardware Kits The following GPIB-ENET hardware kits include a GPIB-ENET with the specified connectors, voltage requirement, and power cord for use in the stated country. GPIB-ENET Twisted Pair/AUI, United States 120 VAC GPIB-ENET Twisted Pair/AUI, Swiss 220 VAC GPIB-ENET Twisted Pair/AUI, Australian 240 VAC GPIB-ENET Twisted Pair/AUI, Universal European 240 VAC GPIB-ENET Twisted Pair/AUI, North American 240 VAC GPIB-ENET Twisted Pair/AUI, UK 240 VAC GPIB-ENET Coaxial/AUI, United States 120 VAC GPIB-ENET Coaxial/AUI, Swiss 220 VAC GPIB-ENET Coaxial/AUI, Australian 240 VAC GPIB-ENET Coaxial/AUI, Universal European 240 VAC GPIB-ENET Coaxial/AUI, North American 240 VAC GPIB-ENET Coaxial/AUI, UK 240 VAC Ethernet Cables Twisted pair (10Base-T) cables (1 m, 5 m, or 10 m) Coax (10Base-2) cables (1 m, 5 m, or 10 m) AUI (10Base-5) cables (1 m, 5 m, or 10 m) National Instruments Corp. 1-1 ESP-488 SRM for the GPIB-ENET

12 Introduction Chapter 1 Shielded GPIB Cables* Type X2 double-shielded cables (1 m, 2 m, or 4 m) * To meet FCC emission limits for this device, you must use a shielded (Type X2) GPIB cable. Operating this equipment with a non-shielded cable may cause interference to radio and television reception. Hardware Description The GPIB-ENET transparently handles data transfers between an Ethernet-based TCP/IP host and the GPIB. With the GPIB-ENET, multiple computers can share a set of GPIB instruments or a single computer can control several GPIB systems. The GPIB-ENET converts a computer equipped with an Ethernet port into a GPIB Talker/Listener/Controller. It is powered by an internal VAC or VAC supply. The GPIB-ENET has all the firmware and logic required to implement the physical and electrical characteristics of all versions of the ANSI/IEEE 488 standard, including ANSI/IEEE Standard , and ANSI/IEEE Standard The GPIB-ENET interprets and executes commands that you send to it over an Ethernet link and performs all necessary Ethernet-to-GPIB protocol conversions. For detailed hardware specifications, refer to Appendix B, Hardware Specifications. Figure 1-1 shows the seven light-emitting diodes (LEDs) on the GPIB-ENET top panel. The LEDs show the current status of the GPIB-ENET. Table 1-1 describes each LED. Ethernet AUI Connector GPIB-ENET ETHERNET IEEE 488 Controller NATIONAL INSTRUMENTS POWER READY TALK LISTEN TRANSMIT RECEIVE LINK GPIB Connector Location of Coax or 10Base-T Connector (depending on version) Figure 1-1. GPIB-ENET Top Panel and LEDs ESP-488 SRM for the GPIB-ENET 1-2 National Instruments Corp.

13 Chapter 1 Introduction Table 1-1. LED Descriptions LED POWER READY TALK LISTEN TRANSMIT RECEIVE LINK Indication Indicates that power has been supplied to the unit and the ON/OFF switch is in the ON position. Indicates the functional state of the GPIB-ENET. When the GPIB-ENET is powered on, this LED flashes and then becomes steady when the box is ready for operation. Continuous flashing indicates an error has occurred. Indicates that GPIB-ENET is configured as a GPIB Talker. Indicates that GPIB-ENET is configured as a GPIB Listener. Indicates that the GPIB-ENET is transmitting onto the Ethernet network. Indicates that the GPIB-ENET is receiving Ethernet network traffic. Indicates that the GPIB-ENET has detected a twisted pair (10Base-T) link. For GPIB-ENET coax and AUI options, this LED is not used and remains OFF. ESP-488 Software Description The ESP-488 development software includes source code that performs basic IEEE 488 functions. The code contains functions for synchronous communication, device configuration, and status reporting. You can customize the code for your specific applications. Refer to Chapter 5, Using Your ESP-488 Software, for more information about modifying the code. You should use the ESP-488 software in systems that do not have a corresponding NI software package. The NI driver software packages provide complete NI compatibility and development utilities. NI software for the GPIB-ENET is available for the Sun Solaris, HP-UX, OSF/1, Mac OS, and Microsoft Windows platforms. National Instruments Corp. 1-3 ESP-488 SRM for the GPIB-ENET

14 Introduction Chapter 1 File Descriptions Check your ESP-488 distribution diskette for the following files: \esp.c ESP-488 Source Code \esp.h Header File for the ESP-488 Code \espproto.h Prototypes for the ESP-488 Code \gpibcnst.h ESP-488 Constants \ibic.c Sample Application Using the ESP-488 Software \read.me Extra Information Not Found in the Documentation \enet_xx.bin Latest GPIB-ENET Firmware Revision at Release \solaris1\ipassign IPassign Executable for SPARC Platforms using Solaris 1 \solaris1\ipsetup IPsetup Executable for SPARC Platforms using Solaris 1 \solaris1\update Update Executable for SPARC Platforms using Solaris 1 \solaris2\ipassign IPassign Executable for SPARC Platforms using Solaris 2 \solaris2\ipsetup IPsetup Executable for SPARC Platforms using Solaris 2 \solaris2\update Update Executable for SPARC Platforms using Solaris 2 \HP-UX\IPassign IPassign Executable for HP-UX Series 700 Platforms \HP-UX\IPsetup IPsetup Executable for HP-UX Series 700 Platforms \HP-UX\Update Update Executable for HP-UX Series 700 Platforms ESP-488 SRM for the GPIB-ENET 1-4 National Instruments Corp.

15 Chapter 2 Configuring the Hardware This chapter explains how to configure your GPIB-ENET hardware. This chapter contains references to two utilities, IPassign and IPsetup, that are not available in source code. The ESP-488 distribution diskette includes executable versions of these utilities for the Solaris 1 and Solaris 2 SPARC platforms, and the HP-UX Series 700 platforms. Executables for other common platforms, such as Microsoft Windows and Mac OS, are also available from National Instruments. If you cannot use any of the included executables, contact National Instruments for assistance. Step 1. Determine IP and Ethernet Addresses The Internet Protocol (IP) address is the address that TCP/IP-based networks use to route information to the appropriate network and host. When you first install a GPIB-ENET in a network, or if the IP address for the GPIB-ENET changes, the GPIB-ENET IP address must be configured. 1. Note the Ethernet address from the bottom panel label of the GPIB-ENET. The Ethernet address is not the same thing as the IP address. All devices on an Ethernet network are assigned a physical address, the Ethernet address, so that they can communicate with each other. The identification label on the bottom panel of the GPIB-ENET contains various information, including the Ethernet address. See Figure 2-1 for a picture of the GPIB-ENET identification label. Ethernet Address Model: GPIB-ENET NATIONAL INSTRUMENTS P/N 1819XX-XX REV X Serial No. XXXXXX MADE IN U.S.A. Ethernet: 00:80:2F:FF:XX:XX XXXV 50-60HZ XXmA FUSE: XXXmA SLOW 250V AC Input Current Fuse Information Voltage Frequency Figure 2-1. GPIB-ENET Bottom Panel Identification Label National Instruments Corp. 2-1 ESP-488 SRM for the GPIB-ENET

16 Configuring the Hardware Chapter 2 2. Contact your network administrator to use the GPIB-ENET on your network. Your network administrator assigns a unique, valid IP address to your GPIB-ENET. You should also obtain a fully qualified name for the GPIB-ENET. Your network administrator can also tell you whether the GPIB-ENET should have its IP address configured automatically or manually. A Reverse Address Resolution Protocol (RARP) server on the network automatically configures the GPIB-ENET with an IP address when you power on the GPIB-ENET; once your network administrator has configured your network RARP server, you can use automatic configuration. You can configure the IP address manually using the IPassign utility. Once you configure the IP address, it is stored in the GPIB-ENET so that you do not need to reassign it every time you power on the box. 3. Make a note of the IP address and name mapping assigned to the GPIB-ENET hardware. You use the IP address when configuring the hardware and the name mapping when you using the ESP-488 software. Step 2. Configure the GPIB-ENET Operating Characteristics The GPIB-ENET has a two-position slide switch that you use to configure the network interface connector of the box. The GPIB-ENET also has an 8-bit DIP switch used to configure the operating characteristics. The switches are located on the back panel of the GPIB-ENET, as shown in Figure ON 10BASE-T AUI Configure the Slide Switch Figure 2-2. GPIB-ENET Back Panel Switches Your GPIB-ENET has two network interface connectors: a 15-pin AUI connector and either a 10Base-T Ethernet connector or a coax Ethernet connector. Use the slide switch to select which of the two connectors the GPIB-ENET uses. The default switch setting is either 10Base-T or coax. Figure 2-3 depicts the default setting for the different types of GPIB-ENET boxes. ESP-488 SRM for the GPIB-ENET 2-2 National Instruments Corp.

17 Chapter 2 Configuring the Hardware 10BASE-T AUI OR COAX AUI Figure 2-3. Default Switch Setting for Ethernet Port Configuration If you want to use the AUI connector, change the switch setting to match the appropriate setting in Figure BASE-T AUI OR COAX AUI Figure 2-4. Switch Setting for AUI Ethernet Port Configuration Configure the 8-Bit DIP Switch The 8-bit DIP switch selects the operating mode of the GPIB-ENET. The GPIB-ENET is shipped to you with the DIP switches set for normal operation mode. In normal operation mode, all the switches are in the OFF position. Most users use the GPIB-ENET in normal operation mode. Do not change the DIP switch settings unless you run a GPIB-ENET utility that requires you to change them. For information about using the 8-bit DIP switch, refer to Appendix C, GPIB-ENET 8-Bit DIP Switch. Step 3. Connect the Cables If you do not have both a GPIB cable and Ethernet cable, refer to the Optional Equipment section in Chapter 1 for ordering information. 1. Connect one end of the Ethernet cable to the GPIB-ENET and securely fasten it. Connect the other end of the Ethernet cable to your Ethernet network. Be sure to follow all IEEE cabling restrictions. 2. Connect one end of the GPIB cable to the GPIB-ENET and tighten the thumb screws on the connector. Connect the other end of the GPIB cable to your GPIB system. Be sure to follow all IEEE cabling restrictions and use only shielded GPIB cables. 3. Plug the power cord into an AC outlet of the correct voltage. National Instruments Corp. 2-3 ESP-488 SRM for the GPIB-ENET

18 Configuring the Hardware Chapter 2 Step 4. Switch on Your GPIB-ENET Warning: Operating the GPIB-ENET at any voltage other than the one specified could damage the unit. The GPIB-ENET is shipped from the factory with either a VAC or VAC power supply. Before you configure your GPIB-ENET, verify that the voltage rating listed on the bottom of the box matches the voltage that is supplied in your area. To assign the IP address manually, refer to Appendix D, GPIB-ENET Configuration Utilities, and run the IPassign utility. For automatic IP address assignment using a RARP server, power on the GPIB-ENET. The POWER LED comes on immediately. The READY LED flashes while the GPIB-ENET completes its power-on self tests and the IP address is assigned. The power-on self tests take about 10 seconds to complete, then the box obtains its IP address. The time required for the IP address assignment is highly dependent on your network and the configuration of your GPIB-ENET. If the READY LED does not become steady after 1 minute, refer to Chapter 6, the section Troubleshooting Hardware Problems. Once the READY LED remains steady, the unit is ready to operate and you can configure the software. Step 5. Configure Subnet Information Before the GPIB-ENET is fully functional, you should configure it with proper subnet information. Your GPIB-ENET may work properly even if you skip this step, but National Instruments recommends that you configure information about the subnet. This information includes the broadcast IP address and netmask to use on the subnet and up to four router IP addresses. Refer to Appendix D, GPIB-ENET Configuration Utilities, and run the IPsetup utility. ESP-488 SRM for the GPIB-ENET 2-4 National Instruments Corp.

19 Chapter 3 The ESP-488 C Language Library This chapter contains a general description of the C language programming interface used in the ESP-488 software. Global Variables Upon completion of a command, the following global variables describe the GPIB status, the error conditions, and, in the case of I/O operations, the data transfer count. ibsta iberr ibcntl Describes the current GPIB status. Gives the error code but is not meaningful unless the ERR bit is set in ibsta. Gives the number of bytes read or written over the GPIB. This number can be an unsigned integer value in the range of 0 to 4 GB. National Instruments Corp. 3-1 ESP-488 SRM for the GPIB-ENET

20 ESP-488 C Language Library Chapter 3 Status Variable: ibsta ESP-488 functions automatically update the ibsta status word, which contains 16 status bits. Some bits in ibsta can be set for both device-level calls (dev) and board-level calls (brd). Other bits are valid for board-level calls only. Table 3-1 lists the ibsta bits. Mnemonic Bit Pos. Table 3-1. Interface Status Word Bits Hex Value Type Description ERR dev, brd GPIB error TIMO dev, brd Time limit exceeded END dev, brd END or EOS detected SRQI brd SRQ is asserted CMPL dev, brd I/O completed LOK 7 80 brd Lockout State REM 6 40 brd Remote State CIC 5 20 brd Controller-In-Charge ATN 4 10 brd Attention is asserted TACS 3 8 brd Talker LACS 2 4 brd Listener DTAS 1 2 brd Device Trigger State DCAS 0 1 brd Device Clear State ESP-488 SRM for the GPIB-ENET 3-2 National Instruments Corp.

21 Chapter 3 ESP-488 C Language Library 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. Later in this chapter, a section 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 been exceeded. TIMO is set in the status word following an ibwait call if the TIMO bit of the ibwait mask parameter is set and the time limit expires. TIMO is also set following any synchronous I/O functions (for example, ibcmd, ibrd, and ibwrt) if a timeout occurs during one of these calls. TIMO is cleared in all other circumstances. END (dev, brd) END indicates that either the GPIB EOI line has been asserted or that the EOS byte has been received, if the software is configured to terminate a read on an EOS byte. END is cleared when any I/O operation is initiated. Some applications might need to know the exact I/O read termination mode of a read operation EOI by itself, the EOS character by itself, or EOI plus the EOS character. You can use the ibconfig function (option IbcEndBitIsNormal) to enable a mode in which the END bit is set only when EOI is asserted. In this mode if the I/O operation completes because of the EOS character by itself, END is not set. The application should check the last byte of the received buffer to see if it is the EOS character. SRQI (brd) SRQI indicates that a GPIB device is requesting service. SRQI is set whenever the GPIB-ENET is CIC and the GPIB SRQ line is asserted. SRQI is cleared either when the GPIB board ceases to be the CIC or when the GPIB SRQ line is unasserted. CMPL (dev, brd) CMPL indicates the condition of I/O operations. It is set whenever an I/O operation is complete. CMPL is cleared while an I/O operation is in progress. National Instruments Corp. 3-3 ESP-488 SRM for the GPIB-ENET

22 ESP-488 C Language Library Chapter 3 LOK (brd) LOK indicates whether the GPIB-ENET is in a lockout state. LOK is set whenever the GPIB-ENET detects that the Local Lockout (LLO) message has been sent either by the GPIB-ENET or by another Controller. LOK is cleared when the System Controller unasserts the Remote Enable (REN) GPIB line. REM (brd) REM indicates whether the GPIB-ENET is in the remote state. REM is set whenever the Remote Enable (REN) GPIB line is asserted and the GPIB-ENET detects that its listen address has been sent either by the GPIB-ENET or by another Controller. REM is cleared in the following situations: When REN becomes unasserted When the GPIB-ENET as a Listener detects that the Go to Local (GTL) command has been sent either by the GPIB-ENET or by another Controller CIC (brd) CIC indicates whether the GPIB-ENET is the Controller-In-Charge. CIC is set when the ibsic function is executed while the GPIB-ENET is System Controller or when another Controller passes control to the GPIB-ENET. CIC is cleared whenever the GPIB-ENET detects Interface Clear (IFC) from the System Controller, or when the GPIB-ENET passes control to another device. ATN (brd) ATN indicates the state of the GPIB Attention (ATN) line. ATN is set whenever the GPIB ATN line is asserted, and it is cleared when the ATN line is unasserted. TACS (brd) TACS indicates whether the GPIB-ENET is addressed as a Talker. TACS is set whenever the GPIB-ENET detects that its talk address (and secondary address, if enabled) has been sent either by the GPIB-ENET itself or by another Controller. TACS is cleared whenever the GPIB-ENET detects the Untalk (UNT) command, its own listen address, a talk address other than its own talk address, or Interface Clear (IFC). ESP-488 SRM for the GPIB-ENET 3-4 National Instruments Corp.

23 Chapter 3 ESP-488 C Language Library LACS (brd) LACS indicates whether the GPIB-ENET is addressed as a Listener. LACS is set whenever the GPIB-ENET detects that its listen address (and secondary address, if enabled) has been sent either by the GPIB-ENET itself or by another Controller. LACS is cleared whenever the GPIB-ENET detects the Unlisten (UNL) command, its own talk address, or Interface Clear (IFC). DTAS (brd) DTAS indicates whether the GPIB-ENET has detected a device trigger command. DTAS is set whenever the GPIB-ENET, as a Listener, detects that the Group Execute Trigger (GET) command has been sent by another Controller. DTAS is cleared on any call immediately following an ibwait call, if the DTAS bit is set in the ibwait mask parameter. See the Note below. DCAS (brd) DCAS indicates whether the GPIB-ENET has detected a device clear command. DCAS is set whenever the GPIB-ENET detects that the Device Clear (DCL) command has been sent by another Controller, or whenever the GPIB-ENET as a Listener detects that the Selected Device Clear (SDC) command has been sent by another Controller. DCAS is cleared on any call immediately following an ibwait call, if the DCAS bit was set in the ibwait mask parameter. It also clears on any call immediately following a read or write. See the Note below. Note: The ESP-488 package does not contain complete functions for handling DCAS and DTAS. (The actions that you should take are described by the IEEE standard and are device specific.) Therefore, you must clear these bits programmatically when you develop routines to handle these events. National Instruments Corp. 3-5 ESP-488 SRM for the GPIB-ENET

24 ESP-488 C Language Library Chapter 3 Error Variable: iberr When the ERR bit in the ibsta status word is set, the error code in iberr is valid. Table 3-2 lists possible error indications. Error Mnemonic iberr Value Table 3-2. iberr Descriptions EDVR 0 Operating system error Meaning ECIC 1 Function requires GPIB board to be CIC ENOL 2 No Listeners on the GPIB EADR 3 GPIB board not addressed correctly EARG 4 Invalid argument to function call ESAC 5 GPIB board not System Controller as required EABO 6 I/O operation aborted ECAP 11 No capability for operation EBUS 14 GPIB bus error ELCK 21 Lock error ECFG 24 Board is configured differently than requested ESP-488 SRM for the GPIB-ENET 3-6 National Instruments Corp.

25 Chapter 3 ESP-488 C Language Library EDVR (0) EDVR is an operating system error. When this error is reported, additional information is recorded in the ibcntl global variable. If ibcntl is 0xe0 or greater, the error is returned from the ESP-488 software. Otherwise, the error is the value in the global error variable errno. ECIC (1) ECIC is returned when one of the following functions is performed while the board is not CIC: Any device-level function that affects the GPIB ibcmd ibrpp Solutions Use ibsic to make the GPIB-ENET become Controller-In-Charge on the GPIB. Make sure your GPIB-ENET is configured as System Controller. In multiple CIC situations, always be certain that the CIC bit appears in the status word ibsta before attempting these calls. If it does not appear, you can perform an ibwait (for CIC) call to delay further processing until control is passed to the board. ENOL (2) ENOL usually occurs when a write operation is attempted with no Listeners addressed. ENOL can also occur in situations in which the GPIB-ENET is not the CIC and the Controller asserts ATN before the write call in progress has ended. When the GPIB-ENET is CIC, this error can also occur when an ibcmd is performed with no other devices attached to the GPIB. Solutions Make sure that the GPIB address of your device configuration matches the GPIB address of the device to which you want to write data. If you are not using device-level calls, make sure that your device is properly addressed to listen before writing to it by using ibcmd. National Instruments Corp. 3-7 ESP-488 SRM for the GPIB-ENET

26 ESP-488 C Language Library Chapter 3 Use the appropriate hex code in ibcmd to address your device. Check your cable connections and make sure at least two-thirds of your devices are powered on. Reduce the write byte count to that which is expected by the Controller. EADR (3) EADR occurs when the GPIB-ENET is CIC and is not properly addressing itself before read and write functions. This error is associated with board-level functions. Solutions Make sure that the GPIB-ENET is addressed correctly before calling board-level ibrd or ibwrt. EARG (4) EARG results when an invalid argument is passed to a function call. The following are some examples: A board-level call made with a valid device descriptor, or a device-level call made with a valid board descriptor An invalid Value is given for the Option requested with ibconfig Solutions Make sure that the parameters passed to the functions are valid. Do not use a device descriptor in a board function or vice-versa. ESAC (5) ESAC results when a function requiring System Controller functionality is called when the GPIB-ENET does not have System Controller capability. Solutions Give the GPIB board System Controller capability by calling ibconfig with the IbcSC option. ESP-488 SRM for the GPIB-ENET 3-8 National Instruments Corp.

27 Chapter 3 ESP-488 C Language Library EABO (6) EABO indicates that an I/O operation has been canceled, usually due to a timeout condition. This error also occurs upon receipt of the Device Clear message from the CIC while performing an I/O operation. Frequently, the I/O is not progressing (the Listener is not continuing to handshake or the Talker has stopped talking), or the byte count in the call which timed out was more than the other device was expecting. Solutions Use the correct byte count in input functions or have the Talker use the END message to signify the end of the transfer. Lengthen the timeout period for the I/O operation using ibconfig with the IbcTMO option. Make sure that you have configured your device to send data before you request data. ECAP (11) ECAP results when the GPIB-ENET lacks the ability to carry out an operation or when a particular capability has been disabled in the software and a call is made that requires the capability. Solutions Check the validity of the call, or make sure the GPIB-ENET has the necessary capability. EBUS (14) EBUS results when certain GPIB bus errors occur during device-level 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 ibconfig function using the IbcTMO option. EBUS results if a timeout occurred while sending these command bytes. Solutions Verify that the instrument is operating correctly. Check for loose or faulty cabling or several powered off instruments on the GPIB. If the timeout period is too short to send command bytes, increase the timeout period. National Instruments Corp. 3-9 ESP-488 SRM for the GPIB-ENET

28 ESP-488 C Language Library Chapter 3 ELCK (21) ELCK occurs when a request cannot be completed because the GPIB-ENET is locked or being used by another user. Locking of descriptors is not supported by the ESP-488 software. However, this error is possible when another user is using your GPIB-ENET with a National Instruments driver that supports locking. Solutions Make sure that no one else is using your GPIB-ENET. ECFG (24) ECFG occurs only when opening a descriptor. It indicates that the GPIB-ENET is already online and configured (PAD, SAD, TIMEOUT, and so on) by another user. The descriptors returned are valid. ECFG is just a warning that the GPIB-ENET is configured differently than requested. After you have a valid descriptor, you can change the configuration using ibconfig (as long as the descriptor is not locked). Note: You should alert other active GPIB-ENET users before changing the configuration of a descriptor, because the changes may have unpredictable effects on other applications. Solutions Make sure that no one else is using your GPIB-ENET. ESP-488 SRM for the GPIB-ENET 3-10 National Instruments Corp.

29 Chapter 3 ESP-488 C Language Library Count Variable: ibcntl The ibcntl variable is updated with the actual byte count that is transferred over the GPIB after every I/O function has completed. ESP-488 Function Descriptions The remainder of this chapter lists the functions in the ESP-488 software package. Table 3-3 lists the device-level functions. Table 3-4 lists the board-level functions. Table 3-3. List of Device-Level Functions Function ibconfig ibfind ibonl ibrd ibrpp ibrsp ibwait ibwrt Purpose Change the software configuration parameters Open and initialize a device descriptor Place the device online or offline Read data from a device into a user buffer Conduct a parallel poll Conduct a serial poll Wait for GPIB events Write data to a device from a user buffer Table 3-4. List of Board-Level Functions Function ibcmd ibconfig ibfind ibonl ibrd ibrpp ibsic ibwait ibwrt Purpose Send GPIB commands Change the software configuration parameters Open and initialize a board descriptor Place the interface board online or offline Read data from a device into a user buffer Conduct a parallel poll Assert interface clear Wait for GPIB events Write data to a device from a user buffer National Instruments Corp ESP-488 SRM for the GPIB-ENET

30 Chapter 4 ESP-488 Functions This chapter describes the purpose, format, input and output parameters, and possible errors for each function available with the ESP-488 software. For general programming information, refer to Chapter 5, Using Your ESP-488 Software. In addition, the ESP-488 distribution diskette contains sample source code. Function Names The functions in this chapter are listed alphabetically. Each function is designated as board level, device level, or both. Purpose Each function description includes a brief statement of the purpose of the function. Input and Output The input and output parameters for each function are listed. Function Return describes the return value of the function. The return value of the ESP-488 functions is usually the value of ibsta. Description The description section gives details about the purpose and effect of each function. Possible Errors Each function description includes a list of errors that could occur when the function is invoked. Examples Each function description includes sample code showing how to use the function. Unlike an actual program, these examples do not check for or handle errors. For a more detailed and complete example, refer to the sample application program supplied on the distribution diskette. National Instruments Corp. 4-1 ESP-488 SRM for the GPIB-ENET

31 ESP-488 Functions Chapter 4 IBCMD Board Level IBCMD Purpose Send GPIB commands. Format int16 ibcmd (GPIBDESCRIPTOR Descriptor, int8 *Cmdbuf, uint32 Cnt) Input Descriptor Cmdbuf Cnt Output Function Return Board descriptor returned from ibfind Buffer of command bytes to send Number of command bytes to send The value of ibsta Description ibcmd sends Cnt bytes from Cmdbuf over the GPIB as command bytes (interface messages). The number of command bytes transferred is returned in the global variable ibcntl. Refer to Appendix A, Multiline Interface Messages, for a table of the defined interface messages. Command bytes are used to configure the state of the GPIB. They are not used to send instructions to GPIB devices. Use ibwrt to send device-specific instructions. Possible Errors EABO EARG ECIC EDVR ENOL The timeout period expired before all of the command bytes were sent. Descriptor does not refer to a board. The GPIB-ENET is not Controller-In-Charge. A system or other unrecoverable error has occurred. No devices are on the GPIB. ESP-488 SRM for the GPIB-ENET 4-2 National Instruments Corp.

32 Chapter 4 ESP-488 Functions IBCMD Board Level IBCMD (Continued) Example Using a board-level descriptor previously opened with ibfind(), issue GPIB command bytes. #include "esp.h" GPIBDESCRIPTOR Board; ibcmd(board, "?_@!", 4); /*Issue GPIB command messages UNL and UNT followed by Talk address 0 and Listen address 1*/ National Instruments Corp. 4-3 ESP-488 SRM for the GPIB-ENET

33 ESP-488 Functions Chapter 4 IBCONFIG Board Level IBCONFIG Device Level Purpose Change the software configuration parameters. Format int16 ibconfig (GPIBDESCRIPTOR Descriptor, int8 Option, int8 Value Input Descriptor Option Value Board or device unit descriptor returned from ibfind A parameter that selects the configuration item The value to which the selected configuration item is to be changed Output Function Return The value of ibsta Description ibconfig changes the configuration item to the specified value for the selected board or device. Option may be any of the defined constants in Table 4-1 and Value must be valid for the parameter that you are configuring. The previous setting of the configured item is return in iberr. Possible Errors EARG Either Option or Value is not valid. See Tables 4-1 and 4-2. ECAP EDVR The driver is not able to make the requested change. A system or other unrecoverable error has occurred. ESP-488 SRM for the GPIB-ENET 4-4 National Instruments Corp.

34 Chapter 4 ESP-488 Functions IBCONFIG Board Level IBCONFIG Device Level (Continued) Table 4-1 lists the options you can use with ibconfig when Descriptor is a board descriptor. If the table does not list the default value for a particular option, the default value is determined by the ESP-488 software. The following is an alphabetical list of the Option constants included in Table 4-1. Constants Definitions Constants Definitions IbcEndBitIsNormal 0x001A IbcPPollTime 0x0019 IbcEOSchar 0x000F IbcReadAdjust 0x0013 IbcEOScmp 0x000E IbcRsv 0x0021 IbcEOSrd 0x000C IbcSAD 0x0002 IbcEOSwrt 0x000D IbcSC 0x000A IbcEOT 0x0004 IbcSRE 0x000B IbcIst 0x0020 IbcTIMING 0x0011 IbcPAD 0x0001 IbcTMO 0x0003 IbcPP2 0x0010 IbcWriteAdjust 0x0014 IbcPPC 0x0005 National Instruments Corp. 4-5 ESP-488 SRM for the GPIB-ENET

35 ESP-488 Functions Chapter 4 IBCONFIG Board Level IBCONFIG Device Level (Continued) Options (Constants) Table 4-1. ibconfig Board Configuration Parameter Options Options (Definitions) Description IbcPAD 0x0001 Changes the primary address of the GPIB-ENET. Valid values are IbcSAD 0x0002 Changes the secondary address of the GPIB-ENET. Valid values are 0 to disable secondary addressing; to change the secondary address. IbcTMO 0x0003 Changes the I/O timeout limit of the GPIB-ENET. TNONE 0 no timeout T10us 1 10 µs T30us 2 30 µs T100us µs T300us µs T1ms 5 1 ms T3ms 6 3 ms T10ms 7 10 ms T30ms 8 30 ms T100ms ms T300ms ms T1s 11 1 s T3s 12 3 s T10s s T30s s T100s s T300s s T1000s s IbcEOT 0x0004 zero = Disable EOI termination. non-zero = Enable EOI termination. IbcPPC 0x0005 Configures the GPIB-ENET for parallel polls. Valid values are 0 to unconfigure the parallel poll configuration; to configure parallel polls. Default: zero. IbcSC 0x000A zero = Release system control. non-zero = Request system control. (continues) ESP-488 SRM for the GPIB-ENET 4-6 National Instruments Corp.

36 Chapter 4 ESP-488 Functions IBCONFIG Board Level IBCONFIG Device Level (Continued) Table 4-1. ibconfig Board Configuration Parameter Options (Continued) Options (Constants) Options (Definitions) Description IbcSRE 0x000B zero = Release the REN line. non-zero = Assert the REN line. Default: zero. IbcEOSrd 0x000C zero = Ignore EOS character during read operations. non-zero = Terminate reads when the EOS character is read. IbcEOSwrt 0x000D zero = Do not assert EOI with the EOS character during write operations. non-zero = Assert EOI with the EOS character during write operations. IbcEOScmp 0x000E zero = Use seven bits for the EOS character comparison. non-zero = Use eight bits for the EOS character comparison. IbcEOSchar 0x000F Any 8-bit value. This byte becomes the new EOS character. IbcPP2 0x0010 zero = PP1 mode-remote parallel poll configuration. non-zero = PP2 mode-local parallel poll configuration. Default: zero. IbcTIMING 0x = Normal timing (T1 delay of 2 µs). 2 = High-speed timing (T1 delay of 500 ns). 3 = Very high-speed timing (T1 delay of 350 ns). The T1 delay is the GPIB source handshake timing. IbcReadAdjust 0x = No byte swapping. 1 = Swap pairs of bytes during a read. Default: zero. (continues) National Instruments Corp. 4-7 ESP-488 SRM for the GPIB-ENET

37 ESP-488 Functions Chapter 4 IBCONFIG Board Level IBCONFIG Device Level (Continued) Table 4-1. ibconfig Board Configuration Parameter Options (Continued) Options (Constants) Options (Definitions) Description IbcWriteAdjust 0x = No byte swapping. 1 = Swap pairs of bytes during a write. Default: zero. IbcPPollTime 0x = Use the standard duration (2 µs) when conducting a parallel poll. 1 to 17 = Use a variable length duration when conducting a parallel poll. The duration represented by 1 to 17 corresponds to the IbcTMO values. Default: zero. IbcEndBitIsNormal 0x001A zero = Do not set the END bit of ibsta when an EOS match occurs during a read. non-zero = Set the END bit of ibsta when an EOS match occurs during a read. Default: non-zero. IbcIst 0x0020 zero = Clear the individual status (ist) bit of the GPIB-ENET. non-zero = Set the individual status (ist) bit of the GPIB-ENET. IbcRsv 0x0021 Changes the serial poll status byte of the GPIB-ENET. Default: zero. ESP-488 SRM for the GPIB-ENET 4-8 National Instruments Corp.

38 Chapter 4 ESP-488 Functions IBCONFIG Board Level IBCONFIG Device Level (Continued) Table 4-2 lists the options you can use with ibconfig when Descriptor is a device descriptor. If the table does not list the default value for a particular option, the default value is determined by the ESP-488 software. The following is an alphabetical list of the Option constants included in Table 4-2. Constants Definitions Constants Definitions IbcEndBitIsNormal 0x001A IbcPAD 0x0001 IbcEOSchar 0x000F IbcReadAdjust 0x0013 IbcEOScmp 0x000E IbcSAD 0x0002 IbcEOSrd 0x000C IbcSPollTime 0x0018 IbcEOSwrt 0x000D IbcTMO 0x0003 IbcEOT 0x0004 IbcWriteAdjust 0x0014 National Instruments Corp. 4-9 ESP-488 SRM for the GPIB-ENET