|
|
 |
| e-docs > Tuxedo > Using the ATMI /Q Component > A Sample Application |
|
Using the ATMI /Q Component
|
A Sample Application
This topic includes the following sections:
Overview
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.
Prerequisites
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.
What Is qsample?
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.
Building qsample
The following procedure provides instructions on building and running the qsample application.
mkdir qsampdir
cd qsampdir
cp $TUXDIR/apps/qsample/* .
$ ls
README
client.c
crlog
crque
makefile
rmipc
runsample
server.c
setenv
ubb.sample
$
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.
Suggestions for Further Exploration
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.
setenv: Set the Environment
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?
makefile: Make Your Application
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.
ubb.sample: The ASCII Configuration File
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.
crlog: Create the Transaction Log
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.
crque: Create the Queue Space and Queues
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.
Boot, Run, and Shut Down the Application
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.
Clean Up
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.
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
