Writing and compiling publish exits

You can configure a publish exit at the queue manager to change the contents of a published message before it is received by subscribers. You can also change the message header, or not deliver the message to a subscription.

Note: Publish exits are not supported on z/OS®.
You can use the publish exit to inspect and alter messages delivered to subscribers:
  • Examine the contents of a message published to each subscriber
  • Modify the contents of a message published to each subscriber
  • Alter the queue to which a message is put
  • Stop the delivery of a message to a subscriber

Writing a publish exit

Use the steps in Writing exits and installable services on UNIX, Linux and Windows, to help you write and compile your exit.

The provider of the publish exit defines what the exit does. The exit, however, must conform to the rules defined in MQPSXP.

IBM MQ does not provide an implementation of the MQ_PUBLISH_EXIT entry point. It does provide a C language typedef declaration. Use the typedef to declare the parameters to a user-written exit correctly. The following example illustrates how to use the typedef declaration: 

#include "cmqec.h"

MQ_PUBLISH_EXIT MyPublishExit;

void MQENTRY MyPublishExit( PMQPSXP pExitParms,
                            PMQPBC  pPubContext,
                            PMQSBC  pSubContext )
{
/* C language statements to perform the function of the exit */
}
The publish exit runs within the queue manager process, as a result of the following operations:
  • A Publish operation where a message is delivered to one or more subscribers
  • A Subscribe operation where one or more retained messages are delivered
  • A Subscription Request operation where one or more retained messages are delivered

If the publish exit is called for a connection, the first time that it is called an ExitReason code of MQXR_INIT is set. Before the connection disconnects after using a publish exit, the exit is called with an ExitReason code of MQXR_TERM.

If the publish exit is configured, but cannot be loaded when the queue manager is started, publish/subscribe message operations are inhibited for the queue manager. You must fix the problem or restart the queue manager before publish/subscribe messaging is re-enabled.

Each IBM MQ connection that requires the publish exit might fail to load or initialize the exit. If the exit fails to load or initialize, publish/subscribe operations that require the publish exit are disabled for that connection. The operations fail with the IBM MQ reason code MQRC_PUBLISH_EXIT_ERROR.

The context in which the publish exit is called is the connection by an application to the queue manager. A user data area is maintained by queue manager for each connection that is performing publish operations. The exit can retain information in the user data area for each connection.

A publish exit can use some MQI calls. It can only use those MQI calls that manipulate message properties. The calls are:
  • MQBUFMH
  • MQCRTMH
  • MQDLTMH
  • MQDLTMP
  • MQMHBUF
  • MQINQMP
  • MQSETMP

If the publish exit changes the destination queue manager or queue name, no new authority check is carried out.

Compiling a publish exit

The publish exit is a dynamically loaded library; it can be thought of as a channel-exit. For information about compiling exits, see Writing exits and installable services on UNIX, Linux and Windows.

Sample publish exit

The sample exit program is called amqspse0.c. It writes a different message to a log file depending on whether the exit was called for initialize, publish, or terminate operations. It also demonstrates the use of the exit user area field to allocate and free storage appropriately.