Processing conventions

When converting a built-in format, the queue manager follows the processing conventions described below. It is recommended that 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:

FMADMN FMMDE
FMCICS FMPCF
FMCMD1 FMRMH
FMCMD2 FMRFH
FMDLH FMRFH2
FMDH FMSTR
FMEVNT FMTM
FMIMS FMXQH
FMIMVS  
  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), it is possible for the number of valid bytes returned in the BUFFER parameter to 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 so 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 DATLEN 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, it is possible for one or more of the header structures to be converted, while the remainder of the message is not. However, (with two exceptions) the MDCSI and MDENC 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 MDCSI and MDENC 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 MDCSI or MDENC fields in the control information of the message being retrieved, or in the MSGDSC parameter, specify values which are undefined or not supported, the queue manager may ignore the error if the undefined or unsupported value does not need to be used in converting the message.

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

    If the error is diagnosed, the message is returned unconverted, with completion code CCWARN and one of the RC2111, RC2112, RC2113, RC2114 or RC2115, RC2116, RC2117, RC2118 reason codes (as appropriate); the MDCSI and MDENC fields in the MSGDSC 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 MDCSI and MDENC fields in the MSGDSC 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 CCWARN, and the MDCSI and MDENC fields in the MSGDSC parameter are set to the values appropriate to the unconverted data. This is done for FMNONE 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 MDCSI and MDENC fields in the MSGDSC parameter.)

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

  9. If completion code CCWARN is returned, and more than one reason code is relevant, the order of precedence is as follows:
    1. The following reason takes precedence over all others:
      • RC2079
    2. Next in precedence is the following reason:
      • RC2110
    3. 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 is not applicable to user-defined formats:

  1. 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 CCWARN and reason code RC2111 or RC2115, 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.

  2. If the message data for a built-in format is truncated, fields within the message which 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 FMADMN message, care must be taken to ensure that the application does not attempt to access data beyond the end of the data returned.

  3. If the format name is FMDLH, the message data begins with an MQDLH structure, and this may be 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 DLFMT, DLCSI, and DLENC fields in the MQDLH structure at the start of the message. Since the MQDLH structure and application message data can have different character sets and encodings, it is possible for one, other, or both of the MQDLH structure and application message data to 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 DLCSI and DLENC 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 DLFMT field in the MQDLH structure, or performs the conversion itself (if DLFMT is the name of a built-in format).

    If the MQGET call returns a completion code of CCWARN, 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 MDCSI and MDENC fields in the MSGDSC parameter, and those in the MQDLH structure, in order to determine which of the above applies.

  4. If the format name is FMXQH, the message data begins with an MQXQH structure, and this may be 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 MDFMT, MDCSI, and MDENC fields in the MQMD structure contained within the MQXQH. For each subsequent MQ header structure present, the MDFMT, MDCSI, and MDENC 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 GMCONV option is specified for an FMXQH 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 may 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 GMCONV 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.