Tutorials for Developing Oracle Tuxedo ATMI Applications

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Tutorial for simpapp, a Simple C Application

This topic includes the following sections:

 


What Is simpapp?

simpapp is a sample ATMI application that includes one client and one server. This application is distributed with the Oracle Tuxedo software. The server performs only one service: it accepts a lowercase alphabetic string from the client and returns the same string in uppercase.

 


Preparing simpapp Files and Resources

This topic is a tutorial that leads you, step-by-step, through the process of developing and running a sample Oracle Tuxedo ATMI application. Figure 2-1 summarizes the process. Click on each task for instructions on completing that task.

Figure 2-1 simpapp Development Process

simpapp Development Process

Before You Begin

Before you can run this tutorial, the Oracle Tuxedo ATMI client and server software must be installed so that the files and commands referred to are available. If the installation has already been done by someone else, you need to know the pathname of the directory in which the software is installed (TUXDIR). You also need to have read and write permissions on the directories and files in the Oracle Tuxedo directory structure so you can copy simpapp files and execute Oracle Tuxedo commands.

About This Tutorial

The instructions for the simpapp tutorial are based on a UNIX system platform. While specific platform instructions for the UNIX operating system environment remain largely the same, instructions for performing tasks (such as copying simpapp files or setting environment variables) on non-UNIX platforms (such as Windows 2003) may be different. For this reason, the examples used in the tutorial may or may not provide reliable procedures for your platform.

What You Will Learn

After you complete this tutorial, you will be able to understand the tasks ATMI clients and servers can perform, edit a configuration file for your own environment, and invoke tmadmin to check on the activity of your application. You will understand the basic elements of all Oracle Tuxedo applications—client processes, server processes, and a configuration file—and you will know how to use Oracle Tuxedo system commands to manage your application.

 


Step 1: How to Copy the simpapp Files

Note: The following instructions are based on a UNIX system platform. Instruction for non-UNIX platforms, such as Windows 2003, may be different. Examples used in the sample applications may vary significantly, depending on the specific platform.
  1. Make a directory for simpapp and cd to it:
  2. mkdir simpdir
    cd simpdir
    Note: This step is suggested so you can see the simpapp files you have at the start and the additional files you create along the way. Use the standard shell (/bin/sh) or the Korn shell; do not use csh.
  3. Set and export environment variables:
  4. TUXDIR=pathname of the Oracle Tuxedo system root directory
    TUXCONFIG=pathname of your present working directory/tuxconfig
    PATH=$PATH:$TUXDIR/bin
    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TUXDIR/lib
    export TUXDIR TUXCONFIG PATH LD_LIBRARY_PATH

    You need TUXDIR and PATH to be able to access files in the Oracle Tuxedo system directory structure and to execute Oracle Tuxedo system commands. On Sun Solaris, /usr/5bin must be the first directory in your PATH. With AIX on the RS/6000, use LIBPATH instead of LD_LIBRARY_PATH. On HP-UX on the HP 9000, use SHLIB_PATH instead of LD_LIBRARY_PATH.

    You need to set TUXCONFIG to be able to load the configuration file, described in Step 4: Editing and Loading the Configuration File.

  5. Copy the simpapp files:
  6. cp $TUXDIR/samples/atmi/simpapp/* .
    Note: It is best to begin with a copy of the files rather than the originals delivered with the software because you will edit some of the files to make them executable.
  7. List the files:
  8.   $ ls 
         README       env        simpapp.nt  ubbmp     wsimpcl
         README.as400 setenv.cmd simpcl.c    ubbsimple
         README.nt    simpapp.mk simpserv.c  ubbws
      $
    Note: Except for the README files, the other files are variations of simp*.* and ubb* files for non-UNIX system platforms. The README files provide explanations of the other files.

    The three files that are central to the application are:

    • simpcl.c—the source code for the client program.
    • simpserv.c—the source code for the server program.
    • ubbsimple—the text form of the configuration file for the application.

See Also

 


Step 2: Examining and Compiling the Client

How to Examine the Client

Review the ATMI client program source code:

    $ more simpcl.c

The output is shown in Listing 2-1.

Listing 2-1 Source Code of simpcl.c
1     #include <stdio.h>          
2     #include "atmi.h"             /* TUXEDO */
3
4
5
6
7     #ifdef __STDC__
8     main(int argc, char *argv[])
9
10    #else
11
12    main(argc, argv)
13    int argc;
14    char *argv[];
15    #endif
16
17    {
18
19             char *sendbuf, *rcvbuf;
20             int sendlen, rcvlen;
21             int ret;
22
23             if(argc != 2) {
24                      fprintf(stderr, "Usage: simpcl string\n");
25                      exit(1);
26             }
27             /* Attach to BEA TUXEDO as a Client Process */
28             if (tpinit((TPINIT *) NULL) == -1) {
29                      fprintf(stderr, "Tpinit failed\n");
30                      exit(1);
31             }
32             sendlen = strlen(argv[1]);
33           if((sendbuf = (char *)tpalloc("STRING", NULL, sendlen+1))== NULL){
34                       fprintf(stderr,"Error allocating send buffer\n");
35                      tpterm();
36                      exit(1);
37             }
38             if((rcvbuf = (char *)tpalloc("STRING", NULL, sendlen+1))== NULL){
39                      fprintf(stderr,"Error allocating receive buffer\n");
40                      tpfree(sendbuf);
41                      tpterm();
42                      exit(1);
43             }
44             strcpy(sendbuf, argv[1]);
45             ret = tpcall("TOUPPER", sendbuf, NULL, &rcvbuf, &rcvlen, 0);
46             if(ret == -1) {
47                  fprintf(stderr, "Can't send request to service TOUPPER\n");
48        fprintf(stderr, "Tperrno = %d, %s\n", tperrno, tpstrerror(tperrno));
49                      tpfree(sendbuf);
50                      tpfree(rcvbuf);
51                      tpterm();
52                      exit(1);
53             }
54             printf("Returned string is: %s\n", rcvbuf);
55
56             /* Free Buffers & Detach from Oracle TUXEDO */
57             tpfree(sendbuf);
58             tpfree(rcvbuf);
59             tpterm();
60    }

