JSON 模式到 PL/I 映射

DFHJS2LS 实用程序支持 JSON 模式和 PL/I 数据结构之间的映射。 由于 Enterprise PL/I 编译器与较早的 PL/I 编译器有所不同,因此支持以下两种语言选项:PLI-ENTERPRISEPLI-OTHER

将模式元素名称映射到 PL/I 的规则

CICS® 助手使用以下规则为模式元素名称中的 PL/I 变量生成唯一且有效的名称:
  1. 将 A-Z , a-z , 0-9 , @ , # , _ 或 $以外的字符替换为 " X '。

    例如,monthly-total 变为 monthlyXtotal

    您可以使用 MAPPING-OVERRIDES 参数来更改处理其他字符的方式。 例如,如果设置值 HYPHENS-AS-UNDERSCORES ,那么 JSON 模式中的任何连字符都将转换为下划线而不是 X。 例如, monthly-total 变为 monthly_total

  2. 将通过为第二个及后续名称实例添加一个或两个数字位来使同一范围内的重复名称唯一。

    例如,三个 year 实例变为 yearyear1year2

    如果不希望出现上述行为,那么用户可以将 MAPPING-OVERRIDES=NO-ARRAY-NAME-INDEXING 指定为实用程序的输入,这将禁止将一个或两个数字数字添加到名称的第二个实例和后续实例中。

  3. JSON 模式指定变量具有不同的基数 (如果其 "type" 值为 "array" ) ,并且省略了关键字 "minItems""maxItems" 或具有不同的值。 如果此模式指定该变量具有可变基数,那么将使用 "_cont""_num" 后缀创建字段名称。

    有关更多信息,请参阅 DFHJS2LS

  4. 如果变量未出现在与 JSON 模式 "object" 类型相关的 "required" 关键字数组中,那么 JSON 模式指定该变量可选。 针对可选字段,会生成其他字段,且会向元素名称添加后缀 _num 在运行时,如果这为零,那么指示 JSON 数据中不存在该值,如果为非零,那么指示 JSON 数据中存在该值。
  5. 将字段名称限制在 31 个字符。 如果生成的名称(包含任何前缀和后缀)超出此长度,那么将截断此元素名称。
生成名称的总长度最多 31 个字符。

将模式类型映射到 PL/I 的规则

DFHJS2LS 根据下表将模式类型值映射到 PL/I 数据类型。 另请注意以下几点:
  • 如果 MAPPING-LEVEL 参数设置为 1.2 或更高版本,并且 CHAR-VARYING 参数设置为 NULL ,那么变长字符数据将映射到以 null 结束的字符串,并为 null 终止符分配额外的字符。
  • 如果 MAPPING-LEVEL 参数设置为 1.2 或更高版本,并且未指定 CHAR-VARYING 参数,那么缺省情况下,变长字符数据将映射到 Enterprise PL/I 的 VARYINGZ 数据类型和其他 PL/I 的 VARYING 数据类型。
  • 可变长度二进制数据映射到 VARYING 数据类型 (如果它小于 32 768 字节) 和容器 (如果它超过 32 768 字节)。
JSON 模式关键字 PL/I 数据描述
所有以下项:
"type":"null"
"type": []
"allOf"
"anyOf"
"noneOf"
"not"

不支持

"$schema":"http://json-schema.org/draft-04/schema#"

将忽略此关键字,但假定它符合草稿 04 JSON 模式规范。

"title": "same text"
"description": "more text"

将忽略这些关键字。

"format": "<predefined values>"

关键字 "format" 用于修改已生成的结构或运行时值。 请参阅以下信息,了解有关对 "format" 的受支持使用信息。

"type":
"array",
"items": {<JSON Sub-schema>},
"additionalItems": false,
"maxItems":
m
,
"minItems":
n

从映射级别 4.3 或更高版本支持多维数组,不支持混合类型数组。

"additionalItems" 假定为 false,并且不支持任何其他值。

如果同时存在 "minItems""maxItems" 并且它们相等,那么会将数组视为固定基数,否则,会将其视为变化的基数。 请参阅 DFHJS2LS中的元素变量数组

"type": "array",
"uniqueItems": true

"uniqueItems" 不受 JSON 数组支持。 <JSON Sub-schema> 必须定义受支持的 "type" ,但该 "type" 不能为 "array" 。 这是对生成的语言结构的限制。

"type": "object",
"additionalProperties": false,
"properties": { [ "<element name>": {<JSON Sub-schema>} [,] ]* }
"required": [ [ "<element name>" [,] ]* ]

当前受支持的唯一 JSON 对象格式是命名元素的固定集合。

这将使用元素名称生成结构(或子结构)。

如果未在 ADDITIONAL-PROPERTIES-DEFAULT 参数中设置值,那么假定 "additionalProperties"false

如果 "properties" 对象中的任何元素不在 "required" 数组中,或者不存在 "required" 数组,那么会将其视为 "optional""optional" 元素被指定为一个从零到 X 的可变序数;其中 X 是 1 或者将项目定义为数组的数组中项目的最大数目。 请参阅 DFHJS2LS中的元素变量数组

