Channel message exit programs

You 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. 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 the processing cycle of the MCA:
  • 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.) 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 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.

Message exits can return the following responses:
  • 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. On UNIX systems, if you provide a message exit for any reason the automatic conversion of user IDs to lowercase characters does not operate. See Security of objects on UNIX and Linux® 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 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, it is possible to issue sync point MQI calls from a channel message exit program.