db2batch - ベンチマーク・ツール・コマンド

フラット・ファイルまたは標準入力から SQL ステートメントおよび XQuery ステートメントを読み取り、ステートメントを動的に準備および記述し、応答セットを戻します。

このツールは、単一パーティション・データベースと複数パーティション・データベースの両方で機能できます。

このツールのオプション・パラメーターにより、応答セットからフェッチする行の数、出力ファイルや標準出力に送信するフェッチ済み行の数、および戻されるパフォーマンス情報のレベルを制御できます。

出力のデフォルトは、標準出力を使用する設定になっています。結果サマリーの出力ファイルの名前を指定することができます。

許可

読み取られる SQL ステートメントまたは XQuery ステートメントが必要とするものと同じ権限レベル。

パフォーマンス情報のレベルを指定する -o p オプションを使用する場合、または Explain モードを設定する -o e オプションを使用する場合には、SYSMON 権限が必要です。

必要な接続

なし。このコマンドは、データベース接続を確立します。

コマンド構文

コマンド・パラメーター

-d dbname

SQL ステートメントまたは XQuery ステートメントが適用されるデータベースの別名。このオプションが指定されない場合、DB2DBDFT 環境変数の値が使用されます。

-f file_name

SQL ステートメントおよび XQuery ステートメントが入っている入力ファイルの名前。デフォルトは標準入力です。

コメント・テキストの前に 2 つのハイフンを付けて --コメント のように指定すると、コメント・テキストが識別されます。 2 つのハイフンの後から行の終わりまでのすべてのテキストは、コメントとして扱われます。隣接する 2 つのハイフンを含むストリングを単一または二重引用符で区切った場合、そのストリングはコメントではなく、ストリング定数として扱われます。出力にコメントを含めるには、--#COMMENT comment のようにマークを付けます。

ブロックとは、単体として扱われる複数の SQL ステートメントおよび XQuery ステートメントの集まりです。デフォルトでは、ブロック内のステートメントの情報は (1 つずつではなく) すべて一度で収集されます。照会ブロックの開始は、--#BGBLK で表します。照会ブロックの終了は、--#EOBLK で表します。ブロック定義時に --#BGBLK repeat_count のように繰り返しカウントを指定することにより、繰り返しループの中に照会ブロックを含めることができます。ブロック内のステートメントは、ループの最初の反復時にのみ準備されます。

ブロックの特定のステートメントや特定の反復でのパラメーター値を指定するために、#PARAM ディレクティブまたはパラメーター・ファイルを使用することができます。詳しくは、-m オプションに関する下記のセクションを参照してください。

1 つ以上の制御オプションを指定するには、次のようにします。--#SET control option value。有効な制御オプションは、以下のとおりです。

ROWS_FETCH

応答セットからフェッチする行数。有効な値は -1 から n です。デフォルト値は -1 (すべての行をフェッチする) です。値として 0 を使用した場合、行はフェッチされず、エラー・メッセージは返されません。

ROWS_OUT

フェッチされた行のうち出力へ送られる行数。有効な値は -1 から n です。デフォルト値は -1 (フェッチされた行をすべて出力へ送る) です。

PERF_DETAIL perf_detail

戻されるパフォーマンス情報のレベルを指定します。有効な値は以下のとおりです。

0: 時間情報やモニター・スナップショットをまったく戻さない。
1: 経過時間のみ戻す。
2: 経過時間とアプリケーションのスナップショットを戻す。
3: 経過時間、およびデータベース・マネージャー、データベース、アプリケーションのスナップショットを戻す。
4: データベース・マネージャー、データベース、アプリケーション、およびステートメントのスナップショットを戻す。 (自動コミットが OFF になっており、かつステートメント・ブロックではなく単一ステートメントを処理している場合にだけ、ステートメントのスナップショットが戻されます。) スナップショットにはハッシュ結合情報は組み込まれません。
5: データベース・マネージャー、データベース、アプリケーション、およびステートメントのスナップショットを戻す。 (自動コミットが OFF になっており、かつステートメント・ブロックではなく単一ステートメントを処理している場合にだけ、ステートメントのスナップショットが戻されます。) バッファー・プール、表スペース、および FCM も戻します (FCM スナップショットはマルチ・データベース・パーティション環境でのみ使用できる)。スナップショットにはハッシュ結合情報は組み込まれません。

デフォルト値は 1 です。 1 より大きい値は Db2® バージョン 2 と Db2 データベース・サーバーでのみ有効で、ホスト・マシンでは現在サポートされていません。

