Writing channel-exit programs

We can use the following information to help you write channel-exit programs.

User exits and channel-exit programs can use all MQI calls, except as noted in the sections that follow. For MQ V7 and later, the MQCXP structure version 7 and higher contains the connection handle hConn, which can be used instead of issuing MQCONN. For earlier versions, to obtain the connection handle, an MQCONN must be issued, even though an MQRC_ALREADY_CONNECTED warning is returned because the channel itself is connected to the queue manager.

Note that the channel exit must be threadsafe.

For exits on client-connection channels, the queue manager to which the exit tries to connect depends on how the exit was linked. If the exit was linked with MQM.LIB (or QMQM/LIBMQM on IBM i ) and we do not specify a queue manager name on the MQCONN call, the exit tries to connect to the default queue manager on the system. If the exit was linked with MQM.LIB (or QMQM/LIBMQM on IBM i ) and you specify the name of the queue manager that was passed to the exit through the QMgrName field of MQCD, the exit tries to connect to that queue manager. If the exit was linked with MQIC.LIB or any other library, the MQCONN call fails whether you specify a queue manager name or not.

We should avoid altering the state of the transaction associated with the passed hConn in a channel exit; we must not use the MQCMIT, MQBACK or MQDISC verbs with the channel hConn, and we cannot use the MQBEGIN verb specifying the channel hConn.

If MQCONNX is used specifying MQCNO_HANDLE_SHARE_BLOCK or MQCNO_HANDLE_SHARE_NO_BLOCK to create a new IBM MQ connection, then it is your responsibility to ensure that the connection is correctly managed and disconnects from the queue manager correctly. For example, a channel exit that creates a new connection to the queue manager on every invocation without disconnecting, results in connection handles building up and an increase in the number of agent threads.

An exit runs in the same thread as the MCA itself and uses the same connection handle. So, it runs inside the same UOW as the MCA and any calls made under sync point are committed or backed out by the channel at the end of the batch.

Therefore, a channel message exit could send notification messages that are only committed to that queue when the batch containing the original message is committed. So, it is possible to issue sync point MQI calls from a channel message exit.

A channel exit can change fields in the MQCD. However, these changes are not acted on, except in the circumstances listed. If a channel exit program changes a field in the MQCD data structure, the new value is ignored by the IBM MQ channel process. However, the new value remains in the MQCD and is passed to any remaining exits in an exit chain and to any conversation sharing the channel instance. For more information, see Change MQCD fields in a channel exit

Also, for programs written in C, non-reentrant C library function must not be used in a channel-exit program.

If we use multiple channel exit libraries simultaneously, problems can arise on some UNIX and Linux platforms if the code for two different exits contains identically named functions. When a channel exit is loaded, the dynamic loader resolves function names in the exit library to the addresses where the library is loaded. If two exit libraries define separate functions which happen to have identical names, this resolution process might incorrectly resolve the function names of one library to use the functions of another. If this problem occurs, specify to the linker that it must only export the required exit and MQStart functions, as these functions are unaffected. Other functions must be given local visibility so that they are not used by functions outside their own exit library. Consult the documentation for the linker for more information.

All exits are called with a channel exit parameter structure (MQCXP), a channel definition structure (MQCD), a prepared data buffer, data length parameter, and buffer length parameter. The buffer length must not be exceeded:

For message exits, we must allow for the largest message required to be sent across the channel, plus the length of the MQXQH structure.
For send and receive exits, the largest buffer we must allow for is as follows:
Note: The maximum usable length might be 2 bytes less than this length. Check the value returned in MaxSegmentLength for details. For more information about MaxSegmentLength, see MaxSegmentLength.
Note: Receive exits on sender channels and sender exits on receiver channels use 2 KB buffers for TCP.
For security exits, the distributed queuing facility allocates a buffer of 4000 bytes.

It is permissible for the exit to return an alternative buffer, together with the relevant parameters. See Channel-exit programs for messaging channels for call details.

Writing channel exit programs on z/OS
We can use the following information to help you write and compile channel-exit programs for z/OS .
Writing channel exit programs on IBM i
We can use the following information to help you write and compile channel-exit programs for IBM i.
Writing channel-exit programs on UNIX, Linux, and Windows
We can use the following information to help you write channel-exit programs for UNIX, Linux, and Windows systems.
Channel security exit programs
We can use security exit programs to verify that the partner at the other end of a channel is genuine. This is known as authentication. To specify that a channel must use a security exit, specify the exit name in the SCYEXIT field of the channel definition.
SSPI security exit
IBM MQ for Windows supplies a security exit that provides authentication for IBM MQ channels by using the Security Services Programming Interface (SSPI). The SSPI provides the integrated security facilities of Windows.
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 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.
Channel message retry exit program
The channel message-retry exit is called when an attempt to open the target queue is unsuccessful. We can use the exit to determine under which circumstances to retry, how many times to retry, and how frequently.
Channel auto-definition exit program
The channel auto-definition exit can be used when a request is received to start a receiver or server-connection channel but no definition for that channel exists (not for IBM MQ for z/OS ). It can also be called on all platforms for cluster-sender and cluster-receiver channels to allow definition modification for an instance of the channel.

Parent topic: Channel-exit programs for messaging channels