TPINITIALIZE-join a BEA TUXEDO system application
01TPINFDEF-REC.
COPY TPINFDEF.
01USER-DATA-RECPIC X(any-length).
01TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPINITIALIZE"TPINFDEF-RECUSER-DATA-RECTPSTATUS-REC.
TPINITIALIZE 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 TPINITIALIZE is optional, a client may also join an application by calling many ATMI routines (for example, TPACALL() or TPCALL()) which transparently call TPINITIALIZE with default values for the members of TPINFDEF-REC. A client may want to call TPINITIALIZE directly so that it can set the parameters described below. In addition, TPINITIALIZE must be used when application authentication is required (see the description of the SECURITY keyword in ubbconfig(5)). After TPINITIALIZE successfully returns, the client can initiate service requests and define transactions.
If TPINITIALIZE is called more than once (that is, after the client has already joined the application), no action is taken and success is returned.
TPINITIALIZE's argument, TPINFDEF-REC record includes the following members:
05 USRNAME PIC X(30).
05 CLTNAME PIC X(30).
05 PASSWD PIC X(30).
05 GRPNAME PIC X(30).
05 NOTIFICATION-FLAG PIC S9(9) COMP-5.
88 TPU-SIG VALUE 1.
88 TPU-DIP VALUE 2.
88 TPU-IGN VALUE 3.
05 ACCESS-FLAG PIC S9(9) COMP-5.
88 TPSA-FASTPATH VALUE 1.
88 TPSA-PROTECTED VALUE 2.
05 DATALEN PIC S9(9) COMP-5.
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 TPINITIALIZE time and are used for both broadcast notification and administrative statistics retrieval. PASSWD is an application password in unencrypted format that is used for validation against the application password. The PASSWD is significant up to 30 characters. GRPNAME is used to associate the client with a resource manager group name. If GRPNAME is SPACES, then the client is not associated with a resource manager and is in the default client group.
The settings of TPINFDEF-REC are 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, TPINITIALIZE will print a warning in a log file, ignore the setting and return the application default setting in TPINFDEF-REC upon return from TPINITIALIZE. For client notification, the possible settings are as follows:
TPU-SIG
TPU-DIP
TPU-IGN
Only one of the above can be used at a time. If the client does not select a notification method, then the application default method will be set upon return from TPINITIALIZE.
For setting the mode of system access, the possible settings are as follows:
TPSA-FASTPATH
TPSA-PROTECTED
Only one of the above can be used at a time. If the client does not select a notification method or a system access mode, then the application default method(s) will be set upon return from TPINITIALIZE. See ubbconfig(5) for details on both client notification methods and system access modes.
DATALEN is the length of the application specific data that will be sent to the service. TPINITIALIZENEED(8) will return A SPACES value for USRNAME and CLTNAME is allowed for applications not making use of the application authentication feature of the BEA TUXEDO system. Currently, GRPNAME must be SPACES. Clients using this option will get defined in the BEA TUXEDO system with default values for USRNAME, CLTNAME and GRPNAME; default settings and no application data.
Upon successful completion, TPINITIALIZE sets TP-STATUS to [TPOK].
Under the following conditions, TPINITIALIZE fails and sets TP-STATUS to:
TPEINVAL]
TPENOENT]
TPEPERM]
TPEPROTO]
TPINITIALIZE was called in an improper context (for example, the caller is a server).
TPESYSTEM]
TPEOS]
The interfaces described in TPINITIALIZE() are supported on UNIX System and MS-DOS operating systems. However, signal-based notification is not supported on MS-DOS. If it is selected at TPINITIALIZE time, then a USERLOG() message is generated and the method is automatically set to dip-in.
WSENVFILE
TPINITIALIZE 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 TPINITIALIZE is called and not before.
WSNADDR
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 "#.#.#.#" 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 NETWORKS 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"
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 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
TPINITIALIZE 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
TPINITIALIZE 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
TPINITIALIZE to set the maximum amount of core memory that should be used for buffering application replies before they are dumped to file. The default value for this parameter varies with each instantiation. The instantiation specific programmer's guide should be consulted for further information.
TMMINENCRYPTBITS
TMMAXENCRYPTBITS
Clients that select signal-based notification may not be signal-able by the system due to signal restrictions. 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()