PTFIND (3X)

NAME

ptfind - Find a physical terminal within a group

SYNOPSIS

#include         <zcom/zcomsys.h>
#include         <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 ptfind (zap, zskeyp, ibuf, len)
 
zaddr_type       *zap;
zskey_type       *zskeyp;
zptt_type        *zptt;
int32            len;

DESCRIPTION

Routine ptfind provides special methods of accessing terminals on the same MUX and port. The zap->zlu parameter is the ZLU of a terminal on a particular MUX and port.

Physical terminals that are associated with the same port are called a physical terminal group. They are linked together to form a circular list via the ptpzlk and ptlist fields in the physical terminal table. This routine provides a method to efficiently search through a group.

This routine provides three methods of finding a particular physical terminal table entry (and relative terminal number) on the same MUX and port as the ZLU given (zap->zlu) in the first parameter.

Method 1: Retrieve the terminal associated with a specific MUX, port, and terminal number.

In the ZCOM subsystem, every physical terminal belongs to a single MUX and PORT and is assigned a TERM (terminal) number, which is unique within that port. Hence, by specifying these three numbers, a single physical terminal table may be retrieved. The TERM number is assigned by TTGEN during configuration file compilation and kept in the ptterm field of the physical terminal table.

This method is used usually when the MUX, PORT, and TERM are known. An example is in retrieving a previously accessed physical terminal table.

Method 2: Retrieve the next terminal whose table has a sequence of matching bytes.

This method compares the contents of the physical terminal tables within a group, and locates the one that matches a byte sequence. In addition to the data buffer, table location and number of bytes to be compared, the caller also specifies a terminal ZLU within the group to be searched.

In order to make it easier to handle multiple matches in a group, the search starts from the next terminal following the specified ZLU. Hence, a returned terminal ZLU may be used in the next ptfind call to locate the next matching terminal. In this case, the whole group is searched if a terminal is returned the second time.

Method 3: Retrieve the next terminal whose table has a sequence of matching bit patterns.

This mode is similar to Method 2 except that the caller also specifies a mask buffer, which is used to mask some unused bits in the physical terminal table before comparing with the specified data.

The mask buffer is AND'ed with the table content before comparison. Hence, the mask buffer should contain zeros for those unused bits and ones for those bits to be compared. The data buffer should have zeros for those unused bits, 0 or 1 for the bits to be compared.

Similarly, the search starts from the next terminal after the specified ZLU. (In fact, method 2 may be treated as a special case of this, if the mask buffer contains all ones.)

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:

PARAMETERS

RETURN VALUE

Routine ptfind returns 0 if successful. Otherwise, if the physical terminal is not found, ZENOTM (-75) is returned.

EXAMPLE

#include        <zcom/zcomsys.h>
#include        <zcom/zcomcall.h>
 
int32          ierr;
zaddr_type     zaddr;
zskey_type     zskey;
zptt_type      zptt;
int32          len;
 
if (ierr = ptfind (&zaddr,  &zskey, &zptt, len)) {
           /* error return code */
}
else {
           /* good return code */
}

FILES