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.
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 firstname.lastname@example.org to request a free trial license.
I was prompted to write this post as a result of this list-server question.