Mainframe Connector API 指令

下表列出 BigQuery、Cloud Storage 和其他可搭配主機架構連接器使用的Google Cloud 指令。

使用自訂字元集

主機連接器支援不同的字元集，可將位元組解碼為 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 檔案時，請注意下列事項：
  • 主機連接器僅支援使用單字節字元集 (SBCS) 的自訂字元集。
  • 主機連接器僅支援 UCM 精確度指標 |0。
  • 請確認 UCM 檔案位於 z/OS Unix 系統服務 (USS) 中，而非多個虛擬儲存空間分割資料集 (MVS PDS)。
  • 請確認 UCM 檔案是以美國國家標準資訊交換碼 (ASCII) 格式儲存，而非延伸二進位碼十進位交換碼 (EBCDIC) 格式。
• 請為每個可能的單位元組值提供明確的對應方式，以便轉換為萬國碼字元。如果不確定要將位元組對應至哪個 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 指令，以便執行遠端轉碼，主機連接器會使用 BQSH_FEATURE_CUSTOM_CHARSET 環境變數的本機值設定。同樣地，在獨立模式中執行 Mainframe Connector 時，也適用相同的做法。如果 --encoding 標記參照的自訂字元集不符於您為 BQSH_FEATURE_CUSTOM_CHARSET 設定的值 (或您根本未設定 BQSH_FEATURE_CUSTOM_CHARSET)，指令會退出並顯示錯誤訊息。

bq export 指令的效能調整設定

Mainframe Connector 支援下列 bq export 指令的效能調整設定：

• exporter_thread_count：(選用) 設定 worker 執行緒的數量。預設值為 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 副本簿解碼 QSAM 檔案，並在 Cloud Storage 上產生 ORC 檔案。您可以使用 dry_run 標記執行 gsutil cp 指令的模擬測試，並測試下列步驟：

• 剖析 COBOL 副本簿或資料檔案，並檢查是否與 Mainframe Connector 相容。
• 解碼 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 指令。如果 Mainframe 上已存在該檔案，請確認您已將 --replace 標記新增至指令。

gsutil cp GCS_URI DSN --recfm=RECFM --lrecl=LRECL --blksize=BLKSIZE --noseek

更改下列內容：

• GCS_URI：Cloud Storage 檔案的 Cloud Storage 統一資源 ID (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，分別代表位元組、kibibyte、mebibyte、gibibyte 和 tebibyte
• 國際格式：KiB/MiB/GiB/TiB，分別代表 kibibyte、mebibyte、gibibyte 和 tebibyte
• 指標格式：b/kb/mb/gb/tb，分別代表千位元組、百萬位元組、千兆位元組和兆位元組

資料大小剖析不區分大小寫。請注意，您無法指定部分金額。例如，使用 716 KiB 而非 0.7 MiB。