MQXCNVC-转换字符

MQXCNVC 调用将字符从一个字符集转换为另一个字符集。

此调用是 IBM® MQ 数据转换接口 (DCI) 的一部分，它是 IBM MQ 框架接口之一。 注: 此调用只能从数据转换出口使用。

语法

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

参数

MQXCNVC 调用具有以下参数:

HCONN (10 位有符号整数)-输入

连接句柄。

此句柄表示与队列管理器的连接。 它通常应该是传递到 MQDXP 结构的 DXHCN 字段中的数据转换出口的句柄; 此句柄不一定与发出 MQGET 调用的应用程序指定的句柄相同。

在 IBM i上，可以为 HCONN指定以下特殊值:
HCDEFH
缺省连接句柄。
OPTS (10 位带符号整数)-输入

用于控制 MQXCNVC 的操作的选项。

可以指定本节后面描述的零个或多个选项。 如果需要多个值，那么可以添加这些值 (请勿多次添加相同的常量)。

缺省-转换选项: 以下选项控制缺省字符转换的使用:
DCCDEF
缺省转换。

此选项指定如果调用上指定的一个或两个字符集不受支持，那么可以使用缺省字符转换。 这允许队列管理器在转换字符串时使用安装指定的缺省字符集，该字符集近似指定的字符集。

注: 使用近似字符集来转换字符串的结果是某些字符可能转换不正确。 这可以通过在字符串中仅使用对指定字符集和缺省字符集都通用的字符来避免。

缺省字符集由配置选项在安装或重新启动队列管理器时定义。

如果未指定 DCCDEF ，那么队列管理器仅使用指定的字符集来转换字符串，如果其中一个或两个字符集不受支持，那么调用将失败。

填充选项: 以下选项允许队列管理器用空格填充转换后的字符串或废弃无关紧要的尾部字符，以使转换后的字符串适合目标缓冲区:
投资公司
填充目标缓冲区。
此选项请求以完全填充目标缓冲区的方式进行转换:
  • 如果字符串在转换时收缩，那么将添加尾部空格以填充目标缓冲区。
  • 如果字符串在转换时扩展，那么将废弃不重要的尾部字符，以使转换后的字符串适合目标缓冲区。 如果可以成功完成此操作，那么调用将通过 CCOK 和原因码 RCNONE 完成。

    如果尾部字符太少，那么将尽可能多的字符串放在目标缓冲区中，并且调用将完成 CCWARN 和原因码 RC2120。

    不重要的字符包括:
    • 尾部空格
    • 字符串中第一个空字符后的字符 (但不包括第一个空字符本身)
  • 如果字符串 TGTCSI 和 TGTLEN 导致无法使用有效字符完全设置目标缓冲区，那么调用将失败并返回 CCFAIL 和原因码 RC2144。 当 TGTCSI 是纯 DBCS 字符集 (例如 UCS-2) ，但 TGTLEN 指定的长度为奇数字节时，可能会发生此情况。
  • TGTLEN 可以小于或大于 SRCLEN。 从 MQXCNVC 返回时， DATLEN 具有与 TGTLEN相同的值。
如果未指定此选项:
  • 允许字符串根据需要在目标缓冲区中收缩或展开。 不会添加或废弃无意义的尾部字符。

    如果转换后的字符串适合目标缓冲区，那么调用将使用 CCOK 和原因码 RCNONE 完成。

    如果转换后的字符串对于目标缓冲区过大，那么将尽可能多的字符串放置在目标缓冲区中，并且调用将完成并带有 CCWARN 和原因码 RC2120。 请注意，在这种情况下，可以返回少于 TGTLEN 个字节的字节。

  • TGTLEN 可以小于或大于 SRCLEN。 从 MQXCNVC 返回时， DATLEN 小于或等于 TGTLEN。

编码选项: 以下选项可用于指定源字符串和目标字符串的整数编码。 当相应的字符集标识指示主存储器中字符集的表示依赖于用于二进制整数的编码时， 仅 使用相关编码。 这仅影响某些多字节字符集 (例如， example,UCS-2 字符集)。

如果字符集是单字节字符集 (SBCS) 或在主存储器中具有不依赖于整数编码的表示的多字节字符集，那么将忽略该编码。

