ATMI C Function Reference
tpinit()
—Joins an application.
#include <atmi.h>
int tpinit(TPINIT *tpinfo)
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.
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 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.
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 typedef
ed 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.
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.
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:
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.
Select THREAD
notification in a separate thread managed by the BEA Tuxedo ATMI 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
.
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:
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:
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 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.
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.
Upon failure, tpinit()
sets tperrno
to one of the following values:
Invalid arguments were specified. tpinfo
is non-NULL and does not point to a typed buffer of type TPINIT
.
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.
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.
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.
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.
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.
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.
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.
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 pathnames 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
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 ATMI 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 ATMI 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.
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.
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.
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
.
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.
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.
Used to establish the minimum level of encryption required to connect to the BEA Tuxedo ATMI 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".
Used to negotiate the level of encryption up to this level when connecting to the BEA Tuxedo ATMI 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."
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.
Introduction to the C Language Application-to-Transaction Monitor Interface, tpgetctxt(3c)
, tpsetctxt(3c)
, tpterm(3c)