gpib_read(3) CLIX gpib_read(3)
NAME
gpib_read, gpib_read_nw - Reads data from a GPIB device
LIBRARY
Intergraph Device Library (libix.a)
SYNOPSIS
#include <sys/xio/xio.h>
#include <sys/xio/xerr.h>
int gpib_read(
int channel ,
char *tdev ,
int tcnt ,
char *dbuf ,
int dcnt ,
int timeout ,
char *eoi ,
int *xfcnt );
int gpib_read_nw(
int channel ,
char *tdev ,
int tcnt ,
char *dbuf ,
int dcnt ,
int timeout ,
char *eoi ,
struct xiosb *xiosb ,
int efn );
PARAMETERS
channel Represents a channel.
tdev Points to the primary device from which to read.
tcnt Specifies an initialization flag.
dbuf Points to the buffer to receive the data.
dcnt Specifies the size of the receiving buffer.
timeout Specifies the number of 1/60 second intervals to wait before
aborting a request.
eoi Points to a status condition.
2/94 - Intergraph Corporation 1
gpib_read(3) CLIX gpib_read(3)
xiosb Points to the IO status buffer.
efn Specifies the event flag number.
DESCRIPTION
The gpib_read() function allows data to be received from a General Purpose
Interface Bus (GPIB) device on channel. The primary address from which to
read is pointed to by tdev.
Setting tcnt to 1 will initialize the specified GPIB device as a talker
before the data transfer begins. Setting tcnt to 0 indicates the device
has already been addressed to talk by a previous gpib_read(), and no
device initialization will occur.
The dbuf parameter is a pointer to the buffer to receive the data. The
size of the buffer is specified (in bytes) by dcnt.
If an abort timeout is desired, timeout contains the number of 1/60 second
intervals the driver waits before aborting the request. A value of 0
disables the timeout mechanism.
The address pointed to by eoi is updated with a nonzero value if the GPIB
End Or Identify (EOI) condition was active upon completion. Conversely, a
value of 0 indicates a deasserted EOI signal upon reception of the last
data byte. If the driver detects an EOI condition before dcnt bytes are
transferred to the buffer, the eoi status location is nonzero, and a
successful completion status is returned.
Upon completion of the synchronous request, the integer pointed to by
xfcnt contains the number of bytes transferred to dbuf.
The gpib_read_nw() function is the asynchronous version of gpib_read(),
providing the same capability without waiting for completion of the
request. The efn parameter is the event flag number associated with the
request. The xiosb parameter is a pointer to the xiosb structure updated
upon completion of the request. (See intro(3).) The xfcnt member of the
xiosb structure indicates the number of bytes transferred to dbuf.
If a primary address is specified, the controller is put in an active
state, and the following GPIB messages are sent over the specified
channel.
UNL Unlisten
UNT Untalk
MTA My Talk Address
LAG Listen Group Address
2 Intergraph Corporation - 2/94
gpib_read(3) CLIX gpib_read(3)
The system controller is forced to the standby state, and data is read
from the channel until dcnt bytes are received or the EOI condition is
detected. If a primary address is not specified (tcnt is 0), the system
controller is put in a standby state, and the read proceeds as described.
EXAMPLES
To initiate a 32 kilobyte read of GPIB device 4:
tcnt = 1;
tdev = 4;
dcnt = 32 * 1024;
if (status = gpib_read(channel, &tdev, tcnt,
dbuf, dcnt, timeout, &eoi, &xfcnt)) {
fprintf(stderr, "gpib_read: failed, %d\n", status);
return(-1);
}
if (xfcnt != dcnt)
fprintf(stdout, "gpib_read: truncated, %d\n", xfcnt);
else
fprintf(stdout, "gpib_read: succeeded\n");
if (eoi)
fprintf(stdout, "gpib_read: EOI received\n");
RETURN VALUES
Upon successful completion of the synchronous request, a value of 0 is
returned. Otherwise, one of the failure codes listed in the ERRORS
section is returned.
If the asynchronous request is accepted by the XIO system, a value of 0
will be returned by the request. Otherwise, XIO_FAILURE will be returned.
Upon completion of an accepted request, the status member of the xiosb
structure will be set to 0 if successful, or to one of the failure codes
listed in the ERRORS section, if unsuccessful.
ERRORS
The gpib_read() and gpib_read_nw() functions fail if one of the following
is true:
[XIO_FAILURE]
The system does not contain the driver needed to support this
request or efn is invalid.
[GPIB_OUT_OF_RANGE]
The specified channel is beyond the maximum allowed.
[GPIB_NOT_OPEN]
The specified channel is not open.
2/94 - Intergraph Corporation 3
gpib_read(3) CLIX gpib_read(3)
[GPIB_NOT_OWNER]
The specified channel is currently open by another process.
[GPIB_CANCELED]
The current request was canceled by gpib_cancel().
[GPIB_DEVICE_INVALID]
The specified device's primary address was not correct.
[GPIB_TIMEOUT]
A timeout occurred before the request completed.
[GPIB_HARDWARE_CHECK]
A hardware error was detected during the request.
[BAD_DATA_BUFFER_ADDRESS]
Either tdev points to an invalid memory address, or eoi, xfcnt, or
dbuf points to a nonwritable memory space.
[BAD_DATA_BUFFER_SIZE]
The data transfer size dcnt is too large.
RELATED INFORMATION
Functions: intro(3), gpib_open(3), gpib_cmd(3), gpib_cancel(3)
Files: xgpib(7)
4 Intergraph Corporation - 2/94