88 DBMS_RLMGR

Summary of Rules Manager Subprograms

Table 88-1 describes the subprograms in the DBMS_RLMGR package.

All the values and names passed to the procedures defined in the DBMS_RLMGR package are case insensitive unless otherwise mentioned. In order to preserve the case, double quotation marks should be used around the values.

---

ADD_ELEMENTARY_ATTRIBUTE Procedures

This procedure adds the specified attribute to an event structure, which is also the Expression Filter attribute set. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definitions.

Syntax

Adds the specified elementary attribute to the attribute set:

DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
              event_struct   IN   VARCHAR2,
              attr_name      IN   VARCHAR2,
              attr_type      IN   VARCHAR2,
              attr_defvl     IN   VARCHAR2 default NULL);
 

Identifies the elementary attributes that are table aliases and adds them to the event structure:

DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
              event_struct   IN   VARCHAR2,
              attr_name      IN   VARCHAR2,
              tab_alias      IN   rlm$table_alias);

Parameters

Usage Notes

• This procedure adds an elementary attribute to an event structure. The event structure is internally managed as the Expression Filter attribute set. If the event structure was originally created from an existing object type, then additional attributes cannot be added.

  Elementary attributes cannot be added to an attribute set that is already assigned to a column storing expressions, which is equivalent to an event structure that is used for a rule class.

• One or more, or all elementary attributes in an attribute set can be table aliases. If an elementary attribute is a table alias, then the value assigned to the elementary attribute is a ROWID from the corresponding table. An attribute set with one or more table alias attributes cannot be created from an existing object type. For more information about table aliases, see Appendix A in Oracle Database Application Developer's Guide - Rules Manager and Expression Filter.

• Elementary attributes cannot be added to an attribute set that is already assigned to a column storing expressions.

• See "Defining Attribute Sets" in Oracle Database Application Developer's Guide - Rules Manager and Expression Filter for more information about adding elementary attributes.

• Related views: USER_EXPFIL_ATTRIBUTE_SETS and USER_EXPFIL_ATTRIBUTES.

Examples

The following commands add two elementary attributes to an attribute set:

BEGIN
  DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
                               event_struct  => 'HRAttrSet',
                               attr_name => 'HRREP',
                               attr_type => 'VARCHAR2(30)');
  DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
                               event_struct  => 'HRAttrSet',
                               attr_name => 'DEPT',
                               tab_alias => exf$table_alias('DEPT'));
END;

---

ADD_EVENT Procedures

This procedure adds a primitive event to a rule class in an active rule session. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definitions.

Syntax

Adds a string representation of the primitive event instance to a rule class:

DBMS_RLMGR.ADD_EVENT (
   rule_class      IN VARCHAR2,
   event_inst      IN VARCHAR2,
   event_type      IN VARCHAR2 default null);

Adds an AnyData representation of the primitive event instance to a rule class:

DBMS_RLMGR.ADD_EVENT (
   rule_class      IN VARCHAR2,
   event_inst      IN sys.AnyData);

Parameters

Usage Notes

• This procedure is used to add a primitive or a simple event to a rule class within an active rule session. By default, a rule session is the same as the database session. Optionally, multiple (sequential) rule sessions can be started within a database session by using the RESET_SESSION or PROCESS_RULES procedures.

• When the rule class is configured for simple events (consisting of only one primitive event structure), the event_type argument for the ADD_EVENT procedure can be ignored. Also, when the AnyData format of the event instance is passed, the event type information is embedded in the AnyData instance. In all other cases, the name of the primitive event structure being added to the rule class should be assigned to the event_type argument.

• For a valid event instance, the ADD_EVENT procedure processes the rules in the rule class and captures the results in the rule class results view (configured at the time of rule class creation). These results are preserved until the end of the rule session.When schema extended name is used for the rule class, you should have PROCESS RULES privilege on the rule class. See the GRANT_PRIVILEGE Procedure for additional information. The value specified for the event_type argument is always resolved in the rule class owner's schema and should not use schema extended names. When a composite event structure is configured with a table alias primitive event type, the name of the corresponding table should be assigned to the event_type argument.

