Mainframe Connector API コマンド

次の表に、Mainframe Connector で使用できる BigQuery、Cloud Storage、その他のGoogle Cloud コマンドを示します。

カスタマイズされた文字セットを使用する

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 System Services（USS）にあり、複数の仮想ストレージ パーティション データセット（MVS PDS）にないことを確認します。
  • UCM ファイルが、拡張バイナリ コード 10 進交換コード（EBCDIC）形式ではなく、American Standard Code for Information Interchange（ASCII）形式で保存されていることを確認します。
• 可能なすべての単一バイト値から Unicode 文字への明示的なマッピングを提供します。バイトをマッピングする Unicode 文字が不明な場合は、U+FFFD にマッピングすることをおすすめします。異なるバイト シーケンスを同じ Unicode 文字にマッピングできます。ただし、この場合、マッピングは双方向ではありません。つまり、BigQuery にデータを読み込んでからバイナリ ファイルにエクスポートすると、出力が元の入力と異なる場合があります。
• 2 列目のバイト シーケンスが一意であることを確認します。複数のバイト シーケンスが同じ Unicode 文字にマッピングされている場合、この Unicode 文字は、UCM ファイルで最後に定義されたマッピングのバイト シーケンスにデコードされます。
• 環境変数 BQSH_FEATURE_CUSTOM_CHARSET を UCM ファイルのパスに設定して、Mainframe Connector が UCM ファイルを検出できることを確認します。複数の文字セットを使用する場合は、セミコロン区切り文字で区切って複数の文字セットのパスを指定できます。例: BQSH_FEATURE_CUSTOM_CHARSET=path1;path2。path は、ローカル ファイルまたは Cloud Storage に保存されているファイルを指すことができます。--remote フラグを指定して gsutil cp コマンドまたは bq export コマンドを実行し、リモート トランスコーディングを行う場合、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: 省略可。読み取りレコードキューの最大数を設定します。デフォルト値はスレッド数の 2 倍です。
• transcoding_buffer:（省略可）スレッドあたりのトランスコード バッファのサイズを MB 単位で設定します。デフォルト値は 20 MB です。

OVERRIDE_GRPC_WINDOW_MB 環境変数を設定して転送ウィンドウ サイズを大きくすることで、パフォーマンスを向上させることもできます。デフォルトのウィンドウ サイズは 4 MB です。

コピーブックから BigQuery テーブルを作成する

bq mk コマンドを使用すると、COBOL コピーブックの解析から BigQuery テーブルを直接生成できます。ネイティブのコピーブック パーサーは、コピーブック内の VALUE 句からデフォルト値を抽出し、新しく作成された BigQuery テーブルの対応する列に割り当てます。

この機能をテストするために、bq mk コマンドにはドライラン モードも用意されています。このモードでは、BigQuery でテーブルを実際に作成せずに、生成された CREATE TABLE SQL コマンドをプレビューできます。

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 からメインフレーム データセットにファイルをコピーするには、次の例に示すように、メインフレームにダウンロードするファイルの DSN とスペース要件を JCL で指定します。

//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（バイト、kibibyte、mebibyte、gibibyte、tebibyte 用）
• 国際形式: KiB/MiB/GiB/TiB（kibibyte, mebibyte, gibibyte、tebibyte 用）
• 指標形式: b/kb/mb/gb/tb（kilobyte、megabyte、gigabyte、terabyte 用）

データサイズの解析では大文字と小文字が区別されません。部分的な量を指定することはできません。たとえば、0.7 MiB ではなく 716 KiB を使用します。