JSON 模式到 COBOL 的映射

DFHJS2LS 实用程序支持 JSON 模式与 COBOL 数据结构之间的映射。

如何将 JSON 模式元素名称转换为 COBOL

CICS® 助手通过使用以下规则,根据模式元素名称为 COBOL 变量生成唯一、有效的字段名:

  1. COBOL 保留字的前缀为 " "。 X

    例如,DISPLAY 变为 XDISPLAY

  2. 除 A-Z , a-z , 0-9 或连字符以外的字符将替换为 " X '。

    例如,monthly_total 变为 monthlyXtotal

  3. 如果最后一个字符是连字符,那么它将替换为 " X '。

    例如,ca-request- 变为 ca-requestX

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

    例如,三个 year 实例变为 yearyear1year2

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

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

    有关更多信息,请参阅 DFHJS2LS

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

如何将 JSON 模式类型映射到 COBOL

DFHJS2LS 根据表 1 ,使用指定的映射级别将模式类型映射到 数据描述元素。 COBOL 请注意以下几点:
  • 如果 MAPPING-LEVEL 参数设置为 1.2 或更高版本,并且 CHAR-VARYING 参数设置为 NULL ,那么变长字符数据将映射到以 null 结束的字符串,并为 null 终止符分配额外的字符。
  • 如果 MAPPING-LEVEL 参数设置为 1.2 或更高版本,并且 CHAR-VARYING 参数设置为 YES ,那么可变长度字符数据将映射到两个相关元素: 长度字段和数据字段。 例如:
    "textString": {
        "type":"string",
        "maxLength":10000,
        "minLength":1
                   }
    映射到:
    15 textString-length PIC S9999 COMP-5 SYNC
    15 textString PIC X(10000)
表 1. JSON 模式类型的映射参考
JSON 模式关键字 COBOL 数据描述
所有以下项:
"type":"null"
"type": []

不支持

"$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 数组支持。

"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 Pipeline技术, Additional Properties 则仅当 JVM 系统 com.ibm.cics.json.enableAxis2Handlers 属性未设置为true时才受支持。
"type": "object",
"maxProperties": m,
"minProperties": n,
"patternProperties": {},
"dependencies":

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

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

PIC X( z )

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

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

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

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

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

PIC N( z ) USAGE NATIONAL

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

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

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

PIC S9(15) COMP-3

当 DATETIME=PACKED15 时全部受支持

请注意,此格式不支持 "maxLength""minLength"

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

PIC X( m )

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

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

PIC N(m) USAGE NATIONAL

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

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

PIC X( m )

其中 m 基于 "maxLength" 关键字

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

PIC X( m )

其中 m 基于 "maxLength" 关键字

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

PIC X( m )

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

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

PIC N( m ) USAGE NATIONAL

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

"type":"boolean"

PIC X DISPLAY

x'00' 表示 false,而 x'01' 表示 true。

"type": "integer",
"exclusiveMaximum": true,
"exclusiveMinimum": true,
"multipleOf": n
"exclusiveMaximum""exclusiveMinimum" 限制仅作为注释传递到语言结构。

将忽略 "multipleOf"

"type"="integer",
minimum=0,
maximum=255

映射级别 3.0 及更低版本:

PIC X DISPLAY

映射级别 4.0 及更高版本 (或者当指定了 INTEGER-AS-PIC9 参数时,无论映射级别如何):

PIC 9( z ) COMP-5 SYNC

PIC 9( z ) DISPLAY

其中 10-1) <<= 10

"type":"integer",
minimum:-128,
maximum:127

映射级别 3.0 及更低版本:

PIC X DISPLAY

映射级别 4.0 及更高版本 (或者当指定了 INTEGER-AS-PIC9 参数时,无论映射级别如何):

PIC S9( z ) COMP-5 SYNC

PIC S9( z ) DISPLAY

其中 10-1) <<= 10

"type":"integer",
minimum:0,
maximum;m

PIC 9( z ) COMP-5 SYNC

PIC 9( z ) DISPLAY

其中 10-1) <<= 10

"type":"integer",
minimum:-m,
maximum:m-1

PIC S9( z ) COMP-5 SYNC

PIC S9( z ) DISPLAY

其中 10-1) <<= 10

"type": "number",
"maximum": m,
"minimum": n,
"exclusiveMaximum": true,
"exclusiveMinimum": true,
"multipleOf": n

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

将忽略 "multipleOf"

"type":"number"
"format":"decimal"

PIC 9( p )V9( n ) COMP-3

其中,pn 是缺省值。

"type":"number"
"format":"float"
映射级别 1.1 和更低版本:
  • PIC X(32)
映射级别 1.2 及更高版本:
  • COMP-1
注: IBM® 十六进制浮点 (HFP) 数据表示与用于 JSON 的 IEEE-754-1985 表示不完全相同。 某些值可能不会精确从一个表示转换为另一个表示。

对于浮点数据类型,某些极大或极小值可能无效。 转换为 HFP 表示或从 HFP 表示转换时,某些值可能会不精确。 如果精确转换很重要,请考虑将 COMP-1 数据类型的使用替换为固定精度替代方法。

"type":"number"
"format":"double"
映射级别 1.1 和更低版本:
  • PIC X(32)
映射级别 1.2 及更高版本:
  • COMP-2
注: IBM 十六进制浮点 (HFP) 数据表示与用于 JSON 的 IEEE-754-1985 表示不完全相同。 某些值可能不会精确从一个表示转换为另一个表示。

对于双精度数据类型,某些极大或极小值可能无效。 转换为 HFP 表示或从 HFP 表示转换时,某些值可能会不精确。 如果精确转换很重要,请考虑将 COMP-2 数据类型的使用替换为固定精度替代方法。

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} ] }

定义为长度最多为 5 个字符的字符串或长度在 7 到 8 个字符之间的字符串。 合并的组合可能会导致映射到长度介于 0 和 8 个字符之间的字符串,而不会识别 6 个字符的长度无效。

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

注:
  • CICS 无法变换大于有符号长整型 (2 ^ 63-1) 的最大值的整数值,除非将其括在引号内。
  • 模式中为数值类型指定的最小值和最大值仅用于映射到 COBOL 数据类型。 在运行时,没有根据这些值验证数据。
表 1 中显示的某些模式类型映射到 COBOL 格式 COMP-5 SYNC 或 DISPLAY,具体取决于 minimummaximum 关键字中指定的值(如果有):
  • 对于已签名类型 ( shortintlong ) ,指定以下内容时将使用 DISPLAY:
    "maximum":a
    "minimum":-a
    其中,a 是一个包含多个“9”的字符串。
  • 对于无符号类型 ( unsignedShortunsignedIntunsignedLong ) ,将在指定以下内容时使用 DISPLAY:
    "maximum":a
    "minimum":0
    其中,a 是一个包含多个“9”的字符串。
  • 当指定了任何其他值,或未指定任何值时,将使用 COMP-5 SYNC。