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 an earlier version, can continue to read the MQRFH2 directly. Properties are directly accessible in the MQRFH2 header.

  We 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 IBM MQ reports an error in the layout of the MQRFH2 header that it ignored in an earlier version.

• 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 the properties in the message are returned to the application.

• If the application calls MQCRTMH to create a message handle, it must query the message properties using MQINQMP. Name-value pairs that are not message properties remain in the MQRFH2, which is stripped of any message properties.
• If the application does not create a message handle, all the message properties and name-value pairs remain in the MQRFH2.

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 application from an earlier version, COMPAT is assumed. By defaulting to the COMPAT option, an earlier version application that did not explicitly create an MQRFH2, works without change on Version 9.2.

Use this option if you have written an earlier version application 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 9.2 application adds new property folders to the message, these properties are also returned in the MQRFH2. Consequently, 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 IBM MQ finds errors in the layout of the MQRFH2 header that it ignored in an earlier version. Note: In this scenario, the behavior of the application is the same whether it is connected to an earlier version or Version 9.2 queue manager. If the channel PROPCTL attribute is set to COMPAT or ALL any new message properties are sent in the message to the earlier version partner 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 earlier version 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, we can infer that the message was created by a new or changed Version 9.2 application. If the receiving application is to process these new properties directly in an MQRFH2, 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 9.2 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 9.2 message properties, but have also retained its ability to work directly with MQRFH2 headers, as before. We 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 we 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.

• If the application calls MQCRTMH to create a message handle, it must query the message properties using MQINQMP. Name-value pairs that are not message properties remain in the MQRFH2, which is stripped of any message properties.
• If the application does not create a message handle, all the message properties are removed from the MQRFH2. Name-value pairs in the MQRFH2 headers remain in the message.

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 we are migrating applications from an earlier version to Version 9.2 the option is valuable because it preserves the behavior of the earlier version. The option is likely to have an impact on message throughput. It is also more difficult to administer; we 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.