Examples

The following commands add two events to the CompTravelPromo rule class that is configured for two types of primitive events (AddFlight and AddRentalCar).

BEGIN
 DBMS_RLMGR.ADD_EVENT(rule_class => 'CompTravelPromo',
                     event_inst =>
                        AddFlight.getVarchar(987, 'Abcair', 'Boston',
                                         'Orlando', '01-APR-2003', '08-APR-2003'),
                     event_type => 'AddFlight');

DBMS_RLMGR.ADD_EVENT(rule_class => 'Scott.CompTravelPromo',
                     event_inst =>
                        AnyData.convertObject(
                                        AddRentalCar(987, 'Luxury', '03-APR-2003',
                                                     '08-APR-2003', NULL)));
END;

---

ADD_FUNCTIONS Procedure

This procedure adds a user-defined function, package, or type representing a set of functions to the event structure, which is also the Expression Filter attribute set.

Syntax

DBMS_RLMGR.ADD_FUNCTIONS (
   event_struct   IN   VARCHAR2,
   funcs_name     IN   VARCHAR2);

Parameters

Usage Notes

• By default, an attribute set implicitly allows references to all Oracle supplied SQL functions for use in the rule conditions. If the expression set refers to a user-defined function, the expression set must be explicitly added to the attribute set.

• The ADD_FUNCTIONS procedure adds a user-defined function or a package (or type) representing a set of functions to the attribute set. Any new or modified expressions are validated using this list.

• The function or the package name can be specified with a schema extension. If a function name is specified without a schema extension, only such references in the rule condition are considered valid. The conditional expression can be restricted to use a synonym to a function or a package by adding the corresponding synonym to the attribute set. This preserves the portability of the expression set to other schemas.

• See "Defining Attribute Sets" in Oracle Database Application Developer's Guide - Rules Manager and Expression Filter for more information about adding functions to an attribute set.

• Related views: USER_EXPFIL_ATTRIBUTE_SETS and USER_EXPFIL_ASET_FUNCTIONS

Examples

The following commands add two functions to the attribute set:

BEGIN 
  DBMS_RLMGR.ADD_FUNCTIONS (attr_set   => 'Car4Sale', 
                             funcs_name => 'HorsePower');
  DBMS_RLMGR.ADD_FUNCTIONS (attr_set   => 'Car4Sale', 
                             funcs_name => 'Scott.CrashTestRating');
END;

---

ADD_RULE Procedure

This procedure adds new rules to a rule class.

Syntax

DBMS_RLMGR.ADD_RULE (
   rule_class      IN  VARCHAR2,
   rule_id         IN  VARCHAR2,
   rule_cond       IN  VARCHAR2,
   actprf_nml      IN  VARCHAR2 DEFAULT NULL,
   actprf_vall     IN  VARCHAR2 DEFAULT NULL);

Parameters

Usage Notes

• This procedure is used to add new rules to the rule class. The rule condition passed to the ADD_RULE procedure is validated using the event structure associated with the rule class. The action preferences names list is a subset of action preference categories configured during rule class creation.

• When schema extended name is used for the rule class, you should have ADD RULE privilege on the rule class. See the GRANT_PRIVILEGE Procedure for more information.

• Alternately, the owner of the rule class can add the rules using SQL INSERT statement on the rule class table (that shares the same name as the rule class). Note that the owner of the rule class can also grant direct DML privileges on the rule class table to other users.

  Note:

  The AUTOCOMMIT property of the rule class is ignored if the new rules are added using the SQL INSERT statement instead of the ADD_RULE procedure.

• See the CREATE_RULE_CLASS Procedure procedure for the structure of the rule class table.

Examples

The following command adds a rule to the rule class.

