DBMS_RULE

140 DBMS_RULE

DBMS_RULEパッケージには、指定されたイベントに対してルール・セットの評価を可能にするサブプログラムが含まれています。

この章のトピックは、次のとおりです:

140.1 DBMS_RULEの概要

このパッケージには、指定されたイベントに対してルール・セットの評価を可能にするサブプログラムが含まれています。

参照:

DBMS_RULEパッケージで使用されるルール・タイプの詳細は、「ルール・タイプ」を参照してください。
このパッケージおよびルールの詳細は、「DBMS_RULE_ADM」および『Oracle Streams概要および管理』を参照してください。

140.2 DBMS_RULEのセキュリティ・モデル

PUBLICには、このパッケージのEXECUTE権限が付与されます。

参照:

ユーザー・グループPUBLICの詳細は、『Oracle Databaseセキュリティ・ガイド』を参照してください。

140.3 DBMS_RULEサブプログラムの要約

この表は、DBMS_RULEサブプログラムを示し、簡単に説明しています。

表140-1 DBMS_RULEパッケージのサブプログラム

サブプログラム	説明
CLOSE_ITERATORプロシージャ	オープンしているイテレータをクローズします。
EVALUATEプロシージャ	指定した評価コンテキストを使用している指定ルール・セット内のルールを評価します。
EVALUATE_EXPRESSIONプロシージャ	セッションのログイン・ユーザーとして式を評価します。
EVALUATE_EXPRESSION_ITERATORプロシージャ	関連するデータポイントを検索し、`re$value_list`を評価インタフェースに渡します。
EVALUATE_RULEプロシージャ	ルールに定義された条件を評価します。
EVALUATE_RULE_ITERATORプロシージャ	関連するデータポイントを検索し、`re$value_list`を評価インタフェースに渡します。
GET_NEXT_HITファンクション	`TRUE`に評価された次のルールをTRUEルールのイテレータから戻します。または、`MAYBE`に評価された次のルールをMAYBEルールのイテレータから戻します。`TRUE`に評価されたルールおよび`MAYBE`に評価されたルールが両方ともない場合は、`NULL`を戻します。
IS_FASTプロシージャ	式を高速と評価できる場合、`TRUE`を戻します。式を高速と評価できるのは、エンジンで内部SQLを実行する必要がなく、PL/SQLが参照されたときでもPL/SQLレイヤーに移動する必要がない場合です。
GET_NEXT_RESULTファンクション	`result_val_iterator`で指定された式の結果を反復処理します。

140.3.1 CLOSE_ITERATORプロシージャ

このプロシージャは、オープンしているイテレータをクローズします。

構文

DBMS_RULE.CLOSE_ITERATOR(
   iterator  IN  BINARY_INTEGER);

パラメータ

表140-2 CLOSE_ITERATORプロシージャのパラメータ

パラメータ	説明
`iterator`	クローズされるイテレータ。

使用上のノート

このプロシージャには、同じセッションでこのプロシージャより前のDBMS_RULE.EVALUATEコールで戻された、オープン状態のイテレータが必要です。ただし、このプロシージャを実行するユーザーには、評価されるルール・セットに対する権限は必要ありません。

イテレータをクローズすると、そのイテレータに関連するメモリーなどのリソースが解放されます。そのため、不要になったイテレータはクローズすることをお薦めします。

参照:

EVALUATEプロシージャ

140.3.2 EVALUATEプロシージャ

このプロシージャは、指定したイベントに対して指定された評価コンテキストを使用する指定ルール・セット内のルールを評価します。

このプロシージャはオーバーロードされています。true_rulesパラメータおよびmaybe_rulesパラメータは、true_rules_iteratorパラメータおよびmaybe_rules_iteratorパラメータと相互に排他的です。また、true_rulesパラメータとmaybe_rulesパラメータを持つプロシージャにはstop_on_first_hitパラメータがありますが、それ以外のプロシージャにはありません。

