ZSETQL (3X)

NAME

zsetql - Set buffer queue limit

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 zsetql (zap, mode, qnum, limit)
 
zaddr_type        *zap; 
uint32            mode;
uint32            qnum;
uint32            limit;

DESCRIPTION

Routine zsetql changes the pre-set queue limit of a buffer queue (the pre-set value is configured in the TTGEN configuration file). This allows the caller to adjust the input/output characteristics of some of the ZLUs in the ZCOM subsystem without restarting the ZCOM subsystem or affecting other ZLUs.

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.
mode	Type of queue:
	ZcPROGRAM_Q	(0) - Program input queue
	ZcLOGICAL_TERM_Q	(1) - Logical terminal queue
	ZcPHYSICAL_TERM_Q	(2) - Physical terminal queue
	If bit ZCOM_QLIM_MFLAG (0x8000) is set, the queue is changed to use a message limit. If bit ZCOM_QLIM_BFLAG (0x4000) is set, the queue is changed to use a byte limit. If neither are set, the limit mode is unchanged. They should not be set together.
qnum	Queue number. Depending on mode, it specifies which queue to set:
	mode 0 -	(ZcPROGRAM_Q) qnum parameter not used
	mode 1 -	(ZcLOGICAL_TERM_Q) Data queue number
		0 = Sub-packet holding queue
		1 = Data holding queue A
		2 = Data holding queue B, etc.
	mode 2 -	(ZcPHYSICAL_TERM_Q) Data queue number
		0 = High priority transmit queue
		1 = Low priority transmit queue
		2 = Unacknowledged transmit queue
		3 = Express transmit queue
limit		New queue limit. Allowable range is 0 to ZCOM_MAXQLIM (0x7FFFFFFF).

RETURN VALUE

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

NOTES

Queue limit does not affect data messages that are already in a queue. If the new limit is below the amount of queued data, no new data is accepted until the queued data drops below the limit. Setting a queue limit to zero will prevent the queue from accepting new messages. The queue is still readable, but new data can't be added to the queue.
Under the current implementation, the terminal unacknowledged queue uses a "byte limit", i.e. the limit for this queue indicates the maximum number of bytes allowed on the queue. The other queues use a "message limit", which means the maximum number of messages allowed on the queue. However, the limit type may be changed by setting the ZCOM_QLIM_MFLAG or ZCOM_QLIM_BFLAG bit in the mode parameter.
The system initializes the express transmit queue (mode 2, qnum 3) with the maximum limit (0x7FFFFFFF). A low limit may affect critical data getting to the interface card and result in terminal control problems. Therefore, it is strongly recommended that the limit not be changed unless it is absolutely necessary. With some protocol options (e.g. X.25), changing this limit is unsupported!

EXAMPLE

#include <zcom/zcomsys.h>
#include <zcom/zcomcall.h> 
 
int32       ierr;
zaddr_type  zaddr;
uint32      mode;
uint32      qnum;
uint32      limit;
 
if (ierr = zsetql (&zaddr, mode, qnum, limit)) {
   /* 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).