Is there a way to delete a single message from an MQ queue?

IBM Support recently released a Support Doc which posed the question:-

Question

Is there a way to delete a single message from an MQ queue (arbitrary position in the queue)?

The document described a couple of options. In this post we cover how to do this using MQGem tools as several of them offer this capability. Open up the twisty for each tool to read how to do this.

Using MO71

In MO71 you can browse a list of messages on a queue, then from that list, select an individual message (or multiple messages if you need to). Then press the Delete button, or select Delete from the right-mouse button context menu and the selected message(s) will be deleted.

MO71 uses the MQ facility, get by message token, so only the exact message(s) that you select from the list will be deleted. While the position of the message on the queue is shown, this is not used for deletion and neither is Message Id, since there is no guarantee that this will be unique either. Each message on a queue is guaranteed to have a unique Message Token.

Alternatively, you can double click on a message from the list, to view the whole message individually. Then from that display, having checked all the details, and made sure it is the message you want to delete, you can press the Delete button, or select Delete from the context menu.

Take care when deleting messages from a production queue manager. Consider that it might be safer to Move the message(s) to a separate holding queue, just in case the message proves to be important after all. MO71 makes it simple to Move messages too. Just fill in the holding queue name, and then press the Move, rather than Delete, button.

Using the Q program

To delete a single message from an MQ queue using the Q program, you should first discover the message ID of the message you wish to delete, to ensure you are addressing the correct message that you intend to delete. Do this by displaying the messages on the queue like this:-

q -m MQG1 -i Q1 -dd

This will browse (-i) the messages on the queue and display the MQMD after the MQGET (-dd) allowing you to see the Message ID of each message on the queue. You will see output like this for each message:-

