pureQuery Configure ユーティリティー

pureQuery Configure ユーティリティーを使用して、最終的に pureQueryXML ファイル内の SQL ステートメントに対して作成する DB2 パッケージのいくつかの特性を設定できます。 DB2 パッケージのコレクション、バージョン、およびルート・パッケージ名を設定し、パッケージで許可される SQL ステートメントの最大数を設定することができます。

設定される特性は、pureQueryXML ファイルに追加されます。pureQueryXML ファイル内にある SQL ステートメントを DB2 パッケージにバインドするために StaticBinder ユーティリティーを実行する場合、StaticBinder ユーティリティーはこれらの特性を読み取ります。

このトピックには以下のセクションが含まれています。

Configure ユーティリティーの出力

Configure ユーティリティーは、更新するすべての pureQueryXML ファイルに対して、1 つから 3 つの追加ファイルを生成します。
  • Configure ユーティリティーが必ず作成する最初の生成ファイルは、ユーザーが提供した pureQueryXML ファイルのコピーです。pureQueryXML ファイルの名前が sampleJDBC.pdqxml であれば、コピーは sampleJDBC.pdqxml.org です (「org」は「original」の略語)。
  • 2 番目のファイルは、Configure ユーティリティーの実行時に、バージョン ID を pkgVersion オプションとともに指定した場合に生成されます。 Configure ユーティリティーは、値を pureQueryXML ファイルのコピーの名前に付加します。 例えば、-pkgVersion Ver1.0 -pureQueryXml sampleJDBC.pdqxml は、更新された sampleJDBC.pdqxml とは名前だけが異なる、sampleJDBC.pdqxml_Ver1.0 という名前の同一内容のファイルを作成します。
    使用するアプリケーションと関連付けられている以前のバージョンの DB2 パッケージに切り替えられるようにする場合は、バージョン管理を使用できます。例えば、以下の 4 つの pureQueryXML ファイルを持っているとします。
    • 内容は同一の sampleJDBC.pdqxmlsampleJDBC.pdqxml_3.0
    • sampleJDBC.pdqxml_2.5
    • sampleJDBC.pdqxml_2.0
    さらに、同じバージョン番号を使用する、対応する DB2 パッケージも持っているとします。最新の DB2 パッケージ (バージョン 3.0) を使用してアプリケーションを実行した後に、前のパッケージ (バージョン 2.5) への復帰を決めたとします。 現在の sampleJDBC.pdqxml ファイルを sampleJDBC.pdqxml_2.5 のコピーで置き換え、アプリケーションを実行します。 それからさらに、バージョン 3.0 の DB2 パッケージに復帰する場合は、sampleJDBC.pdqxmlsampleJDBC.pdqxml_3.0 のコピーに置き換えるだけで済みます。
  • 3 番目のファイルは、pureQueryXML ファイルに DDL ステートメントが含まれている場合に生成されます。 DECLARE GLOBAL TEMPORARY TABLE ステートメントを除き、Configure ユーティリティーは pureQueryXML ファイル内のすべての DDL ステートメントを、ファイル・タイプ .ddl のテキスト・ファイルにコピーします。 このファイルを使用すると、DDL ステートメントをバインドしたくない場合に、データベース管理者は、これらの DDL ステートメントを参照する DML ステートメントをバインドする前にターゲット DBMS でステートメントを実行できます。DDL ステートメントが作成または変更するデータベース・オブジェクトは、それらのオブジェクトを参照する DML ステートメントがバインドできるように、必ず存在していなければなりません。 この .ddl ファイルの編集が必要になる場合があります。

Configure ユーティリティーが pureQueryXML ファイルに対して行う更新を検証するには、ファイルをエディターで開くことができます。

Configure ユーティリティーが pureQueryXML ファイルを更新するために使用したいずれかの値を変更するには、Configure ユーティリティーを再実行して、pureQueryXML ファイルを提供します。

Configure ユーティリティーで既に処理した pureQueryXML ファイルに SQL ステートメントを追加した場合、Configure ユーティリティーを再実行して、pureQueryXML ファイルを提供する必要があります。

