EVMON_FORMAT_UE_TO_TABLES プロシージャー - XML 文書をリレーショナル表へ移動する

構文

スキーマは SYSPROC です。

プロシージャー・パラメーター

EVMON_TYPE

フォーマットされていないイベント表に保管されているデータのタイプを表す、タイプ VARCHAR(128) の入力パラメーター。 可能な値は、以下のとおりです。

ロック

未フォーマット・イベント表に保管されているデータは、ロック・イベント・モニターからのものです。

PKGCACHE

フォーマットされていないイベント表に保管されているデータは、PACKAGE CACHE イベント・モニターからのものです。

UOW

フォーマットされていないイベント表に保管されているデータは、UOW イベント・モニターからのものです。

XSRSCHEMA

UE ファイルからのデータがどのように表の列に対応するかを示す XSR オブジェクトの名前の最初の部分を指定する VARCHAR (128) タイプの入力パラメーター。 XSR オブジェクト名の 2 番目の部分は xsrobjectname パラメーターから導出されます。 完全な XSR オブジェクト名は、xsrschema.xsrobjectname と定義されます。 この値が NULL の場合は、現行セッションのユーザーの許可 ID が使用されます。

XSROBJECTNAME

UE ファイルからのデータがどのように表の列に対応するかを示す XSR オブジェクトの名前の 2 番目の部分を指定する VARCHAR (128) タイプの入力パラメーター。 XSR オブジェクト名の最初の部分は、xsrschema パラメーターから導出されます。 完全な XSR オブジェクト名は xsrschema.xsrobjectname と定義され、XSR 内のすべてのオブジェクト間で固有です。 この値が NULL の場合、 xsrobjectname は次のように導出されます:EVMON_<evmon_type>_SCHEMA_<SQL release level>。

XSR オブジェクトは、イベント・モニターの出力を説明する XML スキーマ・ファイルのコピーです。 これは、XML スキーマ・リポジトリー (XSR) に格納され、EVMON_FORMAT_UE_TO_TABLES 処理の最初の段階で作成される一時 XML 文書の要素と、最終的にプロシージャーが作成する表および列の間のリレーションシップを定義します。 XSR オブジェクトは、作成されるすべての表とそれらの表を派生させる XML スキーマとの間の相互依存関係の管理を行うためにも使用されます。 XSR オブジェクトがドロップされるか、プロシージャーにより作成されたいずれかの表がドロップされたり列が変更されたりした場合、これら 2 つのものの間の依存関係は「壊れた」と言います。 EVMON_FORMAT_UE_TO_TABLES (または EVMON_FORMAT_UE_TO_XML 表関数) が特定のタイプのイベント・モニターの UE ファイルに対してまだ実行されていない場合、イベント・モニター出力を説明する XSR オブジェクトはまだ存在していません。 この場合、イベント・モニター用の XML スキーマ・ファイルが使用されて、システム・カタログ表に XSR オブジェクトを作成し登録します。

データベースを新しいリリースにアップグレードした場合、リレーショナル表と XML スキーマの間の従属関係を維持するためには、元の xsrobjectname を明示的に指定する必要があります。

xmlschemafile

イベント・モニターにより作成された出力を説明するディスク上の XML スキーマ文書の絶対パスを表わす、タイプ VARCHAR (1024) の入力パラメーター。 XML スキーマ文書要素には、XML 要素と属性をリレーショナル表とその列にマップする情報でアノテーションが付けられています。

このパラメーターは、XSR オブジェクトを登録するために使用されます。 evmon_type で指定されているイベント・モニターのタイプに関して登録されていて使用可能になっている XSR オブジェクトが存在しない場合、XSR オブジェクトは以下のように登録されます。

• xmlschemafile が NULL の場合、evmon_type に指定されている値に応じて、以下のように、プロシージャーはディスク上の XML スキーマ・ファイルを使用します。

  ロック

  sqllib/misc/DB2EvmonLocking.xsd

  PKGCACHE

  sqllib/misc/DB2EvmonPkgCache.xsd

  UOW

  sqllib/misc/DB2EvmonUOW.xsd

• XML スキーマ・ファイル名を指定した場合、分解のための XSR オブジェクトを登録し使用可能にするためにそのファイルが使用されます。
• xsrschema および xsrobjectname パラメーターの値を指定した場合、これらの名前を使用して XSR オブジェクトが作成されます。 それ以外の場合、XSR オブジェクトは、前述の xsrobjectnameのデフォルトを使用して命名されます。

