MQ

This is part of an occasional series of small blog posts where I (Morag) will write about some of the quirks in IBM MQ, in the hope of invoking the response, "Well, I didn't know that!" Read other posts in this series.

If you've programmed using the MQ API, you'll be used to the idea that there are numerous structures used in the MQI, such as the MQOD (Object Descriptor), MQPMO (Put Message Options) or MQCSP (Connection Security Parameters). You'll also be familiar with the concept that many of these structures have more than one version, and the version of the structure is increased when new fields are added to it.

To give a short example, look at the MQOD. When you are using it to describe the queue object you wish to open, the fields in the first version of the structure are all you need to use. However, if you want to open a topic, then you might need fields such as the ObjectString which is in the extension to the structure which took it up to version 4.

So, having got used to the idea that MQ API structures have versions, you might have then come across the MQCFH structure - the header structure for PCF format messages. Looking in the MQ header files you will see that the MQCFH structure has three versions.

#define MQCFH_VERSION_1                1
#define MQCFH_VERSION_2                2
#define MQCFH_VERSION_3                3

However, regardless of which version number you use, the actual MQCFH structure stays the same. That's a bit odd!

struct tagMQCFH {
  MQLONG  Type;            /* Structure type */
  MQLONG  StrucLength;     /* Structure length */
  MQLONG  Version;         /* Structure version number */
  MQLONG  Command;         /* Command identifier */
  MQLONG  MsgSeqNumber;    /* Message sequence number */
  MQLONG  Control;         /* Control options */
  MQLONG  CompCode;        /* Completion code */
  MQLONG  Reason;          /* Reason code qualifying completion code */
  MQLONG  ParameterCount;  /* Count of parameter structures */
};

This seemed an ideal candidate for a quirky post!

The MQCFH structure is the beginning of a longer data format. PCF messages begin with one of these and then are followed by any number of PCF sub-types, such as the MQCFST which describes a string, the MQCFIN which describes an integer, and so on. The full set are shown in the table below. The version field of the MQCFH is in fact a version number which applies to the whole data format of the message and not just that one small structure.

The original set of PCF sub-types are those shown in the table below as needing only a version 1 structure. These were around for many versions of MQ before they were joined by some additional types. A number of features were introduced into the IBM MQ product which made use of the PCF format, and they caused the PCF format to be enhanced with the addition of new sub-types.

Configuration events, which were initially introduced in WebSphere MQ V5.3 on z/OS, introduced the MQCFBS sub-type in order to describe the context fields from the application which had caused the changed, which include the byte-string field AccountingToken. This was when the MQCFH_VERSION_2 was introduced.

The MQCFH_VERSION_3 was introduced in WebSphere MQ V6 with various new sub-types used by:-

• WHERE clause for commands, which uses the MQCFSF, MQCFIF, MQCFBF to filter responses from the command server
• Command events, which uses the MQCFGR sub-type in order to contain the full PCF command message that sent to the command server as part of the event.
• Accounting and Statistics, which uses the MQCFIN64 and MQCFIL64 sub-types for some more granular duration recording.
• Trace Route, which makes extensive use of the MQCFGR sub-type to group together operation fields.

Later in IBM MQ V7.1, when Activity Trace was introduced, it had everything it needed already defined in the PCF format.

User PCF Messages

The PCF format, as well as being used extensively by queue manager features, is also available for you to use for your own application messages. There are a number of benefits of using PCF as a message format, the main one being that you can have a message containing string and integer data, and move it between ASCII and EBCDIC, or big and little endian systems, and the data conversion is all handled for you without the need to create data conversion exits.

If you want to use the PCF format with some of these newer sub-types, what should you do? Well, you could look at the table above and ensure you have a large enough version to cover the sub-types you have in use, or more simply you could ensure that you always have an MQCFH Version of MQCFH_VERSION_3. This version of the structure has been supported since WebSphere MQ V6, so all queue managers in support will understand it.

The policing of this is varied. If you use a V2 MQMD, you will not even be able to put a message if your MQCFH version is not high enough. However, it is possible to bypass this check by using a V1 MQMD. Having too low an MQCFH version (if you bypass the checking) may lead to later problems when trying to data convert the message. So, it is best to stick with a V3 MQCFH to be certain your message is correct.