オプション・ファイル

オプション・ファイルでは、pureQuery Configure ユーティリティーで処理する pureQueryXML ファイル (複数可) と、kpureQueryXML ファイルの処理方法を Configure ユーティリティーに通知するオプションがリストされます。オプション・ファイルにリストされているすべての pureQueryXML ファイルに適用されるデフォルト・オプションを設定できます。 さらに、デフォルト・オプションをオーバーライドして、個別の pureQueryXML ファイルに固有の他のオプションを設定できるように、pureQueryXML ファイルにオプションを設定することもできます。

Configure ユーティリティーを実行するコマンドでは、-optionsFile オプションで使用するファイルを指定することができます。

例えば、pureQuery Configure ユーティリティーの単純なオプション・ファイルは以下のようになります。
defaultOptions = -collection COLL01 -traceFile C:\logs\configure.txt -traceLevel ALL
C:\capture_files\capture_sales.pdqxml = -collection NULLID -rootPkgName SALES
C:\capture_files\capture_employee.pdqxml = -collection COLL02 -rootPkgName EMP
C:\capture_files\capture_orders.pdqxml = -rootPkgName ORDERS
この例では、defaultOptions で始まる行は、最終的に作成およびバインドされる DB2 パッケージのコレクション ID を指定します。 さらにその行では、メッセージをログに記録するファイルも指定します。 次の 2 つの行はデフォルトのコレクション ID をオーバーライドします。3 つの pureQueryXML ファイルのすべてにおいて、必須の -rootPkgName オプションは DB2 パッケージ名のルート・パッケージ名を指定します。
さらに、各コメント行の前に # 記号を置くことによって、オプション・ファイルにコメントを含めることもできます。オプションのいずれかの値でこの記号を表示する必要がある場合は、以下のように値を二重引用符で囲みます。
-pkgVersion "ver#1"
コマンド行から Configure ユーティリティーを実行してオプション・ファイルを使用する場合、pureQuery は以下の優先順位でオプションを認識します。
  1. コマンド行のオプション
  2. 指定されたオプション・ファイルにある個別のインターフェースのオプション
  3. 指定されたオプション・ファイルにあるデフォルト・オプション

オプション・ファイルを使用せずに Configure ユーティリティーを実行するコマンドの構文

pureQueryXML ファイルが 1 つしかない場合は、pureQueryXML ファイルの名前と、DB2 パッケージ用のオプションを指定するために、このコマンドを使用することを選択できます。

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

>--+-------------------------------+---------------------------->
   '- -collection--collection-name-'   

>--+-----------------------------+------------------------------>
   '- -markDDLForBind--+-TRUE--+-'   
                       '-FALSE-'     

>--+--------------------------------+--------------------------->
   '- -pkgVersion----+-AUTO-------+-'   
                     '-version-ID-'     

>-- -rootPkgName--package-name-stem-- -showDetails--+-TRUE--+--->
                                                    '-FALSE-'   

>--+--------------------+--+---------------------+-------------->
   '- -sqlLimit--number-'  '-|--Trace options--|-'   

>-- -pureQueryXml--pureQueryXML-file---------------------------><

オプション・ファイルを使用して Configure ユーティリティーを実行するコマンドの構文

pureQueryXML ファイルが複数ある場合は、pureQueryXML ファイルの名前と、DB2 パッケージ用のオプションを指定するために、コマンドとオプション・ファイルを使用します。pureQueryXML ファイルが 1 つしかない場合でも、コマンドとオプション・ファイルは使用できます。

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

>-- -optionsFile--file-name--+---------------------+-----------><
                             '-|--Trace options--|-'   

Configure ユーティリティーのオプション・ファイルにデフォルト・オプションを指定する構文

この構文図は、オプション・ファイルにリストしたすべての pureQueryXML ファイルに対して設定できるデフォルト・オプションを示しています。

構文図を読む構文図をスキップする
>>-defaultOptions--=--+-------------------------------+--------->
                      '- -collection--collection-name-'   

>--+-----------------------------+------------------------------>
   '- -markDDLForBind--+-TRUE--+-'   
                       '-FALSE-'     

