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.
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, we 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:
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.
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.
Set 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.