MQXCNVC - Convert characters

The MQXCNVC call converts characters from one character set to another using the C programming language.

This call is part of the IBM MQ Data Conversion Interface (DCI), which is one of the IBM MQ framework interfaces.

Note: The call can be used from both application, and data-conversion exit environments.


Syntax

MQXCNVC (Hconn, Options, SourceCCSID, SourceLength, SourceBuffer, TargetCCSID, TargetLength, TargetBuffer, DataLength, CompCode, Reason)


Parameters

    Hconn
    Type: MQHCONN - input

    This handle represents the connection to the queue manager.

    In a data-conversion exit, Hconn is normally the handle that is passed to the data-conversion exit in the Hconn field of the MQDXP structure; this handle is not necessarily the same as the handle specified by the application which issued the MQGET call.

    On IBM i, the following special value can be specified for Hconn:

      MQHC_DEF_HCONN
      Default connection handle.

    If you run a CICS TS 3.2 or higher application, ensure that the character conversion exit program, which invokes the MQXCNVC call, is defined as OPENAPI. This definition prevents the 2018 MQRC_HCONN_ERROR error caused by from an incorrect connection, and allows the MQGET to complete.

    Options
    Type: MQLONG - input

    Options that control the action of MQXCNVC.

    Zero or more of the options described can be specified. To specify more than one option, either add the values together (do not add the same constant more than once), or combine the values using the bitwise OR operation (if the programming language supports bit operations).

    Default-conversion option: The following option controls the use of default character conversion:

      MQDCC_DEFAULT_CONVERSION
      Default conversion.

      This option specifies that default character conversion can be used if one or both of the character sets specified on the call is not supported. This allows the queue manager to use an installation-specified default character set that approximates the specified character set, when converting the string.

      Note: The result of using an approximate character set to convert the string is that some characters can be converted incorrectly. This can be avoided by using in the string only characters which are common to both the specified character set and the default character set.

      The default character sets are defined by a configuration option when the queue manager is installed or restarted.

      If MQDCC_DEFAULT_CONVERSION is not specified, the queue manager uses only the specified character sets to convert the string, and the call fails if one or both of the character sets is not supported.

      This option is supported in the following environments:

      • AIX
      • IBM i
      • Linux
      • Windows

    Padding option: The following option allows the queue manager to pad the converted string with blanks or discard insignificant trailing characters, in order to make the converted string fit the target buffer:

      MQDCC_FILL_TARGET_BUFFER
      Fill target buffer. This option requests that conversion take place in such a way that the target buffer is filled completely:

      • If the string contracts when it is converted, trailing blanks are added in order to fill the target buffer.
      • If the string expands when it is converted, trailing characters that are not significant are discarded to make the converted string fit the target buffer. If this can be done successfully, the call completes with MQCC_OK and reason code MQRC_NONE.

        If there are too few insignificant trailing characters, as much of the string as can fit is placed in the target buffer, and the call completes with MQCC_WARNING and reason code MQRC_CONVERTED_MSG_TOO_BIG.

        Insignificant characters are:

        • Trailing blanks
        • Characters following the first null character in the string (but excluding the first null character itself)

      • If the string, TargetCCSID, and TargetLength are such that the target buffer cannot be set completely with valid characters, the call fails with MQCC_FAILED and reason code MQRC_TARGET_LENGTH_ERROR. This can occur when TargetCCSID is a pure DBCS character set (such as UTF-16), but TargetLength specifies a length that is an odd number of bytes.
      • TargetLength can be less than or greater than SourceLength. On return from MQXCNVC, DataLength has the same value as TargetLength.

      If this option is not specified:

      • The string is allowed to contract or expand within the target buffer as required. Insignificant trailing characters are not added or discarded.

        If the converted string fits in the target buffer, the call completes with MQCC_OK and reason code MQRC_NONE.

        If the converted string is too large for the target buffer, as much of the string as fits is placed in the target buffer, and the call completes with MQCC_WARNING and reason code MQRC_CONVERTED_MSG_TOO_BIG. Note fewer than TargetLength bytes can be returned in this case.

      • TargetLength can be less than or greater than SourceLength. On return from MQXCNVC, DataLength is less than or equal to TargetLength.

      This option is supported in the following environments:

      • AIX
      • IBM i
      • Linux
      • Windows

    Encoding options: The options described can be used to specify the integer encodings of the source and target strings. The relevant encoding is used only when the corresponding character set identifier indicates that the representation of the character set in main storage is dependent on the encoding used for binary integers. This affects only certain multibyte character sets (for example, UTF-16 character sets).

    The encoding is ignored if the character set is a single-byte character set (SBCS), or a multibyte character set with representation in main storage that is not dependent on the integer encoding.

    Only one of the MQDCC_SOURCE_* values must be specified, combined with one of the MQDCC_TARGET_* values:

      MQDCC_SOURCE_ENC_NATIVE
      Source encoding is the default for the environment and programming language.

      MQDCC_SOURCE_ENC_NORMAL
      Source encoding is normal.

      MQDCC_SOURCE_ENC_REVERSED
      Source encoding is reversed.

      MQDCC_SOURCE_ENC_UNDEFINED
      Source encoding is undefined.

      MQDCC_TARGET_ENC_NATIVE
      Target encoding is the default for the environment and programming language.

      MQDCC_TARGET_ENC_NORMAL
      Target encoding is normal.

      MQDCC_TARGET_ENC_REVERSED
      Target encoding is reversed.

      MQDCC_TARGET_ENC_UNDEFINED
      Target encoding is undefined.

    The encoding values defined previously can be added directly to the Options field. However, if the source or target encoding is obtained from the Encoding field in the MQMD or other structure, the following processing must be done:

    1. The integer encoding must be extracted from the Encoding field by eliminating the float and packed-decimal encodings; see Analyzing encodings for details of how to do this.
    2. The integer encoding resulting from step 1 must be multiplied by the appropriate factor before being added to the Options field. These factors are:

      • MQDCC_SOURCE_ENC_FACTOR for the source encoding
      • MQDCC_TARGET_ENC_FACTOR for the target encoding

    The following example code illustrates how this might be coded in the C programming language: 

    Options = (MsgDesc.Encoding & MQENC_INTEGER_MASK)
           * MQDCC_SOURCE_ENC_FACTOR
        + (DataConvExitParms.Encoding & MQENC_INTEGER_MASK)
           * MQDCC_TARGET_ENC_FACTOR;

    If not specified, the encoding options default to undefined (MQDCC_*_ENC_UNDEFINED). In most cases, this does not affect the successful completion of the MQXCNVC call. However, if the corresponding character set is a multibyte character set with representation that is dependent on the encoding (for example, a UTF-16 character set), the call fails with reason code MQRC_SOURCE_INTEGER_ENC_ERROR or MQRC_TARGET_INTEGER_ENC_ERROR as appropriate.

    The encoding options are supported in the following environments:

    • AIX
    • IBM i
    • Linux
    • Windows
    • z/OS

    Default option: If none of the options described previously is specified, the following option can be used:

      MQDCC_NONE
      No options specified.

      MQDCC_NONE is defined to aid program documentation. It is not intended that this option is used with any other, but as its value is zero, such use cannot be detected.

    SourceCCSID
    Type: MQLONG - input

    This is the coded character set identifier of the input string in SourceBuffer.

    SourceLength
    Type: MQLONG - input

    This is the length in bytes of the input string in SourceBuffer ; it must be zero or greater.

    SourceBuffer
    Type: MQCHAR x SourceLength - input

    This is the buffer containing the string to be converted from one character set to another.

    TargetCCSID
    Type: MQLONG - input

    This is the coded character set identifier of the character set to which SourceBuffer is to be converted.

    TargetLength
    Type: MQLONG - input

    This is the length in bytes of the output buffer TargetBuffer ; it must be zero or greater. It can be less than or greater than SourceLength.

    TargetBuffer
    Type: MQCHAR x TargetLength - output

    This is the string after it has been converted to the character set defined by TargetCCSID. The converted string can be shorter or longer than the unconverted string. The DataLength parameter indicates the number of valid bytes returned.

    DataLength
    Type: MQLONG - output

    This is the length of the string returned in the output buffer TargetBuffer. The converted string can be shorter or longer than the unconverted string.

    CompCode
    Type: MQLONG - output It is one of the following:

      MQCC_OK
      Successful completion.

      MQCC_WARNING
      Warning (partial completion).

      MQCC_FAILED
      Call failed.

    Reason
    Type: MQLONG - output

    Reason code qualifying CompCode.

    If CompCode is MQCC_OK:

      MQRC_NONE
      (0, X'000') No reason to report.

    If CompCode is MQCC_WARNING:

      MQRC_CONVERTED_MSG_TOO_BIG
      (2120, X'848') Converted data too large for buffer.

    If CompCode is MQCC_FAILED:

      MQRC_DATA_LENGTH_ERROR
      (2010, X'7DA') Data length parameter not valid.

      MQRC_DBCS_ERROR
      (2150, X'866') DBCS string not valid.

      MQRC_HCONN_ERROR
      (2018, X'7E2') Connection handle not valid.

      MQRC_OPTIONS_ERROR
      (2046, X'7FE') Options not valid or not consistent.

      MQRC_RESOURCE_PROBLEM
      (2102, X'836') Insufficient system resources available.

      MQRC_SOURCE_BUFFER_ERROR
      (2145, X'861') Source buffer parameter not valid.

      MQRC_SOURCE_CCSID_ERROR
      (2111, X'83F') Source coded character set identifier not valid.

      MQRC_SOURCE_INTEGER_ENC_ERROR
      (2112, X'840') Source integer encoding not recognized.

      MQRC_SOURCE_LENGTH_ERROR
      (2143, X'85F') Source length parameter not valid.

      MQRC_STORAGE_NOT_AVAILABLE
      (2071, X'817') Insufficient storage available.

      MQRC_TARGET_BUFFER_ERROR
      (2146, X'862') Target buffer parameter not valid.

      MQRC_TARGET_CCSID_ERROR
      (2115, X'843') Target coded character set identifier not valid.

      MQRC_TARGET_INTEGER_ENC_ERROR
      (2116, X'844') Target integer encoding not recognized.

      MQRC_TARGET_LENGTH_ERROR
      (2144, X'860') Target length parameter not valid.

      MQRC_UNEXPECTED_ERROR
      (2195, X'893') Unexpected error occurred.

    For detailed information about these codes, see Reason codes.