BEGIN
DBMS_RLMGR.ADD_RULE (
           rule_class => 'CompTravelPromo',
           rule_id => 'AB_AV_FL',
           rule_cond =>
             '<condition>
                 <and join="Flt.CustId = Car.CustId">
                    <object name="Flt">
                      Airline=''Abcair'' and ToCity=''Orlando''
                    </object>
                    <object name="Car">
                      CarType = ''Luxury''
                    </object>
                  </and>
               </condition>' ,
             actprf_nml => 'PromoType, OfferedBy',
             actprf_vall => '''RentalCar'', ''Acar''');
END;

With proper privileges, the following SQL INSERT statement can be used to add the rule to the rule class.

INSERT INTO CompTravelPromo (rlm$ruleid, rlm$rulecond, PromoType, OfferedBy)
  VALUES ('AB_AV_FL',
          '<condition>
             <and join="Flt.CustId = Car.CustId">
               <object name="Flt">
                   Airline=''Abcair'' and ToCity=''Orlando''
               </object>
               <object name="Car">
                   CarType = ''Luxury''
               </object>
             </and>
           </condition>',
          'RentalCar','Acar');

---

CONSUME_EVENT Function

This function consumes an event and prepares the corresponding rule for action execution. This is required only when the action (or rule execution) is carried by the user's application and not in the callback.

Syntax

DBMS_RLMGR.CONSUME_EVENT (
   rule_class       IN VARCHAR2,
   event_ident      IN VARCHAR2) 
 RETURN NUMBER;

Parameters

Returns

The function returns:

• 1 -- If the event is successfully consumed.

• 0 -- If the event is expired (owing to duration policy) or consumed by another session prior to this call.

Usage Notes

• When an EXCLUSIVE consumption policy is set for the events in a rule class, an event must be deleted from the system immediately after the rule it matched is executed (action is executed). When the rule action is carried in the rule class callback procedure by calling the PROCESS_RULES procedure, the rule manager automatically handles the consumption of the events. However, when you request the results from matching events with rules in a rule class results view using the ADD_EVENT procedure, you should take appropriate action to indicate the exact rule-event combination that is to be used for rule execution. The CONSUME_EVENT procedure performs the required housekeeping services when the unique identifier for the event used in a rule execution is passed in.

• Since there could be a time lag between fetching the rule class matching results and the execution of the user initiated action, the application should execute the action only if the CONSUME_EVENT call succeeds in consuming the event. This avoids any race condition with parallel sessions trying to consume the same events. When the event is successfully consumed, this call returns 1. In all other cases, it returns 0. A return value of 0 implies that the event is already consumed by another session and hence it is not available for this session.

• The CONSUME_EVENT procedure deletes the events configured with EXCLUSIVE consumption policy and does nothing for events configured for 4 consumption policy.

• Unlike the EXCLUSIVE and SHARED consumption policies, which are determined at the rule class level, a RULE consumption policy can be used to determine the consumption of an event on a rule by rule basis. That is a subset of the rules in a rule class may be configured such that when they are matched, the event is deleted from the system. At the same time the other set of rules could leave the event in the system even after executing the corresponding action. In this scenario, the action callback procedure implemented by the application developer can call CONSUME_EVENT function (with appropriate arguments) to conditionally consume the event for certain rules. Also see the use of CONSUME_PRIM_EVENTS Function for rule classes configured for RULE consumption policy

Examples

The following commands identify an event that is used for a rule execution and consumes it using its identifier.

var eventid VARCHAR(40);
var evtcnsmd NUMBER;

BEGIN
  SELECT rlm$eventid INTO :eventid FROM MatchingPromos WHERE rownum < 2;

  -- carry the required action for a rule matched by the above event --
  :evtcnsmd := DBMS_RLMGR.CONSUME_EVENT(rule_class  => 'TravelPromotion',
                                        event_ident => :eventid);
END;

---

CONSUME_PRIM_EVENTS Function

This function consumes a set of primitive events with all or nothing semantics in the case of a rule class configured with RULE based consumption policy.

