Mainframe Connector API 指令

下表列出可搭配 Mainframe Connector 使用的 BigQuery、Cloud Storage 和其他Google Cloud 指令。

注意： 對於支援遠端執行的指令，您可以使用 remoteUrl 選項，而不是 remoteHost 和 remotePort。remoteUrl 選項必須包含配置、主機和連接埠。如果配置為 https，且未提供信任儲存區做為選項 trustCertCollectionFilePath 或環境變數 TRUST_CERT_COLLECTION_FILE_PATH，系統會使用預設的信任儲存區。

產品	指令	說明	支援遠端轉碼
BigQuery 指令	bq export	使用這個指令建立二進位檔案。這項指令接受 COPYBOOK DD 做為輸入。 注意：建議您使用 qsam decode 和 qsam encode 指令執行這項工作。如要瞭解使用 qsam 指令的優點，請參閱「qsam 指令的優點」。 bq export 指令支援部分效能調整功能。詳情請參閱「bq export 指令的效能提升」。您可以使用 bq export 指令搭配自訂字元集。詳情請參閱「使用自訂字元集」。 注意：bq export 指令無法匯出大型 Bigtable 資料表。如要避免發生錯誤，請在匯出大型表格時，將 -allowLargeResults 標記新增至 bq export 指令。	是
	bq load	使用這項指令將資料載入資料表。	否
	bq mk	使用這項指令建立需要設定分割和叢集功能的 BigQuery 資源，例如內建資料表或外部資料表。 您也可以使用 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 rm	使用這項指令可永久刪除 BigQuery 資源。這項指令會永久刪除資源，因此建議您謹慎使用。	否
Cloud Run 指令	cloud run job execute	使用這個指令從大型主機觸發 Cloud Run 工作。	否
	cloud run job logs	使用這個指令查看特定 Cloud Run 工作執行的記錄。	否
	cloud run job cancel	使用這項指令取消 Cloud Run 工作。	否
Cloud Storage 指令	scp	使用這項指令將文字或二進位資料複製到 Cloud Storage。 您可以使用簡單的二進位複製模式，將資料集從 IBM z/OS 複製到 Cloud Storage，且不會修改資料，這項作業是資料管道的一部分。您也可以選擇將字元編碼從延伸二進位編碼十進位互換碼 (EBCDIC) 轉換為 ASCII UTF-8，並新增換行符號。 注意：建議您使用 copy text 指令執行這項工作，因為這些指令的功能更完善。 您也可以使用這項指令，複製作業控制語言 (JCL) 中定義的應用程式原始碼。	否
gsutil 公用程式	gsutil cp	使用這項指令轉碼資料集，並以最佳化列欄 (ORC) 檔案格式寫入 Cloud Storage。這項指令會從 INFILE DD 讀取資料，並從 COPYBOOK 檔案讀取記錄版面配置。 注意：建議您使用 qsam decode 和 qsam encode 指令執行這項工作。如要瞭解使用 qsam 指令的優點，請參閱「使用 qsam 指令的優點」。 如要讓指令從資料來源名稱 (DSN) 檔案讀取資料，請使用下列標記： --inDsn：輸入資料集 DSN。如果提供這個標記，系統會覆寫 INFILE DD。 --cobDsn：副本 DSN。如果提供這個旗標，系統會覆寫 COPYBOOK DD。 接著，這項指令會開啟可設定數量的平行連線至 Cloud Storage API，並將 COBOL 資料集轉碼為直欄式和 GZIP 壓縮的 ORC 檔案格式。壓縮率約為 35%。 您可以視需要使用這項指令，與在大型主機 VM 上執行的 Mainframe Connector gRPC 服務互動。如要這麼做，請設定 SRVHOST 和 SRVPORT 環境變數，或使用指令列選項提供主機名稱和通訊埠號碼。使用 gRPC 服務時，Mainframe Connector 會先將輸入資料集複製到 Cloud Storage，然後發出遠端程序呼叫 (RPC)，指示 gRPC 服務轉碼檔案。 您也可以使用 gsutil cp 指令執行下列工作： 執行 gsutil cp 指令的模擬測試 將檔案從 Cloud Storage 複製到大型主機 微調 gsutil cp 指令的效能 使用 gsutil cp 自訂字元集。	是
	gsutil rm	使用這項指令刪除 bucket 或 bucket 中的物件。	否
