tpinit(3)-routine for joining an application
#include <atmi.h>
int tpinit(TPINIT *tpinfo)
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. Because calling tpinit() is optional, a client may also join an application by calling many ATMI routines (for example, tpcall(3)) 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 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.
If tpinit() is called more than once (that is, after the client has already joined the application), no action is taken and success is returned.
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(3). The buffer should be freed using tpfree(3) 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;
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 /WS clients. Note that grpname is not related to ACL GROUPS.
The setting of flags is used to indicate both the client-specific notification mechanism and the mode of system access. These settings may override the application default; however, in the event that they cannot, tpinit() will print a warning in a log file, ignore the setting and return the application default setting in the flags element upon return from tpinit(). For client notification, the possible values for flags are as follows:
TPU_SIG-Select unsolicited notification by signals.
TPU_DIP-Select unsolicited notification by dip-in.
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.
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.
tpinit() returns -1 on error and sets tperrno to indicate the error condition.
Under the following conditions, tpinit() fails and sets tperrno to:
TPEINVAL]
tpinfo is non-NULL and does not point to a typed buffer of type TPINIT.
TPENOENT]
TPEPERM]
TPEPROTO]
tpinit() was called in an improper context (for example, the caller is a server).
TPESYSTEM]
TPEOS]
tpchkauth(3c) 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(3c) message is generated and the method is automatically set to dip-in.
WSENVFILE-is 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 more details on environment variable settings necessary for workstation clients. Note that this file is processed only when tpinit() is called and not before.
WSNADDR-is used within tpinit() when invoked by a workstation client. It indicates the network address(es) of the workstation listener that is to be contacted for access to the application.
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 example, 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
For users running under Windows, the address string would look like this:
set WSNADDR=(//m1.acme.com:3050^|//m2.acme.com:3050),//m3.acme.com:3050
The carat (^) is needed to escape the pipe (|).
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.
WSDEVICE-is 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-is 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-is 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 varies with each instantiation. The instantiation specific Programmer's Guide should be consulted for further information.
TMMINENCRYPTBITS-When connecting to the BEA TUXEDO system, require at least this minimum level of encryption. "0" means no encryption, while "40" and "128" specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment will fail. The default is "0".
TMMAXENCRYPTBITS-When connecting to the BEA TUXEDO system, negotiate encryption up to this level. "0" means no encryption, while "40" and "128" specify the encryption length (in bits). The default is "128"
Signal restrictions may prevent the system 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 ubbconfig(5) description of the *RESOURCES NOTIFY parameter for a detailed discussion of notification methods.) Note that signaling of clients is always done by the system so that the behavior of notification is consistent regardless of where the originating notification call is made. Because of this, only clients running as the application administrator can 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.
tpterm(3)