DFHLS2JS：针对请求/响应服务的高级语言到 JSON 模式转换

DFHLS2JS 过程会从高级语言数据结构生成 JSON 模式文件。将 CICS 应用程序作为服务提供者时，可以使用 DFHLS2JS。

DFHLS2JS JCL 过程安装在数据集 HLQ.XDFHINST中，其中 HLQ 是安装了 CICS 的高级限定符。

DFHLS2JS 的作业控制语句

JOB: 启动作业。
EXEC: 指定过程名称 (DFHLS2JS)。
INPUT.SYSUT1 DD: 指定输入。输入参数通常在输入流中指定。但是，可以在数据集中或分区数据集的成员中定义这些值。

符号参数

DFHLS2JS:

JAVADIR = 路径: 指定 DFHLS2JS所使用的 Java™ 目录的名称。此参数的值将追加到 /usr/lpp/ 以生成完整路径名 /usr/lpp/ path 。; 通常，您不指定此参数。缺省值是在 JAVADIR 参数中提供给 CICS 安装作业 (DFHISTAR) 的值。
PATHPREF = 前缀: 指定扩展 z/OS UNIX 目录路径的前缀，该路径用于其他参数；如果不使用前缀，则指定 '' （空字符串）。; 通常，您不指定此参数。缺省值是在 PATHPREF 参数中提供给 CICS 安装作业 (DFHISTAR) 的值。
SERVICE = 值: 仅当 IBM 支持人员指示时才使用此参数。
TMPDIR = tmpdir: 指定 z/OS UNIX 中用作临时工作区的目录位置， DFHLS2JS。运行作业时所使用的用户标识必须具有对此目录的读和写许可权。; 缺省值为 /tmp。
TMPFILE = tmpprefix: 指定 DFHLS2JS 用于构造临时工作空间文件的名称的前缀。; 缺省值为 LS2JS。
PATHMAIN = 路径: 指定 UNIX 系统服务文件系统中 CICS TS 目录的名称。此参数的值将附加到 USSDIR 参数指定的值。; 通常，您不指定此参数。缺省值是在 USSDIR 参数中提供给 CICS 安装作业 (DFHISTAR) 的值。
USSDIR = 路径: 指定 UNIX 系统服务文件系统中 CICS TS 目录的名称。此参数的值将附加到 PATHMAIN 参数指定的值。如果使用缺省值，那么必须将此值指定为 '.' (句点)。; 通常，您不指定此参数。缺省值是在 USSDIR 参数中提供给 CICS 安装作业 (DFHISTAR) 的值。

临时工作空间

DFHLS2JS 在运行时创建以下三个临时文件:

tmpdir / tmpprefix .in
tmpdir / tmpprefix .out
tmpdir / tmpprefix .err

其中：

tmpdir 是 TMPDIR 参数中指定的值。
tmpprefix 是 TMPFILE 参数中指定的值。

当未指定 TMPDIR 和 TMPFILE 时，文件的缺省名称如下所示:

/tmp/LS2JS.in
/tmp/LS2JS.out
/tmp/LS2JS.err

重要： DFHLS2JS 不会锁定 z/OS UNIX 文件或数据集成员的访问权限。如果同时运行两个或多个 DFHLS2JS 实例并使用相同的临时工作空间文件，那么当另一个作业正在使用这些文件时，不会有任何内容阻止一个作业覆盖这些工作空间文件，这可能会导致不可预测的失败。

因此，建议您设计避免这种情况的命名约定和操作过程。例如，可以使用系统符号参数 SYSUID 来生成对单个用户唯一的工作空间文件名。在作业结束之前，将删除这些临时文件。

重要信息: 实用程序将仅在缺省 USS shell 下运行。如果您已根据 .profile 配置其他 shell (例如 bash shell) 以启动，那么该实用程序将无法运行，而不会发出任何错误消息。如果使用其他 shell ，那么在运行实用程序之前，必须更改 .profile 的配置以使用缺省 USS shell。

