FORALL Statement

FORALL Statement

The FORALL statement issues a series of INSERT, UPDATE, or DELETE statements, usually much faster than an equivalent FOR loop. It requires some setup code, because each iteration of the loop must use values from one or more collections in its VALUES or WHERE clauses. For more information, see "Reducing Loop Overhead for DML Statements and Queries (FORALL, BULK COLLECT)" on page 11-7.

Syntax

bounds_clause

lower_bound .. upper_bound

BETWEEN lower_bound AND upper_bound

INDICES OF collection

VALUES OF index_collection

Keyword and Parameter Description

INDICES OF collection_name

A clause specifying that the values of the index variable correspond to the subscripts of the elements of the specified collection. With this clause, you can use FORALL with nested tables where some elements have been deleted, or with associative arrays that have numeric subscripts.

BETWEEN lower_bound AND upper_bound

Limits the range of subscripts in the INDICES OF clause. If a subscript in the range does not exist in the collection, that subscript is skipped.

VALUES OF index_collection_name

A clause specifying that the subscripts for the FORALL index variable are taken from the values of the elements in another collection, specified by index_collection_name. This other collection acts as a set of pointers; FORALL can iterate through subscripts in arbitrary order, even using the same subscript more than once, depending on what elements you include in index_collection_name.

The index collection must be a nested table, or an associative array indexed by

PLS_INTEGER or BINARY_INTEGER, whose elements are also PLS_INTEGER or

BINARY_INTEGER. If the index collection is empty, an exception is raised and the FORALL statement is not executed.

index_name

An undeclared identifier that can be referenced only within the FORALL statement and only as a collection subscript.

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

FORALL Statement

The implicit declaration of index_name overrides any other declaration outside the loop. You cannot refer to another variable with the same name inside the statement. Inside a FORALL statement, index_name cannot appear in expressions and cannot be assigned a value.

lower_bound .. upper_bound

Numeric expressions that specify a valid range of consecutive index numbers. PL/SQL rounds them to the nearest integer, if necessary. The SQL engine executes the SQL statement once for each index number in the range. The expressions are evaluated once, when the FORALL statement is entered.

SAVE EXCEPTIONS

Optional keywords that cause the FORALL loop to continue even if some DML operations fail. Instead of raising an exception immediately, the program raises a single exception after the FORALL statement finishes. The details of the errors are available after the loop in SQL%BULK_EXCEPTIONS. The program can report or clean up all the errors after the FORALL loop, rather than handling each exception as it happens.

sql_statement

An INSERT, UPDATE, or DELETE statement that references collection elements in the

VALUES or WHERE clauses.

Usage Notes

Although the SQL statement can reference more than one collection, the performance benefits apply only to subscripted collections.

If a FORALL statement fails, database changes are rolled back to an implicit savepoint marked before each execution of the SQL statement. Changes made during previous iterations of the FORALL loop are not rolled back.

Restrictions

The following restrictions apply to the FORALL statement:

■You cannot loop through the elements of an associative array that has a string type for the key.

■Within a FORALL loop, you cannot refer to the same collection in both the SET clause and the WHERE clause of an UPDATE statement. You might need to make a second copy of the collection and refer to the new name in the WHERE clause.

■You can use the FORALL statement only in server-side programs, not in client-side programs.

■The INSERT, UPDATE, or DELETE statement must reference at least one collection. For example, a FORALL statement that inserts a set of constant values in a loop raises an exception.

■When you specify an explicit range, all collection elements in that range must exist. If an element is missing or was deleted, you get an error.

■When you use the INDICES OF or VALUES OF clauses, all the collections referenced in the DML statement must have subscripts matching the values of the index variable. Make sure that any DELETE, EXTEND, and so on operations are applied to all the collections so that they have the same set of subscripts. If any of the collections is missing a referenced element, you get an error. If you use the

PL/SQL Language Elements 13-65

FORALL Statement

SAVE EXCEPTIONS clause, this error is treated like any other error and does not stop the FORALL statement.

■You cannot refer to individual record fields within DML statements called by a FORALL statement. Instead, you can specify the entire record with the SET ROW clause in an UPDATE statement, or the VALUES clause in an INSERT statement.

■Collection subscripts must be just the index variable rather than an expression, such as i rather than i+1.

■The cursor attribute %BULK_ROWCOUNT cannot be assigned to other collections, or be passed as a parameter to subprograms.

Example

You can use the lower and upper bounds to bulk-bind arbitrary slices of a collection:

DECLARE

TYPE NumList IS VARRAY(15) OF NUMBER; depts NumList := NumList();

BEGIN

-- fill varray here

...

FORALL j IN 6..10 -- bulk-bind middle third of varray UPDATE emp SET sal = sal * 1.10 WHERE deptno = depts(j);

END;

Bulk binds apply only to subscripted collections. In the following example, the collection sals, which is passed to the function median, is not bulk-bound:

FORALL i IN 1..20

INSERT INTO emp2 VALUES (enums(i), names(i), median(sals), ...);

Related Topics

"Retrieving Query Results into Collections with the BULK COLLECT Clause" on page 11-15

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

Functions

Functions

A function is a subprogram that can take parameters and return a single value. A function has two parts: the specification and the body. The specification (spec for short) begins with the keyword FUNCTION and ends with the RETURN clause, which specifies the datatype of the return value. Parameter declarations are optional. Functions that take no parameters are written without parentheses. The function body begins with the keyword IS (or AS) and ends with the keyword END followed by an optional function name.

