Writing and compiling API exits

API exits let you write code that changes the behavior of IBM® MQ API calls, such as MQPUT and MQGET, and then insert that code immediately before or immediately after those calls.

Note: Not supported on IBM MQ for z/OS®.

Why use API exits?

Each of your applications has a specific job to do, and its code should do that task as efficiently as possible. At a higher level, you might want to apply standards or business processes to a particular queue manager for all the applications that use that queue manager. It is more efficient to do this above the level of individual applications, and thus without having to change the code of each application affected.

Here are a few suggestions of areas in which API exits might be useful:
  • For security, you can provide authentication, checking that applications are authorized to access a queue or queue manager. You can also police applications' use of the API, authenticating the individual API calls, or even the parameters they use.
  • For flexibility, you can respond to rapid changes in your business environment without changing the applications that rely on the data in that environment. You could, for example, have API exits that respond to changes in interest rates, currency exchange rates, or the price of components in a manufacturing environment.
  • For monitoring use of a queue or queue manager, you can trace the flow of applications and messages, log errors in the API calls, set up audit trails for accounting purposes, or collect usage statistics for planning purposes.

What happens when an API exit runs?

Once you have written an exit program and identified it to IBM MQ, the queue manager automatically invokes your exit code at the registered points.

The API exit routines to run are identified in stanzas on IBM i , Windows, UNIX and Linux® systems. This topic covers the stanzas in the configuration files mqs.ini and qm.ini.

The definition of the routines can occur in three places:
  1. ApiExitCommon, in the mqs.ini file, identifies routines, for the whole of IBM MQ, applied when queue managers start. These can be overridden by routines defined for individual queue managers (see item3in this list).
  2. ApiExitTemplate, in the mqs.ini file, identifies routines, for the whole of IBM MQ, copied to the ApiExitLocal set (see item 3 in this list) when a new queue manager is created.
  3. ApiExitLocal, in the qm.ini file, identifies routines that apply to a particular queue manager.

When a new queue manager is created, the ApiExitTemplate definitions in mqs.ini are copied to the ApiExitLocal definitions in qm.ini for the new queue manager. When a queue manager is started, both the ApiExitCommon and ApiExitLocal definitions are used. The ApiExitLocal definitions replace the ApiExitCommon definitions if both identify a routine of the same name. The Sequence attribute, described in Configuring API exits determines the order in which the routines defined in the stanzas run.

Using API exits across multiple installations of IBM MQ

Ensure that the API exits written for the earlier version of IBM MQ are used to work with all versions because the changes made to exits in Version 7.1 might not work with an earlier version. For more information about the changes made to exits, see Writing exits and installable services on UNIX, Linux and Windows.

The samples provided for API exits amqsaem and amqsaxe reflect the changes required while writing exits. The client application must ensure that the correct IBM MQ libraries that correspond to the installation of the queue manager with which the application is associated are linked to it prior to the launch of the application.