>--+--------------------------------+--------------------------->
   '- -pkgVersion----+-AUTO-------+-'   
                     '-version-ID-'     

>-- -showDetails--+-TRUE--+--+--------------------+------------->
                  '-FALSE-'  '- -sqlLimit--number-'   

>--+---------------------+-------------------------------------><
   '-|--Trace options--|-'   

Configure ユーティリティーのオプション・ファイル内の個々の pureQueryXML ファイルに対してオプションを指定する構文

この構文図は、オプション・ファイルにリストした各 pureQueryXML ファイルに対して設定できるオプションを示しています。

構文図を読む構文図をスキップする
>>-pureQueryXML-file--=--+-------------------------------+------>
                         '- -collection--collection-name-'   

>--+-----------------------------+------------------------------>
   '- -markDDLForBind--+-TRUE--+-'   
                       '-FALSE-'     

>--+--------------------------------+--------------------------->
   '- -pkgVersion----+-AUTO-------+-'   
                     '-version-ID-'     

>-- -rootPkgName--package-name-stem-- -showDetails--+-TRUE--+--->
                                                    '-FALSE-'   

>--+--------------------+--------------------------------------><
   '- -sqlLimit--number-'   

オプションの説明

pureQueryXML-file (オプション・ファイルの行の始め)
オプション・ファイルのこの行のオプションが適用される pureQueryXML ファイルの名前 (絶対パスまたは相対パスを含む) を指定します。このファイルの拡張子は、.pdqxml または .xml でなければなりません。
この行で指定するオプションは、defaultOptions 行で指定するオプションよりも優先されます。
-collection collection-name
pureQuery StaticBinder ユーティリティーがバインドするパッケージの修飾子。 修飾子は、使用している DB2 データベースのコレクション名の制約を満たしている必要があります。
このパラメーターを指定しない場合、値のデフォルトは NULLID です。
-markDDLForBind
Configure ユーティリティーが pureQueryXML ファイル内のすべての DDL ステートメントの isBindable 属性に対して設定する値を指定します。Configure ユーティリティーは、DLL ステートメントのパッケージの isBindable 属性に対しても、この値を設定します。

有効な値は TRUE と FALSE であり、大/小文字は区別されません。デフォルト値はありません。

TRUE
isBindable の値が TRUE である場合は、StaticBinder ユーティリティーが pureQueryXML ファイルを処理する際に、対応する DDL ステートメントまたは DDL パッケージがバインドされます。
FALSE
isBindable の値が FALSE である場合は、StaticBinder ユーティリティーが pureQueryXML ファイルを処理する際に、対応する DDL ステートメントまたは DDL パッケージがバインドされません。

このオプションを指定しなかった場合、Configure ユーティリティーは、pureQueryXML ファイル内のすべての DDL ステートメントについて isBindable が TRUE であるかどうかをチェックします。少なくとも 1 つの DDL ステートメントで isBindable が TRUE である場合、Configure ユーティリティーは DDL パッケージの isBindable 属性を TRUE に設定します。

StaticBinder ユーティリティーは、DDL パッケージの isBindable 属性の値が TRUE であることを検出すると、isBindable 属性の値が TRUE になっているそのパッケージ内のすべてのステートメントをバインドしようとします。

-optionsFile file-name
pureQuery StaticBinder ユーティリティー用のメタデータで変更する pureQueryXML ファイルをリストするファイルの名前 (絶対パスまたは相対パスを含む)。
-pkgVersion AUTO|version-ID
パッケージをバインドするときに使用されるパッケージ・バージョンを指定します。

DB2 では複数のバージョンのパッケージを同時に存在させることができるため、古いバージョンのパッケージを置換することなく、同名の新しいパッケージをバインドできます。 新しいパッケージで問題が発生した場合には、そのパッケージの古いバージョンを使用することができます。

このオプションを指定しない場合は、後続のバインドによって生成されるデータベース・パッケージはバージョンなしで作成されます。

