TUXEDO samples

Before running these samples, you must build the server environment.

Note:: Throughout this section the "\" character is used to split long commands over more than one line. Do not enter this character, enter each command as a single line.

Building the server environment

It is assumed that you have a working TUXEDO environment.

To build the server environment for WebSphere MQ for AIX:

Create a directory (for example, <APPDIR>) in which the server environment is built and execute all commands in this directory.

Export the following environment variables, where TUXDIR is the root directory for TUXEDO:

       $ export CFLAGS="-I /usr/mqm/inc -I /<APPDIR> -L /usr/mqm/lib"
       $ export LDOPTS="-lmqm -lmqmzse -lnet -insl -lsocket -lc -ldl"
       $ export FIELDTBLS=/usr/mqm/samp/amqstxvx.flds
       $ export VIEWFILES=/<APPDIR>/amqstxvx.V
       $ export LIBPATH=$TUXDIR/lib:/usr/mqm/lib:/lib

Add the following to the TUXEDO file udataobj/RM

       MQSeries_XA_RMI:MQRMIXASwitchDynamic: \
  /usr/mqm/lib/libmqmxa.a /usr/mqm/lib/libmqm.a

Run the commands:

       $ mkfldhdr    /usr/mqm/samp/amqstxvx.flds
       $ viewc       /usr/mqm/samp/amqstxvx.v
       $ buildtms    -o MQXA -r MQSeries_XA_RMI
       $ buildserver -o MQSERV1 -f /usr/mqm/samp/amqstxsx.c \
              -f /usr/mqm/lib/libmqm.a \
              -r MQSeries_XA_RMI -s MPUT1:MPUT \
              -s MGET1:MGET \
              -v -bshm
       $ buildserver -o MQSERV2 -f /usr/mqm/samp/amqstxsx.c \
              -f /usr/mqm/lib/libmqm.a \
              -r MQSeries_XA_RMI -s MPUT2:MPUT
              -s MGET2:MGET \
              -v -bshm
       $ buildclient -o doputs  -f /usr/mqm/samp/amqstxpx.c \
              -f /usr/mqm/lib/libmqm.a
       $ buildclient -o dogets  -f /usr/mqm/samp/amqstxgx.c \
              -f /usr/mqm/lib/libmqm.a

Edit ubbstxcx.cfg (see Figure 38), and add details of the machine name, working directories, and queue manager as necessary:
```
       $ tmloadcf    -y /usr/mqm/samp/ubbstxcx.cfg
```
Create the TLOGDEVICE:
```
      $tmadmin -c
```
A prompt then appears. At this prompt, enter:
```
      > crdl -z /<APPDIR>/TLOG1
```
Start the queue manager:
```
       $ strmqm
```
Start Tuxedo:
```
       $ tmboot -y
```

You can now use the doputs and dogets programs to put messages to a queue and retrieve them from a queue.

To build the server environment for MQSeries for AT&T GIS UNIX and WebSphere MQ for Solaris:

Create a directory (for example, <APPDIR>) in which the server environment is built and execute all commands in this directory.

Export the following environment variables, where TUXDIR is the root directory for TUXEDO:

       $ export CFLAGS="-I /<APPDIR>"
       $ export FIELDTBLS=amqstxvx.flds
       $ export VIEWFILES=amqstxvx.V
       $ export SHLIB_PATH=$TUXDIR/lib:/opt/mqm/lib:/lib
       $ export LD_LIBRARY_PATH=$TUXDIR/lib:/opt/mqm/lib:/lib

Add the following to the TUXEDO file udataobj/RM (RM must include /opt/mqm/lib/libmqmcs and /opt/mqm/lib/libmqmzse).

  MQSeries_XA_RMI:MQRMIXASwitchDynamic: \
  /opt/mqm/lib/libmqmxa.a /opt/mqm/lib/libmqm.so \
  /opt/tuxedo/lib/libtux.a /opt/mqm/lib/libmqmcs.so  \
  /opt/mqm/lib/libmqmzse.so

