WebSphere MQ Sample Programs

Exclusive offer: get 50% off this eBook here
IBM InfoSphere Replication Server and Data Event Publisher

IBM InfoSphere Replication Server and Data Event Publisher — Save 50%

Design, implement, and monitor a successful Q replication and Event Publishing project with IBM InfoSphere Replication Server and Data Event Publisher using this book and eBook

$35.99    $18.00
by Pav Kumar-Chatterjee | August 2010 | Enterprise Articles IBM

In the previous articles IBM WebSphere MQ commands and MQ Listener, Channel and Queue Management, we illustrated the working and setup of WebSphere MQ and we also took a look at how we manage the WebSphere MQ Listeners, channels and queues respectively.

In this article by Pav Kumar-Chatterjee, author of IBM InfoSphere Replication Server and Data Event Publisher, we will take a look at the following:

  • MQ sample programs
    • Server
    • Client
  • Dead Letter Queue handler
  • WebSphere MQ message format
  • MQ error messages

(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:

$ amqsput CAPA.TO.APPB.SENDQ.REMOTE QMA < hello

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.
SENDQ.REMOTE QMA < QMA_TEST1.TXT

Batch file—UNIX example:

"/opt/mqm/samp/bin/amqsput" CAPA.TO.APPB.SENDQ.REMOTE
QMA < QMA_TEST1.TXT

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:

$ amqsget CAPA.TO.APPB.RECVQ QMB

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.
RECVQ QMB
@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:

$ SYSA_QMA_TESTG_UNI_BA.BAT

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.
RECVQ QMB
@ECHO You should see: test1

From CLP-B, run the file as:

$ SYSB_QMB_TESTG_UNI_AB.BAT

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

IBM InfoSphere Replication Server and Data Event Publisher Design, implement, and monitor a successful Q replication and Event Publishing project with IBM InfoSphere Replication Server and Data Event Publisher using this book and eBook
Published: August 2010
eBook Price: $35.99
Book Price: $59.99
See more
Select your format and quantity:

(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:

WAIT (NO) REASON(MQRC_Q_FULL) ACTION (RETRY) RETRY (1)

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

MQMD

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

MQXQH

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

MQDLH

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

MQRMH

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

IMSrtm

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:

1

The queue name for reply messages.

2

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

3

Is the message persistent or non-persistent.

4

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

5

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.

6

Priority 0 to 9, with 9 being the highest.

7

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

8

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:

AMQ2053

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

AMQ2058

We have specified an invalid Queue Manager name.

AMQ2059

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).

AMQ2080

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

AMQ2085

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

AMQ2101

Damaged disks.

Summary

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:


IBM InfoSphere Replication Server and Data Event Publisher Design, implement, and monitor a successful Q replication and Event Publishing project with IBM InfoSphere Replication Server and Data Event Publisher using this book and eBook
Published: August 2010
eBook Price: $35.99
Book Price: $59.99
See more
Select your format and quantity:

About the Author :


Pav Kumar-Chatterjee

Pav Kumar-Chatterjee (Eur Ing, CENG, MBCS) has been involved in DB2 support on the mainframe platform since 1991, and on midrange platforms since 2000. Before joining IBM he worked as a database administrator in the airline industry as well as various financial institutions in the UK and Europe. He has held various positions during his time at IBM, including in the Software Business Services team and the global BetaWorks organization. His current position is a DB2 technical specialist in the Software Business. He was involved with Information Integrator (the forerunner of Replication Server) since its inception, and has helped numerous customers design and implement Q replication solutions, as well as speaking about Q replication at various conferences.
Pav Kumar-Chatterjee has co-authored the “DB2 pureXML Cookbook” (978-0-13-815047-1) published in August 2009.

Books From Packt


IBM Lotus Notes 8.5 User Guide
IBM Lotus Notes 8.5 User Guide

Application Development for IBM WebSphere Process Server 7 and Enterprise Service Bus 7
Application Development for IBM WebSphere Process Server 7 and Enterprise Service Bus 7

IBM Cognos 8 Report Studio Cookbook
IBM Cognos 8 Report Studio Cookbook

IBM Lotus Notes and Domino 8.5.1
IBM Lotus Notes and Domino 8.5.1

IBM WebSphere eXtreme Scale 6
IBM WebSphere eXtreme Scale 6

WebSphere Application Server 7.0 Administration Guide
WebSphere Application Server 7.0 Administration Guide

IBM Cognos 8 Planning
IBM Cognos 8 Planning

Domino 7 Lotus Notes Application Development
Domino 7 Lotus Notes Application Development


No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
i
c
V
4
9
X
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software