CICS JSON 助手的映射级别

映射是一组规则，用于指定如何在语言结构和 JSON 模式之间转换信息。 要从可用的最复杂的映射中获益，建议您将 CICS® 助手中的 MAPPING-LEVEL 参数设置为最新级别。

每个级别的映射都继承了先前映射的功能，最高级别的映射提供了最佳的可用功能。 最高映射级别在运行时提供对数据转换的更多控制，并消除对某些数据类型和 JSON 属性支持的限制

如果要重新部署先前在该级别启用的应用程序，那么可以将 MAPPING-LEVEL 参数设置为较早的级别。

所有映射级别的限制

  • 必须显式声明 JSON 模式中使用的数据类型。
  • JSON 模式中不支持使用 $ref 对外部文档的 JSON 对象引用。

映射级别 4.3

映射级别 4.3 与 CICS TS V5.4 和更高版本兼容。

映射级别 4.3 主要用于 DFHJS2LS，但也包含在 CICS Web Service 助手， XML 助手和 JSON 助手中。 此映射级别实现对 JSON 中的多维数组的支持。

映射级别 4.2

映射级别 4.2 与 CICS TS V5.4 及更高版本兼容。

映射级别 4.2 主要用于 DFHJS2LS，但也包含在 CICS Web Service 助手， XML 助手和 JSON 助手中。 此映射级别实现对 JSON 中的 "其他属性" 的支持，并将以下三个参数引入到 DFHJS2LS: ADDITIONAL-PROPERTIES-DEFAULT， ADDITIONAL-PROPERTIES-MAX和 ADDITIONAL-PROPERTIES-SIZE。

映射级别 4.1

映射级别 4.1 与 CICS TS 5.3 区域和更高版本兼容。

映射级别 4.1 将添加到 CICS Web Service 助手， XML 助手和 JSON 助手。 此映射级别针对从现有副本自底向上生成的简单数组实施改进的映射; 它还使 CICS 能够自动检测数组中未初始化的尾部存储器，并从生成的 XML/JSON 表单中省略这些记录。

DFHLS2WS， DFHWS2LS， DFHLS2SC， DFHSC2LS， DFHJS2LS和 DFHLS2JS 支持 TRUNCATE-NULL-ARRAYS 和 TRUNCATE-NULL-ARRAY-VALUES 参数。

如果为 TRUNCATE-NULL-ARRAY-VALUES 指定任何值，那么还必须指定 TRUNCATE-NULL-ARRAYS=ENABLED。

映射级别 4.0

此映射级别提供以下支持:

在 4.0 及更高映射级别， DFHLS2JS 支持 COBOL OCCURS DEPENDING ON 子句，并支持将 COBOL 字符数组映射到 JSON 模式。 您可以使用 CICS JSON 助手上的 CHAR-OCCURS 参数设置这一行为。
  • 必须指定参数 DATA-TRUNCATION=ENABLED。
  • 不支持复合的 OCCURS DEPENDING ON。 此限制意味着仅对结构的最后一个字段支持 OCCURS 靠 ON。
  • CICS 不支持将限定名 (使用 "OF" 关键字) 作为 OCCURS BASED ON 子句的目标，例如 FIELD1 OF STRUCTURE1。
  • CICS 不支持UN定界关键字。 必须为应用程序期望的表的最大大小指定整数界限。
在映射级别 4.0 和更高版本上， JSON Web Service 支持转换使用 UTF-16 Unicode 编码的应用程序数据。
  • 使用 LS2JS时，可以通过对 UTF-16使用特定于语言的数据类型来启用此行为。
  • 使用 JS2LS时，可以通过设置 CCSID=1200来启用此行为。
  • CICS 仅支持单个 Unicode 代码页 具有 IBM® 专用区域的 UTF-16BE (CCSID 1200)。
  • 不支持转换使用 UTF-8 编码的应用程序数据。
注意： DFHLS2JS 不支持 COBOL GROUP USAGE NATIONAL 子句。

映射级别 3.0 和更高级别