Run the commands:

       $ mkfldhdr    amqstxvx.flds
       $ viewc       amqstxvx.v
       $ buildtms    -o MQXA -r MQSeries_XA_RMI
       $ buildserver -o MQSERV1 -f amqstxsx.c \
              -f /opt/mqm/lib/libmqm.so \
              -r MQSeries_XA_RMI -s MPUT1:MPUT \
              -s MGET1:MGET \
              -v -bshm
              -l -ldl
       $ buildserver -o MQSERV2 -f amqstxsx.c \
              -f /opt/mqm/lib/libmqm.so \
              -r MQSeries_XA_RMI -s MPUT2:MPUT \
              -s MGET2:MGET \
              -v -bshm
              -l -ldl
       $ buildclient -o doputs  -f amqstxpx.c \
              -f /opt/mqm/lib/libmqm.so  \
              -f /opt/mqm/lib/libmqmzse.co  \
              -f /opt/mqm/lib/libmqmcs.so
       $ buildclient -o dogets  -f amqstxgx.c \
              -f /opt/mqm/lib/libmqm.so
              -f /opt/mqm/lib/libmqmzse.co  \
              -f /opt/mqm/lib/libmqmcs.so

Edit ubbstxcx.cfg (see Figure 38), and add details of the machine name, working directories, and Queue Manager as necessary:
```
       $ tmloadcf    -y ubbstxcx.cfg
```
Create the TLOGDEVICE:
```
      $tmadmin -c
```
A prompt then appears. At this prompt, enter:
```
      > crdl -z /<APPDIR>/TLOG1
```
Start the queue manager:
```
       $ strmqm
```
Start Tuxedo:
```
       $ tmboot -y
```

You can now use the doputs and dogets programs to put messages to a queue and retrieve them from a queue.

To build the server environment for WebSphere MQ for HP-UX:

Create a directory (for example, <APPDIR>) in which the server environment is built and execute all commands in this directory.

Export the following environment variables, where TUXDIR is the root directory for TUXEDO:

       $ export CFLAGS="-Aa -D_HPUX_SOURCE"
       $ export LDOPTS="-lmqm"
       $ export FIELDTBLS=/opt/mqm/samp/amqstxvx.flds
       $ export VIEWFILES=<APPDIR>/amqstxvx.V
       $ export SHLIB_PATH=$TUXDIR/lib:/opt/mqm/lib:/lib
       $ export LPATH=$TUXDIR/lib:/opt/mqm/lib:/lib

Add the following to the TUXEDO file udataobj/RM

       MQSeries_XA_RMI:MQRMIXASwitchDynamic: \
       /opt/mqm/lib/libmqmxa.a /opt/mqm/lib/libmqm.sl \
       /opt/tuxedo/lib/libtux.sl

Run the commands:

       $ mkfldhdr    /opt/mqm/samp/amqstxvx.flds
       $ viewc       /opt/mqm/samp/amqstxvx.v
       $ buildtms    -o MQXA -r MQSeries_XA_RMI
       $ buildserver -o MQSERV1 -f /opt/mqm/samp/amqstxsx.c \
              -f /opt/mqm/lib/libmqm.sl \
              -r MQSeries_XA_RMI -s MPUT1:MPUT \
              -s MGET1:MGET \
              -v -bshm
       $ buildserver -o MQSERV2 -f /opt/mqm/samp/amqstxsx.c \
              -f /opt/mqm/lib/libmqm.sl \
              -r MQSeries_XA_RMI -s MPUT2:MPUT \
              -s MGET2:MGET \
              -v -bshm
       $ buildclient -o doputs  -f /opt/mqm/samp/amqstxpx.c \
              -f /opt/mqm/lib/libmqm.sl
       $ buildclient -o dogets  -f /opt/mqm/samp/amqstxgx.c \
              -f /opt/mqm/lib/libmqm.sl

Edit ubbstxcx.cfg (see Figure 38), and add details of the machine name, working directories, and Queue Manager as necessary:
```
       $ tmloadcf    -y /opt/mqm/samp/ubbstxcx.cfg
```
Create the TLOGDEVICE:
```
      $tmadmin -c
```
A prompt then appears. At this prompt, enter:
```
      > crdl -z /<APPDIR>/TLOG1
```
Start the queue manager:
```
       $ strmqm
```
Start Tuxedo:
```
       $ tmboot -y
```

