WebSphere MQ Sample Programs

(For more resources on IBM, see here.)

WebSphere MQ sample programs—server

There is a whole set of sample programs available to the WebSphere MQ administrator. We are interested in only a couple of them: the program to put a message onto a queue and a program to retrieve a message from a queue. The names of these sample programs depend on whether we are running WebSphere MQ as a server or as a client.

There is a server sample program called amqsput, which puts messages onto a queue using the MQPUT call. This sample program comes as part on the WebSphere MQ samples installation package, not as part of the base package.

The maximum length of message that we can put onto a queue using the amqsput sample program is 100 bytes.

There is a corresponding server sample program to retrieve messages from a queue called amqsget.

Use the sample programs only when testing that the queues are set up correctly—do NOT use the programs once Q Capture and Q Apply have been started. This is because Q replication uses dense numbering between Q Capture and Q Apply, and if we insert or retrieve a message, then the dense numbering will not be maintained and Q Apply will stop. The usual response to this is to cold start Q Capture!

To put a message onto a Queue (amqsput)

The amqsput utility can be invoked from the command line or from within a batch program. If we are invoking the utility from the command line, the format of the command is:

$ amqsput <Queue> <QM name> < <message>

We would issue this command from the system on which the Queue Manager sits. We have to specify the queue (<Queue>) that we want to put the message on, and the Queue Manager (<QM name>) which controls this queue. We then pipe (<) the message (<message>) into this. An example of the command is:


We put these commands into an appropriately named batch fle (say SYSA_QMA_TESTP_UNI_AB.BAT), which would contain the following:

Batch file—Windows example:

call "C:\Program Files\IBM\WebSphere MQ\bin\amqsput" CAPA.TO.APPB.

Batch file—UNIX example:

"/opt/mqm/samp/bin/amqsput" CAPA.TO.APPB.SENDQ.REMOTE

Where the QMA_TEST1.TXT fle contains the message we want to send. Once we have put a message onto the Send Queue, we need to be able to retrieve it.

To retrieve a message from a Queue(amqsget)

The amqsget utility can be invoked from the command line or from within a batch program. The utility takes 15 seconds to run. We need to specify the Receive Queue that we want to read from and the Queue Manager that the queue belongs to:

$ amqsget <Queue> <QM name>

As example of the command is shown here:


If we have correctly set up all the queues, and the Listeners and Channels are running, then when we issue the preceding command, we should see the message we put onto the Send Queue.

We can put the amqsget command into a batch fle, as shown next:

Batch file—Windows example:

@ECHO This takes 15 seconds to run
call "C:\Program Files\IBM\WebSphere MQ\bin\amqsget" CAPA.TO.APPB.
@ECHO You should see: test1

Batch file—UNIX example:

echo This takes 15 seconds to run
"/opt/mqm/samp/bin/amqsget" CAPA.TO.APPB.RECVQ QMB
echo You should see: test1

Using these examples and putting messages onto the queues in a unidirectional scenario, then the "get" message batch fle for QMA (SYSA_QMA_TESTG_UNI_BA.BAT) contains:

@ECHO This takes 15 seconds to run
call "C:\Program Files\IBM\WebSphere MQ\bin\amqsget" CAPA.ADMINQ QMA
@ECHO You should see: test2

From CLP-A, run the fle as:


The "get" message batch file for QMB (SYSB_QMB_TESTG_UNI_AB.BAT) contains:

@ECHO This takes 15 seconds to run
call "C:\Program Files\IBM\WebSphere MQ\bin\amqsget" CAPA.TO.APPB.
@ECHO You should see: test1

From CLP-B, run the file as:


To browse a message on a Queue

It is useful to be able to browse a queue, especially when setting up Event Publishing. There are three ways to browse the messages on a Local Queue. We can use the rfhutil utility, or the amqsbcg sample program, both of which are WebSphere MQ entities, or we can use the asnqmfmt Q replication command.

  • Using the WebSphere MQ rfhutil utility: The rfhutil utility is part of the WebSphere MQ support pack available to download from the web—to find the current download website, simply type rfhutil into an internet search engine. The installation is very simple—unzip the file and run the rfhutil.exe file.
  • Using the WebSphere MQ amqsbcg sample program: The amqsbcg sample program displays messages including message descriptors.

    $ amqsbcg CAPA.TO.APPB.RECVQ QMB

(For more resources on IBM, see here.)

WebSphere MQ sample programs—client

The sample program used to put messages onto a queue using the MQPUT call is amqsputc. The sample program used to retrieve messages onto a queue using the MQPUT call is amqsgetc.

Dead Letter Queue handler (runmqdlq)

