IOtech 488 quick reference guide

GPIB-488

GPIB-488 Programming Reference Manual

Programming Reference Manual

July 2006
371930C-01

© Copyright 1996-2006 by Measurement Computing Corporation’s licensor(s). All rights reserved.

Support

Conventions

The following conventions are used in this manual:

[ ] Square brackets indicate the key to be pressed.

» 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.

This icon denotes a caution, which advises you of precautions to take to
avoid injury, data loss, or a system crash.

When symbol is marked on a product, it denotes a warning advising you to
take precautions to avoid electrical shock.

When symbol is marked on a product, it denotes a component that may be
hot. Touching this component may result in bodily injury.

bold Bold text denotes items that you must select or click in the software, such

as menu items and dialog box options. Bold text also denotes parameter
names.

italic Italic text denotes variables, emphasis, a cross reference, or an introduction

to a key concept. Italic text also denotes text that is a placeholder for a word
or value that you must supply.

monospace Text in this font denotes text or characters that you should enter from the

keyboard, sections of code, programming examples, and syntax examples.
This font is also used for the proper names of disk drives, paths, directories,
programs, subprograms, subroutines, device names, functions, operations,
variables, filenames, and extensions.

GPIB terms used within this manual are:

GPIB General Purpose Interface Bus

System controller The system controller has the unique ability to retrieve active control of the

bus or to enable devices to be remotely programmed. It takes control of the
bus by issuing an IFC (Interface Clear) message for at least 200 µsec. It also
can put devices into the remote state by asserting the REN (Remote Enable)
line.

There is always one system controller in a GPIB system. The system

controller is designated at system initialization either through the use of
hardware switches or by some type of configuration software, and is not
changed. The system controller can be the same controller as the one which
is the current active controller or an entirely different one. Note that if a
controller is both a system controller and the active controller and it passes
control to another controller, the system controller capability is not passed
along with it.

Active controller The active controller is the controller which has the ability to mediate all

communications which occur over the bus. In other words, the active
controller designates (addresses) which device is to talk and which devices
are to listen. The active controller is also capable of relinquishing its
position as active controller and designating another controller to become
the active controller.

Device A device is any IEEE-488 instrument which is not a system controller or

active controller. It can be idle or act as a talker and/or listener when
addressed or unaddressed by the active controller.

Listener A listener is any device which is able to receive data when properly

addressed. There can be up to 14 active listeners on the bus concurrently.
Some devices can also be a talker or controller; however, only one of these
functions can be performed at a time.

Talker A talker is a device which can transmit data over the bus when properly

addressed. Only one device can transmit at a time. Some devices can also
be a listener or controller; however, only one of these functions can be
performed at a time.

Contents

Chapter 1
GPIB Software Overview

Supported Languages.....................................................................................................1-1

GPIB Library Utility Programs......................................................................................1-2

Support For VISA Calls ..................................................................................1-2

GPIB-32.DLL function support.......................................................................1-2

ibnotify ............................................................................................................1-2

Chapter 2
Programming with the GPIB Library

General Concepts...........................................................................................................2-2

Device vs. Board I/O .......................................................................................2-2

Device I/O .......................................................................................................2-2

Board l/O .........................................................................................................2-3

Device Handles................................................................................................2-3

Global Variables ...............................................................................2-4

iberr—The Error Variable.................................................................2-4

ibcnt and ibcntl—Count Variables....................................................2-4

Chapter 3
GPIB 488.1 Library Reference

IBASK ...........................................................................................................................3-3

IBCAC ...........................................................................................................................3-6

IBCLR............................................................................................................................3-7

IBCMD ..........................................................................................................................3-8

IBCMDA .......................................................................................................................3-10

IBCONFIG..................................................................................................................... 3-11

IBDEV ...........................................................................................................................3-15

IBDMA ..........................................................................................................................3-17

IBEOS............................................................................................................................3-18

IBEOT............................................................................................................................3-20

IBFIND ..........................................................................................................................3-21

IBGTS............................................................................................................................3-22

IBIST .............................................................................................................................3-24

IBLINES ........................................................................................................................3-25

IBLN ..............................................................................................................................3-27

IBLOC ...........................................................................................................................3-28

IBONL ...........................................................................................................................3-29

GPIB-488 v Programming Reference Manual

Contents

IBPAD ...........................................................................................................................3-30

IBPCT............................................................................................................................3-31

IBPPC............................................................................................................................ 3-32

IBRD.............................................................................................................................. 3-34

IBRDA...........................................................................................................................3-36

IBRDF ...........................................................................................................................3-37

IBRPP............................................................................................................................ 3-39

IBRSC............................................................................................................................ 3-40

IBRSP............................................................................................................................ 3-41

IBRSV ...........................................................................................................................3-42

IBSAD ...........................................................................................................................3-43

IBSIC............................................................................................................................. 3-44

IBSRE............................................................................................................................3-45

IBSTOP ......................................................................................................................... 3-46

IBTMO .......................................................................................................................... 3-47

IBTRG ...........................................................................................................................3-49

IBWAIT......................................................................................................................... 3-50

IBWRT .......................................................................................................................... 3-52

IBWRTA ....................................................................................................................... 3-54

IBWRTF........................................................................................................................ 3-55

Chapter 4
GPIB 488.2 Library Reference

AllSpoll.......................................................................................................................... 4-2

DevClear........................................................................................................................4-3

DevClearList.................................................................................................................. 4-4

EnableLocal................................................................................................................... 4-5

EnableRemote................................................................................................................ 4-6

FindLstn......................................................................................................................... 4-7

FindRQS........................................................................................................................ 4-8

PassControl.................................................................................................................... 4-9

Ppoll............................................................................................................................... 4-10

PPollConfig ................................................................................................................... 4-11

PPollUnconfig ............................................................................................................... 4-12

RcvRespMsg.................................................................................................................. 4-13

ReadStatusByte.............................................................................................................. 4-14

Receive .......................................................................................................................... 4-15

ReceiveSetup ................................................................................................................. 4-16

ResetSys ........................................................................................................................4-17

Send ...............................................................................................................................4-18

SendCmds...................................................................................................................... 4-19

SendDataBytes .............................................................................................................. 4-20

SendIFC.........................................................................................................................4-21

Programming Reference Manual vi GPIB-488

SendList .........................................................................................................................4-22

SendLLO........................................................................................................................4-23

SendSetup ......................................................................................................................4-24

SetRWLS .......................................................................................................................4-25

TestSRQ.........................................................................................................................4-26

TestSys...........................................................................................................................4-27

Trigger ...........................................................................................................................4-28

TriggerList .....................................................................................................................4-29

WaitSRQ........................................................................................................................4-30

Appendix A
Multiline Interface Messages

Appendix B
IBSTA

Appendix C
IBERR

Contents

GPIB-488 vii Programming Reference Manual

GPIB Software Overview

The GPIB software includes the 488.1 library, the 488.2 library, and a set
of utility programs. The 488.1 library consists of all of the functions and
subroutines that begin with the letters "
to devices on the GPIB bus by their device names and handles rather than
by their GPIB addresses.

• The 488.2 library consists of all the routines that do not begin with the
letters "
bus by their GPIB addresses rather than by their names or handles.

Note The GPIB library is available only in a 32-bit version.

Supported Languages

The GPIB library provides identical routines for each supported language.
Languages supported by the GPIB library at the time this manual was
published are listed below.

ib". The 488.2 library routines refer to devices on the GPIB

1

ib". The 488.1 library routines refer

Table 1-1. Programming Languages

Programming Languages

Delphi

C

VB

GPIB-488 1-1 Programming Reference Manual

Chapter 1 GPIB Software Overview

GPIB Library Utility Programs

The following utility programs are installed with the GPIB library
software.

Utility program Description

GPIBDIAGNOSTIC.EXE

GPIBINTERACTIVECONTROL.EXE

GPIBCONFIGURATION.EXE

Support For VISA Calls

VISA (Virtual Instrument Software Architecture) drivers are command
drivers that convert company and program-independent VISA calls into
company-dependent calls.

GPIB-32.DLL function support

Each library function defined by GPIB 488.1 and GPIB 488.2 has a
corresponding entry point in

ibnotify

The GPIB library does not support ibnotify. Applications that utilize the

ibnotify function will not run properly.

Hardware test program (Win32)

Interactive control program (Win32)

Configuration utility program (Win 32)

gpib-32.DLL.

Programming Reference Manual 1-2 GPIB-488

Programming with the GPIB
Library

The GPIB library contains two different and complete GPIB libraries.

Original 488.1 library—The 488.1 library (also referred to as the original
library), consists of all of the functions and subroutines that begin with the
letters "
than GPIB addresses when referring to GPIB devices. There are two
advantages to this approach:

• The GPIB addresses of each device are not stored in the program, so

• The program can refer to each device with an intelligible name rather

488.2 library—This library consists of all the routines that do not begin

with the letters "
GPIB addresses rather than by names. The Device I/O section does not
apply to the 488.2 library.

ib". This library uses a concept of device names and handles rather

the same program can run on different buses where the addresses of
each device are different.

than a number (the GPIB address).

ib". These routines refer to all devices on the bus by their

2

The GPIB library includes different routines that allow you to control the
operations of the GPIB bus in a very specific manner. You may find the
number of routines included in the GPIB library intimidating, however, in
most applications you need to use only a small subset of these routines.

The routines are divided into two distinct libraries. All routines which begin
with "

ib" are part of the "488.1" or "Original GPIB library." All other

routines are part of the "488.2 library." You only need to use one or the
other library. Each library provides a different method of performing the
same tasks. The choice of which library to use is a matter of personal
preference. If you use the original GPIB library, you can perform either
Board Level or Device Level operations.

GPIB-488 2-1 Programming Reference Manual

Chapter 2 Programming with the GPIB Library

General Concepts

This section explains the difference between routines which use Device I/O
and those which use Board I/O, the use of device handles, and the global
variables used by the library routines.

Device vs. Board I/O

The most typical GPIB operations are sending commands to a device
attached to the bus and reading back responses. To do this, program the
GPIB board to execute these steps:

1. Address the selected device as a Listener.

2. Send the secondary address if used.

3. Address the board itself as the GPIB Talker.

4. Send the command bytes to the device.

5. Address the board itself as the Listener.

6. Read the response from the device.

7. Send the GPIB Unlisten (UNL) message.

8. Send the GPIB Untalk (UNT) message.

The original GPIB library interface is comprised of two different types of
routines: Board I/O and Device I/O. These routines are described in
Chapter 3, GPIB 488.1 Library Reference. You can program the board
using either Board I/O routines or Device I/O routines to perform the
sequence of operations outlined above.

The 488.2 library is all "Board I/O" in that you always supply the board ID
and the device address. Refer to Chapter 4, GPIB 488.2 Library Reference.

Device I/O

It is usually easier to use the Device I/O routines. Device I/O is very simple
to use and understand. Device I/O routines are higher-level routines which
conceal most of the underlying complexity of GPIB operations. The Device
I/O routines automatically take care of all of the low-level details involving
GPIB messages and addressing. For example, to accomplish the seven
steps listed above, you use only three routines:

•

ibdev—to open the device

•

ibwrt—to send the instrument command

•

ibrd—to read the data back from the device

Programming Reference Manual 2-2 GPIB-488

Board l/O

Chapter 2 Programming with the GPIB Library

In comparison, the Board I/O routines are low-level routines. If you use
them, you must understand how the GPIB operates in detail. Generally, the
only time you need to use Board I/O is if it is impossible to perform the
same operation using device I/O, such as passing control from one
controller to another.

