Skip Headers
Oracle® Database PL/SQL Packages and Types Reference
11g Release 2 (11.2)

Part Number E16760-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

122 DBMS_RLMGR

The DBMS_RLMGR package contains various procedures to create and manage rules and rule sessions by the Rules Manager.

See Also:

Oracle Database Rules Manager and Expression Filter Developer's Guide for more information.

This chapter contains the following topic:


Using DBMS_RLMGR

This section contains topics that relate to using the Rules Manager DBMS_RLMGR package.


Security Model

The Oracle Database installation runs the catrul.sql script to load the DBMS_RLMGR package and create the required Rules Manager schema objects in the EXFSYS Schema.

DBMS_RLMGR is an EXFSYS-owned package compiled with AUTHID CURRENT_USER. Any DBMS_RLMGR subprogram called from an anonymous PL/SQL block is run using the privileges of the current user.

A user must be granted CONNECT and RESOURCE roles, EXECUTE privilege on DBMS_LOCK, and CREATE VIEW privilege to use this package.

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

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. Rule class privileges cannot be revoked from the owner of the rule class.

A user who is not the owner of the rule class must be granted appropriate types of privileges to perform certain tasks. The types of privileges that can be granted are:

A user must have the EXECUTE privilege on the primitive event types associated with a rule class before that user can make use of the corresponding rule class results view.

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. When you use the schema extended name for the rule class, the user must have the ADD RULE privilege on the rule class to add a rule to the rule class.

The owner of the rule class can use an SQL DELETE statement on one rule class table to delete a rule. When you use the schema extended name for the rule class, the user must have the DELETE RULE privilege on the rule class.

When the schema extended name is used for the rule class, the user must have PROCESS RULES privilege on the rule class.

A user must have EXECUTE privilege on the CTX_DDL package for successful synchronization of the text indexes using the DBMS_RLMGR.SYNC_TEXT_INDEXES procedure.

The USER_RLMGR_PRIVILEGES view lists privileges of the current user for the rule classes.


Summary of Rules Manager Subprograms

Table 122-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. To preserve the case, enclose the values with double quotation marks.

Table 122-1 DBMS_RLMGR Package Subprograms

Subprogram Description

ADD_ELEMENTARY_ATTRIBUTE Procedures

Adds the specified attribute to the event structure and the Expression Filter attribute set

ADD_EVENT Procedure

Adds an event to a rule class in an active session

ADD_FUNCTIONS Procedure

Adds a Function, a Type, or a Package to the approved list of functions with an event structure and to the Expression Filter attribute set

ADD_RULE Procedure

Adds a rule to the rule class

CONDITION_REF Function

Retrieves the primitive rule condition reference from a rule condition for composite events

CONSUME_EVENT Function

Consumes an event using its identifiers and prepares the corresponding rule for action execution

CONSUME_PRIM_EVENTS Function

Consumes one or more primitive events with all or none semantics

CREATE_CONDITIONS_TABLE Procedure

Creates a repository for the primitive rule conditions that can be shared by multiple rules from the same or different rule classes

CREATE_EVENT_STRUCT Procedure

Creates an event structure

CREATE_EXPFIL_INDEXES Procedure

Creates expression filter indexes for the rule class if the default indexes have been dropped

CREATE_INTERFACE Procedure

Creates a rule class interface package to directly operate on the rule class

CREATE_RULE_CLASS Procedure

Creates a rule class

DELETE_RULE Procedure

Deletes a rule from a rule class

DROP_CONDITIONS_TABLE Procedure

Drops the conditions table

DROP_EVENT_STRUCT Procedure

Drops an event structure

DROP_EXPFIL_INDEXES Procedure

Drops Expression Filter indexes for the rule conditions

DROP_INTERFACE Procedure

Drops the rule class interface package

DROP_RULE_CLASS Procedure

Drops a rule class

EXTEND_EVENT_STRUCT Procedure

Adds an attribute to the primitive event structure

GET_AGGREGATE_VALUE Function

Retrieves the aggregate value computed for a collection event

GRANT_PRIVILEGE Procedure

Grants a privilege on a rule class to another user

PROCESS_RULES Procedure

Process the rules for a given event

PURGE_EVENTS Procedure

Resets the rule class by removing all the events associated with the rule class and purging any state information pertaining to rules matching some events

RESET_SESSION Procedure

Starts a new rule session within a database session

REVOKE_PRIVILEGE Procedure

Revokes a privilege on a rule class from a user

SYNC_TEXT_INDEXES Procedure

Synchronizes the indexes defined to process the predicates involving the CONTAINS operator in rule conditions



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);

