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 your 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.

You should avoid altering the state of the transaction associated with the passed hConn in a channel exit; you 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, you 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 you 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.