To perform the same task as the seven steps outlined in Device vs. Board

I/O (send a command to a device), you need to know the codes for the

various forms of addressing and the codes for the GPIB Unlisten and
Untalk commands.

Use the routines in this sequence:

ibfind—to open the board

ibcmd—to send the address of the talker and listener

ibwrt—to send the command to the device

ibcmd—to send the address of the talker and listener

ibrd—to read the data back from the device

ibcmd—to send the Unlisten (UNL) and Untalk (UNT) commands

Device Handles

Most of the routines in the 488.1 library have a device handle as the first
argument. The first GPIB call in your program is usually
routine "opens" a board or device and returns a GPIB board or device
handle. If you pass the name of a board, it returns a board handle. Likewise,
if a device name is passed, a device handle is returned. Some library
routines only work with device handles, some only with board handles, and
some with both.

GPIB-488 2-3 Programming Reference Manual

ibfind. This

Chapter 2 Programming with the GPIB Library

Global Variables

The following global variables are used in all programming languages:

ibsta Status Word

iberr Error Codes

ibcnt, ibcntl Count Variables (short/long)

The

iberr variables are briefly explained here. For additional information

about

iberr, refer to Appendix C, IBERR.

For additional information about

ibcnt and ibcntl, refer to the routines

which return them.

iberr—The Error Variable

If a GPIB error occurs during a routine, its corresponding error code is
returned into the variable

iberr. Possible error codes and their meanings

are listed in Appendix C, IBERR.

ibcnt and ibcntl—Count Variables

These variables contain an integer which describes how many bytes were
actually transferred during a read or write operation.
value (16-bits wide) and

ibcntl is a long integer value (32-bits wide).

ibcnt is an integer

Programming Reference Manual 2-4 GPIB-488

GPIB 488.1 Library Reference

This chapter describes each of the 488.1 GPIB library routines. A short
description of the routine, its syntax, parameters, any values that are
returned, any special usage notes, and an example are included for each
routine. The routines are listed in alphabetical order. The following table
lists all of the 488.1 GPIB library routines. A full description of each
routine follows the table.

Table 3-1. 488.1 Library routines

Name Description

3

ibask

ibcac

ibclr

ibcmd

ibcmda

ibconfig

ibdev

ibdma

ibeos

ibeot

ibfind

ibgts

ibist

iblines

ibln

ibloc

Returns software configuration information

Become Active Controller

Clear specified device

Send GPIB commands from a string

Send GPIB commands asynchronously from a string

Configure the driver

Open and initialize a device when the device name is unknown

Enable/Disable DMA

Change EOS

Change EOI

Open a device and return its unit descriptor

Go from Active Controller to standby

Define IST bit

Return status of GPIB bus lines

Check for presence of device on bus

Go to Local

ibonl

GPIB-488 3-1 Programming Reference Manual

Place device online/offline

Chapter 3 GPIB 488.1 Library Reference

Table 3-1. 488.1 Library routines (Continued)

Name Description

ibpad

ibpct

ibppc

ibrd

ibrda

ibrdf

ibrpp

ibrsc

ibrsp

ibrsv

ibsad

ibsic

ibsre

ibstop

ibtmo

ibtrg

Change Primary address

Pass Control

Parallel Poll Configure

Read data to a string

Read data asynchronously

Read data to file

Conduct parallel poll

Request/release system control

Return serial poll byte

Request service

Define secondary address

Send IFC

Set/clear REN line

Stop asynchronous I/O operation

Define time limit

Trigger selected device

ibwait

ibwrt

ibwrta

ibwrtf

Programming Reference Manual 3-2 GPIB-488

Wait for event

Write data from a string

Write data asynchronously from a string

Write data from file

IBASK

Returns software configuration information.

Syntax

C ibask (int boarddev, int option, unsigned int

Parameters

boarddev A board handle or device handle
option Specifies which configuration item to return; see Table.
value Current value of specified item returned here

Option Valid for Information returned

Chapter 3 GPIB 488.1 Library Reference

*value)

Table 3-2. ibask Options

IbaPAD bd/dev

IbaSAD bd/dev

IbaTMO bd/dev

IbaEOT bd/dev

IbaPPC bd

IbaREADDR dev

IbaAUTOPOLL bd

IbaCICPROT bd

IbaSC bd

IbaSRE bd

Primary address of board or device

Secondary address of board or dev

The current timeout value for I/O commands (refer to
ibtmo for a list of possible values)

0 = EOI asserted at end of write

non zero = EOI is not asserted at end of write

The current parallel poll configuration of the board

0 = Forced re-addressing is disabled

non zero = Forced re-addressing is enabled.

0 = automatic at end of write

non zero = automatic serial poll is disabled

0 = CIC protocol is disabled

non zero = CIC protocol is enabled

0 = board is not system controller

non zero = board is system controller

0 = do not automatically assert REN line when system
controller

non zero = automatically assert REN line when system
controller

GPIB-488 3-3 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

Table 3-2. ibask Options (Continued)

Option Valid for Information returned

IbaEOSrd bd/dev

IbaEOSwrt bd/dev

IbaEOScmp bd/dev

IbaEOSchar bd/dev

IbaPP2 bd

IbaTiming bd

IbaDMA bd

IbaSendLLO bd

IbaSPollTime dev

0 = ignore EOS char during reads

non zero = terminate read when EOS char is received

0 = don’t assert EOI line when EOS char is sent

non zero = assert EOI line whenever EOS char is sent

0 = 7 bit compare is used when checking for EOS char

non zero = 8 bit compare is used when checking for EOS
char

0 = The current EOS char of board or device

0 = board is in remote parallel poll configuration

non zero = board is in local parallel poll configuration

Current T1 timing delay 1 = Normal (2 us), 2 = High
Speed (500 ns), 3 = Very High Speed (350 ns)

0 = The interface does not use DMA for GPIB transfers

non zero = The interface uses DMA for GPIB transfers

0 = LLO command is not sent when device is put online

non zero = LLO command is sent

Length of time to wait for parallel poll response before
timing out

IbaPPollTime bd

IbaEndBitIsNormal bd

Length of time to wait for parallel port response

0 = The END bit of ibsta is not set when the EOS
character is received without EOI.

non zero = The END bit of ibsta is set when the EOS
character is received

IbaUnAddr dev

0 = The untalk and unlisten (UNT, UNL) are not sent after
each device level read/write

non zero = The UNT, UNL commands are sent after each
device lever read/write

IbaIST bd

IbaBNA dev

Programming Reference Manual 3-4 GPIB-488

The individual status (ist) bit of the interface

Device’s access board

Chapter 3 GPIB 488.1 Library Reference

Returns ibsta will contain a 16-bit status word; refer to Appendix B,

IBSTA.

iberr will contain an error code if an error occurred
value will contain the current value of selected configuration

item

Usage notes Some options apply to boards, some to devices and some apply to

both boards and devices.
A program may modify many of these configuration items via
library routines (for example,

ibask returns the modified version.

Example Returns the

C int dev, istbit;

dev = ibdev (0,3,0,13,1,0);
ibask (dev, IbaIST, &istbit);

ist bit of a device at PAD 3.

ibtmo, ibeos, etc.). In that case,

GPIB-488 3-5 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBCAC

Makes the specified board the Active Controller.

Syntax

C ibcac (int board, int sync)

Parameters

board is an integer containing the board handle

sync specifies if the GPIB board is to take control synchronously or asynchronously. If sync

is 0, the GPIB board takes control asynchronously. Otherwise, it takes control synchronously
(immediately).

When the board takes control, the GPIB interface board asserts the ATN line. When taking
control synchronously, the board waits for any data transfer to be completed and then takes
control. Note that if synchronous take control is specified while an
is in progress, the synchronous take control may not occur if a timeout or other error occurs
during the

In comparison, if the board is to take control asynchronously, it takes control immediately,
without waiting for any data transfers to be completed.

ibrd/ibwrt.

ibrd or ibwrt operation

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. In particular, the ECIC error occurs if

the specified GPIB board cannot become an Active Controller.

Usage Notes

This routine is only used when doing board level I/O.

Example

GPIB board 1 takes control asynchronously.

C ibcac (brd1, 0);

Programming Reference Manual 3-6 GPIB-488

IBCLR

Clears a specified device.

Syntax

C ibclr (int device)

Parameters

device is an integer containing the device handle.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, the GPIB Interface Board (which is currently the CIC) sends
its talk address over the GPIB. This makes it the active talker. It then unlistens all devices and
addresses the specified device as a listener. Finally, the GPIB board clears the device, by
sending the

Chapter 3 GPIB 488.1 Library Reference

Selected Device Clear message.

Example

This example uses ibdev to return the unit descriptor for a device at PAD 5, a DMM, into the
variable dmm. The DMM is then cleared.

C int dmm;

dmm = ibdev(0,5,0,13,1,0);

/*open instrument*/

ibclr (dmm);

/* clear it */

GPIB-488 3-7 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBCMD

Sends GPIB commands.

Syntax

C ibcmd (int board, char cmnd[], long bytecount)

Parameters

board is an integer containing the board handle.

cmnd is the command string to be sent. This string is comprised of GPIB multiline commands.

These commands are listed in Appendix A, Multiline Interface Messages.

bytecount is the number of command bytes to be transferred.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

ibcnt, ibcntl will contain the number of bytes that were transferred. ibcnt is a 16-bit

integer.
instead of

ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl

ibcnt.

Usage Notes

This routine passes only GPIB commands. It cannot be used to transmit programming
instructions (data) to devices. Use the

This routine terminates when any one of the following takes place:

• Commands transfer is successfully completed.

• An error occurs

• A timeout occurs

• A Take Control (TCT) command is sent

• The system controller asserts the IFC (Interface Clear) line.

Programming Reference Manual 3-8 GPIB-488

ibrd and ibwrt routines for this purpose.

Example

Chapter 3 GPIB 488.1 Library Reference

This example prepares the board to talk and addresses three devices (at addresses 8, 9, and

10) to listen.

C char *command;

command = "\0x3f\0x5f\0x40\0x28\0x29\0x2a"
ibcmd (board, command, 6);

GPIB-488 3-9 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBCMDA

Transfers GPIB commands asynchronously from a string.

Syntax

C ibcmda (int board, char cmnd[], long bytecount)

Parameters

board is an integer containing the board handle.

cmnd is thecommand string to be sent. This string is comprised of GPIB multiline

commands.These commands are listed in Appendix A, Multiline Interface Messages.

bytecount is the number of command bytes to be transferred. Note that in C, although this

parameter is of type long, integer values and variables can also be passed.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. An ECIC error is generated if the GPIB

Interface Board specified is not the Active Controller. If no listening devices are found, the
ENOL error is returned.

ibcnt, ibcntl will contain the number of bytes that were transferred. ibcnt is a 16-bit

integer.
instead of

ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl

ibcnt.

Usage Notes

This routine passes only commands. It is not used to transmit programming instructions (data)
to devices. Use the

ibrd/ibwrt routines for this purpose.

Asynchronous I/O is not explicitly supported and will be treated as synchronous.

Example

This example prepares the board to talk and addresses three devices (at addresses 8, 9, and

10) to listen.
loop. This loop calls
completed or an error has occurred. The program may do anything within the WHILE loop
except make other GPIB I/O calls.

C char command[] = "\0x3f\0x5f\0x40\0x28\0x29\0x2a"

Programming Reference Manual 3-10 GPIB-488

ibcmda executes in the background and the program continues into the WHILE

ibwait to update ibsta and checks ibsta to see if ibcmda has

ibcmda (board, command, 6);
while ( (ibsta & CMPL+ERR) == 0)