DFHLS2JS 的输入参数

映射级别 1.2 和更高级别

映射级别 2.1 和更高级别

映射级别 3.0 和更高级别

映射级别 4.0 和更高级别

映射级别 4.1 和更高级别

参数使用

您可以按任何顺序指定输入参数。
每个参数必须在新行开始。
参数及其连续字符（如果使用的话）的长度不能超出第 72 列；第 73 至 80 列必须包含空格。
如果参数太长，无法适合单行，请在行尾使用星号 (*) 字符来指示该参数在下一行继续。所有内容 (包括星号之前的空格) 都被视为参数的一部分。例如：
```
WSBIND=wsbinddir*
						/app1
```
等同于
```
WSBIND=wsbinddir/app1
```
行的第一个字符位置中的 # 字符是注释字符。将忽略该行。
行的最后一个字符位置中的逗号是可选的行分隔符，将被忽略。

参数描述

CCSID = 值: 指定在运行时用于对应用程序数据结构中的字符数据进行编码的 CCSID。此参数的值将覆盖 LOCALCCSID 系统初始化参数的值。 该值必须是 Java 和 z/OS Unicode Services 用户指南和参考支持的 EBCDIC CCSID。如果未指定此参数，那么将使用系统初始化参数中指定的 CCSID 对应用程序数据结构进行编码。

CHAR-VARYING = { no | NULL | COLLAPSE | BINARY }

指定当映射级别为 1.2 或更高时如何映射语言结构中的字符字段。 COBOL 中的字符字段是类型为X的Picture子句，例如 PIC(X) 10 ；而在C/C++中，字符字段则是字符数组。您可以选择以下选项：

否: 字符字段映射到 JSON 字符串并作为固定长度字段处理。数据的最大长度等于字段的长度。对于映射级别 2.0 及更早的 COBOL 和 PL/I ，"NO "是 CHAR-VARYING 参数的默认值。; 该值不适用于 Enterprise 和其他 PL/I 语言结构。
NULL: 字符字段映射到 JSON 字符串并作为以 null 结束的字符串处理。 CICS 在从 JSON 消息变换时添加终止空字符。字符串的最大长度计算为比语言结构中指示的长度少一个字符。对于 C/C++，CHAR-VARYING 参数的缺省值为 NULL。; 该值不适用于 Enterprise 和其他 PL/I 语言结构。
COLLAPSE: 字符字段映射到 JSON 字符串。字段中的尾部和嵌入的空格不会包含在 JSON 消息中; 例如， <space>AB<space><space><space>C<space> 变为 AB<space>C。解析入站 JSON 消息以除去所有前置、末尾和包含的空格。对于 COBOL 和 PL/I ，COLLAPSE 是映射级别 2.1 及以后的 CHAR-VARYING 参数的默认值。
BINARY: 字符字段映射到包含 base64 编码数据的 JSON 字符串并作为固定长度字段处理。 CHAR-VARYING 参数上的 BINARY 值仅在映射级别 2.1 及以后可用。

有关处理变长值和空白的更多信息，请参阅支持变长值和空白。

CHAR-OCCURS = { string | ARRAY }

指定当映射级别为 4.0 或更高时如何映射语言结构中的字符数组。例如，PIC X OCCURS 20。该参数仅适用于 COBOL 语言。

ARRAY: 字符数组映射到 JSON 数组。这意味着每个字符都映射为单个 JSON 元素。这也是映射级别 3.0 和更低版本的行为。
字符串: 字符数组映射到 JSON 字符串。这意味着整个 COBOL 数组被映射为一个 JSON 元素。

CHAR-USAGE = { N国际 | DBCS }

