GeneratePureQueryXml ユーティリティー

GeneratePureQueryXml ユーティリティーは、入力ファイルから pureQueryXML ファイルを生成します。 この入力ファイルとして、ステートメントとカーソル属性情報が含まれた SQL スクリプト・ファイル、 または InfoSphere® Optim™ Query Workload Tuner XML ファイルを 使用できます。

GeneratePureQueryXml ユーティリティーは、SQL ステートメントとそのステートメントに関する情報が含まれているファイルを 読み取り、pureQueryXML ファイルを作成します。 ファイルの作成後、Configure ユーティリティーを使用して、pureQuery Runtime で使用するファイルを準備してください。 pureQueryXML ファイルの構成後、StaticBinder ユーティリティーを使用して、構成された pureQueryXML ファイルの SQL ステートメントを含む DB2® パッケージを作成してバインドします。

コマンドの構文

構文図を読む構文図をスキップする
    (1)                                                      
>>-------java--java com.ibm.pdq.tools.GeneratePureQueryXml------>

>-- -username--user-ID-- -password--password-- -url--JDBC-URL--->

>--+---------------------------------------------+-------------->
   |               .-com.ibm.db2.jcc.DB2Driver-. |   
   '- -driverName--+-JDBC-driver---------------+-'   

>-- -pureQueryXml--fileName-- -inputSql--fileName--------------->

>--+------------------------------------------+----------------->
   |                  (2).- - - ------------. |   
   '- -commentStart------+-commentIndicator-+-'   

>--+---------------------------------------+-------------------->
   |                           .-NOT_SET-. |   
   '- -sqlLiteralSubstitution--+-DISABLE-+-'   
                               '-ENABLE--'     

>--+-------------------------------------+---------------------->
   |                       .-;---------. |   
   '- -statementDelimiter -+-delimiter-+-'   

>--+------------------------------------------------------+----->
   |                         .-HOLD_CURSORS_OVER_COMMIT-. |   
   '- -resultSetHoldability -+-CLOSE_CURSORS_AT_COMMIT--+-'   

>--+----------------------------------------------+------------->
   |                         .-CONCUR_READ_ONLY-. |   
   '- -resultSetConcurrency--+-CONCUR_UPDATABLE-+-'   

>--+--------------------------------------------+--------------->
   |                  .-TYPE_FORWARD_ONLY-----. |   
   '- -resultSetType--+-TYPE_SCROLL_SENSITIVE-+-'   
                      '-TYPE_SCROLL_SENSITIVE-'     

>--+-----------------------+--+--------+-----------------------><
   |                   (3) |  '- -help-'   
   '-| Trace options |-----'               

注:
  1. オプションは任意の順序で指定できます。
  2. デフォルト値は 2 つのダッシュ (--) です。
  3. 構文については、以下のオプションの説明を参照してください。

ダイアグラムで使用される規則を理解するには、構文図の読み方を参照してください。

オプションの説明

-username user-ID
user-ID は、データベースの認証に使用するユーザー ID を指定します。
-password password
データベースの認証に使用するパスワードを指定します。
-url JDBC-URL
データベースとの接続の確立に使用する JDBC URL を指定します。
-driverName JDBC-driver
データベースとの接続の確立に使用する JDBC ドライバーの完全修飾名を指定します。デフォルト値は com.ibm.db2.jcc.DB2Driver です。これは、IBM® Data Server Driver for JDBC and SQLJ 用のドライバーです。
-pureQueryXml file
出力 pureQueryXML ファイルの絶対パスまたは相対パスを指定します。
-inputSql file
拡張子 .sql を持つ SQL スクリプト・ファイル、または拡張子 .xml を持つ XML ファイルの絶対パスまたは相対パスを指定します。

SQL スクリプト・ファイルの形式について詳しくは、GeneratePureQueryXml ユーティリティーにより使用される SQL スクリプト・ファイルの形式を参照してください。

