RESTRICT_REFERENCES Pragma

RESTRICT_REFERENCES Pragma

To be callable from SQL statements, a stored function must obey certain "purity" rules, which control side-effects. (See "Controlling Side Effects of PL/SQL Subprograms" on page 8-22.) The fewer side-effects a function has, the better it can be optimized within a query, particular when the PARALLEL_ENABLE or DETERMINISTIC hints are used. The same rules that apply to the function itself also apply to any functions or procedures that it calls.

If any SQL statement inside the function body violates a rule, you get an error at run time (when the statement is parsed). To check for violations of the rules at compile time, you can use the compiler directive PRAGMA RESTRICT_REFERENCES. This pragma asserts that a function does not read and/or write database tables and/or package variables. Functions that do any of these read or write operations are difficult to optimize, because any call might produce different results or encounter errors.

For more information, see Oracle Database Application Developer's Guide - Fundamentals.

Syntax

Keyword and Parameter Description

DEFAULT

Specifies that the pragma applies to all subprograms in the package spec or object type spec. You can still declare the pragma for individual subprograms. Such pragmas override the default pragma.

function_name

A user-defined function or procedure.

PRAGMA

Signifies that the statement is a compiler directive. Pragmas are processed at compile time, not at run time. They do not affect the meaning of a program; they convey information to the compiler.

RNDS

Asserts that the subprogram reads no database state (does not query database tables).

RNPS

Asserts that the subprogram reads no package state (does not reference the values of packaged variables)

PL/SQL Language Elements 13-113

RESTRICT_REFERENCES Pragma

TRUST

Asserts that the subprogram can be trusted not to violate one or more rules. This value is needed for functions written in C or Java that are called from PL/SQL, since PL/SQL cannot verify them at run time.

WNDS

Asserts that the subprogram writes no database state (does not modify database tables).

WNPS

Asserts that the subprogram writes no package state (does not change the values of packaged variables).

Usage Notes

You can declare the pragma RESTRICT_REFERENCES only in a package spec or object type spec. You can specify up to four constraints (RNDS, RNPS, WNDS, WNPS) in any order. To call a function from parallel queries, you must specify all four constraints. No constraint implies another.

When you specify TRUST, the function body is not checked for violations of the constraints listed in the pragma. The function is trusted not to violate them. Skipping these checks can improve performance.

If you specify DEFAULT instead of a subprogram name, the pragma applies to all subprograms in the package spec or object type spec (including the system-defined constructor for object types). You can still declare the pragma for individual subprograms, overriding the default pragma.

A RESTRICT_REFERENCES pragma can apply to only one subprogram declaration. A pragma that references the name of overloaded subprograms always applies to the most recent subprogram declaration.

Typically, you only specify this pragma for functions. If a function calls procedures, then you need to specify the pragma for those procedures as well.

Examples

This example asserts that the function BALANCE writes no database state (WNDS) and reads no package state (RNPS). That is, it does not issue any DDL or DML statements, and does not refer to any package variables, and neither do any procedures or functions that it calls. It might issue queries or assign values to package variables.

CREATE PACKAGE loans AS

FUNCTION balance(account NUMBER) RETURN NUMBER; PRAGMA RESTRICT_REFERENCES (balance, WNDS, RNPS);

END loans;

/

DROP PACKAGE loans;

Related Topics

AUTONOMOUS_TRANSACTION Pragma, EXCEPTION_INIT Pragma,

SERIALLY_REUSABLE Pragma

13-114 PL/SQL User's Guide and Reference

RETURN Statement

RETURN Statement

The RETURN statement immediately completes the execution of a subprogram and returns control to the caller. Execution resumes with the statement following the subprogram call. In a function, the RETURN statement also sets the function identifier to the return value. For more information, see "Using the RETURN Statement" on page 8-4.

Syntax

Keyword and Parameter Description

expression

A combination of variables, constants, literals, operators, and function calls. The simplest expression consists of a single variable. When the RETURN statement is executed, the value of expression is assigned to the function identifier.

Usage Notes

Do not confuse the RETURN statement with the RETURN clause in a function spec, which specifies the datatype of the return value.

A subprogram can contain several RETURN statements. Executing any of them completes the subprogram immediately. The RETURN statement might not be positioned as the last statement in the subprogram.

In procedures, a RETURN statement cannot contain an expression. The statement just returns control to the caller before the normal end of the procedure is reached.

In functions, a RETURN statement must contain an expression, which is evaluated when the RETURN statement is executed. The resulting value is assigned to the function identifier. In functions, there must be at least one execution path that leads to a RETURN statement. Otherwise, PL/SQL raises an exception at run time.

The RETURN statement can be used in an anonymous block to exit the block (and all enclosing blocks), but the RETURN statement cannot contain an expression.

Example

The following example demonstrates the RETURN statement using a variable, an expression, or no argument at all:

DECLARE

FUNCTION num_rows (table_name VARCHAR2) RETURN user_tables.num_rows%TYPE IS

howmany user_tables.num_rows%TYPE;

BEGIN

EXECUTE IMMEDIATE 'SELECT num_rows FROM user_tables ' || 'WHERE table_name = ''' || UPPER(table_name) || ''''

INTO howmany;

-- A function can compute a value, then return that value.

PL/SQL Language Elements 13-115

RETURN Statement

RETURN howmany;

END num_rows;

FUNCTION double_it(n NUMBER) RETURN NUMBER IS

BEGIN

-- A function can also return an expression. RETURN n * 2;

END double_it;

PROCEDURE print_something IS

BEGIN

dbms_output.put_line('Message 1.');

-- A procedure can end early by issuing RETURN with no value. RETURN;

dbms_output.put_line('Message 2 (never printed).'); END;

BEGIN

dbms_output.put_line('EMPLOYEES has ' || num_rows('employees') || ' rows.'); dbms_output.put_line('Twice 100 is ' || double_it(n => 100) || '.'); print_something;

END;

/

Related Topics

Functions, Procedures

13-116 PL/SQL User's Guide and Reference