在 COBOL 中，国家数据类型 PIC N 可用于 UTF-16 或 DBCS 数据。此设置由 NSYMBOL 编译器选项控制。必须将助手上的 CHAR-USAGE 参数设置为与 NSYMBOL 编译器选项相同的值，以确保正确处理数据。使用 UTF-16 时，该值通常设置为 CHAR-USAGE=NATIONAL 。

DBCS: PIC ( n ) 字段中的数据被视为 DBCS 编码数据。
NATIONAL: PIC ( n ) 字段中的数据被视为 UTF-16 编码的数据。

CONTID = 值

在服务提供者中指定容器的名称，该容器包含用于表示 JSON 消息的顶级数据结构。

CICS 传递到目标应用程序的容器的长度大于请求容器和响应容器的长度。

DATA-SCREENING = { enabled | DISABLED }

指定是否筛选应用程序提供的数据以查找错误。

ENABLED: 将应用程序提供的与语言结构不一致的任何运行时数据视为错误，并发出消息 DFHPI1010 。系统会向应用程序返回错误响应。
DISABLED: 应用程序提供的运行时数据中与语言结构不一致的值将被缺省值替换。例如，零替换数字字段中的错误值。未发出消息 DFHPI1010 ，并且将向应用程序返回正常响应。此功能可用于避免从未初始化的输出字段中生成的 INVALID_PACKED_DEC 和 INVALID_ZONED_DEC 错误响应。

DATA-TRUNCATION = { disabled | ENABLED }

指定在固定长度字段结构中是否容许可变长度数据:

DISABLED: 如果数据小于 CICS 期望的固定长度，那么 CICS 将拒绝截断的数据并发出错误消息。
ENABLED: 如果数据小于 CICS 期望的固定长度，那么 CICS 会容许截断的数据，并将缺失的数据作为空值处理。

DATETIME = { 未使用 | PACKED15 }

指定是否将高级语言结构中的潜在 ABSTIME 字段映射为时间戳记:

PACKED15: 长度为 15（8 字节）的压缩十进制字段被视为 CICS ABSTIME 字段并映射为时间戳记。
UNUSED: 长度为 15（8 字节）的压缩十进制字段不会被视为时间戳记。

可以在映射级别 3.0设置此参数。

JSON-SCHEMA-CODEPAGE = { 本地 | UTF-8 | EBCDIC-CP-美国 }

指定用于生成 JSON 模式文档的代码页。

LOCAL: 指定使用文件系统的缺省代码页生成 JSON 模式。
UTF-8: 指定使用 UTF-8 代码页生成 JSON 模式。
EBCDIC-CP-美国: 指定使用美国 EBCDIC 代码页生成 JSON 模式。

JSON-SCHEMA-REQUEST = 值: 这是必需参数。; 该值指示存储请求 JSON 模式的 UNIX 系统服务位置。

JSON-SCHEMA-RESPONSE = 值

这是必需参数。

该值指示用于存储响应 JSON 模式的 UNIX 系统服务位置。

LANG = COBOL|PLI-ENTERPRISE|PLI-OTHER|C|CPP

指定高级语言结构的编程语言:

COBOL: COBOL
PLI-企业: Enterprise PL/I
PLI-其他: PL/I 以外的级别 Enterprise PL/I
C: C
CPP: C++

LOGFILE = 值

DFHLS2JS 写入活动日志和跟踪信息的文件的完整限定 z/OS UNIX 名称。 DFHLS2JS 创建文件，但不创建目录结构 (如果不存在)。

通常情况下，您不会用到这个文件，但如果您在部署 DFHLS2JS 或网络服务后遇到问题， IBM 服务组织可能会要求您提供该文件。

MAPPING-LEVEL = { 1.0 | 1.1 | 1.2 | 2.0 | 2.1 | 2.2 | 3.0 | 4.0 | 4.1 | 4.2 | 4.3 }

指定 DFHLS2JS 在生成 Web Service 绑定文件和 JSON 模式时使用的映射级别。您可以选择以下选项：

1.0: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
1.1: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
1.2: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
2.0: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
2.1: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
2.2: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。

