This appendix contains a description of a one-client, one-server application using BEA TUXEDO System/Q called Before you can run this example the BEA TUXEDO software must be installed and built 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 root directory of the installed software. You also need to have read and execute permissions on the directories and files in the BEA TUXEDO directory structure so you can copy q What follows is a procedure to build and run the example.
What This Appendix Is About
qsample. An interactive form of this software is distributed with the BEA TUXEDO software.
Some Preliminaries
sample files and execute BEA TUXEDO commands.
The qsample Application
qsample is a very basic BEA TUXEDO application that uses BEA TUXEDO System/Q. It has one application client and server, and uses two system servers. TMQUEUE and TMQFORWARD. The client calls TMQUEUE to enqueue a message in a queue space created for qsample. The message is dequeued by TMQFORWARD and passed to the application server. The server converts a string from lower case to upper case and returns to TMQFORWARD. TMQFORWARD enqueues the reply message. The client meanwhile has called TMQUEUE to dequeue the reply. When the reply is received, the client displays it on the user's screen.
qsample and cd to it:
This is suggested so you will be able to see clearly the mkdir qsampdir
cd qsampdirqsample 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 the C shell (/bin/csh).
qsample files.
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.
cp $TUXDIR/apps/qsample/* .
The files that make up the application are:
$ ls
README
client.c
crlog
crque
makefile
rmipc
runsample
server.c
setenv
ubb.sample
$
README
setenv
crlog
TLOG file
crque
makefile
client.c
server.c
ubb.sample
runsample
rmipc
Five of the files have location-specific entries that you must edit to provide your own directory pathnames and machine name.
The text to be replaced is enclosed in angle brackets. You need to substitute the absolute path for Here is a summary of the required values:
TUXDIR and APPDIR, and the machine name of the machine you are running on.
TUXDIR
APPDIR
machine
uname -n command (where uname is supported on the target platform).
The six files that must be edited (and the value that you must put in) are:
crlogAPPDIR pathnamecrqueAPPDIR pathnamemakefileTUXDIR pathnamermipcAPPDIR pathnameubb.sampleTUXDIR pathname,APPDIR pathname,machine namesetenvTUXDIR pathname
runsample.
The When you run this script you will see a series of messages on your screen that are output by the various commands. Included among them are the following lines.
The runsample script contains 11 commands; each command is preceded by a comment line that says what the command does.
#set the environment
. ./setenv
#build the client and server
make client server
#create the tuxconfig file
tmloadcf -y ubb.sample
#create the TLOG
#create the QUE
#boot the application
tmboot -y
#run the client
client
#shutdown the application
tmshutdown -y
#remove the client and server
make clean
#remove the QUE ipc resources
#remove all files created
rm tuxconfig QUE stdout stderr TLOG ULOG*before: this is a q example
after: THIS IS A Q EXAMPLEbefore: line is a copy of the string that client enqueues for processing by server. The after: line is what server sends back. These two lines prove that the program worked successfully.
While it might prove interesting to build and run the sample application using runserver, you will probably find it more instructive to examine the individual pieces of the application. In this section we suggest some things we recommend you look at and try; you will undoubtedly be able to think of others as you explore the application more closely.
The script setenv is an example of a file often used in BEA TUXEDO development. Three of the variables that are set (TUXDIR, APPDIR, and PATH) are needed whenever you are working with the BEA TUXEDO system. Notice that if you are running on a SUN machine, there is another bin you must have at the beginning of your PATH variable. LD_LIBRARY_PATH is important if you are building the system with shared libraries. TUXCONFIG must be set before you can boot the system. QMADMIN can be set in a variable or provided on the qmadmin(1) command line.
Points to consider: should you plan to have such a file where you will be doing your BEA TUXEDO System/Q work? Should you have a command in your .profile so that you set your environment as you log in?
Notice that the makefile uses buildserver(1) and buildclient(1) to build the server and client, respectively. You can, of course, execute these commands individually or use the capability of make to keep the application current.
While we are on the subject of the makefile, this might be a good time to look through the .c files for the client and server programs. Of particular interest in connection with BEA TUXEDO System/Q are the tpenqueue and tpdequeue calls. Notice particularly the values for the qspace and the qname arguments. When we look at the configuration file, we will see where those values come from.
The three most pertinent entries in the configuration file are the CLOPT parameters for the TMQUEUE and TMQFORWARD servers and the OPENINFO parameter in the *GROUPS entry. We will extract those items to call them to your attention here:
# First the CLOPT parameter from TMQUEUE:
CLOPT = "-s QSPACENAME:TMQUEUE -- "
# Then the CLOPT parameter from TMQFORWARD:
CLOPT="-- -i 2 -q STRING"
# Finally, the OPENINFO parameter from the QUE1 group:
OPENINFO = "TUXEDO/QM:<APPDIR pathname>/QUE:QSPACE"
The CLOPT parameter from TMQUEUE specifies a service alias of QSPACENAME. Look back again at client.c and check the qspace argument of tpenqueue and tpdequeue. The CLOPT parameter for TMQFORWARD specifies a service STRING by means of the -q option. This is also the name given to the queue where messages are enqueued for that service and is specified as the qname argument of tpenqueue in client.c.
The tmloadcf(1) command is used to compile the ASCII configuration file into a TUXCONFIG file.
The script in crlog invokes tmadmin(1) to create a device list entry for the TLOG and then create the log for the site specified in our configuration. Because all messages for the queued message facility are enqueued and dequeued within transactions, you must have a log in which to keep track of transactions managed by the TMS_QM server.
The script in crque invokes qmadmin(1) to create the queue space and queues for the sample application. Notice that the queue space is named QSPACE (that is also the name specified as the last argument of the OPENINFO parameter in the configuration file). Queues named STRING and RPLYQ are created. In the qspacecreate portion of the script an error queue is named, but the script does not include any qcreate command to create that queue. That is a modification you might want to make later.
After making the application programs, loading TUXCONFIG, and creating the queue space and queues, the next step is to boot the application and run it. The command to boot is
tmboot -y
The -y option keeps tmboot from prompting for an okay before booting.
The sample application is run simply by entering the command:
client
The tmshutdown command is used to bring the application down.
The runsample script includes three commands that restore the environment to the state it was in before the script was run. The make clean command uses make to remove the object and executable files for the client and server.
The rmipc command is included because the IPC resources for the queue space are not automatically removed by tmshutdown (which does remove the BEA TUXEDO IPC resources used by the application). If you look at rmipc you will find that it invokes qmadmin and uses its version of the ipcrm command, naming QSPACE to identify resources to be removed.
The final command in the script is the rm command, which removes a number of files that are generated by the application. There is no harm in leaving these files; in fact, as you work more with the sample application you will probably want to keep tuxconfig, QUE, and TLOG to save having to recreate them.