PROPCTL queue options

Use this option so that different applications reading a message from the same queue can process the message in different ways.

• An application, migrated unchanged from Version 6.0, can continue to read the MQRFH2 directly. Properties are directly accessible in the MQRFH2 header.

  You must modify the application to handle any new properties, and new property attributes. It is possible that the application might be affected by changes in the layout and number of MQRFH2 headers. Some folder attributes might be removed, or that WebSphere® MQ reports an error in the layout of the MQRFH2 header that it ignored in Version 6.0.

• A new or changed application can use the message property MQI to query message properties, and read name/value pairs in MQRFH2 header directly.

ALL only has this affect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

COMPAT is the default option. If GMO_PROPERTIES_* is not set, as in an unmodified Version 6.0 application, COMPAT is assumed. By defaulting to the COMPAT option, a Version 6.0 application that did not explicitly create an MQRFH2, works without change on Version 7.5.

Use this option if you have written an Version 6.0 MQI application to read JMS messages.

• The JMS properties, which are stored in an MQRFH2 header, are returned to the application in an MQRFH2 header in folders with names starting with mcd., jms., usr., or mqext..
• If the message has JMS folders, and if a Version 7.5 application adds new property folders to the message, these properties are also returned in the MQRFH2. Consequently, you must modify the application to handle any new properties, and new property attributes. It is possible that an unmodified application might be affected by changes in the layout and number of MQRFH2 headers. It might find some folder attributes are removed, or that WebSphere MQ finds errors in the layout of the MQRFH2 header that it ignored in Version 6.0.
  Note: In this scenario, the behavior of the application is the same whether it is connected to a Version 6.0 or Version 7.5 queue manager. If the channel PROPCTL attribute is set to COMPAT or ALL any new message properties are sent in the message to the Version 6.0 queue manager.
• If the message is not a JMS message, but contains other properties, those properties are not returned to the application in an MQRFH2 header.¹
• The option also enables Version 6.0 applications that explicitly create an MQRFH2 to work correctly, in many cases. For example, An MQI program that creates an MQRFH2 containing JMS message properties continues to work correctly. If a message is created without JMS message properties, but with some other MQRFH2 folders, the folders are returned to the application. Only if the folders are message property folders are those specific folders are removed from the MQRFH2. Message property folders are identified by having the new folder attribute content='properties', or are folders with names listed in Defined property folder name or Ungrouped property folder name.
• If the application calls MQCRTMH to create a message handle, it must query the message properties using MQINQMP. Message properties are removed from the MQRFH2 headers. Name/value pairs that are not message properties remain in the MQRFH2.
• If the application calls MQCRTMH to create a message handle, it can query all message properties, regardless of whether the message has JMS folders.
• If the application does not create a message handle, all the message properties and name/value pairs remain in the MQRFH2.

If a message contains new user property folders, you can infer that the message was created by a new or changed Version 7.5 application. If the receiving application is to process these new properties directly in an MQRFH2, you must modify the application to use the ALL option. With the default COMPAT option set, an unmodified application continues to process the rest of the MQRFH2, without the Version 7.5 properties.

The intent of the PROPCTL interface is to support old applications reading MQRFH2 folders, and new and changed applications using the message property interface. Aim for new applications to use the message property interface for all user message properties, and to avoid reading and writing MQRFH2 headers directly.

COMPAT only has this affect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

The FORCE option places all messages properties into MQRFH2 headers. All message properties and name/value pairs in the MQRFH2 headers remain in the message. Message properties are not removed from the MQRFH2, and made available through a message handle. The effect of choosing the FORCE option is to enable a newly migrated application to read message properties from MQRFH2 headers.

Suppose you have modified an application to process Version 7.5 message properties, but have also retained its ability to work directly with MQRFH2 headers, as before. You can decide when to switch the application over to using message properties by initially setting the PROPCTL queue attribute to FORCE. Set the PROPCTL queue attribute to another value when you are ready to start using message properties. If the new function in the application does not behave as you expected, set the PROPCTL option back to FORCE.

FORCE only has this affect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

NONE only has this affect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

Use this option to receive an MQRFH2 in the same format as it was sent. If the sending application, or the queue manager, creates additional message properties, these are returned in the message handle.

This option has to be set on both the sending and receiving queues, and any intervening transmission queues. It overrides any other PROPCTL options set on queue definitions in the queue name resolution path.

Use this option only in exceptional circumstances. For example, if you are migrating applications from Version 6.0 to Version 7.5 the option is valuable because it preserves Version 6.0 behavior. The option is likely to have an impact on message throughput. It is also more difficult to administer; you need to ensure the option is set on the sender, receiver, and intervening transmission queues.

V6COMPAT only has this affect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.