3.0: 使用此映射级别可使用可用的完整选项集来生成 JSON 模式。
4.0: 在 CICS TS 5.3 或更高版本的区域中使用此映射级别。在此映射级别，您可以使用 COBOL OCCURS DEPENDING ON 字段和 CHAR-OCCURS 参数。
4.1: 如需支持可截断阵列，请将此映射级别与 CICS TS 5.3 或更高版本的区域一起使用。
4.2: 无重大更改。将此映射级别用于 CICS TS V5.4 或更高版本的区域。
4.3: 无重大更改。将此映射级别用于 CICS TS V5.4 或更高版本的区域。

有关映射级别的更多信息，请参阅 CICS JSON 助手的映射级别。

MINIMUM-RUNTIME-LEVEL = { 最小值 | 1.0 | 1.1 | 1.2 | 2.0 | 2.1 | 2.2 | 3.0 | 4.0 | 4.1 | 4.2 | 4.3 | CURRENT }

指定可将 Web Service 绑定文件部署到的最低 CICS 运行时环境。如果选择的级别与指定的其他参数不匹配，那么将接收到错误消息。您可以选择以下选项：

最小值: 将根据您选择的参数自动分配 CICS 的最低可能运行时级别。
1.0: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
1.1: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
1.2: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
2.0: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
2.1: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
2.2: 保留此选项是为了与 SOAP Web Service 兼容。建议不要与 JSON 配合使用。
3.0: 生成的 Web Service 绑定文件将部署到 CICS 区域中。
4.0: 生成的网络服务绑定文件已成功部署到 CICS TS 5.3 或更高版本的区域。通过此运行时级别，可以将映射级别 4.0 或更低版本用于 MAPPING-LEVEL 参数。可以在此级别使用任何可选参数。
4.1: 生成的网络服务绑定文件已成功部署到 CICS TS 5.3 或更高版本的区域。通过此运行时级别，可以将映射级别 4.1 或更低版本用于 MAPPING-LEVEL 参数。
4.2: 生成的 Web Service 绑定文件已成功部署到 CICS TS 5.4或更高版本的区域中。通过此运行时级别，可以将映射级别 4.2 或更低版本用于 MAPPING-LEVEL 参数。
4.3: 生成的 Web Service 绑定文件已成功部署到 CICS TS 5.4或更高版本的区域中。通过此运行时级别，可以将映射级别 4.3 或更低版本用于 MAPPING-LEVEL 参数。
CURRENT: 生成的 Web Service 绑定文件将成功部署到与您用于生成 Web Service 绑定文件的运行时级别相同的 CICS 区域中。

PDSLIB = 值

指定包含要处理的高级语言数据结构的分区数据集的名称。用于请求和响应的数据集成员在 REQMEM 和 RESPMEM 参数中指定。

限制: 分区数据集中的记录的固定长度必须为 80 个字节。

PDSCP = 值

指定在 REQMEM 和 RESPMEM 参数中指定的分区数据集成员中使用的代码页，其中 value 是 CCSID 编号或 Java 代码页编号。如果未指定此参数，那么将使用 z/OS UNIX System Services 代码页。例如，可以指定 PDSCP = 037。

PGMINT = { CHANNEL | COMMAREA }

对于服务提供者，指定 CICS 如何将数据传递到目标应用程序:

CHANNEL

CICS 使用通道接口将数据传递到目标应用程序。

在 3.0之前的映射级别中，通道只能包含一个用于输入和输出的容器。使用 CONTID 参数来指定容器的名称。缺省名称为 DFHWS-DATA。
在映射级别 3.0，通道可以包含多个容器。使用 REQUEST-CHANNEL 和 RESPONSE-CHANNEL 参数。请勿指定 PDSLIB ， REQMEM 或 RESPMEM。

COMMAREA

CICS 使用通信区域将数据传递到目标应用程序。

