大型主机连接器 API 参考文档

下表列出了您可以与主机连接器搭配使用的 BigQuery、Cloud Storage 和其他 Google Cloud 命令。

产品 命令 说明 支持远程转码
BigQuery 命令 使用此命令可创建二进制文件。该命令接受 COPYBOOK DD 作为输入。

bq export 命令支持部分性能调整 功能。如需了解详情，请参阅 Google Ads 中 bq export 命令。

注意：bq export 命令会使请求失败 导出大型 Bigtable 表。为避免错误，请在要导出大型表时，在 bq export 命令中添加 -allowLargeResults 标志。		 是
使用此命令将数据加载到表中。如需了解详情，请参阅 bq load 操作。 否
可以使用此命令创建 BigQuery 资源，例如 内置表或外部表，需要使用分区和聚簇才能 设置。如需了解详情，请参阅 bq mk。

您还可以使用 bq mk 命令生成 BigQuery 表。如需了解详情，请参阅根据副本簿创建 BigQuery 表。 		否
使用此命令创建一个运行指定 SQL 查询的查询作业。 该命令会从 --sql 标志或 来自“QUERY DD”。 如果同时提供这两者，则 --sql 标志中的查询优先。

使用 --follow=true 标志生成一个报告，以显示选择查询的结果。若要将此报告写入到 定义一个指向AUDITL 该文件应包含审核日志报告。如果您希望使用正常的日志记录行为，请勿使用 --follow 标志。

某些查询结果可能会返回大量行，有时可能会返回数百万行。 为了让输出保持可读性，系统会对显示的行数进行上限。如需控制显示的行数，请使用 --report_row_limit 标志。例如，使用 --report_row_limit 10 可将结果限制为 10 行。修改者 默认情况下，显示的行数上限为 30。

如需使用 bq query 参数化，请参阅 bq 查询参数化。

如需了解详情，请参阅 bq query。 		是
您可以使用此命令永久删除 BigQuery 资源。由于此命令会永久删除资源，因此我们建议您谨慎使用。如需了解详情，请参阅 bq rm。 否
Cloud Storage 命令 使用此命令将文本或二进制数据复制到 Cloud Storage。您 可以使用简单的二进制复制模式将 IBM z/OS 作为数据流水线的一部分未经修改的 Cloud Storage。您可以选择将字符编码从扩展二进制编码十进制交换码 (EBCDIC) 转换为 ASCII UTF-8，并添加换行符。

您还可以使用此命令复制作业控制语言 (JCL) 中定义的应用源代码。 		否
gsutil 实用程序 使用此命令对数据集进行转码并将其写入 Cloud Storage 在 Optimized Row Columnar (ORC) 中 文件格式该命令会从 INFILE DD 读取数据，并从 COPYBOOK 文件。 如果您希望该命令从数据源名称 (DSN) 文件读取数据，请使用以下标志：
  • --inDsn：输入数据集 DSN。如果提供，此标志会替换 INFILE DD。
  • --cobDsn：副本簿 DSN。如果提供，此标志会替换 COPYBOOK DD。
然后，该命令会打开一个可配置数量的并行连接， Cloud Storage API 并将 COBOL 数据集转码为列式和 GZIP 压缩的 ORC 文件格式。压缩率预计为 35% 左右。

您可以选择使用此命令与大型机上的虚拟机上运行的主机连接器 gRPC 服务进行交互。为此，请将 SRVHOST 和 SRVPORT 环境变量，或者提供主机名和 使用命令行选项指定端口号使用 gRPC 服务时， 输入数据集首先由 大型主机连接器，然后进行了远程过程 (RPC) 调用 指示 gRPC 服务对文件进行转码

您还可以使用 gsutil cp 命令执行以下操作： 		是
使用此命令删除存储桶或存储桶中的对象。有关 相关信息，请参阅 rm - 移除对象。 否
gszutil 实用程序 gszutil 实用程序使用 IBM JZOS Java SDK 运行，并提供一个 shell 模拟器 接受 gsutil 和 BigQuery 命令行 使用 JCL 进行调用。

gszutil 实用程序扩展了 gsutil 实用程序，以接受以下形式的架构： COPYBOOK DD， 先将 COBOL 数据集直接转码为 ORC，然后再上传到 Cloud Storage借助 gszutil 实用程序，您还可以使用 JCL 执行 BigQuery query 和 load。

