Properly Parsing the Pieces of PCF

Body

PCF messages are unique within WebSphere MQ because they help to solve problems like remotely administering an MQ network as they grow and thus become more complex. Remote administration through their use helps to centralize task execution and can help with resource management, object manipulation, and performance monitoring just to name a few.

The product documentation in the IBM Knowledge Center provides some great reference material on the topic. Its chapters contain detailed information on these messages and the many ways in which they can be used. PCF messages (that is, messages using the programmable command format) allow for programmatic control by sending such messages to well known queues such as the SYSTEM.ADMIN.COMMAND.QUEUE (in the case of distributed platforms).

For example, when you issue an ALTER QMGR command, a PCF message is built. In the case of MQ running on z/OS, the command server will handle this command by processing the associated message on the SYSTEM.COMMAND.INPUT queue. These messages will always begin with a PCF header and then be followed by a number of parameter structures. But what do they really look like?

Well, in this example we'll look at a PCF event message (which is another type of PCF message that can be generated). Below is the header required at the start of the message. This example complements the product documentation topic "Structures for commands and responses". The two major parts of this type of message are the event header (below) and the event parameter data (discussed later).

The documentation topic "Command format Types of Structures" documents all of the possible values in the first word, ranging from MQCFT_NONE to MQCFT_INTEGER64_LIST. In this case the first word confirms this is a PCF event message. The second word tells us that this header has a total length of 36 bytes.

This particular PCF message was generated as the result of an ALTER QMGR so the MQCFH version is "2" for a configuration event. The event category is (MQCMD_CONFIG_EVENT).

The MQRC values included in this message are specific to events but you can refer to the "Reason code list" within documentation to see what any particular value means.

The last word in the header is important because the ParameterCount tells how many event data structures follow this header. In this example you should expect 5 data structures to follow this header and each of those will can be broken down in a similar way as described next.

The first (decimal 20) bytes of the structure below (called the fixed part) is mapped by MQCFST. The second word (00000020) means the entire structure (including the string) is (decimal) 32 bytes long and the first word defines this parameter as being for a string. What kind of string is it? The third word tells us this is a userid string that is associated with this configuration event and then the (StringLength) tells how long that userid string field is (IBMMQ padded with blanks).

Topic "Fields for MQCFST" is useful to interrogate the fixed part of this structure. All of the values that the third word might be (like MQCACF_EVENT_USER_ID) are listed out in the product documentation as well.

To finish out, I wanted to provide just one more parameter structure (since there are actually a total of five in this case). We've seen a string parameter, so below is an example of an integer parameter. The first word, as before, is the key to knowing immediately what type of parameter you're dealing with.

This one is short but tells us immediately (under "Event Origins") where the command associated with this event originated.

It should be noted that some of the parameter structures within a PCF message can end up being much longer than those that I've included here, but the same rules of interrogating them apply.

Use of programmed commands can greatly facilitate administration and configuration of your WebSphere MQ network. For more on the topic refer to the MQ product documentation for your version.

title image (modified) credit: (cc) Some rights reserved by Nemo