GPIB Error Codes and Common Solutions

Error Condition: Driver error.

Description: EDVR is returned when GPIB hardware is not configured properly, or the interface name or device name passed to the ibfind function is incorrect.

Possible Cause: Often EDVR errors are caused when you misspell the interface name of your board or the device name of your instrument. For example, the default interface name for NI boards is GPIB0, but you may misspell it as GPIBO (with an "oh" instead of a zero). This error may also occur if the board index passed to the ibdev function is incorrect. The board index is the number portion of the interface name for the GPIB board, but many people make the incorrect assumption that it is the primary address of the board. For example, I may install a PCI-GPIB board in my computer and give a primary address of 2. The default interface name for board is GPIB0, so it has a board index of 0, not 2.

Solutions:

• Use the default settings for your GPIB hardware in the GPIB Configuration Utility (i.e., GPIB0 for the interface name and zero for the primary address).
• Use the ibdev function instead of the ibfind function to open communications with your instrument (to avoid using its device name).
• If you must use device names for your instruments, then make sure they are correctly configured in the Device Templates of the GPIB Configuration Utility (see your NI-488.2 User Manual for more details).
• Use the unit descriptor returned from ibdev or ibfind as the first parameter in subsequent NI-488 functions. Examine the variable before the failing function to make sure its value has not been corrupted.

Error Condition: Function requires the GPIB board to be the Controller-In-Charge (CIC).

Description: Certain functions require your GPIB board to be the CIC - these functions are noted in the NI-488.2 Function Reference Manual (see the Related Link, below). By default, your GPIB board will be the System Controller, but this is not the same as being the Controller-In-Charge. The System Controller has the ability to become the CIC at any time (there can be one System Controller on a given General Purpose Interface Bus).

Possible Cause: Often ECIC errors are caused when you do not send an interface clear at the start of your program to make sure that your GPIB board is the CIC.

Solutions:

• If your GPIB board is supposed to be the System Controller, then use ibrsc 1 to make sure your GPIB board is configured as the System Controller.
• If your GPIB board is the System Controller, then use the ibsic function (or SendIFC function) to send an interface clear. This will make your GPIB board the CIC (it also resets GPIB communications on the bus).
• If your GPIB board is one of several controllers on the bus, then always check for the CIC bit of the status word, ibsta, before attempting any function calls that require your GPIB board to have CIC status. If it does not appear, then you can call the ibwait function (set the wait mask for the CIC bit) to delay further processing until control is passed to your GPIB board.

Error Condition: Function detected no Listener(s).

Description: GPIB communications require a single Talker (to write data messages) and one or more Listeners (to read data messages). ENOL usually occurs when a write operation is attempted, but no Listeners are addressed or there are no Listeners at the specified address(es). For a device write, ENOL indicates that the GPIB address you are attempting to communicate with does not match the GPIB address of the device connected to the bus.

Possible Cause: The instrument you are trying to communicate with is not at the expected primary address, the instrument is not powered on, or the cable to the instrument is either disconnected or broken.

Solutions:

• Make sure that the GPIB address of your device matches the GPIB address of the device to which you want to write data.
• Verify that the cable is properly connected to the instrument. Try switching cables to verify that the cable is not broken.
• Make sure that at least two-thirds of your devices are powered on.
• For board-level communications, use the appropriate hex code in the ibcmd function to address your device as a Listener.
• Call the ibpad function (and ibsad, if necessary) to set the primary address of your device. The ibpad function will return what the previous setting for the device was, and you can check to see if the configured address matches the device's actual address.

Error Condition: GPIB board (GPIB0 or GPIB1) is not addressed correctly.

Description: EADR occurs when the GPIB board is Controller-In-Charge (CIC) and is not properly addressing itself before read and write 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.

Possible Cause: Your GPIB board is configured for the same primary address as the instrument with which you are trying to communicate.

Solutions:

• Never configure your GPIB board to the same address as your device. You should (almost) always leave your GPIB board configured for primary address 0 and no secondary address. Call ibpad 0 and ibsad 0 at the beginning of your program to properly configure your board’s address.
• Make sure that the GPIB board is addressed correctly before calling ibrd, ibwrt, RcvRespMsg, or SendDataBytes.
• Avoid calling ibgts, except immediately after an ibcmd call. The ibcmd function causes the ATN line to be asserted, which tells instruments to expect command messages, instead of data messages.

