図で使用される規則を理解するには、構文図の読み方を参照してください。
静的に DB2 パッケージにバインドされる、組み込み SQL を使用するアプリケーションは、パフォーマンス、信頼性、セキュリティー、モニター機能、および管理の点で最初から優れています。
StaticBinder ユーティリティーを実行する前に、pureQuery Generator ユーティリティーを実行して、バインドする SQL ステートメントが含まれるインターフェースのインプリメンテーション・クラスを生成します。pureQuery Generator ユーティリティーを実行すると、静的 DB2 パッケージを作成するために必要なすべての情報が収集されて、生成されたインプリメンテーション・クラスに格納されます。この情報には、SQL ステートメントに関する情報と、適用可能なすべてのデータ型についての情報が、Java クラス定義からと、ターゲット・データベースの列またはパラメーター・メタデータからの両方について含まれています。またこの情報には、DB2 パッケージのルート・パッケージ名と、オプションとしてコレクション ID およびバージョンが含まれます。
StaticBinder ユーティリティーは、DB2 パッケージの作成とバインド時にインプリメンテーション・クラスからこの情報を読み取ります。StaticBinder ユーティリティーを実行する際に、読み取り元のインプリメンテーション・クラス、またはそうしたクラスに対応するインターフェースをコマンド行から指定できます。オプション・ファイルを使用する場合、1 つ以上のインターフェースを指定できます。StaticBinder ユーティリティーは、対応するインプリメンテーション・クラスから情報を読み取ります。
ただし、ジェネレーター・ユーティリティーの実行時に -forceSingleBindIsolation オプションを使用した場合には、分離レベルの数字は、作成されたパッケージの名前に付加されません。
バインドの実行時に -isolationLevel オプションを使用した場合、 またはバインド・オプション・ストリングで分離レベルを指定した場合には、指定した分離レベルのパッケージまたは DBRM ファイルのみが作成されます。 名前は、4 つのすべての分離レベルでパッケージまたは DBRM ファイルを作成するときに StaticBinder が使用する規則に従います。
オプション・ファイルは、pureQuery StaticBinder ユーティリティーで処理する単一または複数のインターフェース、およびインターフェースを処理する方法を StaticBinder ユーティリティーに指示するオプションをリストします。 オプション・ファイルにリストしたすべてのインターフェースに適用するデフォルト・オプションを設定できます。 また、デフォルト・オプションをオーバーライドするためにインターフェースのオプションを設定したり、個々のインターフェースに固有の他のオプションを設定したりすることもできます。
StaticBinder ユーティリティーを実行するコマンドでは、-optionsFile オプションを指定して、使用するファイルを指定できます。
defaultOptions = -bindOptions "QUALIFIER qual1" -url jdbc:db2://SRVR01:50000/DB01 -username user01 -password pass01
com.myCompany.MyInterfaceA = -bindOptions "QUALIFIER qual2"
com.myCompany.MyInterfaceB
com.myCompany.MyInterfaceC = -url jdbc:db2://SRVR01:50001/DB02 -username user02 -password pass02
この例の defaultOptions から始まる行では、
DB2 パッケージの修飾子が指定されるとともに、デフォルト接続 URL が設定されています。
次の行では、デフォルト修飾子をオーバーライドする修飾子が指定されたインターフェースが指定されています。
その次の行では、すべてのデフォルト・オプションが適用されるインターフェースが指定されています。
最後の行では、別のデータベースにバインドするインターフェースが指定されています。-pkgVersion "ver#1"
オプション・ファイルで、Java インターフェースのセットに適用される StaticBinder プロパティーを指定する項目を作成できます。 groupOptions.group-name で始まる行を作成します。 group-name の値はグループ ID です。 値 group-name は、pureQuery @Group アノテーション付きのインターフェースに割り当てられるストリングです。
@Group ("Payroll")
public Interface CalculateTax {
…
}
次の groupOptions.Payroll 項目がオプション・ファイルに指定されているときには、StaticBinder が、
指定のオプション設定を使用してインターフェース CalculateTax のアノテーション付きメソッドに対してバインド操作を実行します。
groupOptions.Payroll -bindOptions "QUALIFIER(Payroll), COLLECTION(Payroll)" -url "jdbc:db2://com.prod.hr:50000/DB01"
複数の groupOptions 項目を使用すれば、さまざまなオプションでインターフェースをバインドできます。 例えば、インターフェースに @Group("Group1") でアノテーションが付けられ、非修飾の SQL ステートメントが含められるとします。 そのインターフェースのパッケージをバインドして、異なるスキーマ値を持つ 2 つの別々のパッケージ・コレクションを生成できます。 Group1 のオプション・ファイルに 2 つの groupOptions 項目を作成します。 groupOptions.Group1 項目ごとに、異なる COLLECTION オプションおよび QUALIFIER オプションを指定します。 StaticBinder が、一致する各 groupOptions 項目の指示どおりにパッケージをバインドします。
@Group アノテーションについては、 『pureQuery ユーティリティーがインターフェースを処理する方法を制御』を 参照してください。
DB2 Database for Linux, UNIX, and Windows: ユーザーに SYSADM 権限があるものの、 バインドを完了するための明示特権がない場合、DB2 データベース・マネージャーは明示的な DBADM 権限を自動的に付与します。
このコマンドを使用すると、アプリケーションが含まれているアーカイブに対して StaticBinder ユーティリティーを実行できます。 アーカイブは StaticBinder ユーティリティーに提供するインターフェースとインプリメンテーション・クラスを含んでいる必要があります。インターフェースとインプリメンテーション・クラスをリストする、拡張子が .bindProps であるオプション・ファイルを使用します。
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> (2) >-------- -url--jdbc--:--db2--:--//--server--+---------+--/--database--> '-:--port-' >-- -username--user-ID-- -password--password--------------------> >-- -archive-- -filename--+-.ear-+------------------------------> +-.jar-+ +-.war-+ '-.zip-' >--+-------------------------+----------------------------------> | .-FALSE-. | '- -autoDetect--+-TRUE--+-' >--+------------------------------------------------------------------------+--> | (3) | +-| DBRM options |-------------------------------------------------------+ +- -bindOptions-- -"--bind-options--"--+-------------------------------+-+ | '- -verifyPackages--+-DETAIL--+-' | | '-SUMMARY-' | '- -verifyPackages--+-DETAIL--+------------------------------------------' '-SUMMARY-' >--+-----------------------------+--+----------------+----------> | .-FALSE-. | | (4) | '- -differenceOnly--+-TRUE--+-' '-| -grant |-----' >--groupOptions--.--group-name--=-------------------------------> >--+--------------------------+--+-----------------------+----->< '- -isolationLevel--+-CS-+-' | (5) | +-RR-+ '-| Trace options |-----' +-RS-+ '-UR-'
このコマンドを使用すると、インターフェースまたはインプリメンテーション・クラスの名前を指定したり、DB2 パッケージまたは DBRM ファイルを作成するためのオプションを指定したりできます。
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> (2) >-------- -url--jdbc--:--db2--:--//--server--+---------+--/--database--> '-:--port-' >-- -username--user-ID-- -password--password--------------------> >--+------------------------------------------------------------------------+--> | (3) | +-| DBRM options |-------------------------------------------------------+ +- -bindOptions-- -"--bind-options--"--+-------------------------------+-+ | '- -verifyPackages--+-DETAIL--+-' | | '-SUMMARY-' | '- -verifyPackages--+-DETAIL--+------------------------------------------' '-SUMMARY-' >--+-----------------------------+--+----------------+----------> | .-FALSE-. | | (4) | '- -differenceOnly--+-TRUE--+-' '-| -grant |-----' >--groupOptions--.--group-name--=-------------------------------> >--+--------------------------+--+-----------------------+------> '- -isolationLevel--+-CS-+-' | (5) | +-RR-+ '-| Trace options |-----' +-RS-+ '-UR-' .------------------------. V | >-- -interface----Java-package.interface-+---------------------><
以下のコマンドとオプション・ファイルを使用すると、インターフェース名を指定したり、こうしたそれぞれのインターフェースに基づく DB2 パッケージまたは DBRM ファイルを作成するためのオプションを指定したりできます。
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> >--+---------------------------------------------------------------------------------------------------------+--> '- -url--jdbc--:--db2--:--//--server--+---------+--/--database-- -username--user-ID-- -password--password-' '-:--port-' >--+-----------------------------------------------+------------> | .------------------------------. | | V | | '- -interface----Java-package.interface.class-+-' >-- -optionsFile--file-name--+-----------------------+----------> | (2) | '-| Trace options |-----' >--+-------------------------------+--------------------------->< '- -verifyPackages--+-DETAIL--+-' '-SUMMARY-'
この構文図は、オプション・ファイルにリストされているすべてのインターフェースに設定できるデフォルト・オプションを示しています。
(1) >>-defaultOptions--=--------------------------------------------> >--+---------------------------------------------------------------------------------------------------------------+--> | (2) | '------- -url--jdbc--:--db2--:--//--server--+---------+--/--database-- -username--user-ID-- -password--password-' '-:--port-' >--+-----------------------------------------+------------------> '-+- -bindOptions-- -"--bind-options--"-+-' | (3) | '-| DBRM options |--------------------' >--+----------------+--+--------------------------+-------------> | (4) | '- -isolationLevel--+-CS-+-' '-| -grant |-----' +-RR-+ +-RS-+ '-UR-' >--+-----------------------+----------------------------------->< | (5) | '-| Trace options |-----'
この構文図は、オプション・ファイルにリストされている各インターフェースに設定できるオプションを示しています。
(1) >>-Java-package.interface--=------------------------------------> >--+---------------------------------------------------------------------------------------------------------------+--> | (2) | '------- -url--jdbc--:--db2--:--//--server--+---------+--/--database-- -username--user-ID-- -password--password-' '-:--port-' >--+-----------------------------------------+------------------> '-+- -bindOptions-- -"--bind-options--"-+-' | (3) | '-| DBRM options |--------------------' >--+----------------+--+--------------------------+------------>< | (4) | '- -isolationLevel--+-CS-+-' '-| -grant |-----' +-RR-+ +-RS-+ '-UR-'
次の構文図では、インターフェースに設定できるオプションが グループ ID group-name の Java インターフェースのセットに適用されています。 group-name は、pureQuery @Group アノテーション付きのインターフェースに割り当てられるストリングです。 値 group_name では大/小文字が区別されます。
groupOptions.group-name の行は、同じ group-name に対して何度も使用できます。
(1) >>-groupOptions--.--group-name--= ------------------------------> >--+---------------------------------------------------------------------------------------------------------------+--> | (2) | '------- -url--jdbc--:--db2--:--//--server--+---------+--/--database-- -username--user-ID-- -password--password-' '-:--port-' >--+-----------------------------------------+------------------> '-+- -bindOptions-- -"--bind-options--"-+-' | (3) | '-| DBRM options |--------------------' >--+----------------+--+--------------------------+-------------> | (4) | '- -isolationLevel--+-CS-+-' '-| -grant |-----' +-RR-+ +-RS-+ '-UR-' >--+-----------------------+----------------------------------->< | (5) | '-| Trace options |-----'
アプリケーションの SQL ステートメントを DB2 パッケージに実行時にバインドするには、 com.ibm.pdq.tools.StaticBinder クラスの bind() メソッドを使用します。 このメソッドは、バインド操作が失敗すると値 FALSE を返し、バインド操作が正常に実行されると値 TRUE を返します。
このメソッドは 2 つのパラメーターを取ります。 最初のパラメーターは、引数を StaticBinder ユーティリティーに渡すためのストリング配列です。 2 番目のパラメーターは、StaticBinder ユーティリティーがメッセージおよび例外を出力する先の PrintWriter オブジェクトです。
bind() メソッドの呼び出し例を以下に示します。
StaticBinder binder = new StaticBinder ();
PrintWriter out = new PrintWriter(
new FileWriter("BinderOutput.txt"));
String[] argsArray = {"-user","username","-password","password",
"-url","JDBC-URL","-interface","interface-class"};
Boolean check=binder.bind(argsArray, out);
アーカイブには、StaticBinder ユーティリティーに渡す pureQueryXML ファイルをリストしたオプション・ファイル (拡張子は .bindProps) を含めることができます。コマンドの一部として .bindProps ファイルを指定しないと、StaticBinder ユーティリティーはアーカイブから .bindProps ファイルを検索します。StaticBinder ユーティリティーは、アーカイブから検出された最初の .bindProps ファイルを使用します。このユーティリティーは、トップレベルの EAR、JAR、または WAR から検索を開始します。
StaticBinder コマンドで .bindProps ファイルの名前を指定した場合、指定されたファイルが使用されます。
-archive オプションを指定して DAO 実装環境をバインドすると、StaticBinder ユーティリティーは実装クラスをロードして、そのクラスから情報を取得します。 クラスをロードするためには、EAR、JAR、または WAR ファイルからの依存クラスのロードが必要になることがあります。
-archive オプションを指定してバインド操作を行っているときに、クラスが見つからないことに関連するエラーが StaticBinder ユーティリティーから返されることがあります。 例えば、アプリケーション・サーバーのコンテキストを必要とする一部のエンタープライズ・アプリケーションが、このようなエラーを返す場合があります。
StaticBinder ユーティリティーでの従属関係のロードを最低限に抑えるために、Apache BCEL ライブラリーをクラスパスに配置することができます。 StaticBinder ユーティリティーは、BCEL ライブラリーを使用できる場合、バイトコード修正を使用して実装の従属関係を除外し、ロードされるクラスの数を最小限に抑えます。 ほとんどの場合、このライブラリーをクラスパスに追加することで、クラス未検出に起因するエラーは解決します。
Apache BCEL JAR ファイルは pureQuery Runtime には付属していません。BCEL ライブラリーは、Apache プロジェクトの Web サイトから入手できます。
このオプションが値 FALSE とともに指定された場合、StaticBinder ユーティリティーはアーカイブ・ファイル内を検索しません。
-optionsFile プロパティーとともに StaticBinder ユーティリティーのプロパティー・ファイルが明示的に 指定されると、StaticBinder ユーティリティーは、プロパティー・ファイルで指定された成果物に対してバインド・プロセスを実行します。 その後で、アーカイブで検出されてもプロパティー・ファイルでは指定されなかったファイルに対してバインド・プロセスが実行されます。 -optionsFile プロパティーが指定されている場合、このユーティリティーは、.bindprops ファイルを検索しません。
アーカイブ・ファイル内で検出されたファイルに対してバインド操作を実行する場合、StaticBinder ユーティリティーは、 他の StaticBinder オプションで指定されたデフォルト・バインド・プロパティー・オプションを使用します。 例えば、バインド・オプションは -defaultOptions 行で指定できます。 @GroupId アノテーションを指定する実装クラスにアノテーションが存在する場合、 バインド・オプションは、StaticBinder の -groupOptions プロパティーによっても指定できます。
ストリングの構文は、"option_1 value_1 option_2 value_2" です。
StaticBinder ユーティリティーで DBRM ファイルが生成された後に、それらのファイルをデータ・セットにコピーする必要があります。デフォルトの DBRM データ・セット名は prefix.DBRMLIB.DATA です。ここで prefix は、ユーザーの TSO プロファイルで指定された高位修飾子です。通常、prefix は TSO におけるユーザー ID です。
DBRM データ・セットがまだ存在しない場合は、それを作成する必要があります。 DBRM データ・セットには、すべての SQL ステートメントを保持するスペースと、各ホスト変数名とヘッダー情報用の追加スペースが必要です。 ヘッダー情報の概算として、DBRM ごとに 2 つのレコード、SQL レコードごとに 20 バイト、ホスト変数ごとに 6 バイトが必要です。 DBRM の厳密なフォーマットについては、DBRM マッピング・マクロである、ライブラリー prefix.SDSNMACS の DSNXDBRM を参照してください。
以下の構文図は、DBRM ファイルを生成するためのオプションを記述しています。
>>- -generateDBRM--+-TRUE--+-- -outputDBRMPath--path----------->< '-FALSE-'
生成された DBRM ファイルのルート名は、ジェネレーター・ユーティリティーの実行時に指定したルート・パッケージ名です。 この名前が 7 文字より長い場合には、StaticBinder ユーティリティーは例外をスローします。
例えば、capture.pdqxml という名前の pureQueryXML ファイルに対して StaticBinder ユーティリティーを実行するとします。 このユーティリティーにより、パッケージ MYPKGA、MYPKGB、および MYPKGC が作成されます。 その後、ワークベンチを使用して capture.pdqxml 内のステートメント・セット MYPKGA を編集し、このファイルに対して、-cleanConfigure オプションを指定して (値としてはデフォルト値 FALSE を使用) Configure ユーティリティーを実行します。 セットが変更されたため、構成ユーティリティーは新規の整合性トークンをステートメント・セットに割り当てます。 MYPKGA の新しいバージョンをバインドするために capture.pdqxml に対して再び StaticBinder ユーティリティーを実行する際には、-differenceOnly TRUE を指定します。 ユーティリティーは MYPKGA のみを再バインドし、他の 2 つのパッケージの再バインドは行いません。
@Group アノテーションについては、 『pureQuery ユーティリティーがインターフェースを処理する方法を制御』を 参照してください。
.-,--------------------. V | >>- -grant-- "--grantees--(----+-authorization-ID-+-+--) - "--->< '-PUBLIC-----------'
DB2 Database for Linux, UNIX, and Windows の場合: USER キーワード、GROUP キーワード、および ROLE キーワードを使用できます。 これらのキーワードについては、『GRANT (パッケージ特権) ステートメント』を参照してください。
DB2 for z/OS の場合: ROLE キーワードを使用できます。 このキーワードについては、『GRANT (パッケージ特権)』を参照してください。
制限: -generateDBRM オプションの値が TRUE である場合には、-grant オプションは使用できません。
オプション・ファイルにインターフェースの項目が入っていない場合、StaticBinder ユーティリティーはコマンド行にあるバインド・オプションおよびオプション・ファイル内の defaultOptions 項目にあるバインド・オプションを使用します。
分離レベルは、パッケージ内のすべての SQL ステートメントに適用されます。 IBM® Data Server Driver for JDBC and SQLJ の Connection.setTransactionIsolation() メソッドを使用して分離レベルを設定した場合は、pureQuery は静的に実行されたステートメントの分離レベルを無視します。
>>-+------------------------+--+---------------------------+--->< '- -traceFile--file-name-' | .-OFF-----. | '- -traceLevel--+-ALL-----+-' +-SEVERE--+ +-WARNING-+ +-INFO----+ +-CONFIG--+ +-FINE----+ +-FINER---+ '-FINEST--'
例えば、表 ORDERS を照会および更新するメソッドを宣言する OrdersData という名前のインターフェースに対してジェネレーター・ユーティリティーを実行したとします。 ジェネレーター・ユーティリティーは、インプリメンテーション・クラス OrdersDataImpl を作成するものとします。
このユーティリティーを実行したときに、 -collection、-pkgVersion、および -rootPkgName オプションの値を指定し、ユーティリティーがインプリメンテーション・クラスにこれらの値を保管しました。 このクラスの名前を指定して StaticBinder ユーティリティーを実行します。ユーティリティーによって DB2 パッケージが作成されます。
後から、StaticBinder ユーティリティーがインプリメンテーション・クラスから作成したパッケージのリストを確認するとします。 ユーティリティーを実行する際に、値 DETAIL を指定して -verifyPackages オプションを使用し、再度クラスの名前を指定できます。
-collection、-pkgVersion、および -rootPkgName オプションの値が、StaticBinder ユーティリティーを前回実行したときと同じであれば、 ユーティリティーによってパッケージが検出されてリストされます。
ただし、StaticBinder ユーティリティーを最初に実行した後に OrdersData インターフェースに対してジェネレーター・ユーティリティーを実行して、 -collection、-pkgName、および -rootPkgName のいずれかの値を変更した場合には、StaticBinder ユーティリティーでは、これらのオプションの新しい値に一致するパッケージが検出されません。 StaticBinder ユーティリティーはレポートで、検索対象のパッケージが存在しないと報告します。
-verifyPackages オプションは、インプリメンテーション・クラスを生成して、そのクラスまたは関連インターフェースに対して StaticBinder ユーティリティーを実行した後に、 そのインターフェースに対して再度ジェネレーター・ユーティリティーを実行して -collection、-pkgVersion、および -rootPkgName に別の値を指定していないことを前提に機能します。
このオプションは、-bindOptions オプションとともに指定できます。 ただし、StaticBinder ユーティリティーはパッケージをバインドしません。 パッケージを作成したときに -bindOptions オプションを使用してコレクションを指定した場合には、 このオプションのみを使用して、検証するパッケージのコレクションを指定してください。