BEA Logo BEA Tuxedo Release 7.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo C Function Reference

tpinit(3c)

Name

tpinit() - joins an application

Synopsis

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

Description

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

tpinit() has two modes of operation: single-context mode and multicontext mode, which will be discussed in detail below. Because calling tpinit() is optional when in single-context mode, a single-context client may also join an application by calling many ATMI routines (for example, tpcall()), which transparently call tpinit() with tpinfo set to NULL. A client may want to call tpinit() directly so that it can set the parameters described below. In addition, tpinit() must be used when multicontext mode is required, when application authentication is required (see the description of the SECURITY keyword in UBBCONFIG(5)), or when the application wishes to supply its own buffer type switch (see typesw(5)). After tpinit() successfully returns, the client can initiate service requests and define transactions.

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 application, a multithreaded workstation client must always call tpinit() with the TPMULTICONTEXTS flag set, even if the client is running in single-context mode.

Description of the TPINFO Structure

tpinit()'s argument, tpinfo, is a pointer to a typed buffer of type TPINIT and a NULL sub-type. 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.

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 application. A client may have associations with multiple BEA Tuxedo 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 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:

TPU_SIG

Select unsolicited notification by signals. This flag should be used only with single-threaded, single-contexted applications; it cannot be used when the TPMULTICONTEXTS flag is set.

TPU_DIP

Select unsolicited notification by dip-in.

TPU_THREAD

Select THREAD notification in a separate thread managed by the BEA Tuxedo system. This flag is allowed only on platforms that support multithreading. If TPU_THREAD is specified on a platform that does not support multithreading, it is considered an invalid argument and will result in an error return with tperrno() set to TPEINVAL.

TPU_IGN

Ignore unsolicited notification.

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:

TPSA_FASTPATH

Set system access to fastpath.

TPSA_PROTECTED

Set system access to protected.

Only one of the above flags can be used at a time. If the client does not select a notification method or a system access mode via the flags field, then the application default method(s) will be set in the flags field upon return from tpinit(). See UBBCONFIG(5) for details on both client notification methods and system access modes.

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

TPMULTICONTEXTS

See description in "Single-context Mode versus Multicontext Mode."

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

[TPEINVAL]

Invalid arguments were specified. tpinfo is non-NULL and does not point to a typed buffer of type TPINIT.

[TPENOENT]

The client cannot join the application because of space limitations.

[TPEPERM]

The client cannot join the application because it does not have permission to do so or because it has not supplied the correct application password. Permission may be denied based on an invalid application password, failure to pass application-specific authentication, or use of restricted names. tpurcode() may be set by an application-specific authentication server to explain why the client cannot join the application.

[TPEPROTO]

tpinit() has been called improperly. For example: (a) the caller is a server; (b) the TPMULTICONTEXTS flag has been specified in single-context mode; or (c) the TPMULTICONTEXTS flag has not been specified in multicontext mode.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

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

The interfaces described in tpinit(3c) are supported on UNIX System, Windows, and MS-DOS operating systems. However, signal-based notification is not supported on 16-bit Windows or MS-DOS platforms. If it is selected at tpinit() time, then a userlog() message is generated and the method is automatically set to dip-in.

Environment Variables

TUXCONFIG

Used within tpinit() when invoked by a native client. It indicates the application to which the client should connect. Note that this environment variable is referenced only when tpinit() is called. Subsequent calls make use of the application context.

WSENVFILE

Used within tpinit() when invoked by a workstation client. It indicates a file containing environment variable settings that should be set in the caller's environment. See compilation(5) for details on environment variable settings necessary for workstation clients. Note that this file is processed only when tpinit() is called and not before.

WSNADDR

Used within tpinit() when invoked by a workstation client. It indicates the network addresses of the workstation listener that is to be contacted for access to the application. This variable is required for Workstation clients and is ignored for native clients.

TCP/IP addresses may be specified in the following forms:

//host.name:port_number

//#.#.#.#:port_number

In the first format, the domain finds an address for hostname using the local name resolution facilities (usually DNS). hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

In the second format, the string #.#.#.# is in dotted-decimal format. In dotted-decimal format, each # should be a number from 0 to 255. This dotted-decimal number represents the IP address of the local machine.

In both of the above formats, port_number is the TCP port number at which the domain process will listen for incoming requests. port_number can either be a number between 0 and 65535 or a name. If port_number is a name, then it must be found in the network services database on your local machine.

