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

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

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

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

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

許可

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

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

必要な接続

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

コマンド構文

コマンド・パラメーター

-d dbname

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

-f file_name

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

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

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

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

--#SET control
option value

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

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: 時間情報を出力する。これがデフォルトです。
OFF: 時間情報を出力しない。

-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>ブラウン</last>などの区切り（'）テキストを使用します。

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

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

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

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

それぞれのパラメーター・ディレクティブは複数のパラメーター値からなる 1 つのセットを指定します。照会が実行されるたびに、このセットから 1 つのランダムな値が選択されます。このようなセットは、単一のパラメーター値の集まり、およびパラメーター値の範囲から構成されます。パラメーター値の範囲は、2 つの有効なパラメーター値の間にコロン (:) を付けることによって指定されます (または空白文字を区切り記号として使用することもできます)。開始値と終了値の間に 3 番目のパラメーター値を指定できます。これは、デフォルトをオーバーライドするステップ・サイズとして使用されます。各パラメーター範囲は、 'start', 'start+step', 'start+2*step...の単一値を指定するのと同じです。 'start+ n * step'ここで、nは'start+ n * step'> ='end'であるが、'start+（n+ 1）*step''>'end'となるように選択されます。パラメーター・ディレクティブを使用すれば (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 ステートメントを自動的に発行します。
PAUSEとSLEEPは、-iタイミング・オプションに長い が指定された場合に指定されます。
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_DETAILperf_detail (または -o p perf_detail) は、監視出力を素早く取得する方法を提供します。実施詳細レベルが> 1 の場合、すべての監視スイッチはdb2batchによって内部でつけられます。監視出力をより正確に制御する必要がある場合は、オプション-mswと-mss（または-＃SET SNAPSHOT）を使用します。
-rオプションと-zオプションを一緒に指定すると、-rオプションは無視されます。これは -r が指定するものが-zオプションに含まれるためです。