Error Condition: Invalid argument to a function call.

Description: EARG results when an invalid argument is passed to a function call.

Possible Cause: The following are some examples: you call ibtmo with a value not in the range 0 through 17 (possible timeout values correspond to a table of values ranging from 0 to 17, where the default is 13, which represents a 10 second timeout); you call ibeos with meaningless bits set in the high byte of the second parameter; or you call ibpad (or ibsad) with invalid addresses.

Solutions:

• Check the NI-488.2 Function Reference Manual (see the Related Link, below) to make sure that your parameters are valid.
• Do not use a device descriptor in a board-level function or a board descriptor in a device-level function.

Error Condition: GPIB board not System Controller as required.

Description: ESAC results when ibsic, ibsre, SendIFC, or EnableRemote is called when the GPIB board does not have System Controller capability.

Possible Cause: The GPIB board is not configured to be the System Controller.

Solutions:

• Give the GPIB board System Controller capability by calling ibrsc 1 or by using the GPIB Configuration Utility.

Error Condition: I/O operation aborted.

Description: EABO indicates that an I/O operation has been cancelled for some reason.

Possible Cause: The EABO error is usually the result of a timeout during a read or a write operation, but it can also be caused by calling the ibstop function, the ibclr function, or similar functions while an I/O operation is in progress. You may receive a timeout during write operations with a PCI-GPIB board, if the PCI bus mastering (an option in the BIOS of your computer) is not enabled. You may receive a timeout during read operations, if the instrument you are reading from did not understand the previous command, so it has nothing to write to you. There are a few reasons why the instrument may not have anything to say:

• The message to the instrument may have been misspelled. For example, "*IDN?" is a common identification query for IEEE 488.2 compliant instruments. It is easy to misspell this message as "*IND?", which the instrument will not understand, so it will not generate a message string for you to read from the instrument.
• The message to the instrument may contain a command that the instrument does not understand. For example, the "*IDN?" message from the previous example is only understood by IEEE 488.2 compliant instruments. If your instrument is an older, non-IEEE 488.2 compliant device, then it will not understand "*IDN?", so it will not generate a message string for you to read from the instrument.
• The instrument may use a particular EOS (end of string) character as its termination method, but you may forget to append this termination character to your message. For example, if your instrument expects a linefeed as the EOS character, then "ID?" will not work, but "ID?\n" (where \n represents a linefeed in IBIC) will.
• You may expect to see EOI (end or identify, one of the five bus management lines) as the termination method, but if the instrument does not set the EOI line when it finishes sending its message, any read operation that you perform will time out.

Solutions:

• Make sure that your messages consist of commands that the instrument understands. Check your device's user manual for a list of possible commands.
• Check the user manual to see if your instrument needs to be in a GPIB or 488.2 mode in order to be a GPIB Listener.  Often instruments will only respond to the standard commands after they have been placed in this mode, and otherwise they will give an error despite being sent a valid command.
• Verify that you are using the correct termination method for your instrument. Byte count (where you expect to receive a certain number of bytes in a message) is always used, but some instruments use EOS and byte count, some use EOI and byte count, and some use only byte count. Check your device's user manual for the possible termination methods to use with your instrument.
• If EOS is the termination method, then be sure to append the termination character to the end of your message. You can specify the termination character in the GPIB Configuration Utility, but the NI-488.2 driver will not automatically append it for you!
• Lengthen the timeout period for I/O operations using the ibtmo command.
• If you receive all of the data and get an EABO error, then look for a particular end of string character (e.g., linefeed or carriage return) and configure the GPIB board to terminate the read on that character using the ibeos function.

Error Condition: Nonexistent GPIB board.

Description: ENEB occurs when no GPIB board exists at the I/O address specified in the GPIB Configuration Utility. This problem happens when the board is not physically plugged into the system, the I/O address specified during configuration does not match the actual board setting, there is a system conflict with the base I/O address, or the interface name for the board is different from the interface name of the board associated with your device.

Solutions:

• Determine the base I/O address for your board by looking in the GPIB Configuration Utility. Check your system's resource manager to see if another board is trying to use part or all of this address range. Make sure that the interface name of your board is the same as the interface name of the board that your device is configured to communicate with.
• For legacy boards make sure that the jumpers and dip switches on the board are set to the same resource settings that the GPIB Configuration Utility thinks it is using.
• Power down your computer and make sure that the board is firmly seated in its slot.

Error Condition: Error occurs while using DMA for data transfers.

Description: EDMA occurs if a system DMA error is encountered when the NI-488.2 driver attempts to transfer data over the GPIB using DMA.

Solutions:

• You can correct the EDMA problem in hardware by using the GPIB Configuration Utility to reconfigure your GPIB board, so that it does not use a DMA resource.
• You can correct the EDMA problem in software by using the ibdma function to disable DMA.

Error Condition: Function not allowed while asynchronous I/O is in progress.

Description: EOIP occurs when an asynchronous I/O operation has not finished before some other GPIB call is made. You can only use the ibstop, ibnotify, ibwait, or ibonl function during asynchronous I/O operations. If any other GPIB call is attempted, EOIP is returned.

Possible Cause: Calling any non-supported GPIB function calls during asynchronous I/O.

Solution:

• Resynchronize the driver and your application before making further GPIB calls. Resynchronization is accomplished by using one of the following functions: ibnotify (if the ibsta value passed to the ibnotify callback contains CMPL, the driver and application are resynchronized), ibwait (if the returned ibsta contains CMPL then the driver and application are resynchronized), ibstop (this cancels the asynchronous I/O operation, so that the driver and your application are resynchronized immediately), or ibonl (this cancels the asynchronous I/O operation and the interface is reset, so that the driver and your application are resynchronized immediately).

Error Condition: No capability for operation.

Description: ECAP results when your GPIB board 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 that capability.

Solution:

• Check the validity of the call, or make sure your GPIB interface board and driver has the needed capability.

Error Condition: File system error.

Description: EFSO results when an ibrdf or ibwrtf call encounters a problem performing a file operation. Specifically, this error indicates that the function is unable to open, create, seek, write, or close the file being accessed. The specific operating system error code for this condition is contained in ibcntl.

Solutions:

• Make sure the filename, path, and driver that you specified are correct.
• Make sure that the access mode of the file is correct. For example, do not try to write to a read-only file.
• Make sure there is enough room on the drive to hold the file.

Error Condition: Command byte transfer error.

Description: EBUS results when certain GPIB bus errors occur during device functions. All device functions send command bytes to perform addressing and other bus management operations. 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.

Possible Cause: There are no GPIB devices attached to your GPIB controller. This can be because all of your instruments are turned off, one of your instruments is in error and is asserting a handshaking line, your GPIB cable is disconnected from your board, or your GPIB cable is broken.

Solutions:

• Verify that all instruments are operating correctly, and that the ones you wish to communicate with are indeed powered-on.
• Disconnect all instruments and connect them one at a time to determine if one instrument is causing the problem.
• Check for loose or faulty cabling, and make sure that at least 2/3 of your instruments are powered-on (this is a requirement of the IEEE 488 specification).
• If the timeout period is too short for the driver to send command bytes, increase the timeout period.

Error Condition: Serial poll status byte(s) lost.

Description: ESTB is reported only by the ibrsp function. ESTB indicates that one or more serial poll status bytes received from automatic serial polls have been discarded due to lack of storage space. Several older status bytes are available; however, the oldest is being returned by the ibrsp call.

Possible Cause: Instrument is repeatedly asserting the SRQ line.

Solutions:

• Call ibrsp more frequently to empty the queue.
• Disable autopolling with the ibconfig function (option IbcAUTOPOLL) or disable autopolling in the GPIB Configuration Utility.

Error Condition: SRQ stuck in the ON position.

Description: ESRQ can only be returned by a device-level ibwait call, in which you have configured the ibwait function to return once the RSQ bit of the status word (ibsta) asserts. ESRQ indicates that a wait for RQS is not possible, because the GPIB SRQ line is stuck ON.

Possible Cause: This situation can be caused by the following events: a cabling problem may be causing the SRQ line to stay asserted; a device unknown to the software is asserting SRQ line - because the software does not know of this device, it can never serial poll the device to unassert the SRQ line; or a GPIB bus tester (or similar equipment) may be forcing the SRQ line to be asserted.

