.\" XXX standard disclaimer belongs here....
.\" $Header: RCS/definerule,v 1.12 91/08/17 22:47:26 glass Exp $
.SP "DEFINE RULE" COMMANDS 6/14/90
.XA 2 "Define Rule"
.uh NAME
.lp
define rule \*(- Define a new rule
.uh SYNOPSIS
.lp
.b "define [instance | rewrite] rule"
rule_name
[as exception to rule_name_2]
.b is
.br
.b on
event
.b to
object [[
.b from
clause]
.b where
clause]
.br
.b "do"
[
.b instead ]
.br
[action | nothing | '[' action ... ']'
.uh DESCRIPTION
.lp
.b Define
.b rule
is used to define a new rule.
There are two implementations of the rules
system, one 
based on 
.b query
.b rewrite
and the other based on 
.b instance-level
processing.  In general, the instance-level system is more efficient
if there are many rules on a single class, each covering a small
subset of the instances.  The rewrite system is more
efficient if large scope rules are being defined. The user
can optionally choose which rule system to use by specifying 
.i rewrite
or
.i instance
in the command.  If the user does not specify which system to use, POSTGRES
defaults to using the instance-level system.  In the long run
POSTGRES will automatically decide which rules system to use and the possibility
of user selection will be removed.
.lp
Here, event is one of:
.(l
retrieve 
replace 
delete
append
.)l
Moreover, object is either:
.(l
a class name
or
class.column
.)l
The FROM clause, the WHERE clause, and the
action are respectively normal POSTQUEL 
FROM clauses, WHERE clauses 
and collections of POSTQUEL commands
with the following change:
.in+6
.ll-6

.b new
or
.b current
can appear instead of 
an instance variable whenever an instance 
variable is permissible in POSTQUEL.
.in-6
.ll+6
.lp
The semantics of a rule is that at the time an individual instance is
accessed, updated, inserted or deleted, there is a current instance (for
retrieves, replaces and deletes) and a new instance (for replaces and appends).
If the event specified in the ON clause and the condition specified
in the WHERE clause are true 
for the current instance,
then the action part of the rule is executed.  First, however, values
from fields in the current instance and/or the new instance are substituted 
for:
.(l
current.attribute-name
new.attribute-name
.)l
The action part of the rule executes with same command and
transaction identifier
as the user command that caused activation.  
.lp
A note of caution about POSTQUEL rules is in order.  If the same class
name or instance variable appears in the event, where clause 
and the action parts of a rule, they are 
all considered different tuple variables.  
More accurately, new and current are the only
tuple variables that are shared between these clauses.
For example the following two rules have the
same semantics: 
.(l
on replace to EMP.salary where EMP.name = "Joe"
do replace EMP ( ...) where ...

on replace to EMP-1.salary where EMP-2.name = "Joe"
do replace EMP-3 ( ...) where ...
.)l
.lp
Each rule can have the optional tag "instead".  Without this tag the
action will be performed in addition to the user command 
when the event 
in the condition part of the rule occurs. 
Alternately, the action part will be done instead of the user command.
In this later case, the action can be the keyword
.b nothing.
.lp
When choosing between the rewrite and instance rule systems for a particular
rule application, remember that in the rewrite system  'current' refers to a
relation and some qualifiers whereas in the instance system it refers to an
instance (read tuple).

.uh EXAMPLES
.lp
/* Make Sam get the same salary adjustment as Joe */
.(l
define rule example_1 is
on replace to EMP.salary where current.name = ``Joe''
do replace EMP (salary = new.salary) where EMP.name = ``Sam''
.)l
At the time Joe receives a salary adjustment, the event will become
true and Joe's current instance and proposed new instance are available
to the execution routines.  Hence, his new salary is substituted into the 
action part of the rule which is subsequently executed.  This 
propagates Joe's salary on to Sam.
.lp
/* Make Bill get Joe's salary when it is accessed */
.(l
define rule example_2 is
on retrieve to EMP.salary where current.name = ``Bill''
do instead retrieve (EMP.salary) where EMP.name = ``Joe''
.)l
.lp
/* Deny Joe access to the salary of employees in the shoe department */
/* Note: ``pg_username'' returns the name of the current user */
.(l
define rule example_3 is
on retrieve to EMP.salary where current.dept = ``shoe'' and pg_username() = ``Joe''
do instead nothing
.)l
.lp
/* create a view of the employees working in the toy department */
.(l
create TOYEMP(name = char16, salary = int4)

define rule example_4 is
on retrieve to TOYEMP
do instead retrieve (EMP.name, EMP.salary) where EMP.dept = ``toy''
.)l
.lp
/* all new employees must make 5,000 or less */
.(l
define rule example_5 is
on append to EMP where new.salary > 5000
do replace new(salary = 5000)
.)l
.uh "SEE ALSO"
.lp
postquel(postquel).
.uh BUGS
.lp
Exceptions are not implemented in Version 3.0.
.lp
The object in a POSTQUEL rule cannot be an array reference and cannot have parameters.
.lp
The WHERE clause can not have a FROM clause.
.lp
Only one POSTQUEL command can be specified in the action part of a tuple rule
and it can only be a
replace, append, retrieve or delete command.
.lp
The rewrite rule system does support multiple action rules surrouas long as the event
is not retrieve.
.lp
The query rewrite rule system now supports most rule semantics, and closely
parallels the tuple system.  It also attempts to avoid odd semantics by
running instead rules before non-instead rules.








