MQDXP - Data-conversion exit parameter

The MQDXP structure is a parameter that the queue manager passes to the data-conversion exit when the exit is invoked to convert the message data as part of the processing of the MQGET call. See the description of the MQ_DATA_CONV_EXIT call for details of the data conversion exit.

Character data in MQDXP is in the character set of the local queue manager; this is given by the CodedCharSetId queue manager attribute. Numeric data in MQDXP is in the native machine encoding; this is given by MQENC_NATIVE.

Only the DataLength, CompCode, Reason, and ExitResponse fields in MQDXP can be changed by the exit; changes to other fields are ignored. However, the DataLength field cannot be changed if the message being converted is a segment that contains only part of a logical message.

When control returns to the queue manager from the exit, the queue manager checks the values returned in MQDXP. If the values returned are not valid, the queue manager continues processing as though the exit had returned MQXDR_CONVERSION_FAILED in ExitResponse ; however, the queue manager ignores the values of the CompCode and Reason fields returned by the exit in this case, and uses instead the values those fields had on input to the exit. The following values in MQDXP cause this processing to occur:

ExitResponse field not MQXDR_OK and not MQXDR_CONVERSION_FAILED
CompCode field not MQCC_OK and not MQCC_WARNING
DataLength field less than zero, or DataLength field changed when the message being converted is a segment that contains only part of a logical message.

The following table summarizes the fields in the structure.

Table 1. Fields in MQDXP
Field	Description	Topic
StrucId	Structure identifier	StrucId
Version	Structure version number	Version
AppOptions	Application options	AppOptions
Encoding	Numeric encoding required by application	Encoding
CodedCharSetId	Character set required by application	CodedCharSetId
DataLength	Length in bytes of message data	DataLength
CompCode	Completion code	CompCode
Reason	Reason code qualifying CompCode	Reason
ExitResponse	Response from exit	ExitResponse
Hconn	Connection handle	Hconn
pEntryPoints	Address of the MQIEP structure	pEntryPoints

Fields

The MQDXP structure contains the following fields; the fields are described in alphabetical order.

AppOptions

Type: 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

Type: 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

Type: 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 does 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 suggestions on how the exit can set this field on output.

This is an input/output field to the exit.

DataLength

Type: 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 is smaller than the value of DataLength. The size of the message provided to the exit is always given by the InBufferLength parameter of the exit, irrespective of any truncation that has occurred.

Truncation is indicated by the Reason field having the value MQRC_TRUNCATED_MSG_ACCEPTED on input to the exit.

Most conversions do 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 fits 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

Type: 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 copies this to the Encoding field in the message descriptor.

This is an input field to the exit.

ExitOptions

Type: MQLONG

This is a reserved field; its value is 0.

ExitResponse

Type: 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

Type: MQHCONN

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.

pEntryPoints

Type: PMQIEP

The address of an MQIEP structure through which MQI and DCI calls can be made.

Reason

Type: MQLONG

Reason code qualifying CompCode.

When the exit is invoked, this contains the reason code that is 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 must 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 fitted the buffer. For this reason, MQRC_TRUNCATED_MSG_ACCEPTED must 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 must 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 must be set to MQCC_WARNING (or left unchanged), and Reason set to one of the values listed, to indicate the nature of the failure. Note if the message after conversion is too large for the buffer, it must 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 is returned.
  - If it did not specify that option, the message is returned unconverted, with reason code MQRC_CONVERTED_MSG_TOO_BIG.

The reason codes listed 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 wants 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 large 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

Type: 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.

Version

Type: MQLONG Structure version number. The value must be:

MQDXP_VERSION_1: Version number 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 must therefore check that the Version field 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.

C declaration

typedef struct tagMQDXP MQDXP;
struct tagMQDXP {
  MQCHAR4  StrucId;         /* Structure identifier */
  MQLONG   Version;         /* Structure version number */
  MQLONG   ExitOptions;     /* Reserved */
  MQLONG   AppOptions;      /* Application options */
  MQLONG   Encoding;        /* Numeric encoding required by
                               application */
  MQLONG   CodedCharSetId;  /* Character set required by application */
  MQLONG   DataLength;      /* Length in bytes of message data */
  MQLONG   CompCode;        /* Completion code */
  MQLONG   Reason;          /* Reason code qualifying CompCode */
  MQLONG   ExitResponse;    /* Response from exit */
  MQHCONN  Hconn;           /* Connection handle */
  PMQIEP   pEntryPoints;    /* Address of the MQIEP structure */
};

COBOL declaration ( IBM® i only)

**   MQDXP structure
  10 MQDXP.
**    Structure identifier
   15 MQDXP-STRUCID        PIC X(4).
**    Structure version number
   15 MQDXP-VERSION        PIC S9(9) BINARY.
**    Reserved
   15 MQDXP-EXITOPTIONS    PIC S9(9) BINARY.
**    Application options
   15 MQDXP-APPOPTIONS     PIC S9(9) BINARY.
**    Numeric encoding required by application
   15 MQDXP-ENCODING       PIC S9(9) BINARY.
**    Character set required by application
   15 MQDXP-CODEDCHARSETID PIC S9(9) BINARY.
**    Length in bytes of message data
   15 MQDXP-DATALENGTH     PIC S9(9) BINARY.
**    Completion code
   15 MQDXP-COMPCODE       PIC S9(9) BINARY.
**    Reason code qualifying COMPCODE
   15 MQDXP-REASON         PIC S9(9) BINARY.
**    Response from exit
   15 MQDXP-EXITRESPONSE   PIC S9(9) BINARY.
**    Connection handle
   15 MQDXP-HCONN          PIC S9(9) BINARY.

System/390 assembler declaration

MQDXP                 DSECT
MQDXP_STRUCID         DS   CL4  Structure identifier
MQDXP_VERSION         DS   F    Structure version number
MQDXP_EXITOPTIONS     DS   F    Reserved
MQDXP_APPOPTIONS      DS   F    Application options
MQDXP_ENCODING        DS   F    Numeric encoding required by application
MQDXP_CODEDCHARSETID  DS   F    Character set required by application
MQDXP_DATALENGTH      DS   F    Length in bytes of message data
MQDXP_COMPCODE        DS   F    Completion code
MQDXP_REASON          DS   F    Reason code qualifying COMPCODE
MQDXP_EXITRESPONSE    DS   F    Response from exit
MQDXP_HCONN           DS   F    Connection handle
*
MQDXP_LENGTH          EQU  *-MQDXP
                      ORG  MQDXP
MQDXP_AREA            DS   CL(MQDXP_LENGTH)