只应指定其中一个 DCCS* 值，并与其中一个 DCCT* 值组合:
DCCSNA
源编码是环境和编程语言的缺省值。
DCCSNO
源编码正常。
DCCSRE
源编码已反转。
DCCSUN
未定义源编码。
DCCTNA
目标编码是环境和编程语言的缺省值。
DCCTNO
目标编码正常。
DCCTRE
目标编码已反转。
DCCTUN
目标编码未定义。
可以将先前定义的编码值直接添加到 OPTS 字段。 但是，如果从 MQMD 或其他结构中的 MDENC 字段获取源或目标编码，那么必须执行以下处理:
  1. 必须通过消除 float 和 packed-decimal 编码从 MDENC 字段中抽取整数编码; 有关如何执行此操作的详细信息，请参阅 分析编码 。
  2. 在添加到 OPTS 字段之前，必须将步骤 1 生成的整数编码乘以相应的因子。 这些因素包括:
    DCCSFA
    源编码的因子
    DCCTFA
    目标编码的因子
如果未指定，那么编码选项缺省为 undefined (DCC* UN)。 在大多数情况下，这不会影响 MQXCNVC 调用的成功完成。 但是，如果相应的字符集是具有依赖于编码的表示的多字节字符集 (例如， UCS-2 字符集) ，那么调用将失败，原因码为 RC2112 或 RC2116 (视情况而定)。
缺省选项: 如果未指定任何先前描述的选项，那么可以使用以下选项:
DCCNON
未指定任何选项。

定义 DCCNON 是为了帮助程序文档。 不打算将此选项与任何其他选项一起使用，但由于其值为零，因此无法检测到此类使用。

SRCCSI (10 位有符号整数)-输入

转换前字符串的编码字符集标识。

这是 SRCBUF中输入字符串的编码字符集标识。

SRCLEN (10 位有符号整数)-输入

转换前字符串的长度。

这是 SRCBUF 中输入字符串的长度 (以字节计); 必须为零或更大。

SRCBUF (1 字节字符串 x SRCLEN)-输入

要转换的字符串。

这是包含要从一个字符集转换为另一个字符集的字符串的缓冲区。

TGTCSI (10 位有符号整数)-输入

转换后字符串的编码字符集标识。

这是要将 SRCBUF 转换为的字符集的编码字符集标识。

TGTLEN (10 位有符号整数)-输入

输出缓冲区的长度。

这是输出缓冲区 TGTBUF 的长度 (以字节计); 必须为零或更大。 它可以小于或大于 SRCLEN。

TGTBUF (1 字节字符串 x TGTLEN)-输出

转换后的字符串。

这是将字符串转换为 TGTCSI定义的字符集后的字符串。 转换后的字符串可以比未转换的字符串短或长。 DATLEN 参数指示返回的有效字节数。

DATLEN (10 位有符号整数)-输出

输出字符串的长度。

这是输出缓冲区 TGTBUF中返回的字符串的长度。 转换后的字符串可以比未转换的字符串短或长。

CMPCOD (10 位有符号整数)-输出

完成代码。

它是下列项之一：
CCOK
成功完成。
CCWARN
警告（部分完成）。
CCFAIL
调用失败。
REASON (10 位带符号整数)-输出

原因码限定 CMPCOD。

如果 CMPCOD 是 CCOK:
RCNONE
(0, X'000') 没有要报告的原因。
如果 CMPCOD 是 CCWARN:
RC2120
(2120 ， X'848 ') 转换的数据对于缓冲区太大。
如果 CMPCOD 为 CCFAIL:
RC2010
(2010，X'7DA'）数据长度参数无效。
RC2150
(2150 ， X'866 ') DBCS 字符串无效。
RC2018
(2018, X'7E2') 连接句柄无效。
RC2046
(2046,X'7FE') 选项无效或不一致。
RC2102
(2102, X'836') 没有足够系统资源可用。
RC2145
(2145 ， X'861 ') 源缓冲区参数无效。
RC2111
(2111，X'83F'）源编码字符集标识符无效。
RC2112
(2112 ， X'840 ') 无法识别源整数编码。
RC2143
(2143，X'85F'）源长度参数无效。
RC2071
(2071, X'817') 没有足够的存储空间可用。
RC2146
(2146 ， X'862 ') 目标缓冲区参数无效。
RC2115
(2115 ， X'843 ') 目标编码字符集标识无效。
RC2116
(2116 ， X'844 ') 无法识别目标整数编码。
RC2144
(2144 ， X'860 ') 目标长度参数无效。
RC2195
(2195, X'893') 发生了意外错误。

有关这些原因码的更多信息，请参阅 IBM i (ILE RPG) 的返回码。

RPG 调用 (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)
调用的原型定义为:
     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