The MQCXP structure is passed to each type of exit called by a Message Channel Agent (MCA). See MQ_CHANNEL_EXIT .
The fields described as "input to the exit" in the descriptions that follow are ignored by the MCA when the exit returns control to the MCA. The exit should not expect that any input fields that it changes in the channel exit parameter block will be preserved for its next invocation. Changes made to input/output fields (for example, the ExitUserArea field), are preserved for invocations of that instance of the exit only. Such changes cannot be used to pass data between different exits defined on the same channel, or between the same exit defined on different channels.
Structure identifier.
For the C programming language, the constant MQCXP_STRUC_ID_ARRAY is also defined; this has the same value as MQCXP_STRUC_ID, but is an array of characters instead of a string.
This is an input field to the exit.
Structure version number.
The value depends on the environment:
The field has this value on z/OS using CICS for distributed queuing.
The field has this value in the following environments: Compaq OpenVMS Alpha, Compaq NonStop Kernel.
The field has this value in the following environments: UNIX systems not listed elsewhere.
The field has this value in the following environments: z/OS not using CICS for distributed queuing, OS/2.
The field has this value in the following environments: AIX, HP-UX, Linux, iSeries, Solaris, WIndows.
Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions of the fields. The following constant specifies the version number of the current version:
The value of this constant depends on the environment (see above).
This is an input field to the exit.
Type of exit.
This indicates the type of exit being called, and is set on entry to the exit routine. Possible values are:
This type of exit is not supported on: z/OS.
On z/OS, this type of exit is supported only for channels of type MQCHT_CLUSSDR and MQCHT_CLUSRCVR.
This is an input field to the exit.
Reason for invoking exit.
This indicates the reason why the exit is being called, and is set on entry to the exit routine. It is not used by the auto-definition exit. Possible values are:
This indicates that the exit is being invoked for the first time. It allows the exit to acquire and initialize any resources that it may need (for example: main storage).
This indicates that the exit is about to be terminated. The exit should free any resources that it may have acquired since it was initialized (for example: main storage).
This indicates that the exit is being invoked to process a message. This occurs for channel message exits only.
This occurs for channel send and receive exits only.
This occurs for channel security exits only.
This occurs for channel security exits only.
The receiver's security exit is always invoked with this reason immediately after being invoked with MQXR_INIT, to give it the opportunity to initiate a security exchange. If it declines the opportunity (by returning MQXCC_OK instead of MQXCC_SEND_SEC_MSG or MQXCC_SEND_AND_REQUEST_SEC_MSG), the sender's security exit is invoked with MQXR_INIT_SEC.
If the receiver's security exit does initiate a security exchange (by returning MQXCC_SEND_SEC_MSG or MQXCC_SEND_AND_REQUEST_SEC_MSG), the sender's security exit is never invoked with MQXR_INIT_SEC; instead it is invoked with MQXR_SEC_MSG to process the receiver's message. (In either case it is first invoked with MQXR_INIT.)
Unless one of the security exits requests termination of the channel (by setting ExitResponse to MQXCC_SUPPRESS_FUNCTION or MQXCC_CLOSE_CHANNEL), the security exchange must complete at the side that initiated the exchange. Therefore, if a security exit is invoked with MQXR_INIT_SEC and it does initiate an exchange, the next time the exit is invoked it will be with MQXR_SEC_MSG. This happens whether or not there is a security message for the exit to process. There will be a security message if the partner returns MQXCC_SEND_SEC_MSG or MQXCC_SEND_AND_REQUEST_SEC_MSG, but not if the partner returns MQXCC_OK or there is no security exit at the partner. If there is no security message to process, the security exit at the initiating end is re-invoked with a DataLength of zero.
This occurs for message-retry exits only.
On z/OS, this is not supported.
This occurs for channel auto-definition exits only.
This occurs for channel auto-definition exits only.
This occurs for channel auto-definition exits only.
This occurs for channel auto-definition exits only.
Notes:
This is an input field to the exit.
Response from exit.
This is set by the exit to communicate with the MCA. It must be one of the following:
The ExitResponse2 field may contain additional information.
For persistent messages, if the sender specified MQRO_DEAD_LETTER_Q, but the put to the dead-letter queue fails, or there is no dead-letter queue, the original message is left on the transmission queue and the report message is not generated. The original message is also left on the transmission queue if the report message cannot be generated successfully.
The Feedback field in the MQDLH structure at the start of the message on the dead-letter queue indicates why the message was put on the dead-letter queue; this feedback code is also used in the message descriptor of the exception report message (if one was requested by the sender).
This response is not supported for the channel send and receive exits.
This value can be set only by a channel security exit. It indicates that the exit has provided a security message which should be transmitted to the partner.
This value can be set only by a channel security exit. It indicates
This is not valid on z/OS if you are using CICS for distributed queuing.
This is not valid on z/OS if you are using CICS for distributed queuing.
This value can be set by any type of channel exit except an auto-definition exit. It causes the message channel agent (MCA) to close the channel.
This is not valid on z/OS if you are using CICS for distributed queuing.
This is an input/output field from the exit.
Secondary response from exit.
This is set to zero on entry to the exit routine. It can be set by the exit to provide further information to the MCA. It is not used by the auto-definition exit.
The exit can set one or more of the following. If more than one is required, the values are added together. Combinations that are not valid are noted; other combinations are allowed.
This is set by the receiver's channel message exit. It indicates that the message is to be put with the MCA's default action, that is either the MCA's default user ID, or the context UserIdentifier in the MQMD (message descriptor) of the message.
The value of this constant is zero, which corresponds to the initial value set when the exit is invoked. The constant is provided for documentation purposes.
This can only be set by the receiver's channel message exit. It indicates that the message is to be put with the MCA's default user identifier.
This can only be set by the receiver's channel message exit. It indicates that the message is to be put with the context UserIdentifier in the MQMD (message descriptor) of the message (this may have been modified by the exit).
Only one of MQXR2_PUT_WITH_DEF_ACTION, MQXR2_PUT_WITH_DEF_USERID, and MQXR2_PUT_WITH_MSG_USERID should be set.
This indicates that any data to be passed on is in AgentBuffer, not ExitBufferAddr.
The value of this constant is zero, which corresponds to the initial value set when the exit is invoked. The constant is provided for documentation purposes.
This indicates that any data to be passed on is in ExitBufferAddr, not AgentBuffer.
Only one of MQXR2_USE_AGENT_BUFFER and MQXR2_USE_EXIT_BUFFER should be set.
Continuation with the next exit in the chain depends on the response from the last exit invoked:
This is an input/output field to the exit.
Feedback code.
This is set to MQFB_NONE on entry to the exit routine.
If a channel message exit sets the ExitResponse field to MQXCC_SUPPRESS_FUNCTION, the Feedback field specifies the feedback code that identifies why the message was put on the dead-letter (undelivered-message) queue, and is also used to send an exception report if one has been requested. In this case, if the Feedback field is MQFB_NONE, the following feedback code is used:
The value returned in this field by channel security, send, receive, and message-retry exits is not used by the MCA.
The value returned in this field by auto-definition exits is not used if ExitResponse is MQXCC_OK, but otherwise is used for the AuxErrorDataInt1 parameter in the event message.
This is an input/output field from the exit.
Maximum segment length.
This is the maximum length in bytes that can be sent in a single transmission. It is not used by the auto-definition exit. It is of interest to a channel send exit, because this exit must ensure that it does not increase the size of a transmission segment to a value greater than MaxSegmentLength. The length includes the initial 8 bytes that the exit must not change. The value is negotiated between the message channel agents when the channel is initiated. See Writing and compiling channel-exit programs for more information about segment lengths.
The value in this field is not meaningful if ExitReason is MQXR_INIT.
This is an input field to the exit.
Exit user area.
This is a field that is available for the exit to use. (It is not used by the auto-definition exit.) It is initialized to binary zero before the first invocation of the exit (which has an ExitReason set to MQXR_INIT), and thereafter any changes made to this field by the exit are preserved across invocations of the exit.
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.
This is set on entry to the exit routine to information that the MCA took from the channel definition. If no such information is available, this field is all blanks.
The length of this field is given by MQ_EXIT_DATA_LENGTH.
This is an input field to the exit.
The following fields in this structure are not present if Version is less than MQCXP_VERSION_2.
Number of times the message has been retried.
The first time the exit is invoked for a particular message, this field has the value zero (no retries yet attempted). On each subsequent invocation of the exit for that message, the value is incremented by one by the MCA. On z/OS, the value is always zero.
This is an input field to the exit. The value in this field is not meaningful if ExitReason is MQXR_INIT. The field is not present if Version is less than MQCXP_VERSION_2.
Minimum interval in milliseconds after which the put operation should be retried.
The first time the exit is invoked for a particular message, this field contains the value of the MsgRetryInterval channel attribute. The exit can leave the value unchanged, or modify it to specify a different time interval in milliseconds. If the exit returns MQXCC_OK in ExitResponse, the MCA will wait for at least this time interval before retrying the MQOPEN or MQPUT operation. The time interval specified must be zero or greater.
The second and subsequent times the exit is invoked for that message, this field contains the value returned by the previous invocation of the exit.
If the value returned in the MsgRetryInterval field is less than zero or greater than 999 999 999, and ExitResponse is MQXCC_OK, the MCA ignores the MsgRetryInterval field in MQCXP and waits instead for the interval specified by the MsgRetryInterval channel attribute. On z/OS, the value of this field is always zero.
This is an input/output field to the exit. The value in this field is not meaningful if ExitReason is MQXR_INIT. The field is not present if Version is less than MQCXP_VERSION_2.
Reason code from previous attempt to put the message.
This is the reason code from the previous attempt to put the message; it is one of the MQRC_* values. On z/OS the value of this field is always zero.
This is an input field to the exit. The value in this field is not meaningful if ExitReason is MQXR_INIT. The field is not present if Version is less than MQCXP_VERSION_2.
The following fields in this structure are not present if Version is less than MQCXP_VERSION_3.
Length of header information.
This field is relevant only for a message exit. The value is the length of the routing header structures at the start of the message data; these are the MQXQH structure, and (for a distribution-list message) the MQDH structure and arrays of MQOR and MQPMR records that follow the MQXQH structure.
The message exit can examine this header information, and modify it if necessary, but the data that the exit returns must still be in the correct format. The exit must not, for example, encrypt or compress the header data at the sending end, even if the message exit at the receiving end makes compensating changes.
If the message exit modifies the header information in such a way as to change its length (for example, by adding another destination to a distribution-list message), it must change the value of HeaderLength correspondingly before returning.
This is an input/output field to the exit. The value in this field is not meaningful if ExitReason is MQXR_INIT. The field is not present if Version is less than MQCXP_VERSION_3.
Partner Name.
The name of the partner, as follows:
When the exit is initialized this field is blank because the queue manager does not know the name of the partner until after initial negotiation has taken place.
This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_3.
Negotiated Formats and Protocols level.
This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_3.
Capability flags.
This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_3.
Exit number.
The ordinal number of the exit, within the type defined in ExitId. For example, if the exit being invoked is the third message exit defined, this field contains the value 3. If the exit type is one for which a list of exits cannot be defined (for example, a security exit), this field has the value 1.
This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_3.
The following fields in this structure are not present if Version is less than MQCXP_VERSION_5.
Number of bytes in transmission buffer reserved for exit to use.
This field is relevant only for a send exit. It specifies the amount of space in bytes that the MCA will reserve in the transmission buffer for the exit to use. This allows the exit to add to the transmission buffer a small amount of data (typically not exceeding a few hundred bytes) for use by a complementary receive exit at the other end. The data added by the send exit must be removed by the receive exit.
By setting ExitSpace the exit is guaranteed that there will always be at least that number of bytes available in the transmission buffer for the exit to use. However, the exit can use less than the amount reserved, or more than the amount reserved if there is space available in the transmission buffer. The exit space in the buffer is provided following the existing data.
ExitSpace can be set by the exit only when ExitReason has the value MQXR_INIT; in all other cases the value returned by the exit is ignored. On input to the exit, ExitSpace is zero for the MQXR_INIT call, and is the value returned by the MQXR_INIT call in other cases.
If the value returned by the MQXR_INIT call is negative, or there are fewer than 1024 bytes available in the transmission buffer for message data after reserving the requested exit space for all of the send exits in the chain, the MCA outputs an error message and closes the channel. Similarly, if during data transfer the exits in the send exit chain allocate more user space than they reserved such that fewer than 1024 bytes remain in the transmission buffer for message data, the MCA outputs an error message and closes the channel. The limit of 1024 allows the channel's control and administrative flows to be processed by the chain of send exits, without the need for the flows to be segmented.
This is an input/output field to the exit if ExitReason is MQXR_INIT, and an input field in all other cases. The field is not present if Version is less than MQCXP_VERSION_5.
typedef struct tagMQCXP MQCXP;
struct tagMQCXP {
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 code */
MQLONG MaxSegmentLength; /* Maximum segment length */
MQBYTE16 ExitUserArea; /* Exit user area */
MQCHAR32 ExitData; /* Exit data */
MQLONG MsgRetryCount; /* Number of times the message has been
retried */
MQLONG MsgRetryInterval; /* Minimum interval in milliseconds after
which the put operation should be
retried */
MQLONG MsgRetryReason; /* Reason code from previous attempt to
put the message */
MQLONG HeaderLength; /* Length of header information */
MQCHAR48 PartnerName; /* Partner Name */
MQLONG FAPLevel; /* Negotiated Formats and Protocols
level */
MQLONG CapabilityFlags; /* Capability flags */
MQLONG ExitNumber; /* Exit number */
MQLONG ExitSpace; /* Number of bytes in transmission buffer
reserved for exit to use */
};
** MQCXP structure 10 MQCXP. ** Structure identifier 15 MQCXP-STRUCID PIC X(4). ** Structure version number 15 MQCXP-VERSION PIC S9(9) BINARY. ** Type of exit 15 MQCXP-EXITID PIC S9(9) BINARY. ** Reason for invoking exit 15 MQCXP-EXITREASON PIC S9(9) BINARY. ** Response from exit 15 MQCXP-EXITRESPONSE PIC S9(9) BINARY. ** Secondary response from exit 15 MQCXP-EXITRESPONSE2 PIC S9(9) BINARY. ** Feedback code 15 MQCXP-FEEDBACK PIC S9(9) BINARY. ** Maximum segment length 15 MQCXP-MAXSEGMENTLENGTH PIC S9(9) BINARY. ** Exit user area 15 MQCXP-EXITUSERAREA PIC X(16). ** Exit data 15 MQCXP-EXITDATA PIC X(32). ** Number of times the message has been retried 15 MQCXP-MSGRETRYCOUNT PIC S9(9) BINARY. ** Minimum interval in milliseconds after which the put operation ** should be retried 15 MQCXP-MSGRETRYINTERVAL PIC S9(9) BINARY. ** Reason code from previous attempt to put the message 15 MQCXP-MSGRETRYREASON PIC S9(9) BINARY. ** Length of header information 15 MQCXP-HEADERLENGTH PIC S9(9) BINARY. ** Partner Name 15 MQCXP-PARTNERNAME PIC X(48). ** Negotiated Formats and Protocols level 15 MQCXP-FAPLEVEL PIC S9(9) BINARY. ** Capability flags 15 MQCXP-CAPABILITYFLAGS PIC S9(9) BINARY. ** Exit number 15 MQCXP-EXITNUMBER PIC S9(9) BINARY. ** Number of bytes in transmission buffer reserved for exit to use 15 MQCXP-EXITSPACE PIC S9(9) BINARY.
dcl
1 MQCXP based,
3 StrucId char(4), /* Structure identifier */
3 Version fixed bin(31), /* Structure version number */
3 ExitId fixed bin(31), /* Type of exit */
3 ExitReason fixed bin(31), /* Reason for invoking exit */
3 ExitResponse fixed bin(31), /* Response from exit */
3 ExitResponse2 fixed bin(31), /* Secondary response from exit */
3 Feedback fixed bin(31), /* Feedback code */
3 MaxSegmentLength fixed bin(31), /* Maximum segment length */
3 ExitUserArea char(16), /* Exit user area */
3 ExitData char(32), /* Exit data */
3 MsgRetryCount fixed bin(31), /* Number of times the message has
been retried */
3 MsgRetryInterval fixed bin(31), /* Minimum interval in milliseconds
after which the put operation
should be retried */
3 MsgRetryReason fixed bin(31), /* Reason code from previous attempt
to put the message */
3 HeaderLength fixed bin(31), /* Length of header information */
3 PartnerName char(48), /* Partner Name */
3 FAPLevel fixed bin(31), /* Negotiated Formats and Protocols
level */
3 CapabilityFlags fixed bin(31), /* Capability flags */
3 ExitNumber fixed bin(31), /* Exit number */
3 ExitSpace fixed bin(31); /* Number of bytes in transmission
buffer reserved for exit to
use */
D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
D* MQCXP Structure
D*
D* Structure identifier
D CXSID 1 4
D* Structure version number
D CXVER 5 8I 0
D* Type of exit
D CXXID 9 12I 0
D* Reason for invoking exit
D CXREA 13 16I 0
D* Response from exit
D CXRES 17 20I 0
D* Secondary response from exit
D CXRE2 21 24I 0
D* Feedback code
D CXFB 25 28I 0
D* Maximum segment length
D CXMSL 29 32I 0
D* Exit user area
D CXUA 33 48
D* Exit data
D CXDAT 49 80
D* Number of times the message has been retried
D CXMRC 81 84I 0
D* Minimum interval in milliseconds after which the put operation
D* should be retried
D CXMRI 85 88I 0
D* Reason code from previous attempt to put the message
D CXMRR 89 92I 0
D* Length of header information
D CXHDL 93 96I 0
D* Partner Name
D CXPNM 97 144
D* Negotiated Formats and Protocols level
D CXFAP 145 148I 0
D* Capability flags
D CXCAP 149 152I 0
D* Exit number
D CXEXN 153 156I 0
D* Number of bytes in transmission buffer reserved for exit to use
D CXHDL 157 160I 0
I*..1....:....2....:....3....:....4....:....5....:....6....:....7..
I* MQCXP Structure
I*
I* Structure identifier
I 1 4 CXSID
I* Structure version number
I B 5 80CXVER
I* Type of exit
I B 9 120CXXID
I* Reason for invoking exit
I B 13 160CXREA
I* Response from exit
I B 17 200CXRES
I* Secondary response from exit
I B 21 240CXRE2
I* Feedback code
I B 25 280CXFB
I* Maximum segment length
I B 29 320CXMSL
I* Exit user area
I 33 48 CXUA
I* Exit data
I 49 80 CXDAT
I* Number of times the message has been retried
I B 81 840CXMRC
I* Minimum interval in milliseconds after which the put operation
I* should be retried
I B 85 880CXMRI
I* Reason code from previous attempt to put the message
I B 89 920CXMRR
I* Length of header information
I B 93 960CXHDL
I* Partner Name
I 97 144 CXPNM
I* Negotiated Formats and Protocols level
I B 145 1480CXFAP
I* Capability flags
I B 149 1520CXCAP
I* Exit number
I B 153 1560CXEXN
I* Number of bytes in transmission buffer reserved for exit to use
I B 157 1600CXHDL
MQCXP DSECT
MQCXP_STRUCID DS CL4 Structure identifier
MQCXP_VERSION DS F Structure version number
MQCXP_EXITID DS F Type of exit
MQCXP_EXITREASON DS F Reason for invoking exit
MQCXP_EXITRESPONSE DS F Response from exit
MQCXP_EXITRESPONSE2 DS F Secondary response from exit
MQCXP_FEEDBACK DS F Feedback code
MQCXP_MAXSEGMENTLENGTH DS F Maximum segment length
MQCXP_EXITUSERAREA DS XL16 Exit user area
MQCXP_EXITDATA DS CL32 Exit data
MQCXP_MSGRETRYCOUNT DS F Number of times the message has been
* retried
MQCXP_MSGRETRYINTERVAL DS F Minimum interval in milliseconds
* after which the put operation should
* be retried
MQCXP_MSGRETRYREASON DS F Reason code from previous attempt to
* put the message
MQCXP_HEADERLENGTH DS F Length of header information
MQCXP_PARTNERNAME DS CL48 Partner Name
MQCXP_FAPLEVEL DS F Negotiated Formats and Protocols
* level
MQCXP_CAPABILITYFLAGS DS F Capability flags
MQCXP_EXITNUMBER DS F Exit number
MQCXP_EXITSPACE DS F Number of bytes in transmission
* buffer reserved for exit to use
*
MQCXP_LENGTH EQU *-MQCXP
ORG MQCXP
MQCXP_AREA DS CL(MQCXP_LENGTH)