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 The BEA TUXEDO Application Development Guide consists of the following ten chapters:
About This Guide
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
simpapp on your system.
bankapp and tells how to set the environment
bankapp
bankapp
bankapp.mk and make bankapp
bankapp was written for and how to integrate other resource managers with the system
bankapp configuration file for your installation
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.
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.
This chapter contains a tutorial that describes a simple one-client, one-server application called If you follow the ten steps of the tutorial you will do the following:
Assumptions
Documentation Roadmap
About This Chapter
simpapp. An interactive form of this application is distributed with the BEA TUXEDO software.
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 ( 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.
Some Preliminaries
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.
Step 1: Copy the simpapp Files
simpapp and cd to it.
This is suggested so you will be able to see clearly the mkdir simpdir
cd simpdirsimpapp 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.
You need You need to set 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_PATHTUXDIR 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.
TUXCONFIG to be able to load the configuration file, which is described in "Step 7: Load the Configuration File."
simpapp files.
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.
cp $TUXDIR/apps/simpapp/*.
The three files that are central to the application are:
$ ls
README env simpapp.nt ubbmp wsimpcl
README.as400 setenv.cmd simpcl.c ubbsimple
README.nt simpapp.mk simpserv.c ubbws
$
simpcl.c-the source code for the client program
simpserv.c-the source code for the server program
ubbsimple-the ASCII form of the configuration file for the application
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.
The output is shown in Listing 1-1.
$ more simpcl.c
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.
The ATMI calls cited above are documented in Section 3c of the BEA TUXEDO Reference Manual.
References
Step 3: Compile the Client
buildclient to compile the client program.
where the output file is buildclient -o simpcl -f simpcl.c
simpcl, and the input source file is simpcl.c.
As can be seen, we now have an executable module called $ 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 ubbsimplesimpcl. The size of simpcl may vary.
buildclient is documented in buildclient(1).
$ 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.
The ATMI calls and structure cited above are documented in Section 3c of the BEA TUXEDO Reference Manual.
References
Step 5: Compile the Server
buildserver to compile the server program:
where the executable file to be created is named buildserver -o simpserv -f simpserv.c -s TOUPPER
simpserv, and simpserv.c is the input source file. The -s TOUPPER option specifies the service to be advertised when the server is booted.
As can be seen, we now have an executable module called $ 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 ubbsimplesimpserv.
buildserver is documented in buildserver(1).
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 62345MASTER 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
The configuration file is documented in ubbconfig(5).
tmloadcf to load the configuration file.
$ tmloadcf ubbsimple
Initialize TUXCONFIG file: /usr/me/simpdir/tuxconfig [y, q] ? y
$
We see that we now have a file called $ 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 ubbsimpletuxconfig. The tuxconfig file is a new file system under the control of the BEA TUXEDO system.
tmloadcf is documented in tmloadcf(1).
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/tuxconfigBooting 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.
tmboot is documented in tmboot(1).
We are successful!
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.
You will see the following lines.
The greater-than sign ($ tmadmin
tmadmin - Copyright (c) 1998 BEA Systems, Inc. All rights reserved.
>
>) is the tmadmin prompt.
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 )
>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
>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.
tmadmin is documented in tmadmin(1).
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/tuxconfigShutting 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.
$ULOG.
Each line of the Now let's look at some individual lines.
$ 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 systemULOG 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
113913.Message from tpsvrinit() in simpserv
114009.When simpserv is shutdown the BEA TUXEDO main sends this message
tmshutdown is documented in tmshutdown(1).
The userlog is documented in userlog(3c).
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!