Table 2-1 Significant Lines in the simpcl.c Source Code 
Line(s)
File/Function
Purpose
     
2
atmi.h
Header file required whenever Oracle Tuxedo ATMI functions are used.
28
tpinit()
The ATMI function used by a client program to join an application.
33
tpalloc()
The ATMI function used to allocate a typed buffer. STRING is one of the five basic Oracle Tuxedo buffer types; NULL indicates there is no subtype argument. The remaining argument, sendlen + 1, specifies the length of the buffer plus 1 for the null character that ends the string.
38
tpalloc()
Allocates another buffer for the return message.
45
tpcall()
Sends the message buffer to the TOUPPER service specified in the first argument. Also includes the address of the return buffer. tpcall() waits for a return message.
35, 41, 52, 60
tpterm()
The ATMI function used to exit an application. A call to tpterm() is used to exit the application before exiting in response to an error condition (lines 36, 42, and 53). The final call to tpterm() (line 60) is issued after the message has been printed.
40, 50, 51, 58, 59
tpfree()
Frees allocated buffers. tpfree() is the functional opposite of tpalloc().
55
printf()
The successful conclusion of the program. It prints out the message returned from the server.

How to Compile the Client

  1. Run buildclient to compile the ATMI client program:
  2.     buildclient -o simpcl -f simpcl.c

    The output file is simpcl and the input source file is simpcl.c.

  3. Check the results:
  4. $ ls -l
    total 97
    -rwxr-x--x 1 usrid grpid 313091 May 28 15:41 simpcl
    -rw-r----- 1 usrid grpid 1064 May 28 07:51 simpcl.c
    -rw-r----- 1 usrid grpid 275 May 28 08:57 simpserv.c
    -rw-r----- 1 usrid grpid 392 May 28 07:51 ubbsimple

    As can be seen, we now have an executable module called simpcl. The size of simpcl may vary.

See Also

 


Step 3: Examining and Compiling the Server

How to Examine the Server

Review the ATMI server program source code.

$ more simpserv.c
Listing 2-2 Source Code of simpserv.c
   */
/* #ident	"@(#) apps/simpapp/simpserv.c	$Revision: 1.1 $" */
1 #include <stdio.h>
2 #include <ctype.h>
3 #include <atmi.h> /* TUXEDO Header File */
4 #include <userlog.h> /* TUXEDO Header File */
5 /* tpsvrinit is executed when a server is booted, before it begins
   processing requests. It is not necessary to have this function.
   Also available is tpsvrdone (not used in this example), which is
   called at server shutdown time.
9  */
10 #if defined(__STDC__) || defined(__cplusplus)

