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, 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:

or

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.


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.

  • API exits on clients
    A client uses the PreConnect exit to modify the behavior of the MQCONN and MQCONNX calls and does not support API exit properties.
  • Backout - MQ_BACK_EXIT
    MQ_BACK_EXIT provides a backout exit function to perform before and after backout processing. Use function identifier MQXF_BACK with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after backout call exit functions.
  • Begin - MQ_BEGIN_EXIT
    MQ_BEGIN_EXIT provides a begin exit function to perform before and after MQBEGIN call processing. Use function identifier MQXF_BEGIN with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQBEGIN call exit functions.
  • Callback - MQ_CALLBACK_EXIT
    MQ_CALLBACK_EXIT provides an exit function to perform before and after callback processing. Use function identifier MQXF_CALLBACK with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after callback call exit functions.
  • Manage callback functions - MQ_CB_EXIT
    MQ_CB_EXIT provides an exit function to perform before and after the MQCB call. Use function identifier MQXF_CB with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQCB call exit functions.
  • Close - MQ_CLOSE_EXIT
    MQ_CLOSE_EXIT provides a close exit function to perform before and after MQCLOSE call processing. Use function identifier MQXF_CLOSE with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQCLOSE call exit functions.
  • Commit - MQ_CMIT_EXIT
    MQ_CMIT_EXIT provides a commit exit function to perform before and after commit processing. Use function identifier MQXF_CMIT with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after commit call exit functions.
  • Connect and connect extension - MQ_CONNX_EXIT
    MQ_CONNX_EXIT provides connection exit function to perform before and after MQCONN processing, and connection extension exit function to perform before and after MQCONNX processing.
  • Control callback - MQ_CTL_EXIT
    MQ_CTL_EXIT provides a subscription request exit function to perform before and after control callback processing. Use function identifier MQXF_CTL with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after control callback call exit functions.
  • Disconnect - MQ_DISC_EXIT
    MQ_DISC_EXIT provides a disconnect exit function to perform before and after MQDISC exit processing. Use function identifier MQXF_DISC with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQDISC call exit functions.
  • Get - MQ_GET_EXIT
    MQ_GET_EXIT provides a get exit function to perform before and after MQGET call processing.
  • MQXF_DATA_CONV_ON_GET
    The MQXF_DATA_CONV_ON_GET function identifier is used with MQ_GET_EXIT.
  • Initialization - MQ_INIT_EXIT
    MQ_INIT_EXIT provides connection level initialization, indicated by setting ExitReason in MQAXP to MQXR_CONNECTION.
  • Inquire - MQ_INQ_EXIT
    MQ_INQ_EXIT provides an inquire exit function to perform before and after MQINQ call processing. Use function identifier MQXF_INQ with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQINQ call exit functions.
  • Open - MQ_OPEN_EXIT
    MQ_OPEN_EXIT provides an open exit function to perform before and after MQOPEN call processing. Use function identifier MQXF_OPEN with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQOPEN call exit functions.
  • Put - MQ_PUT_EXIT
    MQ_PUT_EXIT provides a put exit function to perform before and after MQPUT call processing. Use function identifier MQXF_PUT with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQPUT call exit functions.
  • Put1 - MQ_PUT1_EXIT
    MQ_PUT1_EXIT provides a put one message only exit function to perform before and after MQPUT1 call processing. Use function identifier MQXF_PUT1 with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQPUT1 call exit functions.
  • Set - MQ_SET_EXIT
    MQ_SET_EXIT provides a set exit function to perform before and after MQSET call processing. Use function identifier MQXF_SET with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQSET call exit functions.
  • Status - MQ_STAT_EXIT
    MQ_STAT_EXIT provides a status exit function to perform before and after MQSTAT call processing. Use function identifier MQXF_STAT with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQSTAT call exit functions.
  • Termination - MQ_TERM_EXIT
    MQ_TERM_EXIT provides connection level termination, registered with a function identifier of MQXF_TERM and ExitReason MQXR_CONNECTION. If registered, MQ_TERM_EXIT is called once for every disconnect request.
  • Register subscription - MQ_SUB_EXIT
    MQ_SUB_EXIT provides an exit function to perform before and after subscription reregistration processing. Use function identifier MQXF_SUB with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after subscription registrationcall exit functions.
  • Subscription request - MQ_SUBRQ_EXIT
    MQ_SUBRQ_EXIT provides a subscription request exit function to perform before and after subscription request processing. Use function identifier MQXF_SUBRQ with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after subscription request call exit functions.
  • xa_close - XA_CLOSE_EXIT
    XA_CLOSE_EXIT provides an xa_close exit function to perform before and after xa_close processing. Use function identifier MQXF_XACLOSE with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_close call exit functions.
  • xa_commit - XA_COMMIT_EXIT
    XA_COMMIT_EXIT provides an xa_commit exit function to perform before and after xa_commit processing. Use function identifier MQXF_XACOMMIT with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_commit call exit functions.
  • xa_complete - XA_COMPLETE_EXIT
    XA_COMPLETE_EXIT provides an xa_complete exit function to perform before and after xa_complete processing. Use function identifier MQXF_XACOMPLETE with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_complete call exit functions.
  • xa_end - XA_END_EXIT
    XA_END_EXIT provides an xa_end exit function to perform before and after xa_end processing. Use function identifier MQXF_XAEND with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_end call exit functions.
  • xa_forget - XA_FORGET_EXIT
    XA_FORGET_EXIT provides an xa_forget exit function to perform before and after xa_forget processing. Use function identifier MQXF_XAFORGET with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_forget call exit functions.
  • xa_open - XA_OPEN_EXIT
    XA_OPEN_EXIT provides an xa_open exit function to perform before and after xa_open processing. Use function identifier MQXF_XAOPEN with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_open call exit functions.
  • xa_prepare - XA_PREPARE_EXIT
    XA_PREPARE_EXIT provides an xa_prepare exit function to perform before and after xa_prepare processing. Use function identifier MQXF_XAPREPARE with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_prepare call exit functions.
  • xa_recover - XA_RECOVER_EXIT
    XA_RECOVER_EXIT provides an xa_recover exit function to perform before and after xa_recover processing. Use function identifier MQXF_XARECOVER with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_recover call exit functions.
  • xa_rollback - XA_ROLLBACK_EXIT
    XA_ROLLBACK_EXIT provides an xa_rollback exit function to perform before and after xa_rollback processing. Use function identifier MQXF_XAROLLBACK with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_rollback call exit functions.
  • xa_start - XA_START_EXIT
    XA_START_EXIT provides an xa_start exit function to perform before and after xa_start processing. Use function identifier MQXF_XASTART with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after xa_start call exit functions.
  • ax_reg - AX_REG_EXIT
    AX_REG_EXIT provides an ax_reg exit function to perform before and after ax_reg processing. Use function identifier MQXF_AXREG with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after ax_reg call exit functions.
  • ax_unreg - AX_UNREG_EXIT
    AX_UNREG_EXIT provides an ax_unreg exit function to perform before and after ax_unreg processing. Use function identifier MQXF_AXUNREG with exit reasons MQXR_BEFORE and MQXR_AFTER to register the before and after ax_unreg call exit functions.

Parent topic: API exit reference