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.
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.
The runsample script contains several commands; each command is preceded by a comment line that describes the purpose of the command.
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.
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.
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.
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.
The -y option keeps
tmboot from prompting for an okay before booting.
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 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.