12 tpsvrinit(int argc, char *argv[])
13 #else
14 tpsvrinit(argc, argv)
15 int argc;
16 char **argv;
17 #endif
18     {
19         /* Some compilers warn if argc and argv aren't used.
20          */
21        argc = argc;
22        argv = argv;
23        /* userlog writes to the central TUXEDO message log */
24         userlog("Welcome to the simple server");
25         return(0);
26 }
27 /* This function performs the actual service requested by the client.
      Its argument is a structure containing, among other things, a pointer
      to the data buffer, and the length of the data buffer.
30 */
31 #ifdef __cplusplus
32 extern "C"
33 #endif
34 void
35 #if defined(__STDC__) || defined(__cplusplus)
36 TOUPPER(TPSVCINFO *rqst)
37 #else
38 TOUPPER(rqst)
39 TPSVCINFO *rqst;
40 #endif
41 {
42       int i;
43
44       for(i = 0; i < rqst->len-1; i++)
45               rqst->data[i] = toupper(rqst->data[i]);
46       /* Return the transformed buffer to the requestor. */
47       tpreturn(TPSUCCESS, 0, rqst->data, 0L, 0);
48 }

Table 2-2 Significant Parts of the simpserv.c Source Code
Line(s)
File/Function
Purpose
Whole file
 
An Oracle Tuxedo server does not contain a main(). The main() is provided by the Oracle Tuxedo system when the server is built.
12
tpsvrinit()
This subroutine is called during server initialization, that is, before the server begins processing service requests. A default subroutine (provided by the Oracle Tuxedo system) writes a message to USERLOG indicating that the server has been booted. userlog(3c) is a log used by the Oracle Tuxedo system and can be used by applications.
38
TOUPPER()
The declaration of a service (the only one offered by simpserv). The sole argument expected by the service is a pointer to a TPSVCINFO structure, which contains the data string to be converted to uppercase.
45
for loop
Converts the input to uppercase by repeated calls to TOUPPER.
49
tpreturn()
Returns the converted string to the client with the TPSUCCESS flag set.

How to Compile the Server

  1. Run buildserver to compile the ATMI server program:
  2.     buildserver -o simpserv -f simpserv.c -s TOUPPER

    The executable file to be created is named simpserv and simpserv.c is the input source file. The -s TOUPPER option specifies the service to be advertised when the server is booted.

  3. Check the results:
  4. $ ls -l
    total 97
    -rwxr-x--x 1 usrid grpid 313091 May 28 15:41 simpcl
    -rw-r----- 1 usrid grpid 1064 May 28 07:51 simpcl.c
    -rwxr-x--x 1 usrid grpid 358369 May 29 09:00 simpserv
    -rw-r----- 1 usrid grpid 275 May 28 08:57 simpserv.c
    -rw-r----- 1 usrid grpid 392 May 28 07:51 ubbsimple

You now have an executable module called simpserv.

See Also

 


Step 4: Editing and Loading the Configuration File

How to Edit the Configuration File

  1. In a text editor, familiarize yourself with ubbsimple, which is the configuration file for simpapp.
  2. Listing 2-3 The simpapp Configuration File
    1$
    2
    3 #Skeleton UBBCONFIG file for the BEA Tuxedo Simple Application.
    4 #Replace the <bracketed> items with the appropriate values.
    5 RESOURCES
    6 IPCKEY            <Replace with valid IPC Key greater than 32,768>
    7
    8 #Example:
    9
    10 #IPCKEY 62345
    11
    12 MASTER simple
    13 MAXACCESSERS 5
    14 MAXSERVERS 5
    15 MAXSERVICES 10
    16 MODEL SHM
    17 LDBAL N
    18
    19 *MACHINES
    20
    21 DEFAULT:
    22
    23                           APPDIR="<Replace with the current pathname>"
    24             TUXCONFIG="<Replace with TUXCONFIG Pathname>"
    25         UXDIR="<Root directory of Tuxedo (not /)>"
    26 #Example:
    27 #       APPDIR="/usr/me/simpdir"
    28 #       TUXCONFIG="/usr/me/simpdir/tuxconfig"
    29 #       TUXDIR="/usr/tuxedo"
    30
    31 <Machine-name> LMID=simple
    32 #Example:
    33 #tuxmach LMID=simple
    34 *GROUPS
    35 GROUP1
    36              LMID=simple GRPNO=1 OPENINFO=NONE
    37
    38 *SERVERS
    39 DEFAULT:
    40              CLOPT="-A"
    41 simpserv SRVGRP=GROUP1 SRVID=1
    42 *SERVICES
    43 TOUPPER
  3. For each <string> (that is, for each string shown between angle brackets), substitute an appropriate value.

