Channel message exit programs

We can use the channel message exit to perform tasks such as encryption on the link, validation or substitution of incoming user IDs, message data conversion, journaling, and reference message handling. We can specify a list of message exit programs to be run in succession.

• At MCA initiation and termination
• Immediately after a sending MCA has issued an MQGET call
• Before the receiving MCA issues an MQPUT call

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 MQXQH - Transmission-queue header.

If we use reference messages (that is, messages that contain only a header that 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 message is a reference message, extracts the object, and passes the header on to the destination queue. See Reference messages and Running the Reference Message samples for more information about reference messages and some sample message exits that handle them.

• Send the message (GET exit). The message might have been changed by the exit. (This returns MQXCC_OK.)
• Put the message on the queue (PUT exit). The message might have been changed by the exit. (This returns MQXCC_OK.)
• Do not process the message. The message is placed on the dead-letter queue (undelivered message queue) by the MCA.
• Close the channel.
• Bad return code, which causes the MCA to abnormally end.

Note:

1. Message exits are called once for every complete message transferred, even when the message is split into parts.
2. If you provide a message exit on UNIX or Linux, the automatic conversion of user IDs to lowercase characters (described here) does not operate.
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. So any calls made under sync point 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 are only committed to the queue when the batch containing the original message is committed.

   Therefore we can issue sync point 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 topic describes the algorithms used to perform the conversions.

Parent topic: Writing channel-exit programs