AUTO
現在のタイム・スタンプを使用してバージョンが自動的に生成されることを指定します。
version-ID
パッケージのバージョン ID を指定します。ストリングは、使用している DB2 のバージョンにおいて有効なものにする必要があります。
Configure ユーティリティーは、pureQueryXML ファイルのコピーを作成し、そのファイルの名前にバージョン ID を付加します。 このため、バージョン ID には、オペレーティング・システム上のファイル名に有効な文字のみを含めることができます。 さらに、ストリングの長さおよびパッケージの名前は、オペレーティング・システムがファイル名でサポートする長さを超えることはできません。

実行時のバージョン検査は、バージョン名ではなく、整合性トークンに基づいて行われます。

-pureQueryXml pureQueryXML-file
絶対パスまたは相対パスを含む pureQueryXML ファイルの名前。このファイルの拡張子は、.pdqxml または .xml でなければなりません。
-rootPkgName package-name-stem
DB2 パッケージに使用される名前の語幹を指定します。 Configure ユーティリティーでの DB2 パッケージの名前の生成についての詳細は、sqlLimit の説明を参照してください。

package-name-stem は、使用している DB2 データベースで設定された制約の範囲内でなければなりません。

DB2 パッケージを作成するのではなく、pureQuery StaticBinder ユーティリティーを使用して DBRM ファイルを生成する計画である場合には、package-name-stem を大文字にし、最大 6 文字にする必要があります。pureQueryXml ファイルに DDL ステートメントが含まれている場合、またはパッケージごとのステートメント数 (sqlLimit で指定) に達した場合、Configure ユーティリティーは名前の語幹に文字を付加します。StaticBinder ユーティリティーを使用して DBRM ファイルを生成する場合、Configure の機能による package-name-stem と余分の文字と分離レベルの組み合わせが 8 文字より長くなると、StaticBinder ユーティリティーは例外をスローします。

-showDetails true|false
Configure ユーティリティーで自身の動作のサマリーを表示するかいなかを指定します。
デフォルト値は false です。
-sqlLimit number
DB2 パッケージで許可される SQL ステートメント数の限度を指定します。 一般に、SQL ステートメントの数がこの限度を超えると、超過したステートメントが含まれる別のパッケージが pureQuery StaticBinder ユーティリティーにより作成されます。 StaticBinder ユーティリティーには、パッケージ内の SQL ステートメントがもう少し多く含まれる場合もあります。

指定値がデフォルト値より小さい場合にはユーザーへの通知なしで無視され、代わりにデフォルト値が使用されます。 デフォルト値は 100 です。

例えば、ご使用のデータベースで長いパッケージ名がサポートされていると想定し、myPackage というルート名で 4 つパッケージ (4 つの異なる分離レベルごとに 1 つのパッケージ) を作成すると仮定します。 使用している pureQueryXML ファイルに含まれるステートメントの数が 101~199 の間で、sqlLimit がデフォルト値に設定されている場合は、バインド操作により次のパッケージが生成されます。
表 1. パッケージの表
  最初の 100 個の SQL ステートメントが入っているパッケージ 次の n 個の SQL ステートメントが入っているパッケージ。ただし 100 < n < 200
分離レベル CS myPackageA1 myPackageB1
分離レベル RR myPackageA2 myPackageB2
分離レベル RS myPackageA3 myPackageB3
分離レベル UR myPackageA4 myPackageB4

数値はパッケージの分離レベルを示し、文字は、sqlLimit の値と pureQueryXML ファイルに含まれるステートメントの数に基づいて作成されたパッケージの数を示します。 文字は、英語のアルファベットの順序で数えます。文字 z に達し、さらにパッケージを作成する必要がある場合、文字は引き続き AA、AB、AC、という順序で付加されます。 名前がデータベースで許容される長さを超えてしまう場合には、ご使用のルート・パッケージ名の長さを短くしてください。

DB2 パッケージの作成時にバインド操作が SQL ステートメントの制限を超える場合があります。 カーソル操作を行う SQL ステートメントはすべて、そのカーソルの DECLARE CURSOR ステートメントと同じパッケージになければなりません。 例えば、アプリケーションで、同じカーソルを参照する異なる UPDATE ステートメントを 15 個実行する場合、15 個のステートメントはすべて、そのカーソルの DECLARE CURSOR ステートメントが置かれている DB2 パッケージに置かれていなければなりません。

