Using the ATMI /Q Component

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

A Sample Application

This topic includes the following sections:



The sample application in this topic contains a description of a one-client, one-server application using Oracle Tuxedo /Q called qsample. An interactive form of this software is distributed with the Oracle Tuxedo software.



Before you can run the sample application, the Oracle 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 Oracle Tuxedo software, consult the Installing the Oracle Tuxedo System for information about how to install the Oracle 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 Oracle Tuxedo directory structure so you can copy qsample files and execute Oracle Tuxedo commands.


What Is qsample?

qsample is a very basic Oracle Tuxedo application that uses Oracle 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.

  1. Make a directory for qsample and cd to it:
  2. 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).

  3. Copy the qsample files.
  4. 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.

  5. List the files.
  6. $ ls

    The files that make up the application are:


A file that describes the application and how to configure and run it.


A script that sets environment variables.


A script that creates a TLOG file.


A script that defines the queue space and queues for the application.


A makefile that creates the executables for the application.


The source code for the client program.


The source code for the server program.


The ASCII form of the configuration file for the application.


A script that calls all the necessary commands to build and run the sample application.


A script that removes the IPC resources for the queue space.
  1. Edit the setenv file.
  2. Open the setenv file and modify the TUXDIR value to the absolute path of the root directory of the Oracle Tuxedo system installation. Remove the angle bracket characters (< and >) when editing this value.

  3. Run runsample.
  4. 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="`uname -n`"
    ed ubb.sample<<!
    g;<uname -n>;s;;${uname};
    g;<full path of Tuxedo software>;s;;${TUXDIR};
    g;<full path of APPDIR>;s;;${APPDIR};
    #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
    #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*

    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 Oracle Tuxedo development. Three of the variables that are set (TUXDIR, APPDIR, and PATH) are needed whenever you are working with the Oracle 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 Oracle 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 Oracle 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:
# Then the CLOPT parameter from TMQFORWARD:
CLOPT="-- -i 2 -q STRING"
# Finally, the OPENINFO parameter from the QUE1 group:

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:


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 Oracle 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.

  Back to Top       Previous  Next