構文

DBMS_RULE.EVALUATE(
   rule_set_name          IN     VARCHAR2,
   evaluation_context     IN     VARCHAR2,
   event_context          IN     SYS.RE$NV_LIST               DEFAULT NULL,
   table_values           IN     SYS.RE$TABLE_VALUE_LIST      DEFAULT NULL,
   column_values          IN     SYS.RE$COLUMN_VALUE_LIST     DEFAULT NULL,
   variable_values        IN     SYS.RE$VARIABLE_VALUE_LIST   DEFAULT NULL,
   attribute_values       IN     SYS.RE$ATTRIBUTE_VALUE_LIST  DEFAULT NULL,

  skip_rules           IN   SYS.RE$RULE_NAME_LIST        DEFAULT NULL,

  dop                  IN   NUMBER,

   result_cache           IN     BOOLEAN                      DEFAULT FALSE,
   stop_on_first_hit      IN     BOOLEAN                      DEFAULT FALSE,
   simple_rules_only      IN     BOOLEAN                      DEFAULT FALSE,
   true_rules             OUT    SYS.RE$RULE_HIT_LIST,
   maybe_rules            OUT    SYS.RE$RULE_HIT_LIST);

DBMS_RULE.EVALUATE(
   rule_set_name          IN     VARCHAR2,
   evaluation_context     IN     VARCHAR2,
   event_context          IN     SYS.RE$NV_LIST               DEFAULT NULL,
   table_values           IN     SYS.RE$TABLE_VALUE_LIST      DEFAULT NULL,
   column_values          IN     SYS.RE$COLUMN_VALUE_LIST     DEFAULT NULL,
   variable_values        IN     SYS.RE$VARIABLE_VALUE_LIST   DEFAULT NULL,
   attribute_values       IN     SYS.RE$ATTRIBUTE_VALUE_LIST  DEFAULT NULL,

  skip_rules            IN   SYS.RE$RULE_NAME_LIST        DEFAULT NULL,

  dop                   IN   NUMBER,

   simple_rules_only      IN     BOOLEAN                      DEFAULT FALSE,
   true_rules_iterator    OUT    BINARY_INTEGER,
   maybe_rules_iterator   OUT    BINARY_INTEGER);

パラメータ

表140-3 EVALUATEプロシージャのパラメータ

