4.5 Client Process Examples

The following pseudo-code in the following listing 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.

Listing Typical Client Process Paradigm

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 Oracle Tuxedo ATMI C Function Reference for a complete list of error codes that can be returned for each of the ATMI functions.

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

Listing Joining and Leaving an Application

#include <stdio.h>             /* UNIX */
#include <string.h>            /* UNIX */
#include <fml.h>               /* ORACLE Tuxedo System */
#include <atmi.h>              /* ORACLE Tuxedo System */
#include <Uunix.h>             /* ORACLE Tuxedo System */
#include <userlog.h>           /* ORACLE 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 Oracle 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.