The MQDXP structure contains the following fields; the fields are described in alphabetic order:
This is a copy of the Options field of the MQGMO structure specified by the application issuing the MQGET call. The exit might need to examine these to ascertain whether the MQGMO_ACCEPT_TRUNCATED_MSG option was specified.
This is an input field to the exit.
This is the coded character-set identifier of the character set required by the application issuing the MQGET call; see the CodedCharSetId field in the MQMD structure for more details. If the application specifies the special value MQCCSI_Q_MGR on the MQGET call, the queue manager changes this to the actual character-set identifier of the character set used by the queue manager, before invoking the exit.
If the conversion is successful, the exit must copy this to the CodedCharSetId field in the message descriptor.
This is an input field to the exit.
When the exit is invoked, this contains the completion code that is returned to the application that issued the MQGET call, if the exit chooses to do nothing. It is always MQCC_WARNING, because either the message was truncated, or the message requires conversion and this has not yet been done.
On output from the exit, this field contains the completion code to be returned to the application in the CompCode parameter of the MQGET call; only MQCC_OK and MQCC_WARNING are valid. See the description of the Reason field for recommendations on how the exit should set this field on output.
This is an input/output field to the exit.
When the exit is invoked, this field contains the original length of the application message data. If the message was truncated to fit into the buffer provided by the application, the size of the message provided to the exit will be smaller than the value of DataLength. The size of the message actually provided to the exit is always given by the InBufferLength parameter of the exit, irrespective of any truncation that may have occurred.
Truncation is indicated by the Reason field having the value MQRC_TRUNCATED_MSG_ACCEPTED on input to the exit.
Most conversions will not need to change this length, but an exit can do so if necessary; the value set by the exit is returned to the application in the DataLength parameter of the MQGET call. However, this length cannot be changed if the message being converted is a segment that contains only part of a logical message. This is because changing the length would cause the offsets of later segments in the logical message to be incorrect.
Note that, if the exit wants to change the length of the data, be aware that the queue manager has already decided whether the message data will fit into the application's buffer, based on the length of the unconverted data. This decision determines whether the message is removed from the queue (or the browse cursor moved, for a browse request), and is not affected by any change to the data length caused by the conversion. For this reason it is recommended that conversion exits do not cause a change in the length of the application message data.
If character conversion does imply a change of length, a string can be converted into another string with the same length in bytes, truncating trailing blanks or padding with blanks as necessary.
The exit is not invoked if the message contains no application message data; hence DataLength is always greater then zero.
This is an input/output field to the exit.
Numeric encoding required by application.
This is the numeric encoding required by the application issuing the MQGET call; see the Encoding field in the MQMD structure for more details.
If the conversion is successful, the exit should copy this to the Encoding field in the message descriptor.
This is an input field to the exit.
Reserved.
This is a reserved field; its value is 0.
Response from exit.
This is set by the exit to indicate the success or otherwise of the conversion. It must be one of the following:
If the exit specifies this value, the queue manager returns the following to the application that issued the MQGET call:
If the Encoding and CodedCharSetId fields in the exit's message descriptor parameter are both unchanged, the queue manager returns:
If one or both of the Encoding and CodedCharSetId fields in the exit's message descriptor parameter has been changed, the queue manager returns:
If the exit specifies this value, the queue manager returns the following to the application that issued the MQGET call:
If the exit has altered InBuffer, the results are undefined.
ExitResponse is an output field from the exit.
Connection handle.
This is a connection handle which can be used on the MQXCNVC call. This handle is not necessarily the same as the handle specified by the application which issued the MQGET call.
Reason code qualifying CompCode.
When the exit is invoked, this contains the reason code that will be returned to the application that issued the MQGET call, if the exit chooses to do nothing. Among possible values are MQRC_TRUNCATED_MSG_ACCEPTED, indicating that the message was truncated in order fit into the buffer provided by the application, and MQRC_NOT_CONVERTED, indicating that the message requires conversion but that this has not yet been done.
On output from the exit, this field contains the reason to be returned to the application in the Reason parameter of the MQGET call; the following is recommended:
(If the CompCode field is not MQCC_OK, the application which retrieves the message can identify a conversion failure by comparing the returned Encoding and CodedCharSetId values in the message descriptor with the values requested; in contrast, the application cannot distinguish a truncated message from a message that just fitted the buffer. For this reason, MQRC_TRUNCATED_MSG_ACCEPTED should be returned in preference to any of the reasons that indicate conversion failure.)
Note that, if the message after conversion is too big for the buffer, it should be truncated only if the application that issued the MQGET call specified the MQGMO_ACCEPT_TRUNCATED_MSG option:
The reason codes listed below are recommended for use by the exit to indicate the reason that conversion failed, but the exit can return other values from the set of MQRC_* codes if deemed appropriate. In addition, the range of values MQRC_APPL_FIRST through MQRC_APPL_LAST are allocated for use by the exit to indicate conditions that the exit wishes to communicate to the application issuing the MQGET call.
This is an input/output field to the exit.
Structure identifier.
For the C programming language, the constant MQDXP_STRUC_ID_ARRAY is also defined; this has the same value as MQDXP_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:
This is an input field to the exit.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
csqzak10383 |