重要: XSR オブジェクトが以前に登録されており、分解が有効になっている場合、このパラメーターは無視されます。 別の XML スキーマ・ファイルを使用する XSR オブジェクトを登録した場合、まず、既存の XSR オブジェクトをドロップする必要があります。

TABSCHEMA

イベント・モニターのリレーショナル表が作成される SQL スキーマ名を表す、タイプ VARCHAR (128) の入力パラメーター。 この値が NULL の場合は、現行セッションのユーザーの許可 ID が使用されます。 表が作成される SQL スキーマは、次のように判別されます。

• <db2-xdb:SQLSchema> が指定される場合には、このスキーマを使用します。
• <db2-xdb:defaultSchema> が指定される場合には、このスキーマを使用します。
• これらのどちらの値も指定されない場合には、sqlschema 入力パラメーターからの値を使用します。

注: XML スキーマが分解のために登録されると、XSR スキーマ・リポジトリーは、スキーマで参照される各表と、このスキーマに対応する XSR オブジェクトとの間に依存関係を作成します。 これは、データベース内のリレーショナル表の固有のセットに XSR オブジェクト名がリンクされることを意味します。 既存の XSR オブジェクトを参照すると、そのデータは必ず分解され、XSR オブジェクトがリンクされた表に挿入されます。

TBSP_NAME

リレーショナル表が作成される表スペースを示す、タイプ VARCHAR(128) の入力パラメーター。 このパラメーターのデフォルト値は NULL です。 なお、XML スキーマ・ファイル内の CREATE TABLE ステートメントで指定された表スペース名は、この入力パラメーターよりも優先されることに注意してください。

OPTIONS

この表関数でサポートされるキーワード・オプションのリストを表す、タイプ VARCHAR (1024) の入力パラメーター。 各オプションはセミコロン (;) 文字で区切られている必要があります。 可能な値は次のとおりです。

RECREATE_FORCE (RECREATE_FORCE)

分解の前にリレーショナル表をドロップして再作成します。

RECREATE_ONERROR (再作成エラー)

以下の状況では、リレーショナル表をドロップして再作成します。

1. XSR オブジェクトは登録されていないが、表が存在する場合。
2. 最初に失敗した分解の試行の際。 その後の失敗は戻され、表を再作成する試みは行われません。

例えば表スペースの満杯エラーや許可エラーなど、エラーが発生した場合にプロシージャーは、分解プロシージャーから戻される SQLCODE をフィルターに掛けません。 プロシージャーは負の SQLCODE すべてを等しく扱い、表の再作成を試みます。

表の予測 (PRUNE_UE_TABLE)

リレーショナル表に正常に挿入されたバイナリー・イベントをすべて UE 表からプルーニングする (つまり削除する) ことを示します。 プルーニングは、リレーショナル表への挿入が実行される同じ作業単位の中で行われます。

UPGRADE_TABLES (UPGRADE_TABLES)

このプロシージャーによって生成されたリレーショナル表を変更して、現行リリースの XSR オブジェクト xsrobjectname で定義されている表定義と一致するようにすることを示します。 以前のリリースで作成されたリレーショナル表をアップグレードして、現行リリースで加えた変更を反映する場合に、このパラメーターを指定します。 リリース間では、以下のタイプの変更が生じる可能性があります。

• 新しい列が表に追加される
• 新しい表がイベント・モニターの出力に追加される
• 列定義 (例えば、データ・タイプや長さ) が変更される

UPGRADE_TABLES オプションを使用しない場合、既存の表定義が保持されます。 現在のリリースで追加された新しい列または表のデータは、リレーショナル表にまったく書き込まれません。

UPGRADE_TABLES を指定する場合は、元の xsrobjectname も明示的に指定する必要があります。

commit_count

タイプ INTEGER の入力パラメーター。 可能な値は、以下のとおりです。

-1

100 文書が正常に分解されるごとにコミットします。-1 がデフォルト値です。

0

コミットなし。

n

n 個の文書が正常に分解されるごとにコミットします。

全選択

フォーマットされていないイベント表からの全選択ステートメントを表す、タイプ CLOB(2M) の入力パラメーター。 全選択ステートメントは、SELECT ステートメントの規則に準拠する照会です。 この照会は、以下の規則に従っていなければなりません。

• この照会は、"*" 節を使用するか、未フォーマット・イベント表のすべての列を指定する必要があります。 それ以外の場合、エラーが戻されます。 列は、未フォーマット・イベント表の DESCRIBE ステートメントで戻されたのと同じ順序で指定されている必要があります。
• この照会は、フォーマットされていないイベント表からのみ選択を行う必要があります。
• WHERE 節は、フォーマットされていないイベント表の非 LOB 列のいずれかを使用して、イベントをフィルターで除外することができます。