ibwait (board, 0);

IBCONFIG

Changes configuration parameters.

Syntax

C ibconfig (int boarddev, unsigned int option,

Parameters

boarddev is an integer containing either a board handle or device handle.

option is a number which represents the configuration option to be changed. See Table 3-3.

value is the new configuration option value. Allowed values differ according to the option

being programmed.

Option Valid for Description

Chapter 3 GPIB 488.1 Library Reference

unsigned int value)

Table 3-3. ibconfig Options

IbcPAD bd or dev

IbcSAD bd or dev

IbcTMO bd or dev

IbcEOT bd or dev

IbcPPC bd

IbcREADDR dev

New Primary Address. Available primary addresses
range from 0 to 30.
(See

ibpad.)

value can be from 0 to 30 decimal.

New Secondary Address. There are 31 secondary
addresses available.
decimal. (See

value can be 0 or from 96 to 126

ibsad.)

Timeout Value. The approximate time that I/O
functions take before a timeout occurs.

value is a

number from 0 to 15 which corresponds to timeout
values ranging from 10 usec to 100 sec. (See ibtmo)

Enable/disable END message. If this option is enabled,
the EOI line is asserted when the last byte of data is sent.
If

value = 0, then the EOI line is not asserted. If value

is non zero, the EOI line is asserted.

Parallel Poll Configure. Redefines the parallel poll
configuration bytes.

value can be 0, or from 96 to 126

decimal.

Forced re-addressing. If value = 0, forced
re-addressing is disabled

non zero = Forced re-addressing is enabled.

GPIB-488 3-11 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

Table 3-3. ibconfig Options (Continued)

Option Valid for Description

IbcAUTOPOLL bd

IbcCICPROT bd

IbcIRQ bd

IbcSC bd

IbcSRE bd

IbcEOSrd bd or dev

IbcEOSwrt bd or dev

Enable/Disable Automatic Serial Polling. If value is 0,
then Automatic Serial Polling is disabled. Otherwise, it
is enabled.

CIC Protocol. If value is 0, then CIC Protocol is not
used. Otherwise, CIC Protocol is used.

Enable/Disable Hardware Interrupts. If value is 0, then
hardware interrupts are disabled, otherwise

value

specifies the IRQ level the board uses to generate
interrupts.

Request/Release System Control. If value is 0, the
board is not able to support routines requiring system
controller capability.

If value is non-zero, the board can support routines
requiring system controller capability.

Assert/Unassert REN. If value is 0, the REN line is
unasserted. Otherwise, the REN line is asserted.

Recognize EOS. If value is non-zero, a read is
terminated when the End-Of-String (EOS) character is
detected. Otherwise, EOS detection is disabled.

Assert EOI. If value is non-zero, then EOI is asserted
when the EOS character is sent. Otherwise, EOI is not
asserted.

IbcEOScmp bd or dev

7/8-bit Comparison. If value is zero, compare the
low-order 7 bits of the EOS character. Otherwise,
compare 8-bits.

IbcEOSchar bd or dev

IbcPP2

End-Of-String (EOS) Character. value is the new EOS
character.

value can be any 8-bit value.

Parallel Poll Remote/Local. If value is zero, then the
GPIB Interface Board is remotely configured for a
parallel poll by an external Controller. Otherwise, the
GPIB interface board accepts parallel poll configuration
commands from your application program.

Programming Reference Manual 3-12 GPIB-488

Chapter 3 GPIB 488.1 Library Reference

Table 3-3. ibconfig Options (Continued)

Option Valid for Description

IbcTIMING bd

IbcDMA bd

IbcSendLLO bd

IbcSPollTime bd or dev

IbcEndBitIsNormal bd or dev

IbcPPollTime bd

IbcUnAddr dev

Handshake Timing. If value is 1, normal timing (> 2
*sec.) is used. If
nsec.) is used. If

value is 2, high-speed timing (> 500

value is 3, very high-speed timing (>

350 nsec.) is used.

Enable/Disable DMA. If value is zero, DMA transfers
are disabled, otherwise

value specifies the DMA

channel that the board uses.

Send Local Lockout. If value is 0, LLO command is
not sent when device is put online; non zero = LLO
command is sent

Serial Poll Timeout. value ranges from 0 to 17 specify
timeouts of 10 msecs to 1000 secs. Refer to Table 3-6,

Timeout Codes.

If set, causes END status to be set on receipt of EOS.

Parallel Poll Timeout. value ranges from 0 to 17
specify timeouts of 10 msecs to 1000 secs. Refer to
Table 3-6, Timeout Codes.

If value is 0, the untalk and unlisten (UNT, UNL) are
not sent after each device level read/write; non zero =
the UNT, UNL commands are sent after each device
lever read/write

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

None.

GPIB-488 3-13 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

Example

This example illustrates how to change the timeout value for GPIB Interface Board 1 to 300
msec.

C int device;

device = ibfind ("gpib1");
ibconfig (device, IbcTMO, 10);

Programming Reference Manual 3-14 GPIB-488

IBDEV

Obtains a device handle for a device whose name is unknown. It opens and initializes the
device with the configuration given.

Syntax

C device = ibdev (int boardindex, int pad, int sad,

Parameters

boardindex identifies the GPIB Interface Board with which the device descriptor is

associated. It is an index in the range 0 to (total number of boards - 1).

pad is the primary address of the device. Available addresses range from 0 to 30.

sad is the secondary address of the device. There are 31 secondary addresses available. value

can be 0, or from 96 to 126 decimal; see Appendix A, Multiline Interface Messages. If 0 is
selected, the driver will not expect the device to require a secondary address.

timeout is the timeout of the device. This is a value from 0 to 17 which corresponds to

timeout value ranging from 10 usec to 1000 sec. See Table 3-6, Timeout Codes, for a list of
timeouts and corresponding values.

Chapter 3 GPIB 488.1 Library Reference

int timeout, int eot, int eos)

eot when writing to a device, eot specifies whether or not to assert EOI with the last data byte.

If eot is non-zero, EOI is asserted. If eot is 0, EOI is not asserted.

eos specifies the End-Of-String termination mode to be used when communicating with the

device. See Table 3-4, Selecting EOS, for a description of special formatting features of this
argument.

Returns

device will contain the assigned descriptor or a negative number. If device is a negative

number, then an error occurred. Two types of errors can occur:

•An

EDVR or ENEB error is returned if a device is not available or the board index specifies

a non-existent board.

•An

iberr will contain an error code, if an error occurred.

EARG error is returned if illegal values are given for pad, sad, timeout, eot, eos.

Usage Notes

This routine returns the device handle of the first available user-configurable device it finds
in the device list.

GPIB-488 3-15 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

Example

This example opens an available device, associates it with GPIB interface board 1, and assigns
it the following device configuration parameters.

• primary address = 3

• secondary address = 19 (115 decimal, 73 hex)

• timeout = 10 sec

• Assert EOI

• EOS Disabled

• The new device handle is returned.

C int device;

device = ibdev(1, 3, 0x73, 13, 1, 0);

Programming Reference Manual 3-16 GPIB-488

IBDMA

Enables/Disables DMA.

Syntax

C ibdma (int board, int dma)

Parameters

board is an integer containing the board handle.

dma is an integer which indicates whether DMA is to be enabled or disabled for the specified

GPIB board. If
memory are performed using DMA. Otherwise, programmed I/O is used.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. An ECAP error results if you tried to

enable DMA operations for a board which does not support DMA operation. If no error
occured, the previous value of

Chapter 3 GPIB 488.1 Library Reference

dma is non-zero, all read and write operations between the GPIB board and

dma is stored in iberr.

Usage Notes

The GPIB Interface Board must have been configured for DMA operations in order for this
routine to be executed successfully. This routine is useful for alternating between
programmed I/O and DMA operations. This call remains in effect until one of the following
occurs:

• Another

•

• The program is re-started.

• The maximum DMA transfer length in Windows is 64 K bytes.

Example

C int board, ibsta;

ibdma call is made.

ibonl or ibfind is called.

This example enables DMA transfers for GPIB Interface Board 1. It
assumes that the DMA channel was previously selected in your
configuration program.

board = ibfind ("gpib1");
ibsta = ibdma (board, 1);

GPIB-488 3-17 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBEOS

Changes or disables End-Of-String termination mode.

Syntax

C ibeos (int boarddev, int eos)

Parameters

boarddev is an integer containing the board/device handle.

eos is an integer that defines which termination mode and what EOS character are to be used,

as shown in Table 3-4, Selecting EOS.

Table 3-4. Selecting EOS

eos

Method Description

A Terminate read when EOS is detected. Can be used

alone or in combination with Method C. (Constant =
REOS)

B Set EOI with EOS on write function. Can be used alone

or in combination with Method C. (Constant = XEOS)

C Compare all 8 bits of EOS byte rather than low 7 bits for

all read and write functions. (Constant = BIN)

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. If an error does not occur the previous

value of

eos is stored in iberr.

Usage Notes

This call only defines an EOS byte for a board or device. It does not cause the handler to
automatically send that byte when performing writes. Your application must include the EOS
byte in the data string it defines.

If this call defines an EOS for a device, then the defined EOS is used for all reads and writes
involving that device. Likewise, if the call defines an EOS for a board, then all reads and
writes involving that board will use that EOS.

High Byte Low Byte

00000100 EOS

character

00001000 EOS

character

00010000 EOS

character

Programming Reference Manual 3-18 GPIB-488

Chapter 3 GPIB 488.1 Library Reference

This call remains in effect until one of the following occurs:

• Another

•

ibonl or ibfind is called.

ibeos call is made.

• The system is re-started.

Example

See also

ibeot

This example configures the GPIB system to send the END message whenever the line feed
character is sent to a particular device. Method B described in Table 3-4, Selecting EOS, is
used (

XEOS).

C int device;

ibeos (device, XEOS + '\n');

GPIB-488 3-19 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBEOT

Enables/Disables assertion of EOI on write operations.

Syntax

C ibeot (int boarddev, int eot)

Parameters

boarddev is an integer containing the board or device handle. Here it represents a GPIB

Interface Board or a device. This value is obtained by calling the

eot is an integer which defines whether or not EOI is to be asserted. If eot is non-zero then

EOI is asserted automatically when the last byte of the message is sent. If
is not asserted.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This call is used to temporarily change the default EOT setting.

ibfind routine.

eot is 0, then EOI

It is useful to automatically send EOI with the last data byte in situations where variable
length data is being sent. When EOI is enabled, you do not need to send an EOS character.

If this call specifies a device, then EOI is asserted/unasserted on all writes to that device.
Likewise, if the call specifies a board, then EOI is asserted/unasserted on all writes from that
board. To assert EOI with an EOS, use the

ibeos routine. This call remains in effect until one

of the following occurs:

• Another ibeot call is made.

• ibonl or ibfind is called.

• The system is re-started.

See also ibeos

Example

Assert EOI with last byte of all write operations from GPIB board 1.

C int device;

device = ibfind ("gpib1");
ibeot (device,1);

Programming Reference Manual 3-20 GPIB-488

IBFIND

Opens a board or device and returns the handle associated with a given name.

Syntax

C boarddev = ibfind (char name[])

Parameters

name is the string specifying the board or device name.

Returns

boarddev will contain the device handle associated with the given name. If a negative

number is returned, this indicates that the call has failed. This most often happens when the
specified name is does not match the default/configured board or device name.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This call is also opens the device/board and initializes the software parameters to their default
configuration settings. See

Chapter 3 GPIB 488.1 Library Reference

ibonl.

Using

ibfind to obtain device descriptors is useful only for compatibility with existing

applications. New applications should use

ibdev instead of ibfind.

Example

This example returns the device handle associated with the device named "DEV5" to the
variable

C Board = ibfind("GPIB0");

GPIB-488 3-21 Programming Reference Manual

dmm. If the device name is not found, the program will jump to an error routine.

if (Board < 0) error();

Chapter 3 GPIB 488.1 Library Reference

IBGTS

Puts an Active Controller in Standby mode.

Syntax

C ibgts (int board, int handshake)

Parameters

board is an integer containing the board handle.

handshake determines whether or not the shadow handshake option is to be activated. If
handshake is non-zero, then the GPIB shadow handshake option is activated. This means

that the GPIB board shadow handshakes the data transfer as an acceptor and when the END
message is detected, the GPIB board enters a
hold-off state on the GPIB. Thus, the GPIB board participates in the data handshake as an
Acceptor without actually reading the data. It monitors the transfers for the
holds off subsequent transfers. Using this mechanism, the GPIB board can take control
synchronously on a subsequent operation like

If

handshake is 0, then no shadow handshake or holdoff is done.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

Not Ready For Data (NRFD) handshake

END message and

ibcmd or ibrpp.

iberr will contain an error code, if an error occurred. The ECIC error occurs if the board is

not an Active Controller.

Usage Notes

This call makes the GPIB board go to Controller Standby state and unasserts the ATN line if
it is initially the Active Controller. This allows transfers between GPIB devices to occur
without the GPIB board's intervention.

Before performing an

ibgts with a shadow handshake, use the ibeos function to

define/disable EOS character detection.

Example

This example uses the ibcmd routine to instruct GPIB board 1 to unlisten
all devices (ASCII ?, hex 3F), and then to address a Talker at MTA26
(ASCII Z, hex 5) and a Listener at MLA11 (ASCII +, hex 2B).
then called to unassert the ATN line and place the GPIB board in Standby
mode. This action allows the Talker to send messages to the Listener. Note
that the GPIB commands/addresses are coded using printable ASCII
characters, for example, "?Z+".

Programming Reference Manual 3-22 GPIB-488

ibgts is

C int gpib1;

gpib1 = ibfind ("GPIB1");
ibcmd (gpib1, "?Z+", 3);
ibgts (gpib1, 1);

Chapter 3 GPIB 488.1 Library Reference

GPIB-488 3-23 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBIST

Sets/Clears the IST (Individual Status) Bit of the GPIB board for parallel polls.

Syntax

C ibist (int board, int statusbit)

Parameters

board is an integer containing the board handle.

statusbit indicates whether the IST bit is to be cleared or set. If statusbit is non-zero,

then the IST bit is set. Otherwise, if

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. If an error does not occur, the previous

IST value is stored in

Usage Notes

This routine is used when the GPIB Interface is not the Active Controller.

iberr.

statusbit = 0, the IST bit is cleared.

IST should be SET to indicate to the controller that service is required.

Example

This example clears GPIB Board 1's IST bit.

C int gpib1;

gpib1 = ibfind ("GPIB1");
ibist (gpib1, 0);

Programming Reference Manual 3-24 GPIB-488

Chapter 3 GPIB 488.1 Library Reference

IBLINES

Returns the status of the GPIB control lines.

Syntax

C iblines (int board, short *clines)

Parameters

board is an integer containing the board handle.

Returns

clines contains a valid mask and GPIB control line state data. Low-order bytes (bits 0

through 7) contain the mask indicating the capability of the GPIB interface board to sense the
status of each GPIB control line. Upper bytes (bits 8 through 15) contain the GPIB control
line state information. The pattern of each byte is as follows:

High

15 14 13 12 11 10 9 8

EOI AT N SRQ REN IFC NRFD NDAC DAV

7 6 5 4 3 2 1 0

Low (Mask)

To determine if a GPIB control line is asserted, first check the appropriate bit in the lower byte
to determine if the line can be monitored (indicated by a 1 in the proper bit position), then
check the corresponding bit in the upper byte. If the bit is set (1), the corresponding control
line is asserted. If the bit is clear (0), the control line is unasserted.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Handshake Information:

• NRFD = Not Ready for Data

• NDAC = Not Data Accepted

• DAV = Data Valid

Interface Management:

• ATN = Attention

GPIB-488 3-25 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

• IFC = Interface Clear

• REN = Remote Enable

• SRQ = Service Request

• EOI = End or Identify

Usage Notes

In order for this call to function properly, all devices attached to the GPIB bus must adhere to
IEEE-488 specification.

Example

This example tests the state of the ATN line.

C #define ATNLINE = 0x40

int lines;
iblines (board, &lines);
if (lines & ATNLINE == 0)

printf "ATN line can not be monitored by this
GPIB board";
else ( (lines >> 8) & ATNLINE ) == 0)

