![[ZOIS]](../pics/little.zois.gif){kind=small}
Home Page *
Contact ZOIS *
Technical Notes
ZOIS Technical Note TN-2003-04-14.
Author and Audience
This TN is intended for persons working with BEA's Tuxedo
Transaction Processing Manager. UNIX systems' and C programming skills
are assumed. Written by Martin Sullivan[1],
ZOIS Limited, Cockermouth.
Abstract
BEA's Tuxedo comes with an example program, "Simpapp" which
arguably could be improved upon. This paper presents and discuss one
such version.
Introduction
The standard distribution of BEA's Tuxedo[2] includes and example known as "Simpapp"[3] which has not changed since Tuxedo made its commercial breakthrough on a variety of operating systems at around version 4 in the early 1990s. Simpapp's purpose is to demonstrate the absolute minimum Tuxedo configuration and coding to support the simplest of applications, that of upper-casing an input string. As such it is often studied by people new to Tuxedo and its heritage can be seen in the source code of many third-part Tuxedo programs.
There are two Simpapps, one coded in 'C' and one in COBOL. Only the 'C' one is considered here. The standard Simpapp has a number of short-comings that this paper hopes to address. These are:
Unnecessary configurable compilation. There are a number of "#ifdef" lines in the source code that allow compilation by 'C' compilers ingrorant of ANSI function declaration conventions. Such compilers are now extremely rare and depricated; consiquently the configurable compilation becomes unnecessary.
No database connectivity. Although it is unlikely that Tuxedo would be used without a database the mechanisms needed to connect to such are not shown.
Re-use of the input buffer. It is possible to re-use the input buffer (and Simpapp upper-cases the string in-situ), it is largely inadvisable to re-use the input buffer because of potential size changes.
The Simapp examples makes no use of the preferred Multiple Server Single Queue (MSSQ) configuration.
A simple client is demonstrated. Further work will show that a
variety of client systems may be used to connect to this Simpapp,
demonstrating full end-to-end connectivity.
Materials and Platform
The code for the ZOIS version of Simapp used Tuxedo
6.5 on AIX[4] with Oracle[5] 8.1.7
as the Database. This work has been repeated with other Database
managers; other, newer, versions of Tuxedo and on a variety of
platforms. The ZOIS version of Simpapp still takes a
string of arbitrary length and returns it upper-cased. The actually
upper-casing work is performed by an SQL function, upper.
Method
The code for the ZOIS Simpapp is found in the
downloads area as a compressed tar archive. In most cases it will need
adaption to the environment of the site you are running on. This is
particularly true of the Bulletin Board configuration file. The
naritive in this paper will both explain the steps necessary and the
reasoning behind some of the code. The code is protected by
ZOIS's copyright statement[6], copy it
as you will but give us attribution. You should note our
Source Code Caveats[7] too.
This part deals with the decisions behind certain constructs.
void upper (TPSVCINFO *in)
{
|
Without optional compilation and using ANSI-style function delcarations the code is a lot cleaner.
exec sql select upper (:input)
into :output
from dual;
|
SQL is used to do the actual upper-casing. Since we are using Oracle the select statement needs to operate on table dual.
out = tpalloc ("STRING", NULL, (long) output.len + (long) 1);
|
tpreturn (TPSUCCESS, (long) 0, out, (long) 0, (long) 0); |
Unlike the original Simpapp, ZOIS's Simpapp allocates
a separate return buffer. Overall this is better practice since one no
longer has to concern one self about the size of the input buffer and
if stuff will fit.
croke: userlog (ER_SQL, sql_error ()); tpreturn (TPEXIT, (long) 0, out, (long) 0, (long) 0); |
Although not part of the original Simpapp, this illustrates the use of TPEXIT rather than TPFAIL. The author has become accustom to seeing TPFAIL in such situations but the use of TPEXIT is indicated in failure senarios. This is preferred over using TPFAIL since there may be unwanted bagage (kept when one simply TPFAILs) associated with the failure which could cause the Service to fail again or which may cause it to fail in the future (for example resource leaks such as memory). Hopefully the failures are rare enough that they will not impact performance as Tuxedo starts a new process.
The Bulletin Board Configuration File is found in simpapp.bbcf. The BEA Tuxedo Reference manual refers to this file format as UBBCONFIG[8]. There are a number of changes to the standard Simpapp's configuration and these are:
In the *MACHINES section:-
*MACHINES DEFAULT: APPDIR="/u/sullivan/ns" TUXCONFIG="/u/sullivan/ns/tuxconfig" TUXDIR="/usr/tuxedo" TLOGDEVICE="/u/sullivan/ns/TLOG" TLOGNAME=TLOG "brown.zois.co.uk" LMID=local |
To use a Oracle and drive it through the XA[9] interface it is necessary to build a TLOG device. See the Associated Shell Scripts. Other than this it is necessary if building this oneself to observe:
In the *GROUPS section:-
*GROUPS simpapp LMID=local GRPNO=1 TMSNAME=TMS_ORA TMSCOUNT=2 OPENINFO="Oracle_XA:Oracle_XA+SqlNet=local+ACC=P/scott/tiger+SesTm=120+logDir=/u/sullivan/ns/log+DbgFl=0" wsl LMID=local GRPNO=2 OPENINFO=NONE |
Since we are connecting to Oracle through an XA interface it is necessary to have an Oracle Transaction Manager Server ("TMS_ORA" in our case) and to provide the necessary Oracle XA Open string. Building the Transaction Manager Server is discussed elsewhere in the Oracle Connections section. The OPENINFO string can be constructed by following Oracle's Instructions[10]. One needs to ensure that the the Session Timeout (SesTm) value should be more than the Tuxedo Transaction Timeout, so Tuxedo breaks deadlocks rather than Oracle and this is about 60 seconds in default Tuxedo set-ups such as ours.
Appart from the "simpapp" group a Workstation Listener group has been defined ("wsl").
This leads on to the "*SERVERS" section.
*SERVERS DEFAULT: CLOPT="-A" simpapp SRVGRP=simpapp SRVID=1 MIN=2 MAX=5 RQADDR="simpapp" REPLYQ=Y WSL SRVGRP=wsl SRVID=10 CLOPT="-A -- -n //brown.zois.co.uk:12015" |
Although not configured so in the original Simpapp,
ZOIS's Simpapp server is configured to use a so called
Multiple Server Single Queue (MSSQ) set-up. This is generally
considered the preferred mechanism for a group of servers allowing the
work to be enqueued by Tuxedo for the first available server. It is
achieved by specifying a reply queue. The ZOIS Simpapp
also provides for client connectivity and to this end a WSL server has
been configured.
Finally there is the "*SERVICES" section. The original Simpapp does
not discuss user-controlled Transactions and neither does
ZOIS's. The single service available is thus has
automatic transaction control enabled.
*SERVICES upper AUTOTRAN=Y |
Oracle is connected via SQL*Net and setting this up is as explained in the Oracle literature[10]. Since a transactional interface (XA) is being employed Oracle will need to be defined as a resource for Tuxedo. The following line should thus be added to ${TUXDIR}/udataobj/RM file.
Oracle_XA:xaosw:-L${ORACLE_HOME}/lib -lclntsh
|
It should be emphasised that this line holds for Oracle 8 and subsequent versions may be different. At time of writing Tuxedo continues to be distributed with an RM line for Oracle 7 and this should be commented out. With Oracle defined to Tuxedo it is possible to build the Oracle Transaction Manager Server (ORA_TMS, in this example) by using buildtms:
buildtms -o ORA_TMS -r Oracle_XA |
As with the original Simpapp a shell scripts has been included that automate the installation process, in particular setting up the Transaction Log file, TLOG.
tmadmin <<! echo crdl -b 200 -z /u/sullivan/ns/TLOG crlog -m local q ! |
The source materials have been placed in a tar(1) archive
compressed with compress(1) [11] for the
convenience of the newer Tuxedo user.
Conclusion
It has been found that a large number of Tuxedo sites start with the
Simpapp example and unfortunately as that example is considered faulty
develop a poorly constructed Tuxedo installation. The presented simpapp
example should go some way to correcting this.
References
References found in this section, and in particular the HTML links were correct at time of writing (2003-04-14).
ZOIS's Copyright statement:
$Date: 2007/10/29 13:36:39 $