gszutil 实用程序可与 gRPC 搭配使用 可帮助您减少每秒处理 100 万条指令 (MIPS) 。我们建议您在生产环境中使用 gszutil 实用程序将 Cloud Storage 中的二进制文件转换为 ORC 格式。 		否
其他命令 使用此命令向 Pub/Sub 主题发送消息。您可以 使用命令行或使用数据集提供消息。 否
使用此命令触发 Dataflow flex 的执行 模板。该命令从指定的 flex 模板路径运行作业。如需了解详情，请参阅 gcloud dataflow flex-template run。 否
使用此命令向 Web 服务或 REST API 发出 HTTP 请求。 否
使用此命令可将必要的系统数据输出到标准输出 (stdout)。这样，大型主机连接器支持团队 来收集诊断问题所需的信息，而无需 广泛的客户互动。
systemreport 命令会根据您使用的标志，输出以下系统数据：
  • --supported_ciphers：支持的密码
  • --available_security_providers：可用的安全提供程序
 否

bq export 命令的性能调整配置

大型主机连接器支持以下性能调整 配置 bq export 命令：

  • exporter_thread_count：（可选）设置工作器线程数。默认值为 4。
  • max_read_streams：（可选）设置读取流数上限。通过 的默认值就是 exporter_thread_count。
  • order_response：（可选）如果将此标志设置为 true， 会保留查询结果顺序。此标志会影响导出 性能默认值为 false。
  • max_read_queue：（可选）设置读取记录数上限 队列。默认值为线程数的两倍。
  • transcoding_buffer：（可选）设置每个线程的转码缓冲区大小（以 MB 为单位）。默认值为 20 MB。

请注意，您也可以尝试增加传输窗口大小，方法是将 OVERRIDE_GRPC_WINDOW_MB 环境变量来提高性能。默认时长为 4 MB。

通过复制簿创建 BigQuery 表

您可以使用 bq mk 命令直接通过解析 COBOL 副本簿生成 BigQuery 表。原生副本簿解析器会从副本簿中的 VALUE 子句中提取默认值，并将其分配给新创建的 BigQuery 表中的相应列。

为了帮助您测试此功能，bq mk 命令还提供了模拟运行模式。在此模式下，您可以预览生成的 CREATE TABLE SQL 命令，而无需实际在 BigQuery 中创建表。

bq mk 命令提供以下配置选项， 支持此功能：

  • --schema_from_copybook：指定用于创建的文案 表格。
  • --dry_run：（可选）启用后，该命令只会输出生成的 CREATE TABLE SQL 命令，而不会执行该命令。此标志默认设置为 false。
  • --tablespec "[PROJECT_ID]:[DATASET].[TABLE]"：指定目标表的 BigQuery 项目 ID、数据集和表名称。
  • --encoding：指定用于读取文案的编码 文件。默认值为 CP037。

支持以下 VALUE 子句：

VAR1   PIC 9(5) VALUE 55.
*-- Set VAR1 to 55
VAR1   PIC X(5) VALUE aaaa. Set VAR1 to aaaa
VAR1   PIC 9(3) COMP VALUE 3. Set VAR1 to 3 (binary)
VAR1   PIC [9(5), X(5)] VALUE <literal>. Set VAR1 to <literal>
VAR1   PIC [9(5), X(5)] VALUE ZERO. Set VAR1 to 0 or "0"
VAR1   PIC [9(5), X(5)] VALUE ZEROS. Set VAR1 to 0 or "00000"
VAR1   PIC [9(5), X(5)] VALUE ZEROES. Set VAR1 to 0 or "00000"
VAR1   PIC X(5) VALUE SPACE. Set VAR1 to  " "
VAR1   PIC X(5) VALUE SPACES. Set VAR1 to  "     "

支持 HIGH-VALUE 和 LOW-VALUE 子句 字母数字变量。

VAR1   PIC X(5) VALUE HIGH-VALUE. Set VAR1 to `X"FF "
VAR1   PIC X(5) VALUE HIGH-VALUES. Set VAR1 to 0 or `X"FFFFFFFFFF"
VAR1   PIC X(5) VALUE LOW-VALUE. Set VAR1 to `X"00" (NULL)
VAR1   PIC X(5) VALUE LOW-VALUES. Set VAR1 to `X"0000000000" (NULL)
VAR1   PIC X(5) VALUE QUOTE. Set VAR1 to `"`
VAR1   PIC X(5) VALUE `QUOTES`. Set VAR1 to 0 or `""""`
VAR1   PIC [9(5), X(5)] VALUE NULL. Not defined and won't be supported
VAR1   PIC [9(5), X(5)] VALUE ALL <literal>. Set all fields with the value ALL to <literal>

bq query 参数化

通过大型主机连接器，您可以将参数化查询与 bq query。

