There are various times when you can be presented with IBM MQ’s Open options in hexadecimal. You might see them in trace, or perhaps in an event message such as a Not Authorized (Type 2). Given a hexadecimal number that represents such options how do you decode them into the actual options?
MQOPEN >> 11:06:10.481473 24.20724 RSESS:0140bf Hconn: 11:06:10.481498 24.20724 RSESS:0140bf 0x0000: 0000000c 11:06:10.481527 24.20724 RSESS:0140bf Objdesc: 11:06:10.481615 24.20724 RSESS:0140bf Options: 11:06:10.481640 24.20724 RSESS:0140bf 0x0000: 00002010
You might see hex options in a trace
You can do the hexadecimal arithmetic yourself to decode them as I’ll show with a couple of examples, or you can use the API Exerciser in MO71 to do the hard work for you as I’ll show with a screenshot later on.
One problem when grabbing the options shown in traces by IBM MQ is that they are sometimes shown in reversed byte order. All the tricks below assume that you have the options in big endian order (or human readable order as I like to think of it), but on an Intel machine, some places where IBM MQ traces it out they may be shown in little endian order. Unfortunately there’s no rule of thumb as to when they are presented to you one way or the other. My rule of thumb for these is to see whether they look sensible. Remember that the most commonly used options are in the lower number ranges. If you’ve got a very big number, odds are that it needs some byte swapping.
Decoding hexadecimal options manually
If you look at the MQOO_* options in the CMQC.H header file you will see that they are defined there with their hexadecimal values.
We need to do some hexadecimal subtraction. We keep subtracting the largest option number we can until we get down to zero. We’ll start with an easy example:-
0x00002010 - 0x00002000 MQOO_FAIL_IF_QUIESCING = 0x00000010 - 0x00000010 MQOO_OUTPUT = 0x00000000
So 0x00002010 is MQOO_FAIL_IF_QUIESCING + MQOO_OUTPUT.
It is important to take away the bigger numbers first. Here’s another example.
0x0000B070 - 0x00008000 MQOO_BIND_NOT_FIXED = 0x00003070 - 0x00002000 MQOO_FAIL_IF_QUIESCING = 0x00001070 - 0x00001000 MQOO_ALTERNATE_USER_AUTHORITY = 0x00000070 - 0x00000040 MQOO_SET = 0x00000030 - 0x00000020 MQOO_INQUIRE = 0x00000010 - 0x00000010 MQOO_OUTPUT = 0x00000000
And so you can see the options which made up the number 0x0000B070.
Getting MO71 to do it for you
Of course, if hexadecimal arithmetic is not your thing, there is an easier way.
MO71 is the IBM MQ GUI Administration tool from MQGem, and it has a number of administration features as you would expect. It also has a variety of other features as well, and one of them is the API Exerciser.
You open the API Exerciser either by pressingor by choosing menu Action‑>API Exerciser…
Select advanced mode by checking the box at the bottom, which means you can now see all the tabs. Normally the API Exerciser only shows you the tabs that make sense, so normally you don’t get to see the MQOPEN tab until you have done an MQCONN.
Switch to the MQOPEN tab now that you can see it, and within that tab you should be looking at the Parameters sub-tab. You’ll see the list of MQOO_* options ready to be selected by clicking on. However, you want to decode a number rather that build up a set of open option by choosing individual ones, so you should simply paste or type your number into the box just above the list of MQOO_* options. You’ll see that when you do this, the API Exerciser highlights those in the list below that were part of the number you provided. You can provide your number in hexadecimal by ensuring you prefix it with ‘0x’, or you can provide it in decimal. Both input types will decode the number out into the options that make up the number.
I was prompted to write this post as a result of this question on the Vienna List Server.