处理 IBM i 上的约定

请考虑将这些约定应用于用户编写的出口，尽管队列管理器不会强制执行这些约定。 队列管理器转换的内置格式包括:

1. 如果消息在转换期间扩展，并且超出 BUFFER 参数的大小，那么将执行以下操作:
   • 如果未指定 GMATM 选项，那么将返回未转换的消息，完成代码为 CCWARN ，原因码为 RC2120。
   • 如果指定了 GMATM 选项 ，那么将截断消息，将完成代码设置为 CCWARN ，将原因码设置为 RC2079，然后继续进行转换处理。
2. 如果发生截断 (在转换之前或期间) ，那么 BUFFER 参数中返回的有效字节数可能 小于 缓冲区的长度。

   例如，如果 4 字节整数或 DBCS 字符跨越缓冲区的末尾，那么会发生此情况。 不会转换信息的不完整元素，因此返回的消息中的那些字节不包含有效信息。 如果转换前截断的消息在转换期间收缩，那么也会发生此情况。

   如果返回的有效字节数小于缓冲区的长度，那么缓冲区末尾未使用的字节将设置为空。

3. 如果数组或字符串横跨缓冲区的末尾，那么将转换尽可能多的数据; 仅转换不完整的特定数组元素或 DBCS 字符-转换前面的数组元素或字符。
4. 如果发生截断 (在转换之前或期间) ，那么为 DATLEN 参数返回的长度是截断之前 未转换 消息的长度。
5. 当在单字节字符集 (SBCS) ，双字节字符集 (DBCS) 或多字节字符集 (MBCS) 之间转换字符串时，这些字符串可以扩展或收缩。
   • 在 PCF 格式 FMADMN ， FMEVNT 和 FMPCF 中， MQCFST 和 MQCFSL 结构中的字符串会根据需要进行扩展或收缩，以适应转换后的字符串。

     对于字符串列表结构 MQCFSL ，列表中的字符串可能会扩展或收缩不同的金额。 如果发生这种情况，那么队列管理器会用空格填充较短的字符串，以使它们与转换后最长的字符串具有相同的长度。

   • 在格式 FMRMH 中，由 RMSEO， RMSNO， RMDEO和 RMDNO 字段寻址的字符串会根据需要展开或收缩，以适应转换后的字符串。
   • 在格式 FMRFH 中， RFNVS 字段会根据需要展开或签订合同，以适应转换后的 "名称/值" 对。
   • 在具有固定字段大小的结构中，如果没有重要信息丢失，那么队列管理器允许字符串在其固定字段中展开或收缩。 在此方面，字段中第一个空字符后面的尾部空格和字符被视为无关紧要。
     • 如果字符串扩展，但仅需要废弃无意义的字符以在字段中容纳转换后的字符串，那么转换将成功完成，并且调用将完成 CCOK 和原因码 RCNONE (假定没有其他错误)。
     • 如果该字符串扩展，但转换后的字符串需要废弃有效字符以适合该字段，那么将返回未转换的消息，并且调用将完成，并带有 CCWARN 和原因码 RC2190。
       注: 原因码 RC2190 导致在这种情况下是否指定了 GMATM 选项。
     • 如果该字符串合上，那么队列管理器将用空白填充该字符串以达到该字段的长度。
6. 对于由一个或多个 IBM® MQ 头结构后跟用户数据组成的消息，可以转换一个或多个头结构，而不转换消息的其余部分。 但是，除了两个例外，每个头结构中的 MDCSI 和 MDENC 字段始终正确指示跟在头结构后面的数据的字符集和编码。

   两个例外是 MQCIH 和 MQIIH 结构，其中这些结构中的 MDCSI 和 MDENC 字段中的值不重要。 对于这些结构，结构后面的数据与 MQCIH 或 MQIIH 结构本身的字符集和编码相同。

7. 如果要检索的消息的控制信息中的 MDCSI 或 MDENC 字段，或者在 MSGDSC 参数中指定未定义或不受支持的值，那么如果在转换消息时不需要使用未定义或不受支持的值，那么队列管理器可能会忽略该错误。

   例如，如果消息中的 MDENC 字段指定了不受支持的浮点编码，但该消息仅包含整数数据，或者包含不需要转换的浮点数据 (因为源和目标浮点编码相同) ，那么可能会或可能不会诊断错误。

   如果诊断出错误，那么将返回未转换的消息，完成代码 CCWARN 和 RC2111， RC2112， RC2113， RC2114 或 RC2115， RC2116， RC2117， RC2118 原因码 (视情况而定); MSGDSC 参数中的 MDCSI 和 MDENC 字段将设置为消息中的控制信息中的值。

   如果未诊断错误并且转换成功完成，那么在 MSGDSC 参数的 MDCSI 和 MDENC 字段中返回的值是由发出 MQGET 调用的应用程序指定的值。

8. 在所有情况下，如果将消息返回到未转换的应用程序，那么完成代码将设置为 CCWARN ，并且 MSGDSC 参数中的 MDCSI 和 MDENC 字段将设置为适合于未转换的数据的值。 这也是针对 FMNONE 完成的。

   REASON 参数设置为指示无法执行转换的原因的代码，除非还必须截断消息; 与截断相关的原因码优先于与转换相关的原因码。 (要确定是否转换了截断的消息，请检查 MSGDSC 参数的 MDCSI 和 MDENC 字段中返回的值。)

   诊断错误时，将返回特定原因码或一般原因码 RC2119。 返回的原因码取决于底层数据转换服务的诊断功能。

