{"id":1070,"date":"2021-12-02T10:51:08","date_gmt":"2021-12-02T10:51:08","guid":{"rendered":"https:\/\/marketaylor.synology.me\/?p=1070"},"modified":"2022-03-21T09:47:18","modified_gmt":"2022-03-21T09:47:18","slug":"decoding-mqi-constants","status":"publish","type":"post","link":"https:\/\/marketaylor.synology.me\/?p=1070","title":{"rendered":"Decoding MQI constants"},"content":{"rendered":"\n

On Twitter, Michael asked<\/a>: “any logic or hints on how to interpret the PCF parameter names returned as multiples from the com.ibm.mq.headers.pcf?” Which is a very good question but a proper answer is far too long to type there. There are several different ways that you can approach the problem, depending on what you are trying to do. So this post talks about decoding MQI constants.<\/p>\n\n\n\n\n\n\n\n

The MQConstants.lookup()<\/em> method in the MQ Java classes knows about all of the definitions in the MQI. Or rather, it discovers all the definitions for itself as it works via reflection. And when you call it, it returns all of the definitions that match a regular expression pattern. For example: MQConstants.lookup(2035,\"MQRC_.*\")<\/code> returns MQRC_NOT_AUTHORIZED<\/code>. <\/p>\n\n\n\n

First know your prefix<\/h3>\n\n\n\n

It’s important when working with decoding that you know which MQI prefix you use to get the value and where different pieces might apply. Most constants are defined such that the first part of the name defines a unique range. The original tweet asked about<\/p>\n\n\n\n

Parameter : 1 MQIA_APPL_TYPE\/MQIAMO_MONITOR_FLAGS_OBJNAME\/MQIAMO_MONITOR_UNIT<\/pre>\n\n\n\n
which suggests that the program calling the lookup method was using a prefix of MQIA<\/code> instead of MQIA_<\/code>. The MQIA<\/code> and MQIAMO<\/code> types of number would be used in different circumstances, and appear in different types or areas of a message.<\/p>\n\n\n\n
Some of the prefixes are managed so that even combined they have a unique set of values. The MQIA<\/code>, MQCA<\/code>, MQBA<\/code> are part of a broad set that do not duplicate values across the entire class. That allows us to write code to find an attribute name like<\/p>\n\n\n\n
s = MQConstants.lookup(v,\"MQIA_.*\");\nif (s == null) s = MQConstants.lookup(v,\"MQCA_.*\");\nif (s == null) s = MQConstants.lookup(v,\"MQBA_.*\");\n...<\/pre>\n\n\n\n
On the other hand, there are some groups of constants where the uniqueness is applied to subsets. The prefix in these cases comes from the combination of the first two elements of the definition. For example, the MQTA_PUB<\/code> range overlaps with the MQTA_SUB<\/code> range. There’s no reliable way to know how these ranges have been allocated, you can only deal with it by testing and reviewing output.<\/p>\n\n\n\n
Simplest answer<\/h3>\n\n\n\n
The mqidecode <\/strong>program that’s part of SupportPac MS0P <\/a>is a very simple wrapper around that method. It automatically adds _<\/code> and the essential .*<\/code> to the given prefix parameter:<\/p>\n\n\n\n
$ mqidecode -p MQPL -v 1 -e\nMQPL_MVS\/MQPL_OS390\/MQPL_ZOS<\/pre>\n\n\n\n
You can see that here we have three “Platform” definitions for the same value, added as the branding changed. The Java method returns all of them in a single string but with ‘\/’ separators. This particular program does show one way of answering Michael’s question. It prints out all of the values returned, with just one additional filter. If there is a multi-value response, then it removes any element that I thought would not be particularly helpful:<\/p>\n\n\n\n
if (e.contains(\"_VERSION_\") || e.endsWith(\"_VERSION\"))\ncontinue;\nelse if (e.endsWith(\"_LAST\") || e.endsWith(\"_FIRST\"))\ncontinue;\nelse { ...<\/pre>\n\n\n\n
Bitfields<\/h5>\n\n\n\n
The mqidecode <\/strong>program can also deal with converting a value into its constituent bitfields. Typically an Options <\/em>field in one of the MQI structures will be an MQLONG (32-bit) integer, with several flags combined into a single number. For example, we can interpret OpenOptions <\/em>(MQOO) values, including some unused bits. The number (not this specific example as it’s got conflicting settings) might have come from looking at Activity Trace events:<\/p>\n\n\n\n
$ mqidecode -p MQOO -v 0xffffff -m\n MQOO_INPUT_AS_Q_DEF (0x00000001)\n MQOO_INPUT_SHARED (0x00000002)\n MQOO_INPUT_EXCLUSIVE (0x00000004)\n MQOO_BROWSE (0x00000008)\n MQOO_OUTPUT (0x00000010)\n MQOO_INQUIRE (0x00000020)\n MQOO_SET (0x00000040)\n MQOO_SAVE_ALL_CONTEXT (0x00000080)\n MQOO_PASS_IDENTITY_CONTEXT (0x00000100)\n MQOO_PASS_ALL_CONTEXT (0x00000200)\n MQOO_SET_IDENTITY_CONTEXT (0x00000400)\n MQOO_SET_ALL_CONTEXT (0x00000800)\n MQOO_ALTERNATE_USER_AUTHORITY (0x00001000)\n MQOO_FAIL_IF_QUIESCING (0x00002000)\n MQOO_BIND_ON_OPEN (0x00004000)\n MQOO_BIND_NOT_FIXED (0x00008000)\n MQOO_RESOLVE_NAMES (0x00010000)\n MQOO_CO_OP (0x00020000)\n MQOO_RESOLVE_LOCAL_Q\/MQOO_RESOLVE_LOCAL_TOPIC (0x00040000)\n MQOO_NO_READ_AHEAD (0x00080000)\n MQOO_READ_AHEAD (0x00100000)\n MQOO_NO_MULTICAST (0x00200000)\n MQOO_BIND_ON_GROUP (0x00400000)\n  (0x00800000)<\/pre>\n\n\n\n
A slightly more sophisticated approach<\/h3>\n\n\n\n
Also in SupportPac MS0P are a bunch of plugins for Explorer that try to format most MQ events. Here, the intention is to make the values more readable, rather than correspond exactly to the spelling of the original definition. I do the same kind of removal as in mqidecode<\/strong>, but also have some explicit replacements. For example, _Q<\/code> gets replaced by _QUEUE<\/code>. Oddly enough, I can see that I had done something for the exact example given in the question:<\/p>\n\n\n\n
if (p.startsWith(\"MQIAMO\") && p.contains(\"MONITOR\"))\n  pieces[i] = null;<\/pre>\n\n\n\n
I guess that I knew that those definitions were irrelevant in the context where they might be returned. I can also see another replacement to aid readability (the mixture of spaces and underscores was deliberate, based on the phase of decoding I’d reached during the formatting):<\/p>\n\n\n\n
if (s.equals(\"Mqca_Base Object Name\/mqca Base Q Name\"))\n  s = \"Mqca_Base Object Name\";<\/pre>\n\n\n\n
The C solution<\/h3>\n\n\n\n
For non-Java programmers, there is an alternative way of getting the decoded values which I wrote about<\/a> back in 2015. The cmqstrc.h<\/em> header file contains mapping functions corresponding to the Java lookup method, one function per prefix.<\/p>\n\n\n\n
Generating the definItions<\/h4>\n\n\n\n
Probably the most pertinent part of this header file in regard to the twitter question is how it gets created. The MQ product source code has all the definitions in a single set of files that is used during the build process to create all the header file or copybook variations for different languages (C, Cobol, RPG etc) and different platforms. So we only have to update a single place when a new constant is added to the specification, and it ensures consistency. <\/p>\n\n\n\n
When I added the decoder header file to MQ in version 8, I did it by adding a new component to the generation tool. From the master files, it knows what data to print and in what format. I had to ensure there were no duplicates in the various generated blocks as it uses switch statements and those require uniqueness. Anything using the header file will simply not compile if there are two branches that have the same value. So I made choices – where there were multiple definitions for the same value in a given range, I picked my favourite. What I thought would be most useful or relevant. For the mqidecode <\/strong>example earlier, which tries to print the platform value, you will not find MQPL_MVS<\/code> in the MQPL_STR<\/code> function in the published C decoder file. There is only MQPL_ZOS<\/code> to match that number. Though the other variations do appear in the full list structures MQI_BY_VALUE_STR<\/code> and MQI_BY_NAME_STR<\/code> later in the file.<\/p>\n\n\n\n
The generation tool has quite a few of these hardcoded choices, along with some other rules. Such as where to use two parts of the definition as the set (prefix) name. Or some definitions that you would never expect to see in program output. Or which cannot be usefully decoded. This is a fragment from the generator program (false<\/code> means that the constant will not appear in cmqstrc.h<\/em>):<\/p>\n\n\n\n
if (s.equals(\"MQTYPE_LONG\")) {rc = false;}\nif (s.startsWith(\"MQXR2_\") && !s.equals(\"MQXR2_DEFAULT_CONTINUATION\") && (v == 0)) {rc = false;}\nif (s.equals(\"MQZCI_DEFAULT\")) {rc = false;}<\/pre>\n\n\n\n
A lot of these rules came from iteratively trying them and looking at the output until the code compiled and I was happy with the output. There are other things I’d like to do with this header file, but it already fulfills its primary requirement.<\/p>\n\n\n\n
Using the definitions<\/h4>\n\n\n\n
One example of where the C definitions are used is in the amqsevt <\/strong>sample program. It knows from the context which prefixes are relevant and will do the decoding. It still does some additional reformatting on the definition for readability, such as changing Q<\/code> to QUEUE<\/code>. You can see this processing in the source file. When attributes need to be converted to a JSON format, then this is done very simply after those “English” replacements are done – remove underscores and convert the first letter of the elements so it comes out in camelCase. This simple heuristic means that the JSON names are not guaranteed to be identical to the names used by the REST Admin API<\/a> but they are fairly similar.<\/p>\n\n\n\n
The C cmqstrc.h<\/em> header file is also used by my tools that build the MQI interfaces for some other languages – it constructs the equivalent of the definition files for the Go and NodeJS bindings. Maybe one day I’ll add those languages to the core generator program but since those language projects work on different schedules than the real product releases, it can be difficult to synchronise the updates.<\/p>\n\n\n\n
Warning: amqsrua events are not so easily decodable<\/h3>\n\n\n\n
One warning about decoding the MQI constants. You can’t use amqsevt <\/strong>or equivalent approaches to work with the queue manager metrics generated through the publish\/subscribe mechanism shown by the amqsrua <\/strong>sample. <\/p>\n\n\n\n
When you try using amqsevt<\/strong>, you get something that appears to work but actually makes no real sense. The CCSID is obviously not a metric, so that gives a clue that it might be wrong. <\/p>\n\n\n\n
$ amqsevt -t \"\\$SYS\/MQ\/INFO\/QMGR\/QM1\/Monitor\/STATMQI\/PUT\" -m QM1\nSample AMQSEVT start\nPress ENTER to end\n\n**** Message #1 (380 Bytes) on Topic $SYS\/MQ\/INFO\/QMGR\/QM1\/Monitor\/STATMQI\/PUT ****\nEvent Type : None [0]\nMessage Type : Statistics [21]\nReason : None [0]\nEvent created : 2021\/12\/02 10:32:24.51 GMT\nQueue Mgr Name : QM1\nMonitor Class : 2\nMonitor Type : 3\nMonitor Interval : 2989229\nMonitor Flags None : 182\nAppl Type : 57916\nCoded Char Set Id   : 182\nCurrent Queue Depth : 0\n...<\/pre>\n\n\n\n
That’s because the “numbers” in the generated events are not MQI constants representing attributes, but keys to data maps returned by metadata queries (see the amqsrua source code to understand how that works).<\/p>\n\n\n\n
Summary<\/h3>\n\n\n\n
This is a lot longer than twitter would allow to answer what looks like a simple question. <\/p>\n\n\n\n
And a short answer could be a) live with it b) do some very simple eliminations c) do a lot more handcrafted work. But I hope it gives interesting background and some ideas on how you might work with MQI decoding.<\/p>\n\n\n\n
Update History<\/h5>\n\n\n\n