The function body has three parts: an optional declarative part, an executable part, and an optional exception-handling part. The declarative part contains declarations of types, cursors, constants, variables, exceptions, and subprograms. These items are local and cease to exist when you exit the function. The executable part contains statements that assign values, control execution, and manipulate data. The exception-handling part contains handlers that deal with exceptions raised during execution. For more information, see "Understanding PL/SQL Functions" on page 8-3.

Syntax

,

AS

PL/SQL Language Elements 13-67

Functions

:=

expression

DEFAULT

Keyword and Parameter Description

AUTHID

Determines whether a stored function executes with the privileges of its owner (the default) or current user and whether its unqualified references to schema objects are resolved in the schema of the owner or current user. You can override the default behavior by specifying AUTHID CURRENT_USER. For more information, see "Using Invoker's Rights Versus Definer's Rights (AUTHID Clause)" on page 8-15.

CREATE

The optional CREATE clause creates standalone functions, which are stored in the Oracle database. You can execute the CREATE statement interactively from SQL*Plus or from a program using native dynamic SQL.

datatype

A type specifier. For the syntax of datatype, see "Constants and Variables" on page 13-28.

DETERMINISTIC

A hint that helps the optimizer avoid redundant function calls. If a stored function was called previously with the same arguments, the optimizer can elect to use the previous result. The function result should not depend on the state of session variables or schema objects. Otherwise, results might vary across calls. Only DETERMINISTIC functions can be called from a function-based index or a materialized view that has query-rewrite enabled. For more information, see the statements CREATE INDEX and

CREATE MATERIALIZED VIEW in Oracle Database SQL Reference.

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

Functions

exception_handler

Associates an exception with a sequence of statements, which is executed when that exception is raised. For the syntax of exception_handler, see "Exceptions" on page 13-45.

expression

An arbitrarily complex combination of variables, constants, literals, operators, and function calls. The simplest expression consists of a single variable. When the declaration is elaborated, the value of expression is assigned to the parameter. The value and the parameter must have compatible datatypes.

function_name

Specifies the name you choose for the function.

IN, OUT, IN OUT

Parameter modes that define the behavior of formal parameters. An IN parameter passes values to the subprogram being called. An OUT parameter returns values to the caller of the subprogram. An IN OUT parameter passes initial values to the subprogram being called, and returns updated values to the caller.

item_declaration

Declares a program object. For its syntax, see "Blocks" on page 13-8.

NOCOPY

A compiler hint (not directive) that allows the PL/SQL compiler to pass OUT and IN OUT parameters by reference instead of by value (the default). The function can run faster, because it does not have to make temporary copies of these parameters, but the results can be different if the function ends with an unhandled exception. For more information, see "Using Default Values for Subprogram Parameters" on page 8-9.

PARALLEL_ENABLE

Declares that a stored function can be used safely in the slave sessions of parallel DML evaluations. The state of a main (logon) session is never shared with slave sessions. Each slave session has its own state, which is initialized when the session begins. The function result should not depend on the state of session (static) variables. Otherwise, results might vary across sessions.

parameter_name

A formal parameter, a variable declared in a function spec and referenced in the function body.

PRAGMA AUTONOMOUS_TRANSACTION

Marks a function as autonomous. An autonomous transaction is an independent transaction started by the main transaction. Autonomous transactions let you suspend the main transaction, do SQL operations, commit or roll back those operations, then resume the main transaction. For more information, see "Doing Independent Units of Work with Autonomous Transactions" on page 6-35.

procedure_declaration

Declares a procedure. For the syntax of procedure_declaration, see "Procedures" on page 13-104.

PL/SQL Language Elements 13-69

Functions

RETURN

Introduces the RETURN clause, which specifies the datatype of the return value.

type_definition

Specifies a user-defined datatype. For its syntax, see "Blocks" on page 13-8.

:= | DEFAULT

Initializes IN parameters to default values.

Usage Notes

A function is called as part of an expression:

promotable := sal_ok(new_sal, new_title) AND (rating > 3);

To be callable from SQL statements, a stored function must obey certain rules that control side effects. See "Controlling Side Effects of PL/SQL Subprograms" on page 8-22.

In a function, at least one execution path must lead to a RETURN statement. Otherwise, you get a function returned without value error at run time. The RETURN statement must contain an expression, which is evaluated when the RETURN statement is executed.

The resulting value is assigned to the function identifier, which acts like a variable.

You can write the function spec and body as a unit. Or, you can separate the function spec from its body. That way, you can hide implementation details by placing the function in a package. You can define functions in a package body without declaring their specs in the package spec. However, such functions can be called only from inside the package.

Inside a function, an IN parameter acts like a constant; you cannot assign it a value. An OUT parameter acts like a local variable; you can change its value and reference the value in any way. An IN OUT parameter acts like an initialized variable; you can assign it a value, which can be assigned to another variable. For information about the parameter modes, see Table 8–1 on page 8-8.

Avoid using the OUT and IN OUT modes with functions. The purpose of a function is to take zero or more parameters and return a single value. Functions should be free from side effects, which change the values of variables not local to the subprogram.

Example

The following function returns the balance of a specified bank account:

FUNCTION balance (acct_id INTEGER) RETURN REAL IS acct_bal REAL;

BEGIN

SELECT bal INTO acct_bal FROM accts WHERE acctno = acct_id; RETURN acct_bal;

END balance;

Related Topics

Collection Methods, Packages, Procedures

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