パラメータ	説明
`rule_set_name`	`[schema_name.]rule_set_name`の形式で指定するルール・セット名。たとえば`hr`スキーマの`hr_rules`という名前のルール・セットにあるルールのすべてを評価するには、このパラメータに`hr.hr_rules`を入力します。スキーマが指定されていない場合は、現在のユーザーのスキーマが使用されます。
`evaluation_context`	`[schema_name.]evaluation_context_name`の形式で指定する、評価コンテキスト名。スキーマが指定されていない場合は、現在のユーザー名が使用されます。評価されるのは、指定した評価コンテキストを使用しているルールのみです。
`event_context`	評価の原因となるイベントを識別する名前/値ペアのリスト。
`table_values`	評価コンテキストの作成時に指定された表の別名を使用した、表の行のデータ。表の別名は、リスト内で一意になるようにしてください。
`column_values`	表の行の部分データが含まれます。値が`table_values`ですでに指定されている表には、列値を指定しないでください。
`variable_values`	変数のデータを含むリスト。明示的な変数値を認識する唯一の方法は、その値をこのリストに指定することです。暗黙的な変数値がリストに指定されていない場合は、暗黙的な変数の値を取得するためのファンクションが起動されます。暗黙的な変数値がリストに指定されている場合は、この値が使用され、ファンクションは起動されません。
`attribute_values`	変数の部分データが含まれます。値が`variable_values`ですでに指定されている変数には、属性値を指定しないでください。
`stop_on_first_hit`	`TRUE`の場合、ルール・エンジンは、`TRUE`ルールを検出次第、評価を停止します。 `TRUE`を指定して、`TRUE`ルールがない場合、ルール・エンジンは、指定データの多くを`TRUE`に評価できるルールが見つかり次第、評価を停止します。 `FALSE`の場合、ルール・エンジンは、`TRUE`ルールの検出後も、ルールの評価を続行します。
`simple_rules_only`	`TRUE`の場合は、高速と評価できる単純な(SQLを使用しない)ルールのみが、評価の対象となります。 `FALSE`の場合は、すべてのルールが評価されます。
`true_rules`	`EVALUATE`プロシージャの出力を`RE$RULE_HIT_LIST`タイプの配列で受け取ります。 `TRUE`に評価されるルールがない場合、`true_rules`は空です。少なくとも1つのルールが`TRUE`に評価され、`stop_on_first_hit`が`TRUE`の場合、`true_rules`には、`TRUE`に評価された1つのルールが含まれます。 `stop_on_first_hit`が`FALSE`の場合、`true_rules`には、`TRUE`に評価されたすべてのルールが含まれます。
`maybe_rules`	すべてのルールが、追加データの必要もなく、完全に評価できる場合、`maybe_rules`は空です。 `stop_on_first_hit`が`TRUE`の状態で、指定データの多くを`TRUE`に評価できるルールが少なくとも1つあり、`TRUE`に評価されるルールがない場合、`maybe_rules`には、`TRUE`に評価できるルールが1つ含まれます。 `stop_on_first_hit`が`FALSE`の場合、`maybe_rules`には、指定データの多くを`TRUE`に評価できるすべてのルールが含まれます。
`true_rules_iterator`	`TRUE`のルールにアクセスするイテレータが含まれます。
`maybe_rules_iterator`	追加データやSQL発行を`TRUE`にできるルールにアクセスするイテレータが含まれます。
`skip_rules`	この評価内でスキップするルールのリスト。
`dop`	並列度。
`result_cache`	`TRUE`の場合、結果キャッシュが作成されます。EVALUATEプロシージャが`true_rules_iterator`または`maybe_rules_iterator`を指定してコールされた場合、`result_cache`は有効になりません。

使用上のノート

ノート:

指定したルールとは異なる評価コンテキストを使用しているルール・セット内のルールは、評価の対象になりません。

ルール・セット内のルールは、table_values、column_values、variable_valuesおよびattribute_valuesに指定されているデータを使用して評価されます。これらの値は、指定した評価コンテキストの表および変数を参照する必要があります。そうでない場合は、エラーが発生します。

コール元は、stop_on_first_hitを使用して、最初のTRUEルールまたは最初のMAYBEルール(TRUEルールがない場合)の検出直後に評価を停止するかどうかを指定できます。

また、コール元は、simple_rules_onlyを使用して、高速と評価できる単純な(SQLを使用しない)ルールのみを評価対象とするかどうかも指定できます。この指定で、評価は高速化されますが、SQLなしでは評価できないルールは、MAYBEルールとして戻されます。

部分評価はサポートされています。EVALUATEプロシージャは、一部の表、列、変数または属性に関するデータによってのみコールできます。この場合、ルール内の1つ以上の単純な式の値に基づいてもTRUEまたはFALSEの判断ができないかぎり、データ不足が原因で評価できないルールはMAYBEルールとして戻されます。たとえば、変数「x」の属性「a.b」に1の値を指定すると、表「tab」の値を指定しなくても、次のルール条件のルールがTRUEで戻ります。

(:x.a.b = 1) or (tab.c > 10)

評価の結果には、次の2種類があります。

