Mainframe Connector API 参考文档

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

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

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

使用自定义字符集

大型机连接器支持将字节解码为 BigQuery 字符串的不同字符集，反之亦然。借助大型机连接器，您可以配置自己的自定义字符集。您可以通过构建 Unicode 字符映射 (UCM) 文件来配置自定义字符集。大型机连接器支持 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 文件时，请注意以下事项：
  • 大型机连接器仅支持使用单字节字符集 (SBCS) 的自定义字符集。
  • 大型机连接器仅支持 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 文件的路径，确保大型机连接器可以找到 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 命令的性能调整配置

大型机连接器支持为 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 参数化

借助 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 副本簿解码 Queued Sequential Access Method (QSAM) 文件，并在 Cloud Storage 上生成 ORC 文件。您可以使用 dry_run 标志对 gsutil cp 命令进行试运行，并测试以下步骤：

• 解析 COBOL 副本簿或数据文件，并检查其是否与大型机连接器兼容。
• 解码 QSAM 文件，而不将其写入 Cloud Storage。

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

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

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

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

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

将文件从 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 命令的性能调整配置

大型机连接器支持为 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。