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.