XML ファイルを 指定する場合、そのファイルは 有効な InfoSphere Optim Query Workload Tuner ファイルでなければなりません。 その XML ファイルが無効な場合は、エラーが報告されます。 Query Workload Tuner ファイルの エクスポートについては、InfoSphere Optim Query Workload Tuner の資料を 参照してください。 SQL ステートメントの キャプチャー時、InfoSphere Optim Query Workload Tuner は 以下の機能をサポートします。
  • DB2 for Linux, UNIX, and Windows データベースでは、パッケージ・キャッシュから SQL ステートメントをキャプチャーできます。
  • DB2 for z/OS® データベースの 場合は、SQL ステートメントをステートメント・キャッシュからキャプチャーできます。 InfoSphere Optim Query Workload Tuner によって 実行される SQL ステートメントを除外するには、「キャプチャー・プロセスにより発行された動的照会を除外」オプションを有効にします。

入力ファイルに SQL ステートメントが複数回出現する場合でも、pureQueryXML の出力ファイルでは、その SQL ステートメントが 1 回だけ書き込まれます。 重複する SQL ステートメントの判別方法については、『SQL ファイル内の重複する SQL ステートメントの判別』を参照してください。

-commentStart commentIndicator
SQL スクリプト・ファイルの場合に、コメント行を示すために行頭に置かれる文字の組み合わせを指定します。 コメント行には、コメントの直後にある SQL ステートメントに適用されるステートメントのカーソル属性を含めることが出来ます。デフォルトはダッシュ 2 つ (--) です。コメント開始文字 /* およびコメント終了文字 */ はこのオプションに対してはサポートされていません。

このオプションは、入力ファイルが XML ファイルの場合はサポートされません。 指定されたオプションが無視されることを示す警告メッセージが表示されます。

-sqlLiteralSubstitution ENABLE|DISABLE|NOT_SET
GeneratePureQueryXml ユーティリティーが SQL ステートメント内のリテラル値をパラメーター・マーカーで置き換えるかどうかを指定します。 デフォルト値は NOT_SET です (この場合、SQL ステートメントのリテラル値は置き換えられません)。 SQL リテラル置換プロセスは、SQL リテラル置換が有効になった状態で pureQuery ランタイムが SQL ステートメントをキャプチャーするときに行われる 置換プロセスと同じです。

サポートされる値について、次のリストで説明します。

DISABLE
このユーティリティーがリテラル置換を実行しないように指定します。 SQL ステートメントは変更されません。

出力 pureQueryXML ファイル内の SQL リテラル置換属性の値が DISABLE に設定されます。

ENABLE
このユーティリティーが SQL ステートメント内のリテラルをパラメーター・マーカーで置き換えるように指定します。 リテラルの置換が SQL ステートメントの結果に影響するということをこのユーティリティーが判断した場合は、SQL リテラルは置き換えられません。 SQL リテラル置換が実行されると、ステートメントからコメントが削除されます。 SQL リテラル置換が実行される SQL ステートメントに関しては、複数の空白文字 (SQL ステートメントの前後にあるスペース文字を含む) は、 単一の空白文字で置き換えられます。

このユーティリティーは、SQL リテラル置換プロセス中に作成された重複する SQL ステートメントを削除します。

出力 pureQueryXML ファイル内の SQL リテラル置換属性の値が ENABLE に設定されます。

NOT_SET
このファイルに対してリテラル置換が実行されないように指定します。 この値がデフォルトです。

出力 pureQueryXML ファイル内の SQL リテラル置換属性の値が NOT_SET に設定されます。

pureQuery Runtime が pureQueryXML ファイル内の SQL ステートメントをキャプチャーすると、 そのファイル内の SQL リテラル置換設定が、ステートメント・キャプチャー時の pureQuery Runtime プロパティー sqlLiteralSubstitution の 値となります。