許可

EVMON_FORMAT_UE_TO_TABLES ストアード・プロシージャーに対する EXECUTE 特権。

未フォーマット・イベント表に対する SELECT 特権 (表を作成していない場合)。

指定した SQL スキーマのリレーショナル表を作成するための CREATE 特権。

リレーショナル表に挿入するための INSERT 特権 (それらの表を作成していない場合)。

XDB_DECOMP_XMP_FROM_QUERY プロシージャーが必要とするすべての特権。

デフォルトの PUBLIC 特権

制限のないデータベースでは、このプロシージャーが自動的に作成されると、EXECUTE 特権が PUBLIC に付与されます。

使用上の注意

XML 文書の最大サイズ 100 MB

EVMON_FORMAT_UE_TO_XML の最大 XML 文書サイズは 100 MB です。

EVMON_FORMAT_UE_TO_TABLES は EVMON_FORMAT_UE_TO_XML を使用するので、これと同じ 100 MB の制限が EVMON_FORMAT_UE_TO_TABLES に適用されます。

UE 表のレコードと EVMON_FORMAT_UE_TO_TABLES 表関数の出力の関係

UE 表に書き込まれるレコードと EVMON_FORMAT_UE_TO_TABLES プロシージャーの出力の間のマッピングは、1 対 1 ではありません。 UE 表に複数のレコードを生成するイベントもありますし、1 つのレコードだけが追加されるものもあります。 リレーショナル表にデータを書き込むとき、EVMON_FORMAT_UE_TO_TABLES プロシージャーは、複数の UE 表レコードにある情報を単一のリレーショナル表に結合させる場合もありますし、複数の行を異なる出力表に生成する場合もあります。

表の作成

分解が行われるためには、一連のリレーショナル表が存在しなければなりません。 EVMON_FORMAT_UE_TO_TABLES プロシージャーは、以下のようにリレーショナル表を自動的に作成します。

• プロシージャーは、<db2-mon:createStmt> エレメントを見つけるために、イベント・モニターの XML スキーマ・ファイルを解析します。 各エレメントには、完全な CREATE TABLE ステートメントが含まれています。
• プロシージャーは CREATE TABLE ステートメントを抽出して実行します。

<db2-mon:createStmt> は、既存の <db2-xdb:table> エレメントの子エレメントです。 この子エレメントを認識して使用できるのは、EVMON_FORMAT_UE_TO_TABLES プロシージャーだけです。 XML スキーマ・ファイルを解析する XSR オブジェクトなどの他のプロシージャーはすべて、このエレメントを無視します。

<db2-mon:createStmt> 内の表名を修飾してはなりません。

各リリースに対応した XML スキーマ・ファイル

イベント・モニターごとに用意されているデフォルトの XML スキーマ・ファイルは、現行リリース用の XML スキーマを常に反映しています。 それで、EVMON_FORMAT_UE_TO_TABLES (または EVMON_FORMAT_UE_TO_XML) を実行する際には、出力はそのリリースのイベント・モニター用に定義されているモニター要素を反映します。 次のセクションでは、イベント・モニター用のスキーマ・ファイルが時間と共に変更された場合に何が起こるかを説明します。 EVMON_FORMAT_UE_TO_TABLES プロシージャーを使用して表を作成してから、フィックスパックを適用したり新規リリースにアップグレードしたりする場合、これらの変更の影響について理解することが重要です。

EVMON_FORMAT_UE_TO_TABLES により作成される表へのスキーマ更新の影響

将来のフィックスパックまたはリリースでは、新規モニター要素がイベント・モニターに追加されるものと思われます。 これらの新規モニター要素により、新しい列また新規表を EVMON_FORMAT_UE_TO_TABLES プロシージャーが作成することになるかもしれません。 しかし、フィックスパックを適用したり新規リリースにアップグレードしたりする前に既にこのプロシージャーで作成した表がある場合、以下のことを行って新規リレーショナル列または表を作成する必要があります。

フィックスパック更新の場合

最新のフィックスパックのインストール前に EVMON_FORMAT_UE_TO_TABLES により作成されたリレーショナル表がまだ存在する場合、リレーショナル形式で新規モニター要素を表示したいならば、フィックスパックで出荷された新規スキーマに基づいて一連の新しい表を作成させなければなりません。

EVMON_FORMAT_UE_TO_TABLES プロシージャーに、フィックスパックで出荷された新規スキーマを強制的に使用させて新規表を作成させるには、以下のステップを行います。

