[Top] [Prev] [Next] [Bottom]

1. A Simple Application


About This Guide

This is the BEA TUXEDO Application Development Guide. Its purpose is to describe how to put together a working BEA TUXEDO application so you can more easily develop applications of your own. The sample applications simpapp and bankapp come with the software. simpapp is described in Chapter 1 and bankapp is used as an example throughout the remainder of the guide.

Organization of the Guide

The BEA TUXEDO Application Development Guide consists of the following ten chapters:

Assumptions

We assume that readers of this guide are UNIX system users with some experience in application development, administration, or programming. We also assume some familiarity with the nature of BEA TUXEDO software, at least as much as can be gained by reading the BEA TUXEDO Product Overview.

An SDK license is required to build BEA TUXEDO applications.

Documentation Roadmap

In addition to describing how to bring up and run a sample application, in this book we hope to familiarize you with the rest of the BEA TUXEDO documentation set. To that end, most chapters in this book close with a section that refers to other guides where the topics of that chapter are dealt with in more detail. In most cases, we do not think you will have to refer to other documents to bring up bankapp successfully, but when you do run into topics on which you would like more information, you can follow those pointers.

About This Chapter

This chapter contains a tutorial that describes a simple one-client, one-server application called simpapp. An interactive form of this application is distributed with the BEA TUXEDO software.

If you follow the ten steps of the tutorial you will do the following:

Some Preliminaries

Before you can run this tutorial the BEA TUXEDO software must be installed so that the files and commands referred to in this chapter are available.

If you are personally responsible for installing the BEA TUXEDO software, consult the BEA TUXEDO Installation Guide for information about how to install the BEA TUXEDO system.

If the installation has already been done by someone else, you need to know the pathname of the directory of the installed software (TUXDIR). You also need to have read and execute permissions on the directories and files in the BEA TUXEDO directory structure so you can copy simpapp files and execute BEA TUXEDO commands.

The simpapp Tutorial

simpapp is a very basic BEA TUXEDO application. It has one client and one server. The server performs only one service: it accepts a string from the client and returns the same string in upper case.

The tutorial consists of ten steps designed to introduce you to the BEA TUXEDO system by showing how an application is developed and by encouraging you to bring the application up and run it. Each of the ten steps includes one or more smaller steps.

Step 1: Copy the simpapp Files

  1. Make a directory for simpapp and cd to it.

    mkdir simpdir
    cd simpdir

    This is suggested so you will be able to see clearly 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; not csh.

  2. Set and export environment variables.

    TUXDIR=<pathname of the BEA 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 BEA TUXEDO system directory structure and to execute BEA TUXEDO system commands. On SunOS, /usr/5bin must be the first directory in your PATH. With AIX on the RS6000, use LIBPATH instead of LD_LIBRARY_PATH. On HPUX on the HP9000, use SHLIB_PATH instead of LD_LIBRARY_PATH.

    You need to set TUXCONFIG to be able to load the configuration file, which is described in "Step 7: Load the Configuration File."

  3. Copy the simpapp files.

    cp $TUXDIR/apps/simpapp/*.

    Note: Later on you will edit some of the files and make them executable, so it is best to begin with a copy of the files rather than the originals delivered with the software.

  4. List the files.

    $ ls
    README env simpapp.nt ubbmp wsimpcl
    README.as400 setenv.cmd simpcl.c ubbsimple
    README.nt simpapp.mk simpserv.c ubbws
    $

    The three files that are central to the application are:

Except for the README files, the other files are variations of these for non-UNIX system platforms. The README files provide explanations of the other files.

Step 2: Examine the Client Program

  1. Page through the client program source code.

    $ more simpcl.c

    The output is shown in Listing 1-1.

    Listing 1-1 Source Code of simpcl.c
    1     #include <stdio.h>           /* UNIX */
    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 System/T 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,
    49 tmemsgs[tperrno]);
    50 tpfree(sendbuf);
    51 tpfree(rcvbuf);
    52 tpterm();
    53 exit(1);
    54 }
    55 printf("Returned string is: %s\n", rcvbuf);
    56
    57 /* Free Buffers & Detach from System/T */
    58 tpfree(sendbuf);
    59 tpfree(rcvbuf);
    60 tpterm();
    61 }

Here are eight important things to see in this file.

line 2

atmi.h

Header file needed whenever BEA TUXEDO ATMI calls are used

line 28

tpinit()

