Q: message operation menu

The Q program can do many different operations, many of which you will be familiar with, or which will be obvious just by glancing at the usage text of the program. There is a separate menu of options available at the prompt where you type in message data. I briefly mentioned this in the previous post about the Q program. I thought it might be worth taking a more detailed look at this part of the Q program today.

If you invoke the Q program like this:-

q -m MQG1 -o Q1

then at the prompt, you can type a ‘?’ to see the full usage text for this prompt:

Connecting ...connected to 'MQG1'.
>?
Formatted message :
 #end     = End program

 #[!][x][X][i][I][c[g[Count]]][p]Reps[/Size[/Delay[/Commits]]]
  [!]     = Don't send # string
  [x]     = Message is full range of hex characters
  [X]     = Message is indexed full range of hex characters
  [i]     = Index the messages
  [I]     = Index the messages using words
  [c]     = Checksum the messages
  [g]     = Checksum group - followed by optional count
  [p]     = Change properties
  Reps    = Number of messages to MQPUT
  Size    = Size of message (-ve range)
  Delay   = Number of milliseconds delay between MQPUTs (-ve range)
  Commits = Commit after n messages
>

Multiple Messages with one command

The simplest use of this menu is just using it to put multiple messages with one command string. So for example, if you type the following at the prompt:

#!20/1024/1000/5 My message text

You will be putting 20 messages, each of size 1K, with a 1 second delay between messages, and in transactions of 5 messages at a time, and the message text will start with “My message text”, i.e. because of the ! in the command, it won’t include the #!20/1024/1000/5 part of the command.

As you can imagine, this can be useful for having a trickle feed of messages appearing on a queue to test many aspects of an application. You can also randomise the size and delay by simply making the number negative. A message size of 1024 means you want messages exactly of that size. A message size of -1024 means you want messages to have a range of sizes up to 1024 bytes.

Random content

In the above example, we have a 1K message, but only a very short string of text. You might instead want to have some random content to fill your message. This can be done by adopting the first half of the check-summing feature which is explained in a moment. You can use a command like:

#!c20/1024

What’s not obvious here, that I should explicitly mention, is that there is a space character on the end of this command. It is this that ensures that the Q program will know to not put the #-command in as your message content, since you have a space on the end of the command. So long as you have the space, your message will contain 1K of random data.

Check-summing messages

If you want the ability to run messages through your system and test that they are being received complete and without corruption, you might choose to make use of the check-summing facility of the Q program. This has two parts. First the Q program generates messages with random content, and then calculates the checksum by adding up the numerical values of each byte in the message multiplied by its offset in the message. It will then print the checksum of the message to the screen.

Connecting ...connected to 'MQG1'.
>#c1/1024
[Chk.-683127]

Now, at the other end of the transmission of this message across your network, you can use the Q program to do a simple get of the message and it will print out the checksum again.

Connecting ...connected to 'MQG1'.
(1024 bytes) [Chk.-683127] #c1/1024)#.äßl.«R.I±±.Td.ª.<ç.>.$^....G.

Indexing messages

If you’re demonstrating a series of messages and what happens to them, for example when looking at how clustering round-robins your messages to different queue managers, you might find the indexing feature of the Q program useful. This feature allows you to very easily have your messages count up where they are in the sequence. Here’s an example (with a space on the end):-

Connecting ...connected to 'MQG1'.
>#!i10

which results in the following series of messages:-

Msg 1 of 10: Source Q1/MQG1
Msg 2 of 10: Source Q1/MQG1
Msg 3 of 10: Source Q1/MQG1
Msg 4 of 10: Source Q1/MQG1
Msg 5 of 10: Source Q1/MQG1
Msg 6 of 10: Source Q1/MQG1
Msg 7 of 10: Source Q1/MQG1
Msg 8 of 10: Source Q1/MQG1
Msg 9 of 10: Source Q1/MQG1
Msg 10 of 10: Source Q1/MQG1

Alternatively, you can have the number in words, by using the capital I alternative:

Connecting ...connected to 'MQG1'.
>#!I10

which results in the following series of messages:-

One
Two
Three
Four
Five
Six
Seven
Eight
Nine
Ten