ERROR_STOP

重大ではないエラーが発生したとき、db2batch を停止させるかどうかを指定します。有効な値は以下のとおりです。

no: 重大ではないエラーが発生しても実行を続ける。これはデフォルト・オプションです。
yes: 重大ではないエラーが発生したら実行を停止する。

DELIMITER

1 文字か 2 文字のステートメント終結区切り文字です。デフォルト値はセミコロン (;) です。

SLEEP

スリープの秒数。有効な値は 1 から n です。

PAUSE

継続するかどうかの入力を要求するプロンプトをユーザーに出します。

SNAPSHOT snapshot

取得するモニター・スナップショットを指定します。取得可能なスナップショットについては、-mss オプションを参照してください。

TIMESTAMP

タイム・スタンプを生成します。

TIMING

時間情報を出力します。有効な値は以下のとおりです。

ON: 時間情報を出力する。これはデフォルトです。
オフ: 時間情報を出力しない。

-a userid/passwd

データベースへの接続に使用するユーザー ID とパスワードを指定します。斜線 (/) を含めなければなりません。

-m parameters_file

ステートメントの実行前に SQL ステートメント・パラメーター・マーカーにバインドされるパラメーター値が入っている入力ファイルを指定します。デフォルトでは、パラメーターをバインドしません。

パラメーター・ファイルを使用する場合、各行は、特定のステートメントやブロックの特定の反復でのパラメーター値を指定します。一方、#PARAM ディレクティブを使用した場合には、各ステートメントの各パラメーターごとに、複数の値やパラメーター範囲があらかじめ指定されます。ブロックのそれぞれの反復では、各パラメーターごとに指定された値セットからランダムな値が選択されます。#PARAM ディレクティブとパラメーター・ファイルを混合することはできません。

パラメーター値の形式:

     -36.6       'DB2'         X'0AB2'    G'...'   NULL
     12          'batch'       x'32ef'    N'...'   null
     +1.345E-6   'db2 batch'   X'afD4'    g'...'   Null

各パラメーターは SQL 定数のように定義され、空白文字によって他のパラメーターから分離されます。区切りなしテキストは数値を、' で単純に区切られたテキストは 1 バイト文字ストリングを、最初に x または X の付いたテキストの単一引用符 (') に囲まれた部分は 16 進数字の対としてエンコードされたバイナリー・ストリングを表します。さらに、最初に g、G、n、N が付いたテキストの単一引用符 (') 内は 2 バイト文字からなる GRAPHIC ストリングを、NULL (大/小文字を区別しない) はヌル値を表します。XML データを指定するには、(') で区切られたテキストを使用します (例えば '<last>Brown</last>')。

パラメーター入力ファイルの形式:

第 X 行は、入力ファイル内の実行される X 番目の SQL ステートメントに提供されるパラメーター・セットをリストします。ステートメント・ブロックが反復されない場合、これは入力ファイルにリストされた X 番目の SQL ステートメントに対応します。ブランク行は、対応する SQL ステートメントのパラメーターを提供しないことを表します。パラメーターの数とタイプは、SQL ステートメントが必要とするパラメーターの数およびタイプと一致しなければなりません。

パラメーター・ディレクティブの形式:

 --#PARAM [single | start:end | start:step:end] [...]

それぞれのパラメーター・ディレクティブは複数のパラメーター値からなる 1 つのセットを指定します。照会が実行されるたびに、このセットから 1 つのランダムな値が選択されます。このようなセットは、単一のパラメーター値の集まり、およびパラメーター値の範囲から構成されます。パラメーター値の範囲は、2 つの有効なパラメーター値の間にコロン (:) を付けることによって指定されます (または空白文字を区切り記号として使用することもできます)。開始値と終了値の間に 3 番目のパラメーター値を指定できます。これは、デフォルトをオーバーライドするステップ・サイズとして使用されます。それぞれのパラメーター範囲は、「開始値」、「開始値 + ステップ」、「開始値 + (ステップ x 2)」...「開始値 + (ステップ x n)」を指定した場合と同じになります (n は「開始値 + (ステップ x n) >= 終了値」および「開始値 + ステップ x (n+1) > 終了値」を満たす数として選択されます)。パラメーター・ディレクティブを使用すれば (NULL も含めて) あらゆるタイプのパラメーターの値セットを指定できますが、パラメーター値の範囲としてサポートされるのは数値 (整数と小数) だけです。