==============================================================
----- MQMD after MQGET -----
[  324 bytes] Message Descriptor (MQMD)
Report       :00000000
Message Type :8 (Datagram)
Format       :'MQSTR   ' (String)
Priority     :0 (Lowest)
Persistence  :0 (Not Persistent)
Message Id   :414D51204D514731202020202020202099FA4A6020B74B02
              A M Q   M Q G 1                 . ú J `   · K .
ReplyToQ     :'                                                '
ReplyToQMgr  :'MQG1                                            '

Now you can copy that message ID and use it on another invocation of the Q program to delete that specific message from the queue.

q -m MQG1 -IQ1 -gxm:414D51204D514731202020202020202099FA4A6020B74B02

Bear in mind that message IDs are likely to be unique, but this is not guaranteed. It would be safer to move the messages to a separate queue, before deletion. This is simple to achieve using a command like the following:

q -m MQG1 -IQ1 -o HOLDING.Q 
-gxm:414D51204D514731202020202020202099FA4A6020B74B02
Using QLOAD

If you have already browsed the queue contents and output them to a file, you can find the message Id of the specific message you are attempting to address by looking for the Message Descriptor attribute “MSI”. Here is a snippet from a QLOAD file to show an example.

A FMT MQSTR
A PRI 0
A PER 0
A MSI 414D51204D514731202020202020202099FA4A6020B74B02
A COI 000000000000000000000000000000000000000000000000

Now you can copy that message ID and use it on another invocation of the QLOAD program to delete that specific message from the queue. We would recommend using QLOAD to actually move that message to an output file, in case you change your mind about deleting it!

qload -m MQG1 -IQ1 -f c:\temp\deletedmsg.qld 
-gxm414D51204D514731202020202020202099FA4A6020B74B02

Alternatively, you can use the very flexible search and filtering capabilities of QLOAD to narrow down your search of messages on the queue until you find the one you wish to delete, and then offload it to a file, or delete it entirely.

For example, this invocation removes all messages on a queue that are older than one week, and moves them instead to the named file:-

qload -m MQG1 -I Q1 -T7:0:0 -f c:\temp\oldmsgs.qld

Another example, here we remove messages larger than 1MB from a queue:-

qload -m MQG1 -I Q1 -z 1M -f c:\temp\bigmsgs.qld

A third example, here we remove message containing the string “Acme Limited”:-

qload -m MQG1 -I Q1 -s "Acme Limited" -f c:\temp\acmemsgs.qld
Using MQEdit

In MQEdit you can browse a list of messages on a queue, then from that list, select an individual message (or multiple messages if you need to). Then press the Delete button, or select Delete from the right-mouse button context menu.

MQEdit uses the MQ facility, get by message token, so only the exact message that you select from the list will be deleted. While the position of the message on the queue is shown, this is not used for deletion and neither is Message Id, since there is no guarantee that this will be unique either. Each message on a queue is guaranteed to have a unique Message Token.

Alternatively, you can double click on a message from the list, to view the whole message individually in the pane below, and then from that pane, having checked all the details, and made sure it is the message you want to delete, you can select “Delete Message” from the context menu.

Particularly for production queue managers, we would always suggest that it is safer to move message(s) to a holding queue rather than deleting them immediately. In MQEdit it is very simple to move a message between queues, all you need do is drag and drop the required message(s) from one queue to another. You can even copy and move messages between queue managers this way.


If you don’t have any of these tools, but would like to try any or all of them out, please contact support@mqgem.com and a 1-month trial licence will be sent to you with no obligation to buy. You can download the tools from our website.

Text Files in Preview Pane

If you’re anything like me, you have a number of text files on your Windows machine that do not use the .txt file extension.

For all of these I have associated Notepad as the application to be used by default when I double click on these file types from the Windows File Explorer. I’m probably a 70:30 command line vs File Explorer user, but it is from time to time handy to be able to double click too.

What I’d never managed to figure out though (until today) was how to get the preview pane in Windows File Explorer to display these text formats with different file extensions. Now that I have found out how to do it, I thought I would share it with all of you too.

Windows File Association Dialog

Windows File Association Dialog

Firstly, it’s important to have the file association in place first, specifically the “Always use this app to open … files” checkbox. This seems to be what adds the file extension into the list you are about to manipulate. So take a moment to make sure all the extensions you want to preview have a default application set.

Now open the registry editor and navigate to Computer > HKEY_CLASSES_ROOT. In here you will see a list of all the file extensions your machine knows about. Locate your file extension that you want to preview (remember you can type into the entry field just below the menu bar). Select the file extension, in this example I am fixing up the .mqx extension; and on the right hand pane right-click and select New > String Value. Give the new key the name “PerceivedType” and then modify it to give it the data value of “text”.

Adding a new String Value in Windows Registry

Adding a new String Value in Windows Registry

Giving new registry key a value of text

Giving new registry key a value of text

Now go back to your File Explorer and you should be able to see your .mqx file in the preview pane.

View .mqx file in Preview Pane

View .mqx file in Windows File Explorer Preview Pane


Many thanks to Scott Williams who wrote about this in a blog post in 2013 which I finally stumbled across in 2020 and it made my day!

JCL with long PARM strings

Prompted by Colin Paice’s recent blog post on bringing your JCL out of the 1960s, I thought I would write this post about a new feature of JCL I recently discovered.

I am quite comfortable creating/editing JCL, but one thing I do hate with a passion is long PARM strings. I can never remember quite which column the continuation line is supposed to start on, and it just makes your parameters hard to read too. You may have noticed a number of features in our recently provided products on z/OS which help to keep PARM strings short.

When testing our recently released QLOAD on z/OS, where there simply are times when you need long PARM strings, I came across a recently added JCL feature called PARMDD. I believe it was added in z/OS 2.1.

Instead of coding the PARM parameter on an EXEC statement inline, this instead allows you to point it to a DD card where you have then have as many lines of parameters as you need. These various lines are stripped of their trailing white space, concatenated together and then passed to your program. You can have this DD card point to a file, but I like to have the parameters inline in the same JCL file.

Here’s an example of one such long parameter when using the QLOAD delimited file feature.

//QLOAD    JOB
//*********************************************************************
//* QLOAD Load Delimited File
//*********************************************************************
//DELIMQL  EXEC PGM=QLOAD,PARMDD=PARMS
//PARMS    DD   *
-m MQG1 -o Q1 -Cd -f"DD:DELIM" -nF -n"is:<msg>" -n"ie:</msg>"
 -n"ip:<usr>" -n"iq:</usr>"
/*
//STEPLIB  DD DSN=GEMUSER.USER.LOAD,DISP=SHR                         
//         DD DSN=IBM.MQ.SCSQAUTH,DISP=SHR                           
//         DD DSN=IBM.MQ.SCSQANLE,DISP=SHR                           
//SYSPRINT DD SYSOUT=*  
//SYSOUT   DD SYSOUT=*      
//DELIM    DD DSN=GEMUSER.MSGFILES(EXMPL1),DISP=SHR
//MQGEML   DD DSN=GEMUSER.MQGEM.LIC,DISP=SHR
//

Now isn’t that so much easier to use and to read, than your standard continuation PARM parameter?


If you want to give this JCL feature a try, I think you just need to be on at least z/OS 2.1, and I’ve provided the link to the JCL Reference above.

You can download QLOAD for z/OS from the QLOAD Download Page. If you’d like to try out QLOAD on z/OS, please email support@mqgem.com and a 1-month trial licence will be sent to you.

QLOAD on z/OS

MQGem Software is pleased to announce that QLOAD, our queue load/unload tool for IBM MQ, is now available natively on z/OS.

Back when QLOAD was a SupportPac, it was available on the z/OS platform, and we are pleased to be able to once again provide it on z/OS.

QLOAD has evolved somewhat from the days when it was a SupportPac, and there have been many features added since then. These features are now also available natively on z/OS. Some of the highlights of those additional features include:

  • Using Delimited Files
    Originally QLOAD only read in files in its native format, but this feature allows files of any format to be used to load messages onto queues, one message per line, or with delimiter marking the start and end of each message. Read more here.
  • Required Rate
    This feature of QLOAD allowed you to test whether your system can handle a particular rate of messages, or even discover what rate of message your system can handle. Read more here.
  • Generic Unload/Load
    Perhaps you need to migrate a queue manager? This feature of QLOAD allows you to unload messages off all your queues, to files, with a single command. Read more here.
  • Using SQL92 selectors in QLOAD
    QLOAD has always had a number of different ways to filter the messages when you are unloading them. In MQGem’s QLOAD, you can also make use of the SQL92 selector string to filter your messages. Read more here.
  • And many more…
    If you have been a user of QLOAD on z/OS at the SupportPac feature level, I strongly recommend you download the user guide and go to the very back of the guide and page through the sections detailing “what’s new” in each release, to get a full picture of all the features that have been added to QLOAD since MQGem released it.

To enable QLOAD to run on z/OS you require a z/OS specific licence. A distributed platform QLOAD licence will not enable QLOAD on z/OS to run.


You can download QLOAD for z/OS from the QLOAD Download Page. If you’d like to try out QLOAD on z/OS, please email support@mqgem.com and a 1-month trial licence will be sent to you.

QLOAD: Using delimited files

The two most recent versions of QLOAD have added a feature to allow you to upload messages onto queues using QLOAD even when the file is not in the standard QLOAD format (i.e. it wasn’t from a QLOAD unload).

UploadDelimitedFileIn fact, the file can be in almost any format you want, so long as it is possible for you to describe where the messages are in the file.

QLOAD can now use files containing message data where each message is delimited from the next message in some way. This could mean that there are tags, or separator characters between the messages or even, the simplest example, that each message is on a new line.

Message text 1
Message text 2
Message text 3

msgs.txt: A file with one message on each line

To load the above file onto a queue, with one message taken from the text on each line, you would use the following QLOAD invocation.

qload -m MQG1 -o Q1 -f msgs.txt -Cd -nn

You haven’t specified any delimiters on this command, and that is because QLOAD assumes that new line is the delimiter you want if you don’t say otherwise. The -n switch is what says you want to parse a delimited file, and saying -nn tells QLOAD not to include the delimiters (in this case the new line character) as part of the message text. You could be explicit about the delimiter in use with the following command.

qload -m MQG1 -o Q1 -f msgs.txt -Cd -nn -ne:"\n"

In our next example, we have a file with some character separators.

message1/message2/message3/message4/

data.txt: A file with single character separators

To load the above file onto a queue, with one message taken from the text on each line, you would use the following QLOAD invocation. Note that you must have the final character delimiter for all four messages to be found.

qload -m MQG1 -o Q1 -f data.txt -Cd -nn -ne:/

Helpfully, QLOAD will output a message to tell you how many messages it has found with a prompt before you continue, to help you spot when it hasn’t found all the messages you hoped it would find.

4 messages found in the file. Do you want to continue? (y/n)

If you have explicit start and end delimiters, then you can start to jump past data in the file that is not part of a message, which is handy for commentary. For example with the following file:-

Here are a few messages
[message1][message2]
and then here are a few more
[message3]
[message4]
[message5]

info.txt: A file with start and end delimiters, and comments

To load the above file onto a queue, ignoring the comments and only pulling out the message data between the square brackets, you would use the following command.

qload -m MQG1 -o Q1 -f info.txt -Cd -nns:[ -nne:]

There is also a short-hand you can use when you have delimiters of the same length, as shown in the next command.

qload -m MQG1 -o Q1 -f info.txt -Cd -nnd:[]

Delimiters don’t have to be single characters, nor do they have to be excluded from the message. You may well have message content that is naturally delimited, for example XML messages. The outside tag of the structure of your XML message may well be all you need as a delimiter.

<message>
  <date>12 Jun 2019</date>
  <priority>High</priority>
  <department>AG75</department>
  <code>HT7228</code>
</message>
<message>
  <date>29 Aug 2019</date>
  <priority>Medium</priority>
  <department>AL23</department>
  <code>LL3460</code>
</message>

xml.txt: A file with XML message data

A file like this where the delimiter is part of the message data can be loaded with the following command.

qload -mMQG1 -oQ1 -f xml.txt -Cd -ni -ns:"<message>" -ne:"</message>"

In this case you cannot use the -nd flag because the delimiters are not of the same length, and you must specify each one individually using the start (-ns) and end (-ne) flags.

If you need to have some message properties added to your message when it is uploaded, this data can also be found are delimited text in your file. Looking again at the XML data example, here we have added some property data to the file.

<usr>
  <importance dt='i4'>1</importance>
</usr>
<message>
  <date>12 Jun 2019</date>
  <priority>High</priority>
  <department>AG75</department>
  <code>HT7228</code>
</message>
<usr>
  <importance dt='i4'>2</importance>
</usr>
<message>
  <date>29 Aug 2019</date>
  <priority>Medium</priority>
  <department>AL23</department>
  <code>LL3460</code>
</message>

xml2.txt: A file with XML message data and message properties

To load this file onto a queue, you now need to provide two sets of delimiters so that QLOAD can know where the message data is and where the property data is.

qload -m MQG1 -o Q1 -f xml2.txt -Cd -nis:"<message>" -nie:"</message>" -nip:"<usr>" -niq:"</usr>"

While it is likely that you will use this second set of delimiters for message properties, that is the <usr> folder in an MQRFH2 header, in fact you can use it to construct any MQRFH2 folder that you require since you provide the complete folder structure.

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.1.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:-

  • Non-QLOAD file can contain property data
    Extending the feature introduced in QLOAD V9.1.0, this allows your delimited file to contain a second set of delimiters to mark where property data to be added to the message is to be found. Read all about this feature here.
  • Fully qualified queue name separator character
    If your queue names contain one of the default separator characters that QLOAD looks for, you can now specify exactly which character should be considered a separator to avoid confusion.
    For example to put messages to a queue called Q1/SALES on queue manager MQG2:-

    qload -m MQG1 -f data.qld -$# -oMQG2#Q1/SALES

    or to avoid QLOAD thinking that you want to put messages to a queue called SALES on queue manager Q1, when actually your queue is called Q1/SALES:-

    qload -m MQG1 -f data.qld  -$#-oQ1/SALES
  • Backout queue
    This version of QLOAD will pay attention to the backout threshold (BOTHRESH) and re-queue name (BOQNAME) you have defined on any input queues, and re-queue any messages with an MQMD.BackoutCount that meet or exceed the threshold.
  • Application Name
    If your IBM MQ version is appropriate, QLOAD will set an application name of ‘MQGem Software QLOAD’
  • Summary Display
    The summary display is extended in this version to show more age and size ranges in its output. For example:

    Message Ages
    ============
    
    < 2  secs < 10 secs < 1   min < 1  hour < 1   day < 1  week
    --------- --------- --------- --------- --------- ---------
            0         0         0         0         0         2
    
    < 2 weeks < 4 weeks < 3 month < 6 month  1  year
    --------- --------- --------- --------- --------- ---------
            2         2        13       110         0         0
    
    Youngest Message : 4 Days 2 Hrs 29 Mins 28 Secs
    
    Oldest   Message : 19 Weeks 3 Days 3 Hrs 26 Mins 7 Secs
    
    Message Sizes
    =============
    
    < 100b <  1Kb <  4Kb <100Kb <  1Mb < 10Mb  50Mb
    ------ ------ ------ ------ ------ ------ ------ ------
         1    128      0      0      0      0      0      0
    
    Smallest Message : 4 bytes
    
    Biggest  Message : 368 bytes
  • Counting mode
    Sometimes you might want to simply discover how many messages are on your queue that meet a certain criteria. For example, how many are over a certain age, or how many contain a certain string of text. Older versions of QLOAD could be used to do such a count with a little bit of manipulation using a command like the following:-

    qload -m MQG1 -i Q1 -T05:00:00 -f null

    New in this version, you can specifically request a count of the messages as follows:

    qload -m MQG1 -i Q1 -T05:00:00 -dk

    or if you literally only want the number of the count as output, you can use:

    qload -m MQG1 -i Q1 -T05:00:00 -dK
  • Update Put Date and Put Time
  • Normally QLOAD will fill in all the context fields in a message from the file or queue you are loading from. In this version however, if you wish to do that but with a current PutDate and PutTime, you can use the -Ct option.

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.

MQGem tools on Linux on Little Endian Power

MQGem is pleased to announce the availability of three of its products on the Linux on Little Endian Power platform.

We have had these products available on Linux on Power for a number of years, and now have added the Little Endian platform to the list.

Thanks to those customers who requested it.

You cannot run a Big Endian application on a Little Endian platform and vice versa. Ensure you download the appropriate version of the tool for the platform you are using. For example, if you try to run the Big Endian version on a Little Endian platform, you will see an error something like this:-

-bash: ./mqscx: cannot execute binary file

If you are not sure which platform you are using, try one of the following commands:-

lscpu

which will show you output similar to:

Architecture:          ppc64le
Byte Order:            Little Endian
CPU(s):                ...

Or if you have an older version of Linux, which doesn’t provide that command, try:-

uname -a

which might give you hint.

Linux gemlnx4.mqgem.com 3.10.0-327.36.3.el7.ppc64le #1 SMP Thu Oct 20 04:58:48 EDT 2016 ppc64le ppc64le ppc64le GNU/Linux

Extra Reading Material


The new versions can be downloaded from the website from the links given above. Any current licensed users of these products can run them on the new platform using their existing licence. If you don’t have a licence and would like to try out any of our products then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.

QLOAD – Reading messages from the log

Version 9.0.3 of QLOAD, our queue load/unload tool for IBM MQ, was created for one specific customer requested feature, retrieving messages from your queue manager log.

IBM MQ comes with a utility, dmpmqlog, which can format your queue manager transactional log and dump out the contents of messages in a hex format (example below snipped for brevity).

LOG RECORD - LSN            
**********

HLG Header: lrecsize 720, version 1, rmid 0, eyecatcher HLRH

LogRecdType . . : AQM Put Message (257)
Eyecatcher  . . : ALRH                 Version . . . . : 1
LogRecdLen  . . : 700                  LogRecdOwnr . . : 256    (AQM)
XTranid . . . . : TranType: NULL
QueueName . . . : HELLO.WORLD.Q                               

Data  . . . . . : 
00000:  41 51 52 48 04 00 00 00 FF FF FF FF FF FF FF FF    AQRH....ÿÿÿÿÿÿÿÿ
:
00160:  4D 44 20 20 01 00 00 00 00 00 00 00 08 00 00 00    MD  ............
00176:  00 00 00 00 22 02 00 00 52 03 00 00 4D 51 53 54    ...."...R...MQST
00192:  52 20 20 20 00 00 00 00 01 00 00 00 20 20 20 20    R   ........    
:
00368:  20 20 20 20 20 20 20 20 0B 00 00 00 43 3A 5C 6D            ....C:\m
00384:  71 6D 38 30 30 34 5C 62 69 6E 36 34 5C 61 6D 71    qm8004\bin64\amq
00400:  73 70 75 74 2E 65 78 65 32 30 31 38 30 34 32 33    sput.exe20180423
00416:  30 34 33 34 33 34 35 36 20 20 20 20 00 00 00 00    04343456    ....
00432:  00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00    ............ÿÿ..
00448:  48 65 6C 6C 6F 20 57 6F 72 6C 64 21                Hello World!

Log To QueueThis format is a little tricky to extract the data from to reinstate your message. As you can see above, you get the MQMD and the message data all in one block. It gets even more tricky when your message is broken up into several log records!

This version of QLOAD hopes to make the process of recreating message from your transactional log files much simpler to do. It can only work when the messages you want are in the log file though. There’s no magic!

Running QLOAD against the queue manager log

With the following invocation, QLOAD will run the dmpmqlog utility and parse through the output looking for the queue you requested, in this example HELLO.WORLD.Q, and write any messages it finds to the HELLO.WORLD.RCOV queue on queue manager MQG2.

qload -m MQG1 -j* -i HELLO.WORLD.Q -m MQG2 -o HELLO.WORLD.RCOV

Since you are reading the log files using dmpmqlog, the queue manager, MQG1, cannot be running when this command is issued and so the messages cannot be put onto a queue on that queue manager as part of the command. In the above example I’ve chosen to put them onto a side queue on another queue manager but equally I could write them into a QLOAD file and then later put them onto the queue manager once it has started up again, as follows:-

qload -m MQG1 -j* -i HELLO.WORLD.Q -f HELLO_WORLD.qld
strmqm MQG1
qload -m MQG1 -f HELLO_WORLD.qld -o HELLO.WORLD.RCOV

Running QLOAD against output from dmpmqlog

If you have already run dmpmqlog, perhaps to determine whether the messages you wish to retrieve can be found in the log, then you may have already spent a few minutes waiting for the utility to complete. You can use the output files you generated from the utility as input into QLOAD.

dmpmqlog -m MQG1 -b > dmpmqlog.txt
qload -j dmpmqlog.txt -i HELLO.WORLD.Q -m MQG1 -o HELLO.WORLD.RCOV

Running QLOAD against copied off queue manager logs

A third alternative is to run QLOAD against queue manager log files that have been copied off. In this case you provide QLOAD with a directory containing these files.

qload -m MQG1 -j c:\mqmarch\log\MQG1 -i HELLO.WORLD.Q -m MQG1 -o HELLO.WORLD.RCOV

This command drives dmpmqlog with the -f parameter, and so the criteria for this directory must follow what is described in Knowledge Center for running dmpmqlog in that way. In addition, you must use the -m parameter to specific the queue manager name that these log files came from so that queue names can be found, and that queue manager cannot be running at the time.

The specified directory must contain the log header file (amqhlctl.lfh) and a subdirectory called active. The active subdirectory must contain the log files. By default, log files are assumed to be in the directories specified in the IBM MQ configuration information. If you use this option, queue names associated with queue identifiers are shown in the dump only if you use the -m option to name a queue manager name that has the object catalog file in its directory path.

QLOAD filtering

Whichever of the above methods you choose to use, you can add many of the QLOAD filtering options to your command.

For example, you can find all the messages containing a particular search string.

qload -m MQG1 -j* -i HELLO.WORLD.Q -s "World" -m MQG2 -o HELLO.WORLD.RCOV

Or perhaps you need to pluck out one specific message using its message id (or correlation id).

qload -m MQG1 -j* -i HELLO.WORLD.Q -gxm414D51204D51473120202020202020202604E15A21D49501 -m MQG2 -o HELLO.WORLD.RCOV

QLOAD also has time based filtering, so if you’re looking for a message from hours, days or weeks ago, you can go directly to that time period. This example is looking for messages that were put onto the queue between 18 and 19 hours ago.

qload -m MQG1 -j* -i HELLO.WORLD.Q -T0:18:00,0:19:00 -m MQG2 -o HELLO.WORLD.RCOV

Note: Filtering by Selection String (the -H parameter) is not available when your input source is a file (either a QLOAD file or an MQ log file) since it uses the Selector feature of MQOPEN.


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.

Use MQGem tools with IBM MQ on IBM Cloud

You may have seen the recent announcement from IBM about the experimental IBM MQ service running on IBM Cloud.
IBM Cloud

You can learn more with these resources:-

When you read the description of this new service in the Bluemix catalog, you’ll see it says the following:-

Manage MQ your way

Manage your cloud-based queue managers with the tools you know and love – including MQ Explorer, the MQ Console, or via MQ Script Commands (MQSC).

This blog post is here to assure you that the tools you know and love from MQGem Software; MO71, MQSCX, MQEdit and QLOAD can all also be used with IBM MQ running on IBM Cloud.

Once you have created your MQ on IBM Cloud Service and Queue Manager, as shown in the above video, and your queue manager is up and running, you’ll have a view something like this.

IBM Cloud QM List

A list showing my Running queue manager

Click on the three vertical dots on the right of your queue manager to “Download Connection info”, or alternatively view the details of your queue manager and then there is a button there too which allows you to download the “Connection Information”. Either way, you’ll be presented with a pop-up which allows you to download a plain text file which contains the queue manager name, hostname, port number and a couple of channel names, one called an Application Channel and one called an Administration Channel.

IBM Cloud Download Connection info

IBM Cloud Download Connection info

In order to remotely connect to your IBM Cloud queue manager you will also need to be able to log in. As the MQ on IBM Cloud documentation describes here, you need the API key as your password to go with the user id ‘admin’. Follow the instructions on that page to obtain your API key.

Now you have all the pieces of information you need to set up any of the MQGem Software tools to administer your queue manager on IBM Cloud. As a reminder, these are the things you will need.

Item From where
Queue Manager Name You invented it when you created the queue manager. If you’ve forgotten it, it’s also in the text file you downloaded with the connection information.
Channel Name The “Administration channel name” can be found in the text file you downloaded with the connection information.
Connection Name This is built by concatenating the “Hostname” and “Listener port” details (with brackets round the port number) that can be found in the text file you downloaded with the connection information.
User ID This is ‘admin’
Password This is the API Key that you created by following the linked instructions.

On the pages that follow, we cover how to use the above information you have gathered in your table to configure each of our tools to connect to your IBM MQ in IBM Cloud Queue Manager. Go directly to the page for the tool you want to use, or page through each one in turn.

  1. MO71
  2. MQEdit
  3. MQSCX
  4. QLOAD

If you don’t have a licence and would like to try out any of our tools then send an email, noting which tool you’d like to try, to support@mqgem.com and a 1-month trial licence will be sent to you.

QLOAD – Required Rate

Version 9.0.2 of QLOAD, our queue load/unload tool for IBM MQ, was created for one specific customer requested feature which we call Required Rate Processing.

Required Rate

QLOAD Source to TargetThis feature allows you to test the speed that your system, or specific applications in your system, can process messages. You may have a target rate you need to be able to achieve, and you can use QLOAD to send messages through the system at that rate to see whether the system (the channels and the applications) can keep up. You may for example have TLS channels; or message compression; or AMS message level encryption applied to the messages which are of course, changing the performance profile of the system. With QLOAD you can test the rate using exactly the same shape and size of messages that you will use in the production environment.

Starting with a queue that contains a representative selection of example messages, you can then use QLOAD to copy those messages and inject them into the system at the rate you require. In the example that follows, the required rate is 500 messages/second and the test is to run for 10 minutes.

qload -m MQG1 -i EXAMPLE.MSGS -o TARGET.QUEUE -R500:600

QLOAD will browse the EXAMPLE.MSGS queue and send copies of those messages to the TARGET.QUEUE. When it reaches the end of the EXAMPLE.MSGS then it will go back to the beginning of the queue and send them again, as often as required until the test ends. You can just have a single message on the queue and send it repeatedly, but to offset the cost of resetting the browse, it’s better to have 10 or more messages on the queue. In reality all your messages will not be the same, so a good selection of example messages is certainly worth collecting.

If you want the test to run until you tell it to stop, you can indicate that you want it to run indefinitely with an asterisk for the duration.

qload -m MQG1 -i EXAMPLE.MSGS -o TARGET.QUEUE -R500:*

There are two other ways you might use this feature.

Discover Achievable Rate

Instead of telling QLOAD to run at a certain rate, you might instead want to discover what your highest rate could be.

To run QLOAD in this way, you use a command like this:-

qload -m MQG1 -i EXAMPLE.MSGS -o TARGET.QUEUE -R*:*

And you will see output like the following, as QLOAD ramps up the rate.

Monitoring depth of queue 'TARGET.QUEUE'
Message Rate 802 msgs/sec
Message Rate 5200 msgs/sec
Message Rate 5548 msgs/sec
Message Rate 5516 msgs/sec
Message Rate 5409 msgs/sec
Message Rate 5566 msgs/sec
Message Rate 5503 msgs/sec

It does this by monitoring the depth of the target queue, which might be a transmission queue being read by a channel, or it might be an application queue being read either by the read application or by another instance of QLOAD acting as a sink.

qload -I TARGET.QUEUE -f null -w600

Trickle Feed the contents of a queue

So far you’ve seen QLOAD copy example messages from a source queue and inject them into the system over and over until the duration of the test is complete. Alternatively though, you could use this feature to move messages from a side queue (the contents of a batch run, or messages from a backout queue or a Dead-letter queue) back into the main system. If you have a large depth of these messages you may not want to load them back into the application queue all at once, since you know deep queues hurt performance. So instead you can trickle feed them into the system using QLOAD.

qload -m MQG1 -I SIDE.QUEUE -o TARGET.QUEUE -R50

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.