The Q program can count pretty high too! 🙂

For those who like the ultimate in flexibility, you can build your own message string here as well, for example:-

Connecting ...connected to 'MQG1'.
>#!i10 Msg num %i (%I) out of %l (%L) put onto queue %q on qmgr %m

which results in the following series of messages:-

Msg num 1 (One) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 2 (Two) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 3 (Three) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 4 (Four) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 5 (Five) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 6 (Six) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 7 (Seven) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 8 (Eight) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 9 (Nine) out of 10 (Ten) put onto queue Q1 on qmgr MQG1
Msg num 10 (Ten) out of 10 (Ten) put onto queue Q1 on qmgr MQG1

So, if you have testing requirements, the Q program has many options for you. If you have more specific requirements for what your message content should look like when testing, remember that the QLOAD program can help you load up real message data at any rate you require.


Read more about the Q program, and download a copy, from the Q Web Page. If you would like to try out MQGem’s Q program before deciding whether to buy then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.

Tasks we use the Q program for

The Q program was (almost[1]) the first Support Pac (MA01) that Paul wrote, and he still uses it on an almost daily basis. Here are some of the tasks that we use it for on a quite regular basis.

Format Out Messages

If you have messages on a queue with a built-in IBM MQ format, then the Q program can format those out. For example, an event message, or messages on your Dead-letter queue. Sometimes just a quick look with Q is all you need to figure out what that message has to say.

Here is an example which browses (-i) the DLQ and formats (-df) the messages using detail level 3 (-df3):-

q -m MQG1 -i SYSTEM.DEAD.LETTER.QUEUE -df3

Empty a queue

You can use the Q program to quickly destructively get off all the messages on a queue, to ensure it is empty before you begin using it for something else. This is a common task we use it for. This works even when the queue is in use and the CLEAR QLOCAL command can’t be used.

Here is an example which destructively gets (-I) from Q1 and does not print the messages to the screen (-q), aka ‘quiet’ mode:-

q -m MQG1 -I Q1 -q

Copy the contents from one queue to another

When working with test messages that you have saved off for reuse, being able to quickly copy them onto your working queue is very handy. You can even do this from one queue manager to another.

Here is an example which copies messages, that is browses them (-i) from Q1 on MQG1, and puts them (-o) to Q1 on QMG2. It uses a shared blocking connection (-xb) to allow locally bound connections to be made to two queue managers in the same application:-

q -m MQG1 -xb -i Q1 -m MQG2 -o Q1

Put test messages

Sometimes you just need to have some test messages to work with.

  • I need a lot of messages
    Here is an example which puts 1000 simple test messages:-

    q -m MQG1 -o Q1 -M"#1000 Test Message"

    Alternatively, you can invoke the Q program like this:-

    q -m MQG1 -o Q1

    and then at the prompt, type in the # string.

    Connecting ...connected to 'MQG1'.
    >#1000 Test Message
    >
  • I need a big message
    Here is an example which puts only one, 10000 byte message:-

    q -m MQG1 -o Q1 -M"#1/10000 Test Message"
  • I need a continual trickle feed of messages
    Here is an example which puts 1000 messages, which a random size up 2000 bytes, with 100 ms delay between each message put:-

    q -m MQG1 -o Q1 -M"#1000/-2000/100 Test Message"

If you’ve not played with the # string in the Q program before, remember that you can type ‘?’ at the prompt to see the full help.

Hold open a transaction

It’s surprising how often this one comes up, but being able to start a transaction, and not commit it yet, can be very useful.

Here’s an example where the Q program will commit a transaction after 5 messages are put in the transaction (-p 5):-

q -m MQG1 -o Q1 -p5

And then at the prompt, you can put four messages, and now you have a transaction that contains work but is not yet committed:-

Connecting ...connected to 'MQG1'.
>#4 Test Message
>

Echo program

You can use the Q program to do a simple echo. That is, it will send any message it reads from a queue, back to the ReplyToQ in the message. You can also use the Q program to send messages with a ReplyToQ set.

Here’s the echo program (-e) which get-waits for 120 seconds (-w120) on queue Q1:-

q -m MQG1 -IQ1 -w120 -e