ストアード・プロシージャーを実行する際、parameters_file を IN パラメーターと OUT パラメーター両方のダミー値で更新します。

-t delcol

1 文字の列区切り記号を指定します。列区切り記号としてタブを指定するには -t TAB、スペースを指定するには -t SPACE をそれぞれ指定します。デフォルトでは、-q on オプションが設定されるとスペースが使用され、-q del オプションが設定されるとコンマが使用されます。

-r result_file [,summary_file]

照会結果が入る出力ファイルを指定します。デフォルトは標準出力です。エラー・メッセージは標準エラーで戻されます。オプションの summary_file を指定した場合、サマリー表が含まれます。

-z output_file [,summary_file]

照会結果および戻されたエラー・メッセージが入る出力ファイルを指定します。デフォルトは標準出力です。エラー・メッセージは標準エラーでも戻されます。オプションの summary_file を指定した場合、サマリー表が含まれます。このオプションは、バージョン 9.7 フィックスパック 1 から使用可能です。

-c

各ステートメントが実行された結果の変更内容を自動的にコミットします。デフォルトは ON です。

-i

経過時間インターバルを測定することを指定します。有効な値は以下のとおりです。

short: 各ステートメント実行時の経過時間を測定します。これはデフォルトです。
long: ステートメント間の追加の処理時間を含めて、各ステートメント実行の経過時間を測定します。
complete: 各ステートメント実行時の経過時間を測定します。準備、実行、フェッチにかかった時間が別々に報告されます。

-g

時間をブロックごとまたはステートメントごとのどちらで報告するかを指定します。有効な値は以下のとおりです。

on: ブロック全体のスナップショットを取得し、ブロックの時間だけがサマリー表に報告されます。これはデフォルトです。
off: ブロック内の実行される各ステートメントごとにスナップショットが取得され、サマリー表に時間が報告されます。

-w

結果セットの列の最大幅を指定します (許容される範囲は 0 から 2 G)。データが切り捨て不能でない限り、データは表示時にこの幅になるように切り捨てられます。この設定値を増やして警告 CLI0002W が出ないようにすると、より正確なフェッチ時間を得ることができます。デフォルトの最大幅は 32768 列です。

-time

時間情報を報告するかどうかを指定します。有効な値は以下のとおりです。

on: 時間を報告する。これはデフォルトです。
off: 時間を報告しない。

-cli

組み込み動的 SQL モード (以前は db2batch のデフォルト・モードだったもの) は、サポートされなくなりました。このコマンドは、CLI モードでのみ実行されます。 -cli オプションは、後方互換性のためにのみ存在しています。これを (オプションとして cache-size 引数を含めて) 指定してもエラーにはなりませんが、内部では無視されます。

-msw switch

指定されたそれぞれのモニター・スイッチの状態を設定します。 uow、statement、table、bufferpool、lock、sort、timestamp のオプションのいずれも指定できます。特殊なスイッチ all は、上述のすべてのスイッチを設定します。指定するスイッチごとに、以下の値のいずれかを選択する必要があります。

hold: スイッチの状態を変更しない。これはデフォルトです。
on: スイッチを ON に切り替える。
off: スイッチを OFF に切り替える。

-mss snapshot

(-g オプションに応じて) それぞれのステートメントまたはブロックの実行後に取得するモニター・スナップショットを指定します。一度に複数のスナップショットを取ることができます。この場合、すべてのスナップショットの情報が出力前に 1 つの大きな表に結合されます。可能なスナップショットは次のとおりです。applinfo_all、dbase_applinfo、dcs_applinfo_all、db2、dbase、dbase_all、dcs_dbase、dcs_dbase_all、dbase_remote、dbase_remote_all、agent_id、dbase_appls、appl_all、dcs_appl_all、dcs_appl_handle、dcs_dbase_appls、dbase_appls_remote、appl_remote_all、dbase_tables、appl_locks_agent_id、dbase_locks、dbase_tablespaces、bufferpools_all、dbase_bufferpools、および dynamic_sql。

特殊なスナップショット all は、すべてのスナップショットを取得します。アプリケーション ID を扱うスナップショットはサポートされず、代わりに対応するエージェント ID (アプリケーション・ハンドル) が使用されます。デフォルトでは、モニター・スナップショットはまったく取得されません。

-iso

データ・アクセス中にデータをロックして他のプロセスから分離する方法を決定する、分離レベルを指定します。デフォルトでは、db2batch は分離レベル RR を使用します。