C invocation

MQXCNVC (Hconn, Options, SourceCCSID, SourceLength, SourceBuffer,
        TargetCCSID, TargetLength, TargetBuffer, &DataLength,
        &CompCode, &Reason);
Declare the parameters as follows: 
MQHCONN  Hconn;            /* Connection handle */
MQLONG   Options;          /* Options that control the action of
                              MQXCNVC */
MQLONG   SourceCCSID;      /* Coded character set identifier of string
                              before conversion */
MQLONG   SourceLength;     /* Length of string before conversion */
MQCHAR   SourceBuffer[n];  /* String to be converted */
MQLONG   TargetCCSID;      /* Coded character set identifier of string
                              after conversion */
MQLONG   TargetLength;     /* Length of output buffer */
MQCHAR   TargetBuffer[n];  /* String after conversion */
MQLONG   DataLength;       /* Length of output string */
MQLONG   CompCode;         /* Completion code */
MQLONG   Reason;           /* Reason code qualifying CompCode */


COBOL declaration ( IBM i only)

     CALL 'MQXCNVC' USING HCONN, OPTIONS, SOURCECCSID, SOURCELENGTH,
                          SOURCEBUFFER, TARGETCCSID, TARGETLENGTH,
                          TARGETBUFFER, DATALENGTH, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN         PIC S9(9) BINARY.