printf "ATN line is not asserted";

Programming Reference Manual 3-26 GPIB-488

IBLN

Check that a device is present on the bus.

Syntax

C ibln (int board, int pad, int sad, short* listen)

Parameters

board is the board or device handle.

pad is the primary address of the GPIB device (0-30).

sad is the secondary address of the GPIB device (96-126 or 0x60-0x7e) or one of the constant

values NO_SAD or ALL_SAD.

listen is the variable that the result is returned to.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code if an error occurred.

Chapter 3 GPIB 488.1 Library Reference

listen will contain 0 if no listener is found. Contains non-zero if a listener is found.

Usage Notes

Set sad = NO_SAD (0) if the device does not have a secondary address.

Set

sad = ALL_SAD (-1) if you do not know the device’s secondary address and you want

all possible secondary addresses to be tested.

Example

This example tests for the presence of a device with a GPIB address of 4.

C int board, listen;

board = ibfind (“GPIB0”);
ibln (board, 4, NO_SAD, &listen);

GPIB-488 3-27 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBLOC

Forces the specified board/device to go to local program mode.

Syntax

C ibloc (int boarddev)

Parameters

boarddev is an integer containing the device or board handle.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This routine is used to place boards or devices temporarily in local mode. If this routine
specifies a device, the following GPIB commands are sent:

• Talk address of the access board

• Secondary address of the access board

• Unlisten (UNL)

• Listen address of the device

• Secondary address of the device (as necessary)

• Go to Local (GTL)

If this routine specifies a board, the board is placed in a local state by sending the Return to
Local (RTL) message, if it is not locked in remote mode. The LOK bit of the status word
indicates whether the board is in a lockout state. The
front panel RTL switch if the computer is used as an instrument.

IBLOC function is used to simulate a

Example

Return GPIB board 1 to local state.

C int gpib1;

gpib1 = ibfind("GPIB1");
ibloc (gpib1);

Programming Reference Manual 3-28 GPIB-488

IBONL

Enables/Disables a device/interface board for operation.

Syntax

C ibonl (int boarddev, int online)

Parameters

boarddev is an integer containing the device/board handle.

online defines whether the device/board is to be enabled/disabled. If online is non-zero,

the device/board is enabled for operation (placed on-line). This restores the board/device to
its default settings. Otherwise, the board/device is placed off-line.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When a device is placed off-line, it is "closed". This means that in order to perform any other
operations with this device, you will need to re-open it by calling the
routine.

Chapter 3 GPIB 488.1 Library Reference

ibfind or ibdev

Example

This example restores the configuration of a device at PAD 1.

C int Dev;

Dev = ibdev (0,1,0,13,1,0);
ibonl (Dev, 1);

GPIB-488 3-29 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBPAD

Changes the primary address assigned to a device or interface board.

Syntax

C ibpad (int boarddev, int address)

Parameters

boarddev is an integer containing the board or device handle.

address specifies the new primary GPIB address. Valid primary addresses range from 0 to

30 (0 to 1E hex).

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code if an error occurred. Contains the previous primary address

if no error occurred.

Usage Notes

This routine temporarily changes the configuration setting. It remains in effect until ibonl or

ibfind is called, ibpad is called again, or the system is re-started.

EARG error occurs if address is out of range.

If a device is specified, its talk and listen addresses are assigned on the basis of
Listen Address equals

address + 20 hex. Its Talk Address equals address + 40 hex. Thus,

address. Its

if a primary address of 0D hex was specified, the corresponding Listen Address would be 2D
hex (MLA 13) and Talk Address would be 4D hex (MTA 13). If a board is specified, the board
is assigned the primary address defined by

address. Refer also to ibsad and IBONL.

Be sure that the address specified agrees with the GPIB address of the device. (Set with
hardware switches or by a software program. Refer to the device's documentation for more
information.)

Example

This example changes the primary GPIB address associated with a DVM at PAD 4 to 1C hex.

C int dvm;

dvm = ibdev (0,4,0,13,1,0);
ibpad (dvm, 0x1C);

Programming Reference Manual 3-30 GPIB-488

IBPCT

Passes control to another device.

Syntax

C ibpct (int device)

Parameters

device an integer containing the device handle.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This makes the specified device the Controller-In-Charge (CIC). The GPIB board goes to the
Controller Idle state and releases the ATN line.

The device that control is passed to must have Controller capability.

Chapter 3 GPIB 488.1 Library Reference

Example

This example makes a device at PAD 1 the Controller-In-Charge.

C int Dev;

Dev = ibdev (0,1,0,13,1,0);
ibpct(Dev);

GPIB-488 3-31 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBPPC

Enables/Disables parallel polling of the specified device.

Syntax

C ibppc (int boarddev, int command)

Parameters

boarddev is an integer containing the board or device handle. This value is obtained by

calling the

command is a valid parallel poll enable/disable message or 0. If command represents a PPE

message, then the device will use that message to respond to a parallel poll. Valid PPE

messages range from 60 to 6F hex. The PPE specifies the GPIB data line (DIO1 through
DIO8) on which the device is to respond and whether that line is to be asserted or unasserted.

The PPE byte is of the format:

7 6 5 4 3 2 1 0

ibfind routine.

0 1 1 0 SENSE P2 P1 P0

Where

SENSE indicates the condition under which the data line is to be asserted. The device

compares the value of the sense bit to its IST (individual status) bit and responds
appropriately. For example, if SENSE = 1, the device will drive the line TRUE if its IST = 1
or FALSE if IST = 0.

P2–P0 specify which GPIB data line should be used to respond to a parallel poll, as shown in

Table 3-5.

Table 3-5. Values for P2–P0

P2 P1 P0 GPIB Data Line

1 1 1 DIO8

1 1 0 DIO7

1 0 1 DIO6

1 0 0 DIO5

0 1 1 DIO4

Programming Reference Manual 3-32 GPIB-488

Chapter 3 GPIB 488.1 Library Reference

Table 3-5. Values for P2–P0

P2 P1 P0 GPIB Data Line

0 1 0 DIO3

0 0 1 DIO2

0 0 0 DIO1

For example, if the PPE byte 01101011 (hex 6B) is sent, the device will drive DIO4 true if its
IST bit = 1, or false if its IST bit = 0.

If

command is 0 or represents a PPD (Parallel Poll Disable) message, the current PPE

(Parallel Poll Enable) configuration is cancelled. Valid PPD messages range from 70 to 7F
hex. The PPD is of a similar format to the PPE byte, for example:

7 6 5 4 3 2 1 0

0 1 1 0 SENSE P2 P1 P0

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. Contains the previous value of
command if no error occurs.

Usage Notes

If boarddev specifies a GPIB interface board, this routine sets the board's Local Poll Enable
(LPE) message to

If

boarddev specifies a device, the GPIB Interface Board associated with the device

command.