How to Load the Configuration File

  1. Run tmloadcf to load the configuration file:
  2. $ tmloadcf ubbsimple
    Initialize TUXCONFIG file: /usr/me/simpdir/tuxconfig [y, q] ? y
    $
  3. Check the results:
  4. $ ls -l
    total 216
    -rwxr-x--x 1 usrid grpid 313091 May 28 15:41 simpcl
    -rw-r----- 1 usrid grpid 1064 May 28 07:51 simpcl.c
    -rwxr-x--x 1 usrid grpid 358369 May 29 09:00 simpserv
    -rw-r----- 1 usrid grpid 275 May 28 08:57 simpserv.c
    -rw-r----- 1 usrid grpid 106496 May 29 09:27 tuxconfig
    -rw-r----- 1 usrid grpid 382 May 29 09:26 ubbsimple

You now have a file called TUXCONFIG. The TUXCONFIG file is a new file under the control of the Oracle Tuxedo system.

See Also

 


Step 5: How to Boot the Application

  1. Execute tmboot to bring up the application:
  2. $ tmboot
    Boot all admin and server processes? (y/n): y
    Booting all admin and server processes in /usr/me/simpdir/tuxconfig
    Booting all admin processes ...
    exec BBL -A:
    process id=24223 ... Started.
    Booting server processes ...
       exec simpserv -A :
    process id=24257 ... Started.
    2 processes started.
    $

The BBL is the administrative process that monitors the shared memory structures in the application. simpserv is the simpapp server that runs continuously, awaiting requests.

See Also

 


Step 6: How to Execute the Run-time Application

To execute your simpapp, have the client submit a request.

$ simpcl “hello, world”
Returned string is: HELLO, WORLD

See Also

 


Step 7: How to Monitor the Run-time Application

As the administrator, you can use the tmadmin command interpreter to check an application and make dynamic changes. To run tmadmin, you must have the TUXCONFIG environment variable set.

tmadmin can interpret and run over 50 commands. For a complete list, see tmadmin(1). The following uses two of the tmadmin commands.

  1. Enter the following command:
  2. $ tmadmin

    The following lines are displayed:

    tmadmin - Copyright (c) 1999 BEA Systems, Inc. All rights reserved.
    >
Note: The greater-than sign (>) is the tmadmin prompt.
  1. Enter the printserver(psr) command to display information about servers:
  2. > psr
    a.out Name Queue Name Grp Name ID RqDone Load Done Current Service
    ---------- ---------- -------- -- ------ --------- ---------------
    BBL 531993 simple 0 0 0 ( IDLE )
    simpserv 00001.00001 GROUP1 1 0 0 ( IDLE )
    >
  3. Enter the printservice(psc) command to display information about the services:
  4. > psc
    Service Name Routine Name a.out Name Grp Name ID Machine # Done Status
    ------------ ------------ ---------- -------- -- ------- ------ ------
    TOUPPER TOUPPER simpserv GROUP1 1 simple - AVAIL
    >

See Also

 


Step 8: How to Shut Down the Application

  1. Run tmshutdown to bring down the application:
  2. $ tmshutdown
    Shutdown all admin and server processes? (y/n): y
    Shutting down all admin and server processes in /usr/me/simpdir/tuxconfig
    Shutting down server processes ...
    Server Id = 1 Group Id = GROUP1 Machine = simple:    shutdown succeeded.
    Shutting down admin processes ...
    Server Id = 0 Group Id = simple Machine = simple:    shutdown succeeded.
    2 processes stopped.
    $
  3. Check the ULOG:
  4. $ cat ULOG*
    $
    113837.tuxmach!tmloadcf.10261: CMDTUX_CAT:879: A new file system has been created. (size = 32 4096-byte blocks)
    113842.tuxmach!tmloadcf.10261: CMDTUX_CAT:871: TUXCONFIG file /usr/me/simpdir/tuxconfig has been created
    113908.tuxmach!BBL.10768: LIBTUX_CAT:262: std main starting
    113913.tuxmach!simpserv.10925: LIBTUX_CAT:262: std main starting
    113913.tuxmach!simpserv.10925: Welcome to the simple server
    114009.tuxmach!simpserv.10925: LIBTUX_CAT:522: Default tpsvrdone() function used.
    114012.tuxmach!BBL.10768: CMDTUX_CAT:26: Exiting system

See Also


  Back to Top       Previous  Next