Migrating a Queue Manager?

If you’re planning to migrate a queue manager, from one machine to another, or perhaps you’re consolidating some queue managers onto an MQ Appliance, you are probably aware of, and have even become familiar with, the steps required to export your object definitions and recreate them on the new queue manager. There are a number of tools available that can do this for you – including those from MQGem.

What about your messages though?

While it’s generally a good idea to reduce the load, and drain off as many messages as you can prior to migrating a queue manager. For example if it’s in a cluster, suspend it from the cluster before the move, to reduce the number of messages heading its way. Let all the applications drain the queues of messages and so on. However, it’s not always possible to drain every last message from all your queues.

QLOAD Offload all queuesIn the latest version of QLOAD, V9.0.1, there’s a new feature that will help out when migrating a queue manager. It allows you to unload the messages from all your queues, with one command. And then you can load the messages onto the queues on another queue manager, with one command (or piecemeal if you prefer). You would combine this with your favoured object definition export tool, and before loading the messages, you’d first recreate the queues on the new queue manager with the exported commands.

Here’s an example of QLOAD unloading all the queues on my queue manager.

qload -m MQG1 -i* -f*

The command will produce the following output to show what has been unloaded. Using the -i (lower case) flag means that the messages are only browsed on the queues and are not destructively removed.

APP1.INPUT                                           2  Done.
APP1.RESULT                                         10  Done.
APP2.INPUT                                           1  Done.
APP2.RESULT                                          4  Done.
Q1                                                  28  Done.
Q2                                                  42  Done.
SYSTEM.ADMIN.QMGR.EVENT                              7  Done.
SYSTEM.AUTH.DATA.QUEUE                             126  Done.
SYSTEM.CHANNEL.SYNCQ                                 3  Done.
SYSTEM.CHLAUTH.DATA.QUEUE                            5  Done.
SYSTEM.CLUSTER.REPOSITORY.QUEUE                      3  Done.
SYSTEM.DURABLE.SUBSCRIBER.QUEUE                      1  Done.
SYSTEM.HIERARCHY.STATE                               2  Done.
SYSTEM.INTER.QMGR.FANREQ                             1  Done.
SYSTEM.RETAINED.PUB.QUEUE                            2  Done.
WORK.REQUEST                                         7  Done.

Total : 7 Queues, 94 Messages
 plus : 9 System Queues, 150 Messages

Listing the directory where I ran the qload command, I can now see I have a file for each queue, with an extension .qld. If you prefer to have a different extension then you can alter the command accordingly. For example, use -f*.txt.

I can copy these files to another machine, or simply use a client connection to the other machine accordingly. Then I can run the following QLOAD command to load the messages onto the new queue manager.

qload -m MQG1 -o* -f*

QLOAD will make some checks when you run a load for multiple queues in this way. It will check that all the queues exist that it has files for in the directory matching the file pattern you specified (which assumes an extension of .qld if you just use ‘*’), and it will check that all those queues are empty. If it finds any problems it will report as follows:-

APP1.RESULT                            RC(2085) Unknown object name.
APP2.RESULT                            Not empty.

There are potential problems with these queues.
Are you sure you want to continue?

This lets you know to go and define the missing queues if you need them – there are messages to go onto them so the assumption is that you do need them. It also warns you of non-empty queues. Now if you’ve already started using this queue manager, you might be expecting this situation, but otherwise, you should rectify it, and then re-run QLOAD.

APP1.INPUT                                       2     Done.
APP1.RESULT                                      10    Done.
APP2.INPUT                                       1     Done.
APP2.RESULT                                      4     Done.
Q1                                               28    Done.
Q2                                               42    Done.
WORK.REQUEST                                     7     Done.

Total : 7 Queues, 94 Messages

You’ll notice that this output does not mention the SYSTEM queues that were offloaded. A generic upload will not upload most SYSTEM queues.
SYSTEM.CLUSTER.TRANSMIT.QUEUE and SYSTEM.DEAD.LETTER.QUEUE are the exceptions. The messages were unloaded to files though, so if you really need to load them you can do so the traditional way, by specifying the full queue name on the command and not using the generic upload.


