ZINIT (3X)

NAME

zinit - ZCOM routine initialization

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 zinit      (sip)
zsinfo_type       *sip;

DESCRIPTION

Routine zinit initializes the access to the ZCOM system and sets up the global variables for use by the other ZCOM routines. Therefore, it must be called before any other ZCOM routines are used. This routine also returns some ZCOM system information. Since not every application programs require this information, so after the zinit call the buffer may be reused for other purposes.

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:

not a cancellation point	Thread cancellation will not occur when a thread is calling this routine.
async-cancel safe	The calling thread’s cancelability type may be deferred or asynchronous when calling this routine.
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

sip (Return Param) ZCOM system information data structure containing the following fields:

sizrev	ZCOM software revision code (4 digits).
sinode	ZCOM system local node number.
sinzlu	Total number of ZLU tables in the ZCOM system.
sinltt	Total number of Logical Terminal Tables in the ZCOM system.
sinptt	Total number of Physical Terminal Tables in the ZCOM system.
sinift	Total number of Interface Tables in the ZCOM system.
sintzlu	Total number of terminal ZLUs in the ZCOM system.
siszlu1	First program ZLU in the ZLU table.
sipqlim	Default program ZLU queue limit.
siltsze	Size (in bytes) of the Logical Terminal Table (LTT).
sispare	Reserved for future use.

NOTES

If the calling program has already opened a primary ZLU, the primary ZLU will be reset after calling zinit: the ZLU remains open and its contents is not disturbed, but it stops being the ‘primary’ ZLU of the calling program. The calling program will no longer have a primary ZLU and need to call zopen to open a primary ZLU again (usually with the same name, hence the same ZLU will be opened). The other opened ZLUs are not affected by calling zinit. See zopen(3X) for more information about the primary ZLU.
The zinit routine will reset the node timeouts to the default values. Hence, any user specified node timeout must be set again after calling zinit. See zrntimer(3X) for more information.
In a multi-threaded application, this routine is to be called only once by any one of the threads. Once zinit returns successfully, the necessary initialization tasks are completed for all threads, and all subsequent calls to ZCOM APIs will be allowed. There is no need for the other running threads or the newly created threads to call this routine again. Usually, zinit is to be called during the main program’s initialization phase, before any threads are generated.
In a multi-threaded application, if this routine is called the second time by a thread while some ZCOM APIs are in-progress in the other threads, the access to the ZCOM system will be re-initialized. The in-progress APIs will detect this and ‘retry’ internally. This is handled automatically and is transparent to the application.

RETURN VALUE

Routine zinit 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;
zsinfo_type   sip;
 
if (ierr = zinit (&sip)) {
          /* 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).