Allows addition of text attributes to the attribute set:

DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
              event_struct   IN   VARCHAR2,
              attr_name      IN   VARCHAR2,
              attr_type      IN   VARCHAR2,
              text_pref      IN   EXF$TEXT);
 

Parameters

Table 122-2 ADD_ELEMENTARY_ATTRIBUTE Procedure Parameters

Parameter Description

event_struct

Name of the event structure or attribute set to which this attribute is added

attr_name

Name of the elementary attribute to be added. No two attributes in a set can have the same name.

attr_type

Datatype of the attribute. This argument accepts any standard SQL datatype or the name of an object type that is accessible to the current user.

tab_alias

The type that identifies the database table to which the attribute is aliased

attr_defv1

Default value for the elementary attribute

text_pref

Text preferences such as LEXER and WORDLIST specification


Usage Notes

Examples

The following command adds two elementary attributes to an attribute set:

BEGIN
  DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
                       EVENT_STRUCT => 'HRAttrSet',
                       ATTR_NAME => 'HRREP',
                       attr_type => 'VARCHAR2'); 
  DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
                       EVENT_STRUCT => 'HRAttrSet',
                       ATTR_NAME => 'DEPT',
                       TAB_ALIAS => RLM$TABLE_ALIAS('DEPT')); 
END;

The following commands create an attribute set with each hotel reservation including some additional information, described as the AddlInfo attribute of CLOB data type. Rule conditions specified for this event structure can include text predicates on this attribute.

BEGIN
  DBMS_RLMGR.CREATE_EVENT_STRUCT (EVENT_STRUCT => 'AddFlight'); 
  DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
                       EVENT_STRUCT => 'AddHotel',
                       ATTR_NAME => 'CustId',
                       ATTR_TYPE => 'NUMBER'); 
  DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
                       EVENT_STRUCT => 'AddHotel',
                       ATTR_NAME => 'Type',
                       ATTR_TYPE => 'VARCHAR2(20)'); 
  . . . 
  DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
                       EVENT_STRUCT => 'AddHotel',
                       ATTR_NAME => 'AddlInfo',
                       ATTR_TYPE => 'CLOB',
                       TEXT_PREF => EXF$TEXT('LEXER hotelreserv_lexer')); 
END;

ADD_EVENT Procedure

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

Table 122-3 ADD_EVENT Procedure Parameters

Parameter Description

rule_class

Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema.

event_inst

String or AnyData representation of the event instance being added to the rule class

event_type

Type of event instance assigned to the event_inst argument when the string representation of the event instance is used for a rule class configured for composite events


Usage Notes

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

Table 122-4 ADD_FUNCTIONS Procedure Parameters

Parameter Description

event_struct

Name of the event structure to which the functions are added

funcs_name

Name of a function, package, or type (representing a function set) or its synonyms


Usage Notes

Examples

The following command adds 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

Table 122-5 ADD_RULE Procedure Parameters

Parameter Description

rule_class

Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema.

rule_id

Unique identifier for the rule within the rule class

rule_cond

The condition for the rule. The condition uses the variables defined in the rule class's event structure.

actprf_nml

The list of action preference names for which values will be assigned through the actprf_vall argument

actprf_vall

The list of action preference values for the names list assigned to the actprf_nml argument


Usage Notes

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');

CONDITION_REF Function

This function retrieves the primitive rule condition reference from a rule condition for composite events.

Syntax

DBMS_RLMGR.CONDITION_REF (
     rule_cond IN   VARCHAR2,
     eventnm   IN   VARCHAR2) 
  RETURN VARCHAR2;

Parameters

Table 122-6 CONDITION_REF Function Parameters

Parameter Description

rule_cond

Rule condition in XML format

eventnm

Name of the event for which the reference should be retrieved


Usage Notes

Examples

The following command joins the rule class table with the primitive conditions table to identify all the rule conditions that have references to the shareable primitive conditions (the query uses a functional index defined on the rlm$rulecond column). This query identifies all the rule conditions that refer to any shared conditions stored in the FlightConditions table.

select ctp.rlm$ruleid from CompTravelPromo ctp, FlightConditions fc
where dbms_rlmgr.condition_ref(ctp.rlm$rulecond, 'FLT') = fc.rlm$condid; 

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

Table 122-7 CONSUME_EVENT Function Parameters

Parameter Description

rule_class

Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema.

event_ident

Event identifier obtained from the corresponding rule class results view (or arguments of the action callback procedure in the case of rule class configured for RULE based consumption policy)


Returns

The function returns:

Usage Notes

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

Table 122-8 CONSUME_PRIM_EVENTS Function Parameters