9. 如果返回完成代码 CCWARN ，并且多个原因码相关，那么优先顺序如下:
   1. 以下原因优先于所有其他原因:
      • RC2079
   2. 优先顺序中的下一个是以下原因:
      • RC2110
   3. 未定义其余原因码中的优先顺序。
10. MQGET 调用完成时:
    • 以下原因码指示消息已成功转换:
      • RCNONE
    • 以下原因码指示消息 可能 已成功转换 (请检查 MSGDSC 参数中的 MDCSI 和 MDENC 字段以查找):
      • RC2079
    • 所有其他原因码都指示未转换消息。

以下处理特定于内置格式; 它不适用于用户定义的格式:

1. 以下格式除外:
   • FMADMN
   • FMEVNT
   • FMIMVS
   • FMPCF
   • FMSTR
   对于队列名称中有效的字符，不能将任何内置格式转换为不具有 SBCS 字符的字符集。 如果尝试执行此类转换，那么将返回未转换的消息，完成代码为 CCWARN ，原因码为 RC2111 或 RC2115(视情况而定)。

   Unicode 字符集 UTF-16 是一个字符集示例，对于队列名称中有效的字符，该字符集没有 SBCS 字符。

2. 如果对内置格式的消息数据进行截断，那么不会调整消息中包含字符串长度或元素或结构计数的字段，以反映返回到应用程序的数据的长度; 对于消息数据中的此类字段返回的值是在截断之前适用于消息的值。

   处理消息 (例如截断的 FMADMN 消息) 时，必须注意确保应用程序不会尝试访问超出返回的数据末尾的数据。

3. 如果格式名称为 FMDLH ，那么消息数据以 MQDLH 结构开头，这可能后跟零个或多个字节的应用程序消息数据。 应用程序消息数据的格式，字符集和编码由消息开头的 MQDLH 结构中的 DLFMT， DLCSI和 DLENC 字段定义。 由于 MQDLH 结构和应用程序消息数据可以具有不同的字符集和编码，因此 MQDLH 结构和应用程序消息数据中的一个或两个都可能需要转换。

   根据需要，队列管理器首先转换 MQDLH 结构。 如果转换成功，或者 MQDLH 结构不需要转换，那么队列管理器会检查 MQDLH 结构中的 DLCSI 和 DLENC 字段，以查看是否需要转换应用程序消息数据。 如果需要转换，那么队列管理器将使用 MQDLH 结构中的 DLFMT 字段给出的名称来调用用户编写的出口，或者执行转换本身 (如果 DLFMT 是内置格式的名称)。

   如果 MQGET 调用返回完成代码 CCWARN ，并且原因码是指示转换不成功的原因码之一，那么下列其中一项适用:

   • 无法转换 MQDLH 结构。 在这种情况下，也不会转换应用程序消息数据。
   • 已转换 MQDLH 结构，但未转换应用程序消息数据。

   应用程序可以检查 MSGDSC 参数中的 MDCSI 和 MDENC 字段中返回的值以及 MQDLH 结构中返回的值，以确定先前应用的值。
4. 如果格式名称为 FMXQH ，那么消息数据以 MQXQH 结构开头，后面可能跟有零个或多个字节的附加数据。 此附加数据通常是应用程序消息数据 (长度可能为零) ，但在附加数据开始时，还可能存在一个或多个进一步的 IBM MQ 头结构。

   MQXQH 结构必须采用队列管理器的字符集和编码。 MQXQH 结构后面的数据的格式，字符集和编码由 MQMD 结构中的 MDFMT， MDCSI和 MDENC 字段提供，这些字段包含在 MQXQH 中 。 对于存在的每个后续 IBM MQ 头结构，结构中的 MDFMT， MDCSI和 MDENC 字段描述遵循该结构的数据; 该数据是另一个 IBM MQ 头结构或应用程序消息数据。

   如果为 FMXQH 消息指定了 GMCONV 选项，那么将转换应用程序消息数据和某些 MQ 头结构，但不会转换 MQXQH 结构中的数据。 从 MQGET 调用返回时，因此:

   • MSGDSC 参数中 MDFMT， MDCSI和 MDENC 字段的值描述 MQXQH 结构中的数据，而不是应用程序消息数据; 因此，这些值将与发出 MQGET 调用的应用程序指定的值不同。

     这样做的效果是，在每次 MQGET 调用之前，重复从指定了 GMCONV 选项的传输队列中获取消息的应用程序必须将 MSGDSC 参数中的 MDCSI 和 MDENC 字段重置为应用程序消息数据所需的值。

   • 提供的最后一个 MQ 头结构中的 MDFMT， MDCSI和 MDENC 字段的值描述了应用程序消息数据。 如果不存在其他 IBM MQ 头结构，那么应用程序消息数据由 MQXQH 结构中的 MQMD 结构中的这些字段描述。 如果转换成功，那么值将与发出 MQGET 调用的应用程序在 MSGDSC 参数中指定的值相同。

   如果消息是分发列表消息，那么 MQXQH 结构后跟 MQDH 结构 (加上其 MQOR 和 MQPMR 记录数组) ，而 MQDH 结构可能后跟零个或更多个进一步的 IBM MQ 头结构以及零个或更多字节的应用程序消息数据。 与 MQXQH 结构一样， MQDH 结构必须采用队列管理器的字符集和编码，并且不会在 MQGET 调用上进行转换，即使指定了 GMCONV 选项也是如此。

   先前描述的 MQXQH 和 MQDH 结构的处理主要供消息通道代理程序在从传输队列获取消息时使用。