Mainframe Connector API 命令

下表列出了可与 Mainframe Connector 搭配使用的 BigQuery、Cloud Storage 和其他Google Cloud 命令。

注意： 对于支持远程执行的命令，您可以使用选项 remoteUrl，而不是 remoteHost 和 remotePort。remoteUrl 选项必须包含方案、主机和端口。如果方案为 https，并且未通过选项 trustCertCollectionFilePath 或环境变量 TRUST_CERT_COLLECTION_FILE_PATH 提供任何信任库，则使用系统的默认信任库。

产品	命令	说明	支持远程转码
BigQuery 命令	bq export	使用此命令创建二进制文件。该命令接受 COPYBOOK DD 作为输入。 注意：我们建议您使用 qsam decode 和 qsam encode 命令来执行此任务。如需了解使用 qsam 命令的优势，请参阅 qsam 命令的优势。 bq export 命令支持一些性能调优功能。如需了解详情，请参阅针对 bq export 命令的性能改进。您可以将自定义字符集与 bq export 命令搭配使用。如需了解详情，请参阅使用自定义字符集。 注意：bq export 命令无法处理导出大型 Bigtable 表的请求。为避免出错，请在要导出大型表时，向 bq export 命令添加 -allowLargeResults 标志。	是
	bq load	使用此命令可将数据加载到表中。	否
	bq mk	使用此命令可创建需要设置分区和聚类的 BigQuery 资源，例如内置表或外部表。 您还可以使用 bq mk 命令直接从解析 COBOL 复制簿生成 BigQuery 表。如需了解详情，请参阅从 Copybook 创建 BigQuery 表。	否
	bq query	使用此命令可创建运行指定 SQL 查询的查询作业。该命令从 --sql 标志或 QUERY DD 读取 SQL 查询。如果同时提供这两个参数，则 --sql 标志中的查询优先。 使用 --follow=true 标志生成显示 SELECT 查询结果的报告。为了将此报告写入大型机中的文件，请定义指向应包含审核日志报告的文件的 DD 语句 AUDITL。如果您希望获得正常的日志记录行为，请勿使用 --follow 标志。 某些查询结果可能会返回大量行，有时甚至达到数百万行。 为了使输出保持人类可读性，显示的行数受到限制。如需控制显示的行数，请使用 --report_row_limit 标志。例如，使用 --report_row_limit 10 将结果限制为 10 行。默认情况下，显示的行数限制为 30。 如需使用 bq query 参数化，请参阅 bq 查询参数化。	是
	bq rm	使用此命令可永久删除 BigQuery 资源。由于此命令会永久删除资源，因此我们建议您谨慎使用。	否
Cloud Run 命令	cloud run job execute	使用此命令从大型机触发 Cloud Run 作业。	否
	cloud run job logs	使用此命令查看特定 Cloud Run 作业执行的日志。	否
	cloud run job cancel	使用此命令可取消 Cloud Run 作业。	否
Cloud Storage 命令	scp	使用此命令可将文本或二进制数据复制到 Cloud Storage。 您可以使用简单的二进制复制模式，将数据集从 IBM z/OS 复制到 Cloud Storage，作为数据流水线的一部分，且无需修改。（可选）您可以将字符编码从扩展的二进制编码十进制交换码 (EBCDIC) 转换为 ASCII UTF-8，并添加换行符。 注意：我们建议您使用 copy text 命令来执行此任务，因为该命令可提供更好的功能。 您还可以使用此命令复制在作业控制语言 (JCL) 中定义的应用源代码。	否
gsutil 实用程序	gsutil cp	使用此命令可将数据集转码为 Optimized Row Columnar (ORC) 文件格式并写入 Cloud Storage。该命令从 INFILE DD 读取数据，并从 COPYBOOK 文件读取记录布局。 注意：我们建议您使用 qsam decode 和 qsam encode 命令来执行此任务。如需了解使用 qsam 命令的优势，请参阅 qsam 命令的优势。 如果您希望命令从数据源名称 (DSN) 文件读取数据，请使用以下标志： --inDsn：输入数据集 DSN。如果提供，此标志会替换 INFILE DD。 --cobDsn：copybook DSN。如果提供，此标志会替换 COPYBOOK DD。 然后，该命令会打开可配置数量的与 Cloud Storage API 的并行连接，并将 COBOL 数据集转码为列式且经过 GZIP 压缩的 ORC 文件格式。预计压缩比约为 35%。 （可选）您可以使用此命令与在大型机上的虚拟机上运行的 Mainframe Connector gRPC 服务进行交互。为此，请设置 SRVHOST 和 SRVPORT 环境变量，或使用命令行选项提供主机名和端口号。使用 gRPC 服务时，Mainframe Connector 会先将输入数据集复制到 Cloud Storage，然后进行远程过程 (RPC) 调用，指示 gRPC 服务对文件进行转码。 您还可以使用 gsutil cp 命令执行以下任务： 对 gsutil cp 命令执行试运行 将文件从 Cloud Storage 复制到大型机 微调 gsutil cp 命令的性能 使用 gsutil cp 自定义字符集。	是
	gsutil rm	使用此命令可删除存储桶或存储桶中的对象。	否