addresses itself as a Talker, unlistens all devices (sends a UNL), addresses the specified device
as a Listener, and sends the PPC command followed by a PPE or PPD command.

Example

This example configures a device at PAD 2 to send DIO7 true if its IST bit = 1.

C int dev2;

dev2 = ibdev (0,2,0,13,1,0);
ibppc (dev2, 0x6B);

GPIB-488 3-33 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBRD

Reads data from a device/interface board into a string.

Syntax

C ibrd (int boarddev, char buf[], unsigned long

Parameters

boarddev is an integer containing the board or device handle.

bytecount)

buf is the storage buffer for the data. Up to 4 gigabytes-1 (2

size may be limited by the language you are using. Check documentation for your language.

bytecount specifies the maximum number of bytes to read.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code of the first error detected, if an error occurred. An EADR

results if the specified GPIB Interface Board is an Active Controller but has not been
addressed to listen. An

ibcnt, ibcntl will contain the number of bytes that were read. ibcnt is a 16-bit integer.
ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl instead

of

ibcnt.

Usage Notes

A read will terminate when one of the following occurs:

• The allocated buffer becomes full.

• An error is detected.

• The time limit is exceeded.

• A terminator (or EOI) is detected.

EABO error results if a timeout occurs.

32

-1 bytes) can be stored. String

If

boarddev specifies a device, the specified device is addressed to talk and its associated

access board is addressed to listen.

If

boarddev specifies a GPIB Interface board, you must have already addressed a device as

a talker and the board as a listener. If the board is the Active Controller, it will unassert ATN
in order to receive data. This routine leaves the board in that state.

Programming Reference Manual 3-34 GPIB-488

Example

Chapter 3 GPIB 488.1 Library Reference

This example reads 90 characters of data from a device at PAD 5.

C int dev5;

char rd [90];
dev5 = ibdev (0,5,0,13,1,0);
ibrd (dev5, rd, 90);

GPIB-488 3-35 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBRDA

Reads data asynchronously from a device/interface board into a string.

Syntax

C ibrda (int boarddev, char buf[], unsigned long

Parameters

boarddev is an integer containing the device/board handle.

bytecount)

buf is the storage buffer for the data. Up to 4 gigabytes-1 (2

size may be limited by the language you are using. Check documentation for your language.

bytecount specifies the maximum number of bytes to read.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code of the first error detected, if an error occurred. An EADR

results if the specified GPIB board is an Active Controller but has not been addressed to listen.
An

EABO error results if a timeout occurs.

ibcnt, ibcntl will contain the number of bytes that were read. ibcnt is a 16-bit integer.
ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl instead

of

ibcnt.

Usage Notes

Asynchronous I/O is not explicitly supported and will be treated as synchronous.

Example

In this example, ibwrt sends the command "DUMP" to a device. The device responds by
sending back a large block of data.
and the program continues on into the WHILE loop. The WHILE loop calls

MASK set to 0 to update IBSTA. The WHILE loop checks IBSTA to see if ibrda has

completed, or if an error has occurred. The program may do anything else within the WHILE
loop except make other GPIB I/O calls.

C char *readbuffer[5000];

32

-1 bytes) can be stored. String

ibrda begins a transfer of 5000 bytes in the background

ibwrt (device, "DUMP");
ibrda (device, readbuffer, 5000);
while ( (ibsta & CMPL+ERR) == 0)

ibwait (device, 0)

ibwait with

Programming Reference Manual 3-36 GPIB-488

IBRDF

Reads data from the GPIB into a file.

Syntax

C ibrdf (int boarddev, char filename [])

Parameters

boarddev is an integer containing the board or device handle.

filename is the name of the file (up to 250 characters, including drive/path) in which the data

is to be stored. Be certain to specify a drive and path if necessary. This file is automatically
opened as a binary file. It is created if it does not already exist.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. An EFSO error is generated if the file

can not be opened, created, found, written to, or closed.

ibcnt, ibcntl will contain the number of bytes that were read. ibcnt is a 16-bit integer.
ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl instead

of

ibcnt.

Chapter 3 GPIB 488.1 Library Reference

Usage Notes

A read terminates when one of the following occurs:

• The allocated buffer becomes full.

• An error is detected.

• The time limit is exceeded.

• A terminator (or EOI) is detected.

• A DCL or SDC command is received from the Active Controller.

If

boarddev specifies a device, the specified device is addressed to talk and its associated

access board is addressed to listen.

If

boarddev specifies a GPIB Interface board, you must have already addressed a device as

a talker and the board as a listener. If the board is the Active Controller, it unasserts ATN in
order to receive data. This routine leaves the board in that state.

GPIB-488 3-37 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

Example

This program sends the command "DUMP" to a device. The device responds by sending data
back.

ibrdf reads the incoming data and stores it in the file called gpib.dat on the C drive.

C ibwrt (boarddev, "DUMP");

ibrdf (boarddev, "c:gpib.dat");

Programming Reference Manual 3-38 GPIB-488

IBRPP

Initiates a parallel poll.

Syntax

C ibrpp (int boarddev, char *command)

Parameters

boarddev is an integer containing the device or board handle.

Returns

command will contain the response to the parallel poll.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

If this routine is called specifying a GPIB Interface Board, the board parallel polls all
previously configured devices. If the routine is called specifying a device, the GPIB Interface
board associated with the device conducts the parallel poll. Note that if the GPIB Interface
Board to conduct the parallel poll is not the Controller-In-Charge, an ECIC error is generated.

Chapter 3 GPIB 488.1 Library Reference

Before executing a parallel poll, the
with

ibppc to specify how they should respond to the poll.

ibppc function should configure the connected devices

Example

This program configures two devices for a parallel poll. It then conducts the poll. It is assumed
that voltmeter and scope have already been set by opening the devices with an
board has been set by opening the board with an

ibfind.

Both devices indicate that they want service by setting their first bit to 1. The first
specifies that the first device (
goes high. The second
line high when its first bit goes high. The

voltmeter) should drive the DIO1 line high when its first line

ibppc specifies that the second device (scope) should drive the DIO2

ibrpp conducts the poll and checks DIO1 and DIO2

to see if either device is requesting service.

C int voltmeter, scope, board, pollbyte;

ibppc (voltmeter, 0x68)
ibppc (scope, 0x69)
ibrpp (board, &pollbyte)
if (pollbyte & 1)

printf "Volt meter is requesting service"

if (pollbyte & 2)

printf "Oscilloscope is requesting service"

GPIB-488 3-39 Programming Reference Manual

ibfind and

ibppc

Chapter 3 GPIB 488.1 Library Reference

IBRSC

Request/Release System Control.

Syntax

C ibrsc (int board, int control)

Parameters

board is an integer containing the board handle.

control indicates whether the GPIB Interface Board is to become the system controller or

to relinquish system control capability. If
the system controller on the GPIB. If

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. If no error occurs, iberr equals 1 if

the specified interface board was previously the system controller or 0 if it was not.

Usage Notes

There may only be one system controller in a GPIB system.

control is non-zero, the specified board becomes

control is 0, the board is not the system controller.

Example

This example makes GPIB board 1 the system controller.

C int gpib1;

gpib1 = ibfind ("gpib1");
ibrsc (gpib1, 3);

Programming Reference Manual 3-40 GPIB-488

IBRSP

Serial polls a device.

Syntax

C ibrsp (int device, char *serialpollbyte)

Parameters

device is an integer containing the device handle.

Returns

serialpollbyte will contain the serial poll response byte of the device. The serial poll

response byte is device-specific with the exception of bit 6. If bit 6 (hex 40) is set, then the
device is requesting service. Consult the device's documentation for more information.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

If the automatic serial polling feature is enabled, the specified device may have been
automatically polled previously. If it has been polled and a positive response was obtained,
the RQS bit of
status byte. If the RQS bit of
device. This routine is used to serial poll one device, and obtain its status byte or to obtain a
previously stored status byte. If bit 6 (the hex 40 bit) of the response is set, the device is
requesting service.

Chapter 3 GPIB 488.1 Library Reference

ibsta is set on that device. In this case ibrsp returns the previously acquired

ibsta is not set during an automatic poll, it serial polls the

When a serial poll occurs, the following sequence of events happens. The board sends an UNL
(unlisten) command. It then addresses itself as a listener and sends a SPE (Serial Poll Enable)
Byte. It then addresses a device as a talker. The board then reads the serial poll response byte
from the device. The board then sends a serial poll disable (SPD) and untalks and unlistens
all devices.

Example

Returns the serial response byte (into serialpollbyte) of a device at PAD 1.

C int dev1;

char serialpollbyte;
dev1 = ibdev (0,1,0,13,1,0);
ibrsp (dev1, &serialpollbyte);

GPIB-488 3-41 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBRSV

Changes the serial poll response byte.

Syntax

C ibrsv (int board, int statusbyte)

Parameters

board is an integer containing the board handle.

statusbyte represents the serial poll response byte of the GPIB Interface Board. The serial

poll response byte is system-specific, with the exception of bit 6 (hex 40). If bit 6 (hex 40) is
set, then the SRQ line is asserted to indicate to the Controller-In-Charge that the board is
requesting service.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. If no error occurs, iberr will contain

the previous value of

statusbyte.

Usage Notes

This routine is used when the specified GPIB Interface Board is not the Controller-In-Charge.
It can be used to request service (set bit 6 of the serial response byte) from the
Controller-In-Charge or to change the value of GPIB Interface Board's serial poll response
byte.

Example

This example sets the GPIB Interface Board 1 serial poll status byte to 41 hex (assert SRQ)
which indicates that the board requires service.

C int gpib1;

gpib1 = ibfind ("gpib1");
ibrsv (gpib1, 0x41);

Programming Reference Manual 3-42 GPIB-488

IBSAD

Assigns/unassigns a secondary address to a board or device.

Syntax

C ibsad (int boarddev, int address)

Parameters

boarddev is an integer containing device or board handle.

address represents the secondary address. If address = 0 or address = 7F hex, secondary

addressing is disabled. If
secondary address is temporarily assigned to the board/device. The new secondary address is
used until it is either redefined by calling
calling

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurs. Contains the previously assigned

secondary address if no error occurs.

Chapter 3 GPIB 488.1 Library Reference

address is a legal secondary address (60 to 7E hex), the new

ibsad again, the device/board is re-initialized by

ibfind or ibonl, or the program is restarted.

Usage Notes

See also ibpad.

Example

This example assigns the secondary address 7 (MSA7, hex 67) to a device at PAD 5.

C int dev5;

dev5 = ibdev (0,5,0,13,1,0);
ibsad (dev5, 0x67);

GPIB-488 3-43 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBSIC

Asserts IFC (Interface Clear) signal. This re-initializes the GPIB system.

Syntax

C ibsic (int board)

Parameters

board is an integer containing the board handle.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. The ESAC error is generated if the

specified GPIB Interface Board is not the system controller.

Usage Notes

This routine can only be used if the specified GPIB board is the system controller. When the
routine is executed, the GPIB interface board asserts the
least 100 µsec. This action results in the system controller regaining control of the GPIB (for
example, becoming the Controller-In-Charge). When
functions of the bus devices are reset.

IFC (Interface Clear) signal for at

IFC line is asserted, all GPIB interface

Example

This example resets the GPIB bus associated with the specified GPIB Interface Board and
makes that board Controller-In-Charge.

C int gpib1;

gpib1 = ibfind("GPIB1");
ibsic (gpib1);

Programming Reference Manual 3-44 GPIB-488

IBSRE

Asserts/Unasserts the REN (Remote Enable) line.

Syntax

C ibsre (int board, int ren)

Parameters