当目标应用程序处理请求时，它必须使用相同的机制返回响应。如果在通信区接收请求，那么必须在通信区返回响应；如果在容器中接收请求，那么必须在容器中返回响应。 CICS 传递到目标应用程序的通信区域或容器的长度大于请求通信区域或容器以及响应通信区域或容器的长度。

PGMNAME = 值

指定作为 Web Service 公开的目标应用程序的 CICS PROGRAM 资源的名称。 CICS Web Service 支持链接到此程序。

REQMEM = 值

指定包含 Web Service 请求的高级语言结构的分区数据集成员的名称。对于服务提供者，Web Service 请求是应用程序的输入。

REQUEST-CHANNEL = 值

指定通道描述文档的名称和位置。该通道描述说明了一些容器，Web Service 提供者在从 Web Service 请求程序接收到 JSON 消息时可以在其接口中使用这些容器。通道描述是必须符合 CICS 提供的通道模式的 XML 文档。更多信息，请参阅创建通道说明文档。

只能在映射级别 3.0 使用此参数。

RESPMEM = 值

指定包含 Web Service 响应的高级语言结构的分区数据集成员的名称。对于服务提供者， Web Service 响应是应用程序的输出。

RESPONSE-CHANNEL = 值

指定通道描述文档的名称和位置。该通道描述说明了一些容器，Web Service 提供者在向 Web Service 请求程序发送 JSON 响应消息时可以在其接口中使用这些容器。通道描述是必须符合 CICS 提供的通道模式的 XML 文档。更多信息，请参阅创建通道说明文档。

只能在映射级别 3.0 使用此参数。

STRUCTURE = ( 请求，响应 )

仅对于 C 和 C++ ，指定在 REQMEM 和 RESPMEM 参数中指定的分区数据集成员中包含的高级结构的名称:

请求: 指定指定 REQMEM 参数时包含请求的高级结构的名称。缺省值为 DFHREQUEST。; 分区数据集成员必须包含具有指定名称的高级结构或名为 DFHREQUEST 的结构 (如果未指定名称)。
响应: 指定指定 RESPMEM 参数时包含响应的高级结构的名称。缺省值为 DFHRESPONSE。; 如果指定值，那么分区数据集成员必须包含具有指定名称的高级结构或名为 DFHRESPONSE 的结构 (如果未指定名称)。

SYNCONRETURN = { NO | YES }

指定远程 Web Service 是否可以发出一个同步点。

否: 远程 Web Service 不能发出一个同步点。该值为缺省值。如果远程 Web Service 发出一个同步点，那么它将发生 ADPL 异常终止。
YES: 远程 Web Service 可以发出一个同步点。如果选择 YES ，那么当控制从远程 Web Service 返回时，远程任务将作为单独的工作单元落实。如果远程 Web Service 更新了一个可恢复的资源并且在返回资源后发生故障，那么将无法回退对该资源的更新。

TRANSACTION = 名称

在服务提供者中，此参数指定可启动管道的别名事务的 1 到 4 个字符的名称。当使用 PIPELINE 扫描命令自动创建 URIMAP 资源时，此参数的值用于定义该资源的 TRANSACTION 属性。

可接受的字符: A-Z a-z 0-9 $ @ # _ < >

TRUNCATE-NULL-ARRAYS = { disabled | ENABLED }

指定如何在映射级别 4.1 或更高级别处理结构化数组。如果启用， CICS 将尝试识别数组中的空记录 (请参阅 TRUNCATE-NULL-ARRAY-VALUES 以获取有关标识空记录的更多信息)。如果检测到五个连续的空数组记录，那么在生成 XML/JSON 时，将在第一个此类记录处截断该数组。仅对具有结构化内容的数组启用此截断功能，简单原始字段的数组不进行截断。数组截断可能导致 JSON/XML 中数据的更简明表示，但这并非没有风险。如果五个连续的数据记录被错误地识别为未初始化的存储 (可能是因为它们合法地包含低值) ，那么可能会发生数据丢失。如果已启用 TRUNCATE-NULL-ARRAY ，并且未设置 TRUNCATE-NULL-ARRAY-VALUES ，那么将使用 TRUNCATE-NULL-ARRAY-VALUES 的缺省值。

