Reference information
This section contains reference information, mainly of interest to the programmer writing API exits. It covers:
- External control blocks
- The exit chain area and exit chain area header (MQACH)
- External constants
- C language typedefs
- The exit entry point registration call (MQXEP)
- Invoking exit functions
External control blocks
Here we describe the structure of the external control blocks, MQAXP and MQAXC.
WebSphere MQ API exit parameter structure (MQAXP)
The MQAXP structure is used as an input/output parameter to the API exit. MQAXP has the following C declaration:
typedef struct tagMQAXP { MQCHAR4 StrucId; /* Structure identifier */ MQLONG Version; /* Structure version number */ MQLONG ExitId; /* Exit Identifier */ MQLONG ExitReason; /* Exit invocation reason */ MQLONG ExitResponse; /* Response code from exit */ MQLONG ExitResponse2; /* Secondary response code from exit */ MQLONG Feedback; /* Feedback code from exit */ MQLONG APICallerType; /* MQSeries API caller type */ MQBYTE16 ExitUserArea; /* User area for use by exit */ MQCHAR32 ExitData; /* Exit data area */ MQCHAR48 ExitInfoName; /* Exit information name */ MQBYTE48 ExitPDArea; /* Problem determination area */ MQCHAR48 QMgrName; /* Name of local queue manager */ PMQACH ExitChainAreaPtr; /* Inter exit communication area */ MQHCONFIG Hconfig; /* Configuration handle */ MQLONG Function; /* Function Identifier */ };The parameter list described below is passed when functions in an API exit are invoked:
- StrucId (MQCHAR4) - input
- The exit parameter structure identifier, with a value of:
MQAXP_STRUC_ID.The exit handler sets this field on entry to each exit function.
- Version (MQLONG) - input
- The structure version number, with a value of:
- MQAXP_VERSION_1
- Version number for the exit parameter structure.
- MQAXP_CURRENT_VERSION
- Current version number for the exit parameter structure.
The exit handler sets this field on entry to each exit function.
- ExitId (MQLONG) - input
- The exit identifier, set on entry to the exit routine, indicating the type of exit:
- MQXT_API_EXIT
- API exit.
- ExitReason (MQLONG) - input
- The reason for invoking the exit, set on entry to each exit function:
- MQXR_CONNECTION
- The exit is being invoked to initialize itself before an MQCONN or MQCONNX call, or to end itself after an MQDISC call.
- MQXR_BEFORE
- The exit is being invoked before executing an API call, or before converting data on an MQGET.
- MQXR_AFTER
- The exit is being invoked after executing an API call.
- ExitResponse (MQLONG) - output
- The response from the exit, initialized on entry to each exit function to:
- MQXCC_OK
- Continue normally.
This field must be set by the exit function, to communicate to the queue manager the result of executing the exit function. The value must be one of the following:
- MQXCC_OK
- The exit function completed successfully. Continue normally.
This value can be set by all MQXR_* exit functions. ExitResponse2 is used to decide whether exit functions later in the chain should be invoked.
- MQXCC_FAILED
- The exit function failed because of some error.
This value can be set by all MQXR_* exit functions. The queue manager sets CompCode to MQCC_FAILED, and Reason to:
- MQRC_API_EXIT_INIT_ERROR if the function is MQ_INIT_EXIT
- MQRC_API_EXIT_TERM_ERROR if the function is MQ_TERM_EXIT
- MQRC_API_EXIT_ERROR for all other exit functions
The values set can be altered by an exit function later in the chain.
ExitResponse2 is ignored; the queue manager continues processing as though MQXR2_SUPPRESS_CHAIN had been returned.
- MQXCC_SUPPRESS_FUNCTION
- Suppress WebSphere MQ API function.
This value can be set only by an MQXR_BEFORE exit function. It bypasses the API call. If it is returned by the MQ_DATA_CONV_ON_GET_EXIT, data conversion is bypassed. The queue manager sets CompCode to MQCC_FAILED, and Reason to MQRC_SUPPRESSED_BY_EXIT, but the values set can be altered by an exit function later in the chain. Other parameters for the call remain as the exit left them. ExitResponse2 is used to decide whether exit functions later in the chain should be invoked.
If this value is set by an MQXR_AFTER or MQXR_CONNECTION exit function, the queue manager continues processing as though MQXCC_FAILED had been returned.
- MQXCC_SKIP_FUNCTION
- Skip WebSphere MQ API function.
This value can be set only by an MQXR_BEFORE exit function. It bypasses the API call. If it is returned by the MQ_DATA_CONV_ON_GET_EXIT, data conversion is bypassed. The exit function must set CompCode and Reason to the values to be returned to the application, but the values set can be altered by an exit function later in the chain. Other parameters for the call remain as the exit left them. ExitResponse2 is used to decide whether exit functions later in the chain should be invoked.
If this value is set by an MQXR_AFTER or MQXR_CONNECTION exit function, the queue manager continues processing as though MQXCC_FAILED had been returned.
- MQXCC_SUPPRESS_EXIT
- Suppress all exit functions belonging to the set of exits.
This value can be set only by the MQXR_BEFORE and MQXR_AFTER exit functions. It bypasses all subsequent invocations of exit functions belonging to this set of exits for this logical connection. This bypassing continues until the logical disconnect request occurs, when MQ_TERM_EXIT function is invoked with an ExitReason of MQXR_CONNECTION.
The exit function must set CompCode and Reason to the values to be returned to the application, but the values set can be altered by an exit function later in the chain. Other parameters for the call remain as the exit left them. ExitResponse2 is ignored.
If this value is set by an MQXR_CONNECTION exit function, the queue manager continues processing as though MQXCC_FAILED had been returned.
For information on the interaction between ExitResponse and ExitResponse2, and its affect on exit processing, see How queue managers process exit functions.
- ExitResponse2 (MQLONG) - output
- This is a secondary exit response code that qualifies the primary exit response code for MQXR_BEFORE exit functions. It is initialized to:
MQXR2_DEFAULT_CONTINUATIONon entry to a WebSphere MQ API call exit function. It can then be set to one of the values:
- MQXR2_DEFAULT_CONTINUATION
- Whether to continue with the next exit in the chain, depending on the value of ExitResponse.
If ExitResponse is MQXCC_SUPPRESS_FUNCTION or MQXCC_SKIP_FUNCTION, bypass exit functions later in the MQXR_BEFORE chain and the matching exit functions in the MQXR_AFTER chain. Invoke exit functions in the MQXR_AFTER chain that match exit functions earlier in the MQXR_BEFORE chain.
Otherwise, invoke the next exit in the chain.
- MQXR2_SUPPRESS_CHAIN
- Suppress the chain.
Bypass exit functions later in the MQXR_BEFORE chain and the matching exit functions in the MQXR_AFTER chain for this API call invocation. Invoke exit functions in the MQXR_AFTER chain that match exit functions earlier in the MQXR_BEFORE chain.
- MQXR2_CONTINUE_CHAIN
- Continue with the next exit in the chain.
For information on the interaction between ExitResponse and ExitResponse2, and its affect on exit processing, see How queue managers process exit functions.
- Feedback (MQLONG) - input/output
- Communicate feedback codes between exit function invocations. This is initialized to:
MQFB_NONE (0)before invocation of the first function of the first exit in a chain.
Exits can set this field to any value, including any valid MQFB_* or MQRC_* value. Exits can also set this field to a user-defined feedback value in the range MQFB_APPL_FIRST to MQFB_APPL_LAST.
- APICallerType (MQLONG) - input
- The API caller type, indicating whether the WebSphere MQ API caller is external or internal to the queue manager: MQXACT_EXTERNAL or MQXACT_INTERNAL.
- ExitUserArea (MQBYTE16) - input/output
- A user area, available to all the exits associated with a particular ExitInfoObject. It is initialized to MQXUA_NONE (binary zeros for the length of the ExitUserArea) before invoking the first exit function (MQ_INIT_EXIT) for the hconn. From then on, any changes made to this field by an exit function are preserved across invocations of functions of the same exit.
This field is aligned to a multiple of 4 MQLONGs.
Exits can also anchor any storage that they allocate from this area.
For each hconn, each exit in a chain of exits has a different ExitUserArea. The ExitUserArea cannot be shared by exits in a chain, and the contents of the ExitUserArea for one exit are not available to another exit in a chain.
For C programs, the constant MQXUA_NONE_ARRAY is also defined with the same value as MQXUA_NONE, but as an array of characters instead of a string.
The length of this field is given by MQ_EXIT_USER_AREA_LENGTH.
- ExitData (MQCHAR32) - input
- Exit data, set, on input to each exit function, to the 32 characters of exit-specific data that is provided in the exit. If you define no value in the exit this field is all blanks.
The length of this field is given by MQ_EXIT_DATA_LENGTH.
- ExitInfoName (MQCHAR48) - input
- The exit information name, set, on input to each exit function, to the ApiExit_name specified in the exit definitions in the stanzas.
- ExitPDArea (MQBYTE48) - input/output
- A problem determination area, initialized to MQXPDA_NONE (binary zeros for the length of the field) for each invocation of an exit function.
For C programs, the constant MQXPDA_NONE_ARRAY is also defined with the same value as MQXPDA_NONE, but as an array of characters instead of a string.
The exit handler always writes this area to the WebSphere MQ trace at the end of an exit, even when the function is successful.
The length of this field is given by MQ_EXIT_PD_AREA_LENGTH.
- QMgrName (MQCHAR48) - input
- The name of the local queue manager that has invoked an exit as a result of processing a WebSphere MQ API call.
If the name of a queue manager supplied on an MQCONN or MQCONNX calls is blank, this field is still set to the name of the local or default queue manager.
The exit handler sets this field on entry to each exit function.
The length of this field is given by MQ_Q_MGR_NAME_LENGTH.
- ExitChainAreaPtr (PMQACH) - input/output
- This is used to communicate data across invocations of different exits in a chain. It is set to a NULL pointer before invoking the first function MQ_INIT_EXIT(with ExitReason MQXR_CONNECTION) of the first exit in a chain of exits. The value returned by the exit on one invocation is passed on to the next invocation.
Refer to The exit chain area and exit chain area header (MQACH) for more details about how to use the exit chain area.
- Hconfig (MQHCONFIG) - input
- The configuration handle, representing the set of functions being initialized. This value is generated by the queue manager on the MQ_INIT_EXIT function, and is subsequently passed to the API exit function. It is set on entry to each exit function.
- Function (MQLONG) - input
- The function identifier, valid values for which are the MQXF_* constants described in External constants.
The exit handler sets this field to the correct value, on entry to each exit function, depending on the WebSphere MQ API call that resulted in the exit being invoked.
How queue managers process exit functions
The processing performed by the queue manager on return from an exit function depends on both ExitResponse and ExitResponse2. Table 9 below summarizes the possible combinations and their effects for an MQXR_BEFORE exit function, showing:
- Who sets the CompCode and Reason parameters of the API call
- Whether the remaining exit functions in the MQXR_BEFORE chain and the matching exit functions in the MQXR_AFTER chain are invoked
- Whether the API call is invoked
For an MQXR_AFTER exit function:
- CompCode and Reason are set in the same way as MQXR_BEFORE
- ExitResponse2 is ignored (the remaining exit functions in the MQXR_AFTER chain are always invoked)
- MQXCC_SUPPRESS_FUNCTION and MQXCC_SKIP_FUNCTION are not valid
For an MQXR_CONNECTION exit function:
- CompCode and Reason are set in the same way as MQXR_BEFORE
- ExitResponse2 is ignored
- MQXCC_SUPPRESS_FUNCTION, MQXCC_SKIP_FUNCTION, MQXCC_SUPPRESS_EXIT are not valid
In all cases, where an exit or the queue manager sets CompCode and Reason, the values set can be changed by an exit invoked later, or by the API call (if the API call is invoked later).
Table 9. MQXR_BEFORE exit processing
>Value of ExitResponse CompCode and Reason set by Value of ExitResponse2 (default continuation) Chain Value of ExitResponse2 (default continuation) API >MQXCC_OK exit Y Y >MQXCC_SUPPRESS_EXIT exit Y Y >MQXCC_SUPPRESS_FUNCTION queue manager N N >MQXCC_SKIP FUNCTION exit N N >MQXCC_FAILED queue manager N N
WebSphere MQ API exit context structure (MQAXC)
The MQAXC structure is used as an input parameter to an API exit. MQAXC has the following C declaration:
typedef struct tagMQAXC { MQCHAR4 StrucId; /* Structure identifier */ MQLONG Version; /* Structure version number */ MQLONG Environment; /* Environment */ MQCHAR12 UserId; /* UserId associated with appl */ MQBYTE40 SecurityId /* Extension to UserId running appl */ MQCHAR264 ConnectionName; /* Connection name */ MQLONG LongMCAUserIdLength; /* long MCA user identifier length */ MQLONG LongRemoteUserIdLength; /* long remote user identifier length */ MQPTR LongMCAUserIdPtr; /* long MCA user identifier address */ MQPTR LongRemoteUserIdPtr; /* long remote user identifier address */ MQCHAR28 ApplName; /* Application name */ MQLONG ApplType; /* Application type */ MQPID ProcessId; /* Process identifier */ MQTID ThreadId; /* Thread identifier */ };The parameters to MQAXC are:
- StrucId (MQCHAR4) - input
- The exit context structure identifier, with a value of MQAXC_STRUC_ID. For C programs, the constant MQAXC_STRUC_ID_ARRAY is also defined, with the same value as MQAXC_STRUC_ID, but as an array of characters instead of a string.
The exit handler sets this field on entry to each exit function.
- Version (MQLONG) - input
- The structure version number, with a value of:
- MQAXC_VERSION_1
- Version number for the exit context structure.
- MQAXC_CURRENT_VERSION
- Current version number for the exit context structure.
The exit handler sets this field on entry to each exit function.
- Environment (MQLONG) - input
- The environment from which a WebSphere MQ API call was issued that resulted in an exit function being driven. Valid values for this field are:
- MQXE_OTHER
- An unrecognizable environment
- MQXE_MCA
- Message Channel Agent.
- MQXE_MCA_SVRCONN
- A Message Channel Agent acting on behalf of a client.
- MQXE_COMMAND_SERVER
- The Command Server.
- MQXE_MQSC
- The runmqsc command interpreter
The exit handler sets this field on entry to each exit function.
- UserId (MQCHAR12) - input
- The UserId associated with the application. In particular, in the case of client connections, this field contains the UserId of the adopted user as opposed to the UserId under which the channel code is running.
The exit handler sets this field on entry to each exit function. The length of this field is given by MQ_USER_ID_LENGTH.
- SecurityId (MQBYTE40) - input
- An extension to the userid running the application. Its length is given by MQ_SECURITY_ID_LENGTH.
- ConnectionName (MQCHAR264) - input
- The connection name field, set to the address of the client. For example, for TCP/IP, it would be the client IP address.
The length of this field is given by MQ_CONN_NAME_LENGTH.
- LongMCAUserIdLength (MQLONG) - input
- The length of the long MCA user identifier.
When MCA connects to the queue manager this field is set to the length of the long MCA user identifier (or zero if there is no such identifier).
- LongRemoteUserIdLength (MQLONG) - input
- The length of the long remote user identifier.
When MCA connects to the queue manager this field will be set to the length of the long remote user identifier. Otherwise this field will be set to zero
- LongMCAUserIdPtr (MQPTR) - input
- Address of long MCA user identifier.
When MCA connects to the queue manager this field is set to the address of the long MCA user identifier (or to a null pointer if there is no such identifier).
- LongRemoteUserIdPtr (MQPTR) - input
- The address of the long remote user identifier.
When MCA connects to the queue manager this field is set to the address of the long remote user identifier (or to a null pointer if there is no such identifier).
- ApplName (MQCHAR28) - input
- The name of the application or component that issued the WebSphere MQ API call.
The rules for generating the ApplName are the same as for generating the default name for an MQPUT.
The value of this field is found by querying the operating system for the program name. Its length is given by MQ_APPL_NAME_LENGTH.
- ApplType (MQLONG) - input
- The type of application or component that issued the WebSphere MQ API call.
The value is MQAT_DEFAULT for the platform on which the application is compiled, or it equates to one of the defined MQAT_* values.
The exit handler sets this field on entry to each exit function.
- ProcessId (MQPID) - input
- The operating system process identifier.
Where applicable, the exit handler sets this field on entry to each exit function.
- ThreadId (MQTID) - input
- The MQ thread identifier. This is the same identifier used in MQ trace and FFST dumps, but may be different from the operating system thread identifier.
Where applicable, the exit handler sets this field on entry to each exit function.
The exit chain area and exit chain area header (MQACH)
If required, an exit function can acquire storage for an exit chain area and set the ExitChainAreaPtr in MQAXP to point to this storage.
Exits (either the same or different exit functions) can acquire multiple exit chain areas and link them together. Exit chain areas must only be added or removed from this list while called from the exit handler. This ensures there are no serialization issues caused by different threads adding or removing areas from the list at the same time.
An exit chain area must start with an MQACH header structure, the C declaration for which is:
typedef struct tagMQACH { MQCHAR4 StrucId; /* Structure identifier */ MQLONG Version; /* Structure version number */ MQLONG StrucLength; /* Length of the MQACH structure */ MQLONG ChainAreaLength; /* Exit chain area length */ MQCHAR48 ExitInfoName /* Exit information name */ PMQACH NextChainAreaPtr; /* Pointer to next exit chain area */ };The fields in the exit chain area header are:
- StrucId (MQCHAR4) - input
- The exit chain area structure identifier, with an initial value, defined by MQACH_DEFAULT, of MQACH_STRUC_ID.
For C programs, the constant MQACH_STRUC_ID_ARRAY is also defined; this has the same value as MQACH_STRUC_ID, but as an array of characters instead of a string.
- Version (MQLONG) - input
- The structure version number, as follows:
- MQACH_VERSION_1
- The version number for the exit parameter structure.
- MQACH_CURRENT_VERSION
- The current version number for the exit context structure.
The initial value of this field, defined by MQACH_DEFAULT, is MQACH_CURRENT_VERSION.
- Note:
- If you introduce a new version of this structure, the layout of the existing part does not change. Exit functions need to check that the version number is equal to or greater than the lowest version containing the fields that the exit function needs to use.
- StrucLength (MQLONG) - input
- The length of the MQACH structure. Exits can use this field to determine the start of the exit data, setting it to the length of the structure created by the exit.
The initial value of this field, defined by MQACH_DEFAULT, is MQACH_CURRENT_LENGTH.
- ChainAreaLength (MQLONG) - input
- The exit chain area length, set to the overall length of the current exit chain area, including the MQACH header.
The initial value of this field, defined by MQACH_DEFAULT, is zero.
- ExitInfoName (MQCHAR48) - input
- The exit information name.
When an exit creates an MQACH structure, it must initialize this field with its own ExitInfoName, so that later this MQACH structure can be found by either another instance of this exit, or by a cooperating exit.
The initial value of this field, defined by MQACH_DEFAULT, is a zero length string ({""}).
- NextChainAreaPtr (PMQACH) - input
- A pointer to the next exit chain area with an initial value, defined by MQACH_DEFAULT, of null pointer (NULL ).
Exit functions must release the storage for any exit chain areas that they acquire, and manipulate the chain pointers to remove their exit chain areas from the list.
An exit chain area can be constructed as follows:
MQAXP.ExitChainAreaPtr ---* *-----------------------* *--> *-----*---*----*-----*----------------------------------------------* | ACH | 1 | 80 | --* | First exit's chain area | *-----*---*----*---|-*----------------------------------------------* *-----------------------* *--> *-----*---*----*-----*---------------------------* | ACH | 1 | 64 | --* | Second exit's chain area | *-----*---*----*---|-*---------------------------* *-----------------------* *--> ... etc.
External constants
The following new external constants are available for API exits:
- MQXF_* (exit function identifiers)
MQXF_INIT 1 X'00000001' MQXF_TERM 2 X'00000002' MQXF_CONN 3 X'00000003' MQXF_CONNX 4 X'00000004' MQXF_DISC 5 X'00000005' MQXF_OPEN 6 X'00000006' MQXF_CLOSE 7 X'00000007' MQXF_PUT1 8 X'00000008' MQXF_PUT 9 X'00000009' MQXF_GET 10 X'0000000A' MQXF_DATA_CONV_ON_GET 11 X'0000000B' MQXF_INQ 12 X'0000000C' MQXF_SET 13 X'0000000D' MQXF_BEGIN 14 X'0000000E' MQXF_CMIT 15 X'0000000F' MQXF_BACK 16 X'00000010'
- MQXR_* (exit reasons)
MQXR_BEFORE 1 X'00000001' MQXR_AFTER 2 X'00000002' MQXR_CONNECTION 3 X'00000003'
- MQXE_* (environments)
MQXE_OTHER 0 X'00000000' MQXE_MCA 1 X'00000001' MQXE_MCA_SVRCONN 2 X'00000002' MQXE_COMMAND_SERVER 3 X'00000003' MQXE_MQSC 4 X'00000004'
- MQ*_* (additional constants)
MQAXP_VERSION_1 1 MQAXC_VERSION_1 1 MQACH_VERSION_1 1 MQAXP_CURRENT_VERSION 1 MQAXC_CURRENT_VERSION 1 MQACH_CURRENT_VERSION 1 MQXACT_EXTERNAL 1 MQXACT_INTERNAL 2 MQXT_API_EXIT 2 MQACH_LENGTH_1 68 (32-bit platforms) 72 (64-bit platforms) 80 (128-bit platforms) MQACH_CURRENT_LENGTH 68 (32-bit platforms) 72 (64-bit platforms) 80 (128-bit platforms)
- MQ*_* (null constants)
MQXPDA_NONE X'00...00' (48 nulls) MQXPDA_NONE_ARRAY '\0','\0',...,'\0','\0'
- MQXCC_* (completion codes)
- MQRC_* (reason codes)
- MQRC_API_EXIT_ERROR 2374 X'00000946'
- An exit function invocation has returned an invalid response code, or has failed in some way, and the queue manager cannot determine the next action to take.
Examine both the ExitResponse and ExitResponse2 fields of the MQAXP to determine the bad response code, and change the exit to return a valid response code.
- MQRC_API_EXIT_INIT_ERROR 2375 X'00000947'
- The queue manager encountered an error while initializing the execution environment for an API exit function.
- MQRC_API_EXIT_TERM_ERROR 2376 X'00000948'
- The queue manager encountered an error while closing the execution environment for an API exit function.
- MQRC_EXIT_REASON_ERROR 2377 X'00000949'
- The value of the ExitReason field supplied on an exit entry point registration call (MQXEP) call is in error.
Examine the value of the ExitReason field to determine and correct the bad exit reason value.
- MQRC_RESERVED_VALUE_ERROR 2378 X'0000094A'
- The value of the Reserved field is in error.
Examine the value of the Reserved field to determine and correct the Reserved value.
C language typedefs
Here are the C language typedefs associated with the API exits:
typedef PMQLONG MQPOINTER PPMQLONG; typedef PMQBYTE MQPOINTER PPMQBYTE; typedef PMQHOBJ MQPOINTER PPMQHOBJ; typedef PMQOD MQPOINTER PPMQOD; typedef PMQMD MQPOINTER PPMQMD; typedef PMQPMO MQPOINTER PPMQPMO; typedef PMQGMO MQPOINTER PPMQGMO; typedef PMQCNO MQPOINTER PPMQCNO; typedef PMQBO MQPOINTER PPMQBO; typedef MQAXP MQPOINTER PMQAXP; typedef MQACH MQPOINTER PMQACH; typedef MQAXC MQPOINTER PMQAXC; typedef MQCHAR MQCHAR16[16]; typedef MQCHAR16 MQPOINTER PMQCHAR16; typedef MQLONG MQPID; typedef MQLONG MQTID;
The exit entry point registration call (MQXEP)
Use the MQXEP call to:
- Register the before and after WebSphere MQ API exit invocation points at which exit functions are to be invoked
- Specify the exit function entry points
- Deregister the exit function entry points
You would usually code the MQXEP calls in the MQ_INIT_EXIT exit function, but you can specify them in any subsequent exit function.
If you use an MQXEP call to register an already registered exit function, the second MQXEP call completes successfully, replacing the registered exit function.
If you use an MQXEP call to register a NULL exit function, the MQXEP call will complete successfully and the exit function is deregistered.
If MQXEP calls are used to register, deregister, and reregister a given exit function during the life of a connection request, the previously registered exit function is reactivated. Any storage still allocated and associated with this exit function instance is available for use by the exit's functions. (This storage is usually released during the invocation of the termination exit function).
The interface to MQXEP is:
MQXEP (Hconfig, ExitReason, Function, EntryPoint, Reserved, &CompCode, &Reason)where:
- Hconfig (MQHCONFIG) - input
- The configuration handle, representing the API exit that includes the set of functions being initialized. This value is generated by the queue manager immediately before invoking the MQ_INIT_EXIT function, and is passed in the MQAXP to each API exit function.
- ExitReason (MQLONG) - input
- The reason for which the entry point is being registered, from the following:
- Connection level initialization or termination (MQXR_CONNECTION)
- Before a WebSphere MQ API call (MQXR_BEFORE)
- After a WebSphere MQ API call (MQXR_AFTER)
- Function (MQLONG) - input
- The function identifier, valid values for which are the MQXF_* constants (see External constants).
- EntryPoint (PMQFUNC) - input
- The address of the entry point for the exit function to be registered. The value NULL indicates either that the exit function has not been provided, or that a previous registration of the exit function is being deregistered.
- Reserved (MQPTR)
- This must be set to NULL and is reserved for future use.
- CompCode (MQLONG) - output
- The completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_FAILED
- Call failed.
- Reason (MQLONG) - output
- The reason code that qualifies the completion code.
If the completion code is MQCC_OK:
- MQRC_NONE
- (0, X'000') No reason to report.
If the completion code is MQCC_FAILED:
- MQRC_HCONFIG_ERROR
- (2280, X'8E8') The supplied configuration handle is invalid. Use the configuration handle from the MQAXP.
- MQRC_EXIT_REASON_ERROR
- (2377, X'949') The supplied exit function invocation reason is either invalid or is invalid for the supplied exit function identifier.
Either use one of the valid exit function invocation reasons (MQXR_* value), or use a valid function identifier and exit reason combination. (See Table 10.)
- MQRC_FUNCTION_ERROR
- (2281, X'8E9') The supplied function identifier is not valid for API exit reason. The following table shows valid combinations of function identifiers and ExitReasons.
Table 10. Valid combinations of function identifiers and ExitReasons
Function ExitReason MQXF_INIT
MQXF_TERM
MQXR_CONNECTION MQXF_CONN
MQXF_CONNX
MQXF_DISC
MQXF_OPEN
MQXF_CLOSE
MQXF_PUT1
MQXF_PUT
MQXF_GET
MQXF_INQ
MQXF_SET
MQXF_BEGIN
MQXF_COMMIT
MQXF_BACK
MQXR_BEFORE
MQXR_AFTER
MQXF_DATA_CONV_ON_GET MQXR_BEFORE
- MQRC_RESOURCE_PROBLEM
- (2102, X'836') An attempt to register or deregister an exit function has failed because of a resource problem.
- MQRC_UNEXPECTED_ERROR
- (2195, X'893') An attempt to register or deregister an exit function has failed unexpectedly.
- MQRC_RESERVED_VALUE_ERROR
- (2378, X'94A') The reserved parameter was not null.
MQXEP C language invocation
MQXEP (Hconfig, ExitReason, Function, EntryPoint, &CompCode, &Reason);Declaration for parameter list:
MQHCONFIG Hconfig; /* Configuration handle */ MQLONG ExitReason; /* Exit reason */ MQLONG Function; /* Function identifier */ PMQFUNC EntryPoint; /* Function entry point */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying completion code */
MQXEP C function prototype
void MQXEP ( MQHCONFIG Hconfig, /* Configuration handle */ MQLONG ExitReason, /* Exit reason */ MQLONG Function, /* Function identifier */ PMQFUNC EntryPoint, /* Function entry point */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
Invoking exit functions
This section tells you how to invoke the exit functions available. The descriptions of the individual functions start at The API exit functions. This section begins with some general information to help you when using these function calls.
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 input to and output from an exit routine are:
- On input to a before WebSphere MQ API exit function, the value of a field may be set by the application program, or by a previous exit function invocation.
- On output from a before WebSphere MQ API exit function, the value of a field may be left unchanged, or set to some other value by the exit function.
- On input to an after WebSphere MQ API exit function, the value of a field may be the value set by the queue manager after processing the WebSphere MQ API call, or may be set to a value by a previous exit function invocation in the chain of exit functions.
- On output from an after WebSphere MQ API call exit function, the value of a field may 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 may 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.
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
In other words, the exit cannot be unloaded as it may 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 at this point.
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 may 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 will not be 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.
The API exit functions
This section describes each of the exit functions and its parameters, as follows:
- Backout - MQ_BACK_EXIT
- Begin - MQ_BEGIN_EXIT
- Close - MQ_CLOSE_EXIT
- Commit - MQ_CMIT_EXIT
- Connect and connect extension - MQ_CONNX_EXIT
- Disconnect - MQ_DISC_EXIT
- Get - MQ_GET_EXIT
- Initialization - MQ_INIT_EXIT
- Inquire - MQ_INQ_EXIT
- Open - MQ_OPEN_EXIT
- Put - MQ_PUT_EXIT
- Put1 - MQ_PUT1_EXIT
- Set - MQ_SET_EXIT
- Termination - MQ_TERM_EXIT
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.
The interface to this functions:
MQ_BACK_EXIT (&ExitParms, &ExitContext, &Hconn, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying completion code */The queue manager then logically calls the exit as follows:
MQ_BACK_EXIT (&ExitParms, &ExitContext, &Hconn, &CompCode, &Reason);Your exit must match the following C function prototype:
void MQENTRY MQ_BACK_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
The interface to this function is:
MQ_BEGIN_EXIT (&ExitParms, &ExitContext, &Hconn, &pBeginOptions, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- pBeginOptions (PMQBO)- input/output
- Pointer to begin options.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ PMQBO pBeginOptions; /* Ptr to begin options */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying completion code */The queue manager then logically calls the exit as follows:
MQ_BEGIN_EXIT (&ExitParms, &ExitContext, &Hconn, &pBeginOptions, &CompCode, &Reason);Your exit must match the following C function prototype:
void MQENTRY MQ_BEGIN_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PPMQBO ppBeginOptions, /* Address of ptr to begin options */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
The interface to this function is:
MQ_CLOSE_EXIT (&ExitParms, &ExitContext, &Hconn, &pHobj, &Options, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- pHobj (PMQHOBJ) - input
- Pointer to object handle.
- Options (MQLONG)- input/output
- Close options.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ PMQHOBJ pHobj; /* Ptr to object handle */ MQLONG Options; /* Close options */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_CLOSE_EXIT (&ExitParms, &ExitContext,&Hconn, &pHobj, &Options, &CompCode, &Reason);Your exit must match the following C function prototype:
void MQENTRY MQ_CLOSE_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PPMQHOBJ ppHobj, /* Address of ptr to object handle */ PMQLONG pOptions, /* Address of close options */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
If a commit operation fails, and the transaction is backed out, the MQCMIT call fails with MQCC_WARNING and MQRC_BACKED_OUT. These return and reason codes are passed into any after MQCMIT exit functions to give the exit functions an indication that the unit of work has been backed out.
The interface to this function is:
MQ_CMIT_EXIT (&ExitParms, &ExitContext, &Hconn, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying completion code */The queue manager then logically calls the exit as follows:
MQ_CMIT_EXIT (&ExitParms, &ExitContext,&Hconn, &CompCode, &Reason);Your exit must match the following C function prototype:
void MQENTRY MQ_CMIT_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
Connect and connect extension - MQ_CONNX_EXIT
MQ_CONNX_EXIT provides:
- Connection exit function to perform before and after MQCONN processing
- Connection extension exit function to perform before and after MQCONNX processing
The same interface, as described below, is invoked for both MQCONN and MQCONNX call exit functions.
When the message channel agent (MCA) responds to an inbound client connection, the MCA can connect and make a number of WebSphere MQ API calls before the client state is fully known. These API calls result in the API exit functions being called with the MQAXC based on the MCA program itself (for example in the UserId and ConnectionName fields of the MQAXC).
When the MCA responds to subsequent inbound client API calls, the MQAXC structure is based on the inbound client, setting the UserId and ConnectionName fields appropriately.
The queue manager name set by the application on an MQCONN or MQCONNX call is passed to the underlying connect call. Any attempt by a before MQ_CONNX_EXIT to change the name of the queue manager has no effect.
Use function identifiers MQXF_CONN and MQXF_CONNX with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQCONN and MQCONNX call exit functions.
An MQ_CONNX_EXIT exit called for reason MQXR_BEFORE must not issue any WebSphere MQ API calls, as the correct environment has not been set up at this time.
The interface to MQCONN and MQCONNX is identical:
MQ_CONNX_EXIT (&ExitParms, &ExitContext, &pQMgrName, &pConnectOpts, &pHconn, &CompCode, &Reason);where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- pQMgrName (PMQCHAR) - input
- Pointer to the queue manager name supplied on the MQCONNX call. The exit must not change this name on the MQCONN or MQCONNX call.
- pConnectOpts (PMQCNO) - input/output
- Pointer to the options that control the action of the MQCONNX call.
See "MQCNO - Connect options" in the WebSphere MQ Application Programming Reference for details.
For exit function MQXF_CONN, pConnectOpts points to the default connect options structure (MQCNO_DEFAULT).
- pHconn (PMQHCONN) - input
- Pointer to the connection handle.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Warning (partial completion)
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ PMQCHAR pQMgrName; /* Ptr to Queue manager name */ PMQCNO pConnectOpts; /* Ptr to Connection options */ PMQHCONN pHconn; /* Ptr to Connection handle */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_CONNX_EXIT (&ExitParms, &ExitContext, &pQMgrName, &pConnectOps, &pHconn, &CompCode, &Reason);Your exit must match the following C function prototype:
void MQENTRY MQ_CONNX_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PPMQCHAR ppQMgrName, /* Address of ptr to queue manager name */ PPMQCNO ppConnectOpts, /* Address of ptr to connection options */ PPMQHCONN ppHconn, /* Address of ptr to connection handle */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
The interface to this function is
MQ_DISC_EXIT (&ExitParms, &ExitContext, &pHconn, &CompCode, &Reason);where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- pHconn (PMQHCONN) - input
- Pointer to the connection handle.
For the before MQDISC call, the value of this field is one of:
- The connection handle returned on the MQCONN or MQCONNX call
- Zero, for environments where an environment-specific adapter has connected to the queue manager
- A value set by a previous exit function invocation
For the after MQDISC call, the value of this field is zero or a value set by a previous exit function invocation.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ PMQHCONN pHconn; /* Ptr to Connection handle */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_DISC_EXIT (&ExitParms, &ExitContext, &pHconn, &CompCode, &Reason);Your exit must match the following C function prototype:
void MQENTRY MQ_DISC_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PPMQHCONN ppHconn, /* Address of ptr to connection handle */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
Get - MQ_GET_EXIT
MQ_GET_EXIT provides a get exit function to perform before and after MQGET call processing. There are two function identifiers:
- Use MQXF_GET with exit reasons MQXR_BEFORE and MQXR_AFTER to register before and after MQGET call exit functions.
- Use MQXF_DATA_CONV_ON_GET with exit reason MQXR_BEFORE to register a before MQGET data conversion exit function. This is invoked only if the MQGMO_CONVERT option is included in the MQGET call.
The interface to this function is:
MQ_GET_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &pMsgDesc, &pGetMsgOpts, &BufferLength, &pBuffer, &pDataLength, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- Hobj (MQHOBJ) - input/output
- Object handle.
- pMsgDesc (PMQMD) - input/output
- Pointer to message descriptor.
- pGetMsgOpts (PMQPMO) - input/output
- Pointer to get message options.
- BufferLength (MQLONG) - input/output
- Message buffer length.
- pBuffer (PMQBYTE) - input/output
- Pointer to message buffer.
- pDataLength (PMQLONG) - input/output
- Pointer to data length field.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ MQHOBJ Hobj; /* Object handle */ PMQMD pMsgDesc; /* Ptr to message descriptor */ PMQPMO pGetMsgOpts; /* Ptr to get message options */ MQLONG BufferLength; /* Message buffer length */ PMQBYTE pBuffer; /* Ptr to message buffer */ PMQLONG pDataLength; /* Ptr to data length field */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_GET_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &pMsgDesc, &pGetMsgOpts, &BufferLength, &pBuffer, &pDataLength, &CompCode, &Reason)Your exit must match the following C function prototype:
void MQENTRY MQ_GET_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PMQHOBJ pHobj, /* Address of object handle */ PPMQMD ppMsgDesc, /* Address of ptr to message descriptor */ PPMQGMO ppGetMsgOpts, /* Address of ptr to get message options */ PMQLONG pBufferLength, /* Address of message buffer length */ PPMQBYTE ppBuffer, /* Address of ptr to message buffer */ PPMQLONG ppDataLength, /* Address of ptr to data length field */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
Initialization - MQ_INIT_EXIT
MQ_INIT_EXIT provides connection level initialization, indicated by setting ExitReason in MQAXP to MQXR_CONNECTION. During the initialization, note the following:
- The MQ_INIT_EXIT function calls MQXEP to register the WebSphere MQ API verbs and the ENTRY and EXIT points in which it is interested.
- Exits do not need to intercept all the WebSphere MQ API verbs. Exit functions are invoked only if an interest has been registered.
- Storage that is to be used by the exit can be acquired while initializing it.
- If a call to this function fails, the MQCONN or MQCONNX call that invoked it also fails with a CompCode and Reason that depend on the value of the ExitResponse field in MQAXP.
- An MQ_INIT_EXIT exit must not issue WebSphere MQ API calls, as the correct environment has not been set up at this time.
- If an MQ_INIT_EXIT fails with MQXCC_FAILED, the queue manager returns from the MQCONN or MQCONNX call that called it with MQCC_FAILED and MQRC_API_EXIT_ERROR.
- If the queue manager encounters an error while initializing the API exit function execution environment before invoking the first MQ_INIT_EXIT, the queue manager returns from the MQCONN or MQCONNX call that invoked MQ_INIT_EXIT with MQCC_FAILED and MQRC_API_EXIT_INIT_ERROR.
The interface to MQ_INIT_EXIT is:
MQ_INIT_EXIT (&ExitParms, &ExitContext, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- CompCode (MQLONG) - input/output
- Pointer to completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Pointer to reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
The CompCode and Reason returned to the application depend on the value of the ExitResponse field in MQAXP.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_INIT_EXIT (&ExitParms, &ExitContext, &CompCode, &Reason)Your exit must match the following C function prototype:
void MQENTRY MQ_INIT_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
The interface to this function is:
MQ_INQ_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &SelectorCount, &pSelectors, &IntAttrCount, &pIntAttrs, &CharAttrLength, &pCharAttrs, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- Hobj (MQHOBJ) - input
- Object handle.
- SelectorCount (MQLONG) - input
- Count of selectors
- pSelectors (PMQLONG) - input/output
- Pointer to array of selector values.
- IntAttrCount (MQLONG) - input
- Count of integer attributes.
- pIntAttrs (PMQLONG) - input/output
- Pointer to array of integer attribute values.
- CharAttrLength (MQLONG) - input/output
- Character attributes array length.
- pCharAttrs (PMQCHAR) - input/output
- Pointer to character attributes array.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ MQHOBJ Hobj; /* Object handle */ MQLONG SelectorCount; /* Count of selectors */ PMQLONG pSelectors; /* Ptr to array of attribute selectors */ MQLONG IntAttrCount; /* Count of integer attributes */ PMQLONG pIntAttrs; /* Ptr to array of integer attributes */ MQLONG CharAttrLength; /* Length of char attributes array */ PMQCHAR pCharAttrs; /* Ptr to character attributes */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying completion code */The queue manager then logically calls the exit as follows:
MQ_INQ_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &SelectorCount, &pSelectors, &IntAttrCount, &pIntAttrs, &CharAttrLength, &pCharAttrs, &CompCode, &Reason)Your exit must match the following C function prototype:
void MQENTRY MQ_INQ_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PMQHOBJ pHobj, /* Address of object handle */ PMQLONG pSelectorCount, /* Address of selector count */ PPMQLONG ppSelectors, /* Address of ptr to array of selectors */ PMQLONG pIntAttrCount; /* Address of count of integer attributes */ PPMQLONG ppIntAttrs, /* Address of ptr to array of integer attributes */ PMQLONG pCharAttrLength, /* Address of character attribute length */ PPMQCHAR ppCharAttrs, /* Address of ptr to character attributes array */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
The interface to this function is
MQ_OPEN_EXIT (&ExitParms, &ExitContext, &Hconn, &pObjDesc, &Options, &pHobj, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- pObjDesc (PMQOD) - input/output
- Pointer to object descriptor.
- Options (MQLONG) - input/output
- Open options.
- pHobj (PMQHOBJ) - input
- Pointer to object handle.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ PMQOD pObjDesc; /* Ptr to object descriptor */ MQLONG Options; /* Open options */ PMQHOBJ pHobj; /* Ptr to object handle */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_OPEN_EXIT (&ExitParms, &ExitContext, &Hconn, &pObjDesc, &Options, &pHobj, &CompCode, &Reason);Your exit must match the following C function prototype:
void MQENTRY MQ_OPEN_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PPMQOD ppObjDesc, /* Address of ptr to object descriptor */ PMQLONG pOptions, /* Address of open options */ PPMQHOBJ ppHobj, /* Address of ptr to object handle */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
The interface to this function is:
MQ_PUT_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &pMsgDesc, &pPutMsgOpts, &BufferLength, &pBuffer, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- Hobj (MQHOBJ) - input/output
- Object handle.
- pMsgDesc (PMQMD) - input/output
- Pointer to message descriptor.
- pPutMsgOpts (PMQPMO) - input/output
- Pointer to put message options.
- BufferLength (MQLONG) - input/output
- Message buffer length.
- pBuffer (PMQBYTE) - input/output
- Pointer to message buffer.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ MQHOBJ Hobj; /* Object handle */ PMQMD pMsgDesc; /* Ptr to message descriptor */ PMQPMO pPutMsgOpts; /* Ptr to put message options */ MQLONG BufferLength; /* Message buffer length */ PMQBYTE pBuffer; /* Ptr to message data */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_PUT_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &pMsgDesc, &pPutMsgOpts, &BufferLength, &pBuffer, &CompCode, &Reason)Your exit must match the following C function prototype:
void MQENTRY MQ_PUT_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PMQHOBJ pHobj, /* Address of object handle */ PPMQMD ppMsgDesc, /* Address of ptr to message descriptor */ PPMQPMO ppPutMsgOpts, /* Address of ptr to put message options */ PMQLONG pBufferLength, /* Address of message buffer length */ PPMQBYTE ppBuffer, /* Address of ptr to message buffer */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
Put1 - MQ_PUT1_EXIT
MQ_PUT1_EXIT provides a put one 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.
The interface to this function is:
MQ_PUT1_EXIT (&ExitParms, &ExitContext, &Hconn, &pObjDesc, &pMsgDesc, &pPutMsgOpts, &BufferLength, &pBuffer, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- pObjDesc (PMQOD) - input/output
- Pointer to object descriptor.
- pMsgDesc (PMQMD) - input/output
- Pointer to message descriptor.
- pPutMsgOpts (PMQPMO) - input/output
- Pointer to put message options.
- BufferLength (MQLONG) - input/output
- Message buffer length.
- pBuffer (PMQBYTE) - input/output
- Pointer to message buffer.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ PMQOD pObjDesc; /* Ptr to object descriptor */ PMQMD pMsgDesc; /* Ptr to message descriptor */ PMQPMO pPutMsgOpts; /* Ptr to put message options */ MQLONG BufferLength; /* Message buffer length */ PMQBYTE pBuffer; /* Ptr to message data */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_PUT1_EXIT (&ExitParms, &ExitContext, &Hconn, &pObjDesc, &pMsgDesc, &pPutMsgOpts, &BufferLength, &pBuffer, &CompCode, &Reason)Your exit must match the following C function prototype:
void MQENTRY MQ_PUT1_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PPMQOD ppObjDesc, /* Address of ptr to object descriptor */ PPMQMD ppMsgDesc, /* Address of ptr to message descriptor */ PPMQPMO ppPutMsgOpts, /* Address of ptr to put message options */ PMQLONG pBufferLength, /* Address of message buffer length */ PPMQBYTE ppBuffer, /* Address of ptr to message buffer */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
Set - MQ_SET_EXIT
MQ_SET_EXIT provides an inquire 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.
The interface to this function is:
MQ_SET_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &SelectorCount, &pSelectors, &IntAttrCount, &pIntAttrs, &CharAttrLength, &pCharAttr, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- Hconn (MQHCONN) - input
- Connection handle.
- Hobj (MQHOBJ) - input
- Object handle.
- SelectorCount (MQLONG) - input
- Count of selectors
- pSelectors (PMQLONG) - input/output
- Pointer to array of selector values.
- IntAttrCount (MQLONG) - input
- Count of integer attributes.
- pIntAttrs (PMQLONG) - input/output
- Pointer to array of integer attribute values.
- CharAttrLength (MQLONG) - input/output
- Character attributes array length.
- pCharAttrs (PMQCHAR) - input/output
- Pointer to character attribute values.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Partial completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED or MQCC_WARNING, the exit function can set the reason code field to any valid MQRC_* value.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQHCONN Hconn; /* Connection handle */ MQHOBJ Hobj; /* Object handle */ MQLONG SelectorCount; /* Count of selectors */ PMQLONG pSelectors; /* Ptr to array of attribute selectors */ MQLONG IntAttrCount; /* Count of integer attributes */ PMQLONG pIntAttrs; /* Ptr to array of integer attributes */ MQLONG CharAttrLength; /* Length of char attributes array */ PMQCHAR pCharAttrs; /* Ptr to character attributes */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying completion code */The queue manager then logically calls the exit as follows:
MQ_SET_EXIT (&ExitParms, &ExitContext, &Hconn, &Hobj, &SelectorCount, &pSelectors, &IntAttrCount, &pIntAttrs, &CharAttrLength, &pCharAttrs, &CompCode, &Reason)Your exit must match the following C function prototype:
void MQENTRY MQ_SET_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQHCONN pHconn, /* Address of connection handle */ PMQHOBJ pHobj, /* Address of object handle */ PMQLONG pSelectorCount, /* Address of selector count */ PPMQLONG ppSelectors, /* Address of ptr to array of selectors */ PMQLONG pIntAttrCount; /* Address of count of integer attributes */ PPMQLONG ppIntAttrs, /* Address of ptr to array of integer attributes */ PMQLONG pCharAttrLength, /* Address of character attribute length */ PPMQCHAR ppCharAttrs, /* Address of ptr to character attributes array */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
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.
As part of the termination, storage no longer required by the exit can be released, and any clean up required can be performed.
If an MQ_TERM_EXIT fails with MQXCC_FAILED, the queue manager returns from the MQDISC that called it with MQCC_FAILED and MQRC_API_EXIT_ERROR.
If the queue manager encounters an error while terminating the API exit function execution environment after invoking the last MQ_TERM_EXIT, the queue manager returns from the MQDISC call that invoked MQ_TERM_EXIT with MQCC_FAILED and MQRC_API_EXIT_TERM_ERROR
The interface to this function is:
MQ_TERM_EXIT (&ExitParms, &ExitContext, &CompCode, &Reason)where the parameters are:
- ExitParms (MQAXP) - input/output
- Exit parameter structure.
- ExitContext (MQAXC) - input/output
- Exit context structure.
- CompCode (MQLONG) - input/output
- Completion code, valid values for which are:
- MQCC_OK
- Successful completion.
- MQCC_FAILED
- Call failed
- Reason (MQLONG) - input/output
- Reason code qualifying the completion code.
If the completion code is MQCC_OK, the only valid value is:
- MQRC_NONE
- (0, x'000') No reason to report.
If the completion code is MQCC_FAILED, the exit function can set the reason code field to any valid MQRC_* value.
The CompCode and Reason returned to the application depend on the value of the ExitResponse field in MQAXP.
C language invocation
The queue manager logically defines the following variables:
MQAXP ExitParms; /* Exit parameter structure */ MQAXC ExitContext; /* Exit context structure */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code */The queue manager then logically calls the exit as follows:
MQ_TERM_EXIT (&ExitParms, &ExitContext, &CompCode, &Reason)Your exit must match the following C function prototype:
void MQENTRY MQ_TERM_EXIT ( PMQAXP pExitParms, /* Address of exit parameter structure */ PMQAXC pExitContext, /* Address of exit context structure */ PMQLONG pCompCode, /* Address of completion code */ PMQLONG pReason); /* Address of reason code qualifying completion code */
General information on invoking exit functions
This section provides some general guidance to help you 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 <-- endThe 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 11. API exit errors and appropriate actions to take
ErrPt Description Actions e1 Error during exit execution environment setup.
- Undo environment setup as required
- Drive no exit functions
- Fail MQCONN with MQCC_FAILED, MQRC_API_EXIT_LOAD_ERROR
e2 MQ_INIT_EXIT function completes with:
- MQXCC_FAILED
- MQXCC_*
- For MQXCC_FAILED:
- Clean up environment
- Fail MQCONN with MQCC_FAILED, MQRC_API_EXIT_INIT_ERROR
- For MQXCC_*
- Act as for the values of MQXCC_* and MQXR2_*1
- Clean up environment
e3 Before MQ_CONNX_EXIT 1 function completes with:
- MQXCC_FAILED
- MQXCC_*
- For MQXCC_FAILED:
- Drive MQ_TERM_EXIT function
- Clean up environment
- Fail MQCONN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
- For MQXCC_*
- Act as for the values of MQXCC_* and MQXR2_*1
- Drive MQ_TERM_EXIT function if required
- Clean up environment if required
e4 Before MQ_CONNX_EXIT 2 function completes with:
- MQXCC_FAILED
- MQXCC_*
- For MQXCC_FAILED:
- Drive after MQ_CONNX_EXIT 1 function
- Drive MQ_TERM_EXIT function
- Clean up environment
- Fail MQCONN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
- For MQXCC_*
- Act as for the values of MQXCC_* and MQXR2_*1
- Drive after MQ_CONNX_EXIT 1 function if exit not suppressed
- Drive MQ_TERM_EXIT function if required
- Clean up environment if required
e5 MQCONN call fails.
- Pass MQCONN CompCode and Reason
- Drive after MQ_CONNX_EXIT 2 function if the before MQ_CONNX_EXIT 2 succeeded and the exit is not suppressed
- Drive after MQ_CONNX_EXIT 1 function if the before MQ_CONNX_EXIT 1 succeeded and the exit is not suppressed
- Drive MQ_TERM_EXIT function
- Clean up environment
e6 After MQ_CONNX_EXIT 2 function completes with:
- MQXCC_FAILED
- MQXCC_*
- For MQXCC_FAILED:
- Drive after MQ_CONNX_EXIT 1 function
- Complete MQCONN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
- For MQXCC_*
- Act as for the values of MQXCC_* and MQXR2_*1
- 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:
- Drive after MQ_OPEN_EXIT 1 function
- 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
- Pass MQOPEN CompCode and Reason
- Drive after MQ_OPEN_EXIT 2 function if exit not suppressed
- 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:
- Drive after MQ_OPEN_EXIT 1 function
- Complete MQOPEN call with MQCC_FAILED, MQRC_API_EXIT_ERROR
- For MQXCC_*
- Act as for the values of MQXCC_* and MQXR2_*1
- 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:
- Drive after MQ_DISC_EXIT 1 function
- Drive MQ_TERM_EXIT function
- Clean up exit execution environment
- Complete MQDISC call with MQCC_FAILED, MQRC_API_EXIT_ERROR
- For MQXCC_*
- Act as for the values of MQXCC_* and MQXR2_*1
- Drive MQ_TERM_EXIT function
- Clean up exit execution environment
Notes:
- 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:
- For a before MQCONN or MQDISC API exit function:
- The ExitResponse2 value is ignored.
- No further before exit functions in the exit chain (if any) are invoked; the API call itself is not issued.
- For any before exits that were successfully called, the after exits are called in reverse order.
- If registered, the termination exit functions for those before MQCONN or MQDISC exit functions in the chain that were successfully invoked are driven to clean up after these exit functions.
- The MQCONN or MQDISC call fails with MQRC_API_EXIT_ERROR.
- For a before WebSphere MQ API exit function other than MQCONN or MQDISC:
- The ExitResponse2 value is ignored.
- No further before or after data conversion functions in the exit chain (if any) are invoked.
- For any before exits that were successfully called, the after exits are called in reverse order.
- The WebSphere MQ API call itself is not issued.
- The WebSphere MQ API call fails with MQRC_API_EXIT_ERROR.
- For an after MQCONN or MQDISC API exit function:
- The ExitResponse2 value is ignored.
- The remaining exit functions which were successfully called before the API call are called in reverse order.
- If registered, the termination exit functions for those before or after MQCONN or MQDISC exit functions in the chain that were successfully invoked are driven to clean up after the exit.
- A CompCode of the more severe of MQCC_WARNING and the CompCode returned by the exit is returned to the application.
- A Reason of MQRC_API_EXIT_ERROR is returned to the application.
- The WebSphere MQ API call is successfully issued.
- For an after WebSphere MQ API call exit function other than MQCONN or MQDISC:
- The ExitResponse2 value is ignored.
- The remaining exit functions which were successfully called before the API call are called in reverse order.
- A CompCode of the more severe of MQCC_WARNING and the CompCode returned by the exit is returned to the application.
- A Reason of MQRC_API_EXIT_ERROR is returned to the application.
- The WebSphere MQ API call is successfully issued.
- For the before data conversion on get exit function:
- The ExitResponse2 value is ignored.
- The remaining exit functions which were successfully called before the API call are called in reverse order.
- The message is not converted, and the unconverted message is returned to the application.
- A CompCode of the more severe of MQCC_WARNING and the CompCode returned by the exit is returned to the application.
- A Reason of MQRC_API_EXIT_ERROR is returned to the application.
- The WebSphere MQ API call is successfully issued.
- Note:
- As the error is with the exit, it is better to return MQRC_API_EXIT_ERROR than to return MQRC_NOT_CONVERTED.
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.
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.