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.

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.

The following procedure provides instructions on building and running the qsample application.

1. Make a directory for qsample and cd to it:

   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).
2. Copy the qsample files.

   cp $TUXDIR/apps/qsample/*

   You can edit 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.
3. List the files.

   $ ls
   README
   client.c
   crlog
   crque
   makefile
   rmipc
   runsample
   server.c
   setenv
   ubb.sample
   $

   The files that make up the application are:

   README

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

   setenv

   A script that sets environment variables.

   crlog

   A script that creates a TLOG file.

   crque

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

   makefile

   A makefile that creates the executables for the application.

   client.c

   The source code for the client program.

   server.c

   The source code for the server program.

   ubb.sample

   The ASCII form of the configuration file for the application.

   runsample

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

   rmipc

   A script that removes the IPC resources for the queue space.

4. Edit the setenv file. 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.
5. Run runsample. 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};
   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. You should check out and try a few things on this topic; as you get more familiar with the application, you are likely to discover additional items.

• setenv: Set the Environment
  
• makefile: Make Your Application
  
• ubb.sample: The ASCII Configuration File
  
• crlog: Create the Transaction Log
  
• crque: Create the Queue Space and Queues
  
• Boot, Run, and Shut Down the Application
  
• Clean Up