AWS 大型机现代化服务（托管运行时环境体验）不再向新客户开放。有关类似于 AWS 大型机现代化服务（托管运行时环境体验）的功能，请浏览 AWS 大型机现代化服务（自我管理体验）。现有客户可以继续正常使用该服务。有关更多信息，请参阅[AWS 大型机现代化可用性变更](https://docs.aws.amazon.com/m2/latest/userguide/mainframe-modernization-availability-change.html)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 数据集实用工具
## BLUESAMCOPY/BLUESAMCREATE/BLUESAMDELETE/BLUESAMCLEAR
这些实用程序在 [Blusam](https://docs.aws.amazon.com/m2/latest/userguide/ba-shared-blusam.html) 数据集上提供了基本的数据集操作功能。
标`bypassBluesamStatus`志（存储在 JobContext）决定是否绕过常规数据集状态验证，该验证可防止联机进程和批处理进程之间的并发访问冲突。
当 `bypassBluesamStatus` 为 true 时：
+ 在操作期间跳过常规数据集状态检查
+ 允许访问通常可能被屏蔽的数据集
### BLUESAMCOPY
BLUESAMCOPY 程序将数据和元数据结构从一个 Bluesam 数据集复制到另一个数据集。
#### 参数
BLUESAMCOPY 程序采用两个参数：
+ `FROM=`-要复制的源数据集
+ `TO=`-要复制到的目标数据集
#### 行为
+ 如果目标数据集不存在，则使用源的元数据结构创建它
+ 如果目标存在，则在复制之前将其清除（覆盖现有数据）
+ 当联机进程未使用数据集或设置`bypassBluesamStatus`为 true 时，操作将继续
+ 保留密钥、压缩、记录长度和其他元数据属性
#### 错误处理
如果源数据集不存在或者在线进程正在使用其中一个数据集，则返回代码 1。
#### 示例用法
```
import ...
mpr = applicationContext.getBean("com.netfective.bluage.gapwalk.rt.call.ExecutionController",MainProgramRunner.class)
// copy bluesam dataset
res = mpr.withArguments("FROM=MYBLUESAMTABLE","TO=MYBLUESAMTABLE2").runProgram("BLUESAMCOPY")
```
### BLUESAMCREATE
BLUESAMCREATE 程序使用指定的参数创建一个 Bluesam 数据集。
#### 参数
BLUESAMCREATE 程序需要七个参数：
+ `name=`-要创建的数据集（必填）
+ `compress=`-启用压缩（可选，默认值：false）
+ `fixedLength=`-固定长度的记录状态（可选，默认值：false）
+ `recordLength=`-以字节为单位的记录长度（可选，默认值：-1）
+ `primaryKey=,duplicates=,fields=`-主键规范（可选）
+ `key=,duplicates=,fields=`-备用密钥（可以有多个或 0）
+ `clearExisting=true/false`-清除现有数据集（可选默认值：true）
具体按键参数说明：
+ `duplicates`: 给定密钥是否允许重复值；
+ `fields`: 字段位置（从 1 开始）和定义密钥的长度；
#### 行为
+ 如果数据集不存在，则使用指定的参数创建它
+ 如果数据集存在，则在以下情况下将其清除 `clearExisting=true`
+ 当联机进程未使用数据集或设置`bypassBluesamStatus`为时，操作将继续 `true`
#### 错误条件
在所有情况下都返回代码 0。
#### 示例用法
```
import ...
mpr = applicationContext.getBean("com.netfective.bluage.gapwalk.rt.call.ExecutionController",MainProgramRunner.class)
// create bluesam dataset
mpr.withArguments(
"name=MYBLUESAMTABLE",
"compress=FALSE",
"fixedLength=true",
"recordLength=54",
"primaryKey=MYKEY_PK,duplicates=FALSE,fields=0,6")
.runProgram("BLUESAMCREATE")
```
### BLUESAMDELETE
BLUESAMDELETE 程序会删除 Bluesam 数据集。
#### 参数
BLUESAMDELETE 程序需要 1 个或多个参数：
+ ``-要删除的数据集（可以有多个）
#### 行为
+ 当联机进程未使用数据集或设置`bypassBluesamStatus`为时，操作将继续 `true`
+ 如果数据集存在，请将其删除
#### 错误条件
在所有情况下都返回代码 0。
#### 示例用法
```
import ...
mpr = applicationContext.getBean("com.netfective.bluage.gapwalk.rt.call.ExecutionController",MainProgramRunner.class)
// delete bluesam datasets
res = mpr.withArguments("MYBLUESAMTABLE","MYBLUESAMTABLE2","MYBLUESAMTABLE3").runProgram("BLUESAMDELETE")
```
### BLUESAMCLEAR
BLUESAMCLEAR 程序从现有数据集中删除所有数据，同时保留其结构和元数据。
#### 参数
BLUESAMCLEAR 程序需要 1 个或多个参数：
+ ``-要清除的数据集（可以有多个）
#### 行为
+ 当联机进程未使用数据集或设置`bypassBluesamStatus`为时，操作将继续 `true`
+ 如果数据集存在，请将其清除
#### 错误条件
在所有情况下都返回代码 0。
#### 示例用法
```
import ...
mpr = applicationContext.getBean("com.netfective.bluage.gapwalk.rt.call.ExecutionController",MainProgramRunner.class)
// clear bluesam datasets
res = mpr.withArguments("MYBLUESAMTABLE","MYBLUESAMTABLE2").runProgram("BLUESAMCLEAR")
```
## BPXWDYN
该实用程序模拟 z/OS BPXWDYN 服务，用于动态数据集分配和解除分配。在现代应用程序中，文件分配是通过`FileConfigurationUtils`生成器 api 在 Groovy 脚本中完成的。该程序允许在没有 Groovy 的情况下动态管理这些分配，这对于现代化应用程序中的交互式或条件文件处理至关重要。
### 参数
保留了旧的参数格式。需要一个包含一个 2 字节大小的标头和命令字符串的参数。
用于分配的命令字符串格式：`ALLOC DD() DSN('') SHR?`
用于取消分配的命令字符串格式：`FREE DD()`
### 错误处理
+ 为成功设置错误代码 0，为失败设置错误代码 1
+ RuntimeException 对无效的命令或参数进行抛出
### 示例用法
以下是 BPXWDYN 程序的 Java 示例用法，该程序源于通过 AWS 转换对 COBOL 进行现代化改造：
COBOL 代码：
```
01 WK-AREA.
03 DS-ALLOC-STRING.
05 DS-LENGTH PIC S9(004) COMP VALUE 100.
05 DS-TEXT PIC X(100) VALUE
"ALLOC DD(INFILE) DSN('A.B.JCLLIB(XYZ470)') SHR".
...
01 RC-RETURN-CODE-AREA.
03 RC-RETURN-CODE PIC S9(008) COMP.
...
CALL 'BPXWDYN' USING DS-ALLOC-STRING RETURNING RC-RETURN-CODE.
```
以及相应的 Java 现代化：
```
private final Group dsAllocString = new Group(root).named("DS-ALLOC-STRING");
private final Elementary dsLength = new Elementary(dsAllocString,new BinaryType(4, 0, "STD", false, false, true),Short.valueOf("100")).named("DS-LENGTH");
private final Elementary dsText = new Elementary(dsAllocString,new AlphanumericType(100),"ALLOC DD(INFILE) DSN('A.B.JCLLIB(XYZ470)') SHR").named("DS-TEXT");
...
private final Group root = new Group(getData()).named("RC-RETURN-CODE-AREA");
private final Elementary rcReturnCode = new Elementary(root,new BinaryType(8, 0, "STD", false, false, true)).named("RC-RETURN-CODE");
...
// Call to utility program BPXWDYN
ctrl.callSubProgram(
"BPXWDYN",
CallBuilder.newInstance().byReference(ctx.getWkArea().getDsAllocStringReference()).getArguments(), ctx);
ctx.getRcReturnCodeArea().setRcReturnCode(NumberUtils.convert(ctx.getProgramReturned()).intValue());
```
## GDGUTILS
GDGs （生成数据组）允许应用程序使用版本化数据集，其中每次执行都会创建新一代数据集，同时保持对前几代数据的访问权限。此实用程序创建并管理这些数据集的生成。此实用程序本应在 groovy 脚本中调用。
### 参数
参数顺序无关紧要
+ `action=`-要执行的操作（必须）
+ `gdgname=`-GDG 基地名称（必填）
+ `storageProvider=`-存储后端
+ `relativeGeneration=<+integer>`-相对世代号（例如，\+1 表示下一代）
+ `absoluteGeneration=integer`-绝对世代号
+ `recordLength=`-数据集中的记录大小
+ `fixedLength=`-指定数据集中记录的长度是固定的
+ `ownerPath=`-存储数据集的路径（特定于文件系统，在这种情况下是必需的）
+ `compress=`-表示如果在数据存储中压缩数据，则数据应在内存中保持压缩状态（特定于 bluesam）（可选，默认值为 false）
+ `catalog`-指定要对数据集进行编目（可选）
+ `warmUp`-表示数据集在打开时应加载到内存中（特定于 bluesam）（可选）
relativeGeneration 或 AbsoluteGeneration：需要设置其中一个属性。
### 操作
+ 创建：根据 GDG 元数据生成新的 GDG 数据集（同时处理文件系统和 Bluesam 存储）
+ refresheevents：在不创建新数据集的情况下调整世代号（Gdg 元数据）（在重启已创建数据集的失败作业时使用）
### 错误处理
+ 为成功设置错误代码 0，为失败设置错误代码 1
+ RuntimeException 对无效的命令或参数进行抛出
### 示例用法
Gdg 创建操作：以下代码为数据集创建 bluesam 生成 (43) `IC.PLI.GDGTEST`
```
import ...
mpr = applicationContext.getBean("com.netfective.bluage.gapwalk.rt.call.ExecutionController",MainProgramRunner.class)
Map params = new Hashtable()
params.put("jobContext", jobContext)
Object[] args =["action=create","gdgname=IC.PLI.GDGTEST","absoluteGeneration=43","storageProvider=bluesam","recordLength=80"]
mpr.withParameters(params).withArguments(args).runProgram("GDGUTILS")
```
Gdg 刷新事件操作：只有 relativeGeneration 与此操作相关。以下代码更新`IC.PLI.GDGTEST`数据集的世代号（与当前一代相比 \+1）
```
import ...
mpr = applicationContext.getBean("com.netfective.bluage.gapwalk.rt.call.ExecutionController",MainProgramRunner.class)
Map params = new Hashtable()
params.put("jobContext", jobContext)
Object[] args =["action=refreshevents","gdgname=IC.PLI.GDGTEST","relativeGeneration=1","storageProvider=bluesam"]
mpr.withParameters(params).withArguments(args).runProgram("GDGUTILS")
```
## ICEGENER/SYNCGENR
该实用程序模仿了 z/OS 系统实用程序 ICEGENER 的行为，它将数据集从输入（数据集）复制到输出（SYSUT1 SYSUT2 数据集）。此 Java 实现提供了支持文件系统和 Bluesam 存储的同等功能。
### 参数
没有争论
### 必需的数据集
+ SYSUT1: 输入数据集/文件
+ SYSUT2: 输出数据集/文件
### SYSUT2 数据集的处置处理
+ 新增：创建新的数据集/文件
+ OLD/SHR: Use existing dataset/file（必须存在）
+ MOD：修改，如果缺少则创建，如果存在则追加
### 错误处理
+ 如果复制成功则设置错误代码 0，如果复制失败则设置为 1
+ 因使用 Bluse `IllegalStateException` am 数据集的无效而被抛出
### 示例用法
以下是 ICEGENER 计划的 Groovy 使用示例，该计划源于 JCL 通过 AWS 转型进行现代化改造：
JCL 的代码：
```
//STEP01 EXEC PGM=ICEGENER
//SYSUT1 DD DSN=POI.INPUT,DISP=SHR
//SYSUT2 DD DSN=POI.OUTPU,
// DISP=(,CATLG,DELETE),
// UNIT=3490,
// DCB=(RECFM=FB,LRECL=100)
/*
```
以及相应的 Groovy 现代化改造：
```
mpr
.withFileConfigurations(new FileConfigurationUtils()
.withJobContext(jobContext)
.bluesam("SYSUT1")
.dataset("POI.INPUT")
.disposition("SHR")
.build()
.bluesam("SYSUT2")
.dataset("POI.OUTPU")
.normalTermination("CATLG")
.abnormalTermination("DELETE")
.build()
.getFileConfigurations())
.withParameters(params)
.runProgram("ICEGENER")
```
## IDCAMS/KQCAMS
该实用程序模仿传统程序 IDCAMS 的行为，IDCAMS 是一种用于 VSAM（虚拟存储访问方法）文件操作的大型机数据管理工具。它处理传统的 IDCAMS 命令，保持与原始 SYSIN 输入相同的语法。
### 上下文
程序行为可以通过以下两个参数进行配置`application-utility-pgm.yml`：
+ jclType：JCL 类型标识符（vse 或 mvs）。如果非 vse jcl 文件为空，则 IDCAMS 实用程序 PRINT/REPRO 命令返回 4
+ forcedCharsetIdcams: IDCAMS 处理的可选字符集替换
### 参数
没有争论。操作通过 SYSIN 数据集传递。
### 必需的数据集
+ SYSIN-包含 IDCAMS 命令语句
+ 输入/输出数据集-如IDCAMS命令中所述（取决于IDCAMS声明）
### 主要功能/支持的命令
此处未提供有关 SYSIN 控制卡中的 IDCAMS 命令的详细信息，但应从现有的相关传统平台文档中获取。
+ 定义-创建 VSAM 群集和数据集
+ 删除-移除数据集（支持通配符）
+ REPRO-在数据集之间复制数据
+ 打印-显示数据集内容
+ 验证-验证数据集的存在和完整性
+ ALTER-修改数据集属性（重命名）
+ ALLOC-动态分配数据集
+ SET-管理条件代码 (LASTCC/MAXCC)
+ IF-THEN-ELSE -有条件的命令执行
+ 取消-终止作业执行
### 错误处理
+ 如果最后一个命令成功则设置错误代码 0，如果失败则设置为 -1
+ SET (LASTCC) 命令可以用来覆盖错误代码，例如 `SET LASTCC = 0`
### 示例用法
以下是 IDCAMS 计划的 Groovy 使用示例，该计划源于 JCL 通过 AWS 转型进行现代化改造：
JCL 的代码：
```
//STEP15 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//ACCTDATA DD DISP=SHR,
// DSN=AWS.M2.CARDDEMO.ACCTDATA.PS
//ACCTVSAM DD DISP=SHR,
// DSN=AWS.M2.CARDDEMO.ACCTDATA.VSAM.KSDS
//SYSIN DD *
REPRO INFILE(ACCTDATA) OUTFILE(ACCTVSAM)
/*
```
以及相应的 Groovy 现代化改造：
```
mpr.withFileConfigurations(new FileConfigurationUtils()
.withJobContext(jobContext)
.systemOut("SYSPRINT")
.output("*")
.build()
.bluesam("ACCTDATA")
.dataset("AWS.M2.CARDDEMO.ACCTDATA.PS")
.disposition("SHR")
.build()
.bluesam("ACCTVSAM")
.dataset("AWS.M2.CARDDEMO.ACCTDATA.VSAM.KSDS")
.disposition("SHR")
.build()
.fileSystem("SYSIN")
.stream("REPRO INFILE(ACCTDATA) OUTFILE(ACCTVSAM)", getEncoding())
.build()
.getFileConfigurations())
.withParameters(params)
.runProgram("IDCAMS")
```
## IEBGENER/JSDGENER
该程序复制了 IEBGENER 实用程序。它用于复制和操作顺序数据集。此实现通过支持用于高级数据处理操作的 IEBGENER 控制语句扩展了基本的复制功能。
### 参数
没有争论。操作通过 SYSIN 数据集传递。
### 必需的数据集
+ SYSIN：包含控制语句（可选，如果未定义，IEBGENER 程序与 ICEGENER 程序相同）
+ SYSUT1: 输入数据集/文件
+ SYSUT2: 输出数据集/文件
### 主要特性/支持的 IEBGENER 控制语句
此处未提供有关 SYSIN 控制卡中的 IEBGENER 控制语句的详细信息，但应从现有的相关传统平台文档中获取。
+ 生成-通过指定要处理的最大记录类型 (MAXNAME) 和字段 (MAXFLDS) 数来定义数据操作过程的整体结构
+ 记录-通过指定将从输入数据集中复制或使用特定值生成的各个字段的位置、长度和格式来定义每种记录类型的实际布局和内容
+ LABEL/MEMBER/EXIT不支持
示例：
```
GENERATE MAXNAME=3,MAXFLDS=5
RECORD TYPE=1,
FIELD=(1,1,CH,VALUE='H'),
FIELD=(2,30,CH,VALUE='EMPLOYEE REPORT 2024 ')
RECORD TYPE=2,
FIELD=(1,1,CH,VALUE='D'),
FIELD=(2,10,CH), /* Name */
FIELD=(12,8,CH), /* Birth date */
FIELD=(20,8,CH,VALUE='ACTIVE')
RECORD TYPE=3,
FIELD=(1,1,CH,VALUE='F'),
FIELD=(2,30,CH,VALUE='END OF REPORT ')
```
### 错误处理
如果复制成功，则设置错误代码 0，如果复制失败，则设置错误代码 1。
### 示例用法
以下是 IEBGENER 计划的 Groovy 使用示例，该计划源于 JCL 通过 AWS 转型进行现代化改造：
JCL 的代码：
```
//GENDATA EXEC PGM=IEBGENER
//SYSUT1 DD DSN=INPUT.EMPLOYEE.DATA,
// DISP=SHR
//SYSUT2 DD DSN=OUTPUT.EMPLOYEE.FILE,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(TRK,(1,1)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)
//SYSIN DD *
GENERATE MAXNAME=2,MAXFLDS=5
RECORD TYPE=1,
FIELD=(1,1,CH,VALUE='H'),
FIELD=(2,30,CH,VALUE='EMPLOYEE SALARY REPORT 2024 ')
RECORD TYPE=2,
FIELD=(1,1,CH,VALUE='D'),
FIELD=(2,10,CH), /* Name from input */
FIELD=(12,8,CH), /* Birth date from input */
FIELD=(20,8,CH), /* Dept from input */
FIELD=(28,8,CH) /* Salary from input */
/*
```
以及相应的 Groovy 现代化改造：
```
mpr
.withFileConfigurations(new FileConfigurationUtils()
.withJobContext(jobContext)
.systemOut("SYSPRINT")
.output("*")
.build()
.bluesam("SYSUT1")
.dataset("INPUT.EMPLOYEE.DATA")
.disposition("SHR")
.build()
.bluesam("SYSUT2")
.dataset("OUTPUT.EMPLOYEE.FILE")
.disposition("NEW")
.normalTermination("CATLG")
.abnormalTermination("DELETE")
.build()
.fileSystem("SYSIN")
.stream( """GENERATE MAXNAME=2,MAXFLDS=5
RECORD TYPE=1,
FIELD=(1,1,CH,VALUE='H'),
FIELD=(2,30,CH,VALUE='EMPLOYEE SALARY REPORT 2024 ')
RECORD TYPE=2,
FIELD=(1,1,CH,VALUE='D'),
FIELD=(2,10,CH), /* Name from input */
FIELD=(12,8,CH), /* Birth date from input */
FIELD=(20,8,CH), /* Dept from input */
FIELD=(28,8,CH) /* Salary from input */""", getEncoding())
.build()
.getFileConfigurations())
.withParameters(params)
.runProgram("IEBGENER")
```
## IEFBR14
IEFBR14 是一个 “什么都不做” 的程序，返回码为 0（零）。它的主要用途是通过 DD 语句进行数据集分配、删除或目录维护，而无需执行任何实际的数据处理。
### 参数
没有争论
### 错误处理
始终设置错误代码 0。
### 示例用法
以下是该 IEFBR14 程序的 Groovy 使用示例，该示例是通过 AWS 转型实现的 JCL 现代化改造：
创建新的顺序数据集的 JCL 代码：
```
//STEP1 EXEC PGM=IEFBR14
//NEWSEQ DD DSN=USER.NEW.SEQ.DATA,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(TRK,(10,5)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)
```
以及相应的 Groovy 现代化改造：
```
mpr
.withFileConfigurations(new FileConfigurationUtils()
.withJobContext(jobContext)
.bluesam("NEWSEQ")
.dataset("USER.NEW.SEQ.DATA")
.disposition("NEW")
.normalTermination("CATLG")
.abnormalTermination("DELETE")
.build()
.getFileConfigurations())
.withParameters(params)
.runProgram("IEFBR14")
```
删除现有数据集的 JCL 代码：
```
//STEP3 EXEC PGM=IEFBR14
//DELDD DD DSN=USER.OLD.DATASET,
// DISP=(OLD,DELETE,DELETE)
```
以及相应的 Groovy 现代化改造：
```
mpr
.withFileConfigurations(new FileConfigurationUtils()
.withJobContext(jobContext)
.bluesam("DELDD")
.dataset("USER.OLD.DATASET")
.disposition("OLD")
.normalTermination("DELETE")
.abnormalTermination("DELETE")
.build()
.getFileConfigurations())
.withParameters(params)
.runProgram("IEFBR14")
```
## JCLBCICS
该程序管理数据集的状态，它基于配置 enables/disables 的数据集，同时支持单个文件和通配符模式：它更改 JICS 表 file\_table 中的 STATUS 字段。
### 参数
没有争论。操作通过`DatasetsConfiguration`对象传递，例如
```
mpr.withDatasetsConfiguration(new DatasetsConfiguration().close()
```
### 上下文
程序行为可以通过两个参数进行配置：
In `application-utility-pgm.yml`:
+ `jclbcics.ddname.size`（默认为 8）：它全局配置数据集名称大小；如果设置了此值且数据集名称长度小于此值，则数据集名称将被截断。
在 Groovy 文件的各个步骤中调用程序
+ `JCLBCICS_OVERRIDDEN_SIZE`:它会覆盖全局数据集名称大小：
```
TreeMap stepMapTransfo = [:]
Map stepParams = ["MapTransfo":stepMapTransfo]
stepParams["MapTransfo"]["JCLBCICS_OVERRIDDEN_SIZE"] = '6'
```
如果调整后的 dd 名称大小（截断后）小于 8，则 dd 名称将被视为通配符，并且该函数适用于以此 dd 名称开头的所有数据集。
### 主要功能
支持的操作有：
+ 打开：将数据集设置为 “已启用” 状态
+ 关闭：将数据集设置为禁用状态
这些操作是通过`DatasetsConfiguration`生成器类声明的：
```
new DatasetsConfiguration().close().open()
```
DD 名称：数据集的名称，如果 dd 名称大小小于最大 dd 名称大小 (8)，则接受通配符 \*。
### 错误处理
将错误代码设置为 0
### 示例用法
以下是 JCLBCICS 程序的 Groovy 示例用法：
它禁用数据集`UFOLJ3P`，启用所有以 AX 开头的数据集，启用所有以 DX 开头的数据集
```
import com.netfective.bluage.gapwalk.rt.call.MainProgramRunner
import com.netfective.bluage.gapwalk.rt.call.ProgramExecutionResult
import com.netfective.bluage.gapwalk.rt.io.support.DatasetsConfiguration
MainProgramRunner mpr = applicationContext.getBean("com.netfective.bluage.gapwalk.rt.call.ExecutionController",MainProgramRunner.class)
def TreeMap stepMapTransfo = [:]
def Map stepParams = ['MapTransfo':stepMapTransfo]
stepParams['MapTransfo']['JCLBCICS_OVERRIDDEN_SIZE'] = '7'
ProgramExecutionResult res = mpr
.withDatasetsConfiguration(new DatasetsConfiguration().close("UFOLJ3P").open("AX*").open("DX"))
.withParameters(stepParams)
.runProgram("JCLBCICS")
```