4.1 Joining an Application

Before an ATMI client can perform any service request, it must join the Oracle Tuxedo ATMI application, either explicitly or implicitly. Once the client has joined the application, it can initiate requests and receive replies.

A client joins an application explicitly by calling the tpinit(3c) function with the following signature:

int
tpinit (TPINIT *tpinfo)

A client joins an application implicitly by issuing a service request (or any ATMI function) without first calling the tpinit()function. In this case, the tpinit() function is called by the Oracle Tuxedo system on behalf of the client with the tpinfo argument set to NULL. The tpinfo argument points to a typed buffer with a TPINIT type and NULL subtype. The TPINIT typed buffer is defined in the atmi.h header file and includes the following information:

char usrname[MAXTIDENT+2];
char cltname[MAXTIDENT+2];
char passwd[MAXTIDENT+2];
char grpname[MAXTIDENT+2];
long flags;
long datalen;
long data;

The following table summarizes the TPINIT data structure fields.

Table 4-1 TPINIT Data Structure Fields

Field	Description
usrname	Name representing the client; used for both broadcast notification and administrative statistics retrieval. The client assigns a value to usrname during the call to the tpinit() function. The value is a string of up to MAXTIDENT characters (which is defined as 30), and must be terminated by NULL.
cltname	Client name with application-defined semantics: a 30-character NULL-terminated string used for both broadcast notification and administrative statistics retrieval. The client assigns a value to cltname during the call to the tpinit() function. The value is a string of up to MAXTIDENT characters (which is defined as 30), and must be terminated by NULL. Note: The value sysclient is reserved for the cltname field.
passwd	Application password in unencrypted format. Used for user authentication. The value is a string of up to 30 characters.
grpname	Associates client with resource manager group. If set to a 0-length string, the client is not associated with a resource manager and is in the default client group. The value of grpname must be the NULL string (0-length string) for Workstation clients. Refer to Using the ATMI Workstation Component for more information on Workstation clients.
flags	Indicates both the client-specific notification mechanism and the mode of system access. Controls both multicontext and single-context modes. Refer to Unsolicited Notification Handling or tpinit() in the Oracle Tuxedo ATMI C Function Reference for more information on flags.
datalen	Length of the application-specific data. The buffer type switch entry for the TPINIT typed buffer sets this field based on the total size passed in for the typed buffer. The size of the application data is the total size less the size of the TPINIT structure itself plus the size of the data placeholder as defined in the structure.
data	Placeholder for variable length data that is forwarded to an application-defined authentication service.

Before it can join the application, the client program must call tpalloc() to allocate the TPINIT buffer. in the following listing shows how to allocate a TPINIT buffer that will be used to pass eight bytes of application-specific data to the tpinit() function.

Listing Allocating a TPINIT Typed Buffer

. 
. 
. 
TPINIT *tpinfo; 
. 
. 
. 
if ((tpinfo = (TPINIT *)tpalloc("TPINIT",(char *)NULL, 
     TPINITNEED(8))) == (TPINIT *)NULL){ 
     Error Routine 
}

Refer to tpinit() in the Oracle Tuxedo ATMI C Function Reference for more information on the TPINIT typed buffer.

Note:

• tpinit(3c) in the Oracle Tuxedo ATMI C Function Reference