About This Guide

This is the TUXEDO System/T Application Development Guide. Its purpose is to describe how to put together a working TUXEDO System/T application so that 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 Application Development Guide consists of ten chapters.

Chapter 1

as noted above, tells how to install and run simpapp on your system.

Chapter 2

lists the files that are delivered with bankapp and tells how to set the environment.

Chapter 3

describes the client programs of bankapp.

Chapter 4

describes the service subroutines of bankapp.

Chapter 5

describes how to edit the file bankapp.mk and make bankapp.

Chapter 6

describes how to create the database that bankapp was written for and how to integrate other resource managers with the system.

Chapter 7

tell how to edit the bankapp configuration files for your installation.

Chapter 8

describes how to load the configuration file, create the transaction log and start the System/T network listener process.

Chapter 9

tells how to boot the application and populate the database.

Chapter 10

tells how to run the application.

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 TUXEDO System/T software, at least as much as can be gained by reading the BEA TUXEDO Product Overview.

An SDK license is required to build 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 System/T documentation set. To that end, most chapters in the 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 bankapp up 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 simpapp. An interactive form of this application is distributed with the TUXEDO System/T software.

If you follow the ten steps of the tutorial you will;

• learn how a System/T application is organized

• see how clients and servers are written and compiled

• understand how an application is described in the configuration file

• actually create an executable version of simpapp

• boot, run and shutdown the application

Some Preliminaries

Before you can run this tutorial the TUXEDO System/T 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 TUXEDO System/T software, consult the BEA TUXEDO Installation Guide for information about how to install System/T.

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 TUXEDO System/T directory structure so you can copy simpapp files and execute System/T commands.

The simpapp Tutorial

simpapp is a very basic TUXEDO System/T 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 TUXEDO System/T 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

Step 1.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.

Step 1.2

Set and export environment variables

TUXDIR=<pathname of the TUXEDO System/T 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 TUXEDO System/T directory structure and to execute TUXEDO System/T commands. On SunOS, /usr/5bin must be the first directory in your PATH. With AIX on the RS6000, LIBPATH is used instead of LD_LIBRARY_PATH. With HPUX on the HP9000, SHLIB_PATH is used instead of LD_LIBRARY_PATH. You need to set TUXCONFIG to be able to load the configuration file, which is described in Step 7.

Step 1.3

Copy the simpapp files.

cp $TUXDIR/apps/simpapp/* .

Later on you will be editing some of the files and making them executable, so it is best to begin with a copy of the files rather than the originals delivered with the software.

Step 1.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:

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

The other files are variations of these for platforms other than Unix. The README files explain.

Step 2: Examine the Client Program

Step 2.1

Page through the client program source code:

$ more simpcl.c

The output is shown in Figure 1.

Fig. 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 System/T 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 System/T 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 & 53). The final tpterm() (line 59) 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 the BEA TUXEDO Reference Manual: Section 3c

Step 3: Compile the Client

Step 3.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.

Step 3.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 file sizes shown above may not be what you see on your system.

References

buildclient is documented in buildclient(1)

Step 4: Examine the server

Step 4.1

Page through the server program source code:

$ more simpserv.c

Fig. 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 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);
	}

Here are five important things to see in this file:

whole file		notice that a TUXEDO System/T server does not contain a main(). The main() is provided by System/T when the server is built.
Note 1.	tpsvrinit()	this subroutine is called during server initialization, before the server begins processing service requests. A default is provided by System/T that writes a message to userlog indicating that the server has been booted. userlog(3c) is a log that is used by System/T and can be used by applications. We'll 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 the BEA TUXEDO Reference Manual: Section 3c

Step 5: Compile the Server

Step 5.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.

Step 5.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.

The file sizes shown above may not be what you see on your system.

References