board is an integer containing the board handle.

ren specifies whether the REN line is to be asserted or unasserted. If ren is zero, the REN line

is unasserted. Otherwise, the

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. The ESAC error is generated if the

specified GPIB interface board is not the system controller. Contains the previous
if no error occurs.

Usage Notes

This routine can only be used if the specified GPIB interface board is the system controller.

Chapter 3 GPIB 488.1 Library Reference

REN line is asserted.

REN state

Even though the

REN line is asserted, the device(s) is not put into remote state until is

addressed to listen by the Active Controller. When the REN line is unasserted, all devices
return to local control.

Example

This example puts the device at MLA 12 (2C hex, ASCII ,) and associated with GPIB
Interface Board 1 in remote mode.

C int gpib1:

gpib1 = ibfind ("GPIB1");
ibsre (gpib1, 2); /* Use any non-zero

value */

ibcmd (gpib1,",", 1);

GPIB-488 3-45 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBSTOP

Terminate an asynchronous operation.

Syntax

C ibstop (int boarddev)

Parameters

boarddev is an integer containing the device or board handle.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA. If an operation

is terminated, the

iberr will contain an error code, if an error occurred. If an operation is terminated, an EABO

error is returned.

Usage Notes

If a device is specified, all unfinished asynchronous operations (read, write, or command)
associated with that device is stopped. If a GPIB Interface Board is specified, all unfinished
asynchronous operations associated with that board is stopped. Once the operation(s) have
been terminated, the application is resynchronized with the driver.

ERR bit is set.

Example

This example starts a background write command and then immediately stops it.

C int dev;

dev = ibdev (0,2,0,13,1,0);
ibwrta(dev, "datafile");
ibstop (dev);

Programming Reference Manual 3-46 GPIB-488

IBTMO

Changes timeout value.

Syntax

C int ibtmo (int boarddev, int timeout)

Parameters

boarddev is an integer containing the board or device handle.

timeout specifies the timeout. The timeout value determines how long I/O routines wait for

a response from a device. When the timeout period expires during an I/O operation, the I/O
function returns an

Chapter 3 GPIB 488.1 Library Reference

EABO error. Valid timeout codes are shown in Table 3-6.

Table 3-6. Timeout Codes

Minimum

Code Val ue

TNONE 0 Disabled T100ms 9 100 msec

T10us 1 10 msec T300ms 10 300 msec

T30us 2 30 msec T1s 11 1 sec

T100us 3 100 msec T3s 12 3 sec

T300us 4 300 msec T10s 13 10 sec

T1ms 5 1 msec T30s 14 30 sec

T3ms 6 3msec T100s 15 100 sec

T10ms 7 10msec T300s 16 300 sec

T30ms 8 30 msec T1000s 17 1000 sec

timeout

Code Va lu e

Minimum

timeout

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. Contains the previous timeout code if

no error occurs.

Usage Notes

This routine is used to temporarily change the default timeout value assigned to the
device/GPIB Interface board.

GPIB-488 3-47 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

The new timeout is used until it is redefined (by calling ibtmo again) the device/board is
re-initialized (by calling

Example

This example changes the timeout (to 30 sec) for all calls specifying the "plotter" device at
PAD 3 .

C int plotter;

ibfind or ibonl); or the system is restarted.

plotter = ibdev (0,3,0,13,1,0);
ibtmo(plotter, T30us);

Programming Reference Manual 3-48 GPIB-488

IBTRG

Triggers the specified device.

Syntax

C ibtrg (int device)

Parameters

device is an integer containing device handle.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, the GPIB Interface Board associated with the device is
addressed to talk and all devices are unlistened. The specified device is then addressed to
listen and a GET (Group Execute Trigger) command is sent.

Example

This example triggers the specified device.

C int plotter;

Chapter 3 GPIB 488.1 Library Reference

plotter = ibdev (0,6,0,13,1,0);
ibtrg (plotter);

GPIB-488 3-49 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBWAIT

Forces application program to wait for a specified event(s) to occur.

Syntax

C ibwait (int boarddev, int mask)

Parameters

boarddev is an integer containing the board or device handle.

mask specifies the events that ibwait will wait for. Each bit in mask represents a different

event. These bits are the same as the bits in

Bit 15 14 13 12 11 10 9 8

Event ERR TIMO END SRQI RQS CMPL

Bit 7 6 5 4 3 2 1 0

ibsta positions.

Event LOK REM CIC AT N TAC S LACS DTAS DCAS

For more information regarding

ibsta, see Appendix B, IBSTA.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

Because the mnemonic for each bit of ibsta is defined as a constant within the header file,
you can elect to use the mnemonic rather than the hex value. If
if the event does not occur within the timeout period of the device.

If a GPIB interface board is specified, the

RQS bit is not applicable.

TIMO is set, ibwait returns

Programming Reference Manual 3-50 GPIB-488

Example

Chapter 3 GPIB 488.1 Library Reference

This example forces your program to wait indefinitely for the specified device to request
service.

C int plotter;

plotter = ibdev (0,1,0,13,1,0);
ibwait (plotter, RQS);

GPIB-488 3-51 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBWRT

Writes data from a string to the specified device or GPIB Interface Board.

Syntax

C ibwrt (int boarddev, char buf[], unsigned long

Parameters

boarddev is an integer containing the board or device handle.

bytecount)

buf is the string containing the data to be written. buf can contain up to 4 gigabytes-1 (2

bytes). String size may be limited by the language you are using. Check documentation for
your language.

bytecount specifies the number of bytes to be written from the string.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code of the first error detected, if an error occurred. An EADR

results if

ibcnt, ibcntl will contain the number of bytes that were written. ibcnt is a 16-bit integer.
ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl instead

of

ibcnt.

Usage Notes

This routine is used to send device-specific commands. A write terminates when one of the
following occurs:

• All bytes are transferred.

• An error is detected.

• The time limit is exceeded.

• A DCL (Device Clear) or SDC (Selected DC) is received from the CIC.

• All data is sent.

32

boarddev specifies a board and the board has not already been addressed to talk.

-1

If

boarddev specifies a device, the specified device is addressed to listen and its associated

access board is addressed to talk. If

boarddev specifies a GPIB Interface Board, the

Controller-In-Charge must have already addressed a device as a listener and the board as a
talker. If the board is the Active Controller, it unasserts ATN in order to send data. This routine
leaves the board in that state.

Programming Reference Manual 3-52 GPIB-488

Example

Chapter 3 GPIB 488.1 Library Reference

If you want to send an EOS character at the end of the data string, you must include it in the
string.

This example sends five bytes terminated by a carriage return and line feed to the specified
device.

C int ptr;

ptr = ibdev (0,7,0,13,1,0);
ibwrt (ptr,"IP2X5\r\n", 7);

GPIB-488 3-53 Programming Reference Manual

Chapter 3 GPIB 488.1 Library Reference

IBWRTA

Writes data asynchronously from a string to the specified device or GPIB interface board.

Syntax

C ibwrta (int boarddev, char buf[], unsigned long

Parameters

boarddev is an integer containing the board or device handle.

bytecount)

buf is the storage buffer for the data. Up to 4 gigabytes-1 (2

size may be limited by the language you are using. Check documentation for your language.

bytecount specifies the number of bytes to be written.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code of the first error detected, if an error occurred. An EADR

results if

ibcnt, ibcntl will contain the number of bytes that were written. ibcnt is a 16-bit integer.
ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl instead

of

ibcnt.

Usage Notes

Asynchronous I/O is not explicitly supported and will be treated as synchronous.

Example

In this example, ibwrt sends a command ("UPLOAD") to a device. The device expects a block
of data to be sent immediately.
program continues on into the WHILE loop. The WHILE loop calls
to 0 to update
error have occurred. The program may do anything else within the WHILE loop except make
other GPIB I/O calls.

C char writebuffer[5000];

32

-1 bytes) can be stored. String

boarddev specifies a board and the board has not already been addressed to talk.

ibwrta begins a transfer of 5000 bytes in the background and

ibwait with MASK set

ibsta. The WHILE loop checks ibsta to see if ibwrta has completed or any

ibwrt (device, "UPLOAD")
ibwrta (device, writebuffer, 5000);
while ( (ibsta & CMPL+ERR) == 0)

ibwait (device, 0)

Programming Reference Manual 3-54 GPIB-488

IBWRTF

Writes data from a file to the specified device or GPIB Interface Board.

Syntax

C ibwrtf (int boarddev, char filename [])

Parameters

boarddev is an integer containing the board or device handle.

filename is the name of the file (up to 50 characters, including drive/path) to store the data.

Specify a drive and path if necessary. This file is automatically opened as a binary file.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred. An EFSO error is generated if the file

can not be found.

ibcnt, ibcntl will contain the number of bytes that were written. ibcnt is a 16-bit integer.
ibcntl is a 32-bit integer. If the requested count was greater than 64 K, use ibcntl instead

of

ibcnt.

Chapter 3 GPIB 488.1 Library Reference

Usage Notes

A write terminates when one of the following occurs:

• An error is detected.

• The time limit is exceeded.

• A DCL or SDC is received from the Active Controller.

• All data has been sent.

If

boarddev specifies a device, the specified device is addressed to talk and its associated

access board is addressed to listen. If

boarddev specifies a GPIB interface board, you must

have already addressed a device as a listener and the board as a talker. If the board is the CIC,
it unasserts ATN in order to receive data. This routine leaves the board in that state.

Example

This program sends the command "UPLOAD" to a device and prepares the device to receive a
large amount of data. The program then sends the data from a file to the device.

C int device;

ibwrt (device, "UPLOAD");
ibwrtf (device, "c:gpib.dat");

GPIB-488 3-55 Programming Reference Manual

GPIB 488.2 Library Reference

This chapter describes each of the 488.2 GPIB library routines. A short
description of the routine, its syntax, parameters, any values that are
returned, any special usage notes, and an example are included for each
routine. The routines are listed in alphabetical order. The following table
lists all of the 488.2 GPIB library routines. A full description of each
routine follows the table.

Note 488.2 addresses contain two bytes packed into a word – the low byte is the primary

address and the high byte is the secondary address. If secondary addressing is not used, the
high byte should be zero.

Table 4-1. 488.2 Address word

HIGH BYTE LOW BYTE

Secondary Address (0 or 96-126) Primary Address (0-30)

488.2 routines use a board index as the first argument (typically zero) – not a handle.

4

GPIB-488 4-1 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

AllSpoll

Performs a serial poll on specified devices.

Syntax

C AllSpoll (int board, short addresslist[],

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to be serial polled.

Returns

resultlist is an array which contains the results of the serial poll. Once a device has been

serial polled, the results of the serial poll are stored in the corresponding element of

resultlist.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

short resultlist[])

iberr will contain an error code, if an error occurred. If a device times out, iberr contains

Error 6 –

EABO (see Appendix C, IBERR), and ibcnt contains the index of the timed-out

device.

Usage Notes

To poll only one GPIB device, use ReadStatusByte.

Example

This example serial polls two devices (GPIB address 6 and 7) connected to GPIB board 0.

C short addresslist[3] = {6,7,NOADDR};

short resultlist[2];
AllSpoll (0, addresslist, resultlist);

Programming Reference Manual 4-2 GPIB-488

DevClear

Clears one device.

Syntax

C DevClear(int board, short address)

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

address is the GPIB address of the device to clear.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This routine sends the GPIB Selected Device Clear (SDC) message to the specified device.

Chapter 4 GPIB 488.2 Library Reference

To clear multiple devices, use the

If

address is set to NOADDR, then all connected devices on the GPIB is cleared through the

Universal

