ZX25L2STAT_RCVR (3X) — ACC X.25

NAME

zx25l2stat_rcvr - Setup receiver for X.25 link status messages

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomx25.h>
 
int zx25l2stat_rcvr (zxip, action, lzap, pzap)
 
zx25info_type     *zxip;
int               action;
zaddr_type        *lzap;
zaddr_type        *pzap;

DESCRIPTION

The zx25l2stat_rcvr routine is used to add or remove the primary or shared receiver for X.25 Link unsolicited status messages. There can be only one primary X.25 link status receiver. If more than one request is issued to add a primary receiver, the last one issued takes precedence.

If more than one application program needs to receive the X.25 link status messages, the application should set itself up as a shared receiver. Any number of applications may request X.25 link status messages as a shared receiver.

Once this routine has been successfully called, X.25 link status messages will continue to be queued on the application program ZLU specified in pzap until another zx25l2stat_rcvr is issued to remove the program ZLU as a receiver of Link status messages. The status messages are retrieved using the zread() routine.

An application program can indicate that it no longer wishes to receive X.25 link status messages by issuing a zx25l2stat_rcvr() call with the same parameters as the specified in the original zx25l2stat_rcvr() request, and setting the action parameter to ZcDEL_PRIMARY or ZcDEL_SHARED.

Note that extreme care must be taken to make sure the application removes itself as a receiver of X.25 link status messages before the application program terminates. Failure to perform this action could cause the ZCOM subsystem to run out of buffer space. That is, the link status messages would continue to be sent to the program's input queue even though the program is no longer running.

The libraries libzx25.a, libzcom_c.a and libpthread.a must be linked into the calling program by giving the "-lzx25 -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. It has the following characteristics when called by multi-threaded applications:

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

PARAMETERS:

RETURN VALUE

Routine zx25l2stat_rcvr returns a 0 when successful. If there was a ZCOM error, it returns a negative value. See /opt/acc/include/zcom/zcomsys.h for the list of ZCOM error codes and their meanings. If zx25l2stat_rcvr, itself, failed, one of the following positive error codes is returned:

NOTES

The calling program (or thread) must call zx25info before calling this routine. In a multi-threaded application, each thread must make a separate call to zx25info using a per-thread ZCOM X.25 access data buffer zxip. The per-thread data buffer can then be used to call this routine.

EXAMPLE

#include    <zcom/zcomsys.h>
#include    <zcom/zcomx25.h>
 
int             ierr;
zx25info_type   zxi;
zaddr_type      lzaddr;
zaddr_type      pzaddr;
 
/* Allocate our primary program ZLU.  */
   if (ierr = zopen (&pzaddr, 1, "myprgrm", 0)) exit (ierr);
 
/* Issue the prerequisite zx25info() call.  */
if (ierr = zx25info (&zxi, "auxprog")) exit (ierr);
 
/* User written routine to find X.25 link ZLU.  Returns its address. */
if (ierr = Get_Link_ZLU(&lzaddr)) exit (ierr);
 
/* Tell ZCOM to send X.25 link status to our application. */
if (ierr = zx25l2stat_rcvr (&zxi, Zc_ADD_PRIMARY, &lzaddr, &pzaddr)) {
    /* error return code */
}
else {
/* good return code */
}
 
/* This code disables X.25 link status messages. */
if (ierr = zx25l2stat_rcvr (&zxi, Zc_DEL_PRIMARY, &lzaddr, &pzaddr)) {
    /* error return code */
}
else {
    /* good return code */
}

FILES

SEE ALSO

zx25info(3x), zopen(3x), zread(3x), zset_rcvr(3x)