View Only

IBM MQ Little Gem #53: PROPCTL

By Morag Hughson posted Tue July 20, 2021 07:24 AM

This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

It seems that there are quite regularly questions on the MQ Forums where users are asking some flavour of the following:-

  • Why has MQ changed my message format to MQHRF2?
  • Why has MQ turned my message into XML?
  • What are all these extra bytes on the front of my message?
  • My message starts with the letters RFH - I didn't put them there
  • My non-JMS application can't read my message correctly - why?

These are all variations on the same theme where the problem is that some message properties have been added to the message when it was put, but the getting application didn't expect them, doesn't want them, and can't handle them. This situation most often occurs when the putting application is written using the JMS interface, but it is possible for it to happen with other languages and interfaces.

In the days prior to IBM WebSphere MQ V7, you could only control this at the putting application side of things. You did this by ensuring your JMS application indicated that the intended recipient of the message was non-JMS. With this configuration (shown at the end of this post), the additional properties were not even added to the message, and so non-JMS applications did not suffer any issues.

There is a downside to this as a solution however. Since none of the properties were added to the message at put time, if the recipient was a JMS application that could handle these properties, and perhaps additionally, wanted and expected to receive these properties, now they weren't there.

If you are lucky enough not to have a mixed set of applications, then configuration at the putting application may well suffice.

Property Control

IBM WebSphere MQ V7 introduced the queue attribute that this blog post is going to cover. It's called PROPCTL and it allows control of property information to be done at get time instead of at put time. This means that the putting application is free to add properties into the message, and any getting applications that can't cope with them won't see them, and yet any getting applications that can cope with them do get to see them.


Making a change to your queue with the above command means that any application that doesn't request message properties explicitly, will receive the message with the properties stripped off. However, if an application requests to be given the properties it is unaffected by this attribute. JMS applications continue to get the properties thanks to the way the underlying IBM MQ JMS classes are written, and so are unaffected by this queue attribute.

If you want to have your own application be able to retrieve message properties when a queue it is getting from is set to PROPCTL(NONE) here's a little snippet of code to show you how.

gmo.Version   = MQGMO_VERSION_4;
gmo.MsgHandle = hMsg;

Alternatively, if you have been parsing an MQRFH2 header in your application, and want to continue to do that, you can use the PROPCTL(FORCE) value on the queue definition, or do what is illustrated in the following code snippet. This code snippet will also over-ride a queue that is defined with PROPCTL(NONE).


And finally, if you still want to make the decision about properties at put time rather than deferring the decision until get time, you need to configure your JMS application to use the name/value pair shown below.

Queue queue = Session.createQueue("queue:///WORKQUEUE?targetClient=1");

Now if you see some unwelcome additions to your message data, you'll know what to do about it.

Morag Hughson is an MQ expert. She spent 18 years in the MQ Devt organisation before taking on her current job writing MQ Technical education courses with MQGem. She also blogs for MQGem. You can connect with her here on IMWUC or on Twitter and LinkedIn.