The new version can be downloaded from the QLOAD Download Page. Any current licensed users of QLOAD can run the new version on their existing licence. If you don’t have a licence and would like to try out QLOAD then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.

QLOAD version 9.0.1 is released

MQGem Software is pleased to announce that a new version of QLOAD, our queue load/unload tool for IBM MQ, is now available.

The main features of the release are as follows:-

  • Unload and Load all queue with one command
    Great for taking a backups of messages or for migratory purposes. Save time and effort by doing all queues at once. Read more about this in Migrating a Queue Manager?.
  • Filter messages based on the reason code in the Dead-letter Header
    Very useful when dealing with messages on your Dead-letter Queue. Save off only those specific messages you are interested in.
  • Copy/Move messages based on the target Q/QMgr in a MQDLH or MQXQH
    Copy or move messages currently on the Dead-letter queue or a transmission queue, based on the target queue and/or queue manager in the MQDLH (Dead-letter header) or MQXQH (Transmission header).

The new version can be downloaded from the QLOAD Download Page. Any current licensed users of QLOAD can run the new version on their existing licence. If you don’t have a licence and would like to try out QLOAD then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.

QLOAD version 8.0.2 is released

MQGem Software is pleased to announce that a new version of QLOAD, our queue load/unload tool for IBM MQ, is now available.

The main features of the release are as follows:-

  • The ability to target multiple destination queues
    It is now possible to target multiple MQ queues and these can now be qualified by Queue Manager name. This means that QLOAD can now be used as a queue replicator.
  • The ability to provide the destination names in a single file
    Going hand in hand with the above feature, if you have a large number of queues you wish to distribute messages to it can be more convenient to put the names of the queues in a file and just refer to that file. This is now possible in QLOAD with the Destination file.
  • Various new verbose options such as
    • A progress indicator of how many messages have been processed
    • Which MQI verbs are being used and their reason codes.
    • The list of targeted destinations.

The new version can be downloaded from the QLOAD Download Page. Any current licensed users of QLOAD can run the new version on their existing licence. If you don’t have a licence and would like to try out QLOAD then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.

Using selectors in QLOAD

MQGem recently announced a new version of QLOAD with a number of enhancements. One of these enhancements is the ability to use a selector string to select certain messages.

The selector string is a feature in the MQ API which allows a more detailed selection of messages than just by Message ID and Correlation ID. It was added in WebSphere MQ V7.0.0 primarily to allow selection by message properties when subscribing to a topic – to narrow down the number of messages a subscriber is actually sent – but it also applies to queues. In addition to the selecting of message properties, you can also treat any of the Message Descriptor fields as a selectable property, just by using the appropriate syntax as we’ll see later.

We’re going to take a look at some of the things you might want to select by, but this is not an exhaustive list by any means. If you can think of others please add them in the comments, and I can incorporate them into the post.

Report Messages

This is the example that triggered the idea for this blog post. The question was asked how to use QLOAD to only act upon report messages.

Report messages are indicated by IBM MQ in a Message Descriptor field called Message Type (MsgType). It is a numeric field with a number of defined values (although you can also make up your own):-

  • Request (1)
  • Reply (2)
  • Report (4)
  • Datagram (8)

To act upon only Report messages, for example to purge them from your application’s reply queue, you would use the following invocation of the QLOAD program.

QLOAD -m QM1 -I MY.REPLYQ -f stdout -H "Root.MQMD.MsgType = 4"

Of course, you could go further than this to only act on the Expiry Report messages by selecting on the MsgType and the Feedback code. The Feedback code is also a field in the Message Descriptor and contains further information to fully define the report message, for example:-

  • MQFB_EXPIRATION (258)
  • MQFB_COA (259)
  • MQFB_COD (260)

