The MQAXP structure describes the information that is passed to an API exit.
This structure is supported in the following environments: AIX, HP-UX, Solaris, Windows.
The MQAXP structure contains the following fields:
Structure identifier.
For the C programming language, the constant MQAXP_STRUC_ID_ARRAY is also defined; this has the same value as MQAXP_STRUC_ID, but is an array of characters instead of a string.
This is an input field to the exit.
Structure version number.
The following constant specifies the version number of the current version:
| Note: | When a new version of the MQAXP structure is introduced, the layout of the existing part is not changed. The exit should therefore check that the version number is equal to or greater than the lowest version which contains the fields that the exit needs to use. |
This is an input field to the exit.
Type of exit.
This indicates the type of exit being called. The value is:
This is an input field to the exit.
Reason for invoking exit.
This indicates the reason why the exit is being called. Possible values are:
The exit is invoked with this value twice for each connection:
The MQXF_INIT exit function should be used for general initialization of the exit suite, and the MQXF_CONN or MQXF_CONNX exit functions should be used specifically for processing the MQCONN or MQCONNX calls.
The MQXF_TERM exit function should be used for general termination of the exit suite, and the MQXF_DISC exit function should be used specifically for processing the MQDISC call.
The Function field can have any of the MQXF_* values other than MQXF_INIT or MQXF_TERM.
For the MQGET call, this value occurs with the:
The Function field can have any of the MQXF_* values other than MQXF_INIT, MQXF_TERM, or MQXF_DATA_CONV_ON_GET.
For the MQGET call, this value occurs with the:
This is an input field to the exit.
Response from exit.
This is set by the exit function to indicate the outcome of the processing performed by the exit. It must be one of the following:
This value can be set by all MQXR_* exit functions. The ExitResponse2 field must be set by the exit function to indicate how processing should continue.
| Note: | Returning MQXCC_OK does not imply that the completion code for the API call is MQCC_OK, or that the reason code is MQRC_NONE. |
This value can be set by all MQXR_* exit functions. It
causes the queue manager to set the completion code for the API call to
MQCC_FAILED, and the reason code to one of the following values:
| Exit function | Reason code set by queue manager |
|---|---|
| MQXF_INIT | MQRC_API_EXIT_INIT_ERROR |
| MQXF_TERM | MQRC_API_EXIT_TERM_ERROR |
| All others | MQRC_API_EXIT_ERROR |
However, the values set by the queue manager can be altered by an exit function later in the chain.
The ExitResponse2 field is ignored; the queue manager continues processing as though MQXR2_SUPPRESS_CHAIN had been returned:
If an MQXR_BEFORE exit function returns this value, the queue manager sets the completion code for the API call to MQCC_FAILED, the reason code to MQRC_SUPPRESSED_BY_EXIT, and the API call is skipped. If returned by the MQXF_DATA_CONV_ON_GET exit function, data conversion is skipped.
The ExitResponse2 field must be set by the exit function to indicate whether the remaining MQXR_BEFORE exit functions and their matching MQXR_AFTER exit functions should be invoked. Any of these exit functions can alter the completion code and reason code of the API call that were set by the queue manager.
If an MQXR_AFTER or MQXR_CONNECTION exit function returns this value, the queue manager continues processing as though the exit had returned MQXCC_FAILED.
This is the same as MQXCC_SUPPRESS_FUNCTION, except the exit function can set the completion code and reason code of the API call.
If an MQXR_BEFORE or MQXR_AFTER exit function returns this value, the queue manager deregisters immediately all of the exit functions belonging to this exit suite. The only exception is the MQXF_TERM exit function, which will be invoked at termination of the connection if registered when MQXCC_SUPPRESS_EXIT is returned. Note that if an MQXR_BEFORE exit function returns this value, the matching MQXR_AFTER exit function will not be invoked after the API call, since that exit function will no longer be registered.
The ExitResponse2 field must be set by the exit function to indicate whether the remaining MQXR_BEFORE exit functions and their matching MQXR_AFTER exit functions should be invoked.
If an MQXR_CONNECTION exit function returns this value, the queue manager continues processing as though the exit had returned MQXCC_FAILED.
If the exit function sets ExitResponse to a value that is not valid, the queue manager continues processing as though the exit had returned MQXCC_FAILED.
On entry to the exit function, ExitResponse has the value MQXCC_OK.
This is an output field from the exit.
Secondary response from exit.
This is the secondary exit response code that can be set by an MQXR_BEFORE exit function to provide additional information to the queue manager. If set by an MQXR_AFTER or MQXR_CONNECTION exit function, the value is ignored. The value must be one of the following:
Continuation with the next exit function in the chain depends on the value of the ExitResponse field:
All subsequent MQXR_BEFORE exit functions in the chain, and their matching MQXR_AFTER exit functions, are skipped for this particular API call. The MQXR_AFTER exit functions that match the current exit function and earlier MQXR_BEFORE exit functions are not skipped.
If the exit function sets ExitResponse2 to a value that is not valid, the queue manager continues processing as though the exit had returned MQXR2_DEFAULT_CONTINUATION.
This is an output field from the exit.
Feedback.
This is a field that allows the exit functions belonging to an exit suite to communicate feedback codes both to each other, and to exit functions belonging to other exit suites. The field is initialized to MQFB_NONE before the first invocation of the first exit function in the first exit suite (the MQXF_INIT exit function), and thereafter any changes made to this field by exit functions are preserved across the invocations of the exit functions.
This is an input/output field to the exit.
API caller type.
This indicates the type of program that issued the API call that caused the exit function to be invoked. The value is one of the following:
This is an input field to the exit.
Exit user area.
This is a field that allows exit functions belonging to the same exit suite to share data with each other, but not with other exit suites. The field is initialized to MQXUA_NONE (binary zero) before the first invocation of the first exit function in the exit suite (the MQXF_INIT exit function), and thereafter any changes made to this field by exit functions are preserved across the invocations of the exit functions. The queue manager resets the field to MQXUA_NONE when control returns from the MQXF_TERM exit function to the queue manager.
The following value is defined:
The value is binary zero for the length of the field.
For the C programming language, the constant MQXUA_NONE_ARRAY is also defined; this has the same value as MQXUA_NONE, but is an array of characters instead of a string.
The length of this field is given by MQ_EXIT_USER_AREA_LENGTH. This is an input/output field to the exit.
Exit data.
On input to each exit function, this field is set to the character data associated with the definition of the exit suite to which the exit function belongs. If no value has been defined for that data, ExitData is blank.
The length of this field is given by MQ_EXIT_DATA_LENGTH. This is an input field to the exit.
Exit information name.
This is a name that is used to identify the exit suite to which the exit function belongs.
The length of this field is given by MQ_EXIT_INFO_NAME_LENGTH. This is an input field to the exit.
Problem determination area.
This is a field that is available for the exit to use, to assist with problem determination. The field is initialized to MQXPDA_NONE (binary zero) before each invocation of the exit function. The exit function can set this field to any value it chooses. When the exit returns control to the queue manager, the contents of ExitPDArea are written to the trace file, if tracing is active.
The following value is defined:
The value is binary zero for the length of the field.
For the C programming language, the constant MQXPDA_NONE_ARRAY is also defined; this has the same value as MQXPDA_NONE, but is an array of characters instead of a string.
The length of this field is given by MQ_EXIT_PD_AREA_LENGTH. This is an input/output field to the exit.
Name of local queue manager.
This is the name of the queue manager that invoked the exit function. QMgrName is never blank.
The length of this field is given by MQ_Q_MGR_NAME_LENGTH. This is an input field to the exit.
Address of first MQACH structure in chain.
The exit chain area allows exit functions belonging to one exit suite to share data with exit functions belonging to another exit suite. The exit chain area is a chain of MQACH structures that is made available to all exit functions. The address of the first MQACH structure in the chain is passed to each exit function in the ExitChainAreaPtr field. The exit function can scan the chain, and examine or alter the data contained within it. However, this should be done only with the prior agreement of the owner of the data.
If there is no current exit chain area, ExitChainAreaPtr is the NULL pointer. An exit function can at any time create an MQACH structure in storage obtained dynamically (for example, by using the C function malloc), and add it to the chain. The exit suite which creates an MQACH is responsible for freeing the storage associated with the MQACH before the exit suite terminates.
If data is to be shared between different exit functions belonging to the same exit suite, but that data is not to be made available to other exit suites, the ExitUserArea field should be used in preference to ExitChainAreaPtr.
This is an input/output field to the exit.
Configuration handle.
This handle represents the set of exit functions that belong to the exit suite whose name is given by the ExitInfoName field. The queue manager generates a new configuration handle when the MQXF_INIT exit function is invoked, and passes that handle to the other exit functions that belong to the exit suite. This handle must be specified on the MQXEP call in order to register the entry point for an exit function.
This is an input field to the exit.
API function identifier.
This is the identifier of the API call that is about to be executed (when ExitReason has the value MQXR_BEFORE), or the API call that has just been executed (when ExitReason has the value MQXR_AFTER). If ExitReason has the value MQXR_CONNECTION, Function indicates whether the exit should perform initialization or termination. The value is one of the following:
This is an input field to the exit.
typedef struct tagMQAXP MQAXP;
struct tagMQAXP {
MQCHAR4 StrucId; /* Structure identifier */
MQLONG Version; /* Structure version number */
MQLONG ExitId; /* Type of exit */
MQLONG ExitReason; /* Reason for invoking exit */
MQLONG ExitResponse; /* Response from exit */
MQLONG ExitResponse2; /* Secondary response from exit */
MQLONG Feedback; /* Feedback */
MQLONG APICallerType; /* API caller type */
MQBYTE16 ExitUserArea; /* Exit user area */
MQCHAR32 ExitData; /* Exit data */
MQCHAR48 ExitInfoName; /* Exit information name */
MQBYTE48 ExitPDArea; /* Problem determination area */
MQCHAR48 QMgrName; /* Name of local queue manager */
PMQACH ExitChainAreaPtr; /* Address of first MQACH structure in
chain */
MQHCONFIG Hconfig; /* Configuration handle */
MQLONG Function; /* API function identifier */
};