LTQDGET (3X)

NAME

ltqdget - Retrieve data buffer in terminal data queue

SYNOPSIS

#include       <zcom/zcomsys.h>
#include       <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 ltqdget (zap, queue, ibuf, len, rlenp)
 
zaddr_type     *zap;
uint32         queue;
char           *ibuf;
int32          len;
int32          *rlenp;

DESCRIPTION

Routine ltqdget retrieves the data message stored in the data queue of the logical terminal tables. It returns the first message in the specified queue and releases the buffers back to the ZCOM subsystem free data buffer pool. See the man page for ltqdput on how to store a message in the data queue.

The data queue is designed to store a relatively large or unpredictable amount of terminal data in a FIFO order. When compared to logical data storage (refer to zltstore and zltup), the data queues allow terminal data to be stored dynamically, that is, memory is used only when data is stored. However, it is penalized by incurring more processing overhead in data update and retrieval. In addition, access is restricted to a FIFO order.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" to cc(1) or ld(1).

Threads Considerations

This routine may be called from a multi-threaded application using the POSIX (1003.1c) kernel threads API package. This routine has the following characteristics when called by a multi-threaded application:

cancellation point	Thread cancellation can occur when a thread calls this routine.
async-cancel unsafe	The calling thread's cancelability type must be PTHREAD_CANCEL_DEFERRED if cancellation is enabled.
async-signal unsafe	It cannot be called from a signal handler.
fork unsafe	It cannot be called by a child process after fork(2) but before exec(2).

PARAMETERS

zap	ZCOM address of a terminal from which to get the data.
queue	Terminal data queue number (specifies which data queue is to be used).
	0 - Sub-packet holding queue (reserved) 1 - Data holding queue A 2 - Data holding queue B 3 - Data holding queue C 4 - Data holding queue D
ibuf (Return Param)	On a successful return, the data is placed into this buffer.
len	Length in bytes of ibuf.
rlenp (Return Param)	Actual number of bytes returned in ibuf.

NOTES

Normally, the data queue number used should be allocated by ZMON (see the zltqueue man page for how to get a data queue number). There is no queue ownership validation within this routine; it is up to the user to make sure that the queue usage is valid and consistent.

RETURN VALUE

Routine ltqdget returns 0 if successful. Otherwise, a non-zero error code is returned. See /opt/acc/include/zcom/zcomsys.h for the list of ZCOM error codes and their meanings.

If the specified queue is empty, then the ZENODATA error (-24) is returned and ibuf contains invalid data.

EXAMPLE

#include    <zcom/zcomsys.h>
#include    <zcom/zcomcall.h>
 
int32        ierr;
zaddr_type   zaddr;
uint32       queue;
char         ibuf[size];  /*Where size is user-determined; must be >= len */
int32        len;
int32        rlen;
       
if (ierr = ltqdget (&zaddr, queue, ibuf, len, &rlen)) {
      /* error return code */
}
else {
      /* good return code */
}

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files.
/opt/acc/include/zcom/zcomcall.h	ZCOM routine function prototypes (requires ANSI C compilation).