Using the ATMI /Q Component
This topic includes the following sections:
The sample application in this topic contains a description of a one-client, one-server application using BEA Tuxedo /Q called qsample
. An interactive form of this software is distributed with the BEA Tuxedo software.
Before you can run the sample application, the BEA Tuxedo software must be installed and built so that the files and commands referred to in this topic are available. If you are personally responsible for installing the BEA Tuxedo software, consult the Installing the BEA Tuxedo System 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 qsample
files and execute BEA Tuxedo commands.
qsample
is a very basic BEA Tuxedo application that uses BEA Tuxedo /Q. It has one application client and server, and uses two system servers. TMQUEUE(5) and TMQFORWARD(5). 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.
The following procedure provides instructions on building and running the qsample
application.
mkdir qsampdir
cd qsampdir
This is suggested so you will be able to see clearly the qsample
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
).
cp $TUXDIR/apps/qsample/* .
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.
$ ls
README
client.c
crlog
crque
makefile
rmipc
runsample
server.c
setenv
ubb.sample
$
Open the setenv
file and modify the TUXDIR
value to the absolute path of the root directory of the BEA Tuxedo system installation. Remove the angle bracket characters (<
and >
) when editing this value.
The runsample
script contains several commands; each command is preceded by a comment line that describes the purpose of the command.
#set the environment
. ./setenv
chmod +w ubb.sample
uname="\Quname -n\Q"
ed ubb.sample<<!
g;<uname -n>;s;;${uname};
g;<full path of Tuxedo software>;s;;${TUXDIR};
g;<full path of APPDIR>;s;;${APPDIR};
w
q
!
#build the client and server
make client server
#create the tuxconfig file
tmloadcf -y ubb.sample
#create the TLOG
./crlog
#create the QUE
./crque
#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
./rmipc
#remove all files created
rm tuxconfig QUE stdout stderr TLOG ULOG*
When you run this script you will see a series of messages on your screen that are generated by the various commands. Included among them are the following lines:
before: this is a q example
after: THIS IS A Q EXAMPLE
The before:
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 topic, we suggest some things that 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
, SHLIB_PATH
, or LIBPATH
are important if you are building the system with shared libraries. The correct variable to use depends on your operating system. 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 /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 /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.