Parameter Description

rule_class

Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema.

event_ident

Event identifiers obtained from the corresponding rule class results view or the arguments of the action callback procedure


Returns

The function returns:

Usage Notes

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 function 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_CONDITIONS_TABLE Procedure

This procedure creates a conditions table, which is a repository for the primitive rule conditions that can be shared by multiple rules from the same or different rule classes. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definitions.

Syntax

Creates a conditions table to store shareable primitive conditions defined for a primitive event.

DBMS_RLMGR.CREATE_CONDITIONS_TABLE (
     cond_table    IN  VARCHAR2,
     pevent_struct IN  VARCHAR2,
     stg_clause    IN  VARCHAR2 DEFAULT NULL);

Creates a conditions table to store shareable primitive conditions defined for a relational table identified through table aliases.

DBMS_RLMGR.CREATE_CONDITIONS_TABLE (
     cond_table    IN  VARCHAR2,
     tab_alias     IN  rlm$table_alias,
     stg_clause    IN  VARCHAR2 DEFAULT NULL);

Parameters

Table 122-9 CREATE_CONDITIONS_TABLE Procedure Parameters

Parameter Description

pevent_struct

Primitive event structure for which the shareable primitive rule conditions are defined

cond_table

Name of the table storing the primitive rule conditions

stg_clause

Storage clause for the conditions table

tab_alias

Type that identifies the database table for which the shareable primitive rule conditions are defined


Usage Notes

Examples

The following command creates a conditions table that can store shareable primitive rule conditions for the AddRentalCar event structure:

BEGIN
  DBMS_RLMGR.CREATE_CONDITIONS_TABLE (
    cond_table    => 'FlightConditions',
    pevent_struct => 'AddFlight', 
    stg_clause    => 'TABLESPACE TBS_1');
END;
/

CREATE_EVENT_STRUCT Procedure

This procedure creates an event structure.

Syntax

DBMS_RLMGR.CREATE_EVENT_STRUCT  (
   event_struct  IN  VARCHAR2);

Parameters

Table 122-10 CREATE_EVENT_ STRUCT Procedure Parameter

Parameter Description

event_struct

Name of the event structure to be created in the current schema


Usage Notes

Examples

The following command creates the event structure.

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

CREATE_EXPFIL_INDEXES Procedure

This procedure creates expression filter indexes for the rule class if the default indexes have been dropped. If a representative set of rules is stored in the rule class table, the indexes can be tuned for these expressions by collecting statistics.

Syntax

DBMS_RLMGR.CREATE_EXPFIL_INDEXES  (
   rule_class  IN  VARCHAR2,
   coll_stats  IN  VARCHAR2 default 'NO');

Parameters

Table 122-11 CREATE_EXPFIL_INDEXES Procedure Parameter

Parameter Description

rule_class

Name of the rule class

coll_stats

To collect expression statistics for building the indexes


Usage Notes

Examples

The following commands collect the statistics for the rules defined in the CompTravelPromo rule class and create the expression filter indexes that are based on the most common predicates in the set.

BEGIN
DBMS_RLMGR.CREATE_EXPFIL_INDEXES (rule_class => 'CompTravelPromo',
                                  coll_stats => 'yes');
END;
/

This is an Expression Filter tuning example where the domain knowledge is used to assign specific index parameters. The following commands associate specific index parameters to the AddFlight event structure such that the expression filter index created for corresponding expressions are optimized accordingly. The subsequent CREATE_EXPFIL_INDEXES step makes use of these index parameters.

BEGIN
  DBMS_EXPFIL.DEFAULT_INDEX_PARAMETERS('AddFlight',
    exf$attribute_list (
       exf$attribute (attr_name => 'Airline',
                      attr_oper => exf$indexoper('='),
                      attr_indexed => 'TRUE'),
       exf$attribute (attr_name => 'ToCity',
                      attr_oper => exf$indexoper('='),
                      attr_indexed => 'TRUE'),
       exf$attribute (attr_name => 'Depart',
                      attr_oper => exf$indexoper('=','<','>','>=','<='),
                      attr_indexed => 'FALSE') 
    )
  );
  -- create the indexes after assigning the index parameters --
  DBMS_RLMGR.CREATE_EXPFIL_INDEXES (rule_class => 'CompTravelPromo'); 
END; 
/

CREATE_INTERFACE Procedure

This procedure creates a rule class interface package that can be used to directly operate on the rule class for efficiency and ease of use.

Syntax

DBMS_RLMGR.CREATE_INTERFACE  (
   rule_class   IN  VARCHAR2,
   interface_nm IN  VARCHAR2);

Parameters

