Pragma RESTRICT_REFERENCES

To execute a SQL statement that calls a member function, Oracle must know the purity level of the function, that is, the extent to which the function is free of side effects. The term side effect, in this context, refers to accessing database tables, package variables, and so forth for reading or writing. It is important to control side effects because they can prevent the proper parallelization of a query, produce order-dependent (and therefore indeterminate) results, or require impermissible actions such as the maintenance of package state across user sessions.

A member function called from a SQL statement can be restricted so that it cannot:

• Insert into, update, or delete database tables

• Be executed remotely or in parallel if it reads or writes the values of packaged variables

• Write the values of packaged variables unless it is called from a SELECT, VALUES, or SET clause

• Call another method or subprogram that violates any of these rules

• Reference a view that violates any of these rules

For more information about the rules governing purity levels and side effects, see the PL/SQL User's Guide and Reference.

You use the pragma (compiler directive) RESTRICT_REFERENCES to enforce these rules. For example, the purity level of the DataStreamMax method of type DataStream is asserted to be write no database state (WNDS) and write no package state (WNPS) in the following way:

CREATE TYPE DataStream AS OBJECT (
         ....
PRAGMA RESTRICT_REFERENCES (DataStreamMax, WNDS, WNPS)
         ... );

Member methods that call external procedures cannot do so directly, but must be routed through a package. The reason for this requirement is that currently the arguments to external procedures cannot be object types; a member function automatically gets a SELF reference (a reference to that specific instance) as its first argument. Therefore, member methods in objects types cannot call out directly to external procedures.

Collecting all external calls into a package makes for a better design. The purity level of the package must also be asserted. Therefore, when the package named DS_Package is declared and all external procedure calls from type DataStream are routed through this package, the purity level of the package is also declared, as follows:

CREATE OR REPLACE PACKAGE DS_Package AS
   ... 
PRAGMA RESTRICT_REFERENCES (ds_findmin, WNDS, WNPS)
   ...
end;

In addition to WNDS and WNPS, it is possible to specify two other constraints: read no database state (RNDS) and read no package state (RNPS). These two constraints are normally useful if you have parallel queries.

Each constraint is independent of the others and does not imply another. Choose the set of constraints based on application-specific requirements. For more information about controlling side effects using the RESTRICT_REFERENCES pragma, see the Oracle8i Application Developer's Guide - Fundamentals.

You can also specify the keyword DEFAULT instead of a method or procedure name, in which case the pragma applies to all member functions of the type (or procedures of the package). For example:

PRAGMA RESTRICT_REFERENCES (DEFAULT, WNDS, WNPS)