Fields

StrucId (MQCHAR4)

Structure identifier.

The value must be:

MQCXP_STRUC_ID
Identifier for channel exit parameter structure.

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.

Version (MQLONG)

Structure version number.

The value depends on the environment:

MQCXP_VERSION_1
Version-1 channel exit parameter structure.
MQCXP_VERSION_2
Version-2 channel exit parameter structure.

The field has this value in the following environments: HP OpenVMS, Compaq NonStop Kernel.

MQCXP_VERSION_3
Version-3 channel exit parameter structure.

The field has this value in the following environments: UNIX systems not listed elsewhere.

MQCXP_VERSION_4
Version-4 channel exit parameter structure.
MQCXP_VERSION_5
Version-5 channel exit parameter structure.
MQCXP_VERSION_6
Version-6 channel exit parameter structure.

The field has this value in the following environments: z/OS(R), AIX, HP-UX, Linux, i5/OS, Solaris, Windows(R).

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:

MQCXP_CURRENT_VERSION
Current version of channel exit parameter structure.

The value of this constant depends on the environment (see above).

Note:
When a new version of the MQCXP 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, and is set on entry to the exit routine. Possible values are:

MQXT_CHANNEL_SEC_EXIT
Channel security exit.
MQXT_CHANNEL_MSG_EXIT
Channel message exit.
MQXT_CHANNEL_SEND_EXIT
Channel send exit.
MQXT_CHANNEL_RCV_EXIT
Channel receive exit.
MQXT_CHANNEL_MSG_RETRY_EXIT
Channel message-retry exit.
MQXT_CHANNEL_AUTO_DEF_EXIT
Channel auto-definition exit.

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.

ExitReason (MQLONG)

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:

MQXR_INIT
Exit initialization.

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).

MQXR_TERM
Exit termination.

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).

MQXR_MSG
Process a message.

This indicates that the exit is being invoked to process a message. This occurs for channel message exits only.

MQXR_XMIT
Process a transmission.

This occurs for channel send and receive exits only.

MQXR_SEC_MSG
Security message received.

This occurs for channel security exits only.

MQXR_INIT_SEC
Initiate security exchange.

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.

MQXR_RETRY
Retry a message.

This occurs for message-retry exits only.

MQXR_AUTO_CLUSSDR
Automatic definition of a cluster-sender channel.

This occurs for channel auto-definition exits only.

MQXR_AUTO_RECEIVER
Automatic definition of a receiver channel.

This occurs for channel auto-definition exits only.

MQXR_AUTO_SVRCONN
Automatic definition of a server-connection channel.

This occurs for channel auto-definition exits only.

MQXR_AUTO_CLUSRCVR
Automatic definition of a cluster-receiver channel.

This occurs for channel auto-definition exits only.

MQXR_SEC_PARMS
Security parameters

This applies to security exits only and indicates that an MQCSP structure is being passed to the exit.

Notes:
  1. If you have more than one exit defined for a channel, they will each be invoked with MQXR_INIT when the MCA is initialized, and will each be invoked with MQXR_TERM when the MCA is terminated.
  2. For the channel auto-definition exit, ExitReason is not set if Version is less than MQCXP_VERSION_4. The value MQXR_AUTO_SVRCONN is implied in this case.

This is an input field to the exit.

ExitResponse (MQLONG)

Response from exit.

This is set by the exit to communicate with the MCA. It must be one of the following:

MQXCC_OK
Exit completed successfully.

The ExitResponse2 field may contain additional information.

MQXCC_SUPPRESS_FUNCTION
Suppress function.

This response is not supported for the channel send and receive exits.

MQXCC_SEND_SEC_MSG
Send security message.

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.

MQXCC_SEND_AND_REQUEST_SEC_MSG
Send security message that requires a reply.

This value can be set only by a channel security exit. It indicates

MQXCC_SUPPRESS_EXIT
Suppress exit.

MQXCC_CLOSE_CHANNEL
Close channel.

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 an input/output field from the exit.

ExitResponse2 (MQLONG)

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.

MQXR2_PUT_WITH_DEF_ACTION
Put with default action.

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.

MQXR2_PUT_WITH_DEF_USERID
Put with 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 MCA's default user identifier.