Device Clear (UDC) message.

DevClearList routine.

Example

This example clears the device at GPIB primary address 4, secondary address 30 connected
to GPIB board 0.

C DevClear(0, MakeAddr (4,30));

/* Use MakeAddr macro (in GPIB.H) to pack

primary and secondary address */

GPIB-488 4-3 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

DevClearList

Clears specified devices.

Syntax

C DevClearList(int board, short addresslist[])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to be cleared.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This routine sends the GPIB Selected Device Clear (SDC) to the devices specified by

addresslist.

To clear only one device, use

DevClear.

Example

This clears the devices at GPIB addresses 6 and 7, connected to GPIB board 0.

C short addresslist[3] = {6,7,NOADDR};

DevClearList(0, addresslist);

Programming Reference Manual 4-4 GPIB-488

EnableLocal

Places specified devices in local mode (Can be "programmed" from front panel controls.).

Syntax

C EnableLocal(int board, short addresslist[])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to enable locally.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, the Controller addresses the specified GPIB devices as
listeners and then sends the GPIB

Chapter 4 GPIB 488.2 Library Reference

Go To Local (GTL) command.

To put all devices in local mode, use an array containing only the
unasserts the GPIB
mode.

Remote Enable (REN) line, thereby placing all GPIB devices in local

NOADDR value. This

Example

Put the GPIB devices at addresses 6 and 7 (connected to board 0) in local mode.

C short addresslist[3] = {6,7,NOADDR};

EnableLocal(0, addresslist);

GPIB-488 4-5 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

EnableRemote

Allow remote programming (by sending messages over the GPIB line) of a device.

Syntax

C EnableRemote(int board, short addresslist[])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to be put in remote programming mode.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, the system controller asserts the Remote Enable (REN) line
and the Controller addresses the specified devices as listeners.

Example

Places devices at GPIB addresses 6 and 7 (connected to GPIB board) in remote mode.

C short addresslist[3] = {6,7,NOADDR};

EnableRemote(0, addresslist);

Programming Reference Manual 4-6 GPIB-488

FindLstn

Finds all listeners on the GPIB.

Syntax

C FindLstn(int board, short addresslist[], short

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR.

limit is an integer which specifies how many address entries can be placed into the
resultlist array. Set to the size of the resultlist array.

Returns

resultlist will contain the addresses of all detected listeners. This array must be large

enough to hold all possible addresses.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

Chapter 4 GPIB 488.2 Library Reference

resultlist[], int limit)

iberr will contain an error code, if an error occurred. An ETAB (20) error indicates that more

listeners are present on the GPIB bus than limit will allow to be placed in
this case,

ibcnt contains the number of addresses actually placed in resultlist.

resultlist. In

Usage Notes

The addresses specified by addresslist are tested to see if a listening device is present. If
a listener is found at a primary address, its address is placed in

resultlist. If no listeners

are detected at a primary address, then all secondary addresses associated with that primary
address are tested. If any listeners are detected, their addresses are placed in

resultlist.

You can use this routine to determine how many devices on the network are capable of
listening. Once these devices are detected, they can be identified by their response to
identification request messages.

Example

This example verifies if listening devices are present at GPIB primary addresses 6 and 7 on
Board 0.

C short addresslist[3] = {6,7,NOADDR};

short resultlist[4];
FindLstn(0, addresslist, resultlist, 4);

GPIB-488 4-7 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

FindRQS

Identify the device requesting service.

Syntax

C FindRQS(int board, short addresslist[], short

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. The devices

located at these addresses are serial polled until the one asserting SRQ is located.

Returns

result will contain the returned status byte of the device asserting SRQ.

ibcnt will contain the index (in addresslist) identifying the device's address.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

*result)

iberr will contain an error code, if an error occurred. iberr contains the error code ETAB,

if no device is requesting service. In this case,

iberr will contain the error code EABO if a device times out while responding to its serial

poll. In this case,

ibcnt contains the index of the timed-out device.

ibcnt contains NOADDR's index.

Usage Notes

None.

Example

Identifies which of the devices at GPIB addresses 6 and 7 (connected to board 0) is requesting
service.

C

short addresslist[3] = {6,7,NOADDR};
short result;
FindRQS (0, addresslist, &result);

Programming Reference Manual 4-8 GPIB-488

PassControl

Makes another device the Active Controller.

Syntax

C PassControl(int board, short address)

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

address is an integer representing the GPIB address of the device that is to become the

controller. The low byte of the integer contains the device's primary GPIB address. The high
byte of the address contains the device's secondary GPIB address. If the device has no
secondary address, the high byte of

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Chapter 4 GPIB 488.2 Library Reference

address is 0.

Usage Notes

When this routine is executed, the GPIB Take Control (TCT) command is issued. This
forces the Active Controller to pass control to the device at the specified address. This device
must have Controller capability.

Example

This example would make the device connected to Board 0 and whose GPIB address is 6 the
Active Controller.

C PassControl(0, 6);

GPIB-488 4-9 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

Ppoll

Performs a parallel poll.

Syntax

C PPoll(int board, short *result)

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

Returns

result will contain the eight-bit result of the parallel poll. Each bit of the poll result contains

one bit of status information from each device which has been configured for parallel polls.
The value of each bit is dependent on the latest parallel poll configuration sent to the devices
through

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

PPollConfig and the individual status of the devices.

Usage notes

None.

Example

Parallel polls devices connected to board 0.

C short result;

PPoll(0, &result);

Programming Reference Manual 4-10 GPIB-488

PPollConfig

Configures a device for parallel polls.

Syntax

C PPollConfig(int board, short address, int

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

address is the address of the GPIB device to be configured for a parallel poll.

dataline specifies which data line (1-8) the device uses to respond to a parallel poll.

sense can be 1 or 0, specifying the condition under which the data line is to be

asserted/unasserted. The device compares this value to its Individual Status Bit (IST) and then
responds accordingly. For example, if
if its IST bit = 0 and unassert the data line if its IST bit = 1.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

Chapter 4 GPIB 488.2 Library Reference

dataline, int sense)

sense = 0 and the device asserts the specified data line

iberr will contain an error code, if an error occurred.

Usage notes

Remember that if a device is locally configured for a parallel poll, the Controller's parallel poll
configuration instruction is ignored.

Example

Configures the device connected to board 0 at address 6 to respond to parallel polls on line 7
with sense 1. The device asserts line 7 if its IST bit = 1, and unasserts line 7 if IST = 0.

C PPollConfig(0, 6, 7, 1)

GPIB-488 4-11 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

PPollUnconfig

Unconfigures devices for parallel polls.

Syntax

C PPollUnconfig(int board, short addresslist[])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices that do not respond to a parallel poll.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Example

Unconfigure the devices connected to board 0 and located at GPIB addresses 6 and 7.

C short addresslist[3] = {6, 7, NOADDR};

PPollUnconfig(0, addresslist);

Programming Reference Manual 4-12 GPIB-488

RcvRespMsg

Reads data from a previously addressed device.

Syntax

C RcvRespMsg(int board, char data[], long count,

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

count specifies the maximum number of data bytes which are to be read.

termination is the flag used to signal the end of data. If termination equals a value

between 0 and 00FF hex, the corresponding ASCII character is the termination character. The
read is stopped when this character is detected. If
defined in the header file), then the read is stopped when EOI is detected.

Returns

data is the string that receives the data.

Chapter 4 GPIB 488.2 Library Reference

int termination)

termination = STOPend (A constant

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

You must address the appropriate devices as Listeners/Talkers prior to calling this routine.
The input data string is not terminated with a zero byte.

Example

A previously addressed Listener receives 50 bytes of data from a previously addressed Talker.
The transmission is terminated when EOI is detected.

C char data[50];

RcvRespMsg(0, data, 50, STOPend)

GPIB-488 4-13 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

ReadStatusByte

Serial poll a single device and read its status byte.

Syntax

C ReadStatusByte(int board, int address, short

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

address is an integer representing the GPIB address of the device that is to be serial polled.

Returns

result will contain the status byte. The high byte of result is always 0.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

None.

*result)

Example

This example serial polls the device at address 2 and retrieves its status byte.

C short result;

ReadStatusByte (0, 2, &result);

Programming Reference Manual 4-14 GPIB-488

Receive

Reads data from a GPIB device.

Syntax

C Receive(int board, int address,char data[],

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

address is an integer representing the GPIB address of the device that is to be read from.

count specifies the maximum number of data bytes which are to be read.

termination is the flag used to signal the end of data. If termination equals a value

between 0 and 00FF hex, the corresponding ASCII character is the termination character. The
read is stopped when this character is detected. If
defined in the header file), then the read is stopped when EOI is detected.

Returns

data is the string that receives the data.

Chapter 4 GPIB 488.2 Library Reference

unsigned long count, int termination)

termination = STOPend (constant

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

The input data string is not terminated with a zero byte.

Example

Receive 50 bytes of data from the specified talker (device at address 2, connected to board).
EOI signals the end of the message.

C char data[50];

Receive (0, 2, data, 50, STOPend);

GPIB-488 4-15 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

ReceiveSetup

Address a GPIB Interface Board as a Listener and a GPIB device as a Talker, in preparation
for data transmission.

Syntax

C ReceiveSetup(int board, short address)

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

address is an integer representing the GPIB address of the device to send the data.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

In order to actually transfer any data, you must call a routine such as RcvRespMsg following
this routine.

This routine is useful in instances where you need to transfer multiple blocks of data between
devices. For example, you could initially address the devices using
make multiple calls of

For typical cases,

RcvRespMsg to transfer the data.

Receive is simpler to use, since it takes care of both the setup and the data

ReceiveSetup, then

transfer.

Example

This example instructs a GPIB device at address 5 to send data to GPIB Board 0. Up to 50
bytes of data is received and then stored in a string. The message is terminated with an EOI.

C char message[100];

ReceiveSetup(0, 5);
RcvRespMsg (0, message, 50, STOPend);

Programming Reference Manual 4-16 GPIB-488

ResetSys

Initializes GPIB System.

Syntax

C ResetSys(int board, short addresslist[])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices on the system to be reset.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This routine initializes the GPIB bus and all specified devices. First, the system controller
asserts the REN (Remote Enable) line and then the IFC (Interface Clear) line. This action
unlistens and untalks all of the attached GPIB devices and causes the system controller to
become the Controller-In-Charge (CIC).

Chapter 4 GPIB 488.2 Library Reference

The Device Clear (DCL) message is then sent to all of the connected devices. This forces the
devices to return to their default states and ensures that they can receive the Reset (RST)
message. A reset message (RST) is then sent to all of the devices specified by
This resets the devices to specific parameters.

addresslist.

Example

This example resets the GPIB devices connected to GPIB board 0 and assigned GPIB bus
addresses of 6 and 7.

C short addresslist[3] = {6, 7, NOADDR};

ResetSys(0, addresslist);

GPIB-488 4-17 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

Send

Sends data to one GPIB device.

Syntax

C Send (int board, short address,char data[],

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

address is an integer representing the GPIB address of the device to receive the data.

data is the string of data which is sent to the device.

count specifies the maximum number of data bytes which are to be sent to the device.

eotmode is the flag used to signal the end of data.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

long count, int eotmode)

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, the specified GPIB board is addressed as a Talker, the
designated GPIB device is addressed as a Listener and the number of bytes (specified by

count) in data is sent. Values for eotmode are:

•

NLend—Send NL (Line Feed) with EOI after last data byte.

•

DABend—Send EOI with the last data byte in the string.

•

NULLend—Do not mark the end of the transfer.

These constants are defined in the header file.

Example

In this example, GPIB board 0 sends an identification query to the GPIB device at address 3.
End of data is signalled by an EOI.

C Send (0, 3, "*IDN?", DABend)

Programming Reference Manual 4-18 GPIB-488

SendCmds

Send GPIB commands.

Syntax

C SendCmds (int board, char commands[],

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

commands is a string containing the GPIB command bytes to be sent.

count specifies the maximum number of command bytes which are to be sent.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This routine is useful in situations where specialized GPIB command sequences are called for.

Chapter 4 GPIB 488.2 Library Reference

unsigned long count)

Example

The GPIB board (at 0) simultaneously triggers the GPIB devices at addresses 8 and 9 and
quickly puts them in local mode.

C SendCmds0, "\x3F\x40\x28\x29\x04\x01",6);