pureQuery Runtime の SQL リテラル置換については、 『sqlLiteralSubstitution プロパティー』を 参照してください。

pureQueryXML ファイルがマージされるときの SQL リテラル置換属性については、 『Merge ユーティリティー』を参照してください。

-statementDelimiter delimiter
ステートメントを区切るために SQL スクリプト・ファイル内で使用される文字の組み合わせを指定します。デフォルト文字はセミコロン (;) です。

このオプションは、 入力ファイルが InfoSphere Optim Query Workload Tuner XML ファイルの場合は サポートされません。 指定されたオプションが無視されることを示す警告メッセージが表示されます。

-resultSetHoldability holdability
ファイル内のすべてのステートメントに適用される結果セットの保持性を指定します。holdability は、次のいずれかの値です。
  • CLOSE_CURSORS_AT_COMMIT を指定すると、コミット時にカーソルを閉じるように結果セットの保持機能が設定されます。 この値は、JDBC 値 java.sql.ResultSet.CLOSE_CURSORS_AT_COMMIT を設定します。
  • HOLD_CURSORS_OVER_COMMIT を指定すると、コミット後もカーソルを保持するように結果セットの保持機能が設定されます。 この値は、JDBC 値 java.sql.ResultSet.HOLD_CURSORS_OVER_COMMIT を設定します。

デフォルト値は HOLD_CURSORS_OVER_COMMIT です。

SQL スクリプト・ファイル内で、特定の SQL ステートメントの直前にあるコメント行で保持性を指定することにより、その SQL ステートメントの 保持性値をオーバーライドできます。

DB2 for z/OS からの Query Workload Tuner XML ファイルの 場合は、SQL ステートメントの初期準備用の結果セットの保持性がこのファイルに保管されます。 結果セットの保持性情報がこのファイル内にある場合、このユーティリティーは出力 pureQueryXML ファイル内の SQL ステートメントに対してその値を使用します。

InfoSphere Optim Query Workload Tuner XML ファイル内の SQL ステートメントの 結果セットの保持性については、『出力 pureQueryXML ファイルに関する注記』を参照してください。

-resultSetConcurrency concurrency
すべてのステートメントに適用される結果セットの並行性を指定します。concurrency は、次のいずれかの値です。
  • CONCUR_READ_ONLY を指定すると、カーソルの並行性が読み取り専用に設定されます。
  • CONCUR_UPDATABLE を指定すると、カーソルの並行性が更新可能に設定されます。

デフォルト値は CONCUR_READ_ONLY です。

SQL スクリプト・ファイルで、特定の SQL ステートメントの直前にあるコメント行で並行性を指定することによって、その SQL ステートメントの並行性値をオーバーライドできます。

InfoSphere Optim Query Workload Tuner XML ファイル内の SQL ステートメントの 結果セット並行性を設定する方法については、『出力 pureQueryXML ファイルに関する注記』を参照してください。

-resultSetType type
すべてのステートメントに適用される結果セットのタイプを指定します。タイプは、次のいずれかの値です。
  • TYPE_FORWARD_ONLY を指定すると、結果セットのタイプが順方向のみに設定されます。
  • TYPE_SCROLL_SENSITIVE を指定すると、結果セットのタイプがスクロール・センシティブに設定されます。
  • TYPE_SCROLL_INSENSITIVE を指定すると、結果セットのタイプがスクロール・インセンシティブに設定されます。

デフォルト値は TYPE_FORWARD_ONLY です。 SQL スクリプト・ファイルで、特定の SQL ステートメントの直前にあるコメント行で結果セット・タイプを指定することによって、その SQL ステートメントの結果セット・タイプ値をオーバーライドできます。

InfoSphere Optim Query Workload Tuner XML ファイル内の SQL ステートメントの 結果セット・タイプを設定する方法については、『出力 pureQueryXML ファイルに関する注記』を参照してください。