"type": "object",
"additionalProperties": true
对象与上一个示例一样映射,具有支持其他属性的其他字段。 如果未在 ADDITIONAL-PROPERTIES-DEFAULT 参数中设置,那么假定 additionalProperties 属性为 false。

如果启用此选项,那么将分配最多为 ADDITIONAL-PROPERTIES-MAX 参数中指定的值的空间。 每个空格中的字符数由 ADDITIONAL-PROPERTIES-SIZE 参数设置。 每个单独的属性都映射到一个 PIC X(z) 字段,其中 zADDITIONAL-PROPERTIES-SIZE 参数定义。 如果 ADDITIONAL-PROPERTIES-MAX 的值大于 0 ,那么将以与设置了 maxItems 的数组相同的方式映射属性。

注: 可以通过多种方法在 CICS中配置 JSON 支持,包括使用 z/OS Connect for CICS。 如果您正在使用较旧的 CICS Java 管道技术,那么仅当 com.ibm.cics.json.enableAxis2Handlers JVM 系统属性未设置为 true 时,才支持 Additional Properties
"type": "object",
"maxProperties": m,
"minProperties": n,
"patternProperties": {},
"dependencies":

这些关键字中没有任何一个受 JSON 对象支持。


"type":"string"
"maxLength":
m
"pattern": "regular expression>",
"minLength":
l

char[ z ]

其中 z 的值基于 m ,但取决于 CHAR-VARYING 参数的设置。

m 基于 "maxLength" 关键字,并且被视为固定长度字符串。

"pattern""minLength" 限制只作为注释传递到语言结构。


"type":"string"
"maxLength":
m

当 CCSID=1200 处于映射级别 4.0 及更高版本时:

WIDECHAR( z )

其中 z 的值基于 m ,但取决于 CHAR-VARYING 参数的设置。

m 基于 "maxLength " 并被视为固定长度字符串。

"*name*":{ 
"type":"string",
   "format":"date-time"
}

FIXED DECIMAL (15,0)

DATETIME=PACKED15 时全部受支持

"*name*":{ 
"type":"string",
   "format":"uri"
}

CHAR( m )

其中 m 基于 "maxLength" 关键字,并且被视为固定长度字符串。

CCSID=1200 处于映射级别 4.0 及更高版本时:

WIDECHAR( m )

其中 m 基于 "maxLength" 关键字,并且被视为固定长度字符串。

"*name*":{ 
"type":"string",
   "format":"base64Binary"
}

CHAR( m )

其中 m 基于 "maxLength" 关键字。

"*name*":{ 
"type":"string",
   "format":"hexBinary"
}

CHAR( m )

其中 m 基于 "maxLength" 关键字。

"*name*":{ 
"type":"string",
   "format":"<predefined>"
}

CHAR( m ) 其中 m 基于 "maxLength" 关键字并被视为固定长度字符串, <predefined> 是下列其中一项: emailhostnameipv4ipv6。 相关 "pattern" 将传递到注释。

CCSID=1200 处于映射级别 4.0 及更高版本时:

WIDECHAR( m )

其中 m 基于 "maxLength" 关键字并视为固定长度字符串,而 <predefined> 是下列其中一项: emailhostnameipv4ipv6 。 将使用相关 "pattern" 并传递到注释。

"type":"boolean"
映射级别 1.1 和更低版本:
企业 PL/I
SIGNED FIXED BINARY (7)
其他 PL/I
FIXED BINARY (7)
映射级别 1.2 及更高版本:
企业 PL/I
BIT(7)
BIT(1)
其他 PL/I
BIT(7)
BIT(1)

其中,BIT(7) 是为对齐提供,BIT(1) 包含布尔映射值。

"type": "integer",
"exclusiveMaximum": true,
"exclusiveMinimum": true,
"multipleOf": n

"exclusiveMaximum""exclusiveMinimum" 限制仅作为注释传递到语言结构。

将忽略 "multipleOf"

"type":"integer",
minimum:-128,
maximum:127
企业 PL/I
SIGNED FIXED BINARY (7)
其他 PL/I
FIXED BINARY (7)
"type":"integer",
minimum:0,
maximum:255
企业 PL/I
UNSIGNED FIXED BINARY (8)
其他 PL/I
FIXED BINARY (8)
"type":"integer",
minimum:-32768,
maximum:32767
企业 PL/I
SIGNED FIXED BINARY (15)
其他 PL/I
FIXED BINARY (15)
"type":"integer",
minimum:0,
maximum:65535
企业 PL/I
UNSIGNED FIXED BINARY (16)
其他 PL/I
FIXED BINARY (16)
"type":"integer",
minimum:-2147483648,
maximum:2147483647
企业 PL/I
SIGNED FIXED BINARY (31)
其他 PL/I
FIXED BINARY (31)
"type":"integer",
minimum:0,
maximum:4294967295
映射级别 1.1 和更低版本:
企业 PL/I
UNSIGNED FIXED BINARY(32)
映射级别 1.2 及更高版本:
企业 PL/I
CHAR( y )

其中,y 是小于 16 MB 的固定长度。