db2cli.ini ファイル内の構成キーワード TxnIsolation は、db2batch に影響を与えません。分離レベルを RR 以外に設定してこのコマンドを実行するには、-iso パラメーターを指定する必要があります。

RR: 反復可能読み取り (ODBC 逐次化可能)。これはデフォルトです。
RS: 読み取り固定 (ODBC 反復可能読み取り)。
CS: カーソル固定 (ODBC コミット読み取り)。
UR: 非コミット読み取り (ODBC 非コミット読み取り)。

-car

db2batch 操作に使用する並行アクセス解決方法を指定します。-car パラメーターには、正しく構成されたデータベース・サーバーおよび CS に設定された分離レベル・パラメーター -iso が必要になります。

CC: 更新または削除の処理中に、db2batch 操作が、該当するスキャンに対して現在コミット済みバージョンのデータを使用することを指定します。挿入処理中の行はスキップできます。このオプションは、有効な分離レベルがカーソル固定または読み取り固定である場合に適用され (読み取り固定の場合、それはコミットされていない挿入だけをスキップします)、そうでない場合は無視されます。該当するスキャンには、非読み取り専用ステートメントに加え、読み取り専用ステートメントの一部にできる読み取り専用スキャンが含まれます。
WFO: db2batch 操作が、操作の結果を待機するように指定します。カーソル固定およびさらに上位のスキャンで、更新処理中または削除処理中のデータが検出されたときには db2batch はコミットまたはロールバックを待機します。挿入処理中の行はスキップされません。

-o options

制御オプション。有効なオプションは以下のとおりです。

f rows_fetch

r rows_out

フェッチされた行のうち出力へ送られる行数。有効な値は -1 から n です。デフォルト値は -1 (フェッチされた行をすべて出力へ送る) です。

p perf_detail

戻されるパフォーマンス情報のレベルを指定します。有効な値は以下のとおりです。

0: 時間情報やモニター・スナップショットをまったく戻さない。
1: 経過時間のみ戻す。
2: 経過時間とアプリケーションのスナップショットを戻す。
3: 経過時間、およびデータベース・マネージャー、データベース、アプリケーションのスナップショットを戻す。
4: データベース・マネージャー、データベース、アプリケーション、およびステートメントのスナップショットを戻す。 (自動コミットが OFF になっており、かつステートメント・ブロックではなく単一ステートメントを処理している場合にだけ、ステートメントのスナップショットが戻されます。)
5: データベース・マネージャー、データベース、アプリケーション、およびステートメントのスナップショットを戻す。 (自動コミットが OFF になっており、かつステートメント・ブロックではなく単一ステートメントを処理している場合にだけ、ステートメントのスナップショットが戻されます。) バッファー・プール、表スペース、および FCM も戻します (FCM スナップショットはマルチ・データベース・パーティション環境でのみ使用できる)。

デフォルト値は 1 です。 1 より大きい値は Db2 バージョン 2 と Db2 データベース・サーバーでのみ有効で、ホスト・マシンでは現在サポートされていません。

o query_optimization_class

照会最適化クラスを設定する。有効な値は 0、1、2、3、5、7、または 9 です。デフォルトは -1 (現行の最適化クラスを使用) です。

e explain_mode

db2batch 実行時の explain モードを設定する。このコマンドを使用する前に、 Explain 表を作成しておく必要があります。有効な値は以下のとおりです。

no: 照会のみ実行 (デフォルト)。
explain: Explain 表に書き込む。このオプションは、Explain 表に書き込み、Explain スナップショットを取得させます。
yes: Explain 表に書き込み、照会を実行する。このオプションは、Explain 表に書き込み、Explain スナップショットを取得させます。

s error_stop

重大ではないエラーが発生したとき、db2batch を停止させるかどうかを指定します。有効な値は以下のとおりです。

no: 重大ではないエラーが発生しても実行を続ける。これはデフォルト・オプションです。
yes: 重大ではないエラーが発生したら実行を停止する。

-v

冗長。照会処理中に標準エラーに情報を送信します。デフォルト値は OFF です。

-s

サマリー表。照会または照会のブロックごとに、サマリー表を提供します。その表には、経過時間 (算術平均と幾何平均を含む)、フェッチされた行、および行出力が含まれます。

-q

照会の出力。有効な値は以下のとおりです。

off: 照会結果およびすべての関連情報を出力する。これはデフォルトです。
on: 照会結果だけを非区切り形式で出力する。
del: 照会結果だけを区切り形式で出力する。

