MQDXP (Data-conversion exit parameter) on IBM i

Data-conversion exit parameter block.

Overview

Purpose: 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 MQCONVX call for details of the data conversion exit.

Character set and encoding: 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 ENNAT.

Usage: Only the DXLEN, DXCC, DXREA and DXRES fields in MQDXP might be changed by the exit; changes to other fields are ignored. However, the DXLEN field cannot be changed if the message being converted is a segment that contains only part of a logical message.

• DXRES field not XROK and not XRFAIL
• DXCC field not CCOK and not CCWARN
• DXLEN field less than zero, or DXLEN field changed when the message being converted is a segment that contains only part of a logical message.

• Fields
• RPG declaration (copy file CMQDXPH)

Fields

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

DXAOP (10-digit signed integer)

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.

DXCC (10-digit signed integer)

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 suggestions on how the exit should set this field on output.

This is an input/output field to the exit.

DXCSI (10-digit signed integer)

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.

DXENC (10-digit signed integer)

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.

DXHCN (10-digit signed integer)

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.

DXLEN (10-digit signed integer)

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 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 than zero.

This is an input/output field to the exit.

DXREA (10-digit signed integer)

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

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

• If DXREA had any other value on input to the exit:
  • If the conversion succeeds, DXCC should be set to CCOK and DXREA set to RCNONE.
  • If the conversion fails, or the message expands and has to be truncated to fit in the buffer, DXCC should be set to CCWARN (or left unchanged), and DXREA set to one of the values i the following list, 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 GMATM option:
    • If it did specify that option, reason RC2079 should be returned.
    • If it did not specify that option, the message should be returned unconverted, with reason code RC2120.

The reason codes in the following list 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 wants to communicate to the application issuing the MQGET call.

Note: If the message cannot be converted successfully, the exit must return XRFAIL in the DXRES field, in order to cause the queue manager to return the unconverted message. This is true regardless of the reason code returned in the DXREA field.

RC0900

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

RC0999

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

RC2120

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

RC2119

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

RC2111

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

RC2113

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

RC2114

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

RC2112

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

RC2115

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

RC2117

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

RC2118

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

RC2116

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

RC2079

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

This is an input/output field to the exit.

DXRES (10-digit signed integer)

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:

XROK

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 DXCC field on output from the exit
• The value of the DXREA field on output from the exit
• The value of the DXLEN field on output from the exit
• The contents of the exit's output buffer OUTBUF. The number of bytes returned is the lesser of the exit's OUTLEN parameter, and the value of the DXLEN field on output from the exit

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

• The value of the MDENC and MDCSI fields in the MQDXP structure on input to the exit

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

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

XRFAIL

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 DXCC field on output from the exit
• The value of the DXREA field on output from the exit
• The value of the DXLEN field on input to the exit
• The contents of the exit's input buffer INBUF. The number of bytes returned is given by the INLEN parameter

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

DXRES is an output field from the exit.

DXSID (4-byte character string)

Structure identifier.

The value must be:

DXSIDV

Identifier for data conversion exit parameter structure.

This is an input field to the exit.

DXVER (10-digit signed integer)

Structure version number.

The value must be:

DXVER1

Version number for data-conversion exit parameter structure.

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

DXVERC

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

DXXOP (10-digit signed integer)

Reserved.

This is a reserved field; its value is 0.

RPG declaration (copy file CMQDXPH)

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQDXP Structure
     D*
     D* Structure identifier
     D  DXSID                  1      4
     D* Structure version number
     D  DXVER                  5      8I 0
     D* Reserved
     D  DXXOP                  9     12I 0
     D* Application options
     D  DXAOP                 13     16I 0
     D* Numeric encoding required by application
     D  DXENC                 17     20I 0
     D* Character set required by application
     D  DXCSI                 21     24I 0
     D* Length in bytes of message data
     D  DXLEN                 25     28I 0
     D* Completion code
     D  DXCC                  29     32I 0
     D* Reason code qualifying DXCC
     D  DXREA                 33     36I 0
     D* Response from exit
     D  DXRES                 37     40I 0
     D* Connection handle
     D  DXHCN                 41     44I 0