TRUEルールで、指定したデータに基づいてTRUEに評価されたルールのリストです。このルールが戻されるのは、TRUEに評価されるすべてのルールを戻すOUTパラメータtrue_rules、またはTRUEに評価されるルールを1回に1つずつ戻すOUTパラメータtrue_rules_iteratorのいずれかです。
MAYBEルール。次の理由の1つのために評価できなかったルールのリストです。
- ルールが使用不可のデータを参照しているため。たとえば、変数の属性"x.a.b"は指定されているが、変数「x」、属性「a」または属性「a.b」には値が指定されていない場合がこれに該当します。
- ルールが、(SQLなしで)高速と評価できるほど単純ではなく、simple_rules_onlyがTRUEに指定されているため。または、部分データを使用できるため。
MAYBEルールが戻されるのは、MAYBEに評価されるすべてのルールを戻すOUTパラメータmaybe_rules、またはMAYBEに評価されるルールを1回に1つずつ戻すOUTパラメータmaybe_rules_iteratorのいずれかです。

コール元は、イベントに対してプロシージャがTRUEおよびMAYBEに評価されるすべてのルールを戻すか、TRUEおよびMAYBEに評価されるルールのイテレータを戻すかを指定できます。TRUEルールのイテレータの場合、クライアントはTRUEに評価される各ルールを1回に1つずつフェッチでき、MAYBEルールのイテレータの場合、クライアントはMAYBEに評価される各ルールを1回に1つずつフェッチできます。

イテレータを使用する場合は、DBMS_RULEパッケージのGET_NEXT_HITファンクションを使用して、TRUEまたはMAYBEに評価される次のルールをイテレータから取得します。イテレータが不要になった場合は、そのイテレータが使用していたメモリーなどのリソースを解放するため、イテレータをクローズすることをお薦めします。次の方法で、イテレータをクローズできます。

DBMS_RULEパッケージのCLOSE_ITERATORプロシージャを、イテレータを指定して実行します。
TRUEまたはMAYBEに評価されるルールがすでに存在しないため、イテレータはNULLを戻します。
イテレータを実行しているセッションが終了します。

DBMS_RULE.EVALUATEプロシージャを実行するユーザーは、次の要件を最低1つ満たす必要があります。

ルール・セットに対するEXECUTE_ON_RULE_SET権限があること。
EXECUTE_ANY_RULE_SETシステム権限があること。
ルール・セットの所有者であること。

ノート:

ルール・エンジンはアクションを開始しません。戻されたルールとともにアクション・コンテキストが戻る場合がありますが、ルール・エンジンのクライアントは、必要なアクションを開始する必要があります。
参照:
- DBMS_RULEパッケージで使用されるルール・タイプの詳細は、「ルール・タイプ」を参照してください。
- GET_NEXT_HITファンクション
- CLOSE_ITERATORプロシージャ

140.3.3 EVALUATE_EXPRESSIONプロシージャ

このプロシージャを使用すると、セッションのログイン・ユーザーとして式を評価できます。

同じ表別名と変数タイプを使用して同一の式を再実行した場合、同じコンパイルされたコンテキストが再利用されます。コンパイルするキャッシュのサイズが固定されている場合、期限切れになる可能性があります。

構文

DBMS_RULE.EVALUATE_EXPRESSION(
   rule_expression         IN         VARCHAR2,
   table_aliases           IN         SYS.RE$TABLE_ALIAS_LIST:= NULL,
   variable_types          IN         SYS.RE$VARIABLE_TYPE_LIST:= NULL,
   table_values            IN         SYS.RE$TABLE_VALUE_LIST:= NULL,
   column_values           IN         SYS.RE$COLUMN_VALUE_LIST:=NULL,
   variable_values         IN         SYS.RE$VARIABLE_VALUE_LIST:=NULL,
   attribute_values        IN         SYS.RE$ATTRIBUTE_VALUE_LIST:=NULL,
   cache                   IN         BOOLEAN DEFAULT FALSE,
   result_val              OUT        BOOLEAN);

パラメータ

表140-4 EVALUATE_EXPRESSIONプロシージャのパラメータ