The address can also be specified in hexadecimal format when preceded by the characters 0x. Each character after the initial 0x is a number between 0 and 9 or a letter between A and F (case insensitive). The hexadecimal format is useful for arbitrary binary network addresses such as IPX/SPX or TCP/IP.

The address can also be specified as an arbitrary string. The value should be the same as that specified for the NLSADDR parameter in the NETWORK section of the configuration file.

More than one address can be specified if desired by specifying a comma-separated list of path names for WSNADDR. Addresses are tried in order until a connection is established. Any member of an address list can be specified as a parenthesized grouping of pipe-separated network addresses. For example:

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

For users running under Windows, the address string looks like the following.

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

Because the pipe symbol (|) is considered a special character in Windows, it must be preceded by a carat ( ^ )-an escape character in the Windows environment-when it is specified on the command line. However, if WSNADDR is defined in an envfile, the BEA Tuxedo system gets the values defined by WSNADDR through the tuxgetenv(3c) function. In this context, the pipe symbol (|) is not considered a special character, so you do not need to escape it with a carat (^).

The BEA Tuxedo system randomly selects one of the parenthesized addresses. This strategy distributes the load randomly across a set of listener processes. Addresses are tried in order until a connection is established. Use the value specified in the application configuration file for the workstation listener to be called. If the value begins with the characters 0x, it is interpreted as a string of hex-digits; otherwise, it is interpreted as ASCII characters.

WSFADDR

Used within tpinit() when invoked by a workstation client. It specifies the network address used by the workstation client when connecting to the workstation listener or workstation handler. This variable, along with the WSFRANGE variable, determines the range of TCP/IP ports to which a workstation client will attempt to bind before making an outbound connection. This address must be a TCP/IP address. The port portion of the TCP/IP address represents the base address from which a range of TCP/IP ports can be bound by the workstation client. The WSFRANGE variable specifies the size of the range. For example, if this address is //mymachine.bea.com:30000 and WSFRANGE is 200, then all native processes attempting to make outbound connections from this LMID will bind a port on mymachine.bea.com between 30000 and 30200. If not set, this variable defaults to the empty string, which implies the operating system chooses a local port randomly.

WSFRANGE

Used within tpinit() when invoked by a workstation client. It specifies the range of TCP/IP ports to which a workstation client process will attempt to bind before making an outbound connection. The WSFADDR parameter specifies the base address of the range. For example, if the WSFADDR parameter is set to //mymachine.bea.com:30000 and WSFRANGE is set to 200, then all native processes attempting to make outbound connections from this LMID will bind a port on mymachine.bea.com between 30000 and 30200. The valid range is 1-65535. The default is 1.

WSDEVICE

Used within tpinit() when invoked by a workstation client. It indicates the device name to be used to access the network. This variable is used by workstation clients and ignored for native clients. Note that certain supported transport level network interfaces do not require a device name; for example, sockets and NetBIOS. Workstation clients supported by such interfaces need not specify WSDEVICE.

WSTYPE

Used within tpinit() when invoked by a workstation client to negotiate encode/decode responsibilities with the native site. This variable is optional for workstation clients and ignored for native clients.

WSRPLYMAX

Used by tpinit() to set the maximum amount of core memory that should be used for buffering application replies before they are dumped to file. The default for this parameter 256,000 bytes. For more information, see the programming documentation for your instantiation.

TMMINENCRYPTBITS

Used to establish the minimum level of encryption required to connect to the BEA Tuxedo system. "0" means no encryption, while "56" and "128" specify the encryption key length (in bits). The link-level encryption value of 40 bits is also provided for backward compatibility. If this minimum level of encryption cannot be met, link establishment will fail. The default is "0".

TMMAXENCRYPTBITS

Used to negotiate the level of encryption up to this level when connecting to the BEA Tuxedo system. "0" means no encryption, while "56" and "128" specify the encryption length (in bits). The link-level encryption value of 40 bits is also provided for backward compatibility. The default is "128."

Warning

Signal-based notification is not allowed in multicontext mode. In addition, signal restrictions may prevent the system from using signal-based notification even though it has been selected by a client. When this happens, the system generates a log message that it is switching notification for the selected client to dip-in and the client is notified then and thereafter via dip-in notification. (See the description of the NOTIFY parameter in the RESOURCES section of UBBCONFIG(5) for a detailed discussion of notification methods.)

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

Introduction to the C Language Application-Transaction Monitor Interface, tpgetctxt(3c), tpsetctxt(3c), tpterm(3c)