Configure API exits

An API exit is a code module, a .dll file, that you provide yourself and that runs immediately before or after MQI calls.

About this task

When IBM MQ receives a call from a program to one of its API entry points, IBM MQ calls your API exit. The API exit runs either before or after the MQI is run, according to how you configured the exit.

We can configure none, one, or many exits to be called, and we can configure the sequence in which multiple exits are called. On Windows and Linux (x86 and x86-64 platforms), we can configure the API exits using IBM MQ Explorer. The configuration details are stored in .ini files.

There are three types of API exit definition:

Common (ApiExitCommon)

One set of definitions per computer. When the queue manager starts, the API exits that are defined, if any, are read and applied to the queue manager. Configure common API exits in the IBM MQ properties dialog. Common exits are displayed in the Local API Exits table in the properties dialog of each local queue manager.

Template (ApiExitTemplate)

One set of definitions per computer. When a queue manager is created, the API exits defined here, if any, are copied into the newly created queue manager as local exits. Configure template API exits in the IBM MQ properties dialog.

Local (ApiExitLocal)

One set of definitions per queue manager. When the queue manager starts, any API exits that are defined override the common exits if their Name attributes are the same, and if the override has been specified. When a common API exit is overridden, none of the fields in the common definition are saved, even if the optional Data attribute has an assigned value. Configure local API exits in the queue manager's properties dialog.

Configure an API exit in IBM MQ Explorer

About this task

To configure an API exit:

Procedure

1. Open the relevant properties dialog:
2. On the Exits page, click Add.... The Add API Exit dialog opens.
3. Type the required information into the fields of the Add API Exit dialog.
4. Click OK to create the exit and close the Add API Exit dialog.

Results

The properties of the new API exit are displayed in the table on the Exits page.

Overriding a common API exit with a local API exit

About this task

When a local API exit is defined on a queue manager with the same name as a common exit, the common exit is overridden. That is, the common exit is not called; instead, the overriding local exit is called. To prevent accidental overriding, the user interface makes you take deliberate actions to configure an override; for example, we cannot add a new exit with the same name as an existing exit, and we cannot change the name of an exit to be the same as an existing exit.

However, you might want to add a local API exit to a queue manager so that the common API exit is not used and the local API exit is used instead. In this case, you need to override the common API exit with the local API exit.

To override a common API exit with a local API exit:

Procedure

1. Open the Exits page of the queue manager properties dialog.
2. Click the common exit to override in the Local API Exits table.
3. Click Override. The Edit API Exit dialog opens with the name of the common API exit displayed.
4. Type the details of the local API exit in the Edit API Exit dialog, and click OK to save the changes.

Results

The local exit now overrides the common exit that has the same name.

API exit attributes

About this task

When you configure API exits in the IBM MQ and queue manager properties dialogs, the attribute values are added to the ApiExitCommon, ApiExitTemplate, and ApiExitLocal stanzas in the configuration files or the Windows registry.

Attribute	Meaning	Stanza key
Name	Specifies the descriptive name of the API exit which is passed to the API exit in the ExitInfoName field of the MQAXP structure. This name must be unique and is limited to a length of 48 characters, and must contain only those characters that are valid for the name of IBM MQ objects, such as queue names.	Name
Type	Specifies the type of exit: common, template, local, or override.	(Not a separate stanza key.)
Sequence	This attribute is an unsigned numeric value that defines the sequence in which this API exit is called in comparison with other API exits. An API exit with a low sequence number is called before another API exit with a higher sequence number. The order in which different API exits with the same sequence number are called is undefined. It is perfectly valid for there to be gaps in the sequence numbers of the API exits defined for a queue manager.	Sequence
Module	Specifies the module that contains the code for the API exit. If this field contains the full path name of the module it is used as is. If this field contains just the module name, the module is located using the same method as channel exits; that is, using the value in the Exit default path field on the Exits page of the queue manager properties dialog.	Module
Function	Specifies the name of the function entry-point into the module that contains the code for the API exit. This entry-point is the MQ_INIT_EXIT function. The length of this field is limited to MQ_EXIT_NAME_LENGTH.	Function
Data	If this attribute is specified, leading and trailing blanks are removed, the remaining string is truncated to 32 characters, and the result is passed to the exit in the ExitData field of the MQAXP structure. If this attribute is not specified, the default value of 32 blanks is passed to the exit in the ExitData field of the MQAXP structure.	Data