LTFIND (3X)

NAME

ltfind - Find specific logical terminal in a group

SYNOPSIS

#include         <zcom/zcomsys.h>
#include         <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 ltfind (zap, laddr, llen, ibuf, len)
 
zaddr_type       *zap;
char             *laddr;
int32            llen;
char             *ibuf;
int32            len;

DESCRIPTION

Routine ltfind searches through the group linkage in the logical terminal table, for the logical terminal with the specified logical address.

Group linkages are set up by TTGEN to form a circular list of logical terminals that are associated with the same physical terminal table. The linkages and logical addresses are defined using the PTERM and LTERM statements in the TTGEN configuration file.

Typically, these linkages are used in a multiplexing environment: a lower level protocol receives multiplexed messages, which contain ID codes for a higher level protocol to further differentiate the data messages. In such cases, the logical terminals may have unique ID codes as their logical addresses, and ltfind is used to locate a logical terminal ZLU with a specified ID code.

Normally, the logical addresses (maximum of 10-bytes) of a group of logical terminals should be unique within that group.

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).

PARAMETERS

zap	ZCOM address of a terminal in the multiplexed group.
laddr	Logical address with which to compare.
llen	Length in bytes of laddr. A maximum of 10 bytes/characters of laddr will be used, even if a number greater than 10 is specified in llen.
ibuf (Return Param)	Logical terminal table. Note that if the logical terminal is not found, ibuf will not contain valid data.
len	Length in bytes of ibuf.

RETURN VALUE

Routine ltfind 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. If the logical terminal is not found, ZENOTM (-75) is returned.

NOTES

The returned logical terminal table consists of the basic table and the logical terminal table extension (the extension size is configurable in the TTGEN configuration file). The size of this buffer should be large enough to hold the information required from the LTT. An example of defining a buffer of sufficient size would be:

struct {
   zltt_type   sys;
   char         ext[ZCOM_MAXLSIZE];  /* Max allowable extension */
ltt;

For example, to access the fields:

ltt.sys.ltname	gives the terminal name
ltt.ext[0]	gives the 1st byte in table extension

This allows &ltt to be used instead of ibuf in the ltfind call.

EXAMPLE

#include        <zcom/zcomsys.h>
#include        <zcom/zcomcall.h> 
    
int32      ierr;
zaddr_type zaddr;
char       laddr[10];
int32      llen;
char       ibuf[size]; /* where size is user-determined; must be >= len */
int32      len;
 
        if (ierr = ltfind (&zaddr, laddr, llen, ibuf, len)) {
           /* 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).