gszutil 公用程式	gszutil	gszutil 公用程式會使用 IBM JZOS Java SDK 執行，並提供接受 gsutil 和 BigQuery 指令列呼叫的 Shell 模擬器 (使用 JCL)。 注意：建議您使用 qsam decode 和 qsam encode 指令執行這項工作。如要瞭解使用 qsam 指令的優點，請參閱「使用 qsam 指令的優點」。 gszutil 公用程式會接受 COPYBOOK DD 形式的結構定義，並使用該結構定義將 COBOL 資料集直接轉碼為 ORC，然後上傳至 Cloud Storage，藉此擴充 gsutil 公用程式的功能。gszutil 公用程式也允許您使用 JCL 執行 BigQuery query 和 load。 gszutil 公用程式可與 gRPC 伺服器搭配使用，有助於減少每秒百萬指令數 (MIPS) 的消耗量。建議您在實際工作環境中使用 gszutil 公用程式，將 Cloud Storage 中的二進位檔案轉換為 ORC 格式。	否
qsam 和 vsam 指令	qsam decode	使用這個指令和 --output-format 引數，將 QSAM 檔案記錄轉碼為所需格式。原始 QSAM 檔案會根據您使用 --max-chunk-size 引數指定的值，分割成多個區塊。轉碼輸出內容會儲存在目標路徑中，並依字典順序排序。	否
	qsam encode	使用這項指令將外部來源的資料轉換為 QSAM 檔案。 輸入內容是由您使用 --input-format 引數指定的值定義。	否
	vsam decode	使用這項指令，透過 --output-format 引數，將虛擬儲存空間存取方法 (VSAM) 檔案記錄轉碼為所需格式。系統會根據您使用 --max-chunk-size 引數指定的值，將原始 VSAM 檔案分割成區塊。轉碼輸出內容會儲存在目標路徑中，並依字典順序排序。	否
Pub/Sub 指令	pubsub topics publish	使用這個指令將訊息發布至 Pub/Sub 主題。	否
其他指令	copy binary	使用這項指令，將二進位資料集從來源路徑複製到目的地路徑。	否
	copy text	使用這項指令將檔案複製到您選擇的儲存位置 (例如 Cloud Storage)，反之亦然。	否
	curl	使用這項指令向 Web 服務或 REST API 發出 HTTP 要求。	否
	gcloud dataflow flex-template run	使用這項指令觸發執行 Dataflow 彈性範本。這項指令會從指定的彈性範本路徑執行工作。詳情請參閱 gcloud dataflow flex-template run。	否
	systemreport	使用這個指令將必要的系統資料列印至標準輸出 (stdout)。這樣一來，Mainframe Connector 支援團隊就能收集診斷問題所需的資訊，不必與客戶進行大量互動。 根據您使用的標記，systemreport 指令會列印下列系統資料： --supported_ciphers：支援的密碼 --available_security_providers：可用的安全性供應商	否

使用自訂字元集

Mainframe Connector 支援不同的字元集，可將位元組解碼為 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 檔案時，請注意下列事項：
  • Mainframe Connector 僅支援使用單一位元組字元集 (SBCS) 自訂的字元集。
  • Mainframe Connector 僅支援 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 檔案的路徑，確認 Mainframe Connector 可以找到 UCM 檔案。如要使用多個字元集，請提供多個字元集的路徑，並以半形分號分隔。例如 BQSH_FEATURE_CUSTOM_CHARSET=path1;path2。path 可以指向本機檔案，也可以指向儲存在 Cloud Storage 中的檔案。如果您執行 gsutil cp 或 bq export 指令時使用 --remote 旗標來執行遠端轉碼，Mainframe Connector 會使用為 BQSH_FEATURE_CUSTOM_CHARSET 環境變數設定的本機值。在獨立模式下執行 Mainframe Connector 時，也適用相同規定。如果 --encoding 旗標參照的自訂字元集與您為 BQSH_FEATURE_CUSTOM_CHARSET 設定的值不符 (或您完全未設定 BQSH_FEATURE_CUSTOM_CHARSET)，指令會結束並顯示錯誤訊息。

bq export 指令的效能調整設定

Mainframe Connector 支援 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 副本解碼 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 指令。如果檔案已存在於大型主機上，請確認您已將 --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 指令的效能調整設定

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，分別代表位元組、KiB、MiB、GiB 和 TiB
• 國際格式：KiB/MiB/GiB/TiB，分別代表 kibibyte、mebibyte、gibibyte 和 tebibyte
• 公制格式：b/kb/mb/gb/tb，分別代表 KB、MB、GB 和 TB

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