DBMS_RULE, 2 of 2

Summary of DBMS_RULE Subprograms

Table 63-1 DBMS_RULE Subprogram

Subprogram	Description
"EVALUATE Procedure"	Evaluates the rules in the specified rule set that use the evaluation context specified

EVALUATE Procedure

Evaluates the rules in the specified rule set that use the evaluation context specified.

Note:

Rules in the rule set that use an evaluation context different from the one specified are not considered for evaluation.

The rules in the rule set are evaluated using the data specified for table_values, column_values, variable_values, and attribute_values. These values must refer to tables and variables in the specified evaluation context. Otherwise, they are ignored.

The caller may specify, using stop_on_first_hit, if evaluation must stop as soon as the first TRUE rule or the first MAYBE rule (if there are no TRUE rules) is found.

The caller may also specify, using simple_rules_only, if only rules that are simple enough to be evaluated fast (which means without SQL) should be considered for evaluation. This makes evaluation faster, but causes rules that cannot be evaluated without SQL to be returned as MAYBE rules.

Partial evaluation is supported. The EVALUATE procedure can be called with data for only some of the tables, columns, variables, or attributes. In such a case, rules that cannot be evaluated because of a lack of data are returned as MAYBE rules, unless they can be determined to be TRUE or FALSE based on the values of one or more simple expressions within the rule. For example, given a value of 1 for attribute "a.b" of variable "x", a rule with the following rule condition can be returned as TRUE, without a value for table "tab":

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

The results of an evaluation are the following:

TRUE rules, which is the list of rules that evaluate to TRUE based on the given data. These rules are returned in the OUT parameter true_rules.
MAYBE rules, which is the list of rules that could not be evaluated for one of the following reasons:
- The rule refers to data that was unavailable. For example, a variable attribute "x.a.b" is specified, but no value is specified for the variable "x", the attribute "a", or the attribute "a.b".
- The rule is not simple enough to be evaluated fast (without SQL) and simple_rules_only is specified as TRUE.
MAYBE rules are returned in the OUT parameter maybe_rules.

To run this procedure, a user must meet at least one of the following requirements:

Have EXECUTE_ON_RULE_SET privilege on the rule set
Have EXECUTE_ANY_RULE_SET system privilege
Be the rule set owner

Note:
The rules engine does not invoke any actions. An action context can be returned with each returned rule, but the client of the rules engine must invoke any necessary actions.

See Also:
Chapter 109, "Rule Types" for more information about the types used with the DBMS_RULE package

Syntax

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,
  variable_values      IN   SYS.RE$VARIABLE_VALUE_LIST   DEFAULT NULL,
  attribute_values     IN   SYS.RE$ATTRIBUTE_VALUE_LIST,
  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);

Note:

This procedure is overloaded. One version of this procedure has the column_values and attribute_values parameters, and the other does not.

Parameters

Table 63-2 EVALUATE Procedure Parameters (Page 1 of 2)

Parameter	Description
`rule_set_name`	Name of the rule set in the form `[``schema_name``.]``rule_set_name`. For example, to evaluate all of the rules in a rule set named `hr_rules` in the `hr` schema, enter `hr.hr_rules` for this parameter. If the schema is not specified, then the schema of the current user is used.
`evaluation_context`	An evaluation context name in the form `[``schema_name``.]``evaluation_context_name`. If the schema is not specified, then the name of the current user is used. Only rules that use the specified evaluation context are evaluated.
`event_context`	A list of name-value pairs that identify events that cause evaluation
`table_values`	Contains the data for table rows using the table aliases specified when the evaluation context was created
`column_values`	Contains the partial data for table rows. It must not contain column values for tables, whose values are already specified in `table_values`.
`variable_values`	A list containing the data for variables. The only way for an explicit variable value to be known is to specify its value in this list. If an implicit variable value is not specified in the list, then the function used to obtain the value of the implicit variable is invoked. If an implicit variable value is specified in the list, then this value is used and the function is not invoked.
`attribute_values`	Contains the partial data for variables. It must not contain attribute values for variables whose values are already specified in `variable_values`.
`stop_on_first_hit`	If `TRUE`, then the rules engine stops evaluation as soon as it finds a `TRUE` rule. If `TRUE` and there are no `TRUE` rules, then the rules engine stops evaluation as soon as it finds a rule that may evaluate to `TRUE` given more data. If `FALSE`, then the rules engine continues to evaluate rules even after it finds a `TRUE` rule.
`simple_rules_only`	If `TRUE`, then only those rules that are simple enough to be evaluated fast (without issuing SQL) are considered for evaluation. If `FALSE`, then evaluates all rules.
`true_rules`	Receives the output of the `EVALUATE` procedure into a varray of `RE$RULE_HIT_LIST` type. If no rules evaluate to `TRUE`, then `true_rules` is empty. If at least one rule evaluates to `TRUE` and `stop_on_first_hit` is `TRUE`, then `true_rules` contains one rule that evaluates to `TRUE`. If `stop_on_first_hit` is `FALSE`, then `true_rules` contains all rules that evaluate to `TRUE`.
`maybe_rules`	If all rules can be evaluated completely, without requiring any additional data, then `maybe_rules` is empty. If `stop_on_first_hit` is `TRUE`, then if there is at least one rule that may evaluate to `TRUE` given more data, and no rules evaluate to `TRUE`, then `maybe_rules` contains one rule that may evaluate to `TRUE`. If `stop_on_first_hit` is `FALSE`, then `maybe_rules` contains all rules that may evaluate to `TRUE` given more data.