Table 122-12 CREATE_INTERFACE Procedure Parameter

Parameter Description

rule_class

Name of the rule class for which the interface package is created

interface_nm

Name of the PL/SQL package that acts as the interface to the rule application


Usage Notes

Examples

The following commands create the rule class interface package for the CompTravelPromo rule class.

BEGIN
    DBMS_RLMGR.CREATE_INTERFACE  (rule_class   => 'CompTravelPromo',
                                  interface_nm => 'TravelPromoRules'); 
  END;

The following commands make use of the interface created in previous step to process the rules for an instance of AddFlight event.

BEGIN
    TravelPromoRules.process_rules (event_inst => 
              AddFlight(987, 'Abcair', 'Boston', 'Orlando',
                                      '01-APR-2009', '08-APR-2009'); 
  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

Table 122-13 CREATE_RULE_CLASS Procedure Parameters

Parameter Description

rule_class

Name of the rule class to be created in the current schema

event_struct

Name of the object type or an Expression Filter attribute set in the current schema that represents the event structure for the rule class

action_cbk

Name of the action callback procedure to be created for the rule class

actprf_spec

Specification (name and SQL datatype pairs) for the action preferences associated with the rule class

rlst_viewnm

Name of rule class results view that lists the matching events and rules within a session. A view with this name is created in the current schema.

rlcls_prop

XML document for setting the rule class properties. By default, the rule class created is for simple events (non-composite).


Usage Notes

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

Table 122-14 DELETE_RULE Procedure Parameters

Parameter Description

rule_class

Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema.

rule_id

Identifier for the rule to be deleted


Usage Notes

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, you can issue the following SQL DELETE statement to delete the above rule from the rule class.

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

DROP_CONDITIONS_TABLE Procedure

This procedure drops the conditions table.

Syntax

DBMS_RLMGR.DROP_CONDITIONS_TABLE (
     cond_table IN   VARCHAR2);

Parameters

Table 122-15 DROP_CONDITIONS_TABLE Procedure Parameters

Parameter Description

cond_table

Name of conditions table in the user schema


Usage Notes

Examples

The following command drops the conditions table:

BEGIN
  DBMS_RLMGR.DROP_CONDITIONS_TABLE (cond_table => 'FlightConditions');
END;
/

DROP_EVENT_STRUCT Procedure

This procedure drops an event structure.

Syntax

DBMS_RLMGR.DROP_EVENT_STRUCT  (
   event_struct  IN  VARCHAR2);

Parameters

Table 122-16 DROP_EVENT_ STRUCT Procedure Parameter

Parameter Description

event_struct

Name of event structure in the current schema


Usage Notes

Examples

The following command drops the event structure.

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

DROP_EXPFIL_INDEXES Procedure

This procedure drops the expression filter indexes created for a rule class.

Syntax

DBMS_RLMGR.DROP_EXPFIL_INDEXES  (
   rule_class  IN  VARCHAR2);

Parameters

Table 122-17 DROP_EXPFIL_INDEXES Procedure Parameter

Parameter Description

rule_class

Name of the rule class


Usage Notes

This procedure drops all the expression filter indexes associated with a rule class. You can recreate the indexes using the DBMS_RLMGR.CREATE_EXPFIL_INDEXES call.

Examples

The following command drops the expression filter indexes created for the CompTravelPromo rule class.

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

DROP_INTERFACE Procedure

This procedure drops the rule class interface package created for a rules application.

Syntax

DBMS_RLMGR.DROP_INTERFACE  (
   interface_nm  IN  VARCHAR2);

Parameters

Table 122-18 DROP_INTERFACE Procedure Parameter

Parameter Description

interface_nm

Name of the PL/SQL package that acts as the interface to the rule application


Usage Notes

This procedure drops the rule class interface package created with the DBMS_RLMGR.CREATE_INTERFACE call.

Examples

The following command drops the rule class interface package TravelPromoRules.

BEGIN
    DBMS_RLMGR.DROP_INTERFACE (interface_nm => 'TravelPromoRules' 
  END;

DROP_RULE_CLASS Procedure

This procedure drops a rule class.

Syntax

DBMS_RLMGR.DROP_RULE_CLASS  (
   rule_class  IN  VARCHAR2);

Parameters

Table 122-19 DROP_RULE_CLASS Procedure Parameter

Parameter Description

rule_class

Name of rule class in the current schema


Usage Notes

Examples

The following command drops the rule class.

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

EXTEND_EVENT_STRUCT Procedure

This is used to extend the primitive event structure used by one or more rule classes by adding a new attribute.

Syntax

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

Parameters

Table 122-20 EXTEND_EVENT_ STRUCT Procedure Parameter

Parameter Description

event_struct

Name of the event structure to which this attribute is added

attr_name

Name of the elementary attribute to be added. No two attributes in a set can have the same name.

attr_type

Data type of the attribute. This argument accepts any standard SQL data type or the name of an object type that is accessible to the current user.

attr_defvl

Default value for the elementary attribute


Usage Notes

Examples

The following commands add an attribute to the AddRentalCar event structure that is used by the CompTravelPromo rule class.

BEGIN 
    DBMS_RLMGR.EXTEND_EVENT_STRUCT (
          event_struct   => 'AddRentalCar',  
          attr_name      => 'PrefMemberId',
          attr_type      => 'VARCHAR2(30)'); 
  END; 

GET_AGGREGATE_VALUE Function

This function retrieves the aggregate value computed for a collection event.

Syntax

DBMS_RLMGR.GRANT_PRIVILEGE  (
   rule_class      IN  VARCHAR2,
   event_ident     IN  VARCHAR2,
   aggr_func       IN  VARCHAR2) RETURN VARCHAR2;

Parameters

Table 122-21 GET_AGGREGATE_VALUE Function Parameters

Parameter Description

rule_class

Name of the rule class for the collection event

event_ident

System-generated identifier for the collection event

aggr_func

Signature for the aggregate value to be retrieved


Usage Notes

Examples

The following example shows a sample implementation of the action callback procedure that prints the computed aggregate values as part of action execution. In this particular case, the BankTransaction primitive event is enabled for collections.

CREATE OR REPLACE PROCEDURE LAWENFORCEMENTCBK (
   bank                 banktransaction,
   bankcollid           rowid,
   transport            transportation,
   fldrpt               fieldreport,
   rlm$rule             LawEnforcementRC%ROWTYPE) IS
   aggrval              VARCHAR(30); 
begin
  dbms_ouput.put_line('Mathing Rule :'||rlm$rule.rlm$ruleid||chr(10)); 
  
  if (bank is not null) then
   dbms_ouput.put_line('-->Bank Transactions by ('||bank.subjectId||')'||chr(10);

   aggrval := dbms_rlmgr.get_aggregate_value(rule_class  =>'LawEnforcementRC',
                                             event_ident => bankcollid,
                                             aggr_func   => 'sum(amount)');
   if (aggrval is not null) then
     dbms_ouput.put_line('---> Sum of the amounts is :'||aggrval||chr(10));
   end if;
   . . .
  end if; 
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

Table 122-22 GRANT_PRIVILEGE Procedure Parameters

Parameter Description

rule_class

Name of the rule class in the current schema

priv_type

Type of rule class privilege to be granted

to_user

User to whom the privilege is to be granted


Usage Notes

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

Table 122-23 PROCESS_RULES Procedure Parameters

Parameter Description

rule_class

Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema.

event_inst

String or AnyData representation of the event instance being added to the rule class

event_type

Type of event instance assigned to the event_inst argument when the string representation of the event instance is used for a rule class configured for composite events


Usage Notes

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;

PURGE_EVENTS Procedure

This procedure resets the incremental state maintained by the rule class by removing all the events associated with the rule class and purging any state information pertaining to rules matching some events.

Syntax

DBMS_RLMGR.PURGE_EVENTS (
     rule_class IN   VARCHAR2);

Parameters

Table 122-24 PURGE_EVENTS Procedure Parameters

Parameter Description

rule_class

Name of rule class in the current schema


Usage Notes

Examples

The following command removes the events associated with the CompTravelPromo rule class:

BEGIN
  DBMS_RLMGR.PURGE_EVENTS (rule_class => 'CompTravelPromo');
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

Table 122-25 RESET_SESSION Procedure Parameter

Parameter Description

rule_class

Name of rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema.


Usage Notes

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

Table 122-26 REVOKE_PRIVILEGE Procedure Parameters

Parameter Description

rule_class

Name of the rule class in the current schema

priv_type

Type of rule class privilege to be revoked

from_user

User from whom the privilege is to be revoked


Usage Notes

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;

SYNC_TEXT_INDEXES Procedure

This procedure synchronizes the indexes defined to process the predicates involving the CONTAINS operator in rule conditions.

Syntax

DBMS_RLMGR.SYNC_TEXT_INDEXES (
     rule_class IN   VARCHAR2);

Parameters

Table 122-27 SYNC_TEXT_INDEXES Procedure Parameters

Parameter Description

rule_class

Name of the rule class in the current schema


Usage Notes

Examples

The following command synchronizes any text indexes associated CompTravelPromo rule class:

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