SQL ステートメントに関する情報をキャプチャーするのかどうか、およびキャプチャーする情報のタイプを指定します。
この情報は、pureQueryXml プロパティーで指定されたファイル、
または outputPureQueryXml プロパティーで指定されたロケーションに書き込まれます。
ロケーションがデータベース内に作成されたリポジトリーである場合、
この情報は propertiesGroupId プロパティーによって指定されたリポジトリー・ランタイム・グループに書き込まれます。
captureMode を ON に設定してアプリケーションを実行する場合には、
取り込む SQL ステートメントが含まれているすべての論理パスを正常に実行する必要があります。
pureQuery は、それらが正常に実行された場合にのみ SQL ステートメントを取り込みます。
DB2® for z/OS® データベースに
アクセスするアプリケーションから SQL ステートメントをキャプチャーする場合、pureQuery Runtime は、Multiple Row Insert (MRI) 対応の SQL ステートメントを
追跡します。
pureQuery ユーティリティーである Configure および StaticBinder は、ステートメントの処理時にこの情報を使用します。
Java アプリケーションの場合、JDBC メソッド setMaxRows は、SQL ステートメントで返される最大行数を制御します。
pureQuery Runtime は、SQL 情報をキャプチャーするときに、JDBC メソッド setMaxRows で指定されている値をキャプチャーします。
pureQuery StaticBinder ユーティリティーは、SQL ステートメントを組み込んだパッケージを作成し、それらのパッケージをバインドするときに、setMaxRows の値を使用します。
pureQuery Runtime は、SQL ステートメントを静的に実行するときに返される行数を制限するために、setMaxRows の値を使用します。
setMaxRows メソッドでさまざまな値が指定されていると、SQL ステートメントが複数回キャプチャーされる可能性があります。
pureQuery Runtime は、setMaxRows メソッドで指定されている最大の値を使用します。
ステートメントに FETCH FIRST 節も含まれていると、pureQuery Runtime は、その節で指定されている値も使用して、返す行の最大数を決定します。
注: setMaxRows メソッドで値 0 を指定すると、すべての行が返されます。
オプティミスティック・ロックを使用して実行される SQL ステートメントは、静的には実行できません。
そのため、pureQuery Runtime は、オプティミスティック・ロックを使用して実行されたステートメントをキャプチャーしません。
このようなステートメントは、pureQuery Runtime オプション
allowDynamicSQL や
capturedOnly の影響を受けません。
オプティミスティック・ロックを有効にするには、次のようにします。
DB2Connection.prepareDB2OptimisticLockingQuery
DB2Statement.executeDB2OptimisticLockingQuery
このプロパティーには、以下の値を指定できます。
- ON
- SQL ステートメントをキャプチャーすることを指定します。
pureQuery Runtime は、アプリケーションの実行時に SQL ランタイム情報を記録します。
- OFF
- デフォルト値です。
アプリケーションの実行時に SQL ステートメントを取り込まないように指定します。
- NEW_STMTS
- 新規 SQL ステートメントのみがキャプチャーされるように指定します。
pureQuery Runtime は、pureQueryXML ファイルにあるステートメントの SQL ランタイム情報も更新します。
キャプチャーされた情報が記録されるのは、その情報が pureQueryXML ファイルにある情報とは異なり、その情報が、前にキャプチャーされたステートメントの今後の静的な実行に影響する可能性がある場合です。
例えば、SQL ステートメントがキャプチャーされた後に、その同じステートメントが異なる SCHEMA 設定や異なる特殊レジスター設定で
再びキャプチャーされると、pureQuery Runtime は、pureQueryXML ファイルにある SQL ステートメントの関連情報を新しい SCHEMA 情報で更新します。
実行時刻や実行カウントなどの SQL 情報はキャプチャーされません。
この値は、Java アプリケーションでのみサポートされます。
入力と出力で異なる pureQueryXML ファイルを指定すると、新しいステートメントと、前にキャプチャーされたステートメントの今後の静的な実行に影響する可能性がある情報だけが出力ファイルに書き込まれます。
captureMode プロパティーの値を
NEW_STMTS に設定すると、pureQuery Runtime プロパティーのデフォルト値が変更されます。
変更されるデフォルト値を次の表にリストします。
表 1. captureMode プロパティーが NEW_STMTS に設定された場合の pureQuery Runtime プロパティーのデフォルト値pureQuery Runtime プロパティー |
デフォルト値 |
maxNonParmSQL |
100 |
maxStackTracesCaptured |
1 |
stackTraceDepth |
5 |
sqlLiteralSubstitution |
NOT_SET |
pureQuery Runtime プロパティーに値を指定して、
デフォルトをオーバーライドできます。
- LITE
- SQL ステートメントを使用して、量が削減されたスタック・トレース情報がキャプチャーされるように指定します。
キャプチャーされるデータの量が削減されると、キャプチャー・プロセスで使用されるリソースが少なくなります。
pureQuery Runtime は、新規 SQL ステートメントと以前にキャプチャーされた SQLステートメントの両方について pureQueryXML ファイルを更新します。
実行時刻や実行カウントなどの SQL 情報がキャプチャーされます。
この値は、Java アプリケーションでのみサポートされます。
captureMode プロパティーの値を
LITE に設定すると、pureQuery Runtime プロパティーのデフォルト値が変更されます。
変更されるデフォルト値を次の表にリストします。
表 2. captureMode プロパティーが LITE に設定された場合の pureQuery Runtime プロパティーのデフォルト値pureQuery Runtime プロパティー |
デフォルト値 |
maxStackTracesCaptured |
1 |
stackTraceDepth |
5 |
sqlLiteralSubstitution |
NOT_SET |
pureQuery Runtime プロパティーに値を指定して、
デフォルトをオーバーライドできます。
DB2 CLI および IBM Data Server Driver の使用上の注意
DB2 コール・レベル・インターフェースまたは IBM® Data Server Driver と pureQuery Runtime を一緒に使用する場合は、pureQuery Runtime プロパティーを構成キーワードとして使用できます。
- IBM CLI キーワードの構文
- captureMode = ON | OFF
- IBM Data Server Driver 構成の構文
- <パラメーター名="captureMode" 値="ON | OFF" />
- 同等の IBM Data Server
Provider for .NET 接続ストリング・キーワード
- 該当なし
使用上の注意
SQL 情報をキャプチャーするときの注意点を以下にまとめます。
- pureQuery クライアントの最適化により使用可能にされた CLI アプリケーションは、ファイル内のデータをキャプチャーするための pureQueryXml キーワードのみをサポートしています。
- 名前付きパラメーター・マーカーを持つ Java アプリケーションを正常に機能させるには、
データ・サーバーのタイプおよびバージョンに関係なく、アプリケーション内で名前付きパラメーター・マーカーを使用する前に、
プロパティー Connection または DataSource enableNamedParameterMarkers を DB2BaseDataSource.YES に
設定してください。
例
この例では、ある会社が pureQuery クライアント最適化対応のアプリケーションから SQL ステートメントを以前にキャプチャーしました。
このステートメントは pureQueryXML ファイルに入っています。
この会社は、そのアプリケーションとその pureQueryXML ファイル prod-v1.pdqxml を実稼働環境にデプロイしました。
SQL ステートメントが実動データベースで静的に実行されるようにバインド・プロセスが実行されました。
ただし、このアプリケーションによって実行されるすべての SQL ステートメントがキャプチャーされたかどうかは不明です。
この会社では、前にキャプチャーされなかった SQL ステートメントだけをキャプチャーするために、
captureMode プロパティーの値を
NEW_STMTS に設定できます。
次のプロパティー設定によって、
ステートメントが pureQueryXML ファイル prod-v1.pdqxml にない場合に pureQueryXML ファイル newStmt.pdqxml 内の SQL ステートメントを
キャプチャーするように pureQuery Runtime が構成されます。
executionMode=STATIC
captureMode=NEW_STMTS
pureQueryXml=prod-v1.pdqxml
outputPureQueryXml=newStmt.pdqxml
新規ステートメントのみがキャプチャーされます。
新規ステートメントのスタック・トレースと統計はキャプチャーされません。
このキャプチャー・プロセスは、リソースをあまり使用しないプロセスであるため、実稼働環境で使用できると考えられます。
この例では、ある会社が pureQuery クライアント最適化対応のアプリケーションから詳細なスタック・トレース情報をキャプチャーせずに SQL ステートメントを
キャプチャーしようと考えています。
次の pureQuery Runtime プロパティーでは、
アプリケーションによって実行される SQL ステートメントが pureQueryXML ファイル capture.pdqxml でキャプチャーされます。
このステートメントは、アプリケーションの調整に使用できる追加ランタイム情報 (ステートメント実行時刻など) とともにキャプチャーされます。
executionMode=DYNAMIC
captureMode=LITE
pureQueryXml=capture.pdqxml