Home

 

Fields

The MQDXP structure contains the following fields; the fields are described in alphabetic order:

 

AppOptions (MQLONG)

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.

 

CodedCharSetId (MQLONG)

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.

 

CompCode (MQLONG)

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.

 

DataLength (MQLONG)

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.

 

Encoding (MQLONG)

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.

 

ExitOptions (MQLONG)

Reserved.

This is a reserved field; its value is

0.

 

ExitResponse (MQLONG)

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:

MQXDR_OK

Conversion was successful.

If the exit specifies this value, the queue manager returns the following to the application that issued the MQGET call:

• The value of the CompCode field on output from the exit

• The value of the Reason field on output from the exit

• The value of the DataLength field on output from the exit

• The contents of the exit's output buffer OutBuffer. The number of bytes returned is the lesser of the exit's OutBufferLength parameter, and the value of the DataLength field on output from the exit.

  If the Encoding and CodedCharSetId fields in the exit's message descriptor parameter are both unchanged, the queue manager returns:

• The value of the Encoding and CodedCharSetId fields in the MQDXP structure on input to the exit.

  If one or both of the Encoding and CodedCharSetId fields in the exit's message descriptor parameter has been changed, the queue manager returns:

• The value of the Encoding and CodedCharSetId fields in the exit's message descriptor parameter on output from the exit

MQXDR_CONVERSION_FAILED

Conversion was unsuccessful.

If the exit specifies this value, the queue manager returns the following to the application that issued the MQGET call:

• The value of the CompCode field on output from the exit

• The value of the Reason field on output from the exit

• The value of the DataLength field on input to the exit

• The contents of the exit's input buffer InBuffer. The number of bytes returned is given by the InBufferLength parameter

If the exit has altered InBuffer, the results are undefined.

ExitResponse is an output field from the exit.

 

Hconn (MQHCONN)

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 (MQLONG)

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 Reason had the value MQRC_TRUNCATED_MSG_ACCEPTED on input to the exit, the Reason and CompCode fields should not be altered, irrespective of whether the conversion succeeds or fails.

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

• If Reason had any other value on input to the exit:

  • If the conversion succeeds, CompCode should be set to MQCC_OK and Reason set to MQRC_NONE.

  • If the conversion fails, or the message expands and has to be truncated to fit in the buffer, CompCode should be set to MQCC_WARNING (or left unchanged), and Reason set to one of the values listed below, to indicate the nature of the 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:

    • If it did specify that option, reason MQRC_TRUNCATED_MSG_ACCEPTED should be returned.

    • If it did not specify that option, the message should be returned unconverted, with reason code MQRC_CONVERTED_MSG_TOO_BIG.

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.

Note:

If the message cannot be converted successfully, the exit must return MQXDR_CONVERSION_FAILED in the ExitResponse field, in order to cause the queue manager to return the unconverted message. This is true regardless of the reason code returned in the Reason field.

MQRC_APPL_FIRST

(900, X'384') Lowest value for application-defined reason code.

MQRC_APPL_LAST

(999, X'3E7') Highest value for application-defined reason code.

MQRC_CONVERTED_MSG_TOO_BIG

(2120, X'848') Converted data too big for buffer.

MQRC_NOT_CONVERTED

(2119, X'847') Message data not converted.

MQRC_SOURCE_CCSID_ERROR

(2111, X'83F') Source coded character set identifier not valid.

MQRC_SOURCE_DECIMAL_ENC_ERROR

(2113, X'841') Packed-decimal encoding in message not recognized.

MQRC_SOURCE_FLOAT_ENC_ERROR

(2114, X'842') Floating-point encoding in message not recognized.

MQRC_SOURCE_INTEGER_ENC_ERROR

(2112, X'840') Source integer encoding not recognized.

MQRC_TARGET_CCSID_ERROR

(2115, X'843') Target coded character set identifier not valid.

MQRC_TARGET_DECIMAL_ENC_ERROR

(2117, X'845') Packed-decimal encoding specified by receiver not recognized.

MQRC_TARGET_FLOAT_ENC_ERROR

(2118, X'846') Floating-point encoding specified by receiver not recognized.

MQRC_TARGET_INTEGER_ENC_ERROR

(2116, X'844') Target integer encoding not recognized.

MQRC_TRUNCATED_MSG_ACCEPTED

(2079, X'81F') Truncated message returned (processing completed).

This is an input/output field to the exit.

 

StrucId (MQCHAR4)

Structure identifier.

The value must be:

MQDXP_STRUC_ID

Identifier for data conversion exit parameter structure.

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.

 

V(MQLONG)

Structure version number.

The value must be:

MQDXP_VERSION_1

Vnumber for data-conversion exit parameter structure.

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

MQDXP_CURRENT_VERSION

Current version of data-conversion exit parameter structure.

Note:

When a new version of this structure is introduced, the layout of the existing part is not changed. The exit should therefore check that the Vfield 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.

 

Home