Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Copybook 剖析器參考資料

Mainframe Connector 使用以 ANTLR4 為基礎的剖析器，支援標準 COBOL 抄本。

本文列出 Copybook 剖析器執行的預先處理工作、支援的資料類型和使用限制，以及如何使用 qsam decode 和 qsam encode 指令，透過轉碼器設定來設定欄位修飾符。

預先處理

剖析 Copybook 前，Copybook 剖析器會預先處理資料，並執行下列步驟：

移除註解行 (第 7 欄中的 *，或內嵌 *> 和 *>CE 註解)。
解析接續行 (第 7 欄中的 -，後接引號常值)。
將序號區域 (第 1 至 6 欄) 和第 73 欄及之後的欄位留空。程式碼必須從第 8 欄或之後開始。
保留預處理器專屬陳述式，例如 EJECT、SKIP1、SKIP2、SKIP3 和 TITLE。系統會剖析這些陳述式，但會忽略。抄本剖析器不支援含有 COPY REPLACING 可用預處理器參數的抄本。在這些抄本中，ID 會以冒號 (:) 括住。

支援的資料類型和限制

以下是 Copybook 剖析器支援的資料類型和使用限制：

一本 copybook 只能有一個頂層 01 記錄，且 01 記錄不能有 OCCURS 子句。
不支援 66 級 (RENAMES/別名) 和 77 級 (獨立) 欄位。系統會剖析並忽略 88 級 (條件名稱)。
除了十六進位浮點欄位 (COMP-1 和 COMP-2) 之外，所有基本 (非群組) 欄位都必須有 PICTURE 子句。系統支援下列 PICTURE 欄位：
- 字母 (PIC A)、英數字元 (PIC X) 和英數字元編輯 (A、X、9、B、0、/)。
- PIC G (DBCS；需要 USAGE DISPLAY-1)。
- PIC N (國家或 DBCS) 和國家編輯 (N、B、0、/)。
- PIC U (UTF-8)，包括 PIC U BYTE-LENGTH n。
- 數值 (9、S、V) 和數值編輯 ($、B、/、V、Z、0、9、,、.、*、+、-、CR、DB)。請注意，系統不支援 PIC P (縮放位置)。
- 有效位數不超過 18 的區間十進位和壓縮十進位欄位會解碼為 64 位元類型 (LONG 或 DECIMAL64)，有效位數較高的欄位則會解碼為任意有效位數類型 (BIG_INTEGER 或 BIG_DECIMAL)。schema_validation_mode 設為 BIG_QUERY 時，支援的最大有效位數為 76 (BIGNUMERIC)，最大小數位數為 38 (POSTGRES 的最大有效位數為 147,455，最大小數位數為 16,383；MYSQL 的最大有效位數為 65，最大小數位數為 30)。
IBM 十六進位浮點 (HFP) 支援使用 COMP-1/COMPUTATIONAL-1 (單精度，4 位元組) 和 COMP-2/COMPUTATIONAL-2 (雙精度，8 位元組)，或在轉碼器設定中套用 hfp 欄位修飾符。
如果所有重新定義的變體都具有相同的位元組大小，則靜態大小欄位支援 REDEFINES 子句。重新定義的欄位無法做為 OCCURS DEPENDING ON 子句的長度欄位，或 null_if 修飾符的 target_field。
固定長度陣列 (OCCURS n TIMES)、動態長度陣列 (OCCURS min TO max TIMES DEPENDING ON field) 和封裝動態長度陣列 (OCCURS UNBOUNDED DEPENDING ON field) 支援 OCCURS 子句。不支援 OCCURS 子句中的 ASCENDING/DESCENDING KEY 和 INDEXED BY 詞組，且 DEPENDING ON 必須參照範圍內的欄位名稱。
系統僅支援下列 USAGE 子句：
- DISPLAY (英數字元和區間十進位欄位的預設值)
- DISPLAY-1 (DBCS)
- NATIONAL (PIC N 欄位的預設值；編碼為 UTF-16BE)
- UTF-8 (PIC U 欄位的預設值)
- BINARY、COMP、COMPUTATIONAL、COMP-4、COMPUTATIONAL-4、COMP-5、COMPUTATIONAL-5
- COMP-3、COMPUTATIONAL-3、PACKED-DECIMAL
- COMP-1、COMPUTATIONAL-1、COMP-2、COMPUTATIONAL-2
DATE 和 TIMESTAMP 支援使用轉碼器設定。
使用轉碼器設定支援空值指標。
支援雙位元組字元集 (DBCS) 欄位 PIC G 和 PIC N。根據預設，沒有 USAGE 子句的 PIC N 欄位會指派 USAGE NATIONAL (UTF-16BE)。如要將 PIC N 欄位做為 DBCS 使用，請在副本中指定 USAGE DISPLAY-1，或在轉碼器設定中覆寫其字元編碼。
使用轉碼器設定，可支援可變長度字元字串。
支援 SIGN 子句 (LEADING、TRAILING、SEPARATE CHARACTER)。
支援註解。

