AWS 大型机现代化服务（托管运行时环境体验）不再向新客户开放。有关类似于 AWS 大型机现代化服务（托管运行时环境体验）的功能，请浏览 AWS 大型机现代化服务（自我管理体验）。现有客户可以继续正常使用该服务。有关更多信息，请参阅[AWS 大型机现代化可用性变更](https://docs.aws.amazon.com/m2/latest/userguide/mainframe-modernization-availability-change.html)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 为托管应用程序配置对实用程序的访问权限
<a name="applications-m2-ba-utilities"></a>

当您使用 Tr AWS ansform for 大型机重构大型机应用程序时，如果您的应用程序依赖于各种传统平台实用程序，例如 IDCAMS、INFUTILB、SORT 等，则可能需要为它们提供支持。 AWS 大型机重构转型通过与现代化应用程序一起部署的专用 Web 应用程序为这种访问提供了这种访问权限。此 Web 应用程序需要您提供配置文件 `application-utility-pgm.yml`。如果您未提供此配置文件，则 Web 应用程序无法与您的应用程序一并部署，并且不可用。

**Topics**
+ [配置属性](#applications-m2-ba-utilities-props)

本主题介绍了您可以在 `application-utility-pgm.yml` 配置文件中指定的所有可能属性及其默认值，包括必需属性和可选属性。以下是一个完整的配置文件示例，其中的属性按我们推荐的顺序列出。您可以将此示例为起点，设置自己的配置文件。

```
# If the datasource support mode is not static-xa, spring JTA transactions autoconfiguration must be disabled
 spring.jta.enabled: false
 logging.config: 'classpath:logback-utility.xml'
 
 # Encoding
 encoding: cp1047
 
 # Encoding to be used by INFUTILB and DSNUTILB to generate and read SYSPUNCH files
 sysPunchEncoding: cp1047
 
 # Utility database access
 spring.aws.client.datasources.primary.secret: `arn:aws:secretsmanager:us-west-2:111122223333:secret:business-FfmXLG`
 
 treatLargeNumberAsInteger: false
 
 # Zoned mode : valid values = EBCDIC_STRICT, EBCDIC_MODIFIED, AS400 
 zonedMode: EBCDIC_STRICT
 
 jcl.type: mvs
 
 # Unload properties 
 # For date/time: if use database configuration is enabled, formats are ignored
 # For nbi; use hexadecimal syntaxe to specify the byte value
 unload:
  sqlCodePointShift: 384
  nbi:
    whenNull: "6F"
    whenNotNull: "00"
  useDatabaseConfiguration: false
  format:
    date: MM/dd/yyyy
    time: HH.mm.ss
    timestamp: yyyy-MM-dd-HH.mm.ss.SSSSSS
  chunkSize:500
  fetchSize: 500
  varCharIsNull: false
  columnFiller: space  
 
 # Load properties 
 # Batch size for DSNUTILB Load Task
 load:
  sqlCodePointShift: 384
  batchSize: 500
  format:
    localDate: dd.MM.yyyy|dd/MM/yyyy|yyyy-MM-dd
    dbDate: yyyy-MM-dd
    localTime: 'HH:mm:ss|HH.mm.ss'
    dbTime: 'HH:mm:ss'
 
 table-mappings:
  TABLE_1_NAME : LEGACY_TABLE_1_NAME
  TABLE_2_NAME : LEGACY_TABLE_2_NAME
```

## 配置属性
<a name="applications-m2-ba-utilities-props"></a>

您可以在配置文件中指定以下属性。

**spring.jta.enabled**  
 （可选）控制是否启用 JTA 支持。对于实用程序，我们建议您将此值设置为 `false`。  

```
spring.jta.enabled : false
```

**logging.config**  
 （必需）指定专用记录器配置文件的路径。建议使用名称 `logback-utility.xml` 并在经过现代化改造的应用程序中使用此文件。组织这些文件的常用方法是将所有记录器配置文件放在同一个位置，通常放在子文件夹 `/config/logback` 中，其中 `/config` 是包含 YAML 配置文件的文件夹。有关更多信息，请参阅 Logback 文档中的[第三章：Logback 配置](https://logback.qos.ch/manual/configuration.html)。  

```
logging.config : classpath:logback-utility.xml
```

**encoding**  
 （必需）指定实用程序使用的字符集。在大多数情况下，当您从 z/OS 平台迁移时，此字符集是 EBCDIC 变体，应与为现代化应用程序配置的字符集相匹配。如果未设置，默认值为 `ASCII`。  

```
encoding : cp1047
```

**sysPunchEncoding**  
 （可选）指定 INFUTILB 和 DSNUTILB 用于生成和读取 SYSPUNCH 文件的字符集。如果您照原样使用来自遗留平台的 SYSPUNCH 文件，则此值应该是 EBCDIC 变体。如果未设置，默认值为 `ASCII`。  

```
sysPunchEncoding : cp1047
```

### 数据来源配置
<a name="applications-m2-ba-utilities-props-data"></a>

某些与数据库相关的实用程序（例如 LOAD 和 UNLOAD）需要通过数据来源访问目标数据库。与 AWS 大型机现代化中的其他数据源定义一样，此访问权限需要您使用 AWS Secrets Manager。指向 Secrets Manager 中正确密钥的属性如下所示：

#### 主数据来源
<a name="applications-m2-ba-utilities-props-data-primary"></a>

这是主要的业务应用程序数据库。

**spring.aws.client.datasources.primary.secret**  
 （可选）指定 Secrets Manager 中包含数据来源属性的密钥。  

```
spring.aws.client.datasources.primary.secret: {{datasource-secret-ARN}}
```

**spring.aws.client.datasources.primary.dbname**  
（可选）如果数据库密钥中未直接提供数据库名称，则使用 `dbname` 属性指定目标数据库名称。  

```
spring.aws.client.datasources.primary.dbname: {{target-database-name}}
```

**spring.aws.client.datasources.primary.type**  
（可选）指定要使用的连接池实现的完全限定名称。默认值为 `com.zaxxer.hikari.HikariDataSource`。  

```
spring.aws.client.datasources.primary.type: target-datasource-type
```
如果主数据来源的类型为 `com.zaxxer.hikari.HikariDataSource`，则可以按如下方式指定其他属性：

**spring.datasource.primary.[property\_name]**  
（可选）您可以使用此格式来指定用于配置主数据来源连接池实现的额外属性。  
以下是 `com.zaxxer.hikari.HikariDataSource` 类型的主数据来源的示例。  

```
spring:
   datasource:
       primary:
         autoCommit: XXXX
         maximumPoolSize: XXXX
         keepaliveTime: XXXX
         minimumIdle: XXXX
         idleTimeout: XXXX
         connectionTimeout: XXXX
         maxLifetime: XXXX
```

#### 其他实用程序数据来源
<a name="applications-m2-ba-utilities-props-data-other"></a>

除了主数据来源外，还可以提供其他实用程序数据来源。

**spring.aws.client.utility.pgm.datasources.names**  
（可选）指定实用程序数据来源名称列表。  

```
spring.aws.client.utility.pgm.datasources.names: dsname1, dsname2, dsname3
```

**spring.aws.client.utility.pgm.datasources.[dsname].secret**  
（可选）指定托管数据来源属性的 SSM 中的密钥 ARN。在 `spring.aws.client.utility.pgm.datasources.names` 中指定的名称列表中提供 [dsname]。  

```
spring.aws.client.utility.pgm.datasources.dsname1.secret: datasource-secret-ARN
```

**spring.aws.client.utility.pgm.datasources.[dsname].dbname**  
（可选）如果数据库密钥中未直接提供数据库名称，则使用 `dbname` 属性指定目标数据库名称。在 `spring.aws.client.utility.pgm.datasources.names` 中指定的名称列表中提供 [dsname]。  

```
spring.aws.client.utility.pgm.datasources.dsname1.dbname: target-database-name
```

**spring.aws.client.utility.pgm.datasources.[dsname].type**  
（可选）指定要使用的连接池实现的完全限定名称。默认值为 `com.zaxxer.hikari.HikariDataSource`。在 `spring.aws.client.utility.pgm.datasources.names` 中指定的名称列表中提供 [dsname]。  

```
spring.aws.client.utility.pgm.datasources.dsname1.type: target-datasource-type
```
如果实用程序数据来源类型为 `com.zaxxer.hikari.HikariDataSource`，则可以按如下方式提供其他属性：

**spring.datasource.[dsname].[property\_name]**  
（可选）指定一组用于配置实用程序数据来源连接池实现的额外属性。在 `spring.aws.client.utility.pgm.datasources.names` 中指定的名称列表中提供 [dsname]。采用以下格式指定这些属性：`property_name : value`  
以下是 `com.zaxxer.hikari.HikariDataSource` 类型的额外实用程序数据来源的示例：  

```
spring:
   datasource:
       dsname1:
         connectionTimeout: XXXX
         maxLifetime: XXXX
       dsname2:
         connectionTimeout: XXXX
         maxLifetime: XXXX
       dsname3:
         connectionTimeout: XXXX
         maxLifetime: XXXX
```

**treatLargeNumberAsInteger**  
 （可选）与 Oracle 数据库引擎细节和 DSNTEP2/DSNTEP4 实用程序用法有关。如果将此标志设置为 true，则来自 Oracle 数据库的大数字 (NUMBER (38,0)) 将被作为整数处理。默认值：`false`  

```
treatLargeNumberAsInteger : false
```

**zonedMode**  
（可选）设置分区模式，以对分区数据类型进行编码或解码。此设置会影响有符号数字的表示方式。有效值如下：  
+ *EBCDIC\_STRICT*：默认值。对符号处理使用严格的定义。根据字符集是 EBCDIC 还是 ASCII，有符号数字表示使用以下字符：
  + 与字节 (`Cn+Dn`) 对应的 EBCDIC 字符表示正数和负数范围（`+0` 至 `+9`、`-0` 至 `-9`）。字符显示为 `{`,`A` 至 `I`, `}`、`J` 至 `R`
  + 与字节 (`3n+7n`) 对应的 ASCII 字符表示正数和负数范围（`+0` 至 `+9`、`-0` 至 `-9`）。字符显示为 `0` 至 `9`、 `p` 至 `y`。
+ *EBCDIC\_MODIFIED*：实用修改后的定义进行符号处理。对于 EBDIC 和 ASCII，相同的字符列表表示有符号数字，即 `+0` 至 `+9` 映射为 `{` \+ `A` 至 `I` 并且 `-0` 至 `-9` 映射为 `}` \+ `J` 至 `R`. \\ 
+ *AS400*: 用于来自 iSeries (AS400) 平台的现代化传统资产。

```
zonedMode:EBCDIC_STRICT
```

**jcl.type**  
 （可选）表示经过现代化改造的 JCL 脚本的遗留类型。如果调用的 JCL 类型为 `vse`，IDCAMS 实用程序将使用此设置来定制返回码。有效值如下所示：  
+ `mvs`（默认值）
+ `vse`

```
jcl.type : mvs
```

### 数据库卸载实用程序相关属性
<a name="applications-m2-ba-utilities-props-unload"></a>

 使用这些属性来配置用于将数据库表卸载到数据集的实用程序。以下所有属性均为可选属性。

 此示例显示了所有可能的卸载属性。

```
# Unload properties 
 # For date/time: if use database configuration is enabled, formats are ignored
 # For nbi; use hexadecimal syntaxe to specify the byte value
 unload:
 sqlCodePointShift: 0
 nbi:
 whenNull: "6F"
 whenNotNull: "00"
 useDatabaseConfiguration: false
 format:
 date: MM/dd/yyyy
 time: HH.mm.ss
 timestamp: yyyy-MM-dd-HH.mm.ss.SSSSSS 
 chunkSize: 0
 fetchSize: 0
 varCharIsNull: false
 columnFiller: space
```

**sqlCodePoint移动**  
 （可选）指定一个整数值，该值表示数据上使用的 SQL 代码点转换。默认值是 0。这表示不进行代码点转换。将此设置与用于现代化应用程序的 SQL 代码点转换参数保持一致。当使用码点转换时，此参数的常用值为 384。  

```
unload.sqlCodePointShift: 0
```

**nbi**  
 （可选）指定一个空的指示符字节，以十六进制值（作为字符串）形式添加到数据值右侧的。两个可能的值如下所示：  
+ *whenNull*：当数据值为空时，添加十六进制值。默认值为 `6``。有时会改用高值 `FF`。

  ```
  unload.nbi.whenNull: "6F"
  ```
+ *whenNotNull*：当数据值不为空但列可以为空时，添加十六进制值。默认值为 `00`（低值）。

  ```
  unload.nbi.whenNotNull: "00"
  ```

**useDatabaseConfiguration**  
 （可选）指定日期和时间格式化属性，这用于处理 UNLOAD 查询中的 date/time 对象。默认值为 `false`。  
+ 如果设置为 `true`，则使用主配置文件 (`application-main.yml`) 中的 `pgmDateFormat`、`pgmTimeFormat` 和 `pgmTimestampFormat` 属性。
+ 如果设置为 `false`，则使用以下日期和时间格式化属性：
  + `unload.format.date`：指定日期格式化模式。默认值为 `MM/dd/yyyy`。
  + `unload.format.time`：指定时间格式化模式。默认值为 `HH.mm.ss`。
  + `unload.format.timestamp`：指定时间戳格式化模式。默认值为 `yyyy-MM-dd-HH.mm.ss.SSSSSS`。

**chunkSize**  
 （可选）指定用于创建 SYSREC 数据集的数据块的大小。这些数据集是数据集卸载操作的目标，可用于并行操作。默认值为 `0`（无数据块）。  

```
unload.chunkSize:0
```

**fetchSize**  
 （可选）指定数据提取大小。该值是使用数据块策略时一次要提取的记录数。默认值：`0`。  

```
unload.fetchSize:0
```

**varCharIs空**  
 （可选）指定如何处理不可为空的 varchar 列内容为空的情况。默认值为 `false`。  
 如果将此值设置为 `true`，则出于卸载目的，列内容将被作为空字符串（而不是单个空格字符串）进行处理。仅针对 Oracle 数据库引擎将此标志设置为 `true`。  

```
unload.varCharIsNull: false
```

**columnFiller**  
 （可选）指定用于填充 varchar 列中已卸载列的值。可能的值为 space 或低值。默认值为 space。  

```
unload.columnFiller: space
```

### 与数据库加载相关的属性
<a name="applications-m2-ba-utilities-props-load"></a>

 使用以下属性来配置将数据集记录加载到目标数据库（例如 DSNUTILB）的实用程序。以下所有属性均为可选属性。

 此示例显示了所有可能的加载属性。

```
# Load properties 
 # Batch size for DSNUTILB Load Task
 load:
 sqlCodePointShift: 384
 batchSize: 500
 format:
 localDate: dd.MM.yyyy|dd/MM/yyyy|yyyy-MM-dd
 dbDate: yyyy-MM-dd
 localTime: HH:mm:ss|HH.mm.ss
 dbTime: HH:mm:ss
 
 table-mappings:
 TABLE_1_NAME : LEGACY_TABLE_1_NAME
 TABLE_2_NAME : LEGACY_TABLE_2_NAME
```

**sqlCodePoint移动**  
 （可选）指定一个整数值，该值表示数据上使用的 SQL 代码点转换。默认值为 0，这表示应用程序没有代码点转换。将此设置与用于经过现代化改造的应用程序的 SQL 代码点转换参数保持一致。当使用代码点转换时，此参数的常用值为 384。  

```
load.sqlCodePointShift : 384
```

**batchSize**  
 （可选）指定一个整数值，该值表示在向数据库发送实际批处理语句之前要处理的记录数。默认值为 0。  

```
load.batchSize: 500
```

**format**  
 （可选）指定在数据库加载操作期间用于日期/时间转换的日期和时间格式化模式。  
+ `load.format.localDate`：本地日期格式化模式。默认值为 `dd.MM.yyyy|dd/MM/yyyy|yyyy-MM-dd`。
+ `load.format.dbDate`：数据库日期格式化模式。默认值为 `yyyy-MM-dd`。
+ `load.format.localTime`：本地时间格式化模式。默认值为 `HH:mm:ss|HH.mm.ss`。
+ `load.format.dbTime`：数据库时间格式化模式。默认值为 `HH:mm:ss`。

**table-mappings**  
 （可选）指定客户提供的遗留表名和现代表名之间的映射集合。DSNUTILB 实用程序会使用这些映射。  
按以下格式指定值：*MODERN\_TABLE\_NAME : LEGACY\_TABLE\_NAME*  
示例如下：  

```
table-mappings:
 TABLE_1_NAME : LEGACY_TABLE_1_NAME
 TABLE_2_NAME : LEGACY_TABLE_2_NAME
 ...
 TABLE_*N*_NAME : LEGACY_TABLE_*N*_NAME
```
实用程序应用程序启动时，会显式记录所有提供的映射。