所有映射级别:
其他 PL/I
BIT(64)
"type":"integer",
minimum:-9223372036854775808,
maximum:9223372036854775807
映射级别 1.1 和更低版本:
企业 PL/I
SIGNED FIXED BINARY(63)
注: LIMITS 编译器伪指令可能会影响 PL/I 编译器解释此字段的方式。 CICS 期望该字段具有声明的大小,但编译器可能会将该字段优化为更小的空间,这可能会导致不匹配。 要避免此类问题,请使用 LIMITS (FIXEDBIN (63)) 编译时选项。
映射级别 1.2 及更高版本:
企业 PL/I
CHAR( y )

其中,y 是小于 16 MB 的固定长度。

所有映射级别:
其他 PL/I
BIT(64)
"type":"integer",
minimum:0,
maximum:18446744073709551615
映射级别 1.1 和更低版本:
企业 PL/I
UNSIGNED FIXED BINARY(64)
注: LIMITS 编译器伪指令可能会影响 PL/I 编译器解释此字段的方式。 CICS 期望该字段具有声明的大小,但编译器可能会将该字段优化为更小的空间,这可能会导致不匹配。 要避免此类问题,请使用 LIMITS (FIXEDBIN (63)) 编译时选项。
映射级别 1.2 及更高版本:
企业 PL/I
CHAR( y )

其中,y 是小于 16 MB 的固定长度。

其他 PL/I
BIT(64)
"type":"number"
"description":"decimal"
FIXED DECIMAL( n , m )
"type":"number"
"description":"float"
映射级别 1.0 和 1.1:
  • CHAR(32)
映射级别 1.2 及更高版本:
企业 PL/I
DECIMAL FLOAT(6) HEXADEC
其他 PL/I
DECIMAL FLOAT(6)
注: IBM® 十六进制浮点 (HFP) 数据表示与用于 JSON 的 IEEE-754-1985 表示不完全相同。 某些值可能无法正好从一种表示法转换为另一种表示法。 对于浮点数据类型,某些极大或极小值可能无效。 在转换到或转换自 HFP 表示法时,某些值可能会失去精度。 如果精确转换很重要,请考虑将 DECIMAL FLOAT 数据类型的使用替换为固定精度替代方法。
"type":"number"
"description":"double"
映射级别 1.0 和 1.1:
  • CHAR(32)
映射级别 1.2 及更高版本:
企业 PL/I
DECIMAL FLOAT(16) HEXADEC
其他 PL/I
DECIMAL FLOAT(16)
注: IBM 十六进制浮点 (HFP) 数据表示与用于 JSON 的 IEEE-754-1985 表示不完全相同。 某些值可能无法正好从一种表示法转换为另一种表示法。 对于浮点数据类型,某些极大或极小值可能无效。 在转换到或转换自 HFP 表示法时,某些值可能会失去精度。 如果精确转换很重要,请考虑将 DECIMAL FLOAT 数据类型的使用替换为固定精度替代方法。

oneOf: [ { "properties": { "A": {...} } } ,
    { "properties": { "B": {...} } } ]
anyOf: [ { "properties": { "A": {...} } } ,
    { "properties": { "B": {...} } } ]
allOf: [ { "properties": { "A": {...} } } ,
    { "properties": { "B": {...} } } ]

通过选项数组的逻辑路径将合并在一起,就像定义了类型为 { "properties": { "A":..., "B":... } }的单个对象一样。 每个 JSON 属性都被视为可选属性。 如果子选项包含相同属性名的冲突定义,那么将发出错误消息; 例如,如果单个属性同时定义为字符串 (在路径 A 中) 和对象 (在路径 B 中) ,那么此类定义不受支持,并且将生成错误消息。

JSON 模式可以定义复杂逻辑结构; 但是,在到语言结构的映射中,复杂逻辑结构中隐含的微妙关系可能会丢失。 变换过程不会尝试从模式强制实施组合规则; 它仅与指示给定 JSON 属性是存在还是不存在的语言结构字段进行交互。

如果子选项包含相同属性名的兼容定义,那么 DFHJS2LS 会尝试合并关联的约束模式,但在此过程中可能会丢失某些子项。 例如,假定以下定义:
"A": { "oneOf": [ { "type": "string", "maxLength": 5}, {"type": "string",
      "minLength": 7, "maxLength": 8} ] }
"A" 定义为长度最多为 5 个字符的字符串或长度在 7 到 8 个字符之间的字符串。 合并的组合可能会导致映射到长度介于 0 和 8 个字符之间的字符串,而不会识别 6 个字符的长度无效。

大多数涉及逻辑组合的场景将映射到简单的语言结构,但复杂的逻辑组合可能会在映射过程中导致妥协。 为了获得最佳结果,请避免在 JSON 模式中使用逻辑组合来定义同一 JSON 属性的备用声明。

注: CICS 不能变换大于带符号长整型 (2 ^ 63-1) 的最大值的整数值,除非将其括在引号内。
注: 在模式中为数字类型指定的最小值和最大值仅用于映射到 PL/I 数据类型。 在运行时不会针对这些值验证数据。