You can now use the doputs and dogets programs to put messages to a queue and retrieve them from a queue.

To build the server environment for MQSeries for SINIX and DC/OSx

Export the following environment variables where TUXDIR is the root directory for TUXEDO:

       $ export CFLAGS="-lmqm -lmqmcs -lmqmzse -lmqmxa \
       -lnsl -lsocket -ldl -lmproc -lext"

Note:: For DC/OSx, add "-liconv" to the above.

       $ export FIELDTBLS=amqstxvx.flds
       $ export VIEWFILES=amqstxvx.V
       $ export VIEWDIR=The path to the directory where the views
       are held
       $ export TUXDIR=The path to the directory where TUXEDO
       is installed (/opt/tuxedo).
       $ export CFLAGS="-lmqm -lmqmcs -lmqmzse -lmqmxa  \
       -lnsl -lsocket -ldl -lmproc -lext"

Add the following to the TUXEDO file udataobj/RM

       MQSeries_XA_RMI:MQRMIXASwitchDynamic: \
  /opt/mqm/lib/libmqmxa.so
  /opt/mqm/lib/libmqm.so /opt/mqm/lib/libmqmcs.s

Ensure that your LD_LIBRARY_PATH contains the path to the Tuxedo libraries (/opt/tuxedo/lib), and that it is exported.
Ensure that your PATH contains the path to the Tuxedo bin directory (/opt/tuxedo/bin), and that it is exported.

Run the commands:

       $ mkfldhdr    amqstxvx.flds
       $ viewc       amqstxvx.v

Alter the value of the CFLAGS variable:

       export CFLAGS="$CFLAGS -LDuMQRMIXASwitchDynamic -lmqmxa"

Run the commands:

       $ buildtms    -o MQXA -r MQSeries_XA_RMI
       $ buildserver -o MQSERV1 -f amqstxsx.c \
              -f /opt/mqm/lib/libmqm.so i \
              -r MQSeries_XA_RMI -s MPUT1:MPUT \
              -s MGET1:MGET \
              -v -bshm
       $ buildserver -o MQSERV2 -f amqstxsx.c \
              -f /opt/mqm/lib/libmqm.so \
              -r MQSeries_XA_RMI -s MPUT2:MPUT \
              -s MGET2:MGET \
              -v -bshm
       $ buildclient -o doputs  -f amqstxpx.c \
              -f /opt/mqm/lib/libmqm.so
       $ buildclient -o dogets  -f amqstxgx.c \
              -f /opt/mqm/lib/libmqm.so

Ensure that your NLS_PATH contains the path to the Tuxedo messages (/opt/tuxedo/locale/C/%N), and that it is exported.
Edit ubbstxcx.cfg (see Figure 38), and add details of the machine name, working directories, and Queue Manager as necessary.
Set the environment variable TUXCONFIG to the value specified in the MACHINES section of the ubbstxcx.cfg file.
If you are using the Tuxedo main machine, run the following commands:
```
      tmadmin -c
```
At the prompt (>), enter:
```
      crdl -z filename
```
where filename is the path to the Tuxedo TLOG file.
Run the following command:
```
       $ tmloadcf    -y ubbstxcx.cfg
```
Start the queue manager:
```
       $ strmqm
```
Start Tuxedo:
```
       $ tmboot -y
```

You can now use the doputs and dogets programs to put messages to a queue and retrieve them from a queue.

For further information on building the TUXEDO server environment, see the README file in the WebSphere MQ sample directory, /opt/mqm/samp.

Figure 38. Example of ubbstxcx.cfg file for UNIX systems

*RESOURCES
IPCKEY          <IPCKey>
 
#Example:
#IPCKEY         123456
 
MASTER          <MachineName>
MAXACCESSERS    20
MAXSERVERS      20
MAXSERVICES     50
MODEL           SHM
LDBAL           N
 