And here’s the driver program, putting to Q1 with a ReplyToQ set (-rREPLY.QUEUE) which is also waiting for 120 seconds (-w120) on the messages coming back to the ReplyToQ (the ‘+’ in -r+REPLY.QUEUE):-

q -m MQG1 -oQ1 -r+REPLY.QUEUE -w120

Create messages in a different code page

A very simple way to create messages in a different code page, is to first create some messages in your own codepage on a queue, and then get the Q program to convert them and put them onto another queue.

Here is an example where the Q program is reading messages from Q1 and converting them into USA EBCDIC (-c37) before putting them onto Q2:-

q -m MQG1 -iQ1 -c37 -oQ2

Do a simple publish to a topic string

The Q program has the full selection of both publish and subscribe options using topic strings and/or topic objects. The simple publish to a topic string is the most commonly used one for us.

Here is an example where the Q program is publishing a retained message (-Tr) to the topic string (-Ts:) 'Price/Fruit/Apples':-

q -m MQG1 -Ts:"Price/Fruit/Apples" -Tr -M"Test Message"

Q in your IBM MQ Toolbox

Summary

This is just a small selection of the things that the Q program can do. It is an invaluable tool to have in your IBM MQ toolbox!


Read more about the Q program, and download a copy, from the Q Web Page. If you would like to try out MQGem’s Q program before deciding whether to buy then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.


Footnotes:

  1. The very first Support Pac Paul wrote was MO00. Its purpose was to show how it was possible to write an MQI application in Win 3.1. In particular it showed how it was possible to issue an MQGET(Wait) on a non-pre-emptive O/S and ensure your windows could still re-paint themselves while you were waiting for a response message to arrive on a queue.

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.

Using User IDs with Q

There are a number of different way that you might interact with user ids when using the Q program. This blog post will provide examples of each.

Providing a User ID and Password at Connect time

q -m MQG1 -u mqgemusr -o Q1

Since no password has been provided with -U on the command line, Q will prompt for the password and what you type in will be echoed to the screen as asterisks.

Please enter password for QM(MQG1) User(mqgemusr) >********

Setting the user ID in the Message Descriptor

When putting a message, to a queue or topic, it is possible to set the various context fields in the Message Descriptor. To do this, you indicate that you need to set either Identity context (-CI) or All context (-CA) and then set the values for the various context fields you need to set. To setting the User Identifier, which is part of Identity context, invoke Q like this:

q -m MQG1 -o Q1 -Au:mqgemusr -CI -M"Test Message"

Using Alternate User ID when opening a queue/topic/sub

An IBM MQ application can MQOPEN a queue or topic, or make an MQSUB using an Alternate User id for the authorization checks.

To open a queue using Alternate User ID, invoke Q like this:

q -m MQG1 -o Q1 -au:mqgemusr

To open a topic using Alternate User ID, invoke Q like this:

q -m MQG1 -To:TOPIC1 -au:mqgemusr

To create (and close after) a durable subscription using Alternate User ID, and wait for messages, invoke Q like this:

q -m MQG1 -SdDo:TOPIC1 -Sn:SUB.TO.TOPIC1 -au:mqgemusr -w60

Note: When Q became an MQGem product, we took the opportunity to “tidy up” some of the flags. There is a chapter in the Q User Guide titled “Migrating from the MA01 IBM Support Pac” which details exactly all the changes. This may mean that some of the above examples differ from the way you would have done things with MA01.


Read more about the Q product, and download a copy, from the Q Web Page. If you would like to try out MQGem’s Q program before deciding whether to buy then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.

Q version 9.2.0 is released

Q program pocket knifeMQGem Software is pleased to announce that a new release of our Q Utility is now available.

This release was created to deliver various display features requested by customers, and after an extended beta period with those individual customers, it is now generally available. The new features are:-

Message Display Formatting

This version of Q now has a new formatting engine based on wide-characters. This means that Q has better display support for DBCS, MBCS and variant characters. You should see less dots in your output display now (dots are how non-printable characters are shown).

q -m MQG1 -i Q1 -df
[    7 bytes] Message Content
Z.rich

Prior version of Q

[    7 bytes] Message Content
Zürich