以下示例说明了如何使用参数化的 bq query 查询：

查询文件

SELECT * FROM `bigquery-public-data.samples.wikipedia` WHERE title = @xtitle

下面是一个包含多个参数的示例。

查询文件

SELECT * FROM bigquery-public-data.samples.wikipedia WHERE title = @mytitle AND num_characters > @min_chars;

执行示例

bq query \
--project_id=mainframe-connector-dev \
--location="US" \
--parameters=mytitle::Hippocrates,min_chars:INT64:42600

将文件从 Cloud Storage 复制到您的大型主机

您可以使用 gsutil cp 命令将文件从 Cloud Storage 到大型机数据集。请注意，您无法复制分区数据集 (PDS)。

如需将文件从 Cloud Storage 复制到大型机数据集，请在 JCL 中指定要下载到大型机的文件的 DSN 和空间要求，如以下示例所示：

//OUTFILE  DD DSN=MAINFRAME.DSN.FILE,DISP=(,CATLG),
//            RECFM=FB,DSORG=PS,
//            SPACE=(10,(2,1),RLSE),
//            AVGREC=M,
//            UNIT=SYSDA
//SYSPRINT DD SYSOUT=*
//SYSDUMP  DD SYSOUT=*
//STDIN DD *

请按以下格式指定 gsutil cp 命令。如果主机上已存在该文件，请务必将 --replace 标志添加到该命令。

gsutil cp GCS_URI DSN --recfm=RECFM --lrecl=LRECL --blksize=BLKSIZE --noseek

替换以下内容：

  • GCS_URI：Cloud Storage 统一资源标识符 (URI) Cloud Storage 文件。例如 gs://bucket/sample.mainframe.dsn。
  • DSN：主机上的 DSN 目标位置。
  • RECFM：大型机文件的记录格式 (RECFM)。有效值为 F、FB 和 U。请注意，这些值不区分大小写。
  • LRECL：（可选）文件的记录长度 (LRECL)。值 必须是大于等于 0 的整数。如果未指定 LRECL，则假定该文件为 采用未定义长度记录格式 (U)。
  • BLKSIZE：（可选）文件的块大小。如果设置为 0，系统将确定最佳分块大小。该值必须为大于等于 0 的整数。 如果未指定值，则文件将被视为已取消屏蔽的文件。
  • noseek：（可选）如果您希望提升效果，请添加此参数 下载性能该标志默认设置为 false，即跳转 操作。

执行示例

gsutil cp gs://sample-bucket/MAINFRAME.DSN.FILE MAINFRAME.DSN.FILE \
--lrecl=16 --blksize=0 --recfm=fb

gsutil cp 命令的性能调整配置

大型机连接器支持为 gsutil cp 命令配置以下性能调整。

  • 使用 --parallelism 标志可设置线程数。通过 默认值为 1（单线程）。
  • 使用 --maxChunkSize 参数设置每个文件的大小上限 数据块。每个分块都将有自己的 Optimized Row Columnar (ORC) 文件。增加此值可减少创建的分块数量，但会增加转码过程中的内存需求。如需了解详情，请参阅解析 maxChunkSize 参数。默认值为 128 MiB。
  • 使用 --preload_chunk_count 参数将的数据量设置为 在所有工作器都处于忙碌状态时预加载到内存。此参数可以提高性能，但会占用内存。默认值为 2。

执行示例

gsutil cp \
  --replace \
  --parser_type=copybook \
  --parallelism=8 \
  --maxChunkSize=256MiB \
  gs://$BUCKET/test.orc

在本示例中，我们考虑了一个大文件，因此在 所达到的线路费率如果您有足够的内存，我们建议您 将数据块大小增加到 256 MiB 甚至 512 MiB，因为这样可以减少 构建 Cloud Storage 对象，以及完成 Cloud Storage 对象的创建。适用于使用较少的小型文件 和较小的数据块可能会生成更好的结果。

解析 maxChunkSize 参数

maxChunkSize 标志接受金额和 计量单位，例如 5 MiB。您可以在 数量和大小

您可以使用以下格式提供值：

  • Java 格式：b/k/m/g/t，表示字节、千比字节、兆比字节、吉比字节和 分别为 TB
  • 国际格式：KiB/MiB/GiB/TiB，分别代表千字节、兆字节、吉比字节和太比字节
  • 公制格式：b/kb/mb/gb/tb，分别表示千字节、兆字节、千兆字节和太字节

数据大小解析不区分大小写。请注意，您无法指定部分金额。例如，使用 716 KiB，而不是 0.7 MiB。