账簿解析器参考文档

Mainframe Connector 支持两个版本的副本簿解析器：

  • 原生副本簿解析器：原生副本簿解析器实现了基于 ANTLR4 的解析器，支持 COBOL 副本簿，是推荐的解析器版本。
  • 旧版副本簿解析器：旧版副本簿解析器是解析器的旧版本，仅支持极少数副本簿格式。

您可以根据自己的副本簿定义要使用的解析器。如需详细了解如何定义要使用的解析器，请参阅定义副本簿解析器。

原生副本簿解析器

原生副本簿解析器是解析器的最新版本，默认情况下使用此解析器。原生副本簿解析器实现了基于 ANTLR4 的解析器，并支持 COBOL 副本簿。

本部分列出了原生副本簿解析器执行的预处理任务。它还概述了原生副本簿解析器支持的数据类型以及其使用限制。

预处理

在解析副本簿之前，原生副本簿解析器会预处理数据并执行以下任务：

  • 移除注释行。
  • 解析行续接。
  • 清空行号区域和第 73 列区域。
  • 保留预处理器专用语句，例如 EJECT、SPACE 和 TITLE。系统会解析这些字段，但会忽略它们。原生副本簿解析器不支持包含可供 COPY REPLACING 使用的预处理器参数的副本簿。在这些副本簿中，标识符用英文冒号 (:) 括起来。

支持的数据类型和限制

以下是原生副本簿解析器支持的数据类型及其使用限制：

  • 不支持级别 66 (ALIAS) 或 77 (STANDALONE)。
  • 请仅使用 PICTURE 字段。支持以下 PICTURE 字段：
    • Pic A、Pic B、Pic G（DBCS）、Pic N（国家/地区或 DBCS）、Pic U（UTF8）、Pic X 和带时区的十进制（最大精度 38，最大小数位数 38）
  • 支持 IBM 十六进制浮点 (HFP)。
  • 不支持 REDEFINE。
  • 请仅使用以下 COMP 字段。不支持 ALIGN 和 OCCURS。
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • 支持 DATE 和 TIMESTAMP。
  • 支持null 指示器。
  • 支持双字节字符集 (DBCS) 字段 Pic G 和 Pic N，应使用它们来替代现已废弃的 Pic T。如需将 Pic N 字段用作 DBCS 而无需指定 USAGE DISPLAY-1，您必须将 NSYMBOL 环境变量设置为 DBCS。默认情况下，NSYMBOL 设置为 NATIONAL，这会将 USAGE NATIONAL 设置为不包含 USAGE 子句的 Pic N 字段。请注意，NSYMBOL 只能设置为 NATIONAL 或 DBCS。
  • 支持可变长度的字符串。
  • 支持 SIGN 子句。
  • 您必须对所有字段进行对齐，并使用单一缩进级别。
  • 支持评论。

支持日期和时间戳字段

Mainframe Connector 支持将日期和时间戳数据移入和移出 BigQuery。为此，您必须按以下格式定义以 SUFFIX 开头的环境变量：

SUFFIX_SUFFIX_STRING="command --format FORMAT --timezone TIMEZONE"

以下列表更详细地介绍了该格式：

  • SUFFIX_SUFFIX_STRING：您可以使用此环境变量来定义日期和时间戳数据。SUFFIX_STRING 名称对应于后缀 -SUFFIX_STRING 或 _SUFFIX_STRING，当用作副本簿中字段名称的后缀时，应将其解读为日期或时间戳。确保 SUFFIX_STRING 不包含连字符或下划线。
  • command：定义应用于解析字段的解码器。支持的命令包括 date-converter 和 timestamp-converter。
  • --format：用于定义日期或时间戳格式的参数。您最多可以指定五种不同的格式（用英文逗号分隔）。如果有多个格式与给定输入匹配，系统会使用第一个匹配的格式将数据加载到 BigQuery。如果为导出指定了多个格式，则系统仅会使用第一个格式。如需详细了解有效格式，请参阅支持的日期和时间戳格式。
  • --timezone：类型为 TIMESTAMP 的可选参数。默认时区为世界协调时间 (UTC)。如需详细了解支持的时区格式，请参阅支持的时区格式。
  • --omitsuffix（可选）：如果指定此参数，系统会从 BigQuery 中显示的字段名称中移除 -SUFFIX_STRING 或 _SUFFIX_STRING。

