The API exit

 

The information in this section does not apply to WebSphere MQ for z/OS.

An API exit is a program module that monitors or modifies the function of MQI calls. An API exit comprises multiple API exit functions, each with its own entry point in the module.

There are two categories of exit function:

An exit function that is associated with an MQI call

There are two exit functions in this category for each MQI call and an additional one for an MQGET call with the MQGMO_CONVERT option. The MQCONN and MQCONNX calls share the same exit functions.

For each MQI call, one of the two exit functions is invoked before the queue manager starts to process the call and the other is invoked after the queue manager has completed processing the call. The exit function for an MQGET call with the MQGMO_CONVERT option is invoked during the MQGET call, after the message has been retrieved from the queue by the queue manager but before any data conversion takes place. This allows, for example, a message to be decrypted before data conversion.

An exit function can inspect and modify any of the parameters on an MQI call. On an MQPUT call, for example, an exit function that is invoked before the processing of the call has started can:

• Inspect and modify the contents of the application data in the message being put

• Change the length of the application data in the message

• Modify the contents of the fields in the message descriptor structure, MQMD

• Modify the contents of the fields in the put message options structure, MQPMO

An exit function that is invoked before the processing of an MQI call has started can suppress the call completely. The exit function for an MQGET call with the MQGMO_CONVERT option can suppress data conversion of the message being retrieved.

Initialization and termination exit functions

There are two exit functions in this category, the initialization exit function and the termination exit function.

The initialization exit function is invoked by the queue manager when an application connects to the queue manager. Its primary purpose is to register exit functions and their respective entry points with the queue manager and perform any initialization processing. You do not have to register all the exit functions, only those that are required for this connection. When the application disconnects from the queue manager, the registrations are removed automatically.

The initialization exit function can also be used to acquire any storage required by the exit and examine the values of any environment variables.

The termination exit function is invoked by the queue manager when an application disconnects from the queue manager. Its purpose is to release any storage used by the exit and perform any required cleanup operations.

An API exit can issue calls to the MQI but, if it does, the API exit is not invoked recursively a second time. The following exit functions, however, are not able to issue MQI calls because the correct environment is not present at the time the exit functions are invoked:

• The initialization exit function

• The exit function for an MQCONN and MQCONNX call that is invoked before the queue manager starts to process the call

• The exit function for the MQDISC call that is invoked after the queue manager has completed processing the call

• The termination exit function

An API exit can also use other APIs that might be available; for example, it can issue calls to DB2.

An API exit can be used with a WebSphere MQ client application, but it is important to note that the exit is invoked at the server end of an MQI channel. See the discussion in What application level security cannot do.

An API exit is written using the C programming language.

To enable an API exit, configure it. On i5/OS, Windows, and UNIX systems, you do this by editing the WebSphere MQ configuration file, mqs.ini, and the queue manager configuration file, qm.ini, for each queue manager.

You configure an API exit by providing the following information:

• The descriptive name of the API exit.

• The name of the module and its location; for example, the full path name.

• The name of the entry point for the initialization exit function.

• The sequence in which the API exit is invoked relative to other API exits. We can configure more than one API exit for a queue manager.

• Optionally, any data to be passed to the API exit.

For more information about how to configure an API exit, see:

• WebSphere MQ for iSeries™ System Administration Guide

• WebSphere MQ System Administration Guide, for UNIX and Windows systems

For information about how to write an API exit, see the WebSphere MQ Application Programming Guide.

 

Parent topic:

Providing your own application level security

sy11460_