The MQDXP structure contains the following fields; the fields are described in alphabetic order:
Application options.
This is a copy of the GMOPT field of the MQGMO structure specified by the application issuing the MQGET call. The exit may need to examine these to ascertain whether the GMATM option was specified.
This is an input field to the exit.
Completion code.
When the exit is invoked, this contains the completion code that will be returned to the application that issued the MQGET call, if the exit chooses to do nothing. It is always CCWARN, 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 CMPCOD parameter of the MQGET call; only CCOK and CCWARN are valid. See the description of the DXREA field for recommendations on how the exit should set this field on output.
This is an input/output field to the exit.
Character set required by application.
This is the coded character-set identifier of the character set required by the application issuing the MQGET call; see the MDCSI field in the MQMD structure for more details. If the application specifies the special value CSQM 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 should copy this to the MDCSI field in the message descriptor.
This is an input field to the exit.
Numeric encoding required by application.
This is the numeric encoding required by the application issuing the MQGET call; see the MDENC field in the MQMD structure for more details.
If the conversion is successful, the exit should copy this to the MDENC field in the message descriptor.
This is an input field to 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.
Length in bytes of message data.
When the exit is invoked, this field contains the original length of the application message data. If the message was truncated in order 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 DXLEN. The size of the message actually provided to the exit is always given by the INLEN parameter of the exit, irrespective of any truncation that may have occurred.
Truncation is indicated by the DXREA field having the value RC2079 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 DATLEN 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 DXLEN is always greater then zero.
This is an input/output field to the exit.
Reason code qualifying DXCC.
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 RC2079, indicating that the message was truncated in order fit into the buffer provided by the application, and RC2119, 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 DXCC field is not CCOK, the application which retrieves the message can identify a conversion failure by comparing the returned MDENC and MDCSI 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, RC2079 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 GMATM 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 RC* codes if deemed appropriate. In addition, the range of values RC0900 through RC0999 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.
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 MDENC and MDCSI fields in the exit's message descriptor parameter are both unchanged, the queue manager returns:
If one or both of the MDENC and MDCSI 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 INBUF, the results are undefined.
DXRES is an output field from the exit.
Structure identifier.
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.
Reserved.
This is a reserved field; its value is 0.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
amqwak02216 |