TRUNCATE-NULL-ARRAY-VALUES = { 空 | PACKEDZERO |SPACE | ZERO }

指定在映射级别 4.1 或更高级别的 TRUNCATE-NULL-ARRAY 处理将哪些值视为空值。缺省情况下，空值 (0x00或低值) 被视为空值。如果结构化数组的记录中的所有存储字节都包含空值，那么将整个记录视为空。可以在以逗号分隔的列表中指定一个或多个 NULL ， PACKEDZERO ， SPACE 和 ZERO 值。

NULL: 暗示空字符 (0x00)。
软件包 EDZERO: 表示正带符号压缩十进制零 (0x0C) ，负带符号压缩十进制零 (0x0D) 或无符号压缩十进制零 (0x0F)。
空间: 暗示 SBCS EBCDIC 空间 (0x40)。
零: 暗示无符号分区十进制零 (0xF0)。

结构化数组记录中所选字节的任何匹配组合都会导致将整个记录被标识为空。

如果 TRUNCATE-NULL-ARRAY-VALUES 定义了值，那么必须启用 TRUNCATE-NULL-ARRAY 。

URI = 值

此参数指定客户机用于访问 Web Service 的相对或绝对 URI。 CICS 使用从 DFHLS2JS创建的 Web Service 绑定文件生成 URIMAP 资源时指定的值。该参数指定 URIMAP 定义所应用于的 URI 的路径部分。

USERID = 标识

在服务提供者中，此参数指定一个 1 到 8 个字符的用户标识，可供任何 Web 客户机使用。对于应用程序生成的响应或 Web Service ，将在此用户标识下附加别名事务。当使用 PIPELINE 扫描命令自动创建 URIMAP 资源时，此参数的值用于定义该资源的 USERID 属性。

可接受的字符: A-Z a-z 0-9 $ @ #

WSBIND = 值

网络服务绑定文件的完整 z/OS UNIX 名称。 DFHLS2JS 创建文件，但不创建目录结构 (如果不存在)。文件扩展名为 .wsbind。

其他信息

必须将 DFHLS2JS 用于运行的用户标识配置为使用 UNIX 系统服务。用户 ID 必须具有 CICS z/OS UNIX 文件结构和 PDS 库的读取权限，以及 LOGFILE 、 WSBIND 和 JSON Schema 参数指定目录的写入权限。
用户标识必须具有足够大的存储器分配才能运行 Java。
JCL 的最大参数长度为 100 个字符。使用 STDPARM 语句可增加该参数长度，详情请参见 z/OS UNIX System Services 《用户指南》。

示例

//LS2JS JOB 'accounting information',name,MSGCLASS=A
// SET QT=''''
//JAVAPROG EXEC DFHLS2JS,
// TMPFILE=&amp;QT.&SYSUID.&QT,
//INPUT.SYSUT1 DD *
PDSLIB=CICSHLQ.SDFHSAMP
REQMEM=DFH0XCP4
RESPMEM=DFH0XCP4
JSON-SCHEMA-REQUEST=/u/exampleapp/json/example_request.json
JSON-SCHEMA-RESPONSE=/u/exampleapp/json/example_response.json
LANG=COBOL
LOGFILE=/u/exampleapp/wsbind/example.log
MAPPING-LEVEL=4.0
CHAR-VARYING=COLLAPSE
PGMNAME=DFH0XCMN
URI=http://myserver.example.org:8080/exampleApp/example
PGMINT=COMMAREA
SYNCONRETURN=YES
WSBIND=/u/exampleapp/wsbind/example.wsbind
/*