その値を 100 未満に設定しようとすると、バインド操作では 100 が使用されます。アプリケーションで最高のパフォーマンスを得るためには、sqlLimit を 400 より大きい値に設定しないでください。

トレース・オプション
メッセージをログに記録するファイルを指定したり、ログに記録する情報レベルを指定したりできます。
構文図を読む構文図をスキップする
>>-+------------------------+--+---------------------------+---><
   '- -traceFile--file-name-'  '- -traceLevel--+-OFF-----+-'   
                                               +-ALL-----+     
                                               +-SEVERE--+     
                                               +-WARNING-+     
                                               +-INFO----+     
                                               +-CONFIG--+     
                                               +-FINE----+     
                                               +-FINER---+     
                                               '-FINEST--'     

-traceFile file-name
操作に関する情報をログに記録するために使用するファイルの絶対パスまたは相対パスと名前を指定します。
ファイルがすでに存在する場合、pureQuery は新規のメッセージを既存のファイルの内容に追加します。
-traceLevel
ログに記録する情報のタイプを指定します。 デフォルトのレベルは OFF です。ログ項目を書き込むファイルを指定せず、このオプションを OFF 以外の値に設定した場合、項目はコンソールに書き込まれます。

Configure ユーティリティーの実行の例

JDBC アプリケーションが作成する各接続に 1 つずつ、合わせて 2 つの pureQueryXML ファイルがあるとしましょう。ファイル名は、capture_sales.pdqxml (450 の SQL ステートメントを含む) および capture_employee.pdqxml (これも 450 の SQL ステートメントを含むが、その 50 は DDL ステートメント) であるとします。

これらのファイルに対して、以下の値を Configure ユーティリティーに提供します。

表 2. Configure ユーティリティーの値の例
Configure ユーティリティーのオプション capture_sales.pdqxml capture_employee.pdqxml
-collection first second
-markDDLForBind FALSE FALSE
-pkgVersion 1.0 1.0
-rootPkgName PK001S PK005E
-sqlLimit 200 200
この状況では、Configure ユーティリティーの実行に使用できる以下の 2 つの方式があります。
  • Configure ユーティリティーを 2 度実行して、それぞれで異なる .pdqxml ファイルを提供する。
    java com.ibm.pdq.tool.Configure -collection first -pkgVersion 1.0 -rootPkgName PK001S \
    -sqlLimit 200 -pureQueryXml C:\capture_files\capture_sales.pdqxml
    java com.ibm.pdq.tool.Configure -collection second -pkgVersion 1.0 -rootPkgName PK005E \
    -sqlLimit 200 -pureQueryXml C:\capture_files\capture_employee.pdqxml
  • Configure ユーティリティーを一度だけ実行して、.pdqxml ファイルがリストされているオプション・ファイルを提供する。

    コマンドは、以下のようになります。

    java com.ibm.pdq.tool.Configure -optionsFile myOptionsFile.txt

    オプション・ファイルは、ご使用のオペレーティング・システムがサポートする任意の名前と拡張子を付けることができ、以下の項目を持ちます。

    defaultOptions = -pkgVersion 1.0 -sqlLimit 200
    
    C:\capture_files\capture_sales.pdqxml = -collection first -rootPkgName PK001S
    
    C:\capture_files\capture_employee.pdqxml = -collection second -rootPkgName PK005E
どの方式を使用するとしても、Configure ユーティリティーは、さまざまなオプションに対してユーザーが指定した値で 2 つの .pdqxml ファイルを更新します。さらに Configure ユーティリティーは、以下のファイルも生成します。
capture_sales.pdqxml に基づくファイル
capture_sales.pdqxml.org

capture_sales.pdqxml_1.0

capture_employee.pdqxml に基づくファイル
capture_employee.pdqxml.org

capture_employee.pdqxml_1.0

capture_employee.ddl

関連タスク
他の pureQuery ユーティリティーからの pureQuery ログ・ユーティリティーのプロパティーの設定

フィードバック