Exit functions

This section provides some general information to help you when using the function calls and describes how to invoke the individual exit functions.

Use this information to understand the general rules for API exit routines, and setting up and cleaning up the exit execution environment.

General rules for API exit routines

The following general rules apply when invoking API exit routines:
  • In all cases, API exit functions are driven before validating API call parameters, and before any security checks (in the case of MQCONN, MQCONNX, or MQOPEN).
  • The values of fields entered into and output from an exit routine are:
    • On input to a before IBM® MQ API exit function, the value of a field can be set by the application program, or by a previous exit function invocation.
    • On output from a before IBM MQ API exit function, the value of a field can be left unchanged, or set to some other value by the exit function.
    • On input to an after IBM MQ API exit function, the value of a field can be the value set by the queue manager after processing the IBM MQ API call, or can be set to a value by a previous exit function invocation in the chain of exit functions.
    • On output from an after IBM MQ API call exit function, the value of a field can be left unchanged, or set to some other value by the exit function.
  • Exit functions must communicate with the queue manager by using the ExitResponse and ExitResponse2 fields.
  • The CompCode and Reason code fields communicate back to the application. The queue manager and exit functions can set the CompCode and Reason code fields.
  • The MQXEP call returns new reason codes to the exit functions that call MQXEP. However, exit functions can translate these new reason codes to any existing reasons codes that existing and new applications can understand.
  • Each exit function prototype has similar parameters to the API function with an extra level of indirection except for the CompCode and Reason.
  • API exits can issue MQI calls (except MQDISC), but these MQI calls do not themselves invoke API exits.

Note, that whether the application is on a server or a client, you cannot predict the sequencing of the API exit calls. An API exit BEFORE call might not be followed immediately by an AFTER call.

The BEFORE call can be followed by another BEFORE call. For example:
  • BEFORE MQCTL
  • BEFORE Callback
  • BEFORE MQPUT
  • AFTER MQPUT
  • AFTER Callback
  • AFTER MQCTL
or
  • BEFORE XAOPEN
  • BEFORE MQCONNX
  • AFTER MQCONNX
  • AFTER XAOPEN

On the client, there is an exit that can modify the behavior of the MQCONN or MQCONNX call, called the PreConnect exit. The PreConnect exit can modify any of the parameters on the MQCONN or MQCONNX call including the queue manager name. The client calls this exit first and then invokes the MQCONN or MQCONNX call. Note that only the initial MQCONN or MQCONNX call invokes the API exit; any subsequent reconnect calls have no effect.

The execution environment

In general, all errors from exit functions are communicated back to the exit handler using the ExitResponse and ExitResponse2 fields in MQAXP.

These errors in turn are converted into MQCC_* and MQRC_* values and communicated back to the application in the CompCode and Reason fields. However, any errors encountered in the exit handler logic are communicated back to the application as MQCC_* and MQRC_* values in the CompCode and Reason fields.

If an MQ_TERM_EXIT function returns an error:
  • The MQDISC call has already taken place
  • There is no other opportunity to drive the after MQ_TERM_EXIT exit function (and thus perform exit execution environment cleanup)
  • Exit execution environment cleanup is not performed
The exit cannot be unloaded as it might still be in use. Also, other registered exits further down in the exit chain for which the before exit was successful, will be driven in the reverse order.

Setting up the exit execution environment

While processing an explicit MQCONN or MQCONNX call, exit handling logic sets up the exit execution environment before invoking the exit initialization function (MQ_INIT_EXIT). Exit execution environment setup involves loading the exit, acquiring storage for, and initializing exit parameter structures. The exit configuration handle is also allocated.

If errors occur during this phase, the MQCONN or MQCONNX call fails with CompCode MQCC_FAILED and one of the following reason codes:
MQRC_API_EXIT_LOAD_ERROR
An attempt to load an API exit module has failed.
MQRC_API_EXIT_NOT_FOUND
An API exit function could not be found in the API exit module.
MQRC_STORAGE_NOT_AVAILABLE
An attempt to initialize the execution environment for an API exit function failed because insufficient storage was available.
MQRC_API_EXIT_INIT_ERROR
An error was encountered while initializing the execution environment for an API exit function.

Cleaning up the exit execution environment

While processing an explicit MQDISC call, or an implicit disconnect request as a result of an application ending, exit handling logic might need to clean up the exit execution environment after invoking the exit termination function (MQ_TERM_EXIT), if registered.

Cleaning up the exit execution environment involves releasing storage for exit parameter structures, possibly deleting any modules previously loaded into memory.

If errors occur during this phase, an explicit MQDISC call fails with CompCode MQCC_FAILED and the following reason code (errors are not highlighted on implicit disconnect requests):
MQRC_API_EXIT_TERM_ERROR
An error was encountered while closing the execution environment for an API exit function. The exit should not return any failure from the MQDISC before or after the MQ_TERM* API exit function calls.