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.

This data is processed by the receive exit program and then removed from the buffer. For example, you might want to encrypt the data and add a security key for decryption.


How you reserve space and use it

When the send exit program is called for initialization, set the ExitSpace field of MQXCP to the number of bytes to be reserved. See MQCXP for details. ExitSpace can be set only during initialization, that is when ExitReason has the value MQXR_INIT. When the send exit is invoked immediately before transmission, with ExitReason set to MQXR_XMIT, ExitSpace bytes are reserved in the transmission buffer. ExitSpace is not supported on z/OS .

The send exit need not use all the reserved space. It can use less than ExitSpace bytes or, if the transmission buffer is not full, the exit can use more than the amount reserved. When setting the value of ExitSpace, we must leave at least 1 KB for message data in the transmission buffer. Channel performance can be affected if reserved space is used for large amounts of data.

The transmission buffer is normally 32Kb bytes long. However, if the channel uses TLS then the transmission buffer size is reduced to 15,352 bytes in order fit within the maximum record length defined by RFC 6101 and the related family of TLS standards. A further 1024 bytes are reserved for use by IBM MQ, so the maximum transmission buffer space usable by send exits is 14,328 bytes.


What happens at the receiving end of the channel

Channel receive exit programs must be set up to be compatible with the corresponding send exits. Receive exits must know the number of bytes in the reserved space and must remove the data in that space.


Multiple send exits

We can specify a list of send and receive exit programs to be run in succession. IBM MQ maintains a total for the space reserved by all the send exits. This total space must leave at least 1 KB for message data in the transmission buffer.

The following example shows how space is allocated for three send exits, called in succession:
  1. When called for initialization:

    • Send exit A reserves 1 KB.
    • Send exit B reserves 2 KB.
    • Send exit C reserves 3 KB.

  2. The maximum transmission size is 32 KB and the user data is 5 KB long.
  3. Exit A is called with 5 KB of data; up to 27 KB are available, because 5 KB is reserved for exits B and C. Exit A adds 1 KB, the amount it reserved.
  4. Exit B is called with 6 KB of data; up to 29 KB are available, because 3 KB is reserved for exit C. Exit B adds 1 KB, less than the 2 KB it reserved.
  5. Exit C is called with 7 KB of data; up to 32 KB are available. Exit C adds 10K, more than the 3 KB it reserved. This amount is valid, because the total amount of data, 17 KB, is less than the 32 KB maximum.

The maximum transmission buffer size for a channel using TLS is 15,352 bytes, not 32Kb. This is because the underlying secure socket transmission segments are limited to 16Kb and some of the space is required for TLS record overheads. A further 1024 bytes are reserved for use by IBM MQ, so the maximum transmission buffer space usable by send exits is 14,328 bytes.

Parent topic: Channel send and receive exit programs