GPIB-488 4-19 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

SendDataBytes

Sends data to previously addressed devices.

Syntax

C SendDataBytes(int board, char data[], long count,

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

data is the string that contains the data which is sent to the device.

count specifies the maximum number of data bytes which are to be sent to the device.

eotmode is the flag used to signal the end of data.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

int eotmode)

Usage Notes

This routine assumes that the desired GPIB listeners have already been addressed (by using

SendSetup, for example).

Val u es f o r

•

•

•

eotmode are as follows:

NLend—Send NL (Line Feed) with EOI after last data byte.

DABend—Send EOI with the last data byte in the string.

NULLend—Do not mark the end of the transfer.

These constants are defined in the header files.

Example

In this example, GPIB board 0 sends an identification query to all previously addressed
listeners. End of data is signaled by an EOI.

C SendDataBytes (0, "*IDN?", 5, DABend)

Programming Reference Manual 4-20 GPIB-488

SendIFC

Clears the GPIB bus by asserting the IFC (Interface Clear) line.

Syntax

C SendIFC(int board)

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This routine is used as part of the GPIB initialization procedure. When the system controller
asserts the IFC line, it unlistens and untalks all GPIB devices, forcing them to an idle state.
The system controller also becomes the Controller-In-Charge (CIC).

Chapter 4 GPIB 488.2 Library Reference

Example

Clears the GPIB bus from Board 0.

C SendIFC(0);

GPIB-488 4-21 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

SendList

Sends data to multiple GPIB devices.

Syntax

C SendList(int board, short addresslist[],

Parameters

board is an integer which identifies the GPIB board to use for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices on the system to reset.

data is the string containing the data to send.

count specifies the maximum number of data bytes to send to the device.

eotmode is the flag used to signal the end of data.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

char data[], long count, int eotmode)

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, the specified GPIB board is addressed as a Talker and the
designated GPIB devices as Listeners. The board then sends the given number of bytes of data
from the data string to the listening GPIB devices.

•

NLend—Send NL (Line Feed) with EOI after last data byte.

•

DABend—Send EOI with the last data byte in the string.

•

NULLend—Do not mark the end of the transfer.

These constants are defined in the header files.

Example

In this example, GPIB board 0 sends an identification query to the GPIB devices at addresses
6 and 7. End of data is signalled by an EOI.

C short addresslist[3] = {6, 7, NOADDR};

SendList (0, addresslist, "*IDN?", 5, DABend)

Programming Reference Manual 4-22 GPIB-488

SendLLO

Sends Local Lockout (LLO) message to all GPIB devices.

Syntax

C SendLLO(int board)

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, the specified GPIB board sends the GPIB Local Lockout
(LLO) message to all devices. This means that once they have been addressed as listeners, the
devices respond only to messages sent over the GPIB by the Controller. (In other words, they
can not be locally programmed from front panel controls.) Only the Controller can return
them to a local programming state.

Chapter 4 GPIB 488.2 Library Reference

Example

In this example, GPIB board 0 sends a Local Lockout to its connected GPIB devices.

C SendLLO (0);

GPIB-488 4-23 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

SendSetup

Addresses a GPIB board as a Talker and the specified GPIB devices as Listeners.

Syntax

C SendSetup(int board, short addresslist [])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to address as Listeners.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

Following this routine, you should call a routine such as SendDataBytes to actually transfer
the data.

Example

This example prepares GPIB board 0 to send data to GPIB devices 6 and 7.

C short addresslist[3] = {6, 7, NOADDR};

SendSetup(0, addresslist);

Programming Reference Manual 4-24 GPIB-488

SetRWLS

Puts all devices in Remote state with Local Lockout and addresses specified devices as
Listeners.

Syntax

C SetRWLS(int board, short addresslist [])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to be put in remote mode.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This routine puts the specified devices in remote mode with local lockout. The system
controller asserts the REN (Remote Enable) line and addresses the specified devices as
listeners. These devices can then be programmed by messages sent over the GPIB bus. (In
other words, they can not be locally programmed from front panel controls.)

Chapter 4 GPIB 488.2 Library Reference

Example

This example puts all devices controlled by GPIB board 0 into Remote mode. Devices 6 and
7 are then addressed as Listeners by the Controller.

C short addresslist[3] = {6, 7, NOADDR};

SetRWLS(0, addresslist);

GPIB-488 4-25 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

TestS RQ

Evaluate state of SRQ line.

Syntax

C TestSRQ(int board, short *result)

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

Returns

result is equal to 1 if the GPIB SRQ line is asserted. result = 0 if the GPIB SRQ line is

unasserted.

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

TestSRQ will not alter the state of the SRQ line.

Example

This example tests to see if SRQ is asserted.

C Short result;

TestSRQ (0, &result);
if (result == 1)

{ /* SRQ is asserted */}
else

{ /* No SRQ at this time */}

Programming Reference Manual 4-26 GPIB-488

TestS ys

Activate self-test procedures of specified devices.

Syntax

C SendSetup(int board, short addresslist [],

Parameters

board is an integer which identifies the GPIB board to use for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to perform self-tests.

Returns

resultlist is an array which contains the results of each device's self-test procedure.

According to the IEEE-488.2 standard, a result code of 0 indicates the device passed its test.
Any other value indicates an error.

ibcnt will contain the number of devices which failed their tests.

Chapter 4 GPIB 488.2 Library Reference

short resultlist[])

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When this routine is executed, all of the devices identified within the addresslist array are
concurrently sent a message which directs them to perform their self-test procedures. Each
device returns an integer code indicating the results of its tests. This code is placed into the
corresponding element of the

resultlist array.

Example

This example tells the devices at addresses 6 and 7 (from Board 0) to perform thier self-test
procedures.

C short addresslist[3] = {6, 7, NOADDR};

short resultlist[2];
TestSys(0, addresslist, resultlist);

GPIB-488 4-27 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

Trigg er

Triggers one device.

Syntax

C Trigger(int board, short address)

Parameters

board is an integer which identifies the GPIB board to used for this operation. In most

applications, this value is 0.

address is an integer representing the GPIB address of the device to trigger. If
address = NOADDR then all Listeners already addressed are triggered.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

When this call is executed, the GPIB GET (Group Execute Trigger) message is sent to the
specified device.

To trigger several GPIB devices, use

TriggerList.

Example

This example triggers a device connected to board 0 whose primary GPIB address is 6 and
secondary address is 12.

C Trigger (0, MakeAddr (6, 12));

Programming Reference Manual 4-28 GPIB-488

TriggerList

Triggers multiple GPIB devices

Syntax

C void TriggerList(int board, int addresslist[])

Parameters

board is an integer which identifies the GPIB board to be used for this operation. In most

applications, this value is 0.

addresslist is an array of GPIB addresses, terminated by the value NOADDR. These

addresses identify the devices to be triggered. If this array contains only
previously addressed listeners are triggered.

Returns

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

Use Trigger to trigger only one device.

Chapter 4 GPIB 488.2 Library Reference

NOADDR, all

Example

This example triggers two devices simultanously. The devices are connected to board 0 and
are at GPIB addresses 6 and 7.

C short addresslist[3] = {6, 7, NOADDR};

TriggerList(0, addresslist);

GPIB-488 4-29 Programming Reference Manual

Chapter 4 GPIB 488.2 Library Reference

WaitSRQ

Wait until a device asserts SRQ.

Syntax

C WaitSRQ(int board, short *result)

Parameters

board is an integer which identifies the GPIB board to use for this operation. In most

applications, this value is 0.

Returns

result indicates whether or not an SRQ occurred. If an SRQ occurs before the timeout

expires,

ibsta will contain a 16-bit status word as described in Appendix B, IBSTA.

iberr will contain an error code, if an error occurred.

Usage Notes

This call suspends operation until a device requests service or a timeout occurs. Follow this
call with a

result = 1. Otherwise, result = 0.

FindRQS call to determine which device needs service.

Example

Wait for a GPIB device to request service and then ascertain if device 6 or 7 requires service.

C short addresslist[3] = {6,7,NOADDR};

short resultlist[3];
short result;
WaitSRQ (0,&result);
if (result == 1)

{FindSRQ (0, addresslist, resultlist)}

Programming Reference Manual 4-30 GPIB-488

A

Multiline Interface Messages

Table A-1. Multiline Interface Messages (Hex 00-3F)

HEX DEC ASCII MSG HEX DEC ASCII MSG

00 0 NUL 20 32 SP MLA0

01 1 SOH GTL 21 33 ! MLA1

02 2 STX 22 34 “ MLA2

03 3 ETX 23 35 # MLA3

04 4 EOT SDC 24 36 $ MLA4

05 5 ENQ PPC 25 37 % MLA5

06 6 ACK 26 38 & MLA6

07 7 BEL 27 39 ‘ MLA7

08 8 BS GET 28 40 ( MLA8

09 9 HT TCT 29 41 ) MLA9

0A 10 LF 2A 42 * MLA10

0B 11 VT 2B 43 + MLA11

0C 12 FF 2C 44 ‘ MLA12

0D 13 CR 2D 45 - MLA13

0E 14 SO 2E 46 > MLA14

0F 15 SI 2F 47 / MLA15

10 16 DLE 30 48 0 MLA16

11 17 DC1 LLO 31 49 1 MLA17

12 18 DC2 32 50 2 MLA18

13 19 DC3 33 51 3 MLA19

14 20 DC4 DCL 34 52 4 MLA20

GPIB-488 A-1 Programming Reference Manual

Appendix A Multiline Interface Messages

Table A-1. Multiline Interface Messages (Hex 00-3F) (Continued)

HEX DEC ASCII MSG HEX DEC ASCII MSG

15 21 NAK PPU 35 53 5 MLA21

16 22 SYN 36 54 6 MLA22

17 23 ETB 37 55 7 MLA23

18 24 CAN SPE 38 56 8 MLA24

19 25 EM SPD39 39 57 9 MLA25

1A 26 SUB 3A 58 : MLA26

1B 27 ESC 3B 59 ; MLA27

1C 28 FS 3C 60 < MLA28

1D 29 GS 3D 61 = MLA29

1E 30 RS 3E 62 > MLA30

1F 31 US 3F 63 ? UNL

Table A-2. Multiline Interface Messages (Hex 40-7F)

HEX DEC ASCII MSG HEX DEC ASCII MSG

40 64 @ MTA0 60 96 ‘ MSA0,P

PE

41 65 A MTA1 61 97 a MSA1,P

PE

42 66 B MTA2 62 98 b MSA2,P

PE

43 67 C MTA3 63 99 c MSA3,P

PE

44 68 D MTA4 64 100 d MSA4,P

PE

45 69 E MTA5 65 101 e MSA5,P

PE

46 70 F MTA6 66 102 f MSA6,P

PE

Programming Reference Manual A-2 GPIB-488