|
|
This topic includes the following sections:
Before an ATMI client can perform any service request, it must join the BEA Tuxedo ATMI application, either explicitly or implicitly. Once the client has joined the application, it can initiate requests and receive replies.
A client joins an application explicitly by calling TPINITIALIZE( 3cbl) with the following signature:
01 TPINFDEF-REC.
COPY TPINFDEF.
01 USER-DATA-REC PIC X(any-length).
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPINITIALIZE" USING TPINFDEF-REC USER-DATA-REC TPSTATUS-REC.
A client joins an application implicitly by issuing a service request (or any ATMI call) without first calling TPINITIALIZE. In this case, TPINITIALIZE is called by the BEA Tuxedo system on behalf of the client with the SPACES parameter.The TPINFDEF-REC record is a special BEA Tuxedo system typed record used by a client program to pass client identification and authentication information to the system when the client attempts to join the application. It is defined in a COBOL COPY file, as follows:
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.
The following table lists the fields that are defined in a COBOL COPY file.
Resource manager group name with which you want to associate the client. The client can access an XA-compliant resource manager as part of a global transaction. The
GRPNAME can be a value up to MAXTIDENT characters (which is defined as 30). Currently, however, the GRPNAME must be passed as SPACES specifying that the client is not associated with a resource manager group and is in the default client group.
|
|
Notification mechanism and system access mode to be used. Refer to Unsolicited Notification Handling for a list of valid values.
|
|
System access mode used. Refer to System Access Mode for a list of values.
|
|
Length of the application-specific data that will be sent to the authentication service. For native clients, it is not encoded by the system, but passed to the authentication service as provided by the client. For workstation clients, client authentication is handled by the system, and passed over the network in encrypted form.
|
The USRNAME and CLTNAME fields are associated with the client process when TPINITIALIZE is called. Both fields are used for both broadcast notification and the retrieval of administrative statistics.
The ATMI client must explicitly invoke TPINITIALIZE in order to take advantage of the following features of the TPINFDEF-REC record:
When an ATMI client joins an application, the BEA Tuxedo system assigns a unique client identifier to it. The identifier is passed to each service called by the client. It can also be used for unsolicited notification.
You can also assign unique client and usernames of up to 30 characters each, by passing them to TPINITIALIZE via the TPINFDEF-REC record. The BEA Tuxedo system establishes a unique identifier for each process by combining the client and usernames associated with it, with the logical machine identifier (LMID) of the machine on which the process is running. You may choose a method for acquiring the values for these fields.
| Note: | If a process is executing outside the administrative domain of the application (that is, if it is running on a workstation connected to the administrative domain), the LMID of the machine used by the Workstation client to access the application is assigned. |
Once a unique identifier for a client process is created:
TPNOTIFY and TPBROADCAST.Refer to "Writing Event-based Clients and Servers" for information on sending and receiving unsolicited messages, and the BEA Tuxedo ATMI C Function Reference for more information on tmadmin(1).
The following figure shows how names might be associated with clients accessing an application. In the example, the application uses the cltname field to indicate a job function.
Unsolicited notification refers to any communication with an ATMI client that is not an expected response to a service request (or an error code). For example, an administrator may broadcast a message to indicate that the system will go down in five minutes.
A client can be notified of an unsolicited message in a number of ways. For example, some operating systems might send a signal to the client and interrupt its current processing. By default, the BEA Tuxedo system checks for unsolicited messages each time an ATMI call is invoked. This approach, referred to as dip-in, is advantageous because it:
As some time may elapse between "dip-ins," the application can call the TPCHKUNSOL call to check for any waiting unsolicited messages. Refer to
Writing Event-based Clients and Servers in Programming A BEA Tuxedo ATMI Application Using C for more information on the TPCHKUNSOL call.
When a client joins an application using TPINITIALIZE, it can control how to handle unsolicited notification messages by defining flags. For client notification, the possible values for NOTIFICATION-FLAG are defined in the following table.
Refer to TPINITIALIZE(3cbl) in the BEA Tuxedo ATMI COBOL Function Reference for more information on the TPINFDEF-REC flags.
An application can access the BEA Tuxedo system through either of two modes: protected or fastpath. The ATMI client can request a mode when it joins an application using TPINITIALIZE. To specify a mode, a client passes one of the following values in the ACCESS-FLAG field of the TPINFDEF-REC record to TPINITIALIZE.
An application administrator can configure groups for servers associated with a resource manager, including servers that provide administrative processes for coordinating transactions. Refer to Setting Up a BEA Tuxedo Application for information on defining groups.
When joining the application, a client can join a particular group by specifying the name of that group in the grpname field of TPINFDEF-REC.
The BEA Tuxedo system provides security at incremental levels, including operating system security, application password, user authentication, optional access control lists, mandatory access control lists, and link-level encryption. Refer to Setting Up a BEA Tuxedo Application for information on setting security levels.
The application password security level requires every client to provide an application password when it joins the application. The administrator can set or change the application password and must provide it to valid users.
If this level of security is used, BEA Tuxedo system-supplied client programs, such as ud(), prompt for the application password. (Refer to Administering a BEA Tuxedo Application at Run Time for more information on ud, wud(1).) In turn, application-specific client programs must include code for obtaining the password from a user. The unencrypted password is placed in the TPINFDEF-REC record and evaluated when the client calls TPINITIALIZE to join the application.
| Note: | The password should not be displayed on the screen. |
You can use TPCHK AUTH(3cbl) to determine:
Typically, a client should call TPCHKAUTH before TPINITIALIZE to identify any additional security information that must be provided during initialization.
Refer to Using Security in CORBA Applications for more information on security programming techniques.
Once all service requests have been issued and replies received, the ATMI client can leave the application using TPT
ERM(3cbl). The TPTERM call signature is as follows:
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPTERM" USING TPSTATUS-REC.
To build an executable ATMI client, compile your application with the BEA Tuxedo system libraries and all other referenced files using the buildclient(1) command. Include the -C option to indicate that you are compiling a COBOL program. Use the following syntax for the buildclient command:
buildclient -Cfilename.cbl-ofilename-ffilenames-lfilenames
The following table describes the options to the buildclient command.
| Note: | The BEA Tuxedo libraries are linked in automatically; you do not need to specify any BEA Tuxedo libraries on the command line. |
The order in which you specify the library files to be link edited is significant: it depends on the order in which functions are called in the code, and which libraries contain references to those functions.
By default, the buildclient command invokes the UNIX cc command. You can set the ALTCC and ALTCFLAGS environment variables to specify an alternative compile command, and to set flags for the compile and link-edit phases, respectively. By default, ALTCC is set to cobcc, which uses the MicroFocus Net Express compiler. To use Fujitsu's NetCOBOL ALTCC must be set, even on a Windows system. You must set ALTCC=cobcc85 for NetCOBOL. For more information, refer to
Setting Environment Variables in Programming A BEA Tuxedo ATMI Application Using C.
| Note: | On a Windows system, the ALTCC and ALTCFLAGS environment variables are not applicable; setting them will produce unexpected results. You must compile your application by first using a COBOL compiler, and then passing the resulting object file to the buildclient command. For example: |
| Note: | buildclient -C -o audit -f audit.o |
| Note: | The following example command line compiles a COBOL program called audit.cbl and generates an executable file named audit. |
| Note: | buildclient -C -o audit -f audit.cbl |
The following pseudo-code shows how a typical ATMI client process works from the time at which it joins an application to the time at which it leaves the application.
. . .
Check level of security
CALL TPSETUNSOL to name your handler routine for TPU-DIP
get USRNAME, CLTNAME
prompt for application PASSWD
SET TPU-DIP TO TRUE.
CALL "TPINITIALIZE" USING TPINFDEF-REC
USER-DATA-REC
TPSTATUS-REC.
IF NOT TPOK
error processing
. . .
make service call
receive the reply
check for unsolicited messages
. . .
CALL "TPTERM" USING TPSTATUS-REC.
IF NOT TPOK
error processing
. . .
EXIT PROGRAM.
In this example, TPINITIALIZE takes three arguments:
Both TPINITIALIZE and TPTERM return [TPOK] in TP-STATUS IN TPSTATUS-REC upon success. If either command encounters an error, the command fails and sets TP-STATUS to a value that indicates the nature of the error. TPSTATUS-REC is defined in a COBOL COPY file. Refer to
Managing Errors in Programming A BEA Tuxedo ATMI Application Using C for possible TP-STATUS values. Refer to
Introduction to the COBOL Application-Transaction Monitor Interface in the BEA Tuxedo ATMI COBOL Function Reference for a complete list of error codes that can be returned for each of the ATMI calls.
The following example illustrates how to use the TPINITIALIZE and TPTERM routines. This example is borrowed from, bankapp, the sample banking application that is provided with the BEA Tuxedo system.
IDENTIFICATION DIVISION.
PROGRAM-ID. FIG1-3.
AUTHOR. TUXEDO DEVELOPMENT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
*
WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
01 TPSTATUS-REC.
COPY TPSTATUS.
*
01 TPINFDEF-REC.
COPY TPINFDEF.
*****************************************************
* Log messages definitions
*****************************************************
01 LOGMSG.
05 FILLER PIC X(10) VALUE "FIG12-3 =>".
05 LOGMSG-TEXT PIC X(50).
01 LOGMSG-LEN PIC S9(9) COMP-5.
*
01 USER-DATA-REC PIC X(75).
******************************************************
PROCEDURE DIVISION.
START-HERE.
MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
*****************************************************
* Now register the client with the system.
*****************************************************
MOVE SPACES TO USRNAME.
MOVE SPACES TO CLTNAME.
MOVE SPACES TO PASSWD.
MOVE SPACES TO GRPNAME.
MOVE ZERO TO DATALEN.
SET TPU-DIP TO TRUE.
*
CALL "TPINITIALIZE" USING TPINFDEF-REC
USER-DATA-REC
TPSTATUS-REC.
IF NOT TPOK
MOVE "TPINITIALIZE FAILED" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM.
*****************************************************
* Application specific code
*****************************************************
. . .
*****************************************************
*Leave Application
*****************************************************
CALL "TPTERM" USING TPSTATUS-REC.
IF NOT TPOK
MOVE "TPTERM FAILED" TO LOGMSG-TEXT
PERFORM DO-USERLOG.
EXIT-PROGRAM.
STOP RUN.
*****************************************************
* Log messages to the userlog
*****************************************************
DO-USERLOG.
CALL "USERLOG" USING LOGMSG
LOGMSG-LEN
TPSTATUS-REC.
The previous example shows the client process attempting to join the application with a call to TPINITIALIZE. If an error is encountered, a message is written to the central event log via a call to USERLOG.
|