Introducing API exits

 

Not supported in WebSphere MQ for z/OS.

API exits let you write code that changes the behavior of WebSphere MQ API calls, such as MQPUT and MQGET, and then insert that code immediately before or immediately after those calls. Once you have written an exit program and identified it to WebSphere MQ, the queue manager automatically invokes your exit code at the registered points.

This chapter tells you how to write API exits, and how to set up WebSphere MQ to enable them. This section explains how you might use them and introduces the tasks involved. This chapter also contains the following major sections:

 

Why use API exits

There are many reasons why you might want to insert code that modifies the behavior of applications at the level of the queue manager. 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 use of the API by applications by 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.

 

How you use API exits

This section gives a brief overview of the tasks involved in setting up API exits. Each subsection here is supported by detailed information in the chapters in the rest of this information.

 

How to configure WebSphere MQ for API exits

You configure WebSphere MQ to enable API exits either by changing the Windows registry, or by editing the WebSphere MQ configuration files, mqs.ini and qm.ini, and adding new stanzas that:

  • Name the API exit

  • Identify the module and entry point of the API exit code to run

  • Optionally pass data with the exit

  • Identify the sequence of each exit in relation to other exits

For detailed information on this configuration, see the WebSphere MQ System Administration Guide. For a description of how API exits run, see What happens when an API exit runs?.

 

How to write an API exit

You write exits using the C programming language. To help you do so, we provide the source of a sample exit, amqsaxe0.c, that generates trace entries to a file you specify. Use this as your starting point when writing exits.

Exits are available for every API call. Within API exits, the calls take the general form: 

MQ_call_EXIT (parameters, context, ApiCallParameters)

where call is the MQI call name without the "MQ" prefix; for example, PUT, GET, and so on. The parameters control the function of the exit, context describes the context in which the ApiExit was called, and ApiCallParameters represent the parameters to the MQI call.

For more information about using the sample exit we supply, see The API exit sample program. For reference information on the API exit calls, external control blocks, and associated topics, see Reference information.

 

What happens when an API exit runs?

The API exit routines to run are specified in stanzas in .ini files or in the Windows registry. There are three ways to specify an exit routine:

  1. ApiExitCommon, in the mqs.ini file, identifies routines, for the whole of WebSphere MQ, applied when queue managers start up. These can be overridden by routines defined for individual queue managers (see item 3 in this list).

  2. ApiExitTemplate, in the mqs.ini file, identifies routines, for the whole of WebSphere 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 applicable 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 the WebSphere MQ System Administration Guide determines the order in which the routines defined in the stanzas run.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.