Syntax

DBMS_RLMGR.CONSUME_PRIM_EVENTS (
   rule_class       IN VARCHAR2,
   event_idents     IN RLM$EVENTIDS) 
 RETURN NUMBER;

Parameters

Returns

The function returns:

• 1 -- If all the events, the identifiers for which are passed in, are successfully consumed.

• 0 -- If one or more primitive event could not be consumed.

Usage Notes

When the rule class is configured for RULE based consumption policy, the CONSUME_PRIM_EVENTS function can be used to consume one or more primitive events that constitute a composite event. This operation will succeed only when all the events passed in are still valid and are available for consumption. Any user initiated action should be implemented after checking the return value of the CONSUME_PRIM_EVENTS call.

Examples

The following commands show the body of the action callback procedure for a rule class configured for RULE consumption policy. This demonstrates the use of CONSUME_PRIM_EVENTS procedure to consume the events before executing the action for the matched rules.

create or replace procedure PromoAction (
      Flt        AddFlight, 
      Flt_EvtId  ROWID,    --- rowid for the flight primitive event
      Car        AddRentalCar, 
      Car_EvtId  ROWID, 
      rlm$rule   TravelPromotions%ROWTYPE) is 
  evtcnsmd   NUMBER; 
BEGIN
  evtcnsmd := DBMS_RLMGR.CONSUME_PRIM_EVENTS(
                    rule_class   => 'TravelPromotions',
                    event_idents => RLM$EVENTIDS(Flt_EvtId, Car_EvtId));

  if (evtcnsmd = 1) then 
    -- consume operation was successful; perform the action ---
    OfferPromotion (Flt.CustId, rlm$rule.PromoType, rlm$rule.OfferedBy);
  end if;
END;

---

CREATE_EVENT_STRUCTURE Procedure

This procedure creates an event structure.

Syntax

DBMS_RLMGR.CREATE_EVENT_STRUCTURE  (
   event_struct  IN  VARCHAR2);

Parameters

Usage Notes

This procedure creates a dummy the event structure in the current schema. One or more attributes can be added to this event structure using the ADD_ELEMENTARY_ATTRIBUTE procedure.

Examples

The following command creates the event structure.

BEGIN
  DBMS_RLMGR.CREATE_EVENT_STRUCT(event_struct => 'AddFlight');
END;

---

CREATE_RULE_CLASS Procedure

This procedure creates a rule class.

Syntax

DBMS_RLMGR.CREATE_RULE_CLASS  (
   rule_class      IN  VARCHAR2,
   event_struct    IN  VARCHAR2,
   action_cbk      IN  VARCHAR2,
   actprf_spec     IN  VARCHAR2  default null,
   rslt_viewnm     IN  VARCHAR2  default null,
   rlcls_prop      IN  VARCHAR2  default <simple/>);

Parameters

Usage Notes

• For successful creation of a rule class, you should have sufficient privileges to create views, object types, tables, packages, and procedures.

