Home

 

Writing and compiling channel-exit programs

 

Channel exits must be named in the channel definition. We can do this when you first define the channels, or we can add the information later using, for example, the MQSC command ALTER CHANNEL. We can also give the channel exit names in the MQCD channel data structure. The format of the exit name depends on your WebSphere MQ platform; see MQCD – Channel definition or the WebSphere MQ Script (MQSC) Command Reference book for information.

If the channel definition does not contain a user-exit program name, the user exit is not called.

The channel auto-definition exit is the property of the queue manager, not the individual channel. In order for this exit to be called, it must be named in the queue manager definition. To alter a queue manager definition, use the MQSC command ALTER QMGR.

User exits and channel-exit programs are able to make use of all MQI calls, except as noted in the sections that follow. To get the connection handle, an MQCONN must be issued, even though a warning, MQRC_ALREADY_CONNECTED, is returned because the channel itself is connected to the queue manager.

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 i5/OS) and you do not specify a queue manager name on the MQCONN call, the exit will try to connect to the default queue manager on your system. If the exit was linked with MQM.LIB (or QMQM/LIBMQM on i5/OS) 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 will fail whether you specify a queue manager name or not.

You are recommended to avoid issuing the following MQI calls in channel-exit programs:

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 syncpoint are committed or backed out by the channel at the end of the batch.

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

Channel-exit programs should not modify the Channel data structure (MQCD). They can actually change the BatchSize parameter and a security exit can set the MCAUserIdentifier parameter, but ChannelType and ChannelName must not be changed.

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

If you use multiple channel exit libraries simultaneously, problems can arise on some UNIX 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 will be unaffected. Other functions should be given local visibility so that they will not be used by functions outside their own exit library. Consult your linker's documentation 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:

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

Before using a channel-exit program for the first time on WebSphere MQ on UNIX systems, iSeries, or Windows, you should relink it with threaded libraries to make it thread-safe.

 

Parent topic:

Channel-exit programs


ic17640_


 

Home