Processing conventions

When converting a built-in format, the queue manager follows the processing conventions described.

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:

  • MQFMT_ADMIN
  • MQFMT_CICS ( z/OS only)
  • MQFMT_COMMAND_1
  • MQFMT_COMMAND_2
  • MQFMT_DEAD_LETTER_HEADER
  • MQFMT_DIST_HEADER
  • MQFMT_EVENT version 1
  • MQFMT_EVENT version 2
  • MQFMT_IMS
  • MQFMT_IMS_VAR_STRING
  • MQFMT_MD_EXTENSION
  • MQFMT_PCF
  • MQFMT_REF_MSG_HEADER
  • MQFMT_RF_HEADER
  • MQFMT_RF_HEADER_2
  • MQFMT_STRING
  • MQFMT_TRIGGER
  • MQFMT_WORK_INFO_HEADER ( z/OS only)
  • MQFMT_XMIT_Q_HEADER

  1. If the message expands during conversion, and exceeds the size of the Buffer parameter, the following is done:

    • If the MQGMO_ACCEPT_TRUNCATED_MSG option was not specified, the message is returned unconverted, with completion code MQCC_WARNING and reason code MQRC_CONVERTED_MSG_TOO_BIG.
    • If the MQGMO_ACCEPT_TRUNCATED_MSG option was specified, the message is truncated, the completion code is set to MQCC_WARNING, the reason code is set to MQRC_TRUNCATED_MSG_ACCEPTED, and conversion processing continues.

  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.

    • In the PCF formats MQFMT_ADMIN, MQFMT_EVENT, and MQFMT_PCF, the strings in the MQCFST and MQCFSL structures expand or contract as necessary to accommodate the string after conversion.

      For the string-list structure MQCFSL, the strings in the list might expand or contract by different amounts. If this happens, the queue manager pads the shorter strings with blanks to make them the same length as the longest string after conversion.

    • In the format MQFMT_REF_MSG_HEADER, the strings addressed by the SrcEnvOffset, SrcNameOffset, DestEnvOffset, and DestNameOffset fields expand or contract as necessary to accommodate the strings after conversion.
    • In the format MQFMT_RF_HEADER, the NameValueString field expands or contracts as necessary to accommodate the name-value pairs after conversion.
    • In structures with fixed field sizes, the queue manager allows strings to expand or contract within their fixed fields, provided that no significant information is lost. In this regard, trailing blanks and characters following the first null character in the field are treated as insignificant.

      • If the string expands, but only insignificant characters need to be discarded to accommodate the converted string in the field, the conversion succeeds and the call completes with MQCC_OK and reason code MQRC_NONE (assuming no other errors).
      • If the string expands, but the converted string requires significant characters to be discarded in order to fit in the field, the message is returned unconverted and the call completes with MQCC_WARNING and reason code MQRC_CONVERTED_STRING_TOO_BIG. Note: Reason code MQRC_CONVERTED_STRING_TOO_BIG results in this case whether or not the MQGMO_ACCEPT_TRUNCATED_MSG option was specified.
      • If the string contracts, the queue manager pads the string with blanks to the length of the field.

  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 reason code indicates that the message was converted successfully:

      • MQRC_NONE

    • The following reason codes indicate that the message might have been converted successfully (check the CodedCharSetId and Encoding fields in the MsgDesc parameter to find out):

      • MQRC_MSG_MARKED_BROWSE_CO_OP
      • MQRC_TRUNCATED_MSG_ACCEPTED

    • All other reason codes indicate that the message was not converted.

    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:

    • MQFMT_ADMIN
    • MQFMT_COMMAND_1
    • MQFMT_COMMAND_2
    • MQFMT_EVENT
    • MQFMT_IMS_VAR_STRING
    • MQFMT_PCF
    • MQFMT_STRING

    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 UTF-16 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 before 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 MQDLH structure could not be converted. In this case the application message data will not have been converted either.
    • The MQDLH structure was converted, but the application message data was not.

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

    • The values of the Format, CodedCharSetId, and Encoding fields in the MsgDesc parameter describe the data in the MQXQH structure, and not the application message data; the values are therefore not the same as those specified by the application that issued the MQGET call.

      The effect of this is that an application that repeatedly gets messages from a transmission queue with the MQGMO_CONVERT option specified must reset the CodedCharSetId and Encoding fields in the MsgDesc parameter to the values required for the application message data, before each MQGET call.

    • The values of the Format, CodedCharSetId, and Encoding fields in the last MQ header structure present describe the application message data. If there are no other MQ header structures present, the application message data is described by these fields in the MQMD structure within the MQXQH structure. If conversion is successful, the values will be the same as those specified in the MsgDesc parameter by the application that issued the MQGET call.

    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 previously is primarily intended for use by message channel agents when they get messages from transmission queues.

Parent topic: Data conversion