Processing conventions on IBM i

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

Consider applying these conventions to user-written exits, although this is not enforced by the queue manager. The built-in formats converted by the queue manager are as follows:

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

    • If the GMATM option was not specified, the message is returned unconverted, with completion code CCWARN and reason code RC2120.
    • If the GMATM option was specified, the message is truncated, the completion code is set to CCWARN, the reason code is set to RC2079, and conversion processing continues.

  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.

    • In the PCF formats FMADMN, FMEVNT, and FMPCF, 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 FMRMH, the strings addressed by the RMSEO, RMSNO, RMDEO, and RMDNO fields expand or contract as necessary to accommodate the strings after conversion.
    • In the format FMRFH, the RFNVS 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, if 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 CCOK and reason code RCNONE (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 CCWARN and reason code RC2190. Note: Reason code RC2190 results in this case whether the GMATM 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 IBM 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 might 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 might or might 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 reason code indicates that the message was converted successfully:

      • RCNONE

    • The following reason code indicates that the message may have been converted successfully (check the MDCSI and MDENC fields in the MSGDSC parameter to find out):

      • RC2079

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

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

  1. Except for the following formats:

    • FMADMN
    • FMEVNT
    • FMIMVS
    • FMPCF
    • FMSTR

    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 UTF-16 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 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 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 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 MDCSI and MDENC fields in the MSGDSC parameter, and those in the MQDLH structure, in order to determine which of the previous 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 typically the application message data (which may be of zero length), but there can also be one or more further IBM 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 IBM 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 IBM 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:

    • The values of the MDFMT, MDCSI, and MDENC fields in the MSGDSC parameter, describe the data in the MQXQH structure, and not the application message data; the values will therefore not be the same as those specified by the application that issued the MQGET call.

      The effect of this is that an application which repeatedly gets messages from a transmission queue with the GMCONV option specified must reset the MDCSI and MDENC fields in the MSGDSC parameter to the values necessary for the application message data, before each MQGET call.

    • The values of the MDFMT, MDCSI, and MDENC fields in the last MQ header structure present describe the application message data. If there are no other IBM 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 MSGDSC 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 may be followed by zero or more further IBM 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 previously are primarily intended for use by message channel agents when they get messages from transmission queues.

Parent topic: Data conversion on IBM i