• This command creates the rule class and its dependent objects in the user's schema. For this operation to succeed the name specified for the event structure should refer to an existing object type or an Expression Filter attribute set in the user's schema. When an object type is used for an event structure, the CREATE_RULE_CLASS procedure implicitly creates an attribute set for the object type. In the case of a rule class configured for composite events, the previous procedure also creates attribute sets for the object types that are directly embedded in the event structure's object type (or the attribute set). A maximum of 32 embedded objects (and/or table aliases) can be specified with an event structure that is used for a composite rule class. The types of dependent objects created with this procedure and their structure depend on the properties of the rule class and its event structure. The minimum set of dependent objects created for a rule class is as follows:

  • Rule class table – A rule class table that shares the name of the rule class is created in the user's schema to store the rule definitions (rule identifiers, rule conditions, rule descriptions, and action preferences). This table implicitly has three columns, rlm$ruleid, rlm$rulecond, and rlm$ruledesc to store the rule identifiers, rule conditions, and rule descriptions respectively. In addition to these three columns, the rule class table has few columns according to the rule classes' access preference specification. For example, if a TravelPromotion rule class uses 'PromoType VARCHAR(20), OfferedBy VARCHAR(20)' as its access preference specification (assigned to actpref_spec argument), the rule class table is created with the following structure.

    TABLE TravelPromotion (
          rlm$ruleid VARCHAR(100),     -- rule identifier column --
          PromoType VARCHAR(20),       -- access preference 1 --
          OfferedBy VARCHAR(20),       -- access preference 2 --
          rlm$rulecond VARCHAR(4000),  -- rule condition –-
          rlm$ruledesc VARCHAR(1000)); -- rule description --
    
    

    The rule class table structure varies from one rule class to another based on the exact list of action preference categories specified for the rule class.

  • Action Callback Procedure – The skeleton for the action callback procedure with the given name is created in the user's schema and it is associated with the rule class. During rule evaluation, the callback procedure is called for each matching rule and event. You should implement the body of the action callback procedure to perform the appropriate action for each rule. The exact action for a rule can be determined based on the event that matched the rule and rule definition along with its action preferences. This information is passed to the action callback procedure through its arguments. Hence, the argument list for the action callback procedure depends on the event structure associated with the rule class and the rule class itself.

    In the case of a rule class configured for simple events (<simple/> assigned to the properties of the rule class), the event that matches a rule is passed through a rlm$event argument that is declared to be of the same type as the event structure. Additionally, the rule definitions are passed to the action callback procedure using an rlm$rule argument that is declared as ROWTYPE of the corresponding rule class table. For example, the structure of the PromoAction action callback procedure created for a TravelPromotion rule class configured for a simple (non-composite) AddFlight event structure is as follows:

    PROCEDURE PromoAction (rlm$event AddFlight,
                           rlm$rule TravlePromotion%ROWTYPE);
    
    

    In the case of a rule class created for composite events (<composite/> assigned to the properties of the rule class), the action callback procedure is created to pass each primitive event as a separate argument. For example, the CompPromoAction action callback procedure created for a rule class CompTravelPromo configured for a composite event with AddFlight and AddRentalCar primitive events are shown as follows:

    -- composite event structure --
    TYPE TSCompEvent (Flt AddFlight,
                      Car AddRentalCar);
    -- corresponding action callback procedure --
    PROCEDURE PromoAction (Flt AddFlight,
                           Car AddRentalCar,
                           rlm$rule CompTravelPromo%ROWTYPE)
    
    

  • Rule class results view – A view to display the results from matching some events with rules is created in the same schema as the rule class. By default, this view is created with a system-generated name. Optionally, the rule class creator can specify a name for this view with the rlst_viewnm argument of the CREATE_RULE_CLASS procedure. When the events are added to the rule manager within a rule session using the ADD_EVENT procedure, the list of matching events and rules are displayed in the rule class results view.

    The structure of the view defined for the rule class results depends on the event structure and the action preferences configured with the rule class. Minimally, the view has three columns to display the system generated event identifier (rlm$evenetid), the identifier of the rule it matches (rlm$ruleid), and the rule condition (rlm$rulecond). Additionally, it has columns to display the event information and the rule action preferences.

    In the case of a rule class configured for simple events, the event information is displayed as rlm$event that is declared to be of the event structure type. So, a MatchingPromos view created for the TravelPromotion rule class configured for a simple AddFlight event structure is as follows:

    VIEW MatchingPromos (
        rlm$eventid ROWID,
        rlm$event AddFlight,
        rlm$ruleid VARCHAR(100),
        PromoType VARCHAR(30), -- action preference 1 --
        OffredBy VARCHAR(30), -- action preference 2 --
        rlm$rulecond VARCHAR(4000),
        rlm$ruledesc VARCHAR(1000)
    );
    
    

    In the case of a rule class configured for composite events, the primitive events matching a rule are displayed separately using corresponding columns. For the above CompTravelPromo rule class, a MatchingCompPromos view is created with the following structure.

    VIEW MatchingCompPromos (
        rlm$eventid ROWID,
        Flt AddFlight,
        Car AddRentalCar,
        rlm$ruleid VARCHAR(100),
        PromoType VARCHAR(30),   -- action preference 1 --
        OffredBy VARCHAR(30),    -- action preference 2 --
        rlm$rulecond VARCHAR(4000),
        rlm$ruledesc VARCHAR(1000)
    );
    
    

    The values from the rlm$eventid column are used to enforce rule class consumption policies when the corresponding rule is executed. See the CONSUME_EVENT Function procedure for more information.

