ZRNTIMER (3X)

NAME

zrntimer - Set timeout for remote node access

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 zrntimer (node, time)
 
int32       node;
int32       time;

DESCRIPTION

Routine zrntimer is used to change the ZCOM request timeout value for requests sent to a remote ZCOM system node. The new timeout only affects the calling program, and is effective for all subsequent requests for that node until another zrntimer call changes the timeout or whenever the program is restarted. In the latter case, the timeout is reset to the default value as defined in the TTGEN configuration file.

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	It has no cancellation point and does not call any function with cancellation point. Thread cancellation will not occur when a thread is calling 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

node	Remote node number where timeout is set. A value of zero means setting the timeout values for ALL remote nodes.
time	Timeout value in seconds (1-65535). Zero or negative values are not allowed.

RETURN VAULE

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

Setting the timeout value for the local node will complete without error. However, the timeout value will have no effect because ZCOM does not timeout local requests (i.e. a program may be suspended forever in order to complete its local request).

An internal table is maintained to keep track of the timeout values for each remote node. The table is initialized with the default values defined in the TTGEN configuration file. If an unknown node number is specified, it is rejected with error -6 (ZENODE).

In a multi-threaded application, all the threads share the single timeout value table. Hence, when a thread sets a node timeout value, the new value will be effective in all the other threads.

Although a timeout value of one (1) is a legal value, a minimum value of two (2) is used in order to avoid false alarms because the internal timeout processing is activated on 1-second intervals.

EXAMPLE

#include      <zcom/zcomsys.h>
#include      <zcom/zcomcall.h>
 
int32         ierr;
int32         node;
int32         time;
 
if (ierr = zrntimer (node, time)) {
       /* 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).