Processing conventions

When converting a built-in format, the queue manager follows the processing conventions described below. User-written exits should also follow these conventions, although this is not enforced by the queue manager. The built-in formats converted by the queue manager are:

  1. If the message expands during conversion, and exceeds the size of the Buffer parameter, the following is done:
  2. If truncation occurs (either before or during conversion), the number of valid bytes returned in the Buffer parameter can be less than the length of the buffer.

    This can occur, for example, if a 4-byte integer or a DBCS character straddles the end of the buffer. The incomplete element of information is not converted, and those bytes in the returned message do not contain valid information. This can also occur if a message that was truncated before conversion shrinks during conversion.

    If the number of valid bytes returned is less than the length of the buffer, the unused bytes at the end of the buffer are set to nulls.

  3. If an array or string straddles the end of the buffer, as much of the data as possible is converted; only the particular array element or DBCS character which is incomplete is not converted; preceding array elements or characters are converted.
  4. If truncation occurs (either before or during conversion), the length returned for the DataLength parameter is the length of the unconverted message before truncation.
  5. When strings are converted between single-byte character sets (SBCS), double-byte character sets (DBCS), or multi-byte character sets (MBCS), the strings can expand or contract.
  6. For messages consisting of one or more MQ header structures followed by user data, one or more of the header structures might be converted, while the remainder of the message is not. However, (with two exceptions) the CodedCharSetId and Encoding fields in each header structure always correctly indicate the character set and encoding of the data that follows the header structure.

    The two exceptions are the MQCIH and MQIIH structures, where the values in the CodedCharSetId and Encoding fields in those structures are not significant. For those structures, the data following the structure is in the same character set and encoding as the MQCIH or MQIIH structure itself.

  7. If the CodedCharSetId or Encoding fields in the control information of the message being retrieved, or in the MsgDesc parameter, specify values that are undefined or not supported, the queue manager might ignore the error if the undefined or unsupported value does not need to be used in converting the message.

    For example, if the Encoding field in the message specifies an unsupported float encoding, but the message contains only integer data, or contains floating-point data that does not require conversion (because the source and target float encodings are identical), the error might not be diagnosed.

    If the error is diagnosed, the message is returned unconverted, with completion code MQCC_WARNING and one of the MQRC_SOURCE_*_ERROR or MQRC_TARGET_*_ERROR reason codes (as appropriate); the CodedCharSetId and Encoding fields in the MsgDesc parameter are set to the values in the control information in the message.

    If the error is not diagnosed and the conversion completes successfully, the values returned in the CodedCharSetId and Encoding fields in the MsgDesc parameter are those specified by the application issuing the MQGET call.

  8. In all cases, if the message is returned to the application unconverted the completion code is set to MQCC_WARNING, and the CodedCharSetId and Encoding fields in the MsgDesc parameter are set to the values appropriate to the unconverted data. This is done for MQFMT_NONE also.

    The Reason parameter is set to a code that indicates why the conversion could not be carried out, unless the message also had to be truncated; reason codes related to truncation take precedence over reason codes related to conversion. (To determine if a truncated message was converted, check the values returned in the CodedCharSetId and Encoding fields in the MsgDesc parameter.)

    When an error is diagnosed, either a specific reason code is returned, or the general reason code MQRC_NOT_CONVERTED. The reason code returned depends on the diagnostic capabilities of the underlying data-conversion service.

  9. If completion code MQCC_WARNING is returned, and more than one reason code is relevant, the order of precedence is as follows:
    1. The following reasons take precedence over all others; only one of the reasons in this group can arise:
      • MQRC_SIGNAL_REQUEST_ACCEPTED
      • MQRC_TRUNCATED_MSG_ACCEPTED
    2. The order of precedence within the remaining reason codes is not defined.
  10. On completion of the MQGET call:

    The following processing is specific to the built-in formats; it does not apply to user-defined formats:

  11. With the exception of the following formats: none of the built-in formats can be converted from or to character sets that do not have SBCS characters for the characters that are valid in queue names. If an attempt is made to perform such a conversion, the message is returned unconverted, with completion code MQCC_WARNING and reason code MQRC_SOURCE_CCSID_ERROR or MQRC_TARGET_CCSID_ERROR, as appropriate.

    The Unicode character set UCS-2 is an example of a character set that does not have SBCS characters for the characters that are valid in queue names.

  12. If the message data for a built-in format is truncated, fields within the message that contain lengths of strings, or counts of elements or structures, are not adjusted to reflect the length of the data actually returned to the application; the values returned for such fields within the message data are the values applicable to the message prior to truncation.

    When processing messages such as a truncated MQFMT_ADMIN message, ensure that the application does not attempt to access data beyond the end of the data returned.

  13. If the format name is MQFMT_DEAD_LETTER_HEADER, the message data begins with an MQDLH structure, possibly followed by zero or more bytes of application message data. The format, character set, and encoding of the application message data are defined by the Format, CodedCharSetId, and Encoding fields in the MQDLH structure at the start of the message. Because the MQDLH structure and application message data can have different character sets and encodings, one, other, or both of the MQDLH structure and application message data might require conversion.

    The queue manager converts the MQDLH structure first, as necessary. If conversion is successful, or the MQDLH structure does not require conversion, the queue manager checks the CodedCharSetId and Encoding fields in the MQDLH structure to see if conversion of the application message data is required. If conversion is required, the queue manager invokes the user-written exit with the name given by the Format field in the MQDLH structure, or performs the conversion itself (if Format is the name of a built-in format).

    If the MQGET call returns a completion code of MQCC_WARNING, and the reason code is one of those indicating that conversion was not successful, one of the following applies:

    The application can examine the values returned in the CodedCharSetId and Encoding fields in the MsgDesc parameter, and those in the MQDLH structure, in order to determine which of the above applies.

  14. If the format name is MQFMT_XMIT_Q_HEADER, the message data begins with an MQXQH structure, possibly followed by zero or more bytes of additional data. This additional data is usually the application message data (which may be of zero length), but there can also be one or more further MQ header structures present, at the start of the additional data.

    The MQXQH structure must be in the character set and encoding of the queue manager. The format, character set, and encoding of the data following the MQXQH structure are given by the Format, CodedCharSetId, and Encoding fields in the MQMD structure contained within the MQXQH. For each subsequent MQ header structure present, the Format, CodedCharSetId, and Encoding fields in the structure describe the data that follows that structure; that data is either another MQ header structure, or the application message data.

    If the MQGMO_CONVERT option is specified for an MQFMT_XMIT_Q_HEADER message, the application message data and certain of the MQ header structures are converted, but the data in the MQXQH structure is not. On return from the MQGET call, therefore:

    If the message is a distribution-list message, the MQXQH structure is followed by an MQDH structure (plus its arrays of MQOR and MQPMR records), which in turn might be followed by zero or more further MQ header structures and zero or more bytes of application message data. Like the MQXQH structure, the MQDH structure must be in the character set and encoding of the queue manager, and it is not converted on the MQGET call, even if the MQGMO_CONVERT option is specified.

    The processing of the MQXQH and MQDH structures described above is primarily intended for use by message channel agents when they get messages from transmission queues.