Channel message exit programs

You can use the channel message exit for the following:

On WebSphere MQ for iSeries, UNIX systems, z/OS(R), and Windows systems, and with WebSphere MQ clients, you can specify a list of message exit programs to be run in succession.

Channel message exit programs are called at the following places in an MCA's processing cycle:

The message exit is passed an agent buffer containing the transmission queue header, MQXQH, and the application message text as retrieved from the queue. (The format of MQXQH is given in the WebSphere MQ Application Programming Reference book.) If you use reference messages, that is messages that contain only a header which points to some other object that is to be sent, the message exit recognizes the header, MQRMH. It identifies the object, retrieves it in whatever way is appropriate appends it to the header, and passes it to the MCA for transmission to the receiving MCA. At the receiving MCA, another message exit recognizes that this is a reference message, extracts the object, and passes the header on to the destination queue. See the WebSphere MQ Application Programming Guide for more information about reference messages and some sample message exits that handle them.

Message exits can return the following responses:

Notes:
  1. Message exits are called just once for every complete message transferred, even when the message is split into parts.
  2. In UNIX systems, if you provide a message exit for any reason the automatic conversion of user IDs to lowercase characters does not operate. See User IDs on UNIX systems.
  3. An exit runs in the same thread as the MCA itself. It also runs inside the same unit of work (UOW) as the MCA because it uses the same connection handle. Therefore, any calls made under syncpoint are committed or backed out by the channel at the end of the batch. For example, one channel message exit program can send notification messages to another and these messages will only be committed to the queue when the batch containing the original message is committed.

    Therefore, it is possible to issue syncpoint MQI calls from a channel message exit program.

Message conversion outside the message exit

Before calling the message exit, the receiving MCA performs some conversions on the message. This section describes the algorithms used to perform the conversions.

Which headers are processed

A conversion routine runs in the receiver's MCA before the message exit is called. The conversion routine begins with the MQXQH header at the top of the message. The conversion routine then processes through the chained headers that follow the MQXQH, performing conversion where necessary. The chained headers can extend beyond the offset contained in the HeaderLength parameter of the MQCXP data that is passed to the receiver's message exit. The following headers will be converted in-place:

The following headers will not be converted, but will be stepped over as the MCA continues to process the chained headers:

How the headers are processed

The Format parameter of each MQ header is read by the MCA. The Format parameter is 8 bytes within the header, which are 8 single-byte characters containing a name.

The MCA then interprets the data following each header as being of the named type. If the Format is the name of a header type eligible for MQ data conversion, it will be converted. If it is another name indicating non-MQ data (for example MQFMT_NONE or MQFMT_STRING) then the MCA stops processing the headers at this point.

What is the MQCXP HeaderLength?

The HeaderLength parameter in the MQCXP data supplied to a message exit is the total length of the MQXQH (which includes the MQMD), MQMDE and MQDH headers at the start of the message. These headers are chained using the 'Format' names and lengths as per the general discussion above.

MQWIH

As noted above, the chained headers can extend beyond the HeaderLength into the user data area. The MQWIH header, if it is present, is one of those that will appear beyond the HeaderLength.

If there is an MQWIH header in the chained headers, it will be converted in-place before the receiver's message exit is called.