gszutil 实用程序	gszutil	gszutil 实用程序使用 IBM JZOS Java SDK 运行，并提供一个接受 gsutil 和 BigQuery 命令行调用的 shell 模拟器（使用 JCL）。 注意：我们建议您使用 qsam decode 和 qsam encode 命令来执行此任务。如需了解使用 qsam 命令的优势，请参阅 qsam 命令的优势。 gszutil 实用程序通过接受 COPYBOOK DD 形式的架构来扩展 gsutil 实用程序的功能，使用该架构将 COBOL 数据集直接转码为 ORC，然后再上传到 Cloud Storage。借助 gszutil 实用程序，您还可以使用 JCL 执行 BigQuery query 和 load。 gszutil 实用程序可与 gRPC 服务器搭配使用，有助于减少每秒百万条指令 (MIPS) 的消耗量。我们建议您在生产环境中使用 gszutil 实用程序将 Cloud Storage 中的二进制文件转换为 ORC 格式。	否
qsam 和 vsam 命令	qsam decode	使用此命令可使用 --output-format 实参将 QSAM 文件记录转码为所需格式。原始 QSAM 文件会根据您通过 --max-chunk-size 实参指定的值拆分为多个块。转码后的输出会以按字典顺序排序的文件形式保存在目标路径中。	否
	qsam encode	使用此命令将外部来源的数据转换为 QSAM 文件。 输入由您使用 --input-format 实参指定的值定义。	否
	vsam decode	使用此命令可使用 --output-format 实参将虚拟存储访问方法 (VSAM) 文件记录转码为所需格式。原始 VSAM 文件会根据您通过 --max-chunk-size 实参指定的值拆分为多个块。转码后的输出会以按字典顺序排序的文件形式保存在目标路径中。	否
Pub/Sub 命令	pubsub topics publish	使用此命令将消息发布到 Pub/Sub 主题。	否
其他指令	copy binary	使用此命令将二进制数据集从源路径复制到目标路径。	否
	copy text	使用此命令可将文件复制到您选择的存储位置（例如 Cloud Storage），反之亦然。	否
	curl	使用此命令向 Web 服务或 REST API 发出 HTTP 请求。	否
	gcloud dataflow flex-template run	使用此命令可触发 Dataflow Flex 模板的执行。该命令会从指定的 Flex 模板路径运行作业。如需了解详情，请参阅 gcloud dataflow flex-template run。	否
	systemreport	使用此命令可将必要的系统数据输出到标准输出 (stdout)。这样，Mainframe Connector 支持团队就可以收集诊断问题所需的信息，而无需与客户进行广泛的互动。 根据您使用的标志，systemreport 命令会输出以下系统数据： --supported_ciphers：支持的加密方式 --available_security_providers：可用的安全提供程序	否

使用自定义字符集

Mainframe Connector 支持不同的字符集，这些字符集可将字节解码为 BigQuery 字符串，反之亦然。借助 Mainframe Connector，您可以配置自己的自定义字符集。您可以通过构建 Unicode 字符映射 (UCM) 文件来配置自定义字符集。Mainframe Connector 支持 UCM 格式的以下子集：

<code_set_name>               "<name>"
<uconv_class>                 "SBCS"
<subchar>                     \x1A #Example

CHARMAP
#_______ _________
<U0000> \x00 |0       #For the third column, only 0 is supported.
<U0001> \x01 |0
#etc
END CHARMAP

如果您想使用自定义字符集，请定义 UCM 格式的配置文件。您可以通过设置 --encoding=charset 标志，将此自定义字符集与 gsutil cp 或 bq export 命令搭配使用。

创建自定义字符集时，请验证以下内容：