パラメータ	説明
`rule_expression`	式の文字列が含まれます。
`table_alias`	式の文字列で参照される表の別名が含まれます。
`variable_types`	式で使用される変数のタイプ定義が含まれます。
`table_values`	式の評価に使用される表の行の`ROWID`が含まれます。
`column_values`	式で参照される列の値が含まれます。
`variable_values`	式で参照される変数の値が含まれます。
`attribute_values`	式で参照される属性の値が含まれます。
`cache`	`TRUE`の場合、結果キャッシュが作成されます。
`result_val`	評価の結果。

140.3.4 EVALUATE_EXPRESSION_ITERATORプロシージャ

これは、ユーザーに表示されるインタフェースです。PL/SQLベースのコールバックは非効率的であるため、配列ベースの方法が用意されています。クライアント・プログラムは、関連するデータポイントを検索し、re$value_listを評価インタフェースに渡すと想定されます。式評価エンジンがこのリストを処理し、各データポイント(re$value_list)要素の式を評価します。

構文

DBMS_RULE.EVALUATE_EXPRESSION_ITERATOR(
       rule_expression        IN              varchar2,
       table_aliases          IN              sys.re$table_alias_list:= NULL,
       variable_types         IN              sys.re$variable_type_list:= NULL,
       values                 IN              sys.re$value_list,
       cache                  IN              boolean DEFAULT FALSE,
       result_val_iter_id     OUT             BINARY_INTEGER)

パラメータ

表140-5 EVALUATE_EXPRESSION_ITERATORプロシージャのパラメータ

パラメータ	説明
`rule_expression`	式の文字列が含まれます。
`table_alias`	前述の式の文字列で参照される表の別名。
`variable_types`	式で使用される変数のタイプ定義。
`values`	この評価のデータポイント値のリスト。
`cache`	`TRUE`の場合、結果キャッシュが作成されます。
`result_val_iter_id`	`value`を使用して送信された値の配列の結果のイテレータが含まれます。

140.3.5 EVALUATE_RULEプロシージャ

ルール評価APIでは、CREATE_RULEプロシージャを正しいEVALUATION_CONTEXTで事前にコールしておく必要があります。このAPIは、ルールに定義された条件を評価します。

構文

DBMS_RULE.EVALUATE_RULE( 
  rule_name            IN   VARCHAR2,
  event_context        IN   SYS.RE$NV_LIST               DEFAULT NULL,
  table_values         IN   SYS.RE$TABLE_VALUE_LIST      DEFAULT NULL,
  column_values        IN   SYS.RE$COLUMN_VALUE_LIST     DEFAULT NULL,
  variable_values      IN   SYS.RE$VARIABLE_VALUE_LIST   DEFAULT NULL,
  attribute_values     IN   SYS.RE$ATTRIBUTE_VALUE_LIST  DEFAULT NULL,
  cache                IN   BOOLEAN DEFAULT FALSE,
  result_val           OUT  BOOLEAN);

パラメータ

表140-6 EVALUATE_RULEプロシージャのパラメータ

パラメータ	説明
`rule_name`	`CREATE_RULE`プロシージャを使用して事前に作成されたルールの名前。
`event_context`	評価の原因となるイベントを識別する名前/値ペアのリスト。
`table_values`	式の評価に使用される表の行の`ROWID`。
`column_values`	式で参照される列の値。
`variable_values`	式で参照される変数の値。
`attribute_values`	式で参照される属性の値。
`cache`	`TRUE`の場合、結果キャッシュが作成されます。
`result_val`	評価の結果

140.3.6 EVALUATE_RULE_ITERATORプロシージャ

これは反復インタフェースです。クライアント・プログラムは、関連するデータポイントを検索し、re$value_listを評価インタフェースに渡すと想定されます。

評価エンジンがこのリストを処理し、各データポイント(re$value_list)要素の式を評価します。ユーザーはDBMS_RULE.GET_NEXT_RESULTプロシージャを使用して結果リストを反復処理します。

構文