*MACHINES
DEFAULT:
                APPDIR="<WorkDirectory>"
                TUXCONFIG="<WorkDirectory>/tuxconfig"
                ROOTDIR="<RootDirectory>"
 
<MachineName>   LMID=<MachineName>
                TLOGDEVICE="<WorkDirectory>/TLOG1"
                TLOGNAME=TLOG
 
*GROUPS
GROUP1
        LMID=<MachineName>  GRPNO=1
        TMSNAME=MQXA
        OPENINFO="MQSeries_XA_RMI:MYQUEUEMANAGER"
 
*SERVERS
DEFAULT:
                CLOPT="-A -- -m MYQUEUEMANAGER
 
MQSERV1         SRVGRP=GROUP1 SRVID=1
MQSERV2         SRVGRP=GROUP1 SRVID=2
 
*SERVICES
MPUT1
MGET1
MPUT2
MGET2

Note:: Other information that you need to add is identified by <> characters. In this file, the queue manager name has been changed to MYQUEUEMANAGER:

To build the server environment for WebSphere MQ for Windows:

Note:: Change the fields identified by <> in the following, to the directory paths:

<MQMDIR>	the directory path specified when WebSphere MQ was installed, for example `g:\Program Files\IBM\WebSphere MQ`
<TUXDIR>	the directory path specified when TUXEDO was installed, for example `f:\tuxedo`
<APPDIR>	the directory path to be used for the sample application, for example `f:\tuxedo\apps\mqapp`

To build the server environment and samples:

Create an application directory in which to build the sample application, for example:
```
   f:\tuxedo\apps\mqapp
```
Copy the following sample files from the WebSphere MQ sample directory to the application directory:
```
      amqstxmn.mak
      amqstxen.env
      ubbstxcn.cfg
```
Edit each of these files to set the directory names and directory paths used on your installation.
Edit ubbstxcn.cfg (see Figure 39) to add details of the machine name and the Queue Manager that you wish to connect to.
Add the following line to the TUXEDO file <TUXDIR>udataobj\rm
```
   MQSeries_XA_RMI;MQRMIXASwitchDynamic;
      <MQMDIR>\tools\lib\mqmtux.lib <MQMDIR>\tools\lib\mqm.lib
```
where <MQMDIR> is replaced as above. Although shown here as two lines, the new entry must be one line in the file.

Set the following environment variables:

       TUXDIR=<TUXDIR>
       TUXCONFIG=<APPDIR>\tuxconfig
       FIELDTBLS=<MQMDIR>\tools\c\samples\amqstxvx.fld
       LANG=C

Create a TLOG device for TUXEDO. To do this, invoke tmadmin -c, and enter the command:
```
  crdl -z <APPDIR>\TLOG
```
where <APPDIR> is replaced as above.
Set the current directory to <APPDIR>, and invoke the sample makefile (amqstxmn.mak) as an external project makefile. For example, with Microsoft Visual C++ Version 2.0, issue the command:
```
  msvc amqstxmn.mak
```
Select build to build all the sample programs.

Figure 39. Example of ubbstxcn.cfg file for WebSphere MQ for Windows

*RESOURCES
IPCKEY        99999
UID           0
GID           0
MAXACCESSERS  20
MAXSERVERS    20
MAXSERVICES   50
MASTER        SITE1
MODEL         SHM
LDBAL         N
 
*MACHINES
<MachineName> LMID=SITE1
              TUXDIR="f:\tuxedo"
              APPDIR="f:\tuxedo\apps\mqapp;g:\Program Files\IBM\WebSphere MQ\bin"
              ENVFILE="f:\tuxedo\apps\mqapp\amqstxen.env"
              TUXCONFIG="f:\tuxedo\apps\mqapp\tuxconfig"
              ULOGPFX="f:\tuxedo\apps\mqapp\ULOG"
              TLOGDEVICE="f:\tuxedo\apps\mqapp\TLOG"
              TLOGNAME=TLOG
              TYPE="i386NT"
              UID=0
              GID=0
 
*GROUPS
GROUP1
        LMID=SITE1  GRPNO=1
        TMSNAME=MQXA
        OPENINFO="MQSeries_XA_RMI:MYQUEUEMANAGER"
 