Solutions:

• Check to see if one of the devices on the bus (even ones not used by your application) is asserting the SRQ line. Disconnect them from the GPIB, if necessary.
• Inspect the GPIB cables and make sure that the connectors are seated properly.

Error Condition: Table problem.

Description: ETAB occurs only during the FindLstn and FindRQS functions. ETAB indicates that there was some problem with a table used by these functions.

Possible Cause: In the case of FindLstn, ETAB means that the given table did not have enough room to hold all of the addresses of the Listeners found. In the case of FindRQS, ETAB means that none of the devices in the given table were requesting service.

Solutions:

• In the case of FindLstn, increase the size of the result arrays.
• In the case of FindRQS, check to see if other devices not used by your application are asserting SRQ. Disconnect them from the GPIB, if necessary.

Error Condition: GPIB interface is locked and cannot be accessed.

Possible Cause: This error usually occurs when there are two or more processes that want to access the same interface and one process has already locked the interface. This error is returned when the operation cannot be performed because of the existing lock on the interface. It is also returned when a process tries to unlock an interface when no such lock exists.

Solution:

• The way to avoid the ELCK error is to wait for a random amount of time before trying to lock the interface again. In case you are using the iblck command to lock the interface, increase the LockWaitTime and wait for the other process to relinquish control over the interface. Also make sure that processes do not lock an interface up for the entire period of execution.

Error Condition: ibnotify callback failed to rearm.

Possible Cause: This error occurs when we use asynchronous notification (ibnotify) in NI-488.2 applications. This function is useful if you want your application to be notified asynchronously about the occurrence of one or more GPIB events. This event notification is carried out by means of a callback function. The callback function is registered with the NI-488.2 driver when the ibnotify call is made. This error indicates that this callback notification failed to rearm itself by returning an illegal value or when a fatal driver error (EDVR) has occurred.

Solutions:

• Ensure that the value being returned by your Callback function is a valid ibnotify mask value.
• Return a zero value from your Callback function to unregister the asynchronous event notification mechanism. Then call ibnotify to re-enable notification.

Error Condition: Input Handle is invalid.

Possible Cause: Several GPIB commands take in the input handle of the board or the device as an input parameter which can be the source of this error. This error can occur under several circumstances. Some scenarios are listed below:

• A valid board handle is passed in as a device handle parameter or vice versa.
• An invalid board or device descriptor is passed as input to any NI-488.2 function.
• A board id outside the range of 0-99 is passed in to a traditional NI-488.2 board-level function or NI-488.2 routine
• ibconfig or ibmask is called with a device unit descriptor and a board-only configuration option, or with a board unit descriptor and a device-only configuration option.

Solutions:

• Check to see if the device-level and board-level functions are not mixed up when calling the respective functions.
• Also check if the board index passed to the NI 488.2 call is a valid index number.

Error Condition: Wait In progress on specified Input handle.

Possible Cause: This error occurs in scenarios that have more than one thread in the same process and when two or more threads are accessing the same interface. EWIP indicates that an ibwait call is already in progress on the specified unit descriptor and it occurs when a thread is already performing an ibwait using the same descriptor and another thread tries to call ibwait on the same descriptor.

Solution:

• Make sure that at any given point in time, only one thread is performing an ibwait call on the given unit descriptor.

Error Condition: Event Notification was cancelled due to a reset of the interface.

Possible Cause: ERST results when an event notification was cancelled due to a reset of the interface. An ibwait call pending in the driver returns ERST in the following situations:

• Another thread in the same process calls ibonl using the same unit descriptor as ibwait.
• Another thread or process issues a board-level ibonl 1.

An ibnotify callback may be invoked with ERST in the following situations:

• Another process issues a board-level ibonl 1.

Solutions:

• Do not call ibonl with ibwait calls still pending in the driver.
• Prevent other applications from calling ibonl by locking the interface with iblck.

Error Condition: The Interface lost power.

Possible Cause: EPWR results when an interface loses power. This often results when the system goes to and returns from a standby state.

Solutions:

• Take all handles offline and reinitialize the application.
• Quit the application and restart the system.
• Disable standby and hibernate modes on the PC.

• NI-488.2 User Manual
• How to Automatically Launch and Use GPIB Interactive Control (IBIC)