Conversion processing

This information describes the processing performed by the queue manager in response to the MQGMO_CONVERT option.

The queue manager performs the following actions if the MQGMO_CONVERT option is specified on the MQGET call, and there is a message to be returned to the application:
  1. If one or more of the following is true, no conversion is necessary:

    • The message data is already in the character set and encoding required by the application issuing the MQGET call. The application must set the CodedCharSetId and Encoding fields in the MsgDesc parameter of the MQGET call to the values required, before issuing the call.
    • The length of the message data is zero.
    • The length of the Buffer parameter of the MQGET call is zero.

    In these cases the message is returned without conversion to the application issuing the MQGET call; the CodedCharSetId and Encoding values in the MsgDesc parameter are set to the values in the control information in the message, and the call completes with one of the following combinations of completion code and reason code:

    Completion code Reason code
    MQCC_OK MQRC_NONE
    MQCC_WARNING MQRC_TRUNCATED_MSG_ACCEPTED
    MQCC_WARNING MQRC_TRUNCATED_MSG_FAILED

    The following steps are performed only if the character set or encoding of the message data differs from the corresponding value in the MsgDesc parameter, and there is data to be converted:

  2. If the Format field in the control information in the message has the value MQFMT_NONE, the message is returned unconverted, with completion code MQCC_WARNING and reason code MQRC_FORMAT_ERROR.

    In all other cases conversion processing continues.

  3. The message is removed from the queue and placed in a temporary buffer that is the same size as the Buffer parameter. For browse operations, the message is copied into the temporary buffer, instead of being removed from the queue.
  4. If the message has to be truncated to fit in the buffer, 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_TRUNCATED_MSG_FAILED.
    • If the MQGMO_ACCEPT_TRUNCATED_MSG option was specified, the completion code is set to MQCC_WARNING, the reason code is set to MQRC_TRUNCATED_MSG_ACCEPTED, and conversion processing continues.

  5. If the message can be accommodated in the buffer without truncation, or the MQGMO_ACCEPT_TRUNCATED_MSG option was specified, the following is done:

    • If the format is a built-in format, the buffer is passed to the queue manager's data-conversion service.
    • If the format is not a built-in format, the buffer is passed to a user-written exit with the same name as the format. If the exit cannot be found, the message is returned unconverted, with completion code MQCC_WARNING and reason code MQRC_FORMAT_ERROR.

    If no error occurs, the output from the data-conversion service or from the user-written exit is the converted message, plus the completion code and reason code to be returned to the application issuing the MQGET call.

  6. If the conversion is successful, the queue manager returns the converted message to the application. In this case, the completion code and reason code returned by the MQGET call are one of the following combinations:

    Completion code Reason code
    MQCC_OK MQRC_NONE
    MQCC_WARNING MQRC_TRUNCATED_MSG_ACCEPTED
    However, if the conversion is performed by a user-written exit, other reason codes can be returned, even when the conversion is successful.

    If the conversion fails, the queue manager returns the unconverted message to the application, with the CodedCharSetId and Encoding fields in the MsgDesc parameter set to the values in the control information in the message, and with completion code MQCC_WARNING.

Parent topic: Data conversion