Name

tpinit()—Joins an application.

Synopsis

#include <atmi.h>
int tpinit(TPINIT *tpinfo) 

Description

tpinit() allows a client to join a BEA Tuxedo ATMI system application. Before a client can use any of the BEA Tuxedo ATMI system communication or transaction routines, it must first join a BEA Tuxedo ATMI system application.

In single-context mode, if tpinit() is called more than once (that is, if it is called after the client has already joined the application), no action is taken and success is returned.

In a multithreaded client, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpinit(). To join a BEA Tuxedo ATMI application, a multithreaded Workstation client must always call tpinit() with the TPMULTICONTEXTS flag set, even if the client is running in single-context mode.

Note: The TPMULTICONTEXTS mode of tpinit will continue to work properly when the TMNOTHREADS environment variable is set to yes. Setting this environment variable to yes turns off multithreaded processing for applications that do not use threads.

Description of the TPINFO Structure

tpinit()'s argument, tpinfo, is a pointer to a typed buffer of type TPINIT and a NULL subtype. TPINIT is a buffer type that is typedefed in the atmi.h header file. The buffer must be allocated via tpalloc() prior to calling tpinit(). The buffer should be freed using tpfree() after calling tpinit(). The TPINIT typed buffer structure includes the following members:

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

The values of usrname, cltname, grpname, and passwd are all NULL-terminated strings. usrname is a name representing the caller. cltname is a client name whose semantics are application defined. The value sysclient is reserved by the system for the cltname field. The usrname and cltname fields are associated with the client at tpinit() time and are used for both broadcast notification and administrative statistics retrieval. They should not have more characters than MAXTIDENT, which is defined as 30. passwd is an application password in unencrypted format that is used for validation against the application password. The passwd is limited to 30 characters. grpname is used to associate the client with a resource manager group name. If grpname is set to a 0-length string, then 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. Note that grpname is not related to ACL GROUPS.

Single-context Mode Versus Multicontext Mode

tpinit() has two modes of operation: single-context mode and multicontext mode. In single-context mode, a process may join at most one application at any one time. Multiple application threads may access this application. Single-context mode is specified by calling tpinit() with a NULL parameter or by calling it without specifying the TPMULTICONTEXTS flag in the flags field of the TPINIT structure. Single-context mode is also specified when tpinit() is called implicitly by another ATMI function. The context state for a process operating in single-context mode is TPSINGLECONTEXT.

Note: The TPMULTICONTEXTS mode of tpinit will continue to work properly when the TMNOTHREADS environment variable is set to "yes".

In single-context mode, if tpinit() is called more than once (that is, if it is called after the client has already joined the application), no action is taken and success is returned.

Multicontext mode is entered by calling tpinit() with the TPMULTICONTEXTS flag set in the flags field of the TPINIT structure. In multicontext mode, each call to tpinit() results in the creation of a separate application association.

An application association is a context that associates a process and a BEA Tuxedo ATMI application. A client may have associations with multiple BEA Tuxedo ATMI applications, and may also have multiple associations with the same application. All of a client's associations must be made to applications running the same release of the BEA Tuxedo ATMI system, and either all associations must be native clients or all associations must be Workstation clients.

For native clients, the value of the TUXCONFIG environment variable is used to identify the application to which the new association will be made. For Workstation clients, the value of the WSNADDR or WSENVFILE environment variable is used to identify the application to which the new association will be made. The context for the current thread is set to the new association.

In multicontext mode, the application can get a handle for the current context by calling tpgetctxt() and pass that handle as a parameter to tpsetctxt(), thus setting the context in which a particular thread or process will operate.

Mixing single-context mode and multicontext mode is not allowed. Once an application has chosen one of these modes, calling tpinit() in the other mode is not allowed unless tpterm() is first called for all application associations.

TPINFO Structure Field Descriptions

In addition to controlling multicontext and single-context modes, the setting of flags is used to indicate both the client-specific notification mechanism and the mode of system access. These two settings may override the application default. If these settings cannot override the application default, tpinit() prints a warning in a log file, ignores the setting, and restores the application default setting in the flags field upon return from tpinit(). For client notification, the possible values for flags are as follows:

Only one of the above flags can be used at a time. If the client does not select a notification method via the flags field, then the application default method will be set in the flags field upon return from tpinit().

For setting the mode of system access, the possible values for flags are as follows:

If your application uses multithreading and/or multicontexting, you must set the following flag:

datalen is the length of the application-specific data that follows. 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 application data size 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 is a place holder for variable length data that is forwarded to an application-defined authentication service. It is always the last element of this structure.

A macro, TPINITNEED, is available to determine the size TPINIT buffer necessary to accommodate a particular desired application specific data length. For example, if 8 bytes of application-specific data are desired, TPINITNEED(8) will return the required TPINIT buffer size.

A NULL value for tpinfo is allowed for applications not making use of the authentication feature of the BEA Tuxedo ATMI system. Clients using a NULL argument will get: defaults of 0-length strings for usrname, cltname and passwd; no flags set; and no application data.

Return Values

Upon failure, tpinit() leaves the calling process in its original context, returns -1, and sets tperrno to indicate the error condition. Also, tpurcode() is set to the value returned by the AUTHSVR(5) server.

Errors

Upon failure, tpinit() sets tperrno to one of the following values:

Interoperability

tpchkauth() and a non-NULL value for the TPINIT typed buffer argument of tpinit() are available only on sites running release 4.2 or later.

Portability

Environment Variables

WSNADDR=(//m1.acme.com:3050|//m2.acme.com:3050),//m3.acme.com:3050

set WSNADDR=(//m1.acme.com:3050^|//m2.acme.com:3050),//m3.acme.com:3050

Warning

Because signaling of clients is always done by the system, the behavior of notification is always consistent, regardless of where the originating notification call is made. Therefore to use signal-based notification:

The ID for the application administrator is identified as part of the configuration for the application.

If signal-based notification is selected for a client, then certain ATMI calls may fail, returning TPGOTSIG due to receipt of an unsolicited message if TPSIGRSTRT is not specified.

See Also