支援日期和時間戳記欄位

Mainframe Connector 支援使用轉碼器設定 (--transcode-configuration) 中的 format_date 和 format_timestamp 欄位修飾符，解碼及編碼日期和時間戳記欄位。您可以使用 field_suffixes 將這些修飾符套用至相符的欄位，或使用 field_overrides 套用至特定欄位：

{
  "field_suffixes": [
    {
      "suffix": "SUFFIX_STRING",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": FIELD_SIZE,
              "pattern": "FORMAT_PATTERN"
            }
          ]
        }
      }
    }
  ]
}

以下清單詳細說明設定屬性：

suffix：比對名稱結尾為 -SUFFIX_STRING 或 _SUFFIX_STRING 的任何抄本欄位 (不區分大小寫)。請確認 suffix 開頭不是連字號或底線。或者，您也可以搭配使用 field_overrides 和 "field": "FIELD_NAME"，指定個別欄位。
format_date/format_timestamp：定義用於剖析或格式化欄位的修飾符：
- format_date 可套用至有大小限制的字串欄位 (PIC X) 或整數數值欄位 (例如 PIC 9(n)、COMP 或 COMP-3，小數位數為 0，精確度最高為 18，在格式化之前會動態轉換為不帶正負號的字串表示法)。
- format_timestamp 可套用至有大小限制的字串欄位 (PIC X)。除非模式中包含時區或偏移量，否則時間戳記會以世界標準時間解讀。
formats：DateTimeFormat 物件清單，每個物件都會指定：
- size：套用模式的欄位大小 (字串欄位的位元組長度，或數值欄位的精確度)。
- pattern：日期或時間戳記模式。解碼 (qsam decode) 期間，系統會依序評估與欄位大小相符的格式，直到找到相符的格式為止。編碼 (qsam encode) 期間，系統只會使用與欄位大小相符的第一個格式。如要進一步瞭解有效格式，請參閱「支援的日期和時間戳記格式」。
移除後置字串 (選用)：如要從輸出欄位名稱中移除 -SUFFIX_STRING 或 _SUFFIX_STRING，請在轉碼器設定的 transformations 陣列中新增 rename 轉換。

範例

如要將結尾為 -DT8 或 _DT8 的 8 位元組欄位格式化為 DATE，並使用 yyyyMMdd 模式，以及將結尾為 -DT 或 _DT 的 10 位元組欄位格式化為 MM-dd-yyyy 或 MM/dd/yyyy：

{
  "field_suffixes": [
    {
      "suffix": "DT8",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": 8,
              "pattern": "yyyyMMdd"
            }
          ]
        }
      }
    },
    {
      "suffix": "DT",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": 10,
              "pattern": "MM-dd-yyyy"
            },
            {
              "size": 10,
              "pattern": "MM/dd/yyyy"
            }
          ]
        }
      }
    }
  ]
}