*SERVERS
DEFAULT: CLOPT="-A -- -m MYQUEUEMANAGER"
 
MQSERV1     SRVGRP=GROUP1 SRVID=1
MQSERV2     SRVGRP=GROUP1 SRVID=2
 
*SERVICES
MPUT1
MGET1
MPUT2
MGET2

Note:: The directory names and directory paths must be changed to match your installation. The queue manager name MYQUEUEMANAGER should also be changed to the name of the queue manager you wish to connect to. Other information that you need to add is identified by <> characters.

The sample ubbconfig file for WebSphere MQ for Windows is listed in Figure 39. It is supplied as ubbstxcn.cfg in the WebSphere MQ samples directory.

The sample makefile (see Figure 40) supplied for WebSphere MQ for Windows is called ubbstxmn.mak, and is held in the WebSphere MQ samples directory.

Figure 40. Sample TUXEDO makefile for WebSphere MQ for Windows

TUXDIR  = f:\tuxedo
MQMDIR  = g:\Program Files\IBM\WebSphere MQ
APPDIR  = f:\tuxedo\apps\mqapp
MQMLIB  = $(MQMDIR)\tools\lib
MQMINC  = $(MQMDIR)\tools\c\include
MQMSAMP = $(MQMDIR)\tools\c\samples
INC = -f "-I$(MQMINC) -I$(APPDIR)"
DBG = -f "/Zi"
 
amqstx.exe:
 $(TUXDIR)\bin\mkfldhdr    -d$(APPDIR) $(MQMSAMP)\amqstxvx.fld
 $(TUXDIR)\bin\viewc       -d$(APPDIR) $(MQMSAMP)\amqstxvx.v
 $(TUXDIR)\bin\buildtms    -o MQXA -r MQSeries_XA_RMI
 $(TUXDIR)\bin\buildserver -o MQSERV1 -f $(MQMSAMP)\amqstxsx.c \
                           -f $(MQMLIB)\mqm.lib -v $(INC) $(DBG) \
                           -r MQSeries_XA_RMI \
                           -s MPUT1:MPUT -s MGET1:MGET
 $(TUXDIR)\bin\buildserver -o MQSERV2 -f $(MQMSAMP)\amqstxsx.c \
                           -f $(MQMLIB)\mqm.lib -v $(INC) $(DBG) \
                           -r MQSeries_XA_RMI \
                           -s MPUT2:MPUT -s MGET2:MGET
 $(TUXDIR)\bin\buildclient -o doputs -f $(MQMSAMP)\amqstxpx.c \
                           -f $(MQMLIB)\mqm.lib -v $(INC) $(DBG)
 $(TUXDIR)\bin\buildclient -o dogets -f $(MQMSAMP)\amqstxgx.c \
                           -f $(MQMLIB)\mqm.lib $(INC) -v $(DBG)
 $(TUXDIR)\bin\tmloadcf    -y $(APPDIR)\ubbstxcn.cfg

To build the server environment for MQSeries for Compaq Tru64 UNIX

The procedure is the same on Compaq Tru64 UNIX Version 4.0 and Version 5.0. It is assumed that you have a working TUXEDO environment.

Create a directory (for example <appdir>) in which the server environment is built and execute all commands in this directory.

Export the following environment variables, where TUXDIR is the root directory for TUXEDO:

$ TUXDIR=/TUXDIR; export TUXDIR
$ PATH=$TUXDIR/bin:$PATH; export PATH
$ COBCPY=:$TUXDIR/cobinclude; export COBCPY
$ COBOPT="-C ANS85 -C ALIGN=8 -C NOIBMCOMP -C TRUNC=ANSI \
         -C OSEXT=cbl"; export COBOPT
$ LD_LIBRARY_PATH=$TUXDIR/lib:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH

Add the following to the TUXEDO file TUXDIR/udataobj/RM

MQSeries_XA_RMI:MQRMIXASwitchDynamic:-lmqm -lmqmzse \
-lmqmxa -lmqmcs -L/$TUXDIR/lib -ltux

Run the commands:

$ mkfldhdr /opt/mqm/samp/amqstxvx.flds
$ viewc /opt/mqm/samp/amqstxvx.v
$ buildtms -o MQXA -r MQSeries_XA_RMI
$ buildserver -o MQSERV1 -f /opt/mqm/samp/amqstxsx.c \
              -f /opt/mqm/lib/libmqm.so -r MQSeries_XA_RMI \
              -s MPUT1:MPUT -s MGET1:MGET -v -bshm
$ buildserver -o MQSERV2 -f /opt/mqm/samp/amqstxsx.c \
              -f /opt/mqm/lib/libmqm.so -r MQSeries_XA_RMI \
              -s MPUT2:MPUT -s MGET2:MGET -v -bshm
$ buildclient -o doputs -f /opt/mqm/samp/amqstxpx.c \
              -f /opt/mqm/lib/libmqm.so -f /opt/mqm/lib/libmqmzse.so \
              -f /opt/mqm/lib/libmqmcs.so
$ buildclient -o dogets -f /opt/mqm/samp/amqstxgx.c \
              -f /opt/mqm/lib/libmqm.so -f /opt/mqm/lib/libmqmzse.so \
              -f /opt/mqm/lib/libmqmcs.so

Edit the file ubbstxcx.cfg and add details of the machine name, working directories, and queue manager as necessary. Execute the following command:
```
$ tmloadcf -y ubbstxcx.cfg
```
Create the TLOGDEVICE:
```
$ tmadmin -c
```
A > prompt then appears. At this point, enter:
```
> crdl -z /<appdir>/TLOG1
```
Start the queue manager MYQUEUEMANAGER
```
$ strmqm MYQUEUEMANAGER
```
Start the Tuxedo server:
```
$ tmboot -y
```

You can now use the doputs and dogets programs to put messages to a queue and retrieve them from a queue.

Server sample program for TUXEDO

This sample server program (amqstxsx) is designed to run with the Put (amqstxpx.c) and the Get (amqstxgx.c) sample programs. The program runs automatically when TUXEDO is started.

Note:: You must start your queue manager before you start TUXEDO.

The sample server provides two TUXEDO services, MPUT1 and MGET1.

The MPUT1 service is driven by the PUT sample and uses MQPUT1 in syncpoint to put a message in a unit of work controlled by TUXEDO. It takes the parameters QName and Message Text, which are supplied by the PUT sample.

The MGET1 service opens and closes the queue each time it gets a message. It takes the parameters QName and Message Text, which are supplied by the GET sample.

Any error messages, reason codes, and status messages are written to the TUXEDO log file.

Figure 41. How TUXEDO samples work together

A diagram showing how clients running the Get and Put sample programs communicate with the Server sample program which in turn communicates with WebSphere MQ.

Put sample program for TUXEDO

This sample allows you to put a message on a queue multiple times, in batches, demonstrating syncpointing using TUXEDO as the resource manager. The sample server program amqstxsx must be running for the put sample to succeed - the server sample program makes the connection to the queue manager and uses the XA interface. To run the sample enter:

doputs -n queuename -b batchsize -c trancount -t message

For example:

doputs -n myqueue -b 5 -c 6 -t "Hello World"

This puts 30 messages on to the queue named myqueue, in 6 batches each with 5 messages in them. If there are any problems it will back a batch of messages out, otherwise it will commit them.

Any error messages are written to the TUXEDO log file and to stderr. Any reason codes are written to stderr.

Get sample for TUXEDO

This sample allows you to get messages from a queue in batches. The sample server program amqstxsx must be running for the put sample to succeed - the server sample program makes the connection to the queue manager and uses the XA interface. To run the sample enter:

dogets -n queuename -b batchsize -c trancount

For example:

dogets -n myqueue -b 6 -c 4

This takes 24 messages off the queue named myqueue, in 6 batches each with 4 messages in them. If you ran this after the put example, which put 30 messages on myqueue, you would now have only 6 messages on myqueue. Note that the number of batches and the batch size can vary between the putting of messages and the getting of them.

Any error messages are written to the TUXEDO log file and to stderr. Any reason codes are written to stderr.