General information on invoking exit functions

This section provides some general guidance to help you to plan your exits, particularly related to handling errors and unexpected events.

What happens when exits fail

If an exit function abnormally terminates after a destructive, out of syncpoint, MQGET call but before the message has been passed to the application, the exit handler can recover from the failure and pass control to the application. In this case, the message might be lost. This is similar to what happens when an application fails immediately after receiving a message from a queue.

The MQGET call might complete with MQCC_FAILED and MQRC_API_EXIT_ERROR.

If a before API call exit function terminates abnormally, the exit handler can recover from the failure and pass control to the application without processing the API call. In this event, the exit function must recover any resources that it owns.

If chained exits are in use, the after API call exits for any before API call exits that had successfully been driven can themselves be driven. The API call might fail with MQCC_FAILED and MQRC_API_EXIT_ERROR.

Example error handling for exit functions

The following diagram shows the points (eN) at which errors can occur. It is only an example to show how exits behave and should be read together with the following table. In this example, two exit functions are invoked both before and after each API call to show the behavior with chained exits.

Application ErrPt     Exit function            API call
----------- -----     -------------            --------

Start

MQCONN  -->
            e1
                         MQ_INIT_EXIT
            e2
                  before MQ_CONNX_EXIT  1
            e3
                  before MQ_CONNX_EXIT  2
            e4
                                          -->  MQCONN
            e5
                  after  MQ_CONNX_EXIT  2
            e6
                  after  MQ_CONNX_EXIT  1
            e7
        <--
MQOPEN  -->
                  before MQ_OPEN_EXIT  1
            e8
                  before MQ_OPEN_EXIT  2
            e9
                                          -->  MQOPEN
            e10
                  after  MQ_OPEN_EXIT  2
            e11
                  after  MQ_OPEN_EXIT  1
            e12
        <--
MQPUT   -->
                  before MQ_PUT_EXIT   1
            e13
                  before MQ_PUT_EXIT   2
            e14
                                          -->  MQPUT
            e15
                  after  MQ_PUT_EXIT   2
            e16
                  after  MQ_PUT_EXIT   1
            e17
        <--
MQCLOSE -->
                  before MQ_CLOSE_EXIT 1
            e18
                  before MQ_CLOSE_EXIT 2
            e19
                                          -->  MQCLOSE
            e20
                  after  MQ_CLOSE_EXIT 2
            e21
                  after  MQ_CLOSE_EXIT 1
            e22
        <--
MQDISC  -->
                  before MQ_DISC_EXIT  1
            e23
                  before MQ_DISC_EXIT  2
            e24
                                          -->  MQDISC
            e25
                  after  MQ_DISC_EXIT  2
            e26
                  after  MQ_DISC_EXIT  1
            e27

        <--

end                                              

The following table lists the actions to be taken at each error point. Only a subset of the error points have been covered, as the rules shown here can apply to all others. It is the actions that specify the intended behavior in each case.

Table 10. API exit errors and appropriate actions to take
ErrPt Description Actions
e1 Error while setting up environment setup.
  1. Undo environment setup as required
  2. Drive no exit functions
  3. Fail MQCONN with MQCC_FAILED, MQRC_API_EXIT_LOAD_ERROR
e2 MQ_INIT_EXIT function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED:
    1. Clean up environment
    2. Fail MQCONN with MQCC_FAILED, MQRC_API_EXIT_INIT_ERROR
  • For MQXCC_*
    1. Act as for the values of MQXCC_* and MQXR2_*1
    2. Clean up environment
e3 Before MQ_CONNX_EXIT 1 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED:
    1. Drive MQ_TERM_EXIT function
    2. Clean up environment
    3. Fail MQCONN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*
    1. Act as for the values of MQXCC_* and MQXR2_*1
    2. Drive MQ_TERM_EXIT function if required
    3. Clean up environment if required
e4 Before MQ_CONNX_EXIT 2 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED:
    1. Drive after MQ_CONNX_EXIT 1 function
    2. Drive MQ_TERM_EXIT function
    3. Clean up environment
    4. Fail MQCONN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*
    1. Act as for the values of MQXCC_* and MQXR2_*1
    2. Drive after MQ_CONNX_EXIT 1 function if exit not suppressed
    3. Drive MQ_TERM_EXIT function if required
    4. Clean up environment if required
e5 MQCONN call fails.
  1. Pass MQCONN CompCode and Reason
  2. Drive after MQ_CONNX_EXIT 2 function if the before MQ_CONNX_EXIT 2 succeeded and the exit is not suppressed
  3. Drive after MQ_CONNX_EXIT 1 function if the before MQ_CONNX_EXIT 1 succeeded and the exit is not suppressed
  4. Drive MQ_TERM_EXIT function
  5. Clean up environment
e6 After MQ_CONNX_EXIT 2 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED:
    1. Drive after MQ_CONNX_EXIT 1 function
    2. Complete MQCONN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*
    1. Act as for the values of MQXCC_* and MQXR2_*1
    2. Drive after MQ_CONNX_EXIT 1 function if required
e7 After MQ_CONNX_EXIT 1 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED, complete MQCONN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*, act as for the values of MQXCC_* and MQXR2_*1
e8 Before MQ_OPEN_EXIT 1 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED, complete MQOPEN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*, act as for the values of MQXCC_* and MQXR2_*1
e9 Before MQ_OPEN_EXIT 2 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED:
    1. Drive after MQ_OPEN_EXIT 1 function
    2. Complete MQOPEN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*, act as for the values of MQXCC_* and MQXR2_*1
e10 MQOPEN call fails
  1. Pass MQOPEN CompCode and Reason
  2. Drive after MQ_OPEN_EXIT 2 function if exit not suppressed
  3. Drive after MQ_OPEN_EXIT 1 function if exit not suppressed and if chained exits not suppressed
e11 After MQ_OPEN_EXIT 2 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED:
    1. Drive after MQ_OPEN_EXIT 1 function
    2. Complete MQOPEN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*
    1. Act as for the values of MQXCC_* and MQXR2_*1
    2. Drive after MQ_OPEN_EXIT 1 function if exit not suppressed
e25 After MQ_DISC_EXIT 2 function completes with:
  • MQXCC_FAILED
  • MQXCC_*
  • For MQXCC_FAILED:
    1. Drive after MQ_DISC_EXIT 1 function
    2. Drive MQ_TERM_EXIT function
    3. Clean up exit execution environment
    4. Complete MQDISC call with MQCC_FAILED, MQRC_API_EXIT_ERROR
  • For MQXCC_*
    1. Act as for the values of MQXCC_* and MQXR2_*1
    2. Drive MQ_TERM_EXIT function
    3. Clean up exit execution environment
Notes:
  1. The values of MQXCC_* and MQXR2_* and their corresponding actions are defined in How queue managers process exit functions.

What if the ExitResponse fields are incorrectly set

If the ExitResponse field is set to a value other than one of the supported values, the following actions apply:

If an exit function sets the ExitResponse2 field to a value other than one of the supported values, a value of MQXR2_DEFAULT_CONTINUATION is assumed instead.