MQXCNVC (Convert characters) on IBM i

The MQXCNVC call converts characters from one character set to another.

This call is part of the IBM MQ Data Conversion Interface (DCI), which is one of the IBM MQ framework interfaces. Note: This call can be used only from a data-conversion exit.


Syntax

    MQXCNVC HCONN, OPTS, SRCCSI, SRCLEN, SRCBUF, TGTCSI, TGTLEN,
    TGTBUF, DATLEN, CMPCOD, REASON)


Parameters

The MQXCNVC call has the following parameters:

    HCONN (10-digit signed integer) - input

    Connection handle.

    This handle represents the connection to the queue manager. It should normally be the handle passed to the data-conversion exit in the DXHCN 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:

      HCDEFH
      Default connection handle.

    OPTS (10-digit signed integer) - input

    Options that control the action of MQXCNVC.

    Zero or more of the options described later in this section can be specified. If more than one is required, the values can be added (do not add the same constant more than once).

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

      DCCDEF
      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 may 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 DCCDEF 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.

    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:

      DCCFIL
      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 CCOK and reason code RCNONE.

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

        Insignificant characters are:

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

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

      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 CCOK and reason code RCNONE.

        If the converted string is too large for the target buffer, as much of the string as will fit is placed in the target buffer, and the call completes with CCWARN and reason code RC2120. Note that fewer than TGTLEN bytes can be returned in this case.

      • TGTLEN can be less than or greater than SRCLEN. On return from MQXCNVC, DATLEN is less than or equal to TGTLEN.

    Encoding options: The following options 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 DCCS* values should be specified, combined with one of the DCCT* values:

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

      DCCSNO
      Source encoding is normal.

      DCCSRE
      Source encoding is reversed.

      DCCSUN
      Source encoding is undefined.

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

      DCCTNO
      Target encoding is normal.

      DCCTRE
      Target encoding is reversed.

      DCCTUN
      Target encoding is undefined.

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

    1. The integer encoding must be extracted from the MDENC field by eliminating the float and packed-decimal encodings; see Analyzing encodings on IBM i 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 OPTS field. These factors are:

        DCCSFA
        Factor for source encoding

        DCCTFA
        Factor for target encoding

    If not specified, the encoding options default to undefined (DCC*UN). 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 RC2112 or RC2116 as appropriate. Default option: If none of the options described previously is specified, the following option can be used:

      DCCNON
      No options specified.

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

    SRCCSI (10-digit signed integer) - input

    Coded character set identifier of string before conversion.

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

    SRCLEN (10-digit signed integer) - input

    Length of string before conversion.

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

    SRCBUF (1-byte character string x SRCLEN) - input

    String to be converted.

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

    TGTCSI (10-digit signed integer) - input

    Coded character set identifier of string after conversion.

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

    TGTLEN (10-digit signed integer) - input

    Length of output buffer.

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

    TGTBUF (1-byte character string x TGTLEN) - output

    String after conversion.

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

    DATLEN (10-digit signed integer) - output

    Length of output string.

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

    CMPCOD (10-digit signed integer) - output

    Completion code.

    It is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

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

    If CMPCOD is CCWARN:

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

    If CMPCOD is CCFAIL:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    For more information about these reason codes, see Return codes for IBM i (ILE RPG).


RPG invocation (ILE)

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQXCNVC(HCONN : OPTS : SRCCSI :
     C                                       SRCLEN : SRCBUF : TGTCSI :
     C                                       TGTLEN : TGTBUF : DATLEN :
     C                                       CMPCOD : REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQXCNVC          PR                  EXTPROC('MQXCNVC')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Options that control the action of MQXCNVC
     D OPTS                          10I 0 VALUE
     D* Coded character set identifier of string before conversion
     D SRCCSI                        10I 0 VALUE
     D* Length of string before conversion
     D SRCLEN                        10I 0 VALUE
     D* String to be converted
     D SRCBUF                          *   VALUE
     D* Coded character set identifier of string after conversion
     D TGTCSI                        10I 0 VALUE
     D* Length of output buffer
     D TGTLEN                        10I 0 VALUE
     D* String after conversion
     D TGTBUF                          *   VALUE
     D* Length of output string
     D DATLEN                        10I 0
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0
Parent topic: Data conversion on IBM i