-l stmt_delimiter

終了文字 (ステートメント区切り文字) を指定します。区切り文字は 1 文字または 2 文字が可能です。デフォルトはセミコロン (;) です。

-h | -u | -?

ヘルプ情報を表示します。このオプションを指定すると、他のすべてのオプションは無視され、ヘルプ情報だけが表示されます。

例

以下に示すのは、db2batch -d crystl -f update.sql コマンドの出力例です。

* Timestamp: Thu Feb 02 2006 10:06:13 EST
---------------------------------------------

* SQL Statement Number 1:

create table demo (c1 bigint, c2 double, c3 varchar(8));

* Elapsed Time is:       0.101091 seconds

---------------------------------------------

* SQL Statement Number 2:

insert into demo values (-9223372036854775808, -0.000000000000005, 'demo');

* Elapsed Time is:       0.002926 seconds

---------------------------------------------

* SQL Statement Number 3:

insert into demo values (9223372036854775807, 0.000000000000005, 'demodemo');

* Elapsed Time is:       0.005676 seconds

---------------------------------------------

* SQL Statement Number 4:

select * from demo;

C1                   C2                     C3      
-------------------- ---------------------- --------
-9223372036854775808 -5.00000000000000E-015 demo    
 9223372036854775807 +5.00000000000000E-015 demodemo

* 2 row(s) fetched, 2 row(s) output.

* Elapsed Time is:       0.001104 seconds

---------------------------------------------

* SQL Statement Number 5:

drop table demo;

* Elapsed Time is:       0.176135 seconds

* Summary Table:

Type      Number      Repetitions Total Time (s) Min Time (s)   Max Time (s)   
--------- ----------- ----------- -------------- -------------- -------------- 
Statement           1           1       0.101091       0.101091       0.101091 
Statement           2           1       0.002926       0.002926       0.002926 
Statement           3           1       0.005676       0.005676       0.005676 
Statement           4           1       0.001104       0.001104       0.001104 
Statement           5           1       0.176135       0.176135       0.176135 

Arithmetic Mean Geometric Mean Row(s) Fetched Row(s) Output
--------------- -------------- -------------- -------------
       0.101091       0.101091              0             0
       0.002926       0.002926              0             0
       0.005676       0.005676              0             0
       0.001104       0.001104              2             2
       0.176135       0.176135              0             0

* Total Entries:              5
* Total Time:                 0.286932 seconds
* Minimum Time:               0.001104 seconds
* Maximum Time:               0.176135 seconds
* Arithmetic Mean Time:       0.057386 seconds
* Geometric Mean Time:        0.012670 seconds
---------------------------------------------
* Timestamp: Thu Feb 02 2006 10:06:13 EST

使用上の注意

すべての SQL ステートメントは、--#SET DELIMITER コマンドによって設定される区切り文字 (デフォルトは「;」) で終わる必要があります。この区切り文字は 1 文字または 2 文字が可能です。
SQL ステートメントの長さは、使用可能メモリー、および使用されるインターフェースによってのみ制限されます。ステートメントを複数の行に分割することは可能ですが、1 行に複数のステートメントを指定することはできません。
入力ファイルの行の長さは、使用可能メモリーによってのみ制限されます。
c は自動的に CONNECT および CONNECT RESET ステートメントを発行します。
タイミング・オプション -i に long が指定されている場合、PAUSE および SLEEP の時間が計測されます。
explain オプションを使用するには、まず Explain 表を作成しておく必要があります。
db2batch では、すべてのコマンド行オプションと入力ファイル・ステートメントは大/小文字を区別しません。
db2batch がサポートするデータ・タイプは、INTEGER、CHAR、VARCHAR、 LONG VARCHAR、FLOAT、SMALLINT、BIGINT、DECIMAL、DATE、TIME、 TIMESTAMP、CLOB、GRAPHIC、VARGRAPHIC、LONGVARGRAPHIC、 DBCLOB、BLOB、および XML です。
--#SET PERF_DETAIL perf_detail (または -o p perf_detail) を使用すれば、モニター出力を素早く得ることができます。パフォーマンス詳細レベルが 1 より大きい場合、すべてのモニター・スイッチは db2batch によって内部的にオンに切り替えられます。モニター出力をより細かく制御する必要がある場合には、-msw および -mss オプション (または --#SET SNAPSHOT) を使用してください。
-r オプションと -z オプションを同時に指定した場合は、-r オプションが指定しているものが -z オプションに含まれているので、-r オプションは無視されます。