BTM UUID Injection

The Message UUID payload contains a UUID from a WebSphere MQ message property that is injected when a message is put. This message property is removed prior to the application seeing the message when a get or callback receives a message. In addition to the aliasing methods described earlier where the get is associated with a put within the application, this method associates a put with a get across applications. In some environments you can actually use this payload value as a transaction identifier without enabling aliasing.

Internally and when sending messages across channels, WebSphere MQ transfers message properties such as the injected UUID in an RFH2 header. Channels do not manipulate message properties and simply pass them through. To use the UUID as an alias or transaction identifier of activities representing the channel sender or channel receiver you must define a message format to access the field from the RFH2.

For applications, the Message UUID technology data payload would be chosen for a transaction ID.

For channels, the RFH2 message format and RFH2 UUID field would be chosen. In this example, the message format name is UUID.

The preference EnableUUIDInjection must be present with a value of 1 to enable injection of the message property. This is done by setting extension preferences for the "WebSphere MQ BTM Ext" extension. Refer to Managing the Agent and Extension preferences using agentpref for information about setting preferences.

When using the UUID Injection feature of the BTM WebSphere MQ Exit the following maintenance levels are required for WebSphere MQ. Earlier maintenance levels contain a message property defect that has been addressed in the levels listed below.

When using UUID injection you might note some differences in how message properties are handled on z/OS versus other WebSphere MQ platforms.

On z/OS, a UUID message property is injected only if the WebSphere MQ application puts a message with message properties and injection is enabled. An application puts message properties by using an appropriate version of the put message options (ex. version 3 or later), creates a message properties handle, saves that handle in the put message options and adds message properties using the MQSETMP API call. Or an equivalent set of steps for your language bindings.
On distributed platforms, the UUID is injected when injection is enabled regardless of whether the application puts a message with message properties or not.

On z/OS, the UUID message property is handled as an application message property. On distributed platforms the WebSphere MQ exit indicates that all message properties beginning with "bmc" belong to the exit. These message properties are never seen by the application.

On z/OS, the UUID message property is only removed prior to the application seeing it if the application gets message properties. An application gets message properties using an appropriate version of the get message options (ex. version 4 or later), uses appropriate get options and/or PROPCTL queue options to get message properties, creates a message properties handle, and saves that handle in the get message options prior to getting the message. Or an equivalent set of steps for your language bindings.

If the application is older or does not use the newer get options it might see the message properties in an RFH2. As such, some applications might not expect to see either the UUID message property in the RFH2 or the RFH2 itself. If the application cannot be updated to handle or ignore the UUID message property UUID injection should be disabled. In the latter case, the PROPCTL setting for the queue can be set to NONE.

On distributed platforms, this is also true if the message with the UUID message property is sent to another Queue Manager for which no exit is installed or is an earlier version of WebSphere MQ that does not support message properties. See the PROPCTL for channels when using older queue managers.

On distributed platforms, the UUID message property is always available for transaction tracking if injection is enabled. On z/OS the UUID message property is available only if the application gets message properties (as per removing the UUID message property, as described above).