**   Options that control the action of MQXCNVC
 01  OPTIONS       PIC S9(9) BINARY.
**   Coded character set identifier of string before conversion
 01  SOURCECCSID   PIC S9(9) BINARY.
**   Length of string before conversion
 01  SOURCELENGTH  PIC S9(9) BINARY.
**   String to be converted
 01  SOURCEBUFFER  PIC X(n).
**   Coded character set identifier of string after conversion
 01  TARGETCCSID   PIC S9(9) BINARY.
**   Length of output buffer
 01  TARGETLENGTH  PIC S9(9) BINARY.
**   String after conversion
 01  TARGETBUFFER  PIC X(n).
**   Length of output string
 01  DATALENGTH    PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE      PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON        PIC S9(9) BINARY.


S/390 assembler declaration

         CALL MQXCNVC,(HCONN,OPTIONS,SOURCECCSID,SOURCELENGTH,         X
               SOURCEBUFFER,TARGETCCSID,TARGETLENGTH,TARGETBUFFER,     X
               DATALENGTH,COMPCODE,REASON)
Declare the parameters as follows: 
HCONN         DS  F      Connection handle
OPTIONS       DS  F      Options that control the action of MQXCNVC
SOURCECCSID   DS  F      Coded character set identifier of string before
*                        conversion
SOURCELENGTH  DS  F      Length of string before conversion
SOURCEBUFFER  DS  CL(n)  String to be converted
TARGETCCSID   DS  F      Coded character set identifier of string after
*                        conversion
TARGETLENGTH  DS  F      Length of output buffer
TARGETBUFFER  DS  CL(n)  String after conversion
DATALENGTH    DS  F      Length of output string
COMPCODE      DS  F      Completion code
REASON        DS  F      Reason code qualifying COMPCODE
Parent topic: Data conversion