Writing Clients

This topic includes the following sections:

•	Joining an Application

•	Using Features of the TPINFDEF-REC Record

•	Leaving the Application

•	Building Clients

•	Client Process Examples

Joining an Application

Before an ATMI client can perform any service request, it must join the Oracle 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 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:

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.

Table 4‑1 lists the fields that are defined in a COBOL COPY file.

 

Table 4‑1 COBOL COPY File Fields

Field	Description
USRNAME	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).
CLTNAME	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).
PASSWD	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.
GRPNAME	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-FLAG	Notification mechanism and system access mode to be used. Refer to “Unsolicited Notification Handling” on page 4‑5 for a list of valid values.
ACCESS-FLAG	System access mode used. Refer to “System Access Mode” on page 4‑6 for a list of values.
DATALEN	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.

See Also

•	TPINITIALIZE(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference

Using Features of the TPINFDEF-REC Record

The ATMI client must explicitly invoke TPINITIALIZE in order to take advantage of the following features of the TPINFDEF-REC record:

•	Client Naming

•	Unsolicited Notification Handling

•	System Access Mode

•	Resource Manager Association

•	Client Authentication

Client Naming

When an ATMI client joins an application, the Oracle 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 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.

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:

•	Client authentication can be implemented.

•	Unsolicited messages can be sent to a specific client or to groups of clients via TPNOTIFY and TPBROADCAST.

•	Detailed statistical information can be gathered via tmadmin(1).

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 Naming

Unsolicited Notification Handling

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 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:

•	Is supported on all platforms

•	Does not interrupt the current processing

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.

 

Table 4‑2 Client Notification Flags in a TPINFDEF-REC Record

Flag	Description
TPU_SIG	Select unsolicited notification by signals. This flag should be used only with single-threaded, single-context applications. The advantage of using this mode is immediate notification. The disadvantages include: • 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.
TPU_THREAD	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.
TPU_IGN	Ignore unsolicited notification.

Refer to TPINITIALIZE(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference for more information on the TPINFDEF-REC flags.

System Access Mode

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.

 

Table 4‑3 System Access Flags in a TPINFDEF-REC Record

Mode	Description
TPSA-PROTECTED	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.

Resource Manager Association

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.

Client Authentication

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.

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, 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.

Note:

The password should not be displayed on the screen.

You can use TPCHKAUTH(3cbl) to determine:

•	Whether the application requires any authentication

•	If the application requires authentication, which of the following types of authentication is needed:

•	System authentication based on an application password

•	Application authentication based on an application password and user-specific information

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.

Leaving the Application

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:

01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPTERM" USING TPSTATUS-REC.

Building Clients

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:

buildclient -C filename.cbl -o filename -f filenames -l filenames

Table 4‑4 describes the options to the buildclient command.

 

Table 4‑4 buildclient Options

This Option or Argument . . .	Allows You to Specify . . .
filename.cbl	The COBOL application to be compiled.
-o filename	The executable output file. The default name for the output file is a.out.
-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).
-r	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.

Notes:

The Oracle Tuxedo libraries are linked in automatically; you do not need to specify any Oracle Tuxedo libraries on the command line.

Link editing must be done by running the buildclient command.

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 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:

buildclient -C -o audit -f audit.o

The following example command line compiles a COBOL program called audit.cbl and generates an executable file named audit.

buildclient -C –o audit –f audit.cbl

See Also

•	“Building Servers in Programming An Oracle Tuxedo ATMI Application Using C

•	buildclient(1) in the Oracle Tuxedo Command Reference

Client Process Examples

The 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 file

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 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 Application

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.