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 Oracle Tuxedo system on behalf of the client with the SPACES parameter.The TPINFDEF-REC record is a special Oracle 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:Table 4‑1 lists the fields that are defined in a COBOL COPY file.
Table 4‑1 COBOL COPY File Fields Name representing the caller. You may want to specify the value returned by the UNIX command getuid(2) within this field. The value of USRNAME may contain up to MAXTIDENT characters (which is defined as 30). Name of a client for which the semantics are application-defined. The value of CLTNAME may contain up to MAXTIDENT characters (which is defined as 30). Application password in unencrypted format that is used by TPINITIALIZE for validation against the application password stored in the TUXCONFIG file. PASSWD is a string of up to MAXTIDENT characters. 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” on page 4‑5 for a list of valid values. System access mode used. Refer to “System Access Mode” on page 4‑6 for a list of values. 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.
• TPINITIALIZE(3cbl) in the Oracle Tuxedo ATMI COBOL Function ReferenceThe ATMI client must explicitly invoke TPINITIALIZE in order to take advantage of the following features of the TPINFDEF-REC record: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 Oracle 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.
• Unsolicited messages can be sent to a specific client or to groups of clients via TPNOTIFY and TPBROADCAST.Refer to “Writing Event-based Clients and Servers” for information on sending and receiving unsolicited messages, and the Oracle Tuxedo ATMI C Function Reference for more information on tmadmin(1).Figure 4‑1 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.Figure 4‑1 Client NamingA 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 Oracle 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 An Oracle 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 Table 4‑2.
• The calling process must have the same UID as the sending process when you are running a native client. (Workstation clients do not have this limitation.)
• TPU_SIG is not available on all platforms (specifically, it is not available on MS-DOS workstations).If you specify this flag but do not meet the system or environmental requirements, the flag is set to TPU_DIP and the event is logged. TPU_DIP (default) Select unsolicited notification by dip-in. In this case, the client can specify the name of the message handling routine using the TPSETUNSOL call, and check for waiting unsolicited messages using the TPCHKUNSOL call. Select THREAD notification in a separate thread. 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. As a result, an error is returned and TP-STATUS is set to TPEINVAL. Refer to TPINITIALIZE(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference for more information on the TPINFDEF-REC flags.An application can access the Oracle 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.
Allows ATMI calls within an application to access the Oracle Tuxedo system internal tables via shared memory, but protects shared memory against access by application code outside of the Oracle Tuxedo system libraries. Overrides the value in UBBCONFIG, except when NO_OVERRIDE is specified. Refer to Setting Up an Oracle Tuxedo Application for more information on UBBCONFIG. TPSA-FASTPATH (default) Allows ATMI calls within application code access to Oracle Tuxedo system internals via shared memory. Does not protect shared memory against access by application code outside of the Oracle Tuxedo system libraries. Overrides the value of UBBCONFIG except when NO_OVERRIDE is specified. Refer to Setting Up an Oracle Tuxedo Application for more information on UBBCONFIG.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 an Oracle 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 Oracle 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 an Oracle Tuxedo Application for information on setting security levels.If this level of security is used, Oracle Tuxedo system-supplied client programs, such as ud(), prompt for the application password. (Refer to Administering an Oracle 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.You can use TPCHKAUTH(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 TPTERM(3cbl). The TPTERM call signature is as follows:To build an executable ATMI client, compile your application with the Oracle 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:Table 4‑4 describes the options to the buildclient command.
Table 4‑4 buildclient Options filename.cbl -o filename -f filenames A list of files that are to be link edited before the Oracle Tuxedo system libraries are link edited. You can specify -f more than once on the command line, and you can include multiple filenames for each occurrence of -f. If you specify a COBOL program file (file.cbl), it is compiled before it is linked. You can specify other object files (file.o) separately, or in groups in an archive file (file.a). -l filenames A list of files that are to be link edited after the Oracle Tuxedo system libraries are link edited. You can specify -l more than once on the command line, and you can include multiple filenames for each occurrence of -l. If you specify a COBOL program file (file.cbl), it is compiled before it is linked. You can specify other object files (file.o) separately, or in groups in an archive file (file.a). The resource manager has access to libraries that should be link edited with the executable server. The application administrator is responsible for predefining all valid resource manager information in the $TUXDIR/updataobj/RM file using the buildtms(1) command. Only one resource manager can be specified. Refer to Setting Up an Oracle Tuxedo Application for more information.Link editing must be done by running the buildclient command.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 An Oracle 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:The following example command line compiles a COBOL program called audit.cbl and generates an executable file named audit.
• “Building Servers in Programming An Oracle Tuxedo ATMI Application Using C
• buildclient(1) in the Oracle Tuxedo Command ReferenceThe following pseudo-code in Listing 4‑1shows 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.Listing 4‑1 Typical Client Process Paradigm. . .
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:
• TPINFDEF-REC, a structure defined in the COBOL COPY file
• User data (USER-DATA-REC)
• TPSTATUS-REC, a status structure defined in the COBOL COPY fileBoth 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 An Oracle Tuxedo ATMI Application Using C for possible TP-STATUS values. Refer to “Introduction to the COBOL Application-Transaction Monitor Interface” in the Oracle 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 Oracle Tuxedo system.Listing 4‑2 Joining and Leaving an ApplicationIDENTIFICATION 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.