• 定义 UCM 文件时，请注意以下几点：
  • Mainframe Connector 仅支持使用单字节字符集 (SBCS) 的自定义字符集。
  • Mainframe Connector 仅支持 UCM 精确度指示器 |0。
  • 验证 UCM 文件是否位于 z/OS Unix 系统服务 (USS) 中，而不是位于多个虚拟存储分区数据集 (MVS PDS) 中。
  • 验证 UCM 文件是否以美国信息交换标准码 (ASCII) 格式保存，而不是以扩展二进制编码十进制交换码 (EBCDIC) 格式保存。
• 为每个可能的单字节值提供到 Unicode 字符的显式映射。如果您不确定要将字节映射到哪个 Unicode 字符，建议您将其映射到 U+FFFD。您可以将不同的字节序列映射到同一 Unicode 字符。不过，在这些情况下，映射不是双向的，也就是说，当您将数据加载到 BigQuery 并稍后将其导出回二进制文件时，输出可能与原始输入不同。
• 验证第二列中的字节序列是否唯一。如果多个字节序列映射到同一 Unicode 字符，则此 Unicode 字符会解码为 UCM 文件中最后定义的映射的字节序列。
• 通过将环境变量 BQSH_FEATURE_CUSTOM_CHARSET 设置为 UCM 文件的路径，验证 Mainframe Connector 是否可以找到该 UCM 文件。如果您想使用多个字符集，可以提供多个字符集的路径，并使用英文分号分隔。例如 BQSH_FEATURE_CUSTOM_CHARSET=path1;path2。path 可以指向本地文件，也可以指向 Cloud Storage 中存储的文件。 如果您执行带有 --remote 标志的 gsutil cp 或 bq export 命令来执行远程转码，Mainframe Connector 会使用为 BQSH_FEATURE_CUSTOM_CHARSET 环境变量设置的本地值。当您以独立模式运行 Mainframe Connector 时，情况也是如此。如果 --encoding 标志所指的自定义字符集与您为 BQSH_FEATURE_CUSTOM_CHARSET 设置的值不对应（或者您根本未设置 BQSH_FEATURE_CUSTOM_CHARSET），则命令会退出并显示错误消息。

针对 bq export 命令的性能调优配置

Mainframe Connector 支持为 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。

通过 copybook 创建 BigQuery 表

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

注意： 旧版解析器不支持此功能。

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

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

• --schema_from_copybook：指定用于创建表的 COBOL 簿册。
• --dry_run：（可选）启用后，该命令仅输出生成的 CREATE TABLE SQL 命令，而不执行该命令。此标志默认设置为 false。
• --tablespec "[PROJECT_ID]:[DATASET].[TABLE]"：指定目标表的 BigQuery 项目 ID、数据集和表名称。
• --encoding：指定用于读取 copybook 文件的编码。默认值为 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 参数化

借助 Mainframe Connector，您可以将参数化查询与 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

对 gsutil cp 命令执行试运行

gsutil cp 命令使用 COBOL copybook 对 QSAM 文件进行解码，并在 Cloud Storage 上生成 ORC 文件。您可以使用 dry_run 标志对 gsutil cp 命令进行试运行，并测试以下步骤：

• 解析 COBOL copybook 或数据文件，并检查其是否与 Mainframe Connector 兼容。
• 解码 QSAM 文件，但不将其写入 Cloud Storage。

使用以下命令执行试运行：

gsutil cp \
--dry_run \
gs://result-dir

如果所有步骤都成功执行，该命令会以返回代码 0 退出。如果遇到任何问题，系统会显示错误消息。

使用 dry_run 标志时，系统会记录所有统计信息，例如读取的总字节数、写入的记录数、总错误数。

如果您使用 dry_run 标志，但数据源不存在，该命令不会返回错误。它只会检查 copybook 解析器，然后完成执行。

将文件从 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 文件的 Cloud Storage 统一资源标识符 (URI)。例如 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 命令的性能调优配置

Mainframe Connector 支持为 gsutil cp 命令进行以下性能调优配置。

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

执行示例

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

在此示例中，我们考虑的是一个大文件，因此使用了 8 个线程，达到了线路速率。如果您有足够的内存，建议您将块大小增加到 256 MiB 甚至 512 MiB，因为这样可以减少创建开销和最终确定 Cloud Storage 对象。对于小型文件，使用较少的线程和较小的块可能会产生更好的结果。

解析 maxChunkSize 实参

maxChunkSize 标志接受以数量和计量单位形式表示的值，例如 5 MiB。您可以在数量和数量级之间使用空格。

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

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

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