1. 以下のいずれかのアクションを実行して、現在登録されているバージョンの XML スキーマ (スキーマ登録について詳しくは、EVMON_FORMAT_UE_TO_TABLES プロシージャーの tabschema パラメーターの下の 注 を参照) と既存の表との間の依存関係を切断します。
   • EVMON_FORMAT_UE_TO_TABLES によって作成された既存の表の 1 つをドロップする
   • DROP XSROBJECT ステートメントを使用して、既存の表に関連する登録済み XML スキーマ・オブジェクトをドロップする。 例えば、 Db2® 9.7のロック・イベント・モニター用に EVMON_FORMAT_UE_TO_TABLES によって生成された表に関連付けられた登録済み XML スキーマ・オブジェクトをドロップするには、次のコマンドを使用します。 DROP XSROBJECT EVMON_LOCKING_SCHEMA_SQL11050.
   • 現行の登録済み XML スキーマ・オブジェクトのアノテーションの付いたモニター要素に対応する既存の列を変更する。
2. FORCE オプションを使用して、EVMON_FORMAT_UE_TO_TABLES プロシージャーを実行する。 このオプションにより、以前の表はドロップされ、一連の新しい表が作成されます。 このオプションを指定しないと、SQL0601N エラーが戻ります。

このプロセスは、 例 5: フィックスパック更新での新規エレメントの選出に示されています。

上記のステップを実行しない場合、既存の表は以前に登録されたスキーマ・ファイルに基づいて更新されます。 フィックスパックに追加されているかもしれない新しい列または表は、EVMON_FORMAT_UE_TO_TABLES プロシージャーの出力に反映されません。

リリース・アップグレードの場合

他の指定をしない場合、EVMON_FORMAT_UE_TO_TABLES プロシージャーを呼び出す際には、現行リリース用の XML スキーマ・ファイルのデフォルト・バージョンが使用されます。 したがって、 Db2 製品の新規リリースにアップグレードする場合、デフォルトでは、プロシージャーの実行時にスキーマ・ファイルの新規バージョンが使用されます。

以前のリリースからの表が存在しない場合、EVMON_FORMAT_UE_TO_TABLES は最新のスキーマ使用して表を作成します。 しかし、以前のリリースからの表が存在する場合、FORCE または RECREATE_ONERROR オプションを使用して以前の表を新規表に置き換えなければなりません。 こうしないと、SQL0601N エラーが戻ります。 例 6: リリース更新で新規エレメントを選出する は、新規リリースのデフォルト・スキーマを使用して表を再作成する例を示しています。

または、最新のリリースで導入されるかもしれないどの新しい列または表も追加せずに、既存の表の使用を続けることもできます。 既存の表を更新するには、表を作成する際に使用された登録済み XML スキーマ・ファイルの名前を EVMON_FORMAT_UE_TO_TABLES プロシージャーの xsrobjectname パラメーターとして指定しなければなりません。 例 7: リリース更新で前のリレーショナル表を使用する は、前のリリースのスキーマを使用する例を示しています。

注: 以前に EVMON_FORMAT_UE_TO_TABLES によって作成されたリレーショナル表にあったデータを保持しながら、フィックスパックまたは新規リリースで導入された新しい列または表を選出することはできません。 どの新しい列を取り出す場合でも、表の再作成が必要です。

部分的なイベント

部分的な (不完全な) イベントが UE 表に存在する場合、EVMON_FORMAT_UE_TO_TABLES を実行すると、メッセージ (SQL443N) が戻されます。 不完全なイベントは、イベント・レコード全体を UE 表に挿入できるようになる前にエージェントが処理を完了すると発生することがあります。 この状況は、特にパーティション・データベース環境で、ロッキングが関係する場合に発生する可能性があります。 例えば、LOCKWAIT しきい値を超えたとき、ロックの保有者に関する詳細が UE 表に書き込まれます。 しかし、同じオブジェクトに対するロックを待機しているエージェントに関する詳細は、ロックがタイムアウトになるか、またはウェイターがロックを獲得するまで取り込まれません。 ロックを待機しているエージェントがその情報を書き込む前に EVMON_FORMAT_UE_TO_TABLES が実行された場合、ロックに関する情報の一部しか UE 表に存在しない可能性があります。

不完全なイベントに関する詳細を参照するには、EVMON_FORMAT_UE_TO_XML に LOG_PARTIAL_EVENTS オプションを付けて実行します。

例