此映射级别提供以下支持:

  • DFHJS2LS 将 date-time 数据类型映射到 CICS ASKTIME 格式。
  • DFHLS2JS 可以从使用多个容器而不是仅使用一个容器的应用程序生成 JSON 模式和 Web Service 绑定。
  • 容许由固定长度数据结构描述的截断数据。 您可以使用 CICS 助手上的 DATA-TRUNCATION 参数来设置此行为。

映射级别 2.2 及更高版本

保留此选项是为了与 SOAP Web Service 兼容。 建议不要与 JSON 配合使用。

映射级别 2.1 和更高级别

保留此选项是为了与 SOAP Web Service 兼容。 建议不要与 JSON 配合使用。

此映射级别包含对使用新的 INLINE-MAXOCCURS-LIMIT 参数和 CHAR-VARYING 参数上的新值处理变量内容的方式的更大控制。

在映射级别 2.1 和更高版本上， DFHJS2LS 为阵列提供以下新的改进支持:
  • INLINE-MAXOCCURS-LIMIT 参数
  • minItems 属性

INLINE-MAXOCCURS-LIMIT 参数指定是否以内联方式映射可变重复列表。 有关映射可变重复内联内容的更多信息，请参阅 DFHJS2LS中的元素的变量数组。

在映射级别 2.1 和更高版本上， DFHLS2JS 支持以下 JSON 映射:
  • COBOL 和 PL/I 中的 FILLER 字段将被忽略
  • CHAR-VARYING 参数的折叠值
  • CHAR-VARYING 参数的值 BINARY

COBOL 和 PL/I 中的 FILLER 字段会被忽略；它们不会出现在生成的 JSON 模式中，运行时会在数据结构中留下适当的空白。

折叠 会导致 CICS 忽略文本字段中的尾部空格。

BINARY 提供对二进制字段的支持。 该值在将 COBOL 转换为 JSON 模式时非常有用。 该选项仅适用于 SBCS 字符数组，允许将数组映射为包含 base64 编码数据的固定长度 JSON 字符串，而不是普通字符串。

映射级别 1.2 和更高级别

保留此选项是为了与 SOAP Web Service 兼容。 建议不要与 JSON 配合使用。

通过批处理工具上的以下附加参数，可以更好地控制在运行时变换字符和二进制数据的方式:
  • CHAR-VARYING
  • CHAR-VARYING-LIMIT
  • CHAR-MULTIPLIER
  • DEFAULT-CHAR-MAXLENGTH
如果您决定使用 DFHJS2LS中的 CHAR-MULTIPLIER 参数，请注意，在使用此参数的值来计算字符数据所需的空间量之后，以下规则适用。
  • DFHJS2LS 提供以下映射:
    • 最大长度超过 32 767 字节的可变长度字符数据类型映射到容器。 您可以使用 CHAR-VARYING-LIMIT 参数来设置下限。 将在语言结构中创建一个 16 字节的字段以存储容器的名称。 在运行时，将字符数据存储在容器中，并将容器名称放入语言结构中。
    • 对于除 C®/C++ 和 Enterprise PL/I 之外的所有语言，最大长度小于 32 768 字节的可变长度字符数据类型都映射为 VARYING 结构。 在 C/C++ 中，这些数据类型被映射为空端字符串，而在 Enterprise PL/I 中，这些数据类型被映射为 VARYINGZ 结构。 您可以使用 CHAR-VARYING 参数来选择可变长度字符数据的映射方式。
    • 最大长度小于 32 768 字节的可变长度二进制数据映射到所有语言的 VARYING 结构。 如果最大长度等于或大于 32 768 字节，那么数据将映射到容器。 将在语言结构中创建一个 16 字节的字段以存储容器的名称。 在运行时，二进制数据存储在容器中，而容器名称放置在语言结构中。

如果 JSON 模式中的字符数据类型没有与其关联的长度，那么可以使用 DFHJS2LS中的 DEFAULT-CHAR-MAXLENGTH 参数指定缺省长度。