MQXR2_PUT_WITH_MSG_USERID
Put with message's 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.

MQXR2_USE_AGENT_BUFFER
Use agent buffer.

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.

MQXR2_USE_EXIT_BUFFER
Use exit buffer.

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.

MQXR2_DEFAULT_CONTINUATION
Default continuation.

Continuation with the next exit in the chain depends on the response from the last exit invoked:

MQXR2_CONTINUE_CHAIN
Continue with the next exit.
MQXR2_SUPPRESS_CHAIN
Skip remaining exits in chain.

This is an input/output field to the exit.

Feedback (MQLONG)

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:

MQFB_STOPPED_BY_MSG_EXIT
Message stopped by channel message exit.

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.

MaxSegmentLength (MQLONG)

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.

ExitUserArea (MQBYTE16)

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:

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.

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.

MsgRetryCount (MQLONG)

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.

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.

MsgRetryInterval (MQLONG)

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.

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.

MsgRetryReason (MQLONG)

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.

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.

HeaderLength (MQLONG)

Length of header information.

This field is relevant only for a message exit and a message-retry exit. The value is the length of the routing header structures at the start of the message data; these are the MQXQH structure, the MQMDE (message description extension header), 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.

PartnerName (MQCHAR48)

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.

FAPLevel (MQLONG)

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.

CapabilityFlags (MQLONG)

Capability flags.

The following are defined:

MQCF_NONE
No flags.
MQCF_DIST_LISTS
Distribution lists supported.

This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_3.

ExitNumber (MQLONG)

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.

ExitSpace (MQLONG)

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.

The value is always zero on z/OS.

Note:
This facility should not be used to send large amounts of data, as this may degrade performance, or even inhibit operation of the channel.

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.

SSLCertUserId (MQCHAR12)

This field specifies the UserId associated with the remote certificate. It is blank on all platforms except z/OS

This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_6.

SSLRemCertIssNameLength (MQLONG)

This field contains length in bytes of the full Distinguished Name of the issuer of the remote certificate pointed to by SSLCertRemoteIssuerNamePtr.

This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_6.

SSLRemCertIssNamePtr (PMQVOID)

This field contains the address of the full Distinguished Name of the issuer of the remote certificate. Its value is the null pointer if the channel is not SSL.

This is an input field to the exit. The field is not present if Version is less than MQCXP_VERSION_6.

SecurityParms (PMQCSP)

Address of the MQCSP structure used to specify a user ID and password. The initial value of this field is the null pointer.

This is an input/output field to the exit. The field is not present if Version is less than MQCXP_VERSION_6.

CurHdrCompression (MQLONG)

Current header data compression.

This field specifies which technique is currently being used to compress the header data.

It is set to one of the following:

MQCOMPRESS_NONE
No header data compression is performed.
MQCOMPRESS_SYSTEM
Header data compression is performed.

The value can be altered by a sending channel's message exit to one of the negotiated supported values accessed from the HdrCompList field of the MQCD. This enables the technique used to compress the header data to be decided for each message based on the content of the message. The altered value is used for the current message only. The channel ends if the attribute is altered to an unsupported value. The value is ignored if altered outside a sending channel's message exit.

This is an input/output field to the exit. The field is not present if Version is less than MQCXP_VERSION_6.

CurMsgCompression (MQLONG)

Current message compression.

This field specifies which technique is currently being used to compress the message data.

It is set to one of the following:

MQCOMPRESS_NONE
No header data compression is performed.
MQCOMPRESS_RLE
Message data compression is performed using run-length encoding.
MQCOMPRESS_ZLIBFAST
Message data compression is performed using the zlib compression technique. A fast compression time is preferred.
MQCOMPRESS_ZLIBHIGH
Message data compression is performed using the zlib compression technique. A high level of compression is preferred.

The value can be altered by a sending channel's message exit to one of the negotiated supported values accessed from the MsgCompList field of the MQCD. This enables the technique used to compress the message data to be decided for each message based on the content of the message. The altered value is used for the current message only. The channel ends if the attribute is altered to an unsupported value. The value is ignored if altered outside a sending channel's message exit.

This is an input/output field to the exit. The field is not present if Version is less than MQCXP_VERSION_6.