如需为 SUFFIX_SUFFIX_STRING 添加别名，您可以设置环境变量 SUFFIX_SUFFIX_ALIAS=$SUFFIX_SUFFIX_STRING。

示例：

  • 如果您将环境变量定义为 SUFFIX_DT8="date-converter --format yyyyMMdd"，则后缀为 -DT8 或 _DT8 的字段将是 BigQuery 中的 DATE 类型字段，其模式为 yyyyMMdd。
  • 如果您将环境变量定义为 SUFFIX_DT10="date-converter --format MM-dd-yyyy"，则后缀为 -DT10 或 _DT10 的字段将是 BigQuery 中的 DATE 类型字段，其模式为 MM-dd-yyyy。
  • 如果您将环境变量定义为 SUFFIX_DT="date-converter --format 'MM-dd-yyyy,MM/dd/yyyy'"，则后缀为 -DT 或 _DT 的字段将是 BigQuery 中的 DATE 类型字段，其模式为 MM-dd-yyyy 或 MM/dd/yyyy。
  • 如果您将两个环境变量定义为 SUFFIX_TIMESTAMP="timestamp-converter --format yyyy-MM-dd SUFFIX_TIMESTAMP=timestamp-converter --format 'yyyy-MM-dd HH.mm.ss.SSSSSS' --timezone America/New_York" 和 SUFFIX_TS=$SUFFIX_TIMESTAMP，则具有以下后缀之一的字段（-TIMESTAMP、_TIMESTAMP、-TS 或 _TS）将在 BigQuery 中成为 TIMESTAMP 类型字段，其模式为 yyyy-MM-dd HH:mm:ss.SSSSSS，时区为 America/New_York。

支持 null 指示器

从 5.13.0 版开始，大型机连接器支持 null 指示器。如需使用 null 指示器，您必须定义以 SUFFIX 开头的环境变量，格式如下：

SUFFIX_NULL_INDICATOR_NAME="command --null-value NULL_VALUE --not-null-value NOT_NULL_VALUE"

NULL_INDICATOR_NAME 对应于后缀 -NULL_INDICATOR_NAME 或 _NULL_INDICATOR_NAME，当用作副本集中字段名称的后缀时，会被解读为 null 指示器。

下表介绍了可与这些环境变量搭配使用的参数：

  • command：值必须为 null-indicator。
  • –null-value：值 null indicator 表示引用的字段为 null。--null-value 的值必须是字符串或小数。
  • –not-null-value：（可选）如果指定了值 null indicator，则表示所引用的字段不为 null。如果未设置此参数，则接受任何非 –value-null 的值。–not-null-value 的值必须是字符串或小数。
  • –keep：（可选）指定此标志后，null-indicator 字段会保留为优化行列式 (ORC) 文件格式的列。默认情况下，此字段不会以 ORC 格式保留。
  • -force-type：（可选）支持两个选项：bytes 和 binary，分别强制将字段解码为字节或二进制。对于字节，null 和 not-null 的值表示为 HEX（例如 FA3AB5）。HIGH 和 LOW 常量可用，它们等同于所有 FF 或所有 00。对于二进制，值为常规整数。

如果 null-indicator 没有引用的字段，Mainframe 连接器会显示错误消息并停止处理文件。

示例：

抄本代码段

10 COL1-NID1            PIC S9(4) USAGE COMP.
10 COL1                 PIC S9(6) USAGE COMP.

10 FIELD       PIC        X(10).
10 FIELD-NID2  PIC        X(1).

10 COL2       PIC        X(10).
10 COL2-NULL  PIC        X(1).

环境变量定义

SUFFIX_NID1="null-indicator --null-value -1 --not-null-value 0"
# Copybook fields with NID1 suffix null indicator configuration.
SUFFIX_NID2="null-indicator --null-value '?'"
# Copybook fields with NID2 suffix null indicator configuration.
SUFFIX_NULL="null-indicator --null-value '?' --keep"
# Copybook fields with NULL suffix null indicator configuration.

