MQAXP - API exit parameter

MQAXP - API exit parameter

The MQAXP structure describes the information that is passed to an API exit.

Fields

The MQAXP structure contains the following fields:

StrucId (MQCHAR4)

Structure identifier.
The value is:

MQAXP_STRUC_ID

Identifier for API exit parameter structure.
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.

Version (MQLONG)

Structure version number.
The value is:

MQAXP_VERSION_1

Version-1 API exit parameter structure.

The following constant specifies the version number of the current version:

MQAXP_CURRENT_VERSION

Current version of API exit parameter structure.

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.

ExitId (MQLONG)

Type of exit.
This indicates the type of exit being called. The value is:

MQXT_API_EXIT

API exit.

This is an input field to the exit.

ExitReason (MQLONG)

Reason for invoking exit.
This indicates the reason why the exit is being called. Possible values are:

MQXR_CONNECTION

Connection level processing.
The exit is invoked with this value twice for each connection:

Before the MQCONN or MQCONNX call, so that the exit can perform connection-level initialization. The Function field has the value MQXF_INIT in this case.
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.
After the MQDISC call, so that the exit can perform connection-level termination. The Function field has the value MQXF_TERM in this case.
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.

MQXR_BEFORE

Before API execution.
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:

MQXF_GET exit function before API execution
MQXF_DATA_CONV_ON_GET exit function after API execution but before data conversion

MQXR_AFTER

After API execution.
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:

MQXF_GET exit function after both API execution and data conversion have been completed

This is an input field to the exit.

ExitResponse (MQLONG)

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:

MQXCC_OK

Exit completed successfully.
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.

MQXCC_FAILED

Exit failed.
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:

For an MQXR_BEFORE exit function, processing continues with the MQXR_AFTER exit function that matches this MQXR_BEFORE exit function (that is, all intervening MQXR_BEFORE and MQXR_AFTER exit functions, plus the API call itself, are skipped).
For an MQXR_AFTER exit function, processing continues with the next MQXR_AFTER exit function in the chain.

MQXCC_SUPPRESS_FUNCTION

Suppress function.
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.

MQXCC_SKIP_FUNCTION

Skip function.
This is the same as MQXCC_SUPPRESS_FUNCTION, except the exit function can set the completion code and reason code of the API call.

MQXCC_SUPPRESS_EXIT

Suppress exit.
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.

ExitResponse2 (MQLONG)

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:

MQXR2_DEFAULT_CONTINUATION

Default continuation.
Continuation with the next exit function in the chain depends on the value of the ExitResponse field:

If ExitResponse is MQXCC_OK or MQXCC_SUPPRESS_EXIT, the next MQXR_BEFORE exit function in the chain is invoked.
If ExitResponse is MQXCC_SUPPRESS_FUNCTION or MQXCC_SKIP_FUNCTION, no further MQXR_BEFORE exit functions are invoked for this particular API call.

MQXR2_CONTINUE_CHAIN

Continue with next MQXR_BEFORE exit function in chain.

MQXR2_SUPPRESS_CHAIN

Skip remaining MQXR_BEFORE exit functions in chain.
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 (MQLONG)

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.

APICallerType (MQLONG)

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:

MQXACT_EXTERNAL

Caller is external to the queue manager.

MQXACT_INTERNAL

Caller is internal to the queue manager.

This is an input field to the exit.

ExitUserArea (MQBYTE16)

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:

MQXUA_NONE

No user information.
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.

ExitData (MQCHAR32)

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.

ExitInfoName (MQCHAR48)

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.

ExitPDArea (MQBYTE48)

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:

MQXPDA_NONE

No problem-determination information.
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.

queue_manager (MQCHAR48)

Name of local queue manager.
Name of the queue manager that invoked the exit function. queue_manager is never blank.
The length of this field is given by MQ_Q_MGR_NAME_LENGTH. This is an input field to the exit.

ExitChainAreaPtr (PMQACH)

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.

Hconfig (MQHCONFIG)

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.

Function (MQLONG)

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:

MQXF_INIT

Initialization of exit suite.

MQXF_TERM

Termination of exit suite.

MQXF_CONN

MQCONN call.

MQXF_CONNX

MQCONNX call.

MQXF_DISC

MQDISC call.

MQXF_OPEN

MQOPEN call.

MQXF_CLOSE

MQCLOSE call.

MQXF_PUT1

MQPUT1 call.

MQXF_PUT

MQPUT call.

MQXF_GET

MQGET call.

MQXF_DATA_CONV_ON_GET

Data conversion on MQGET call.

MQXF_INQ

MQINQ call.

MQXF_SET

MQSET call.

MQXF_BEGIN

MQBEGIN call.

MQXF_CMIT

MQCMIT call.

MQXF_BACK

MQBACK call.

This is an input field to the exit.

C declaration
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   queue_manager;          /* Name of local queue manager */
  PMQACH     ExitChainAreaPtr;  /* Address of first MQACH structure in
                                   chain */
  MQHCONFIG  Hconfig;           /* Configuration handle */
  MQLONG     Function;          /* API function identifier */
};

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