Examples

The following commands create a rule class for simple events (of AddFlight type).

CREATE or REPLACE TYPE AddFlight AS OBJECT (
                  CustId NUMBER,
                  Airline VARCHAR(20),
                  FromCity VARCHAR(30),
                  ToCity VARCHAR(30),
                  Depart DATE,
                  Return DATE);
BEGIN
  DBMS_RLMGR.CREATE_RULE_CLASS (
              rule_class   => 'TravelPromotion', -- rule class name --
              event_struct => 'AddFlight', -- event struct name --
              action_cbk    => 'PromoAction', -- callback proc name –-
              rslt_viewnm   => 'MatchingPromos', -- results view --
              actprf_spec   => 'PromoType VARCHAR(20),
                              OfferedBy VARCHAR(20)');
END;

The following commands create a rule class for composite events consisting of two primitive events (AddFlight and AddRentalCar).

CREATE or REPLACE TYPE TSCompEvent (Flt AddFlight,
                                    Car AddRentalCar);
BEGIN
  DBMS_RLMGR.CREATE_RULE_CLASS (
              rule_class    => 'CompTravelPromo', -- rule class name --
              event_struct  => 'TSCompEvent', -- event struct name --
              action_cbk    => 'CompPromoAction', -- callback proc name –-
              rslt_viewnm   => 'MatchingCompPromos', -- results view --
              actprf_spec   => 'PromoType VARCHAR(20),
                              OfferedBy VARCHAR(20)',
              properties    => '<composite/>');
END;

---

DELETE_RULE Procedure

This procedure deletes a rule from a rule class.

Syntax

DBMS_RLMGR.DELETE_RULE (
   rule_class    IN    VARCHAR2,
   rule_id       IN    VARCHAR2);

Parameters

Usage Notes

• This procedure is used to delete a rule from the rule class. The identifier for the rule to be deleted can be obtained by querying the rule class table (that shares the same name as the rule class). Alternately, the owner of the rule class can use a SQL DELETE statement on one rule class table to delete a rule.When schema extended name is used for the rule class, you should have DELETE RULE privilege on the rule class. See the GRANT_PRIVILEGE Procedure procedure for more information.

  Note:

  AUTOCOMMIT property of the rule class is ignored if the rules are deleted with the SQL DELETE statement instead of the DELETE_RULE procedure.

• See the CREATE_RULE_CLASS Procedure procedure for the structure of the rule class table.

Examples

The following command deletes a rule from the rule class.

BEGIN
  DBMS_RLMGR.DELETE_RULE (
           rule_class  => 'CompTravelPromo',
           rule_id     => 'AB_AV_FL');
END;

Alternately, the following SQL DELETE statement can be issued to delete the above rule from the rule class.

DELETE FROM CompTravelPromo WHERE rlm$ruleid = 'AB_AV_FL';

---

DROP_EVENT_STRUCTURE Procedure

This procedure drops an event structure.

Syntax

DBMS_RLMGR.DROP_EVENT_STRUCTURE  (
   event_struct  IN  VARCHAR2);

Parameters

Usage Notes

This procedure drops the event structure from the current schema. This drops all the dependent objects created to manage the event structure.

Examples

The following command drops the event structure.

BEGIN
  DBMS_RLMGR.DROP_EVENT_STRUCT(event_struct => 'AddFlight');
END;

---

DROP_RULE_CLASS Procedure

This procedure drops a rule class.

Syntax

DBMS_RLMGR.DROP_RULE_CLASS  (
   rule_class  IN  VARCHAR2);

Parameters

Usage Notes

This procedure drops the rule class from the current schema. This drops all the dependent objects created to manage the rule class. Because an event structure in a user's schema can be shared across multiple rule classes, the event structure is not dropped with this command. The DROP_EVENT_STRUCTURE API should be used for the composite event as well as the individual primitive events to cleanup unused event structures.

Examples

The following command drops the rule class.

BEGIN
  DBMS_RLMGR.DROP_RULE_CLASS(rule_class => 'CompTravelPromo');
END;

---

GRANT_PRIVILEGE Procedure

This procedure grants privileges on a rule class to another user.

Syntax

DBMS_RLMGR.GRANT_PRIVILEGE  (
   rule_class      IN  VARCHAR2,
   priv_type       IN  VARCHAR2,
   to_user         IN  VARCHAR2);

Parameters

Usage Notes

• This procedure grants appropriate privileges to a user who is not the owner of the rule class. The types of privileges that can be granted to a user are:

  • PROCESS RULES: A user with PROCESS RULES privilege on a rule class can process the rules in the rule class using the PROCESS_RULES procedure or the ADD_EVENT procedure. Also, the user with this privilege can select from the corresponding rule class results view.

  • ADD RULE: A user with ADD RULE privilege on a rule class can add rules to a rule class. Alternatively, the owner of the rule class can grant INSERT privileges on one rule class table to other users.

  • DELETE RULE: A user with DELETE RULE privilege on a rule class can delete rules from a rule class. Alternatively, the owner of the rule class can grant DELETE privileges on one rule class table to other users.

  • ALL: Granting the ALL privilege on a rule class is equivalent to granting all the above privileges on the rule class to the user.

• The owner of the rule class always has privileges to drop a rule class, process rules in a rule class, add rules and delete rules from a rules class. Only the owner of the rule class can drop a rule class and this privilege cannot be granted to another user.

• A user should also have EXECUTE privileges on the primitive event types associated with a rule class in order to make use of the corresponding rule class results view

Examples

The following command grants PROCESS RULES privilege on TravelPromo rule class to the user SCOTT.

BEGIN
  DBMS_RLMGR.GRANT_PRIVILEGE(rule_class => 'TravelPromo',
                             priv_type => 'PROCESS RULES',
                             to_user => 'SCOTT');
END;

---

PROCESS_RULES Procedure

This procedure processes the rules for a given event. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definitions.

Syntax

Processes the rules for a string representation of the event instance being added to the rule class:

DBMS_RLMGR.PROCESS_RULES  (
   rule_class    IN  VARCHAR2,
   event_inst    IN  VARCHAR2,
   event_type    IN  VARCHAR2 default null);

Processes the rules for an AnyData representation of the event instance being added to the rule class:

DBMS_RLMGR.PROCESS_RULES  (
   rule_class    IN  VARCHAR2,
   event_inst    IN  sys.AnyData);

Parameters

Usage Notes

• This procedure is used to process the rules in a rule class for an event instance assigned to the event_inst argument.

• In the case of a rule class configured for simple events (non-composite), the event instance is an instantiation of the corresponding event structure. The rules are evaluated (conclusively) for this event and the corresponding action callback procedure is called for each matching rule. If the event does not match any rule, no further action is performed. If the event matches two or more rules, the ordering clause configured for the rule class is used to order them accordingly to invoke the action callback procedure. If the rule class is configured for EXCLUSIVE consumption policy, once the first rule in this order is executed (and the corresponding action callback procedure is called), the rest of the rules that matched the event are ignored.

• In the case of a rule class configured for composite events, the event instance assigned to the event_inst argument is an instantiation of one of the primitive type within the composite event. When the instance is represented as a string, the corresponding type name should be assigned to the event_type argument. The PROCESS_RULES call on a rule class configured for composite events performs various actions depending on the state of the rule class and the kind of rules in the rule class.

  • The rules operating only on the primitive event passed in are evaluated conclusively and the action callback procedure is called for the matching rules, as described in previous paragraph.

  • In the case of a rule operating on more than one primitive event, the event instance passed through PROCESS_RULES procedure could match only a part of the rule.

    • If there is (are) another primitive event instance(s) that matches the rest of the rule, the current event instance is combined with the other instance(s) to form a complete composite event that matches a rule in the rule class. So, the event instance assigned to the event_inst argument of the PROCESS_RULES procedure could be combined with various other primitive events (previously processed) to evaluate one or more rules conclusively. The rule classes' action callback procedure is called for each such combination of primitive events (composite event) and the rule. The ordering clause for the rule class and the consumption policy for the primitive events in taken into account while invoking the action callback procedure.

    • If there is no other primitive event that matches the rest of the rule, the current event instance and its (incremental) evaluation results are recorded in the database. These results are preserved until either the event is consumed or deleted from the system owing to the duration policy used for the rule class.

Examples

The following command processes the rules in the TravelPromotion rule class for the given events.

BEGIN
  DBMS_RLMGR.PROCESS_RULES (
               rule_class => 'TravelPromotion',
               event_inst =>
                 AddFlight.getVarchar(987, 'Abcair', 'Boston', 'Orlando',
                                      '01-APR-2003', '08-APR-2003'));
END;

The following commands process the rules in the CompTravelPromo rule class for the two primitive events shown.

BEGIN  DBMS_RLMGR.PROCESS_RULES(
               rule_class => 'CompTravelPromo',
               event_inst =>
                 AddFlight.getVarchar(987, 'Abcair', 'Boston', 'Orlando',
                                      '01-APR-2003', '08-APR-2003'),
               event_type => 'AddFlight');
  DBMS_RLMGR.PROCESS_RULES(
               rule_class => 'Scott.CompTravelPromo',
               event_inst =>
                  AnyData.convertObject(AddRentalCar(987, 'Luxury', '03-APR-2003',
                                        '08-APR-2003', NULL)));
END;

---

RESET_SESSION Procedure

This procedure starts a new session and thus discards the results in the rule class results view.

Syntax

DBMS_RLMGR.RESET_SESSION  (
   rule_class  IN  VARCHAR2);

Parameters

Usage Notes

• When the ADD_EVENT procedure is used to add events to the rule class, the results from matching rules with events are recorded in the rule class results view. By default, these results are reset at the end of the database session. Alternately, the RESET_SESSION Procedure can be used to reset and start a new rule session within a database session.

• This procedure is only applicable while using ADD_EVENT Procedures to evaluate the rules.

Examples

The following command resets a rule class session.

BEGIN  DBMS_RLMGR.RESET_SESSION(
             rule_class => 'CompTravelPromo');
END;

---

REVOKE_PRIVILEGE Procedure

This procedure revokes privileges on a rule class from another user.

Syntax

DBMS_RLMGR.REVOKE_PRIVILEGE  (
   rule_class      IN  VARCHAR2,
   priv_type       IN  VARCHAR2,
   from_user       IN  VARCHAR2);

Parameters

Usage Notes

This procedure revokes appropriate privileges from a user. The types of privileges that can be revoked are the same as the types listed in the GRANT_PRIVILEGE Procedure description. Rule class privileges cannot be revoked from the owner of the rule class.

Examples

The following command revokes PROCESS RULES privilege on TravelPromo rule class from the user SCOTT.

BEGIN
  DBMS_RLMGR.REVOKE_PRIVILEGE(rule_class  => 'TravelPromo',
                              priv_type   => 'PROCESS RULES',
                              from_user   => 'SCOTT');
END;