ZLTQUEUE (3X)

NAME

zltqueue - Logical data queue allocation

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compliled with ANSI C (recommended) */
 
int32      zltqueue (appln, label, queuep)
 
uint32     appln;
char       *label;
uint32     *queuep;

DESCRIPTION

Routine zltqueue requests a data queue in the logical terminal tables for terminals of a specific application number. There is currently a maximum of 4 queues. Each queue is identified by the terminal application group and a user-defined label. The returned queue number (on successful completion) could then be used in subsequent data storing and retrieval calls (ltqdput and ltqdget).

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

appln	Application number of terminal group.
label	Queue label name.
queuep (Return Param)	Data queue number (or ZCOM error, if negative)

NOTES

The data queue returned should only be used for terminals within the specified application group (there is NO queue ownership validation when it is used in ltqdget and ltqdput). An application value of zero means terminals in ALL application groups. This zero application value allows the queue to be used to store global data for all terminals in the system.

Routine zltqueue returns an already assigned queue if the queue label matches a previously assigned queue (in this case the specified application number is not used or validated). This provides a facility to share a data queue between different programs and enables program restartability.

The following example illustrates the queue allocation algorithm:

Appln Program	Appln Nmbr	Appln Label	Queue Queue No.	Returned
A	30	USAGE1	1	<-- first allocation
B	0	GLOBAL	2	<-- global allocation
C	40	CCCCCC	1	<-- different appln group
D	30	USAGE2	3	<-- same appln, diff usage
E	30	USAGE1	1	<-- data queue sharing
F	30	USAGE3	4	<-- same appln, diff usage
G	30	USAGE4	error	<-- no more queues for apln 30

Queues 1, 3, and 4 are allocated for application 30, and queue 2 is allocated for global usage in program B. Thus, because there is a current limit of four queues, an error is returned to program G when it attempts to allocate another queue to application 30.

RETURN VALUE

Routine zltqueue 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.

EXAMPLE

#include     <zcom/zcomsys.h>
#include     <zcom/zcomcall.h>
 
int32          ierr;
uint32         appln;
char           label[6];
uint32         queue
 
if (ierr = zltqueue (appln, label, &queue)) {
       /* error return code */
}
else {
       /* good return code */
}

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM subsystem 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).