Tutorials for Developing Tuxedo ATMI Applications
This topic includes the following sections:
simpapp
is a sample ATMI application that includes one client and one server. This application is distributed with the BEA Tuxedo software. The server performs only one service: it accepts a lowercase alphabetic string from the client and returns the same string in uppercase.
This topic is a tutorial that leads you, step-by-step, through the process of developing and running a sample BEA Tuxedo ATMI application. The following flowchart summarizes the process. Click on each task for instructions on completing that task.
Figure 2-1 simpapp Development Process
Before you can run this tutorial, the BEA 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 BEA Tuxedo directory structure so you can copy simpapp
files and execute BEA Tuxedo commands.
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.
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 BEA Tuxedo applications—client processes, server processes, and a configuration file—and you will know how to use BEA Tuxedo system commands to manage your application.
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.
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
.
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 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.
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.
$ 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.
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,
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 BEA TUXEDO */
58 tpfree(sendbuf);
59 tpfree(rcvbuf);
60 tpterm();
61 }
buildclient -o simpcl -f simpcl.c
$ 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
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
#else14
tpsvrinit(argc, argv)15
int argc;16
char **argv;17
#endif18
{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 __cplusplus32
extern "C"33
#endif34
void35
#if defined(__STDC__) || defined(__cplusplus)36
TOUPPER(TPSVCINFO *rqst)37
#else38
TOUPPER(rqst)39
TPSVCINFO *rqst;40
#endif41
{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
}
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.
$ 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
.
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 TUXDIR="<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
$ tmloadcf ubbsimple
Initialize TUXCONFIG file: /usr/me/simpdir/tuxconfig [y, q] ? y
$
$ 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 BEA Tuxedo system.
$ 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.
To execute your simpapp
, have the client submit a request.
$ simpcl "hello, world"
Returned string is: HELLO, WORLD
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.
Note: The greater-than sign (>) is the tmadmin
prompt.
> 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 )
>
> psc
Service Name Routine Name a.out Name Grp Name ID Machine # Done Status
------------ ------------ ---------- -------- -- ------- ------ ------
TOUPPER TOUPPER simpserv GROUP1 1 simple - AVAIL
>
$ 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.
$
$ 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