如要將結尾為 -TIMESTAMP、_TIMESTAMP、-TS 或 _TS 的 26 位元組欄位格式化為 TIMESTAMP，並使用 yyyy-MM-dd HH.mm.ss.SSSSSS 模式，以及從輸出資料欄名稱中移除後置字串：

{
  "field_suffixes": [
    {
      "suffix": "TIMESTAMP",
      "modifier": {
        "format_timestamp": {
          "formats": [
            {
              "size": 26,
              "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
            }
          ]
        }
      }
    },
    {
      "suffix": "TS",
      "modifier": {
        "format_timestamp": {
          "formats": [
            {
              "size": 26,
              "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
            }
          ]
        }
      }
    }
  ],
  "transformations": [
    {
      "rename": {
        "find": "^(.*)[-_](TIMESTAMP|TS)$",
        "replace": "$1"
      }
    }
  ]
}

支援空值指標

Mainframe Connector 支援空值指標，方法是在轉碼器設定 (--transcode-configuration) 中使用 null_if 欄位修飾符。

如要設定以後置字串為基礎的空值指標 (其中 COL1-NID 等欄位會做為同一記錄中 COL1 的空值指標)，請使用 "is_inverse": true 和 "target_field": "$self" 在 field_suffixes 中定義項目：

{
  "field_suffixes": [
    {
      "suffix": "NULL_INDICATOR_NAME",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "NULL_VALUE",
          "non_null_value": "NOT_NULL_VALUE"
        }
      }
    }
  ]
}

下表列出可用於設定空值指標的參數：

suffix：對應至 -NULL_INDICATORNAME 或 NULL_INDICATOR_NAME 後置字串，用於識別副本中的空值指標欄位。
is_inverse：在 FieldSuffix 上設為 true 時，修飾符會套用至同層級欄位，其名稱與指標欄位相同，但不含後置字串 (例如，指標為 COL1-NID1 時，則為 COL1)，而 "$self" 則是指標欄位本身。您也可以使用 field_overrides 直接在特定欄位上套用 null_if，並將 target_field 設為指標欄位的名稱。
null_value 或 null_values：指定 target_field 中的單一值 (null_value) 或值清單 (null_values)，表示參照欄位為 null。
non_null_value 或 non_null_values：(選用) 指定 target_field 中的單一值 (non_null_value) 或值清單 (non_null_values)，表示參照的欄位不是 null。如果省略，則 null_value 或 null_values 以外的任何值都會視為非空值。必須指定至少一個 null_value(s) 或 non_null_value(s)。
排除或保留空值指標欄位：根據預設，空值指標欄位會保留為輸出結構定義中的資料欄。如要在轉碼期間使用空值指標欄位，但從輸出資料表中省略該欄位，請在 transformations 陣列中為指標欄位新增 exclude 轉換 (請勿將 filler 修飾符套用至空值指標欄位，因為 filler 會完全略過解碼欄位)。
覆寫指標欄位類型：(選用) 如要強制將空值指標欄位解碼為 bytes 或 binary，請使用 "modifier": { "bytes": {} } 或 "modifier": { "binary": {} } 為指標欄位新增非反向 field_suffixes (或 field_overrides) 規則。如果是 bytes，請將 null_value 和 non_null_value 表示為十六進位字串 (例如 "FF" 或 "00")。

範例

在下列範例中，COL1-NID1 和 FIELD-NID2 經評估為空值指標後，會從輸出資料表中排除，而 COL2-NULL 則會保留在輸出結構定義中。

Copybook 程式碼片段：

01 REC.
   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).

轉碼器設定 (transcode-configuration.json)：

{
  "field_suffixes": [
    {
      "suffix": "NID1",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "-1",
          "non_null_value": "0"
        }
      }
    },
    {
      "suffix": "NID2",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    },
    {
      "suffix": "NULL",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    }
  ],
  "transformations": [
    {
      "exclude": {
        "field": "COL1-NID1"
      }
    },
    {
      "exclude": {
        "field": "FIELD-NID2"
      }
    }
  ]
}