To act upon only Expiration Report messages (and to demonstrate an SQL selector with two different fields in it), you would use the following invocation of the QLOAD program.

QLOAD -m QM1 -I MY.REPLYQ -f ExpiredMsgs.txt
-H "Root.MQMD.MsgType = 4 AND Root.MQMD.Feedback = 258"

Messages published on specific topics

As mentioned earlier, one of the original reasons for Selectors was for selecting on message properties. One of the message properties that the product adds to messages for you is the topic string when a message is published.

If you have a subscription that subscribes to multiple topics, the subscriber queue will have various messages with different values in the MQTopicString message property. You can use QLOAD to offload only those associated with a particular topic string using the following invocation:-

QLOAD -m QM1 -I SUB.Q -f Apples.txt -H "MQTopicString = 'Price/Fruit/Apples'"

Messages put by a particular user ID

With a queue containing messages put by a mixture of users, you may have a need to remove or copy off those by a specific user ID, perhaps to edit the user ID before putting them back.

To offload all the messages put by the user ID Paul, you can use the following invocation. As you can see it is necessary to provide all 12 of the characters of the UserIdentifier field since it is blank padded.

QLOAD -m QM1 -I Q2 -f PaulsMsgs.txt
-H "Root.MQMD.UserIdentifier = 'Paul        '"

Messages soon to expire

If you have messages with expiry set, you can of course see how much time the messages have left in the Message Descriptor. The Expiry field shows the number of 1/10ths of a second the message has left to live. Remember that messages with no expiration will have this field set to MQEI_UNLIMITED which has a value of -1 so we must also test that the value is positive.

So to see all the messages that will expire off your queue in the next hour, you can use the following invocation of the QLOAD program.

QLOAD -m QM1 -I Q1 -f stdout
-H "Root.MQMD.Expiry > 0 AND Root.MQMD.Expiry < 36000"

Hopefully this post has given you some ideas. There’s lots more you can do with QLOAD. If you’d like to try it out for yourself, please send us an email at support@mqgem.com to request a free trial license.


I was prompted to write this post as a result of this list-server question.

QLOAD version 8.0.1 is available

QLOAD Diagram After a period of time in free use mode, the QLOAD program can now be licensed in order to recieve support.

QLOAD is a program which allows you to be able to move or copy messages between queues and files. When selecting messages to move or copy, you can filter which messages to work with by message ID or correlation ID; or perhaps some part of the message content; or how old it is; plus many other criteria.

You can download the program and the user manual from MQGem Website: QLOAD Webpage.

Free use of QLOAD will expire at the end of September 2015, after which point you must have an MQGem licence to continue to use it.

This version of QLOAD has the following new enhancements, many of which were requested by users:-

  1. Built on older versions of Unix
    It should now be possible to run the latest version of QLOAD, with all it’s features, on older versions of Unix.
  2. Multi-version Support
    QLOAD will load the MQ libraries from the place identified by setmqenv.
  3. New Message Selection Features
    • Allow Message Selection based on a time-stamp
      For a long time QLOAD has enabled you to select messages based on age. However, now you can select based on an absolute time-stamp. So, you can now easily select those messages put ‘last week’, or yesterday.
    • Allow Message Selection based on Message Size
      Have you ever wanted to get rid of those ‘large’ messages? Well now it’s easy.
    • Allow Message Selection based on Message Priority
      You can now easily remove all the low or high priority messages from a queue.
    • Allow Message Selection based on SQL92 Selection String
      The IBM MQ product allows messages to be got based on an SQL92 selection string that allows you to write sophisticated selection criteria. QLOAD now allows you to use these selections string.
  4. Client Performance options
    You can now explicitly state that you wish QLOAD to use Read Ahead or Async Put. This can increase the speed of QLOAD quite significantly when run over client connections.
  5. New help features
    To make it easier to find the option you are looking for
  6. General Bug fixes
    Sadly software bugs are a fact of life, this version has fixed all those reported to me.