Trace options
メッセージのログを記録するファイルおよびログを記録する情報のレベルを指定できます。
構文図を読む構文図をスキップする
>>-+------------------------+--+---------------------------+---><
   '- -traceFile--file-name-'  |               .-OFF-----. |   
                               '- -traceLevel--+-ALL-----+-'   
                                               +-SEVERE--+     
                                               +-WARNING-+     
                                               +-INFO----+     
                                               +-CONFIG--+     
                                               +-FINE----+     
                                               +-FINER---+     
                                               '-FINEST--'     

-traceFile file-name
操作に関する情報のログを記録するために使用するファイルへの絶対パスまたは相対パスとファイル名を指定します。
ファイルが既に存在する場合には、pureQuery は、ファイルの既存の内容に新しいメッセージを追加します。デフォルトでは、項目は System.err に書き込まれます。
-traceLevel OFF|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST|ALL
ログに記録する情報のタイプを指定します。 デフォルトのレベルは OFF です。ログ項目を書き込むファイルを指定せず、このオプションを OFF 以外の値に設定した場合、項目は System.err に書き込まれます。
-help
サマリー使用情報を表示します。

出力 pureQueryXML ファイルに関する注記

以下のリストに、pureQueryXML ファイルの使用法についての情報を示します。
  • SQL スクリプト・ファイル または InfoSphere Optim Query Workload Tuner XML ファイルから pureQueryXML ファイルを 作成する場合は、SQL ステートメントごとに次の基準が満たされていることを確認してください。
    • ファイル内の SQL ステートメントのテキストが、アプリケーションによって発行された SQL ステートメントと一致していること。 ステートメントの大/小文字と空白文字が一致していなければなりません。
    • ファイル内の SQL ステートメントの結果セットの保持機能、並行性、およびタイプの設定が、アプリケーションにより発行された SQL ステートメントの設定と一致していること。

    上記の情報が一致しないと、pureQuery Runtime の executionMode プロパティーが STATIC に設定されている場合、 または pureQuery Runtime の capturedOnly プロパティーが TRUE に設定されている場合に、pureQuery クライアント最適化で、SQL ステートメントと、 アプリケーションによって発行されたステートメントとの突き合わせが行われません。

    以下の項目は、入力ファイルが Query Workload Tuner XML ファイルの場合に適用されます。
    • この XML ファイルには、SQL ステートメントに関する特殊レジスター情報がいくつか含まれています。 GeneratePureQueryXml ユーティリティーが XML ファイルから pureQueryXML ファイルを生成すると、 特殊レジスター情報が pureQueryXML ファイルにメタデータとして組み込まれます。 pureQuery Runtime によってキャプチャーされる特殊レジスター情報と、Query Workload Tuner によってキャプチャーされる特殊レジスター情報には相違があります。 GeneratePureQueryXml には、pureQuery Runtime によって通常キャプチャーされる特殊レジスター情報が含まれています。

      Configure ユーティリティーを使用して pureQueryXML ファイルを構成するときは、 特殊レジスター設定に応じて -groupSQLBySpecialRegisters オプションでそのファイル内の SQL ステートメントをグループ化できます。 また、-optionsFileForBind オプションを指定すれば、特殊レジスター設定に基づいて、バインド・オプションを含む サンプルの StaticBinder オプション・ファイルを生成することもできます。 構成オプションについては、 『Configure ユーティリティー』を参照してください。

      pureQuery Runtime によってトラッキングおよび記録される特殊レジスター情報については、 『pureQuery クライアント最適化による DB2 特殊レジスターの変更のトラッキング』を 参照してください。

      DB2 for z/OS データベースの場合に、InfoSphere Optim Query Workload Tuner の XML ファイルにある SQL パフォーマンス統計をキャプチャーするには、そのための構成が必要です。 統計の収集を有効にする方法については、InfoSphere Optim Query Workload Tuner の XML ファイルにある DB2 for z/OS のパフォーマンス統計をキャプチャーする操作を参照してください。

    • SQL ステートメントを pureQueryXML ファイルに追加する前に、このユーティリティーはその SQL ステートメントに関するメタデータを収集するためのステートメントを準備します。 CURRENT SCHEMA 特殊レジスターの値が XML ファイル内にある場合、このユーティリティーは準備を行うときに CURRENT SCHEMA 特殊レジスターの値を使用します。
    • XML ファイル内の SQL ステートメントが静的に実行されたということをこのユーティリティーが判断すると、 そのステートメントは出力 pureQueryXML ファイルに組み込まれません。
    • GeneratePureQueryXml ユーティリティーは、XML ファイルから出力 pureQueryXML ファイルに統計の一部をコピーします。 入力 XML ファイル内の統計は、データベースのタイプとバージョン、 および InfoSphere Optim Query Workload Tuner のバージョンによって 異なります。 この統計は、pureQueryXML ファイル内の SQL ステートメントのバインド方法や、pureQuery Runtime が SQL ステートメントを、 アプリケーションから発行されたステートメントと突き合わせる方法には影響しません。

      このユーティリティーは、SQL ステートメントのタイム・スタンプ情報が検出されないときは現在日時を使用します。

    • XML ファイルにカーソル属性を指定することはできません。 カーソル属性は、GeneratePureQueryXml ユーティリティー・オプションの -resultSetType、-resultSetHoldability、 および -resultSetConcurrency を使用して指定できます。 これらのオプションは、XML ファイル内のすべての SQL ステートメントに適用されます。

      DB2 for z/OS からの XML ファイルの 場合は、SQL ステートメントの初期準備用の結果セットの保持性がこのファイルに保管されます。 結果セットの保持性情報がこのファイル内にある場合、このユーティリティーは出力 pureQueryXML ファイル内の SQL ステートメントに対してその値を使用します。

      pureQuery Runtime は、SQL ステートメントの実行方法を制御するときに SQL ステートメントおよびそのステートメントのカーソル属性を詳しく調べます。 例えば、SQL ステートメントを静的に実行するように pureQuery Runtime を構成できます。 pureQueryXML ファイル内のステートメントおよび属性がアプリケーションのステートメントおよび属性と一致しない 場合、pureQuery Runtime はステートメントを静的には実行しません。

    • 出力 pureQueryXML ファイル内の SQL ステートメントを静的に実行するために各種バインド・オプションが必要な場合は、 ワークベンチで pureQueryXML エディターを使用して、SQL ステートメントをステートメント・セットにグループ化できます。 その後で、StaticBinder ユーティリティーの実行時に、そのステートメント・セットの各種バインド・オプションを指定できます。

      オプション -statementBindError に値 REMOVE または MARK_INVALID を 指定して StaticBinder ユーティリティーを実行できます。 StaticBinder ユーティリティーは、バインド・プロセス中に SQL エラーを返す SQL ステートメントをスキップします。

  • 出力 pureQueryXML ファイルを、SQL ステートメントを静的に実行するために、pureQuery クライアントの最適化で直接使用することはできません。StaticBinder ユーティリティーを使用する前に、Configure ユーティリティーを使用して、pureQuery クライアントの最適化で pureQueryXML ファイルを使用できるようファイルを変更しておく必要があります。
  • 出力 pureQueryXML ファイルには、スタック・トレース情報や特殊レジスター情報といったアプリケーションの実行情報が含まれません。これらの情報は、pureQuery クライアントの最適化を使用するアプリケーションから SQL ステートメントをキャプチャーする際に作成される pureQueryXML ファイルに含まれます。
  • pureQueryXML の出力ファイルには、以下の SQL ステートメント情報が組み込まれません。これらの情報は、pureQuery のクライアント最適化機能が実行時にステートメントを SQL ステートメントとして識別するために使用する情報です。
    • 自動生成されたキー列名
    • 自動生成されたキー列の索引
    • 自動生成されたキー・インディケーター

    pureQuery クライアント最適化を使用するアプリケーションが、SQL ステートメントを静的に実行するように、 または SQL ステートメントをキャプチャー専用モードで実行するように構成されていて、GeneratePureQueryXml ユーティリティーによって 作成された pureQueryXML ファイルを使用する場合、そのアプリケーションによって発行されたステートメントで上記の 3 つの機能のいずれかが使用されていると、 そのステートメントは静的には実行されません。 これは、SQL ステートメントのテキストが同一の場合であっても同様です。