This section looks at the WebSphere MQ Dead Letter Queue (DLQ), what it is, and how to handle messages that are put on this queue.

Firstly, let's look at what a DLQ actually does. In one sentence, a DLQ is a queue that stores messages that cannot be routed to their correct destination(s). This occurs when, for example, the destination queue is full.

In our examples, we always defne a DLQ called DEAD.LETTER.QUEUE.<QMgr-name>.

We can check that we have a DLQ defned by displaying the attributes of the Queue Manager. So for Q Apply running on CLP-B, we would issue:

$ runmqsc QMB
: dis qmgr

To handle messages in the DLQ, we use the WebSphere MQ DLQ message handler utility called runmqdlq. Note that we cannot simply read the messages off the DLQ and put them somewhere else, because then we would change the message header information.

As part of the WebSphere MQ samples package, the source of a Dead Letter Queue handler program is provided and is called amqsdlq. We can customize this program if the provided handler does not meet our requirements.

So let's look at how we handle messages on the DLQ using the provided handler. The first thing we need is a DLQ rule handler fle. This is a text file and tells the utility what type of messages to look for in the DLQ and then what to do with them. The contents of such a fle is as follows:


This says for any messages that are in the DLQ because the queue they were supposed to go to was full, retry putting the message onto that original queue. Try this once and then stop. We will run the utility only when we have sorted out any problems, so we do not think specifying a retry value of 1 is a problem.

Create a fle in the c:\temp directory called dlqrule.txt and put the preceding code line into it.

Now we can run the DLQ handler utility as:

C:\TEMP> runmqdlq DEAD.LETTER.QUEUE.QMB QMB < dlqrule.txt

WebSphere MQ message format

Each WebSphere MQ message consists of two parts: a header and the application data.

There are fve types of header, as shown in the following table


The message descriptor. Created by the application at message create time.


The Transmission Queue header, which contains delivery information in remote queuing.


The dead letter header, which identifies conditions that prevent delivery to a destination queue.


Reference message header, which contains information to assist in delivery of reference messages.


Information header (MQIIH), which is carried with the message using the IMS hierarchical database bridge facility.

Let's look at the MQMD header in more detail. The following figure shows how the MQMD is made up:

WebSphere MQ Sample Programs

The following table shows the meaning of each MQMD entry in the preceding fgure:


The queue name for reply messages.


If we cannot deliver this message, put it in the DLQ or discard (DLQ is the default).


Is the message persistent or non-persistent.


Message type - Request, Reply, Report, Datagram (broadcast message).


The context is 8 fields that travel with the MQMD which can be used for security. It gets filled in automatically, but we can change it with the appropriate authority.


Priority 0 to 9, with 9 being the highest.


Used for authentication. This contains the userid and other security information (does the user have the authority to access the queue).


Used to identify which physical message this segment belongs to if the original message had to be split.

WebSphere MQ messages have the concept of persistence:

  • If a message is defined as persistent then its delivery is assured.
  • If a message is defned as non-persistent, then if WebSphere MQ cannot deliver the message it is discarded.

Persistence is decided at message creation time by the application program creating the message and is a property of a message, not a queue. Non-persistent messages get deleted at Queue Manager start-up time.

Prior to DB2 9.7, Q replication had to use persistent WebSphere MQ messages. Starting with DB2 9.7, we have the option of using non-persistent WebSphere MQ messages. To specify non-persistent messages, start Q Capture with the msg_persistence=n parameter.

MQ error messages

The current WebSphere MQ error log is called AMQERR01.LOG. The two previous copies of the log are called AMQERR02.LOG and AMQERR03.LOG. The log directories are called:

On UNIX: var/mqm/errors

On Windows: C:\Program Files\IBM\WebSphere MQ\errors

We can see the MQ error messages in the Q Capture and Q Apply logs. Some common errors are shown in the following table:


A queue is full. We need to stop the Channel before clearing the queue using the MQSC command clear qlocal <queue-name>.


We have specified an invalid Queue Manager name.


We have specified a Queue Manager name which is not available (it knows it exists, but is unavailable - perhaps there are authorization problems or it has not been started).


The length of the message we are trying to retrieve using amqsget is greater than 100 bytes.


The queue name does not exist in the Queue Manager where we told it that the queue existed.


Damaged disks.


In this article, we covered the MQ sample programs that can be used to check that MQ has been set up correctly and then looked at the Dead Letter Queue handler. We finally listed some of the common MQ error messages that occur with Q replication.

Further resources on this subject:

You've been reading an excerpt of:

IBM InfoSphere Replication Server and Data Event Publisher

Explore Title