支持 DBCS 字段

使用 DBCS 字段时，请确保：

  • 使用 PIC G 或 Pic N DBCS 字段时，如果使用 gsutil cp 或 bq export 命令，则必须在 encoding 选项或 ENCODING 环境变量中提供以下有效的多字节字符集 (MBCS) 编码之一：
    • x-IBM930
    • x-IBM933
    • x-IBM935
    • x-IBM937
    • x-IBM939
    • x-IBM942
    • x-IBM942C
    • x-IBM943
    • x-IBM943C
    • x-IBM949
    • x-IBM949C
    • x-IBM950
    • x-IBM964
    • x-IBM970
    • x-IBM1364
  • 如果复制簿字段仅包含 DBCS 字节，但这些字节未被 shift-out (0x0E) 和 shift-in (0x0F) 字节括起来，您必须向字段名称添加后缀 _DBCS，以确保这些字节被解码为 DBCS 字节。

例如，如果与复制簿字段 03 FLD01 PIC N USAGE DISPLAY-1 对应的数据包含编码为 x-IBM930 且未被 0x0E 和 0x0F 括起来的字节 0x43 和 0xC5，则必须将复制簿字段名称重命名为 03 FLD01-DBCS PIC N USAGE DISPLAY-1，才能正确解码 DBCS 数据。

支持可变长度的字符串

原生副本簿解析器支持以下 struct 字段：

  • 10 var
  • 15 var-LEN PIC 9(4) USAGE COMP
  • 15 var-TEXT PIC X(n)

struct 字段中的第一个字段是第二个字段（字符串字段）的长度。您可能需要根据记录长度在记录末尾添加一些内边距，如下图所示。

向可变长度的字符串添加了内边距。
图 1。向可变长度的字符串添加了内边距。

Mainframe Connector 会先从变量名称中移除后缀，然后再将数据保存到 BigQuery 中。在此示例中，变量名称将为 var。

如需使用 struct 字段，请将环境变量 BQSH_FEATURE_VARIABLE_LENGTH_ENABLED 设置为 yes 或 true。

使用 struct 字段时，请确保：

  • struct 中第一个参数的后缀为 -LEN。如果您想使用其他后缀，则必须将环境变量 BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX 设置为您要使用的后缀。
  • struct 中第二个参数的后缀为 -TEXT。如果您想使用其他后缀，必须将环境变量 BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX 设置为您要使用的后缀。

不受支持的字段和结构

以下部分介绍了

COBOL 结构

COBOL 结构（即使这些结构不受支持）。如果您在副本集中使用这些结构，Mainframe 连接器会显示错误。

  • dataAlignedClause
  • dataBlankWhenZeroClause
  • dataCommonOwnLocalClause
  • dataIntegerStringClause
  • dataJustifiedClause
  • dataOccursClause
  • dataReceivedByClause
  • dataRecordAreaClause
  • dataRenamesClause
  • dataSignClause
  • dataSynchronizedClause
  • dataThreadLocalClause
  • dataTypeClause
  • dataTypeDefClause
  • dataUsingClause

数据类型

支持 COMP-1 和 COMP-2 等 COBOL 数据类型。

旧版副本簿解析器

旧版 Copybook 解析器是支持非 COBOL 功能的旧版解析器。如果您使用的是基于 DSL 的副本簿，则旧版解析器可能更适合，因为原生副本簿解析器可能会导致错误。

您可以使用副本簿 DD，但需遵循以下限制：

  • 不支持级别 66 (ALIAS) 或 77 (STANDALONE)。
  • 不支持 REDEFINE。
  • 不支持注释行。
  • 长度为 10 且名称以 DATE 或 DT 结尾的字段是日期。对这些字段进行解码的方式有所不同。
  • 请仅使用以下 COMP 字段。不支持 ALIGN 和 OCCURS。
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • 请仅使用 PICTURE 字段。在同一行中，直接在字段名称后面定义 PICTURE 字段。
  • 您必须对所有字段进行对齐，并使用单一层级。不支持评论。
  • 确保第 1 到第 6 列始终包含空白。