Mainframe Connector API リファレンス

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

注: リモート実行をサポートするコマンドの場合は、remoteHost と remotePort の代わりに remoteUrl オプションを使用できます。remoteUrl オプションには、スキーム、ホスト、ポートを含める必要があります。スキームが https で、オプション trustCertCollectionFilePath または環境変数 TRUST_CERT_COLLECTION_FILE_PATH としてトラストストアが指定されていない場合、システムのデフォルトのトラストストアが使用されます。

プロダクト	コマンド	説明	リモート コード変換をサポート
BigQuery コマンド	bq export	このコマンドを使用してバイナリ ファイルを作成します。このコマンドは、COPYCOPY DD を入力として受け取ります。 bq export コマンドは、一部のパフォーマンス チューニング機能をサポートしています。詳細については、bq export コマンドのパフォーマンスの改善をご覧ください。 カスタマイズされた文字セットは、bq export コマンドを使用して使用できます。詳細については、カスタマイズされた文字セットを使用するをご覧ください。 注: bq export コマンドは、サイズの大きい Bigtable テーブルのエクスポート リクエストを失敗させます。エラーを回避するには、大きなテーブルをエクスポートするときに bq export コマンドに -allowLargeResults フラグを追加します。	○
	bq load	このコマンドを使用して、テーブルにデータを読み込みます。詳細については、bq load をご覧ください。	×
	bq mk	このコマンドを使用すると、パーティショニングとクラスタリングを設定する必要のある BigQuery リソース（組み込みテーブルや外部テーブルなど）を作成できます。詳細については、bq mk をご覧ください。 bq mk コマンドを使用して、COBOL コピーブックの解析から BigQuery テーブルを直接生成することもできます。詳細については、コピーブックから BigQuery テーブルを作成するをご覧ください。	×
	bq query	このコマンドを使用して、指定した SQL クエリを実行するクエリジョブを作成します。このコマンドは、--sql フラグまたは QUERY DD から SQL クエリを読み取ります。両方が指定されている場合、--sql フラグ内のクエリが優先されます。 --follow=true フラグを使用して、select クエリの結果を表示するレポートを生成します。このレポートをメインフレームのファイルに書き込むには、監査ログ レポートを含むファイルを指す DD ステートメント AUDITL を定義します。通常のロギング動作が必要な場合は、--follow フラグを使用しないでください。 クエリ結果によっては、数百万行に達する大量の行が返される場合があります。出力が人が読めるようにするために、表示される行数には上限があります。表示される行数を制御するには、--report_row_limit フラグを使用します。たとえば、--report_row_limit 10 を使用して結果を 10 行に制限します。デフォルトでは、表示される行数は 30 行に制限されています。 bq query パラメータ化を使用するには、bq クエリのパラメータ化をご覧ください。 詳細については、bq query をご覧ください。	○
	bq rm	このコマンドを使用して、BigQuery リソースを完全に削除します。このコマンドはリソースを完全に削除するため、慎重に使用することをおすすめします。詳細については、bq rm をご覧ください。	×
Cloud Storage コマンド	scp	このコマンドを使用して、テキストまたはバイナリデータを Cloud Storage にコピーします。シンプルなバイナリ コピー モードを使用すると、データ パイプラインの一部として、データセットを IBM z/OS から Cloud Storage に変更せずにコピーできます。必要に応じて、文字エンコードを EBCDIC（拡張バイナリ コード）10 進数交換コード（EBCDIC）から ASCII UTF-8 に変換して、改行を追加できます。 このコマンドを使用して、ジョブ制御言語（JCL）で定義されたアプリケーション ソースコードをコピーすることもできます。	×
gsutil ユーティリティ	gsutil cp	このコマンドを使用して、データセットをコード変換し、Optimized Row Columnar（ORC）ファイル形式で Cloud Storage に書き込みます。このコマンドは、INFILE DD からデータを読み取り、COPYBOOK ファイルからレコード レイアウトを読み取ります。コマンドでデータソース名（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	このコマンドを使用して、バケットまたはバケット内のオブジェクトを削除します。詳細については、rm - オブジェクトの削除をご覧ください。	×
gszutil ユーティリティ	gszutil	gszutil ユーティリティは IBM JZOS Java SDK を使用して実行され、JCL を使用して gsutil と BigQuery コマンドライン呼び出しを受け入れることができるシェル エミュレータを提供します。 gszutil ユーティリティは、COPYBOOK DD の形式でスキーマを受け入れることで、gsutil ユーティリティの機能を拡張します。これを使用して、Cloud Storage にアップロードする前に、COBOL データセットを直接 ORC にコード変換します。gszutil ユーティリティでは、JCL を使用して BigQuery の query と load を実行することもできます。 gszutil ユーティリティは gRPC サーバーで動作し、100 万命令/秒（MIPS）の消費量を削減できます。本番環境で gszutil ユーティリティを使用して、Cloud Storage のバイナリ ファイルを ORC 形式に変換することをおすすめします。	×
その他のコマンド	gcloud pubsub topics send	このコマンドを使用して、Pub/Sub トピックにメッセージを送信します。コマンドラインまたはデータセットを使用してメッセージを提供できます。	×
	gcloud dataflow flex-template run	このコマンドを使用して、Dataflow Flex テンプレートの実行をトリガーします。このコマンドは、指定された Flex テンプレート パスからジョブを実行します。詳細については、gcloud dataflow flex-template run をご覧ください。	×
	curl	このコマンドを使用して、ウェブサービスまたは REST API に対して HTTP リクエストを行います。	×
	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 ファイルが、複数の仮想ストレージ パーティション化データセット（MVS PDS）ではなく、z/OS Unix System Services（USS）にあることを確認します。
  • UCM ファイルが拡張バイナリ コード 10 進数交換コード（EBCDIC）形式ではなく、American Standard Code for Information Interchange（ASCII）形式で保存されていることを確認します。
• 可能なすべての 1 バイト値を 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 と互換性があるかどうかを確認します。
• Cloud Storage に書き込まずに QSAM ファイルをデコードします。

ドライランを実行するには、次のコマンドを使用します。

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 を使用します。