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.
MQGem Software 