The ATMI call used by a client program to join an application

line 33

tpalloc()

The ATMI call used to allocate a typed buffer. STRING is one of the four basic BEA TUXEDO buffer types; NULL indicates there is no sub-type argument. The remaining argument, sendlen + 1, specifies the length of the buffer plus 1 for the null character that ends the string.

line 38

tpalloc()

Allocates another buffer for the return message

line 45

tpcall()

Sends the message buffer to the service specified in the first argument. Also includes the address of the return buffer. tpcall waits for a return message.

lines 35, 41, 52, 60

tpterm()

The ATMI call used to leave an application. A call to tpterm() is used to leave the application prior to taking an exit due to an error condition (lines 36, 42, and 53). The final tpterm() (line 60) comes after the message has been printed.

lines 40, 50, 51, 58, 59

tpfree()

The counterpart of tpalloc() to free allocated buffers.

line 55

printf()

This is the successful conclusion of the program. It prints out the message returned from the server.

References

The ATMI calls cited above are documented in Section 3c of the BEA TUXEDO Reference Manual.

Step 3: Compile the Client

  1. Run buildclient to compile the client program.

    buildclient -o simpcl -f simpcl.c

    where the output file is simpcl, and the input source file is simpcl.c.

  2. Check the results.

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

References

buildclient is documented in buildclient(1).

