140 DBMS_RULE

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

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

140.1 DBMS_RULEの概要

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

参照:

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コールで戻された、オープン状態のイテレータが必要です。ただし、このプロシージャを実行するユーザーには、評価されるルール・セットに対する権限は必要ありません。

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

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_hitTRUEの場合、true_rulesには、TRUEに評価された1つのルールが含まれます。

stop_on_first_hitFALSEの場合、true_rulesには、TRUEに評価されたすべてのルールが含まれます。

maybe_rules

すべてのルールが、追加データの必要もなく、完全に評価できる場合、maybe_rulesは空です。

stop_on_first_hitTRUEの状態で、指定データの多くをTRUEに評価できるルールが少なくとも1つあり、TRUEに評価されるルールがない場合、maybe_rulesには、TRUEに評価できるルールが1つ含まれます。

stop_on_first_hitFALSEの場合、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_valuescolumn_valuesvariable_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_onlyTRUEに指定されているため。または、部分データを使用できるため。

    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システム権限があること。

  • ルール・セットの所有者であること。

    注意:

    ルール・エンジンはアクションを開始しません。戻されたルールとともにアクション・コンテキストが戻る場合がありますが、ルール・エンジンのクライアントは、必要なアクションを開始する必要があります。

    参照:

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に評価されたルールが取得されるイテレータ。

使用上の注意

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

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

注意:

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

参照:

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

式が高速と評価できる場合