Q V9.2.0

New message summary display

Option -dy will tell Q to output just a one line summary of the messages on the queue.

q -m MQG1 -iSYSTEM.ADMIN.QMGR.EVENT -dy
Connecting ...connected to 'MQG1'.
  1.[ 320 bytes] QMgr Event - Reason(Alias queue type error) QMgr Name:'MQG...
  2.[ 320 bytes] QMgr Event - Reason(Unknown alias base queue) QMgr Name:'M...
  3.[ 320 bytes] QMgr Event - Reason(Unknown alias base queue) QMgr Name:'M...
  4.[ 236 bytes] QMgr Event - Reason(Unknown object name) QMgr Name:'MQG1' ...
No more messages.

New formatted Put Date/Time option in ISO 8601 format

The new Put Time format is displayed based on the -dz and -dZ option which display the time in UTC or local time respectively.

q -m MQG1 -iQ3 -dz
Connecting ...connected to 'MQG1'.
PutDateTime  : 2020-09-07T03:17:45Z
Hello MQ World
No more messages.

UTC time display

q -m MQG1 -iQ3 -dZ
Connecting ...connected to 'MQG1'.
PutDateTime  : 2020-09-07T15:17:45+12:00
Hello MQ World
No more messages.

Local time display

Message limiting

The message limit parameter -L has been enhanced to contain both an optional start and end limit. For example -L3: will display just the 3rd message. -L5:7 will display messages 5,6 and 7. As before -L10 will display the first 10 messages.

XML formatting

By default XML leaf tags will be displayed on a single line. The previous method of displayed them on three lines can be obtained using option -dL.

q -m MQG1 -i PRODUCT.DATA -dfL
<Product>
  <Name>
    MQEV
  </Name>
  <WebpageURL>
    https://www.mqgem.com/mqev.html
  </WebpageURL>
</Product>

Prior release behaviour

q -m MQG1 -i PRODUCT.DATA -df
<Product>
  <Name>MQEV</Name>
  <WebpageURL>https://www.mqgem.com/mqev.html</WebpageURL>
</Product>

Q V9.2.0 default behaviour

PCF Groups

By default Q will now display the boundaries of PCF groups. This can be suppressed using the -dB option.

q -m MQG1 -iSYSTEM.ADMIN.COMMAND.EVENT -df1
[ 544 bytes] Message Content
Command :99 (Command event)
Reason :2413 (PCF Command)
Parameter Id :8001 (Group Command Context)
Parameter Id :3045 (Event User Identifier)
Value :'mqgemusr '
Parameter Id :1011 (Event Origin)
Value :3 [0x'3']
Parameter Id :3047 (Event Queue Manager)
Value :'MQG1 '
Parameter Id :3050 (Event Appl Name)
Value :'MQGem Software MQSCX '
Parameter Id :1021 (Command)
Value :8 [0x'8']
----------------------------------------- PCF group (Group Command Context) --
Parameter Id :8002 (Group Command Data)
Parameter Id :2016 (Q Name)
Value :'Q1 '
Parameter Id :20 (Q Type)
Value :1 [0x'1']
Parameter Id :15 (Max Q Depth)
Value :99999 [0x'1869F']
-------------------------------------------- PCF group (Group Command Data) --
--------------------------------------------------- Command (Command event) --

A command event, trimmed a little for brevity, showing two PCF groups


The new version can be downloaded from the Q Download Page. Any current licensed users of Q can run the new version on their existing licence. If you don’t have a licence and would like to try out Q 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.

Announcing Q from MQGem

SupportPac MA01 was written by Paul Clarke back in June 1995. It was one of the first SupportPacs for MQ as you can tell by its number. Paul wrote it because the amqsput, amqsget and amqsbcg samples didn’t give him the flexibility he wanted. It became a very handy tool in the pocket of many an MQ administrator over the years.

When Paul left IBM to form MQGem Software, the MA01 SupportPac was discontinued, and it’s source code put on GitHub for anyone who wanted to build it and run it themselves. However, many MQ users don’t want the complication and expense of looking after home-built tools, and would prefer a fully supported product. As such, a few of our customers have asked whether we would be willing to continue to maintain and enhance the Q program, and so here it is.

