Copybook 剖析器參考資料

Mainframe Connector 支援兩個版本的 Copybook 剖析器：

  • 原生副本簿剖析器：原生副本簿剖析器會實作以 ANTLR4 為基礎的剖析器，支援 COBOL 副本簿，也是剖析器的建議版本。
  • 舊版複本簿剖析器：舊版複本簿剖析器是舊版剖析器，僅支援極少數的複本簿格式。

您可以根據自己的抄本定義要使用的剖析器。如要進一步瞭解如何定義要使用的剖析器，請參閱「定義副程式剖析器」。

原生抄本剖析器

原生抄本剖析器是剖析器的最新版本，預設會使用這個版本。原生副本簿剖析器會實作以 ANTLR4 為基礎的剖析器，並支援 COBOL 副本簿。

本節列出原生副本簿剖析器執行的預先處理工作。並概略說明原生式抄本剖析器支援的資料類型，以及使用這些資料類型的限制。

預先處理

剖析影本前，原生影本剖析器會先預先處理資料，並執行下列工作：

  • 移除註解行。
  • 解析行續接。
  • 將行號區域和第 73 欄區域空白。
  • 保留預處理器專屬陳述式，例如 EJECT、SPACE 和 TITLE。系統會剖析這些欄位，但會忽略它們。原生副本簿剖析器不支援包含可供 COPY REPLACING 使用的預處理器參數的副本簿。在這些副本簿中，ID 會以冒號 (:) 包圍。

支援的資料類型和限制

以下是原生副本簿剖析器支援的資料類型，以及使用限制：

  • 不支援 66 級 (別名) 或 77 級 (獨立)。
  • 請只使用 PICTURE 欄位。系統支援下列 PICTURE 欄位：
    • Pic A、Pic、Pic B、Pic G (DBCS)、Pic N (國家/地區或 DBCS)、Pic U (UTF8)、Pic X 和區域性小數 (最大精確度 38、最大比例 38)
  • 支援 IBM 16 進制浮點 (HFP)。
  • 不支援 REDEFINES。
  • 請僅使用下列 COMP 欄位。不支援 ALIGN 和 OCCURS。
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • 支援 DATE 和 TIMESTAMP。
  • 支援空值指標。
  • 系統支援雙位元組字元集 (DBCS) 欄位 Pic G 和 Pic N，且應使用這些欄位，而非已淘汰的 Pic T。如要將 Pic N 欄位設為 DBCS 而不指定 USAGE DISPLAY-1，您必須將 NSYMBOL 環境變數設為 DBCS。根據預設，NSYMBOL 會設為 NATIONAL，而 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 類型的選用參數。時區預設為世界標準時間。如要進一步瞭解支援的時區格式，請參閱「支援的時區格式」。
  • --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。

支援空值指標

自 5.13.0 版起，Mainframe Connector 就支援空值指標。如要使用空值指標，您必須定義開頭為 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，當用於抄本中欄位名稱的後置字串時，會解讀為空值指標。

以下清單說明您可以與這些環境變數搭配使用的參數：

  • command：值必須是 null-indicator。
  • –null-value：值 null indicator 表示參照的欄位為空值。--null-value 的值必須是字串或小數。
  • –not-null-value：(選用) 指定後，值 null indicator 會表示參照的欄位非空值。如果未設定此參數，系統會接受任何非 –value-null 的值。–not-null-value 的值必須是字串或小數。
  • –keep：(選用) 如果指定此選項，系統會將 null-indicator 欄位保留為 Optimized Row Columnar (ORC) 檔案格式的資料欄。根據預設，這個欄位不會以 ORC 格式保留。
  • -force-type：(選用) 支援兩個選項：bytes 和 binary，分別會強制將欄位解碼為位元組或二進位。位元組的 null 和 not-null 值會以 HEX 表示 (例如 FA3AB5)。HIGH 和 LOW 常數可用於等同於所有 FF 或所有 00。二進位值的值為一般整數。

如果 null-indicator 沒有參照欄位，主機連接器會顯示錯誤訊息，並停止處理檔案。

範例：

抄本程式碼片段

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 中的位元組 0x43 和 0xC5，但未以 0x0E 和 0x0F 包圍，則必須將副程式欄位名稱重新命名為 03 FLD01-DBCS PIC N USAGE DISPLAY-1，才能正確解碼 DBCS 資料。

支援可變長度字元字串

原生抄本剖析器支援下列 struct 欄位：

  • 10 個變數
  • 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_DATA_SUFFIX 設為要使用的後置字串。

不支援的欄位和結構

下列各節說明不支援的欄位和結構體

COBOL 建構式

COBOL 結構體，即使這些結構體不受支援。如果在副程式中使用這些結構，主機連接器會顯示錯誤。

  • 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 級 (別名) 或 77 級 (獨立)。
  • 不支援 REDEFINES。
  • 系統不支援註解行。
  • 長度為 10 且名稱結尾為 DATE 或 DT 的欄位為日期。這些欄位的解碼方式有所不同。
  • 請僅使用下列 COMP 欄位。不支援 ALIGN 和 OCCURS。
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • 請只使用 PICTURE 欄位。在同一行中定義 PICTURE 欄位，直接放在欄位名稱後方。
  • 您必須對齊所有欄位，並使用單一層級。不支援留言。
  • 請確認第 1 到 6 欄一律空白。