Programming a BEA Tuxedo ATMI Application Using C

Writing Clients

This topic includes the following sections:

Joining an Application

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 the tpinit(3c) function with the following signature:

int
tpinit (TPINIT *tpinfo)

A client joins an application implicitly by issuing a service request (or any ATMI function) without first calling the tpinit()function. In this case, the tpinit() function is called by the BEA Tuxedo system on behalf of the client with the tpinfo argument set to NULL. The tpinfo argument points to a typed buffer with a TPINIT type and NULL subtype. The TPINIT typed buffer is defined in the atmi.h header file and includes the following information:

char usrname[MAXTIDENT+2]; 
char cltname[MAXTIDENT+2];
char passwd[MAXTIDENT+2];
char grpname[MAXTIDENT+2];
long flags;
long datalen;
long data;

The following table summarizes the TPINIT data structure fields.

Before it can join the application, the client program must call tpalloc() to allocate the TPINIT buffer. The following example shows how to allocate a TPINIT buffer that will be used to pass eight bytes of application-specific data to the tpinit() function.

.
.
.
TPINIT *tpinfo;
.
.
.
if ((tpinfo = (TPINIT *)tpalloc("TPINIT",(char *)NULL,
     TPINITNEED(8))) == (TPINIT *)NULL){
     Error Routine
}

Refer to tpinit() in the BEA Tuxedo ATMI C Function Reference for more information on the TPINIT typed buffer.

See Also

Using Features of the TPINIT Typed Buffer

The ATMI client must explicitly invoke the tpinit() function in order to take advantage of the following features of the TPINIT typed buffer:

Client Naming

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 the tpinit() function via the tpinfo buffer argument. 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.

Once a unique identifier for a client process is created:

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 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 BEA Tuxedo system checks for unsolicited messages each time an ATMI function 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() function to check for any waiting unsolicited messages. Refer to Writing Event-based Clients and Servers for more information on the tpchkunsol()function.

When a client joins an application using the tpinit() function, it can control how to handle unsolicited notification messages by defining flags. For client notification, the possible values for flags are defined in the following table.

Refer to tpinit(3c) in the BEA Tuxedo ATMI C Function Reference for more information on the TPINIT typed buffer flags.

System Access Mode

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 the tpinit() function. To specify a mode, a client passes one of the following values in the flags field of the TPINIT buffer to the tpinit() function.

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 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 the TPINIT buffer.

Client Authentication

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 TPINIT buffer and evaluated when the client calls tpinit() to join the application.

You can use the tpchkauth(3c) function to determine:

Typically, a client should call the tpchkauth() function before tpinit() 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 the tpterm(3c) function. The tpterm() function takes no arguments, and returns an integer value that is equal to -1 on error.

Building Clients

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. Use the following syntax for the buildclient command:

buildclient filename.c -o filename -f filenames -l filenames

The following table describes the options to 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 CC and CFLAGS environment variables to specify an alternative compile command, and to set flags for the compile and link-edit phases, respectively. For more information, refer to Setting Environment Variables.

buildclient -C -o audit -f audit.o

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

buildclient -o audit -f audit.c

See Also

Client Process Examples

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.

main()
{
     check level of security
     call tpsetunsol() to name your handler for TPU_DIP
     get usrname, cltname
     prompt for application password
     allocate a TPINIT buffer
     place values into TPINIT buffer structure members
 
     if (tpinit((TPINIT *) tpinfo) == -1){
          error routine;
     }
 
     allocate a message buffer
     while user input exists {
          place user input in the buffer
          make a service call
          receive the reply
          check for unsolicited messages
     }
     free buffers
     . . .
     if (tpterm() == -1){
          error routine;
     }
}

On error, -1 is returned and the application sets the external global variable, tperrno, to a value that indicates the nature of the error. tperrno is defined in the atmi.h header file and documented in tperrno(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference. Programmers typically assign an error code to this global variable that reflects the type of error encountered. There is a discussion of the values of tperrno in System Errors. See Introduction to the C Language Application-to-Transaction Monitor Interface" in the BEA Tuxedo ATMI C Function Reference for a complete list of error codes that can be returned for each of the ATMI functions.

The following example illustrates how to use the tpinit() and tpterm() functions. This example is borrowed from, bankapp, the sample banking application that is provided with the BEA Tuxedo system.

#include <stdio.h>         /* UNIX */
#include <string.h>        /* UNIX */
#include <fml.h>           /* BEA Tuxedo System */
#include <atmi.h>          /* BEA Tuxedo System */
#include <Uunix.h>         /* BEA Tuxedo System */
#include <userlog.h>       /* BEA Tuxedo System */
#include "bank.h"          /* BANKING #defines */
#include "aud.h"           /* BANKING view defines */
 
...
 
main(argc, argv)
int argc;
char *argv[];
 
{
     ...
     if (strrchr(argv[0],'/') != NULL)
      proc_name = strrchr(argv[0],'/')+1;
     else
      proc_name = argv[0];
     ...
     /* Join application */
     if (tpinit((TPINIT *) NULL) == -1) {
      (void)userlog("%s: failed to join application\n", proc_name);
        exit(1);
     }
     ...
     /* Leave application */
     if (tpterm() == -1) {
      (void)userlog("%s: failed to leave application\n", proc_name);
      exit(1);
     }
}

The previous example shows the client process attempting to join the application with a call to tpinit(). If the process encounters an error (that is, if the return code is -1), the process writes a descriptive message to the central event log via a call to userlog(), which takes arguments similar to the printf() C program statement. Refer to userlog(3c) in the BEA Tuxedo ATMI C Function Reference for more information.

Similarly, when tpterm() is called, if an error is encountered, the process writes a descriptive message to the central event log.