Channel send and receive exit programs

We can use the send and receive exits to perform tasks such as data compression and decompression. We can specify a list of send and receive exit programs to be run in succession.

Channel send and receive exit programs are called at the following places in the processing cycle of an MCA:

• The send and receive exit programs are called for initialization at MCA initiation and for termination at MCA termination.
• The send exit program is invoked at one or other end of the channel, depending on the end at which a transmission for one message transfer is sent, immediately before a transmission is sent over the link. Note 4 explains why exits are available in both directions even though message channels send messages in one direction only.
• The receive exit program is invoked at one or other end of the channel, depending on the end at which a transmission for one message transfer is received, immediately after a transmission has been taken from the link. Note 4 explains why exits are available in both directions even though message channels send messages in one direction only.

There might be many transmissions for one message transfer, and there could be many iterations of the send and receive exit programs before a message reaches the message exit at the receiving end.

The channel send and receive exit programs are passed an agent buffer containing the transmission data as sent or received from the communications link. For send exit programs, the first 8 bytes of the buffer are reserved for use by the MCA, and must not be changed. If the program returns a different buffer, then these first 8 bytes must exist in the new buffer. The format of data presented to the exit programs is not defined.

A good response code must be returned by send and receive exit programs. Any other response causes an MCA abnormal end (abend).

Note: Do not issue an MQGET, MQPUT, or MQPUT1 call within sync point from a send or receive exit. Note:

1. Send and receive exits typically work in pairs. For example a send exit might compress the data and a receive exit decompress it, or a send exit might encrypt the data and a receive exit decrypt it. When you define the appropriate channels, make sure that compatible exit programs are named for both ends of the channel.
2. If compression is turned on for the channel, the exits are passed compressed data.
3. Channel send and receive exits might be called for message segments other than for application data, for example, status messages. They are not called during the startup dialog, nor the security check phase.
4. Although message channels send messages in one direction only, channel-control data, such as heart beats and end of batch processing, flows in both directions, and these exits are available in both directions, also. However, some of the initial channel startup data flows are exempt from processing by any of the exits.
5. There are circumstances in which send and receive exits could be invoked out of sequence; for example, if we are running a series of exit programs or if we are also running security exits. Then, when the receive exit is first called upon to process data, it might receive data that has not passed through the corresponding send exit. If the receive exit just performed the operation, for example decompression, without first checking that it was required, the results would be unexpected. We need to code your send and receive exits in such a way that the receive exit can check that the data it is receiving has been processed by the corresponding send exit. The recommended way to do so is to code your exit programs so that:
   • The send exit sets the value of the ninth byte of data to 0 and shifts all the data along 1 byte, before performing the operation. (The first 8 bytes are reserved for use by the MCA.)
   • If the receive exit receives data that has a 0 in byte 9, it knows that the data has come from the send exit. It removes the 0, performs the complementary operation, and shifts the resulting data back by 1 byte.
   • If the receive exit receives data that has something other than 0 in byte 9, it assumes that the send exit has not run, and sends the data back to the caller unchanged.

   When using security exits, if the channel is ended by the security exit it is possible that a send exit might be called without the corresponding receive exit. One way to prevent this problem is to code the security exit to set a flag, in MQCD.SecurityUserData or MQCD.SendUserData, for example, when the exit decides to end the channel. Then the send exit needs to check this field, and process the data only if the flag is not set. This check prevents the send exit from unnecessarily altering the data, and thus prevents any conversion errors that could occur if the security exit received altered data.

• Channel send exit programs - reserving space
  We can use send and receive exits to transform the data before transmission. Channel send exit programs can add their own data about the transformation by reserving space in the transmission buffer.

Parent topic: Writing channel-exit programs