Sun Java System Message Queue 4.3 Developer's Guide for C Clients

Working With the Sample C-Client Programs

This section describes the sample C-Client programs that are installed with Message Queue and explains how you should build them and run them.

Message Queue provides two sets of sample C-client programs: basic C-client programs and distributed transaction programs.

Basic C-Client Programs

The sample C-client program files include the following:

Table 1–3 Basic C-Client Sample Program Files

Sample Program 

Description 

Producer.c

Illustrates how you send a message 

Consumer.c

Illustrates how you receive a message synchronously 

ProducerAsyncConsumer.c

Illustrates how you send a message and receive it asynchronously 

RequestReply.c

Illustrates how you send and respond to a message that specifies a reply-to destination 

Table 1–4 lists the location of the sample programs on each platform.

Table 1–4 Location of Basic C-Client Sample Programs

Platform 

Directory 

Solaris 

/opt/SUNWimq/demo/C

Linux 

/opt/sun/mq/examples/C

AIX 

IMQ_HOME/demo/C

Windows 

IMQ_HOME\demo\C

Building the Basic C-Client Sample Programs

The following commands illustrate the process of building and linking the sample application Producer.c on the Solaris, Linux, AIX, and Windows platforms. The commands include the pre-processor definitions needed to support Message Queue C-API fixed-size integer types. For options used to support multithreading, please consult documentation for your compiler.

To Compile and Link on Solaris OS

CC -compat=5 -mt -DSOLARIS -I/opt/SUNWimq/include -o Producer \\
    -L/opt/SUNWimq/lib -lmqcrt Producer.c

For Solaris OS, if you need 64-bit support, you need to specify the following compiler options:

. For example, to compile and link the example application on Solaris/SPARC, you would use the following command:

CC -compat=5 -mt -xarch=v9 -DSOLARIS -I/opt/SUNWimq/include -o Producer \\
   L/opt/SUNWimq/lib/sparcv9 -lmqcrt Producer.c

To Compile and Link on Linux

g++ -DLINUX -D_REENTRANT -I/opt/sun/mq/include -o Producer \\
    -L/opt/sun/mq/lib -lmqcrt Producer.c

To Compile and Link on AIX

xlC_r -qthreaded -DAIX -I/$IMQ_HOME/include -o Producer \\
    -blibsuff:so -l$IMQ_HOME/lib -imqcrt Producer.c

To Compile and Link on Windows

cl /c /MD -DWIN32 -I%IMQ_HOME%\include Producer.c
link Producer.obj /NODEFAULTLIB msvcrt.lib \\
      /LIBPATH:%IMQ_HOME%\lib mqcrt.lib

Running the Basic C-Client Sample Programs

Before you run any sample programs, you should start the broker. You can display output describing the command-line options for each program by starting the program with the -help option.

For example, the following command, runs the program Producer. It specifies that the program should connect to the broker running on the host MyHost and port 8585, and that it should send a message to the destination My Topic :

Producer -h MyHost -p 8585 -d MyTopic

The directories that contain the sample programs also include a README file that explains how you should run their respective samples.

Distributed Transaction Sample Programs

The distributed transaction sample programs show how to use the X/Open distributed transaction (XA) support of the Message Queue C-API with an X/Open distributed transaction processing system (in this case BEA Tuxedo: http://edocs.bea.com/tuxedo/tux100/index.html.)

The distributed transaction sample programs include the following files:

Table 1–5 Distributed Transaction Sample Program Files

Sample Program 

Description 

jmsserver.c

Implements Tuxedo services that send and receive messages using the Message Queue C-API 

jmsclient_sender.c

Tuxedo client that uses the message producing service in jmsserver.c

jmsclient_receiver.c

Tuxedo client that uses the message receiving service in jmsserver.c

async_jmsserver.c

Implements a Tuxedo service that asynchronously consumes messages using the Message Queue C-API 

jmsclient_async_receiver.c

Tuxedo client that uses the asynchronous message consuming service in async_jmsserver.c

Table 1–4 lists the location of the sample programs on each platform.

Table 1–6 Location of Distributed Transaction Sample Programs

Platform 

Directory 

Solaris 

/opt/SUNWimq/demo/C/tuxedo

Linux 

/opt/sun/mq/examples/C/tuxedo

AIX 

IMQ_HOME/demo/C/tuxedo

Windows 

IMQ_HOME\demo\C\tuxedo

The following procedures document how to set up Tuxedo as a distributed transaction manager, how to build the sample distributed transaction programs, and how to run the sample programs. The procedures are based on the synchronous message consumption samples and assume a Solaris operating system platform.

ProcedureTo Set Up Tuxedo as a Distributed Transaction Manager

  1. Install Tuxedo.

    See Tuxedo documentation for instructions.

  2. Set up the following environment variables:

    Environment Variable 

    Description 

    LD_LIBRARY_PATH

    Modify to include Message Queue C-API runtime library path and TUXDIR/lib path

    TUXDIR

    Tuxedo install root 

    PATH

    modify to include $TUXDIR/bin and compiler path

    TUXCONFIG

    TUXCONFIG filename path

    TLOGDEVICE

    Tuxedo transaction log filename path 

    MQ_HOME

    Message Queue install root 

    MQ_LOG_FILE

    Message Queue C-API runtime log file name 

    MQ_LOG_FILE_APPEND_PID

    Set so that Message Queue C-API runtime log file name will be auto-appended with the Tuxedo server process id 

  3. Build the Tuxedo transaction monitor server (TMS).

    1. Add the following entry to the $TUXDIR/udataobj/RM file:

      # SUN_MQ:sun_mq_xa_switch:-lmqcrt

    2. Build the TMS executable using buildtms:

      # buildtms -o $TUXDIR/bin/<exe-name> -r SUN_MQ

  4. Configure the Tuxedo servers.

    # tmloadcf config-file

    where config-file is the Tuxedo UBBCONFIG file.

ProcedureTo Build the Distributed Transaction Sample Programs

  1. Build the server side of the sample application (jmsserver.c).

    # cc -I$MQ_HOME/include -I$TUXDIR/include -g -c jmsserver.c

    # buildserver -v -t -r SUN_MQ -s SENDMESSAGES,RECVMESSAGES -o jmsserver -f jmsserver.o -f -lmqcrt

  2. Build the client side of the sample application (jmsclient_sender.c and jmsclient_receiver.c).

    # cc -I$TUXDIR/include -c jmsclient_sender.c # buildclient -o jmsclient_sender -f jmsclient_sender.o

    # cc -I$TUXDIR/include -c jmsclient_receiver.c # buildclient -o jmsclient_receiver -f jmsclient_receiver.o

ProcedureTo Run the Distributed Transaction Sample Programs

  1. Start a Message Queue broker.

    # imqbrokerd -tty

  2. Start the Tuxedo servers.

    # tmboot

  3. Run the client-side applications.

    # jmsclient_sender

    # jmsclient_receiver

  4. Confirm the messages are produced to and consumed from the applicable destination.

    # imqcmd list dst -u admin

    # imqcmd querry dst -t q -n xatestqueue -u admin