DBMS_RULE.EVALUATE_RULE_ITERATOR)
  rule_name            IN       VARCHAR2,
  event_context        IN       SYS.RE$NV_LIST DEFAULT NULL,
  values               IN       SYS.RE$VALUE_LIST,
  cache                IN       BOOLEAN DEFAULT FALSE,
  result_val_iter_id   OUT      BINARY_INTEGER);

パラメータ

表140-7 EVALUATE_RULE_ITERATORプロシージャのパラメータ

パラメータ	説明
`rule_name`	`CREATE_RULE`プロシージャを使用して事前に作成されたルールの名前。
`event_context`	評価の原因となるイベントを識別する名前/値ペアのリスト。
`values`	この評価のデータポイント値のリスト。
`cache`	`TRUE`の場合、結果キャッシュが作成されます。
`result_val_iter_id`	`values`を使用して送信された値の配列の結果のイテレータが含まれます。

140.3.7 GET_NEXT_HITファンクション

このファンクションは、TRUEに評価された次のルールをTRUEルールのイテレータから戻し、またはMAYBEに評価された次のルールをMAYBEルールのイテレータから戻します。TRUEまたはMAYBEに評価されるルールがすでに存在しない場合、ファンクションはNULLを戻します。

構文

DBMS_RULE.GET_NEXT_HIT(
   iterator  IN  BINARY_INTEGER)
 RETURN SYS.RE$RULE_HIT;

パラメータ

表140-8 GET_NEXT_HITファンクションのパラメータ

パラメータ	説明
`iterator`	`TRUE`または`MAYBE`に評価されたルールが取得されるイテレータ。

使用上のノート

イテレータは、NULLを戻すと自動的にクローズします。オープンしているイテレータが不要になった場合は、DBMS_RULEパッケージのCLOSE_ITERATORプロシージャを使用してクローズしてください。

ノート:

イテレータを戻したDBMS_RULE.EVALUATEプロシージャをコールした後で、評価されるルール・セットが変更された場合、このファンクションを使用するとエラーになります。ルール・セットの変更には、ルール・セットへのルールの追加、ルール・セット内の既存ルールの変更、ルール・セットからのルールの削除、ルール・セットの削除などがあります。

参照:

DBMS_RULEパッケージで使用されるルール・タイプの詳細は、「ルール・タイプ」を参照してください。
EVALUATEプロシージャ
CLOSE_ITERATORプロシージャ

140.3.8 GET_NEXT_RESULTファンクション

このファンクションは、RESULT_VAL_ITERATORで指定された式の結果を反復処理します。TRUEまたはFALSEに評価される式をイテレータで戻します。

構文

DBMS_RULE.GET_NEXT_RESULT (
 result_val_iterator_id    IN   BINARY_INTEGER)
 RETURN  BOOLEAN;

パラメータ

表140-9 GET_NEXT_RESULTファンクションのパラメータ

パラメータ	説明
`result_val_iterator_id`	`EVALUATE_EXPRESSION_ITERATOR`から戻されたイテレータ

140.3.9 IS_FASTプロシージャ

このプロシージャは、ルールの式または独立した式について、高速と評価できる場合はTRUEを戻します。式を高速と評価できるのは、エンジンで内部SQLを実行する必要がなく、PL/SQLが参照されたときでもPL/SQLレイヤーに移動する必要がない場合です。

構文

DBMS_RULE.IS_FAST(
   expression            IN       VARCHAR2,
   table_aliases         IN       SYS.RE$TABLE_ALIAS_LIST:= NULL,
   variable_types        IN       SYS.RE$VARIABLE_TYPE_LIST:= NULL,
   result_val            OUT      BOOLEAN);

パラメータ

表140-10 IS_FASTプロシージャのパラメータ

パラメータ	説明
`expression`	チェックする式。
`table_aliases`	前述の式の文字列で参照される表の別名。
`variable_types`	式で使用される変数のタイプ定義。
`result_val`	式が高速と評価できる場合