次の例では、SQL スクリプト・ファイル c:¥mystatements.sql で検出されたステートメントに関する情報が 入った pureQueryXML ファイル c:¥statements.pdqxml を作成します。 -sqlLiteralSubstitution オプションの値は ENABLE であり、SQL ステートメント内のリテラルが パラメーター・マーカーに置き換えられます。
java com.ibm.pdq.tools.GeneratePureQueryXml 
    -username db2admin –password mypass 
    –url jdbc:db2://localhost:50000/mydb 
    -sqlLiteralSubstitution ENABLE
    –pureQueryXml "C:¥statements.pdqxml" –inputSql "C:¥mystatements.sql"

SQL ファイル内の重複する SQL ステートメントの判別

GeneratePureQueryXml は、2 つの SQL ステートメントのテキスト (前後の空白文字を除く) が同一である場合、 および以下の属性が同一である場合に、それら 2 つのSQL ステートメントを重複と見なします。
  • 結果セット・タイプ
  • 結果セット並行性
  • 結果セットの保持性

SQL ファイルに含まれる次の 2 つの項目は同一と見なされます。 SQL ステートメントの前後にある空白文字のみが異なっています。

-- resultSetType=TYPE_FORWARD_ONLY
-- resultSetConcurrency=CONCUR_READ_ONLY
         SELECT * FROM EMPLOYEE ;

