SQL ステートメントをキャプチャーするプロセスは、「特定のプロパティー群の値を設定する」、次に「アプリケーションを実行する」という 2 つのステップで構成されます。 キャプチャー・プロセスでは、最初に captureMode プロパティーを ON に設定してから、アプリケーションを実行します。pureQuery は、SQL ステートメントとスタック・トレースをリストするファイルを作成します。このファイルは pureQueryXML ファイルと呼ばれ、拡張子は .pdqxml または .xml のいずれかに指定できます。
captureMode 設定を ON にして pureQuery 以外の API アプリケーションを実行する場合には、静的に実行する SQL ステートメントを含んだすべての論理パスを正常に実行する必要があります。pureQuery は、SQL ステートメントが正常に実行される場合にのみ、SQL ステートメントをキャプチャーします。
一般的な考慮事項
- Connection.prepareStatement() メソッドでは、SQL ステートメントのキャプチャーは行われません。
- アプリケーションは、pureQuery を使用して SQL を静的に実行する場合に、正しく作動しない場合があります。SQL をキャプチャーするときは、pureQuery ログ・ユーティリティーを使用してください。
このユーティリティーがログに記録するメッセージは、アプリケーションの静的 SQL との互換性のレベルを判別するために役立てることができます。ご使用のアプリケーションにおいて静的 SQL との互換性がなくなる可能性がある幾つかの状態については、pureQuery 以外の API アプリケーションが SQL ステートメントを静的に実行するときに問題が発生する可能性がある状態またはコーディング手法を参照してください。
- アプリケーションが SQL ステートメントを静的に実行できるように、pureQuery のアノテーション付きメソッドが呼び出す SQL ステートメントをキャプチャーすることはお勧めしません。
そのようにすると最適のパフォーマンスが得られず、異機種混合でのバッチ実行など特定の機能で SQL エラーが発生する可能性があります。
- pureQuery Runtime では、BEGIN ATOMIC で始まるコンパウンド・ステートメントを除いて、
コンパウンド・ステートメントの静的実行をサポートしません。
コンパウンド・ステートメントがキャプチャーされると、pureQuery は、pureQueryXML ファイル内のこれらの
各ステートメントの isBindable 属性を false に設定します。
この属性は、StaticBinder ユーティリティーに、ステートメントをバインドするかどうかを指示します。
BEGIN ATOMIC コンパウンド・ステートメントについては、isBindable を true に設定できます。
StaticBinder ユーティリティーは、ステートメントをバインドできない場合には、エラーをログに記録します。
- pureQuery Runtime では、特定の XML 制御文字にマップされる可能性がある 16 進文字を含んだ SQL ステートメントのキャプチャーをサポートしていません。
これらの文字は、0x32 (16 進数) 以下の範囲にあります。
これらの文字が SQL で出現することはほとんどありません。
これらの文字は、従来とは異なるソースから生成されたストリング・リテラル値を使用している場合に出現する可能性があります。
これらの文字がキャプチャーされることがあるため、以降のキャプチャー・ファイルの処理中にエラーが発生することがあります。
SQL でこのようなリテラル値の使用が避けられない場合、sqlLiteralSubstitution プロパティーを使用すると、キャプチャー・ファイルの処理中に発生する可能性があるエラーを回避できます。
sqlLiteralSubstitution プロパティーは、キャプチャーした SQL 内のすべてのリテラルをパラメーターに置き換えるよう pureQuery Runtime に指示します。
- DB2® データベースに対して実行されている SQL ステートメントをキャプチャーする際には、キャプチャー・プロセス・ログが DB2 特殊レジスターに変更されます。
共用されており、SQL ステートメントの戻すデータに影響を与える可能性がある特殊レジスターに加えた変更は、pureQueryXML ファイルにもキャプチャーされます。