DFHLS2JS 提供以下映射:
  • 字符字段映射到 string 数据类型，并且可以在运行时作为固定长度字段或以 null 结束的字符串进行处理。 对于除 PL/I 之外的所有语言，您可以使用 CHAR-VARYING 参数选择运行时处理变长字符数据的方式。
  • 如果数据的最大长度大于 32 767 字节或未定义长度，那么 Base64Binary 数据类型将映射到容器。 如果数据长度为 32 767 或更小，那么 base64Binary 数据类型将映射到所有语言的 VARYING 结构。

映射级别 1.1 和更高版本

保留此选项是为了与 SOAP Web Service 兼容。 建议不要与 JSON 配合使用。

此映射级别提供了 JSON 字符和二进制数据类型的改进映射，尤其是在使用 JSON 模式中的不同值定义了 maxLength 和 minLength 属性的可变长度映射数据时。 按如下所示处理数据:
  • 对于除 PL/I 之外的所有语言，固定长度大于 16 MB 的字符和二进制数据类型都会映射到容器中。在 PL/I 中，固定长度大于 32 767 字节的字符和二进制数据类型会映射到容器中。 将在语言结构中创建一个 16 字节的字段以存储容器的名称。 在运行时，将定长数据存储在容器中，并将容器名称放入语言结构中。

    由于容器的长度是可变的，因此映射到容器的固定长度数据不会填充空格或空值，也不会截断以与 JSON 模式中指定的固定长度相匹配。 如果数据的长度很重要，那么您可以编写应用程序以进行检查，或者在 CICS 区域中开启验证。 验证会对性能产生重大影响。

仅映射级别 1.1

保留此选项是为了与 SOAP Web Service 兼容。 建议不要与 JSON 配合使用。

此映射级别提供了 JSON 字符和二进制数据类型的改进映射，尤其是在使用 JSON 模式中的不同值定义了 maxLength 和 minLength 属性的可变长度映射数据时。 通过以下方式处理数据:
  • 可变长度二进制数据类型映射到容器。 将在语言结构中创建一个 16 字节的字段以存储容器的名称。 在运行时，二进制数据存储在容器中，而容器名称放置在语言结构中。
  • 最大长度大于 32 767 字节的可变长度字符数据类型映射到容器。 将在语言结构中创建一个 16 字节的字段以存储容器的名称。 在运行时，将字符数据存储在容器中，并将容器名称放入语言结构中。
  • 对于除 PL/I 之外的所有语言，固定长度小于 16 MB 的字符和二进制数据类型都映射到固定长度字段。在 PL/I 中，固定长度为 32 767 字节或更少的字符和二进制数据类型映射到固定长度字段。
  • CICS 以 hexBinary 格式 (而不是 base64Binary 格式) 对数据进行编码和解码。 JSON 模式中的 Base64Binary 数据类型映射到语言结构中的字段。 使用以下公式计算字段的大小: 4 × (ceil ( z /3)) ，其中:
    • z 是 JSON 模式中数据类型的长度。
    • ceil ( x ) 是大于或等于 x的最小整数。
    如果 z 的长度大于 24 566 字节，那么生成的语言结构无法编译。 如果 base64Binary 数据大于 24 566 字节，那么建议使用映射级别 1.2。 通过映射级别 1.2，可以将 base64Binary 数据映射到容器，而不是使用语言结构中的字段。

仅映射级别 1.0

保留此选项是为了与 SOAP Web Service 兼容。 建议不要与 JSON 配合使用。

请注意以下限制，这些限制已在以后的映射级别中修改:
  • DFHJS2LS 将 JSON 模式中的字符和二进制数据类型映射到语言结构中的固定长度字段。 查看此部分 JSON 模式:
     "example":{
"type":"string",
"maxLength":33000
    该部分 JSON 模式在 COBOL 语言结构中显示为
    15 example PIC X(33000)
  • CICS 以 hexBinary 格式 (而不是 base64Binary 格式) 对数据进行编码和解码。 DFHJS2LS 将 Base64Binary 数据映射到固定长度的字符字段，该字段的内容必须由应用程序进行编码或解码。
  • DFHLS2JS 将语言结构中的字符和二进制字段解释为固定长度字段，并将这些字段映射到具有 maxLength 属性的 JSON 字符串。 在运行时，语言结构中的字段将填充空格或空值 (如果没有足够的可用数据)。