Q program pocket knife

A veritable pocket knife of features

The Q program from MQGem has moved on a little from the last version that was the MA01 SupportPac, after all we’ve continued to use it as a very helpful tool here inside MQGem Software. Some of the new features are:-

  • IBM MQ Multi-version Support
    Q will load the MQ libraries from the place identified by setmqenv.
  • New help features
    To make it easier to find the option you are looking for since the Q program does have a lot of flags!.
  • Message formatters added
    Formatters for JSON, EDIFACT, CSV and FIX message formats have been added.
  • Character substitution
    This will display text such as &gt; as the character ‘>’.
  • 64-bit executable
    The Q program is now 64-bit across all platforms.
  • Minor flag enhancements
    1. The special message format string which starts with the ‘#’ character previously had a 40 character limit. This has been lifted.
    2. MQRO_PASS_CORREL_ID has been added to the confirm options on the -n flag as -n[passc].
    3. You can use -dt to print out the offsets of a message
    4. The prompt menu used by -xc to set various client connection channel settings such as TLS and exits has been updated to only request valid exits for a client channel, and to use a more modern CipherSpec by default.
    5. The use of truncation on an MQGET has been made safer by requiring the user explicitly select MQGMO_ACCEPT_TRUNCATED_MESSAGE when using the -=> flag by using the optional ‘t‘ flag, to give -=t<length>.
    6. The Commit interval (-p) flag has been extended to also take an optional commit interval after which an incomplete transaction, that is one that has not reached the requested total number of messages, will be committed anyway.
    7. The subscribe call created with the -S flag can be additionally configured to use MQSO_SET_CORREL_ID by using the -gc:CorrelId flag.
  • Flags renamed
    Some minor flags have been renamed to improve usability and consistency. These are listed in full in the User Guide. The majority of the flags are exactly the same as they were in the Support Pac.

Even if you don’t intend to purchase a licence, you may find value in downloading the user guide. At long last we have a manual for Q! As we said above, the parameters are not absolutely identical to the SupportPac, but the majority are the same, and the vast majority of the manual is still applicable to the SupportPac. You may well discover features you never knew that Q had.


Read more about the new product, and download a copy, from the Q Web Page. If you would like to try out MQGem’s Q program before deciding whether to buy then send an email to support@mqgem.com and a 1-month trial licence will be sent to you.

Using selectors in Q and QLOAD

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.

This post was originally written for QLOAD, and all the example commands shown use QLOAD, but the -H parameter works in exactly the same way in the Q program too.

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"

Messages with a particular Correlation ID

While you might not always choose to do such a selection using the SQL92 selector string, this one does illustrate the quoting problem you might come across when using such things with a command line tool. In order to do this, the selector string that you pass into the IBM MQ API needs to be as follows:-

Root.MQMD.MsgId="0x414D51204D5147312020202020202020664C395D20115802"

Specifically, it needs to have the double quotes exactly as shown. Now the question becomes, how do I pass that into a command line program such as Q or QLOAD?

On Windows, to get round the command interpreter, I need to issue the following command and double up all instances of double quotes that are inside the string.

QLOAD -m QM1 -i Q1 -f stdout -H "Root.MQMD.MsgId=""0x414D51204D5147312020202020202020664C395D20115802"""

Whereas, on Linux (using the bash shell) my command looks like this with escape sequences in order to get the double quotes in the correct place.

QLOAD -m QM1 -i Q1 -f stdout -H "Root.MQMD.MsgId=\"0x414D51204D5147312020202020202020664C395D20115802\""

Helpfully, when you are using selectors with QLOAD, it’s output will include the selector it is attempting to use. If it doesn’t have the double quotes in it like the initial example in this section, you need to do something to convince your shell to put double quotes there. Here’s the output you will see in a working command. The single quotes in this output are added when printing out the selector to show the boundaries of what was passed in. The double quotes are what you managed to pass in.

Message selection active:
  Messages matching selector 'Root.MQMD.MsgId="0x414D51204D5147312020202020202020664C395D20115802"'

Hopefully this post has given you some ideas. There’s lots more you can do with Q and QLOAD. If you’d like to try them 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.