-- resultSetType=TYPE_FORWARD_ONLY
-- resultSetConcurrency=CONCUR_READ_ONLY
SELECT * FROM EMPLOYEE     ;

SQL ファイルに含まれる次の 2 つの項目は同一とは見なされません。 SQL ステートメント内の空白文字の数が異なっています。

-- resultSetType=TYPE_FORWARD_ONLY
-- resultSetConcurrency=CONCUR_READ_ONLY
SELECT      *      FROM      EMPLOYEE;

-- resultSetType=TYPE_FORWARD_ONLY
-- resultSetConcurrency=CONCUR_READ_ONLY
SELECT * FROM EMPLOYEE;

SQL ファイル内のこれら 2 つの項目は、異なるカーソル属性が指定されているため同一ではありません。

-- resultSetType=TYPE_FORWARD_ONLY
-- resultSetConcurrency=CONCUR_READ_ONLY
SELECT * FROM EMPLOYEE;

-- resultSetType=TYPE_SCROLL_SENSITIVE
-- resultSetConcurrency=CONCUR_READ_ONLY
SELECT * FROM EMPLOYEE;
以下の項目は入力 SQL ファイル内にあります。 これらの SQL ステートメントは、リテラル値以外は同一です。
SELECT * FROM EMPLOYEE WHERE EMPNO = '000010'
SELECT * FROM EMPLOYEE WHERE EMPNO = '000020'
SELECT * FROM EMPLOYEE WHERE EMPNO = '000030'
sqlLiteralSubstitution オプションの値を ENABLE に 設定して GeneratePureQueryXml ユーティリティーを実行すると、リテラル値がパラメーター・マーカーに置き換えられ、置換によって生じた重複は削除されます。 結果として、単一 SQL ステートメントで、pureQueryXML ファイルに書き込まれます。
SELECT * FROM EMPLOYEE WHERE EMPNO = ?

フィードバック