支援 DBCS 欄位

使用 DBCS 欄位 (PIC G 或 PIC N 搭配 USAGE DISPLAY-1) 時，請確認下列事項：

PIC G 欄位必須明確指定 USAGE DISPLAY-1。
不含 USAGE 子句的 PIC N 欄位預設為 USAGE NATIONAL (UTF-16BE)。如要將 PIC N 欄位視為 DBCS 欄位，請在副本中指定 USAGE DISPLAY-1 (或在轉碼器設定中覆寫其編碼)。
根據預設，USAGE DISPLAY-1 欄位會使用 cp300 (x-IBM300) DBCS 字元集進行解碼和編碼，該字元集預期原始 DBCS 位元組不含移出 (0x0E) 和移入 (0x0F) 控制字元。
如要使用其他 DBCS 字元集 (例如 Cp834) 或使用移出 (0x0E) 和移入 (0x0F) 位元組的多位元組字元集 (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)，請在轉碼器設定 (--transcode-configuration) 中設定 string 欄位修飾符。

您可以使用 defaults.dbcs 為所有 USAGE DISPLAY-1 欄位全域設定 DBCS 編碼，或使用 field_overrides 或 field_suffixes 為特定欄位設定：

{
  "defaults": {
    "dbcs": {
      "string": {
        "encoding": "x-IBM930"
      }
    }
  }
}

支援可變長度字元字串

Copybook 剖析器支援可變長度字元字串群組欄位，方法是在轉碼器設定中使用 varlen 欄位修飾符：

10 VAR-GRP.
   15 VAR-LEN  PIC 9(4) USAGE COMP.
   15 VAR-TEXT PIC X(50).

使用 varlen 欄位修飾符時，請確保下列事項：

在轉碼器設定中使用 field_overrides 或 field_suffixes，將 varlen 修飾符套用至群組項目 (例如 VAR-GRP)：

{
  "field_overrides": [
    {
      "field": "VAR-GRP",
      "modifier": {
        "varlen": {}
      }
    }
  ]
}

群組項目必須剛好包含兩個子欄位：
1. 第一個子欄位必須解碼為 64 位元整數 (LONG，例如二進位 COMP 或區域十進位整數欄位)，用於指定字串資料的位元組長度。
2. 第二個子欄位必須是未經修改的字串欄位 (例如 PIC X(n)、PIC N(n) 或 PIC U(n))。
不需要特定子欄位後置字串 (例如 -LEN 或 -TEXT)，輸出結構定義中的結果資料欄會使用群組項目的名稱 (VAR-GRP)。

不支援的欄位和建構項目

以下各節說明 Copybook 剖析器不支援的欄位和建構項目。

不支援的 COBOL 建構項目

Copybook 剖析器可以剖析下列 COBOL 建構，即使這些建構不受支援。如果您在抄本中使用這些結構，Mainframe Connector 會顯示錯誤：

ALIGNED
BLANK WHEN ZERO
COMMON、OWN、LOCAL
DYNAMIC LENGTH (例如 PIC X DYNAMIC LENGTH 或 PIC U DYNAMIC LENGTH LIMIT n)
INTEGER、STRING
JUSTIFIED
OCCURS 中的 ASCENDING/DESCENDING KEY
OCCURS 中的 INDEXED BY
RECEIVED BY
RECORD AREA
RENAMES
SYNCHRONIZED/SYNC
THREAD-LOCAL
TYPE IS ...
TYPEDEF
USING LANGUAGE/CONVENTION

不支援的資料類型

下列 USAGE 類型可由文法剖析，但 Copybook 編譯器不支援：

BIT
CONTROL-POINT
DATE
DOUBLE
EVENT
FUNCTION-POINTER
INDEX
KANJI
LOCK
POINTER
PROCEDURE-POINTER
REAL
SQL
TASK