• 例 1: デフォルト・パラメーターを使用する
• 例 2: 異なるスキーマ下の表の使用を試みる
• 例 3: 異なるスキーマ下の表の使用を試みる
• 例 4: RECREATE_FORCE オプションを使用する
• 例 5: フィックスパック更新に含まれる新規エレメントを取り出す
• 例 6: リリース更新に含まれる新規エレメントを取り出す
• 例 7: リリース更新でそれまでのリレーショナル表を使用する
• 例 8: UPGRADE_TABLES および PRUNE_UE_TABLE オプションを使用する

例 1: デフォルト・パラメーターを使用する

Paul という名前のユーザーが、デフォルト・パラメーターを使用して、このプロシージャーを呼び出します。 サービス・クラス STUDENTS に含まれるすべてのイベントをリレーショナル表に挿入するためです。

EVMON_FORMAT_UE_TO_TABLES ( 
  'UOW', NULL, NULL, NULL, NULL, NULL, NULL, -1,
  'SELECT * FROM UOWUE
     WHERE service_subclass_name = 'STUDENTS'
     ORDER BY event_id, event_timestamp')

例 2: 異なるスキーマ下の表の使用を試みる

前の例に続いて、Dave という名前のユーザーがこのストアード・プロシージャーを呼び出します。 tabschema パラメーターが Paul に設定されています。

EVMON_FORMAT_UE_TO_TABLES ( 
  'UOW', NULL, NULL, NULL, 'Paul', NULL, NULL, -1,
  'SELECT * FROM UOWTBLE 
     ORDER BY event_timestamp')

例 3: 異なるスキーマ下の表の使用を試みる

前の例に続いて、Greg という名前のユーザーがこのストアード・プロシージャーを呼び出します。 入力パラメーター xsrschema が Paul に設定されています。

EVMON_FORMAT_UE_TO_TABLES ( 
  'UOW', 'Paul', NULL, NULL, NULL, NULL, NULL, -1,
  'SELECT * FROM UOWTBL 
     ORDER BY event_timestamp')

例 4: RECREATE_FORCE オプションを使用する

前の例に続いて、Paul が表を再び作成しますが、今度は表スペース MYSPACE に作成します。 Paul は RECREATE_FORCE オプションと tbsp_name パラメーターを指定してプロシージャーを呼び出します。

EVMON_FORMAT_UE_TO_TABLES ( 
  'UOW', NULL, NULL, NULL, NULL, 'MYSPACE', 'RECREATE_FORCE', -1,
  'SELECT * FROM UOWTBL 
     ORDER BY event_timestamp')

例 5: フィックスパック更新に含まれる新規エレメントを取り出す

例 6: リリース更新に含まれる新規エレメントを取り出す

Paul は新規製品リリースにアップグレードしており、イベント・モニターの XML スキーマ・ファイルに含まれる新規変更を取り出したいと考えています。 Paul は RECREATE_ONERROR オプションを指定してプロシージャーを呼び出します。

EVMON_FORMAT_UE_TO_TABLES ( 
  'LOCKING', NULL, NULL, NULL, NULL, NULL, 'RECREATE_ONERROR', -1,
  'SELECT * FROM LOCK 
     ORDER BY event_timestamp')

例 7: リリース更新でそれまでのリレーショナル表を使用する

Greg は新しい製品リリースにアップグレードしました。 Greg は、前のリリースからの xsrobjectname 値を指定して、プロシージャーを呼び出します。

EVMON_FORMAT_UE_TO_TABLES ( 
  'LOCKING', NULL, 'EVMON_LOCKING_SCHEMA_SQL11010', NULL, NULL, NULL, NULL, -1,
  'SELECT * FROM LOCK 
     ORDER BY event_timestamp')

例 8: UPGRADE_TABLES および PRUNE_UE_TABLE オプションを使用する

Paul は、UOWTABLE という UE 表に出力を書き込む作業単位イベント・モニターを 10.5 で作成しました。 その後、 11.5 にアップグレードし、 EVMON_FORMAT_UE_TO_TABLES によって前のリリースで作成されたリレーショナル表を、 UPGRADE_TABLES オプションを使用してアップグレードする必要があります。 このアップグレードは、新しいデータを処理する前に行います。 さらに、UOWTABLE のレコードが処理された後、PRUNE_UE_TABLE オプションを使ってそれらのレコードを削除したいと考えています。

EVMON_FORMAT_UE_TO_TABLES (
'UOW', NULL, 'EVMON_UOW_SCHEMA_SQL10050', NULL, NULL, NULL,
'UPGRADE_TABLES;PRUNE_UE_TABLE', -1,
'SELECT * FROM UOWTABLE
ORDER BY event_timestamp')

戻される情報