ZOPEN (3X)

NAME

zopen - Create ZLU program input queue

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 zopen (zap, pflag, name, limit)
 
zaddr_type       *zap; 
uint32           pflag;
char             *name;
uint32           limit;

DESCRIPTION

Routine zopen allocates a free ZLU as a program input queue. This must be done before a program may receive any messages from terminals or other programs. The calling program's PID is put into the zowner field of the zlu_type structure.

If a calling program (or thread) terminates without doing a zclos(3X) of a ZLU, that ZLU and its resources will remain allocated in the ZCOM system. When the program (or thread) is restarted later on, that ZLU can be re-opened (using the same name parameter) without losing its queue contents. The program (or thread) can re-use the ZLU and resume its processing from where it left off. To flush the contents of a re-opened ZLU, use the zqmve(3X) routine after the ZLU is opened.

If it is not desirable to re-use an existing ZLU, the ZCOM_ZOPEN_NEW bit of pflag can be set. In this case, if the ZLU name already exists, the ZLU is not re-opened and error ZENAME (-11) is returned.

A ZLU can be defined either as a primary or an auxiliary ZLU. Auxiliary ZLUs are used, for example, when a program is receiving messages from multiple sources, so that the messages can be read in a different order from which they were received. All programs must have a primary ZLU defined, because all status messages are returned to the primary ZLU.

In addition, a program's primary ZLU is used as the source ZLU for messages sent by that program (unless overridden by a different ZLU specified in the message header). Refer to the zsend(3X) routine for details.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" options 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).

See the NOTES section below for more information on using this routine in a multi-threaded application.

PARAMETERS

zap (Return Param)	ZCOM address (node, ZLU number, and checksum). Node contains the local node as defined in the TTGEN configuration file.
pflag	Set to ZcPRIMARY_ZLU(1) if this ZLU is to be primary ZLU for this program. Any other value (ZcAUXILIARY_ZLU) defines it as an auxiliary ZLU. Bit ZCOM_ZOPEN_NEW (0x8000) tells the routine to return an error if we are using an existing ZLU.
name	Name to be given to the opened ZLU. The name must be unique within the local node ZLU table. The name may be a maximum of 7 characters long, and must be null-terminated.
limit	Queue size limit. If 0 is specified, then the default queue size limit (defined in the TTGEN configuration file) is used.

RETURN VALUE

Routine zopen 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

The first zopen call that a program makes will define the primary ZLU irrespective of the value of pflag. If a subsequent zopen call is made with pflag=1, the primary ZLU definition will be overridden. If multiple zopen calls are made with pflag=1, then each call will override the previous definition, leaving the primary ZLU defined as the one allocated in the last zopen call. It is a good practice to define the primary ZLU in the first call to zopen and not to redefine it unless the application program has a good reason for doing so.

In a multi-threaded application, the primary ZLU is shared globally. If a thread opens a primary ZLU, it is effective for all threads.

Routine zopen can only allocate a program input ZLU within the local node. The zaddr parameter in the call is a return parameter only and contains the number of the local node as well as the ZLU and checksum.

EXAMPLE

#include     <zcom/zcomsys.h>
#include     <zcom/zcomcall.h> 
 
int32            ierr;
zaddr_type       zaddr;
uint32           pflag;
char             name[8];
uint32           limit;
 
if (ierr = zopen (&zaddr, pflag, name, 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).