Step 4: Examine the Server

  1. Page through the server program source code.

    $ more simpserv.c

    Listing 1-2 Source Code of simpserv.c
    #include <stdio.h>
    #include <ctype.h>
    #include <atmi.h> /* TUXEDO Header File */
    #include <userlog.h> /* TUXEDO Header File */
    /* 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.
    */
    #if defined(__STDC__) || defined(__cplusplus)
    Note 1. tpsvrinit(int argc, char *argv[])
    #else
    tpsvrinit(argc, argv)
    int argc;
    char **argv;
    #endif
    {
    /* Some compilers warn if argc and argv aren't used. */
    argc = argc;
    argv = argv;
    /* userlog writes to the central TUXEDO message log */
    userlog("Welcome to the simple server");
    return(0);
    }
    /* 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.
    */
    #ifdef __cplusplus
    extern "C"
    #endif
    void
    #if defined(__STDC__) || defined(__cplusplus)
    Note 2. TOUPPER(TPSVCINFO *rqst)
    #else
    TOUPPER(rqst)
    TPSVCINFO *rqst;
    #endif
    {
    int i;
    Note 3. for(i = 0; i < rqst->len-1; i++)
    rqst->data[i] = toupper(rqst->data[i]);
    /* Return the transformed buffer to the requester. /
         Note 4.         tpreturn(TPSUCCESS, 0, rqst->data, 0L, 0);
    }
    #include stdio.h>
    }

Here are five important things to see in this file.

whole file

Notice that a BEA TUXEDO server does not contain a main(). The main() is provided by the BEA TUXEDO system when the server is built.

Note 1

tpsvrinit()

This subroutine is called during server initialization, before the server begins processing service requests. A default (provided by the BEA TUXEDO system) writes a message to userlog indicating that the server has been booted. userlog(3c) is a log that is used by the BEA TUXEDO system and can be used by applications. We will see the format in Step 10.

Note 2

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.

Note 3

for loop

Converts the input to uppercase by repeated calls to toupper.

Note 4

tpreturn

Returns the converted string to the client with the TPSUCCESS flag set.

References

The ATMI calls and structure cited above are documented in Section 3c of the BEA TUXEDO Reference Manual.

Step 5: Compile the Server

  1. Run buildserver to compile the server program:

    buildserver -o simpserv -f simpserv.c -s TOUPPER

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

  2. Check the results.

    $ 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

    As can be seen, we now have an executable module called simpserv.

References

buildserver is documented in buildserver(1).

Step 6: Edit the Configuration File

  1. Edit the file.

    Listing 1-3 The simpapp Configuration File
    $ vi ubbsimple
    #Skeleton UBBCONFIG file for the BEA TUXEDO Simple Application.
    #Replace the <bracketed> items with the appropriate values.
    *RESOURCES
    IPCKEY <Replace with valid IPC Key greater than 32,768>
    #Example:
    #IPCKEY 62345
    MASTER            simple
    MAXACCESSERS 5
    MAXSERVERS 5
    MAXSERVICES 10
    MODEL SHM
    LDBAL N
    *MACHINES
    DEFAULT:
    APPDIR="<Replace with the current pathname>"
    TUXCONFIG="<Replace with TUXCONFIG Pathname>"
    TUXDIR="<Root directory of TUXEDO (not /)>"
    #Example:
    # APPDIR="/usr/me/simpdir"
    # TUXCONFIG="/usr/me/simpdir/tuxconfig"
    # TUXDIR="/usr/tuxedo"
    <Machine-name>    LMID=simple
    #Example:
    #tuxmach LMID=simple
    *GROUPS
    GROUP1
    LMID=simple GRPNO=1 OPENINFO=NONE
    *SERVERS
    DEFAULT:
    CLOPT="-A"
    simpserv          SRVGRP=GROUP1 SRVID=1
    *SERVICES
    TOUPPER

  2. Change values enclosed in angle brackets to your own local values:

    IPCKEY

    Use a value that will not conflict with any other users

    TUXCONFIG

    Provide the full pathname of the binary tuxconfig file to be created in Step 7

    TUXDIR

    Provide the full pathname of your BEA TUXEDO root directory

    APPDIR

    Provide the full pathname of the directory where you intend to boot the application; in this case, the current directory

    machine-name

    Provide the machine name as returned by uname -n

  3. The pathnames for TUXCONFIG and TUXDIR must be identical to those you set and exported in Step 1.2. The strings must be the actual values; environment variables (like $TUXCONFIG, for example) are not acceptable.

    Note: Do not forget to remove the angle brackets.

References

The configuration file is documented in ubbconfig(5).

Step 7: Load the Configuration File

  1. Run tmloadcf to load the configuration file.

    $ tmloadcf ubbsimple
    Initialize TUXCONFIG file: /usr/me/simpdir/tuxconfig [y, q] ? y
    $

  2. Check the results.

    $ 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

    We see that we now have a file called tuxconfig. The tuxconfig file is a new file system under the control of the BEA TUXEDO system.

References

tmloadcf is documented in tmloadcf(1).

Step 8: Boot the Application

  1. Execute tmboot to bring up the application.

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

BBL is the administrative process that monitors the application shared memory structures. simpserv is our server that runs continuously awaiting requests.

References

tmboot is documented in tmboot(1).

Step 9: Enter a Request

  1. Run the client program to submit a request.

    $ simpcl "hello, world"
    Returned string is: HELLO, WORLD

We are successful!

Step 10: Using tmadmin

tmadmin is an interactive program that an administrator can use to check an application and make dynamic changes. It requires the TUXCONFIG variable to be set. We will show you just two of the many tmadmin commands.

  1. Enter the following command.

    $ tmadmin

    You will see the following lines.

    tmadmin - Copyright (c) 1998 BEA Systems, Inc. All rights reserved.
    >

    The greater-than sign (>) is the tmadmin prompt.

  2. Enter the printserver(psr) command to display information about the servers.

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

    > psc
    Service Name Routine Name a.out Name Grp Name ID Machine # Done Status
    ------------ ------------ ---------- -------- -- ------- ------ ------
    TOUPPER TOUPPER simpserv GROUP1 1 simple - AVAIL
    >

  4. Leave tmadmin by entering a q at the prompt. You can boot and shut down the application from within tmadmin. We have done those functions with shell commands in Step 8 and Step 11, respectively.

References

tmadmin is documented in tmadmin(1).

Step 11: Shut Down the Application

  1. Run tmshutdown to bring the application down.

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

  2. Check the ULOG.

    $ 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

    Each line of the ULOG for this session contains something of interest. Most are self-explanatory, but we want to add some explanation for a couple of them. First let's look at the format of a ULOG line.

    time (hhmmss).machine_uname!process_name.process_id: log message

    Now let's look at some individual lines.

    113913.Message from tpsvrinit() in simpserv
    114009.When simpserv is shutdown the BEA TUXEDO main sends this message

References

tmshutdown is documented in tmshutdown(1).

The userlog is documented in userlog(3c).

Summary

If you have reached this point, you have successfully brought up, run, and brought down a BEA TUXEDO system application. You have seen what a client program and a server look like. You have edited a configuration file to refer to your own environment. You have invoked tmadmin to check on the activity of your application. In all the applications you may work on in the future the basic elements of client processes, server processes, and a configuration file will be present, and you will have all of the BEA TUXEDO shell commands at your fingertips.

Good luck!



[Top] [Prev] [Next] [Bottom]