Oracle Release 2 (9.2) PL/SQL User's Guide and Reference

EXECUTE IMMEDIATE Statement

EXIT Statement

Expressions

PL/SQL Language Elements

13-1

OPEN-FOR-USING Statement

RESTRICT_REFERENCES Pragma

SET TRANSACTION Statement

SERIALLY_REUSABLE Pragma

13-2

PL/SQL User’s Guide and Reference

Reading the Syntax Diagrams

When you are unsure of the syntax to use in a PL/SQL statement, trace through its syntax diagram, reading from left to right and top to bottom. You can verify or construct any PL/SQL statement that way.

The diagrams are graphic representations of Backus-Naur Form (BNF) productions.

Within the diagrams, keywords are enclosed in boxes, delimiters in circles, and identifiers in ovals.

Each diagram defines a syntactic element. Every path through the diagram describes a possible form of that element. Follow in the direction of the arrows. If a line loops back on itself, you can repeat the element enclosed by the loop.

PL/SQL Language Elements

13-3

Assignment Statement

An assignment statement sets the current value of a variable, field, parameter, or element. The statement consists of an assignment target followed by the assignment operator and an expression. When the statement is executed, the expression is evaluated and the resulting value is stored in the target. For more information, see

"Variable Assignment" on page 2-22.

Syntax assignment_statement

( index ) collection_name cursor_variable_name

: host_cursor_variable_name

: indicator_name

: host_variable_name

attribute_name object_name parameter_name

field_name record_name variable_name

:= expression ;

Keyword and Parameter Description

attribute_name

This identifies an attribute of an object type. The name must be unique within the object type (but can be reused in other object types). You cannot initialize an attribute in its declaration using the assignment operator or

DEFAULT

clause. Also, you cannot impose the

NOT NULL

constraint on an attribute.

13-4

PL/SQL User’s Guide and Reference

Assignment Statement

collection_name

This identifies a nested table, index-by table, or varray previously declared within the current scope.

cursor_variable_name

This identifies a PL/SQL cursor variable previously declared within the current scope. Only the value of another cursor variable can be assigned to a cursor variable.

expression

This is an arbitrarily complex combination of variables, constants, literals, operators, and function calls. The simplest expression consists of a single variable.

For the syntax of expression

, see

"Expressions" on page 13-73. When the

assignment statement is executed, the expression is evaluated and the resulting value is stored in the assignment target. The value and target must have compatible datatypes.

field_name

This identifies a field in a user-defined or

%ROWTYPE

record.

host_cursor_variable_name

This identifies a cursor variable declared in a PL/SQL host environment and passed to PL/SQL as a bind variable. The datatype of the host cursor variable is compatible with the return type of any PL/SQL cursor variable. Host variables must be prefixed with a colon.

host_variable_name

This identifies a variable declared in a PL/SQL host environment and passed to

PL/SQL as a bind variable. Host variables must be prefixed with a colon.

index

This is a numeric expression that must yield a value of type

BINARY_INTEGER

or a value implicitly convertible to that datatype.

PL/SQL Language Elements

13-5

Assignment Statement

indicator_name

This identifies an indicator variable declared in a PL/SQL host environment and passed to PL/SQL. Indicator variables must be prefixed with a colon. An indicator variable "indicates" the value or condition of its associated host variable. For example, in the Oracle Precompiler environment, indicator variables let you detect nulls or truncated values in output host variables.

object_name

This identifies an object (instance of an object type) previously declared within the current scope.

parameter_name

This identifies a formal

OUT

IN OUT

parameter of the subprogram in which the assignment statement appears.

record_name

This identifies a user-defined or

%ROWTYPE

record previously declared within the current scope.

variable_name

This identifies a PL/SQL variable previously declared within the current scope.

Usage Notes

By default, unless a variable is initialized in its declaration, it is initialized to

NULL every time a block or subprogram is entered. So, never reference a variable before you assign it a value.

You cannot assign nulls to a variable defined as

NOT NULL

. If you try, PL/SQL raises the predefined exception

VALUE_ERROR

Only the values

TRUE

FALSE

, and

NULL

can be assigned to a Boolean variable.

When applied to an expression, the relational operators return a Boolean value. So, the following assignment is legal:

DECLARE

out_of_range BOOLEAN;

...

BEGIN

...

out_of_range := (salary < minimum) OR (salary > maximum);

13-6

PL/SQL User’s Guide and Reference

Assignment Statement

As the next example shows, you can assign the value of an expression to a specific field in a record:

DECLARE

emp_rec emp%ROWTYPE;

BEGIN

...

emp_rec.sal := current_salary + increase;

Moreover, you can assign values to all fields in a record at once. PL/SQL allows aggregate assignment between entire records if their declarations refer to the same cursor or table. For example, the following assignment is legal:

DECLARE

emp_rec1 emp%ROWTYPE;

emp_rec2 emp%ROWTYPE;

dept_rec dept%ROWTYPE;

BEGIN

...

emp_rec1 := emp_rec2;

Using the following syntax, you can assign the value of an expression to a specific element in a collection: collection_name(index) := expression;

In the following example, you assign the uppercase value of last_name

to the third row in nested table ename_tab

: ename_tab(3) := UPPER(last_name);

Examples

Several examples of assignment statements follow: wages := hours_worked * hourly_salary; country := ’France’; costs := labor + supplies; done := (count > 100); dept_rec.loc := ’BOSTON’; comm_tab(5) := sales * 0.15;

Related Topics

Expressions ,

"Doing Independent Units of Work with Autonomous Transactions" on page 6-53.

PL/SQL Language Elements

13-7

AUTONOMOUS_TRANSACTION Pragma

The

AUTONOMOUS_TRANSACTION pragma instructs the PL/SQL compiler to mark a routine as autonomous (independent). An autonomous transaction is an independent transaction started by another transaction, 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

Syntax autonomous_transaction_pragma

PRAGMA AUTONOMOUS_TRANSACTION ;

Keyword and Parameter Description

PRAGMA

This keyword signifies that the statement is a pragma (compiler directive). Pragmas are processed at compile time, not at run time. They do not affect the meaning of a program; they simply convey information to the compiler.

Usage Notes

In this context, the term routine includes

■

Top-level (not nested) anonymous PL/SQL blocks

■

Local, standalone, and packaged functions and procedures

Methods of a SQL object type

■

Database triggers

You cannot use the pragma to mark all subprograms in a package (or all methods in an object type) as autonomous. Only individual routines can be marked autonomous. You can code the pragma anywhere in the declarative section of a routine. But, for readability, code the pragma at the top of the section.

13-8

PL/SQL User’s Guide and Reference

AUTONOMOUS_TRANSACTION Pragma

Examples

Unlike regular triggers, autonomous triggers can contain transaction control statements such as

COMMIT

and

ROLLBACK

. Also, unlike regular triggers, autonomous triggers can execute DDL statements (such as

CREATE

and

DROP

) using native dynamic SQL.

Changes made by an autonomous transaction become visible to other transactions when the autonomous transaction commits. The changes also become visible to the main transaction when it resumes, but only if its isolation level is set to

READ

COMMITTED

(the default).

If you set the isolation level of the main transaction to

SERIALIZABLE

, as follows, changes made by its autonomous transactions are not visible to the main transaction when it resumes:

When in the main transaction, rolling back to a savepoint marked before you started an autonomous transaction does not roll back the autonomous transaction.

Remember, autonomous transactions are fully independent of the main transaction.

If you try to exit an active autonomous transaction without committing or rolling back, Oracle raises an exception. If the exception goes unhandled, the transaction is rolled back.

In the following example, you mark a packaged function as autonomous:

CREATE PACKAGE banking AS

...

FUNCTION balance (acct_id INTEGER) RETURN REAL;

END banking;

CREATE PACKAGE BODY banking AS

...

FUNCTION balance (acct_id INTEGER) RETURN REAL IS

PRAGMA AUTONOMOUS_TRANSACTION;

my_bal REAL;

BEGIN

PL/SQL Language Elements

13-9

AUTONOMOUS_TRANSACTION Pragma

...

END;

END banking;

In the example below, you mark a database trigger as autonomous. Unlike regular triggers, autonomous triggers can contain transaction control statements.

CREATE TRIGGER parts_trigger

BEFORE INSERT ON parts FOR EACH ROW

DECLARE

PRAGMA AUTONOMOUS_TRANSACTION;

BEGIN

INSERT INTO parts_log VALUES(:new.pnum, :new.pname);

COMMIT; -- allowed only in autonomous triggers

END;

Related Topics

EXCEPTION_INIT Pragma ,

RESTRICT_REFERENCES Pragma ,

SERIALLY_REUSABLE Pragma

13-10

PL/SQL User’s Guide and Reference

Blocks

The basic program unit in PL/SQL is the block. A PL/SQL block is defined by the keywords

DECLARE

BEGIN

EXCEPTION

, and

END

. These keywords partition the block into a declarative part, an executable part, and an exception-handling part.

Only the executable part is required. You can nest a block within another block wherever you can place an executable statement. For more information, see

"Block

Structure" on page 1-2 and

"Scope and Visibility of PL/SQL Identifiers" on page 2-19.

PL/SQL Language Elements

13-11

Blocks

Syntax plsql_block

<< label_name >> type_definition item_declaration

BEGIN statement

EXCEPTION exception_handler

DECLARE function_declaration procedure_declaration label_name

END

type_definition

record_type_definition ref_cursor_type_definition table_type_definition subtype_definition varray_type_definition

subtype_definition

SUBTYPE subtype_name IS base_type

( constraint )

;

NOT NULL

;

13-12

PL/SQL User’s Guide and Reference

Blocks

item_declaration

collection_declaration constant_declaration cursor_declaration cursor_variable_declaration exception_declaration object_declaration object_ref_declaration record_declaration variable_declaration

sql_statement

commit_statement delete_statement insert_statement lock_table_statement rollback_statement savepoint_statement select_statement set_transaction_statement update_statement

PL/SQL Language Elements

13-13

Blocks

statement

<< label_name >> assignment_statement close_statement execute_immediate_statement exit_statement fetch_statement forall_statement goto_statement if_statement loop_statement null_statement open_statement open_for_statement plsql_block raise_statement return_statement sql_statement

Keyword and Parameter Description

base_type

This is any scalar or user-defined PL/SQL datatype specifier such as

CHAR

DATE

, or

RECORD

BEGIN

This keyword signals the start of the executable part of a PL/SQL block, which contains executable statements. The executable part of a block is required. That is, a

PL/SQL block must contain at least one executable statement. The

NULL

statement meets this requirement.

13-14

PL/SQL User’s Guide and Reference

Blocks

collection_declaration

This declares a collection (index-by table, nested table, or varray). For the syntax of collection_declaration

, see

"Collections" on page 13-29.

constant_declaration

This declares a constant. For the syntax of constant_declaration

, see

"Cursor Variables" on page 13-48.

constraint

This applies only to datatypes that can be constrained such as

CHAR

and

NUMBER

For character datatypes, this specifies a maximum size in bytes. For numeric datatypes, this specifies a maximum precision and scale.

cursor_declaration

This declares an explicit cursor. For the syntax of cursor_declaration

, see

"Cursors" on page 13-54.

cursor_variable_declaration

This declares a cursor variable. For the syntax of cursor_variable_declaration

, see

DECLARE

This keyword signals the start of the declarative part of a PL/SQL block, which contains local declarations. Items declared locally exist only within the current block and all its sub-blocks and are not visible to enclosing blocks. The declarative part of a PL/SQL block is optional. It is terminated implicitly by the keyword

BEGIN

, which introduces the executable part of the block.

PL/SQL does not allow forward references. So, you must declare an item before referencing it in other statements, including other declarative statements. Also, you must declare subprograms at the end of a declarative section after all other program items.

END

This keyword signals the end of a PL/SQL block. It must be the last keyword in a block. Neither the

END IF in an

IF statement nor the

END LOOP in a

LOOP statement can substitute for the keyword

END

. Remember,

END

does not signal the end of a transaction. Just as a block can span multiple transactions, a transaction can span multiple blocks.

PL/SQL Language Elements

13-15

Blocks

EXCEPTION

This keyword signals the start of the exception-handling part of a PL/SQL block.

When an exception is raised, normal execution of the block stops and control transfers to the appropriate exception handler. After the exception handler completes, execution proceeds with the statement following the block.

If there is no exception handler for the raised exception in the current block, control passes to the enclosing block. This process repeats until an exception handler is found or there are no more enclosing blocks. If PL/SQL can find no exception handler for the exception, execution stops and an unhandled exception error is returned to the host environment. For more information, see

Chapter 7

exception_declaration

This declares an exception. For the syntax of exception_declaration

, see

exception_handler

This associates an exception with a sequence of statements, which is executed when that exception is raised. For the syntax of exception_handler

, see

function_declaration

This declares a function. For the syntax of function_declaration

, see

"Object Types" on page 13-122.

label_name

This is an undeclared identifier that optionally labels a PL/SQL block. If used, label_name

must be enclosed by double angle brackets and must appear at the beginning of the block. Optionally, label_name

(not enclosed by angle brackets) can also appear at the end of the block.

A global identifier declared in an enclosing block can be redeclared in a sub-block, in which case the local declaration prevails and the sub-block cannot reference the global identifier unless you use a block label to qualify the reference, as the following example shows:

<<outer>>

DECLARE

x INTEGER;

BEGIN

...

13-16

PL/SQL User’s Guide and Reference

Blocks

DECLARE

x INTEGER;

BEGIN

...

IF x = outer.x THEN -- refers to global x

...

END IF;

END;

END outer;

object_declaration

This declares an object (instance of an object type). For the syntax of object_declaration

, see

procedure_declaration

This declares a procedure. For the syntax of procedure_declaration

, see

"Records" on page 13-152.

record_declaration

This declares a user-defined record. For the syntax of record_declaration

, see

statement

This is an executable (not declarative) statement that you use to create algorithms. A sequence of statements can include procedural statements such as

RAISE

, SQL statements such as

UPDATE

, and PL/SQL blocks (sometimes called "block statements").

PL/SQL statements are free format. That is, they can continue from line to line if you do not split keywords, delimiters, or literals across lines. A semicolon (

;

) serves as the statement terminator.

subtype_name

This identifies a user-defined subtype that was defined using any scalar or user-defined PL/SQL datatype specifier such as

CHAR

DATE

, or

RECORD

variable_declaration

This declares a variable. For the syntax of variable_declaration

, see

PL/SQL Language Elements

13-17

Blocks

PL/SQL supports a subset of SQL statements that includes data manipulation, cursor control, and transaction control statements but excludes data definition and data control statements such as

ALTER

CREATE

GRANT

, and

REVOKE

Example

The following PL/SQL block declares several variables and constants, then calculates a ratio using values selected from a database table:

-- available online in file ’examp11’

DECLARE

numerator NUMBER;

denominator NUMBER;

the_ratio NUMBER;

lower_limit CONSTANT NUMBER := 0.72;

samp_num CONSTANT NUMBER := 132;

BEGIN

SELECT x, y INTO numerator, denominator FROM result_table

WHERE sample_id = samp_num;

the_ratio := numerator/denominator;

IF the_ratio > lower_limit THEN

INSERT INTO ratio VALUES (samp_num, the_ratio);

ELSE

INSERT INTO ratio VALUES (samp_num, -1);

END IF;

COMMIT;

EXCEPTION

WHEN ZERO_DIVIDE THEN

INSERT INTO ratio VALUES (samp_num, 0);

COMMIT;

WHEN OTHERS THEN

ROLLBACK;

END;

Related Topics

Exceptions ,

Functions

"CASE Expressions" on page 2-31, NULLIF and COALESCE expressions in Oracle9i SQL Reference

13-18

PL/SQL User’s Guide and Reference

CASE Statement

The

CASE

statement selects a sequence of statements to execute. To select the sequence, the

CASE

statement uses a selector (an expression whose value is used to select one of several alternatives) or, in the searched

CASE

statement, multiple search conditions.

Syntax searched_case_statement ::=

[ <<label_name>> ]

CASE { WHEN boolean_expression THEN {statement;} ... }...

[ ELSE { statement;}... ]

END CASE [ label_name ];

simple_case_statement ::=

[ <<label_name>> ]

CASE case_operand

{ WHEN when_operand THEN {statement;} ... }...

[ ELSE { statement;}... ]

END CASE [ label_name ];

Keyword and Parameter Description

The value of the

CASE

operand and

WHEN

operands in a simple

CASE

statement can be any PL/SQL type other than

BLOB

BFILE

, an object type, a PL/SQL record, an index-by-table, a varray, or a nested table.

If the

ELSE

clause is omitted, the system substitutes a default action. For a

CASE statement, the default when none of the conditions matches is to raise a

CASE_NOT_FOUND

exception. For a CASE expression, the default is to return

NULL

PL/SQL Language Elements

13-19

CASE Statement

Usage Notes

Each

WHEN

clause is executed only once.

The

WHEN

clauses are executed in order.

After a matching

WHEN

clause is found, subsequent

WHEN

clauses are not executed.

Because the execution order of the

WHEN

clauses is defined by the preceding rules, the statements in a

WHEN

clause are allowed to modify the database and call non-deterministic functions.

There is no "fall-through" as in the C switch

statement. Once a

WHEN

clause is matched and its statements are executed, the

CASE

statement ends.

The

CASE

statement is appropriate when there is some different action to be taken for each alternative. If you just need to choose among several values to assign to a variable, you can code an assignment statement using a

CASE

expression instead.

Examples

The following example shows a simple

CASE

statement. Notice that you can use multiple statements after a

WHEN

clause.

DECLARE

n number;

BEGIN

CASE n

WHEN 1 THEN dbms_output.put_line(’n = 1’);

WHEN 2 THEN

dbms_output.put_line(’n = 2’);

dbms_output.put_line(’That implies n > 1’);

ELSE dbms_output.put_line(’n is some other value.’);

END CASE;

END;

The following example shows a searched

CASE

statement. Notice that the

WHEN clauses can use different conditions rather than all testing the same variable or using the same operator. Because this example does not use an

ELSE

clause, an exception is raised if none of the

WHEN

conditions are met.

DECLARE

quantity NUMBER;

projected NUMBER;

needed NUMBER;

BEGIN

<<here>>

13-20

PL/SQL User’s Guide and Reference

CASE Statement

CASE

WHEN quantity is null THEN

dbms_output.put_line(’Quantity not available’);

WHEN quantity + projected >= needed THEN

dbms_output.put_line(’Quantity ’ || quantity ||

’ should be enough if projections are met.’);

WHEN quantity >= 0 THEN

dbms_output.put_line(’Quantity ’ || quantity || ’ is probably not enough.’);

END CASE here;

EXCEPTION

WHEN CASE_NOT_FOUND THEN

dbms_output.put_line(’Somehow quantity must be less than 0.’)

END;

PL/SQL Language Elements

13-21

CLOSE Statement

The

statement allows resources held by an open cursor or cursor variable to be reused. No more rows can be fetched from a closed cursor or cursor variable. For more information, see

"Using Collection Methods" on page 5-28.

Syntax close_statement

CLOSE cursor_name cursor_variable_name

: host_cursor_variable_name

;

Keyword and Parameter Description

cursor_name

This identifies an explicit cursor previously declared within the current scope and currently open.

cursor_variable_name

This identifies a PL/SQL cursor variable (or parameter) previously declared within the current scope and currently open.

host_cursor_variable_name

Usage Notes

Once a cursor or cursor variable is closed, you can reopen it using the

OPEN

OPEN-FOR

statement, respectively. If you reopen a cursor without closing it first,

PL/SQL raises the predefined exception

CURSOR_ALREADY_OPEN

. However, you need not close a cursor variable before reopening it.

13-22

PL/SQL User’s Guide and Reference

CLOSE Statement

If you try to close an already-closed or never-opened cursor or cursor variable,

PL/SQL raises the predefined exception

INVALID_CURSOR

Example

In the following example, after the last row is fetched and processed, you close the cursor variable emp_cv

LOOP

FETCH emp_cv INTO emp_rec;

EXIT WHEN emp_cv%NOTFOUND;

... -- process data record

END LOOP;

/* Close cursor variable. */

CLOSE emp_cv;

Related Topics

FETCH Statement ,

OPEN Statement

OPEN-FOR Statement

PL/SQL Language Elements

13-23

Collection Methods

A collection method is a built-in function or procedure that operates on collections and is called using dot notation. The methods

EXISTS

COUNT

LIMIT

FIRST

LAST

PRIOR

EXTEND

TRIM

, and

DELETE

help generalize code, make collections easier to use, and make your applications easier to maintain.

EXISTS

COUNT

LIMIT

FIRST

LAST

PRIOR

, and

are functions, which appear as part of an expression.

EXTEND

TRIM

, and

DELETE

are procedures, which appear as a statement.

EXISTS

PRIOR

TRIM

EXTEND

, and

DELETE

take integer parameters.

EXISTS

PRIOR

, and

DELETE

can also take

VARCHAR2 parameters for associative arrays with string keys.

EXTEND

and

TRIM

cannot be used with index-by tables.

For more information, see

Syntax collection_method_call

collection_name .

COUNT

( index

DELETE

EXISTS ( index )

( number

EXTEND

FIRST

LAST

LIMIT

PRIOR

( index )

( number )

TRIM

, index

)

13-24

PL/SQL User’s Guide and Reference

Collection Methods

Keyword and Parameter Description

collection_name

This identifies an index-by table, nested table, or varray previously declared within the current scope.

COUNT

returns the number of elements that a collection currently contains, which is useful because the current size of a collection is not always known. You can use

COUNT

wherever an integer expression is allowed.

For varrays,

COUNT

always equals

LAST

. For nested tables, normally,

COUNT

equals

LAST

. But, if you delete elements from the middle of a nested table,

COUNT

is smaller than

LAST

DELETE

This procedure has three forms.

DELETE

removes all elements from a collection.

DELETE(n)

removes the n th element from an index-by table or nested table. If n

is null,

DELETE(n)

does nothing.

DELETE(m,n)

removes all elements in the range m..n

from an index-by table or nested table. If m

is larger than n

or if m

or n

is null,

DELETE(m,n)

does nothing.

EXISTS

EXISTS(n)

returns

TRUE

if the n th element in a collection exists. Otherwise,

EXISTS(n)

returns

FALSE

. Mainly, you use

EXISTS

with

DELETE

to maintain sparse nested tables. You can also use

EXISTS

to avoid raising an exception when you reference a nonexistent element. When passed an out-of-range subscript,

EXISTS

returns

FALSE

instead of raising

SUBSCRIPT_OUTSIDE_LIMIT

EXTEND

This procedure has three forms.

EXTEND

appends one null element to a collection.

EXTEND(n)

appends n

null elements to a collection.

EXTEND(n,i)

appends n copies of the i th element to a collection.

EXTEND

operates on the internal size of a collection. So, if

EXTEND

encounters deleted elements, it includes them in its tally.

You cannot use

EXTEND

with index-by tables.

FIRST, LAST

FIRST and

LAST return the first and last (smallest and largest) subscript values in a collection. The subscript values are usually integers, but can also be strings for

PL/SQL Language Elements

13-25

Collection Methods associative arrays. If the collection is empty,

FIRST

and

LAST

return

NULL

. If the collection contains only one element,

FIRST

and

LAST

return the same subscript value.

For varrays,

FIRST

always returns 1 and

LAST

always equals

COUNT

. For nested tables, normally,

LAST equals

COUNT

. But, if you delete elements from the middle of a nested table,

LAST

is larger than

COUNT

index

This is an expression that must yield (or convert implicitly to) an integer in most cases, or a string for an associative array declared with string keys.

LIMIT

For nested tables, which have no maximum size,

LIMIT

returns

NULL

. For varrays,

LIMIT

returns the maximum number of elements that a varray can contain (which you must specify in its type definition).

NEXT, PRIOR

PRIOR(n)

returns the subscript that precedes index n

in a collection.

NEXT(n) returns the subscript that succeeds index n

. If n

has no predecessor,

PRIOR(n) returns

NULL

. Likewise, if n

has no successor,

NEXT(n)

returns

NULL

TRIM

This procedure has two forms.

TRIM

removes one element from the end of a collection.

TRIM(n)

removes n

elements from the end of a collection. If n

is greater than

COUNT

TRIM(n)

raises

SUBSCRIPT_BEYOND_COUNT

. You cannot use

TRIM with index-by tables.

TRIM

operates on the internal size of a collection. So, if

TRIM

encounters deleted elements, it includes them in its tally.

Usage Notes

You cannot use collection methods in a SQL statement. If you try, you get a compilation error.

Only

EXISTS

can be applied to atomically null collections. If you apply another method to such collections, PL/SQL raises

COLLECTION_IS_NULL

You can use

PRIOR

to traverse collections indexed by any series of subscripts. For example, you can use

PRIOR

to traverse a nested table from which some elements have been deleted.

13-26

PL/SQL User’s Guide and Reference

Collection Methods

Examples

EXTEND

operates on the internal size of a collection, which includes deleted elements. You cannot use

EXTEND

to initialize an atomically null collection. Also, if you impose the

NOT NULL constraint on a

TABLE or

VARRAY type, you cannot apply the first two forms of

EXTEND

to collections of that type.

If an element to be deleted does not exist,

DELETE

simply skips it; no exception is raised. Varrays are dense, so you cannot delete their individual elements.

PL/SQL keeps placeholders for deleted elements. So, you can replace a deleted element simply by assigning it a new value. However, PL/SQL does not keep placeholders for trimmed elements.

The amount of memory allocated to a nested table can increase or decrease dynamically. As you delete elements, memory is freed page by page. If you delete the entire table, all the memory is freed.

In general, do not depend on the interaction between

TRIM

and

DELETE

. It is better to treat nested tables like fixed-size arrays and use only

DELETE

, or to treat them like stacks and use only

TRIM

and

EXTEND

Within a subprogram, a collection parameter assumes the properties of the argument bound to it. So, you can apply methods

FIRST

LAST

COUNT

, and so on to such parameters. For varray parameters, the value of

LIMIT

is always derived from the parameter type definition, regardless of the parameter mode.

In the following example, you use

to traverse a nested table from which some elements have been deleted: i := courses.FIRST; -- get subscript of first element

WHILE i IS NOT NULL LOOP

-- do something with courses(i)

i := courses.NEXT(i); -- get subscript of next element

END LOOP;

In the following example, PL/SQL executes the assignment statement only if element i

exists:

IF courses.EXISTS(i) THEN

courses(i) := new_course;

END IF;

The next example shows that you can use

FIRST and

LAST to specify the lower and upper bounds of a loop range provided each element in that range exists:

PL/SQL Language Elements

13-27

Collection Methods

FOR i IN courses.FIRST..courses.LAST LOOP ...

In the following example, you delete elements 2 through 5 from a nested table: courses.DELETE(2, 5);

In the final example, you use

LIMIT

to determine if you can add 20 more elements to varray projects

IF (projects.COUNT + 20) < projects.LIMIT THEN

-- add 20 more elements

Related Topics

Collections ,

"Defining Collection Types" on page 5-7.

13-28

PL/SQL User’s Guide and Reference

Collections

A collection is an ordered group of elements, all of the same type (for example, the grades for a class of students). Each element has a unique subscript that determines its position in the collection. PL/SQL offers three kinds of collections: associative arrays, nested tables, and varrays (short for variable-size arrays). Nested tables extend the functionality of associative arrays (formerly called "PL/SQL tables" or

"index-by tables").

Collections work like the arrays found in most third-generation programming languages. Collections can have only one dimension. Most collections are indexed by integers, although associative arrays can also be indexed by strings. To model multi-dimensional arrays, you can declare collections whose items are other collections.

Nested tables and varrays can store instances of an object type and, conversely, can be attributes of an object type. Also, collections can be passed as parameters. So, you can use them to move columns of data into and out of database tables or between client-side applications and stored subprograms.

For more information, see

PL/SQL Language Elements

13-29

Collections

Syntax table_type_definition

TYPE type_name IS TABLE OF element_type

INDEX BY BINARY_INTEGER

;

varray_type_definition

TYPE type_name IS

OF element_type

VARRAY

VARRYING ARRAY

NOT NULL

;

NOT NULL

( size_limit )

collection_declaration

collection_name type_name ;

13-30

PL/SQL User’s Guide and Reference

Collections

element_type

cursor_name db_table_name

% ROWTYPE

column_name

% TYPE object_name

REF object_type_name

field_name record_name record_type_name scalar_datatype_name variable_name % TYPE

% TYPE

Keyword and Parameter Description

element_type

This is any PL/SQL datatype except

BINARY_INTEGER

BOOLEAN

LONG

RAW

NATURAL

NATURALN

PLS_INTEGER

POSITIVE

POSITIVEN

REF CURSOR

SIGNTYPE

, or

STRING

. Also, with varrays, element_type

cannot be

BLOB

CLOB

, or an object type with

BLOB

CLOB

attributes.

INDEX BY type_name

This optional clause lets you define associative arrays, where you specify the subscript values to use rather than the system defining them in sequence.

type_name

can be

BINARY_INTEGER

PLS_INTEGER

, or a string type such as

VARCHAR2

size_limit

This is a positive integer literal that specifies the maximum size of a varray, which is the maximum number of elements the varray can contain.

PL/SQL Language Elements

13-31

Collections

type_name

This identifies a user-defined collection type that was defined using the datatype specifier

TABLE

VARRAY

Usage Notes

Nested tables extend the functionality of index-by tables, so they differ in several ways. See

"Choosing Between Nested Tables and Associative Arrays" on page 5-6.

Every element reference includes the collection name and one or more subscripts enclosed in parentheses; the subscripts determine which element is processed.

Except for associative arrays, which can have negative subscripts, collection subscripts have a fixed lower bound of 1. Subscripts for multilevel collections are evaluated in any order; if a subscript includes an expression that modifies the value of a different subscript, the result is undefined.

You can define all three collection types in the declarative part of any PL/SQL block, subprogram, or package. But, only nested table and varray types can be

CREATE d and stored in an Oracle database.

Associative arrays and nested tables can be sparse (have non-consecutive subscripts), but varrays are always dense (have consecutive subscripts). Unlike nested tables, varrays retain their ordering and subscripts when stored in the database.

Initially, associative arrays are sparse. That enables you, for example, to store reference data in a temporary variable using a primary key (account numbers or employee numbers for example) as the index.

Collections follow the usual scoping and instantiation rules. In a package, collections are instantiated when you first reference the package and cease to exist when you end the database session. In a block or subprogram, local collections are instantiated when you enter the block or subprogram and cease to exist when you exit.

Until you initialize it, a nested table or varray is atomically null (that is, the collection itself is null, not its elements). To initialize a nested table or varray, you use a constructor, which is a system-defined function with the same name as the collection type. This function "constructs" a collection from the elements passed to it.

Because nested tables and varrays can be atomically null, they can be tested for nullity. However, they cannot be compared for equality or inequality. This restriction also applies to implicit comparisons. For example, collections cannot appear in a

DISTINCT

GROUP BY

, or

ORDER BY

list.

13-32

PL/SQL User’s Guide and Reference

Collections

Examples

Collections can store instances of an object type and, conversely, can be attributes of an object type. Also, collections can be passed as parameters. So, you can use them to move columns of data into and out of database tables or between client-side applications and stored subprograms.

When calling a function that returns a collection, you use the following syntax to reference elements in the collection: collection_name(parameter_list)(subscript)

With the Oracle Call Interface (OCI) or the Oracle Precompilers, you can bind host arrays to index-by tables declared as the formal parameters of a subprogram. That lets you pass host arrays to stored functions and procedures.

To specify the element type of a collection, you can use

%TYPE

%ROWTYPE

, as the following example shows:

DECLARE

TYPE JobList IS VARRAY(10) OF emp.job%TYPE; -- based on column

CURSOR c1 IS SELECT * FROM dept;

TYPE DeptFile IS TABLE OF c1%ROWTYPE; -- based on cursor

TYPE EmpFile IS VARRAY(150) OF emp%ROWTYPE; -- based on database table

In the next example, you use a

RECORD

type to specify the element type:

DECLARE

TYPE Entry IS RECORD (

term VARCHAR2(20),

meaning VARCHAR2(200));

TYPE Glossary IS VARRAY(250) OF Entry;

In the example below, you declare an index-by table of records. Each element of the table stores a row from the emp

database table.

DECLARE

TYPE EmpTabTyp IS TABLE OF emp%ROWTYPE

INDEX BY BINARY_INTEGER;

emp_tab EmpTabTyp;

BEGIN

/* Retrieve employee record. */

SELECT * INTO emp_tab(7468) FROM emp WHERE empno = 7468;

PL/SQL Language Elements

13-33

Collections

When defining a

VARRAY type, you must specify its maximum size. In the following example, you define a type that stores up to 366 dates:

DECLARE

TYPE Calendar IS VARRAY(366) OF DATE;

Once you define a collection type, you can declare collections of that type, as the following SQL*Plus script shows:

CREATE TYPE Project AS OBJECT(

project_no NUMBER(2),

title VARCHAR2(35),

cost NUMBER(7,2))

CREATE TYPE ProjectList AS VARRAY(50) OF Project -- VARRAY type

CREATE TABLE department (

idnum NUMBER(2),

name VARCHAR2(15),

budget NUMBER(11,2),

projects ProjectList) -- declare varray

The identifier projects

represents an entire varray. Each element of projects will store a

Project

object.

In the following example, you declare a nested table as the formal parameter of a packaged procedure:

CREATE PACKAGE personnel AS

TYPE Staff IS TABLE OF Employee;

...

PROCEDURE award_bonuses (members IN Staff);

You can specify a collection type in the

RETURN

clause of a function spec, as the following example shows:

DECLARE

TYPE SalesForce IS VARRAY(20) OF Salesperson;

FUNCTION top_performers (n INTEGER) RETURN SalesForce IS ...

13-34

PL/SQL User’s Guide and Reference

Collections

In the following example, you update the list of projects assigned to the Security

Department:

DECLARE

new_projects ProjectList :=

ProjectList(Project(1, ’Issue New Employee Badges’, 13500),

Project(2, ’Inspect Emergency Exits’, 1900),

Project(3, ’Upgrade Alarm System’, 3350),

Project(4, ’Analyze Local Crime Stats’, 825));

BEGIN

UPDATE department

SET projects = new_projects WHERE name = ’Security’;

In the next example, you retrieve all the projects for the Accounting Department into a local varray:

DECLARE

my_projects ProjectList;

BEGIN

SELECT projects INTO my_projects FROM department

WHERE name = ’Accounting’;

Related Topics

Collection Methods ,

Object Types

Records

PL/SQL Language Elements

13-35

Comments

Comments describe the purpose and use of code segments and so promote readability. PL/SQL supports two comment styles: single-line and multi-line.

Single-line comments begin with a double hyphen (

- -

) anywhere on a line and extend to the end of the line. Multi-line comments begin with a slash-asterisk (

), end with an asterisk-slash (

), and can span multiple lines. For more information, see

"Comments" on page 2-10.

Syntax comment

text

/* text */

Usage Notes

Comments can appear within a statement at the end of a line. However, you cannot nest comments.

You cannot use single-line comments in a PL/SQL block that will be processed dynamically by an Oracle Precompiler program because end-of-line characters are ignored. As a result, single-line comments extend to the end of the block, not just to the end of a line. Instead, use multi-line comments.

While testing or debugging a program, you might want to disable a line of code.

The following example shows how you can "comment-out" the line:

-- UPDATE dept SET loc = my_loc WHERE deptno = my_deptno;

You can use multi-line comment delimiters to comment-out whole sections of code.

Examples

The following examples show various comment styles:

-- compute the area of a circle area := pi * radius**2; -- pi equals 3.14159

/* Compute the area

of a circle. */ area := pi * radius**2; /* pi equals 3.14159 */

13-36

PL/SQL User’s Guide and Reference

COMMIT Statement

The

COMMIT

statement explicitly makes permanent any changes made to the database during the current transaction. Changes made to the database are not considered permanent until they are committed. A commit also makes the changes visible to other users. For more information, see

"Overview of Transaction

Processing in PL/SQL" on page 6-43.

Syntax commit_statement

WORK COMMENT ’ text ’

COMMIT ;

Keyword and Parameter Description

COMMENT

This keyword specifies a comment to be associated with the current transaction and is typically used with distributed transactions. The text must be a quoted literal no more than 50 characters long.

WORK

This keyword is optional and has no effect except to improve readability.

Usage Notes

The

COMMIT statement releases all row and table locks. It also erases any savepoints you marked since the last commit or rollback. Until your changes are committed, the following conditions hold:

■

You can see the changes when you query the tables you modified, but other users cannot see the changes.

If you change your mind or need to correct a mistake, you can use the

ROLLBACK

statement to roll back (undo) the changes.

PL/SQL Language Elements

13-37

COMMIT Statement

If you commit while a

FOR UPDATE

cursor is open, a subsequent fetch on that cursor raises an exception. The cursor remains open, however, so you should close it. For more information, see

"Using FOR UPDATE" on page 6-50.

When a distributed transaction fails, the text specified by

COMMENT

helps you diagnose the problem. If a distributed transaction is ever in doubt, Oracle stores the text in the data dictionary along with the transaction ID. For more information about distributed transactions, see Oracle9i Database Concepts.

In SQL, the

FORCE

clause manually commits an in-doubt distributed transaction.

However, PL/SQL does not support this clause. For example, the following statement is not allowed:

COMMIT WORK FORCE ’23.51.54’; -- not allowed

In embedded SQL, the

RELEASE

option frees all Oracle resources (locks and cursors) held by a program and disconnects from the database. However, PL/SQL does not support this option. For example, the following statement is not allowed:

COMMIT WORK RELEASE; -- not allowed

Related Topics

ROLLBACK Statement ,

SAVEPOINT Statement

13-38

PL/SQL User’s Guide and Reference

Constants and Variables

You can declare constants and variables in the declarative part of any PL/SQL block, subprogram, or package. Declarations allocate storage space for a value, specify its datatype, and name the storage location so that you can reference it.

Declarations can also assign an initial value and impose the

NOT NULL

constraint.

For more information, see

"Declarations" on page 2-11.

Syntax variable_declaration

NOT NULL variable_name datatype

datatype

collection_name % collection_type_name db_table_name

TYPE cursor_name % ROWTYPE cursor_variable_name % TYPE

% ROWTYPE

column_name % TYPE object_name

REF

% TYPE object_type_name record_name % TYPE record_type_name ref_cursor_type_name scalar_datatype_name variable_name % TYPE

DEFAULT expression

;

PL/SQL Language Elements

13-39

Constants and Variables

constant_declaration

constant_name CONSTANT datatype

NOT NULL

DEFAULT expression ;

Keyword and Parameter Description

collection_name

Identifies a collection (index-by table, nested table, or varray) previously declared within the current scope.

collection_type_name

Identifies a user-defined collection type that was defined using the datatype specifier

TABLE

VARRAY

CONSTANT

Denotes the declaration of a constant. You must initialize a constant in its declaration. Once initialized, the value of a constant cannot be changed.

constant_name

Identifies a program constant. For naming conventions, see

"Identifiers" on page 2-4.

cursor_name

Identifies an explicit cursor previously declared within the current scope.

cursor_variable_name

Identifies a PL/SQL cursor variable previously declared within the current scope.

db_table_name

A database table or view that must be accessible when the declaration is elaborated.

db_table_name.column_name

A database table and column that must be accessible when the declaration is elaborated.

13-40

PL/SQL User’s Guide and Reference

Constants and Variables

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 constant or variable. The value and the constant or variable must have compatible datatypes.

NOT NULL

This constraint prevents the assigning of nulls to a variable or constant. At run time, trying to assign a null to a variable defined as

NOT NULL

raises the predefined exception

VALUE_ERROR

. The constraint

NOT NULL

must be followed by an initialization clause.

object_name

Identifies an instance of an object type previously declared within the current scope.

record_name

Identifies a user-defined or

%ROWTYPE

record previously declared within the current scope.

record_name.field_name

Identifies a field in a user-defined or

%ROWTYPE

record previously declared within the current scope.

record_type_name

Identifies a user-defined record type that is defined using the datatype specifier

RECORD

ref_cursor_type_name

Identifies a user-defined cursor variable type is was defined using the datatype specifier

REF CURSOR

%ROWTYPE

This attribute provides a record type that represents a row in a database table or a row fetched from a previously declared cursor. Fields in the record and corresponding columns in the row have the same names and datatypes.

PL/SQL Language Elements

13-41

Constants and Variables

scalar_datatype_name

Identifies a predefined scalar datatype such as

BOOLEAN

NUMBER

, or

VARCHAR2

Includes any qualifiers for size, precision, or character versus byte semantics.

%TYPE

This attribute provides the datatype of a previously declared collection, cursor variable, field, object, record, database column, or variable.

variable_name

Identifies a program variable.

Usage Notes

Constants and variables are initialized every time a block or subprogram is entered.

By default, variables are initialized to

NULL

. So, unless you expressly initialize a variable, its value is undefined.

Whether public or private, constants and variables declared in a package spec are initialized only once for each session.

An initialization clause is required when declaring

NOT NULL

variables and when declaring constants. If you use

%ROWTYPE

to declare a variable, initialization is not allowed.

Examples

Several examples of variable and constant declarations follow: credit_limit CONSTANT NUMBER := 5000; invalid BOOLEAN := FALSE; acct_id INTEGER(4) NOT NULL DEFAULT 9999; pi CONSTANT REAL := 3.14159; postal_code VARCHAR2(20); last_name VARCHAR2(20 CHAR); my_ename emp.ename%TYPE;

Related Topics

"Declarations" on page 2-11,

"Predefined Datatypes" on page 3-2,

13-42

PL/SQL User’s Guide and Reference

Cursor Attributes

Every explicit cursor and cursor variable has four attributes:

%FOUND

%ISOPEN

%NOTFOUND

, and

%ROWCOUNT

. When appended to the cursor or cursor variable, these attributes return useful information about the execution of a data manipulation statement. For more information, see

"Using Cursor Attributes" on page 6-34.

The implicit cursor

SQL

has additional attributes,

%BULK_ROWCOUNT

and

%BULK_EXCEPTIONS

. For more information, see

"SQL Cursor" on page 13-175.

Syntax cursor_attribute

cursor_name cursor_variable_name

: host_cursor_variable_name

FOUND

ISOPEN

NOTFOUND

ROWCOUNT

Keyword and Parameter Description

cursor_name

This identifies an explicit cursor previously declared within the current scope.

cursor_variable_name

This identifies a PL/SQL cursor variable (or parameter) previously declared within the current scope.

%FOUND Attribute

This is a cursor attribute that can be appended to the name of a cursor or cursor variable. Before the first fetch from an open cursor, cursor_name%FOUND

yields

NULL

. Thereafter, it yields

TRUE

if the last fetch returned a row, or

FALSE

if the last fetch failed to return a row.

PL/SQL Language Elements

13-43

Cursor Attributes

host_cursor_variable_name

%ISOPEN Attribute

This is a cursor attribute that can be appended to the name of a cursor or cursor variable. If a cursor is open, cursor_name%ISOPEN

yields

TRUE

; otherwise, it yields

FALSE

%NOTFOUND Attribute

This is a cursor attribute that can be appended to the name of a cursor or cursor variable. Before the first fetch from an open cursor, cursor_name%NOTFOUND yields

NULL

. Thereafter, it yields

FALSE

if the last fetch returned a row, or

TRUE

if the last fetch failed to return a row.

%ROWCOUNT Attribute

This is a cursor attribute that can be appended to the name of a cursor or cursor variable. When a cursor is opened,

%ROWCOUNT

is zeroed. Before the first fetch, cursor_name%ROWCOUNT yields 0. Thereafter, it yields the number of rows fetched so far. The number is incremented if the latest fetch returned a row.

Usage Notes

The cursor attributes apply to every cursor or cursor variable. So, for example, you can open multiple cursors, then use

%FOUND

%NOTFOUND

to tell which cursors have rows left to fetch. Likewise, you can use

%ROWCOUNT

to tell how many rows have been fetched so far.

If a cursor or cursor variable is not open, referencing it with

%FOUND

%NOTFOUND

, or

%ROWCOUNT

raises the predefined exception

INVALID_CURSOR

When a cursor or cursor variable is opened, the rows that satisfy the associated query are identified and form the result set. Rows are fetched from the result set one at a time.

If a

SELECT INTO

statement returns more than one row, PL/SQL raises the predefined exception

TOO_MANY_ROWS

and sets

%ROWCOUNT

to 1, not the actual number of rows that satisfy the query.

13-44

PL/SQL User’s Guide and Reference

Cursor Attributes

Examples

Before the first fetch,

%NOTFOUND

evaluates to

NULL

. So, if

FETCH

never executes successfully, the loop is never exited. That is because the

EXIT WHEN

statement executes only if its

WHEN

condition is true. To be safe, you might want to use the following

EXIT

statement instead:

EXIT WHEN c1%NOTFOUND OR c1%NOTFOUND IS NULL;

You can use the cursor attributes in procedural statements but not in SQL statements.

The PL/SQL block below uses

%FOUND

to select an action. The

statement either inserts a row or exits the loop unconditionally.

-- available online in file ’examp12’

DECLARE

CURSOR num1_cur IS SELECT num FROM num1_tab

ORDER BY sequence;

CURSOR num2_cur IS SELECT num FROM num2_tab

ORDER BY sequence;

num1 num1_tab.num%TYPE;

num2 num2_tab.num%TYPE;

pair_num NUMBER := 0;

BEGIN

OPEN num1_cur;

OPEN num2_cur;

LOOP -- loop through the two tables and get pairs of numbers

FETCH num1_cur INTO num1;

FETCH num2_cur INTO num2;

IF (num1_cur%FOUND) AND (num2_cur%FOUND) THEN

pair_num := pair_num + 1;

INSERT INTO sum_tab VALUES (pair_num, num1 + num2);

ELSE

EXIT;

END IF;

END LOOP;

CLOSE num1_cur;

CLOSE num2_cur;

END;

PL/SQL Language Elements

13-45

Cursor Attributes

The next example uses the same block. However, instead of using

%FOUND

in an

IF statement, it uses

%NOTFOUND

in an

EXIT WHEN

statement.

-- available online in file ’examp13’

DECLARE

CURSOR num1_cur IS SELECT num FROM num1_tab

ORDER BY sequence;

CURSOR num2_cur IS SELECT num FROM num2_tab

ORDER BY sequence;

num1 num1_tab.num%TYPE;

num2 num2_tab.num%TYPE;

pair_num NUMBER := 0;

BEGIN

OPEN num1_cur;

OPEN num2_cur;

LOOP -- loop through the two tables and get

-- pairs of numbers

FETCH num1_cur INTO num1;

FETCH num2_cur INTO num2;

EXIT WHEN (num1_cur%NOTFOUND) OR (num2_cur%NOTFOUND);

pair_num := pair_num + 1;

INSERT INTO sum_tab VALUES (pair_num, num1 + num2);

END LOOP;

CLOSE num1_cur;

CLOSE num2_cur;

END;

In the following example, you use

%ISOPEN

to make a decision:

IF NOT (emp_cur%ISOPEN) THEN

OPEN emp_cur;

END IF;

FETCH emp_cur INTO emp_rec;

The following PL/SQL block uses

%ROWCOUNT to fetch the names and salaries of the five highest-paid employees:

-- available online in file ’examp14’

DECLARE

CURSOR c1 is

SELECT ename, empno, sal FROM emp

ORDER BY sal DESC; -- start with highest-paid employee

my_ename CHAR(10);

my_empno NUMBER(4);

my_sal NUMBER(7,2);

13-46

PL/SQL User’s Guide and Reference

Cursor Attributes

BEGIN

OPEN c1;

LOOP

FETCH c1 INTO my_ename, my_empno, my_sal;

EXIT WHEN (c1%ROWCOUNT > 5) OR (c1%NOTFOUND);

INSERT INTO temp VALUES (my_sal, my_empno, my_ename);

COMMIT;

END LOOP;

CLOSE c1;

END;

In the final example, you use

%ROWCOUNT

to raise an exception if an unexpectedly high number of rows is deleted:

DELETE FROM accts WHERE status = ’BAD DEBT’;

IF SQL%ROWCOUNT > 10 THEN

RAISE out_of_bounds;

END IF;

Related Topics

Cursors ,

Cursor Variables

PL/SQL Language Elements

13-47

Cursor Variables

REF CURSOR

type, then declare cursor variables of that type.

Cursor variables are like C or Pascal pointers, which hold the memory location

(address) of some item instead of the item itself. So, declaring a cursor variable creates a pointer, not an item.

For more information, see

"Using Cursor Variables" on page 6-16.

Syntax ref_cursor_type_definition

TYPE type_name IS REF CURSOR

RETURN db_table_name cursor_name cursor_variable_name record_name % TYPE

% ROWTYPE record_type_name ref_cursor_type_name

;

cursor_variable_declaration

cursor_variable_name type_name ;

13-48

PL/SQL User’s Guide and Reference

Cursor Variables

Keyword and Parameter Description

cursor_name

This identifies an explicit cursor previously declared within the current scope.

cursor_variable_name

This identifies a PL/SQL cursor variable previously declared within the current scope.

db_table_name

This identifies a database table (or view) that must be accessible when the declaration is elaborated.

record_name

This identifies a user-defined record previously declared within the current scope.

record_type_name

This identifies a user-defined record type that was defined using the datatype specifier

RECORD

REF CURSOR

In PL/SQL, pointers have datatype

REF X

, where

REF

is short for

REFERENCE

and

stands for a class of objects. Therefore, cursor variables have datatype

REF

CURSOR

RETURN

This keyword introduces the

RETURN

clause, which specifies the datatype of a cursor variable return value. You can use the

%ROWTYPE

attribute in the

RETURN clause to provide a record type that represents a row in a database table or a row returned by a cursor or strongly typed cursor variable. Also, you can use the

%TYPE attribute to provide the datatype of a previously declared record.

%ROWTYPE

This attribute provides a record type that represents a row in a database table or a row fetched from a cursor or strongly typed cursor variable. Fields in the record and corresponding columns in the row have the same names and datatypes.

PL/SQL Language Elements

13-49

Cursor Variables

%TYPE

This attribute provides the datatype of a previously declared user-defined record.

type_name

This is a user-defined cursor variable type that was defined using the datatype specifier

REF CURSOR

Usage Notes

Cursor variables are available to every PL/SQL client. For example, you can declare a cursor variable in a PL/SQL host environment such as an OCI or Pro*C program, then pass it as a bind variable to PL/SQL. Moreover, application development tools such as Oracle Forms and Oracle Reports, which have a PL/SQL engine, can use cursor variables entirely on the client side.

The Oracle database server also has a PL/SQL engine. So, you can pass cursor variables back and forth between an application and server through remote procedure calls (RPCs). And, if you have a PL/SQL engine on the client side, calls from client to server impose no restrictions. For example, you can declare a cursor variable on the client side, open and fetch from it on the server side, then continue to fetch from it back on the client side.

REF CURSOR

types can be strong (restrictive) or weak (nonrestrictive). A strong

REF

CURSOR

type definition specifies a return type, but a weak definition does not.

Strong

REF CURSOR

types are less error prone because the PL/SQL compiler lets you associate a strongly typed cursor variable only with type-compatible queries.

However, weak

REF CURSOR

types are more flexible because the compiler lets you associate a weakly typed cursor variable with any query.

Once you define a

REF CURSOR

type, you can declare cursor variables of that type.

You can use

%TYPE

to provide the datatype of a record variable. Also, in the

RETURN clause of a

REF CURSOR type definition, you can use

%ROWTYPE to specify a record type that represents a row returned by a strongly (not weakly) typed cursor variable.

Currently, cursor variables are subject to several restrictions. See

"Restrictions on

Cursor Variables" on page 6-33.

13-50

PL/SQL User’s Guide and Reference

Cursor Variables

You use three statements to control a cursor variable:

OPEN

FOR

FETCH

, and

. First, you

OPEN

a cursor variable

FOR

a multi-row query. Then, you

FETCH rows from the result set. When all the rows are processed, you

the cursor variable.

Other

OPEN

FOR

statements can open the same cursor variable for different queries.

You need not close a cursor variable before reopening it. When you reopen a cursor variable for a different query, the previous query is lost.

PL/SQL makes sure the return type of the cursor variable is compatible with the

INTO

clause of the

FETCH

statement. For each column value returned by the query associated with the cursor variable, there must be a corresponding, type-compatible field or variable in the

INTO

clause. Also, the number of fields or variables must equal the number of column values. Otherwise, you get an error.

If both cursor variables involved in an assignment are strongly typed, they must have the same datatype. However, if one or both cursor variables are weakly typed, they need not have the same datatype.

When declaring a cursor variable as the formal parameter of a subprogram that fetches from or closes the cursor variable, you must specify the

IN OUT

mode.

If the subprogram opens the cursor variable, you must specify the

IN OUT

mode.

Be careful when passing cursor variables as parameters. At run time, PL/SQL raises

ROWTYPE_MISMATCH

if the return types of the actual and formal parameters are incompatible.

You can apply the cursor attributes

%FOUND

%NOTFOUND

%ISOPEN

, and

%ROWCOUNT

to a cursor variable.

If you try to fetch from, close, or apply cursor attributes to a cursor variable that does not point to a query work area, PL/SQL raises the predefined exception

INVALID_CURSOR

. You can make a cursor variable (or parameter) point to a query work area in two ways:

■

OPEN

the cursor variable

FOR

the query.

Assign to the cursor variable the value of an already

OPEN ed host cursor variable or PL/SQL cursor variable.

A query work area remains accessible as long as any cursor variable points to it.

PL/SQL Language Elements

13-51

Cursor Variables

Examples

You can declare a cursor variable in a PL/SQL host environment such as an OCI or

Pro*C program. To use the host cursor variable, you must pass it as a bind variable to PL/SQL. In the following Pro*C example, you pass a host cursor variable and a selector to a PL/SQL block, which opens the cursor variable for the chosen query:

EXEC SQL BEGIN DECLARE SECTION;

...

/* Declare host cursor variable. */

SQL_CURSOR generic_cv;

int choice;

EXEC SQL END DECLARE SECTION;

...

/* Initialize host cursor variable. */

EXEC SQL ALLOCATE :generic_cv;

...

/* Pass host cursor variable and selector to PL/SQL block. */

EXEC SQL EXECUTE

BEGIN

IF :choice = 1 THEN

OPEN :generic_cv FOR SELECT * FROM emp;

ELSIF :choice = 2 THEN

OPEN :generic_cv FOR SELECT * FROM dept;

ELSIF :choice = 3 THEN

OPEN :generic_cv FOR SELECT * FROM salgrade;

END IF;

END;

END-EXEC;

Host cursor variables are compatible with any query return type. They behave just like weakly typed PL/SQL cursor variables.

When passing host cursor variables to PL/SQL, you can reduce network traffic by grouping

OPEN-FOR

statements. For example, the following PL/SQL block opens three cursor variables in a single round-trip:

/* anonymous PL/SQL block in host environment */

BEGIN

OPEN :emp_cv FOR SELECT * FROM emp;

OPEN :dept_cv FOR SELECT * FROM dept;

OPEN :grade_cv FOR SELECT * FROM salgrade;

END;

13-52

PL/SQL User’s Guide and Reference

Cursor Variables

You can also pass a cursor variable to PL/SQL by calling a stored procedure that declares a cursor variable as one of its formal parameters. To centralize data retrieval, you can group type-compatible queries in a packaged procedure, as the following example shows:

CREATE PACKAGE emp_data AS

TYPE EmpCurTyp IS REF CURSOR RETURN emp%ROWTYPE;

PROCEDURE open_emp_cv (emp_cv IN OUT EmpCurTyp,

choice IN NUMBER);

END emp_data;

CREATE PACKAGE BODY emp_data AS

PROCEDURE open_emp_cv (emp_cv IN OUT EmpCurTyp,

choice IN NUMBER) IS

BEGIN

IF choice = 1 THEN

OPEN emp_cv FOR SELECT * FROM emp WHERE comm IS NOT NULL;

ELSIF choice = 2 THEN

OPEN emp_cv FOR SELECT * FROM emp WHERE sal > 2500;

ELSIF choice = 3 THEN

OPEN emp_cv FOR SELECT * FROM emp WHERE deptno = 20;

END IF;

END open_emp_cv;

END emp_data;

Alternatively, you can use a standalone procedure to open the cursor variable.

Simply define the

REF CURSOR

type in a separate package, then reference that type in the standalone procedure. For instance, if you create the following (bodiless) package, you can create standalone procedures that reference the types it defines:

CREATE PACKAGE cv_types AS

TYPE EmpCurTyp IS REF CURSOR RETURN emp%ROWTYPE;

TYPE DeptCurTyp IS REF CURSOR RETURN dept%ROWTYPE;

TYPE BonusCurTyp IS REF CURSOR RETURN bonus%ROWTYPE;

...

END cv_types;

Related Topics

PL/SQL Language Elements

13-53

Cursors

Syntax

To execute a multi-row query, Oracle opens an unnamed work area that stores processing information. An explicit cursor lets you name the work area, access the information, and process the rows individually. For more information, see

cursor_declaration

(

, cursor_parameter_declaration

CURSOR cursor_name

RETURN rowtype

IS select_statement ;

cursor_spec

(

, cursor_parameter_declaration

CURSOR cursor_name

RETURN rowtype ;

cursor_body

(

, cursor_parameter_declaration

CURSOR cursor_name

RETURN rowtype IS select_statement ;

)

cursor_parameter_declaration

IN parameter_name datatype

DEFAULT expression

13-54

PL/SQL User’s Guide and Reference

Cursors

rowtype

db_table_name cursor_name cursor_variable_name record_name % TYPE record_type_name

% ROWTYPE

Keyword and Parameter Description

cursor_name

This identifies an explicit cursor previously declared within the current scope.

datatype

This is a type specifier. For the syntax of datatype

, see

Statement" on page 13-166. If the cursor declaration declares parameters, each

db_table_name

This identifies a database table (or view) that must be accessible when the declaration is elaborated.

expression

This is 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.

parameter_name

This identifies a cursor parameter; that is, a variable declared as the formal parameter of a cursor. A cursor parameter can appear in a query wherever a constant can appear. The formal parameters of a cursor must be

parameters. The query can also reference other PL/SQL variables within its scope.

PL/SQL Language Elements

13-55

Cursors

record_name

This identifies a user-defined record previously declared within the current scope.

record_type_name

This identifies a user-defined record type that was defined using the datatype specifier

RECORD

RETURN

This keyword introduces the

RETURN

clause, which specifies the datatype of a cursor return value. You can use the

%ROWTYPE

attribute in the

RETURN

clause to provide a record type that represents a row in a database table or a row returned by a previously declared cursor. Also, you can use the

%TYPE

attribute to provide the datatype of a previously declared record.

A cursor body must have a

SELECT

statement and the same

RETURN

clause as its corresponding cursor spec. Also, the number, order, and datatypes of select items in the

SELECT

clause must match the

RETURN

clause.

%ROWTYPE

This attribute provides a record type that represents a row in a database table or a row fetched from a previously declared cursor or cursor variable. Fields in the record and corresponding columns in the row have the same names and datatypes.

select_statement

This is a query that returns a result set of rows. Its syntax is like that of select_into_statement

without the

INTO

clause. See

"SELECT INTO

parameter must be used in the query.

%TYPE

This attribute provides the datatype of a previously declared user-defined record.

Usage Notes

You must declare a cursor before referencing it in an

OPEN

FETCH

, or

CLOSE statement. And, you must declare a variable before referencing it in a cursor declaration. The word SQL is reserved by PL/SQL for use as the default name for implicit cursors and cannot be used in a cursor declaration.

13-56

PL/SQL User’s Guide and Reference

Cursors

You cannot assign values to a cursor name or use it in an expression. However, cursors and variables follow the same scoping rules. For more information, see

"Scope and Visibility of PL/SQL Identifiers" on page 2-19.

You retrieve data from a cursor by opening it, then fetching from it. Because the

FETCH

statement specifies the target variables, using an

INTO

clause in the

SELECT statement of a cursor_declaration

is redundant and invalid.

The scope of cursor parameters is local to the cursor, meaning that they can be referenced only within the query used in the cursor declaration. The values of cursor parameters are used by the associated query when the cursor is opened. The query can also reference other PL/SQL variables within its scope.

The datatype of a cursor parameter must be specified without constraints. For example, the following parameter declarations are not allowed:

CURSOR c1 (emp_id NUMBER NOT NULL, dept_no NUMBER(2)) -- not allowed

Examples

Some examples of cursor declarations follow:

CURSOR c1 IS SELECT empno, ename, job, sal FROM emp

WHERE sal > 2000;

CURSOR c2 RETURN dept%ROWTYPE IS

SELECT * FROM dept WHERE deptno = 10;

CURSOR c3 (start_date DATE) IS

SELECT empno, sal FROM emp WHERE hiredate > start_date;

Related Topics

CLOSE Statement ,

FETCH Statement

OPEN Statement

"Reducing Loop Overhead for Collections with Bulk Binds" on page 5-37.

PL/SQL Language Elements

13-57

DELETE Statement

The

DELETE

statement removes entire rows of data from a specified table or view.

For a full description of the

DELETE

statement, see Oracle9i SQL Reference.

Syntax delete_statement

DELETE

WHERE

FROM

( table_reference subquery

TABLE (

) subquery2

) search_condition

CURRENT OF cursor_name alias returning_clause

;

table_reference

schema_name .

db_table_name view_name

@ dblink_name

returning_clause

, single_row_expression INTO

, variable_name

: host_variable_name

RETURNING

, multiple_row_expression

BULK COLLECT

INTO

, collection_name

: host_array_name

13-58

PL/SQL User’s Guide and Reference

DELETE Statement

Keyword and Parameter Description

alias

This is another (usually short) name for the referenced table or view and is typically used in the

WHERE

clause.

BULK COLLECT

This clause instructs the SQL engine to bulk-bind output collections before returning them to the PL/SQL engine. The SQL engine bulk-binds all collections referenced in the

RETURNING INTO

list. The corresponding columns must store scalar (not composite) values. For more information, see

returning_clause

This clause lets you return values from the deleted rows, thereby eliminating the need to

SELECT

the rows beforehand. You can retrieve the column values into variables and/or host variables, or into collections and/or host arrays. However, you cannot use the

RETURNING

clause for remote or parallel deletes.

subquery

This is a

SELECT

statement that provides a set of rows for processing. Its syntax is like that of select_into_statement

without the

INTO

clause. See

table_reference

This specifies a table or view, which must be accessible when you execute the

DELETE

statement, and for which you must have

DELETE

privileges.

TABLE (subquery2)

The operand of

TABLE

is a

SELECT

statement that returns a single column value, which must be a nested table. Operator

TABLE

informs Oracle that the value is a collection, not a scalar value.

PL/SQL Language Elements

13-59

DELETE Statement

Usage Notes

You can use the

DELETE WHERE CURRENT OF

statement after a fetch from an open cursor (this includes implicit fetches executed in a cursor

FOR

loop), provided the associated query is

FOR UPDATE

. This statement deletes the current row; that is, the one just fetched.

The implicit cursor

SQL

and the cursor attributes

%NOTFOUND

%FOUND

, and

%ROWCOUNT

let you access useful information about the execution of a

DELETE statement.

Examples

WHERE CURRENT OF cursor_name

This clause refers to the latest row processed by the

FETCH

statement associated with the cursor identified by cursor_name

. The cursor must be

FOR UPDATE

and must be open and positioned on a row. If the cursor is not open, the

CURRENT OF clause causes an error.

If the cursor is open, but no rows have been fetched or the last fetch returned no rows, PL/SQL raises the predefined exception

NO_DATA_FOUND

WHERE search_condition

This clause conditionally chooses rows to be deleted from the referenced table or view. Only rows that meet the search condition are deleted. If you omit the

WHERE clause, all rows in the table or view are deleted.

The following statement deletes from the bonus

table all employees whose sales were below quota:

DELETE FROM bonus WHERE sales_amt < quota;

The following statement returns two column values from a deleted row into local variables:

DECLARE

my_empno emp.empno%TYPE;

my_ename emp.ename%TYPE;

my_job emp.job%TYPE;

BEGIN

...

DELETE FROM emp WHERE empno = my_empno

RETURNING ename, job INTO my_ename, my_job;

END;

13-60

PL/SQL User’s Guide and Reference

DELETE Statement

You can combine the

BULK COLLECT

clause with a

FORALL

statement, in which case, the SQL engine bulk-binds column values incrementally. In the following example, if collection depts

has 3 elements, each of which causes 5 rows to be deleted, then collection enums

has 15 elements when the statement completes:

FORALL j IN depts.FIRST..depts.LAST

DELETE FROM emp WHERE deptno = depts(j)

RETURNING empno BULK COLLECT INTO enums;

The column values returned by each execution are added to the values returned previously.

Related Topics

FETCH Statement ,

"Associating a PL/SQL Exception with a Number: Pragma EXCEPTION_INIT" on page 7-8.

PL/SQL Language Elements

13-61

EXCEPTION_INIT Pragma

The pragma

EXCEPTION_INIT

associates an exception name with an Oracle error number. That lets you refer to any internal exception by name and to write a specific handler for it instead of using the

OTHERS

handler. For more information, see

Syntax exception_init_pragma

PRAGMA EXCEPTION_INIT ( exception_name , error_number ) ;

Keyword and Parameter Description

error_number

This is any valid Oracle error number. These are the same error numbers returned by the function

SQLCODE

exception_name

This identifies a user-defined exception previously declared within the current scope.

PRAGMA

Usage Notes

You can use

EXCEPTION_INIT

in the declarative part of any PL/SQL block, subprogram, or package. The pragma must appear in the same declarative part as its associated exception, somewhere after the exception declaration.

Be sure to assign only one exception name to an error number.

13-62

PL/SQL User’s Guide and Reference

EXCEPTION_INIT Pragma

Example

The following pragma associates the exception deadlock_detected

with Oracle error 60:

DECLARE

deadlock_detected EXCEPTION;

PRAGMA EXCEPTION_INIT(deadlock_detected, -60);

BEGIN

...

EXCEPTION

WHEN deadlock_detected THEN

-- handle the error

...

END;

Related Topics

AUTONOMOUS_TRANSACTION Pragma ,

SQLCODE Function

PL/SQL Language Elements

13-63

Exceptions

An exception is a runtime error or warning condition, which can be predefined or user-defined. Predefined exceptions are raised implicitly (automatically) by the runtime system. User-defined exceptions must be raised explicitly by

RAISE statements. To handle raised exceptions, you write separate routines called exception handlers. For more information, see

Chapter 7 .

Syntax exception_declaration

exception_name EXCEPTION ;

exception_handler

WHEN exception_name

OTHERS

OR exception_name

THEN statement

Keyword and Parameter Description

exception_name

This identifies a predefined exception such as

ZERO_DIVIDE

, or a user-defined exception previously declared within the current scope.

OTHERS

This keyword stands for all the exceptions not explicitly named in the exception-handling part of the block. The use of

OTHERS

is optional and is allowed only as the last exception handler. You cannot include

OTHERS in a list of exceptions following the keyword

WHEN

statement

This is an executable statement. For the syntax of statement

, see

"Predefined PL/SQL Exceptions" on page 7-4. PL/SQL declares predefined

13-64

PL/SQL User’s Guide and Reference

Exceptions

WHEN

This keyword introduces an exception handler. You can have multiple exceptions execute the same sequence of statements by following the keyword

WHEN

with a list of the exceptions, separating them by the keyword

. If any exception in the list is raised, the associated statements are executed.

Usage Notes

An exception declaration can appear only in the declarative part of a block, subprogram, or package. The scope rules for exceptions and variables are the same.

But, unlike variables, exceptions cannot be passed as parameters to subprograms.

Some exceptions are predefined by PL/SQL. For a list of these exceptions, see

exceptions globally in package

STANDARD

, so you need not declare them yourself.

Redeclaring predefined exceptions is error prone because your local declaration overrides the global declaration. In such cases, you must use dot notation to specify the predefined exception, as follows:

EXCEPTION

WHEN invalid_number OR STANDARD.INVALID_NUMBER THEN ...

The exception-handling part of a PL/SQL block is optional. Exception handlers must come at the end of the block. They are introduced by the keyword

EXCEPTION

. The exception-handling part of the block is terminated by the same keyword

END

that terminates the entire block. An exception handler can reference only those variables that the current block can reference.

An exception should be raised only when an error occurs that makes it undesirable or impossible to continue processing. If there is no exception handler in the current block for a raised exception, the exception propagates according to the following rules:

■

If there is an enclosing block for the current block, the exception is passed on to that block. The enclosing block then becomes the current block. If a handler for the raised exception is not found, the process repeats.

If there is no enclosing block for the current block, an unhandled exception error is passed back to the host environment.

Only one exception at a time can be active in the exception-handling part of a block.

Therefore, if an exception is raised inside a handler, the block that encloses the current block is the first block searched to find a handler for the newly raised exception. From there on, the exception propagates normally.

PL/SQL Language Elements

13-65

Exceptions

Example

The following PL/SQL block has two exception handlers:

DECLARE

bad_emp_id EXCEPTION;

bad_acct_no EXCEPTION;

...

BEGIN

...

EXCEPTION

WHEN bad_emp_id OR bad_acct_no THEN -- user-defined

ROLLBACK;

WHEN ZERO_DIVIDE THEN -- predefined

INSERT INTO inventory VALUES (part_number, quantity);

COMMIT;

END;

Related Topics

Blocks ,

"Passing Nulls" on page 11-16.

RAISE Statement

13-66

PL/SQL User’s Guide and Reference

EXECUTE IMMEDIATE Statement

The

EXECUTE IMMEDIATE

statement prepares (parses) and immediately executes a dynamic SQL statement or anonymous PL/SQL block. For more information, see

Chapter 11 .

Syntax execute_immediate_statement

EXECUTE IMMEDIATE dynamic_string

INTO

, define_variable record_name

OUT

IN OUT

USING

RETURNING

RETURN

INTO bind_argument

, bind_argument

;

Keyword and Parameter Description

bind_argument

This can be an expression whose value is passed to the dynamic SQL statement or

PL/SQL block, or it can be a variable that stores a value returned by the dynamic

SQL statement or PL/SQL block.

PL/SQL Language Elements

13-67

EXECUTE IMMEDIATE Statement

define_variable_name

This identifies a variable that stores a selected column value.

dynamic_string

This is a string literal, variable, or expression that represents a SQL statement or

PL/SQL block.

INTO ...

Used only for single-row queries, this clause specifies the variables or record into which column values are retrieved. For each value retrieved by the query, there must be a corresponding, type-compatible variable or field in the

INTO

clause.

record_name

This identifies a user-defined or

%ROWTYPE

record that stores a selected row.

RETURNING INTO ...

Used only for DML statements that have a

RETURNING

clause (without a

BULK

COLLECT

clause), this clause specifies the bind variables into which column values are returned. For each value returned by the DML statement, there must be a corresponding, type-compatible variable in the

RETURNING INTO

clause.

USING ...

This clause specifies a list of input and/or output bind arguments. If you do not specify a parameter mode, it defaults to

Usage Notes

Except for multi-row queries, the dynamic string can contain any SQL statement

You can place all bind arguments in the

USING

clause. The default parameter mode is

. For DML statements that have a

RETURNING

clause, you can place

OUT arguments in the

RETURNING INTO

clause without specifying the parameter mode, which, by definition, is

OUT

. If you use both the

USING

clause and the

RETURNING

INTO

clause, the

USING

clause can contain only

arguments.

13-68

PL/SQL User’s Guide and Reference

EXECUTE IMMEDIATE Statement

Examples

At run time, bind arguments replace corresponding placeholders in the dynamic string. So, every placeholder must be associated with a bind argument in the

USING clause and/or

RETURNING INTO

clause. You can use numeric, character, and string literals as bind arguments, but you cannot use Boolean literals (

TRUE

FALSE

, and

NULL

). To pass nulls to the dynamic string, you must use a workaround. See

Dynamic SQL supports all the SQL datatypes. So, for example, define variables and bind arguments can be collections,

INTO

clause.

You can execute a dynamic SQL statement repeatedly using new values for the bind arguments. However, you incur some overhead because

EXECUTE IMMEDIATE re-prepares the dynamic string before every execution.

The following PL/SQL block contains several examples of dynamic SQL:

DECLARE

sql_stmt VARCHAR2(200);

plsql_block VARCHAR2(500);

emp_id NUMBER(4) := 7566;

salary NUMBER(7,2);

dept_id NUMBER(2) := 50;

dept_name VARCHAR2(14) := ’PERSONNEL’;

location VARCHAR2(13) := ’DALLAS’;

emp_rec emp%ROWTYPE;

BEGIN

EXECUTE IMMEDIATE ’CREATE TABLE bonus (id NUMBER, amt NUMBER)’;

sql_stmt := ’INSERT INTO dept VALUES (:1, :2, :3)’;

EXECUTE IMMEDIATE sql_stmt USING dept_id, dept_name, location;

sql_stmt := ’SELECT * FROM emp WHERE empno = :id’;

EXECUTE IMMEDIATE sql_stmt INTO emp_rec USING emp_id;

plsql_block := ’BEGIN emp_pkg.raise_salary(:id, :amt); END;’;

EXECUTE IMMEDIATE plsql_block USING 7788, 500;

sql_stmt := ’UPDATE emp SET sal = 2000 WHERE empno = :1

RETURNING sal INTO :2’;

EXECUTE IMMEDIATE sql_stmt USING emp_id RETURNING INTO salary;

PL/SQL Language Elements

13-69

EXECUTE IMMEDIATE Statement

EXECUTE IMMEDIATE ’DELETE FROM dept WHERE deptno = :num’

USING dept_id;

EXECUTE IMMEDIATE ’ALTER SESSION SET SQL_TRACE TRUE’;

END;

Related Topics

OPEN-FOR-USING Statement

13-70

PL/SQL User’s Guide and Reference

EXIT Statement

You use the

EXIT

statement to exit a loop. The

EXIT

statement has two forms: the unconditional

EXIT

and the conditional

EXIT WHEN

. With either form, you can name the loop to be exited. For more information, see

"Iterative Control: LOOP and

EXIT Statements" on page 4-9.

Syntax exit_statement

label_name WHEN boolean_expression

EXIT ;

Keyword and Parameter Description

boolean_expression

This is an expression that yields the Boolean value

TRUE

FALSE

, or

NULL

. It is evaluated with each iteration of the loop in which the

EXIT WHEN

statement appears. If the expression yields

TRUE

, the current loop (or the loop labeled by label_name

) is exited immediately. For the syntax of boolean_expression

, see

"Expressions" on page 13-73.

EXIT

An unconditional

EXIT

statement (that is, one without a

WHEN

clause) exits the current loop immediately. Execution resumes with the statement following the loop.

label_name

This identifies the loop to be exited. You can exit not only the current loop but any enclosing labeled loop.

Usage Notes

The

EXIT

statement can be used only inside a loop. PL/SQL lets you code an infinite loop. For example, the following loop will never terminate normally:

WHILE TRUE LOOP ... END LOOP;

In such cases, you must use an

EXIT

statement to exit the loop.

PL/SQL Language Elements

13-71

EXIT Statement

If you use an

EXIT

statement to exit a cursor

FOR

loop prematurely, the cursor is closed automatically. The cursor is also closed automatically if an exception is raised inside the loop.

Examples

The

EXIT

statement in the following example is not allowed because you cannot exit from a block directly; you can exit only from a loop:

DECLARE

amount NUMBER;

maximum NUMBER;

BEGIN

...

BEGIN

...

IF amount >= maximum THEN

EXIT; -- not allowed; use RETURN instead

END IF;

END;

The following loop normally executes ten times, but it will exit prematurely if there are less than ten rows to fetch:

FOR i IN 1..10 LOOP

FETCH c1 INTO emp_rec;

EXIT WHEN c1%NOTFOUND;

total_comm := total_comm + emp_rec.comm;

END LOOP;

The following example illustrates the use of loop labels:

<<outer>>

FOR i IN 1..10 LOOP

...

<<inner>>

FOR j IN 1..100 LOOP

...

EXIT outer WHEN ... -- exits both loops

END LOOP inner;

END LOOP outer;

Related Topics

Expressions ,

LOOP Statements

13-72

PL/SQL User’s Guide and Reference

Expressions

An expression is an arbitrarily complex combination of variables, constants, literals, operators, and function calls. The simplest expression is a single variable.

The PL/SQL compiler determines the datatype of an expression from the types of the variables, constants, literals, and operators that comprise the expression. Every time the expression is evaluated, a single value of that type results. For more information, see

"PL/SQL Expressions and Comparisons" on page 2-23.

Syntax expression

( boolean_expression character_expression date_expression numeric_expression

)

boolean_expression

NOT

AND

OR boolean_constant_name boolean_function_call boolean_literal boolean_variable_name other_boolean_form

NOT boolean_constant_name boolean_function_call boolean_literal boolean_variable_name other_boolean_form

PL/SQL Language Elements

13-73

Expressions

other_boolean_form

collection_name .

cursor_name

EXISTS ( index )

: cursor_variable_name host_cursor_variable_name

SQL expression

FOUND

ISOPEN

NOTFOUND relational_operator

NOT

NOT expression

NULL

LIKE pattern

BETWEEN expression

(

, expression

character_expression

character_constant_name character_function_call character_literal character_variable_name

: indicator_name

: host_variable_name

AND expression

)

|| character_constant_name character_function_call character_literal character_variable_name

: host_variable_name

: indicator_name

13-74

PL/SQL User’s Guide and Reference

numeric_subexpression

cursor_name cursor_variable_name

: host_cursor_variable_name

SQL

% ROWCOUNT

SQL % BULK_ROWCOUNT ( index )

: indicator_name

: host_variable_name numeric_constant_name numeric_function_call numeric_literal numeric_variable_name collection_name .

COUNT

FIRST

LAST

LIMIT

PRIOR

( index )

** exponent

Expressions

PL/SQL Language Elements

13-75

Expressions

date_expression

date_constant_name date_function_call date_literal date_variable_name

: host_variable_name

: numeric_expression indicator_name

numeric_expression

– numeric_subexpression numeric_subexpression

Keyword and Parameter Description

BETWEEN

This comparison operator tests whether a value lies in a specified range. It means

"greater than or equal to low value and less than or equal to high value."

boolean_constant_name

This identifies a constant of type

BOOLEAN

, which must be initialized to the value

TRUE

FALSE

, or

NULL

. Arithmetic operations on Boolean constants are not allowed.

boolean_expression

This is an expression that yields the Boolean value

TRUE

FALSE

, or

NULL

13-76

PL/SQL User’s Guide and Reference

Expressions

boolean_function_call

This is any function call that returns a Boolean value.

boolean_literal

This is the predefined value

TRUE

FALSE

, or

NULL

(which stands for a missing, unknown, or inapplicable value). You cannot insert the value

TRUE

FALSE

into a database column.

boolean_variable_name

This identifies a variable of type

BOOLEAN

. Only the values

TRUE

FALSE

, and

NULL can be assigned to a

BOOLEAN

variable. You cannot select or fetch column values into a

BOOLEAN

variable. Also, arithmetic operations on

BOOLEAN

variables are not allowed.

%BULK_ROWCOUNT

Designed for use with the

FORALL

statement, this is a composite attribute of the implicit cursor

SQL

. For more information, see

"SQL Cursor" on page 13-175.

character_constant_name

This identifies a previously declared constant that stores a character value. It must be initialized to a character value or a value implicitly convertible to a character value.

character_expression

This is an expression that yields a character or character string.

character_function_call

This is a function call that returns a character value or a value implicitly convertible to a character value.

character_literal

This is a literal that represents a character value or a value implicitly convertible to a character value.

character_variable_name

This identifies a previously declared variable that stores a character value.

PL/SQL Language Elements

13-77

Expressions

collection_name

This identifies a collection (nested table, index-by table, or varray) previously declared within the current scope.

cursor_name

This identifies an explicit cursor previously declared within the current scope.

cursor_variable_name

This identifies a PL/SQL cursor variable previously declared within the current scope.

date_constant_name

This identifies a previously declared constant that stores a date value. It must be initialized to a date value or a value implicitly convertible to a date value.

date_expression

This is an expression that yields a date/time value.

date_function_call

This is a function call that returns a date value or a value implicitly convertible to a date value.

date_literal

This is a literal that represents a date value or a value implicitly convertible to a date value.

date_variable_name

This identifies a previously declared variable that stores a date value.

EXISTS, COUNT, FIRST, LAST, LIMIT, NEXT, PRIOR

These are collection methods. When appended to the name of a collection, these methods return useful information. For example,

EXISTS(n)

returns

TRUE

if the n th element of a collection exists. Otherwise,

EXISTS(n)

returns

FALSE

. For more information, see

"Collection Methods" on page 13-24.

exponent

This is an expression that must yield a numeric value.

13-78

PL/SQL User’s Guide and Reference

Expressions

%FOUND, %ISOPEN, %NOTFOUND, %ROWCOUNT

These are cursor attributes. When appended to the name of a cursor or cursor variable, these attributes return useful information about the execution of a multi-row query. You can also append them to the implicit cursor

SQL

host_cursor_variable_name

This identifies a cursor variable declared in a PL/SQL host environment and passed to PL/SQL as a bind variable. Host cursor variables must be prefixed with a colon.

host_variable_name

This identifies a variable declared in a PL/SQL host environment and passed to

PL/SQL as a bind variable. The datatype of the host variable must be implicitly convertible to the appropriate PL/SQL datatype. Also, host variables must be prefixed with a colon.

IN

This comparison operator tests set membership. It means "equal to any member of."

The set can contain nulls, but they are ignored. Also, expressions of the form value NOT IN set yield

FALSE

if the set contains a null.

index

This is a numeric expression that must yield a value of type

BINARY_INTEGER

or a value implicitly convertible to that datatype.

indicator_name

This identifies an indicator variable declared in a PL/SQL host environment and passed to PL/SQL. Indicator variables must be prefixed with a colon. An indicator variable "indicates" the value or condition of its associated host variable. For example, in the Oracle Precompiler environment, indicator variables can detect nulls or truncated values in output host variables.

IS NULL

This comparison operator returns the Boolean value

TRUE

if its operand is null, or

FALSE

if its operand is not null.

PL/SQL Language Elements

13-79

Expressions

LIKE

This comparison operator compares a character value to a pattern. Case is significant.

returns the Boolean value

TRUE

if the character patterns match, or

FALSE

if they do not match.

NOT, AND, OR

These are logical operators, which follow the tri-state logic of

Table 2–2 on page 2-25.

AND

returns the value

TRUE

only if both its operands are true.

returns the value

TRUE

if either of its operands is true.

NOT

returns the opposite value

(logical negation) of its operand. For more information, see

"Logical Operators" on page 2-25.

NULL

This keyword represents a null; it stands for a missing, unknown, or inapplicable value. When

NULL

is used in a numeric or date expression, the result is a null.

numeric_constant_name

This identifies a previously declared constant that stores a numeric value. It must be initialized to a numeric value or a value implicitly convertible to a numeric value.

numeric_expression

This is an expression that yields an integer or real value.

numeric_function_call

This is a function call that returns a numeric value or a value implicitly convertible to a numeric value.

numeric_literal

This is a literal that represents a number or a value implicitly convertible to a number.

numeric_variable_name

This identifies a previously declared variable that stores a numeric value.

pattern

This is a character string compared by the

LIKE operator to a specified string value.

It can include two special-purpose characters called wildcards. An underscore (_) matches exactly one character; a percent sign (%) matches zero or more characters.

13-80

PL/SQL User’s Guide and Reference

Expressions

relational_operator

This operator lets you compare expressions. For the meaning of each operator, see

"Comparison Operators" on page 2-26.

SQL

This identifies a cursor opened implicitly by Oracle to process a SQL data manipulation statement. The implicit cursor

SQL

always refers to the most recently executed SQL statement.

+, -, /, *, **

These symbols are the addition, subtraction, division, multiplication, and exponentiation operators, respectively.

||

This is the concatenation operator. As the following example shows, the result of concatenating string1 with string2 is a character string that contains string1 followed by string2:

’Good’ || ’ morning!’ = ’Good morning!’

The next example shows that nulls have no effect on the result of a concatenation:

’suit’ || NULL || ’case’ = ’suitcase’

A null string (

’’

), which is zero characters in length, is treated like a null.

Usage Notes

In a Boolean expression, you can only compare values that have compatible datatypes. For more information, see

"Datatype Conversion" on page 3-24.

In conditional control statements, if a Boolean expression yields

TRUE

, its associated sequence of statements is executed. But, if the expression yields

FALSE

NULL

, its associated sequence of statements is not executed.

The relational operators can be applied to operands of type

BOOLEAN

. By definition,

TRUE

is greater than

FALSE

. Comparisons involving nulls always yield a null. The value of a Boolean expression can be assigned only to Boolean variables, not to host variables or database columns. Also, datatype conversion to or from type

BOOLEAN is not supported.

You can use the addition and subtraction operators to increment or decrement a date value, as the following examples show:

PL/SQL Language Elements

13-81

Expressions hire_date := ’10-MAY-95’; hire_date := hire_date + 1; -- makes hire_date ’11-MAY-95’ hire_date := hire_date - 5; -- makes hire_date ’06-MAY-95’

When PL/SQL evaluates a boolean expression,

NOT

has the highest precedence,

AND

has the next-highest precedence, and

has the lowest precedence. However, you can use parentheses to override the default operator precedence.

Within an expression, operations occur in their predefined order of precedence.

From first to last (top to bottom), the default order of operations is parentheses exponents unary operators multiplication and division addition, subtraction, and concatenation

PL/SQL evaluates operators of equal precedence in no particular order. When parentheses enclose an expression that is part of a larger expression, PL/SQL evaluates the parenthesized expression first, then uses the result in the larger expression. When parenthesized expressions are nested, PL/SQL evaluates the innermost expression first and the outermost expression last.

Examples

Several examples of expressions follow:

(a + b) > c -- Boolean expression

NOT finished -- Boolean expression

TO_CHAR(acct_no) -- character expression

’Fat ’ || ’cats’ -- character expression

’15-NOV-95’ -- date expression

MONTHS_BETWEEN(d1, d2) -- date expression pi * r**2 -- numeric expression emp_cv%ROWCOUNT -- numeric expression

Related Topics

Assignment Statement

EXIT Statement ,

IF Statement

LOOP Statements

13-82

PL/SQL User’s Guide and Reference

FETCH Statement

The

FETCH

statement retrieves rows of data one at a time from the result set of a multi-row query. The data is stored in variables or fields that correspond to the columns selected by the query. For more information, see

Overhead for Collections with Bulk Binds" on page 5-37.

Syntax fetch_statement

FETCH

INTO cursor_name

: cursor_variable_name host_cursor_variable_name

, variable_name record_name

BULK COLLECT INTO

, collection_name

: host_array_name

LIMIT numeric_expression

Keyword and Parameter Description

BULK COLLECT

This clause instructs the SQL engine to bulk-bind output collections before returning them to the PL/SQL engine. The SQL engine bulk-binds all collections referenced in the

INTO

list.

collection_name

This identifies a declared collection into which column values are bulk fetched. For each query select_item

, there must be a corresponding, type-compatible collection in the list.

;

PL/SQL Language Elements

13-83

FETCH Statement

cursor_name

This identifies an explicit cursor previously declared within the current scope.

cursor_variable_name

This identifies a PL/SQL cursor variable (or parameter) previously declared within the current scope.

host_array_name

This identifies an array (declared in a PL/SQL host environment and passed to

PL/SQL as a bind variable) into which column values are bulk fetched. For each query select_item

, there must be a corresponding, type-compatible array in the list. Host arrays must be prefixed with a colon.

host_cursor_variable_name

LIMIT

This optional clause, allowed only in bulk (not scalar)

FETCH

statements, lets you limit the number of rows fetched from the database.

record_name

This identifies a user-defined or

%ROWTYPE

record into which rows of values are fetched. For each column value returned by the query associated with the cursor or cursor variable, there must be a corresponding, type-compatible field in the record.

variable_name

This identifies a previously declared variable into which a column value is fetched.

For each column value returned by the query associated with the cursor or cursor variable, there must be a corresponding, type-compatible variable in the list.

Usage Notes

You must use either a cursor

FOR

loop or the

FETCH

statement to process a multi-row query.

13-84

PL/SQL User’s Guide and Reference

FETCH Statement

Examples

Any variables in the

WHERE

clause of the query are evaluated only when the cursor or cursor variable is opened. To change the result set or the values of variables in the query, you must reopen the cursor or cursor variable with the variables set to their new values.

To reopen a cursor, you must close it first. However, you need not close a cursor variable before reopening it.

You can use different

INTO

lists on separate fetches with the same cursor or cursor variable. Each fetch retrieves another row and assigns values to the target variables.

If you

FETCH

past the last row in the result set, the values of the target fields or variables are indeterminate and the

%NOTFOUND

attribute yields

TRUE

PL/SQL makes sure the return type of a cursor variable is compatible with the

INTO

clause of the

FETCH

statement. For each column value returned by the query associated with the cursor variable, there must be a corresponding, type-compatible field or variable in the

INTO

clause. Also, the number of fields or variables must equal the number of column values.

When you declare a cursor variable as the formal parameter of a subprogram that fetches from the cursor variable, you must specify the

IN OUT

mode.

However, if the subprogram also opens the cursor variable, you must specify the

OUT

mode.

Eventually, the

FETCH statement must fail to return a row, so when that happens, no exception is raised. To detect the failure, you must use the cursor attribute

%FOUND or

%NOTFOUND

PL/SQL raises the predefined exception

INVALID_CURSOR

if you try to fetch from a closed or never-opened cursor or cursor variable.

The following example shows that any variables in the query associated with a cursor are evaluated only when the cursor is opened:

DECLARE

my_sal NUMBER(7,2);

n INTEGER(2) := 2;

CURSOR emp_cur IS SELECT n*sal FROM emp;

PL/SQL Language Elements

13-85

FETCH Statement

BEGIN

OPEN emp_cur; -- n equals 2 here

LOOP

FETCH emp_cur INTO my_sal;

EXIT WHEN emp_cur%NOTFOUND;

-- process the data

n := n + 1; -- does not affect next FETCH; sal will be multiplied by 2

END LOOP;

In the following example, you fetch rows one at a time from the cursor variable emp_cv

into the user-defined record emp_rec

DECLARE

TYPE EmpCurTyp IS REF CURSOR RETURN emp%ROWTYPE;

emp_cv EmpCurTyp;

emp_rec emp%ROWTYPE;

BEGIN

LOOP

FETCH emp_cv INTO emp_rec;

EXIT WHEN emp_cv%NOTFOUND;

...

END LOOP;

END;

The

BULK COLLECT

clause lets you bulk-bind entire columns of Oracle data. That way, you can fetch all rows from the result set at once. In the following example, you bulk-fetch from a cursor into a collection:

DECLARE

TYPE NameList IS TABLE OF emp.ename%TYPE;

names NameList;

CURSOR c1 IS SELECT ename FROM emp WHERE job = ’CLERK’;

BEGIN

OPEN c1;

FETCH c1 BULK COLLECT INTO names;

...

CLOSE c1;

END;

13-86

PL/SQL User’s Guide and Reference

FETCH Statement

In the example below, you use the

LIMIT clause. With each iteration of the loop, the

FETCH

statement fetches 100 rows (or less) into index-by table acct_ids

. The previous values are overwritten.

DECLARE

TYPE NumList IS TABLE OF NUMBER INDEX BY BINARY_INTEGER;

CURSOR c1 IS SELECT acct_id FROM accounts;

acct_ids NumList;

rows NATURAL := 100; -- set limit

BEGIN

OPEN c1;

LOOP

/* The following statement fetches 100 rows (or less). */

FETCH c1 BULK COLLECT INTO acct_ids LIMIT rows;

EXIT WHEN c1%NOTFOUND;

...

END LOOP;

CLOSE c1;

END;

Related Topics

PL/SQL Language Elements

13-87

FORALL Statement

The

FORALL

statement instructs the PL/SQL engine to bulk-bind input collections before sending them to the SQL engine. Although the

FORALL

statement contains an iteration scheme, it is not a

FOR

loop. For more information, see

"Reducing Loop

Syntax forall_statement

FORALL index_name IN lower_bound ..

upper_bound sql_statement ;

Keyword and Parameter Description

index_name

This is an undeclared identifier that can be referenced only within the

FORALL statement and only as a collection subscript.

The implicit declaration of index_name overrides any other declaration outside the loop. So, another variable with the same name cannot be referenced inside the statement. Inside a

FORALL

statement, index_name

cannot appear in expressions and cannot be assigned a value.

lower_bound .. upper_bound

These are expressions that must yield number, which, if necessary, PL/SQL rounds to the nearest integer. The integers must specify a valid range of consecutive index numbers. The SQL engine executes the SQL statement once for each index number in the range. The expressions are evaluated only when the

FORALL statement is first entered.

SAVE EXCEPTIONS

These optional keywords cause the

FORALL

loop to continue even if some DML operations fail. 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.

13-88

PL/SQL User’s Guide and Reference

FORALL Statement

Usage Notes

The SQL statement can reference more than one collection. However, 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

sql_statement

This must be an

INSERT

UPDATE

, or

DELETE

statement that references collection elements.

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). Otherwise, you get the error this feature is not supported 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.

All collection elements in the specified range must exist. If an element is missing or was deleted, you get an error. An example follows:

DECLARE

TYPE NumList IS TABLE OF NUMBER;

depts NumList := NumList(10, 20, 30, 40);

BEGIN

depts.DELETE(3); -- delete third element

FORALL i IN depts.FIRST..depts.LAST

DELETE FROM emp WHERE deptno = depts(i); -- causes an error

END;

■

As the following example shows, input collections of composite values cannot be decomposed and bound to database columns:

PL/SQL Language Elements

13-89

FORALL Statement

Example

CREATE TABLE coords (x NUMBER, y NUMBER);

CREATE TYPE Pair AS OBJECT (m NUMBER, n NUMBER);

DECLARE

TYPE PairTab IS TABLE OF Pair;

pairs PairTab := PairTab(Pair(1,2), Pair(3,4), Pair(5,6));

TYPE NumTab IS TABLE OF NUMBER;

nums NumTab := NumTab(1, 2, 3);

BEGIN

/* The following statement fails. */

FORALL i IN 1..3

UPDATE coords SET (x, y) = pairs(i)

WHERE x = nums(i);

END;

The workaround is to decompose the composite values manually:

DECLARE

TYPE PairTab IS TABLE OF Pair;

pairs PairTab := PairTab(Pair(1,2), Pair(3,4), Pair(5,6));

TYPE NumTab IS TABLE OF NUMBER;

nums NumTab := NumTab(1, 2, 3);

BEGIN

/* The following statement succeeds. */

FORALL i in 1..3

UPDATE coords SET (x, y) = (pairs(i).m, pairs(i).n)

WHERE x = nums(i);

END;

■

Collection subscripts cannot be expressions, as the following example shows:

FORALL j IN mgrs.FIRST..mgrs.LAST

DELETE FROM emp WHERE mgr = mgrs(j+1); -- invalid subscript

The cursor attribute

%BULK_ROWCOUNT

cannot be assigned to other collections.

Also, it cannot be passed as a parameter to subprograms.

The following example shows that 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

13-90

PL/SQL User’s Guide and Reference

FORALL Statement

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

Remember, the PL/SQL engine bulk-binds only subscripted collections. So, in the following example, it does not bulk-bind the collection sals

, which is passed to the function median

FORALL i IN 1..20

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

PL/SQL Language Elements

13-91

Functions

A function is a subprogram that can take parameters and be invoked. Generally, you use a function to compute a 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

(or

) 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 Oracle 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-6.

13-92

PL/SQL User’s Guide and Reference

Functions

Syntax function_spec

FUNCTION function_name

(

, parameter_declaration )

RETURN datatype ;

ffunction_declaration | function body

OR REPLACE

CREATE

(

, parameter_declaration )

FUNCTION function_name

RETURN datatype

AUTHID

CURRENT_USER

DEFINER

PARALLEL_ENABLE DETERMINISTIC

PL/SQL Language Elements

13-93

Functions

PRAGMA AUTONOMOUS_TRANSACTION ; type_definition item_declaration

EXCEPTION exception_handler function_declaration procedure_declaration function_name

END

BEGIN statement

;

parameter_declaration

OUT

IN OUT parameter_name

DEFAULT expression

NOCOPY datatype

Keyword and Parameter Description

AUTHID

This clause 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

CURRENT_USER

. For more information, see

"Invoker Rights Versus Definer Rights" on page 8-49.

CREATE

The optional

CREATE

clause lets you create 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.

13-94

PL/SQL User’s Guide and Reference

Functions

datatype

This is a type specifier. For the syntax of datatype

, see

DETERMINISTIC

This hint 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 Oracle9i SQL

Reference.

exception_handler

This associates an exception with a sequence of statements, which is executed when that exception is raised. For the syntax of exception_handler

, see

expression

This is 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

This identifies a user-defined function.

IN, OUT, IN OUT

These parameter modes define the behavior of formal parameters. An

IN parameter lets you pass values to the subprogram being called. An

OUT

parameter lets you return values to the caller of the subprogram. An

IN OUT

parameter lets you pass initial values to the subprogram being called and return updated values to the caller.

item_declaration

This declares a program object. For the syntax of item_declaration

, see

"Passing Large Data Structures with the NOCOPY Compiler Hint" on page 8-17.

PL/SQL Language Elements

13-95

Functions

NOCOPY

This is a compiler hint (not directive), which allows the PL/SQL compiler to pass

OUT and

IN OUT parameters by reference instead of by value (the default). For more information, see

PARALLEL_ENABLE

This option 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

This identifies a formal parameter, which is a variable declared in a function spec and referenced in the function body.

PRAGMA AUTONOMOUS_TRANSACTION

This pragma instructs the PL/SQL compiler to mark a function as autonomous

(independent). An autonomous transaction is an independent transaction started by another transaction, 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-53.

procedure_declaration

This declares a procedure. For the syntax of procedure_declaration

, see

RETURN

This keyword introduces the

RETURN

clause, which specifies the datatype of the return value.

type_definition

This specifies a user-defined datatype. For the syntax of type_definition

, see

"Controlling Side Effects of PL/SQL Subprograms" on page 8-9.

13-96

PL/SQL User’s Guide and Reference

Functions

:= | DEFAULT

This operator or keyword lets you initialize

parameters to default values.

Usage Notes

As the following example shows, 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 meant to control side effects. See

In a function, there must be at least one execution path that leads to a

RETURN statement. Otherwise, you get a function returned without value error at run time.

Also, 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

parameter acts like a constant. So, you cannot assign it a value. An

OUT

parameter acts like a local variable. So, you can change its value and reference the value in any way. An

IN OUT

parameter acts like an initialized variable. So, you can assign it a value, which can be assigned to another variable.

For summary information about the parameter modes, see

Table 8–1 on page 8-16.

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. Also, functions should be free from side effects, which change the values of variables not local to the subprogram.

PL/SQL Language Elements

13-97

Functions

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

"GOTO Statement" on page 4-17.

13-98

PL/SQL User’s Guide and Reference

GOTO Statement

The

GOTO

statement branches unconditionally to a statement label or block label.

The label must be unique within its scope and must precede an executable statement or a PL/SQL block. The

GOTO

statement transfers control to the labelled statement or block. For more information, see

Syntax label_declaration

<< label_name >>

goto_statement

GOTO label_name ;

Keyword and Parameter Description

label_name

This is an undeclared identifier that labels an executable statement or a PL/SQL block. You use a

GOTO

statement to transfer control to the statement or block following

<<label_name>>

Usage Notes

Some possible destinations of a

GOTO

statement are not allowed. In particular, a

GOTO

statement cannot branch into an

statement,

LOOP

statement, or sub-block.

For example, the following

GOTO

statement is not allowed:

BEGIN

...

GOTO update_row; -- can’t branch into IF statement

...

IF valid THEN

...

<<update_row>>

UPDATE emp SET ...

END IF;

PL/SQL Language Elements

13-99

GOTO Statement

Examples

From the current block, a

GOTO

statement can branch to another place in the block or into an enclosing block, but not into an exception handler. From an exception handler, a

GOTO

statement can branch into an enclosing block, but not into the current block.

If you use the

GOTO

statement to exit a cursor

FOR

loop prematurely, the cursor is closed automatically. The cursor is also closed automatically if an exception is raised inside the loop.

A given label can appear only once in a block. However, the label can appear in other blocks including enclosing blocks and sub-blocks. If a

GOTO

statement cannot find its target label in the current block, it branches to the first enclosing block in which the label appears.

GOTO

label cannot precede just any keyword. It must precede an executable statement or a PL/SQL block. For example, the following

GOTO

statement is not allowed:

FOR ctr IN 1..50 LOOP

DELETE FROM emp WHERE ...

IF SQL%FOUND THEN

GOTO end_loop; -- not allowed

END IF;

...

<<end_loop>>

END LOOP; -- not an executable statement

To debug the last example, simply add the

NULL

statement, as follows:

FOR ctr IN 1..50 LOOP

DELETE FROM emp WHERE ...

IF SQL%FOUND THEN

GOTO end_loop;

END IF;

...

<<end_loop>>

NULL; -- an executable statement that specifies inaction

END LOOP;

13-100

PL/SQL User’s Guide and Reference

IF Statement

The

statement lets you execute a sequence of statements conditionally. Whether the sequence is executed or not depends on the value of a Boolean expression. For more information, see

"Conditional Control: IF and CASE Statements" on page 4-2.

Syntax if_statement

IF boolean_expression THEN statement

ELSIF boolean_expression THEN statement

ELSE statement

END IF ;

Keyword and Parameter Description

boolean_expression

This is an expression that yields the Boolean value

TRUE

FALSE

, or

NULL

. It is associated with a sequence of statements, which is executed only if the expression yields

TRUE

ELSE

If control reaches this keyword, the sequence of statements that follows it is executed.

ELSIF

This keyword introduces a Boolean expression to be evaluated if the expression following

and all the expressions following any preceding

ELSIF s yield

FALSE or

NULL

PL/SQL Language Elements

13-101

IF Statement

THEN

This keyword associates the Boolean expression that precedes it with the sequence of statements that follows it. If the expression yields

TRUE

, the associated sequence of statements is executed.

Usage Notes

There are three forms of

statements:

IF-THEN

IF-THEN-ELSE

, and

IF-THEN-ELSIF

. The simplest form of

statement associates a Boolean expression with a sequence of statements enclosed by the keywords

THEN

and

END

. The sequence of statements is executed only if the expression yields

TRUE

. If the expression yields

FALSE

NULL

, the

statement does nothing. In either case, control passes to the next statement.

The second form of

statement adds the keyword

ELSE

followed by an alternative sequence of statements. The sequence of statements in the

ELSE clause is executed only if the Boolean expression yields

FALSE

NULL

. Thus, the

ELSE clause ensures that a sequence of statements is executed.

The third form of

statement uses the keyword

ELSIF

to introduce additional

Boolean expressions. If the first expression yields

FALSE

NULL

, the

ELSIF

clause evaluates another expression. An

statement can have any number of

ELSIF clauses; the final

ELSE

clause is optional. Boolean expressions are evaluated one by one from top to bottom. If any expression yields

TRUE

, its associated sequence of statements is executed and control passes to the next statement. If all expressions yield

FALSE

NULL

, the sequence in the

ELSE

clause is executed.

statement never executes more than one sequence of statements because processing is complete after any sequence of statements is executed. However, the

THEN

and

ELSE

clauses can include more

statements. That is,

statements can be nested.

13-102

PL/SQL User’s Guide and Reference

IF Statement

Examples

In the example below, if shoe_count

has a value of 10, both the first and second

Boolean expressions yield

TRUE

. Nevertheless, order_quantity

is assigned the proper value of 50 because processing of an

statement stops after an expression yields

TRUE

and its associated sequence of statements is executed. The expression associated with

ELSIF

is never evaluated and control passes to the

INSERT statement.

IF shoe_count < 20 THEN

order_quantity := 50;

ELSIF shoe_count < 30 THEN

order_quantity := 20;

ELSE

order_quantity := 10;

END IF;

INSERT INTO purchase_order VALUES (shoe_type, order_quantity);

In the following example, depending on the value of score

, one of two status messages is inserted into the grades

table:

IF score < 70 THEN

fail := fail + 1;

INSERT INTO grades VALUES (student_id, ’Failed’);

ELSE

pass := pass + 1;

INSERT INTO grades VALUES (student_id, ’Passed’);

END IF;

Related Topics

CASE Statement ,

Expressions

PL/SQL Language Elements

13-103

INSERT Statement

The

INSERT

statement adds new rows of data to a specified database table. For a full description of the

INSERT

statement, see Oracle9i SQL Reference.

Syntax insert_statement

INSERT INTO

( table_reference

( subquery

TABLE (

) subquery2

)

, column_name ) alias

, sql_expression returning_clause

VALUES ( subquery3

)

;

Keyword and Parameter Description

alias

This is another (usually short) name for the referenced table or view.

column_name[, column_name]...

This identifies a list of columns in a database table or view. Column names need not appear in the order in which they were defined by the

CREATE TABLE

CREATE

VIEW statement. However, no column name can appear more than once in the list. If the list does not include all the columns in a table, the missing columns are set to

NULL

or to a default value specified in the

CREATE TABLE

statement.

13-104

PL/SQL User’s Guide and Reference

INSERT Statement

returning_clause

This clause lets you return values from inserted rows, thereby eliminating the need to

SELECT

the rows afterward. You can retrieve the column values into variables and/or host variables, or into collections and/or host arrays. However, you cannot use the

RETURNING

clause for remote or parallel inserts. For the syntax of returning_clause

, see

sql_expression

This is any expression valid in SQL. For more information, see Oracle9i SQL

Reference.

subquery

This is a

SELECT

statement that provides a set of rows for processing. Its syntax is like that of select_into_statement

without the

INTO

clause. See

subquery3

This is a

SELECT

statement that returns a value or set of values. As many rows are added to the table as are returned by the subquery. It must return a value for every column in the column list or for every column in the table if there is no column list.

table_reference

This identifies a table or view that must be accessible when you execute the

INSERT statement, and for which you must have

INSERT

privileges. For the syntax of table_reference

, see

TABLE (subquery2)

The operand of

TABLE

is a

SELECT

statement that returns a single column value, which must be a nested table. Operator

TABLE

informs Oracle that the value is a collection, not a scalar value.

VALUES (...)

This clause assigns the values of expressions to corresponding columns in the column list. If there is no column list, the first value is inserted into the first column defined by the

CREATE TABLE

statement, the second value is inserted into the second column, and so on. There must be only one value for each column in the column list. Also, the datatypes of the values being inserted must be compatible with the datatypes of corresponding columns in the column list.

PL/SQL Language Elements

13-105

INSERT Statement

Usage Notes

Character and date literals in the

VALUES

list must be enclosed by single quotes (’).

Numeric literals are not enclosed by quotes.

The implicit cursor

SQL

and the cursor attributes

%NOTFOUND

%FOUND

%ROWCOUNT

, and

%ISOPEN

let you access useful information about the execution of an

INSERT

statement.

Examples

The following examples show various forms of

INSERT

statement:

INSERT INTO bonus SELECT ename, job, sal, comm FROM emp

WHERE comm > sal * 0.25;

...

INSERT INTO emp (empno, ename, job, sal, comm, deptno)

VALUES (4160, ’STURDEVIN’, ’SECURITY GUARD’, 2045, NULL, 30);

...

INSERT INTO dept

VALUES (my_deptno, UPPER(my_dname), ’CHICAGO’);

Related Topics

13-106

PL/SQL User’s Guide and Reference

Literals

Syntax

A literal is an explicit numeric, character, string, or Boolean value not represented by an identifier. The numeric literal 135 and the string literal

’hello world’

are examples. For more information, see

"Literals" on page 2-7.

numeric_literal

_ integer real_number

integer

digit

real_number

integer

character_literal

’ ’

’ character

’

string_literal

’ ’

’ character

’

E e

_ integer

PL/SQL Language Elements

13-107

Literals

boolean_literal

TRUE

FALSE

NULL

Keyword and Parameter Description

character

This is a member of the PL/SQL character set. For more information, see

"Character

Set" on page 2-2.

digit

This is one of the numerals 0 .. 9.

TRUE, FALSE, NULL

This is a predefined Boolean value.

Usage Notes

Two kinds of numeric literals can be used in arithmetic expressions: integers and reals. Numeric literals must be separated by punctuation. Spaces can be used in addition to the punctuation.

A character literal is an individual character enclosed by single quotes

(apostrophes). Character literals include all the printable characters in the PL/SQL character set: letters, numerals, spaces, and special symbols.

PL/SQL is case sensitive within character literals. So, for example, PL/SQL considers the literals

’Q’

and

’q’

to be different.

A string literal is a sequence of zero or more characters enclosed by single quotes.

The null string (

’’

) contains zero characters. To represent an apostrophe within a string, write two single quotes. PL/SQL is case sensitive within string literals. So, for example, PL/SQL considers the literals

’white’

and

’White’

to be different.

Also, trailing blanks are significant within string literals, so

’abc’

and

’abc ’

are different. Trailing blanks in a literal are never trimmed.

The Boolean values

TRUE

and

FALSE

cannot be inserted into a database column.

13-108

PL/SQL User’s Guide and Reference

Examples

Several examples of numeric literals follow:

25 6.34 7E2 25e-03 .1 1. +17 -4.4

Several examples of character literals follow:

’H’ ’&’ ’ ’ ’9’ ’]’ ’g’

A few examples of string literals follow:

’$5,000’

’02-AUG-87’

’Don’’t leave without saving your work.’

Related Topics

"Using LOCK TABLE" on page 6-51.

Expressions

Literals

PL/SQL Language Elements

13-109

LOCK TABLE Statement

The

LOCK TABLE

statement lets you lock entire database tables in a specified lock mode. That enables you to share or deny access to tables while maintaining their integrity. For more information, see

Syntax lock_table_statement

LOCK TABLE

, table_reference IN lock_mode MODE

NOWAIT

;

Keyword and Parameter Description

table_reference

This identifies a table or view that must be accessible when you execute the

LOCK

TABLE

statement. For the syntax of table_reference

, see

lock_mode

This parameter specifies the lock mode. It must be one of the following:

ROW SHARE

ROW EXCLUSIVE

SHARE UPDATE

SHARE ROW EXCLUSIVE

, or

EXCLUSIVE

NOWAIT

This optional keyword tells Oracle not to wait if the table has been locked by another user. Control is immediately returned to your program, so it can do other work before trying again to acquire the lock.

Usage Notes

If you omit the keyword

NOWAIT

, Oracle waits until the table is available; the wait has no set limit. Table locks are released when your transaction issues a commit or rollback.

A table lock never keeps other users from querying a table, and a query never acquires a table lock.

13-110

PL/SQL User’s Guide and Reference

LOCK TABLE Statement

If your program includes SQL locking statements, make sure the Oracle users requesting locks have the privileges needed to obtain the locks. Your DBA can lock any table. Other users can lock tables they own or tables for which they have a privilege, such as

SELECT

INSERT

UPDATE

, or

DELETE

Example

The following statement locks the accts

table in shared mode:

LOCK TABLE accts IN SHARE MODE;

Related Topics

"Iterative Control: LOOP and EXIT Statements" on page 4-9.

ROLLBACK Statement

PL/SQL Language Elements

13-111

LOOP Statements

LOOP statements execute a sequence of statements multiple times. The loop encloses the sequence of statements that is to be repeated. PL/SQL provides four kinds of loop statements: basic loop,

WHILE

loop,

FOR

loop, and cursor

FOR

loop. For more information, see

Syntax basic_loop_statement

<< label_name >>

LOOP statement END LOOP

while_loop_statement

<< label_name >>

LOOP statement

WHILE boolean_expression label_name

END LOOP ;

for_loop_statement

<< label_name >>

FOR index_name IN

REVERSE

LOOP statement lower_bound ..

upper_bound label_name

END LOOP ; label_name

;

13-112

PL/SQL User’s Guide and Reference

LOOP Statements

cursor_for_loop_statement

<< label_name >>

FOR record_name IN

( cursor_name select_statement

(

)

, cursor_parameter_name label_name

LOOP statement END LOOP

)

;

Keyword and Parameter Description

basic_loop_statement

The simplest form of

LOOP

statement is the basic (or infinite) loop, which encloses a sequence of statements between the keywords

LOOP

and

END LOOP

. With each iteration of the loop, the sequence of statements is executed, then control resumes at the top of the loop. If further processing is undesirable or impossible, you can use the

EXIT

GOTO

, or

RAISE

statement to complete the loop. A raised exception will also complete the loop.

boolean_expression

This is an expression that yields the Boolean value

TRUE

FALSE

, or

NULL

. It is associated with a sequence of statements, which is executed only if the expression yields

TRUE

. For the syntax of boolean_expression

, see

"Expressions" on page 13-73.

cursor_for_loop_statement

A cursor

FOR

loop implicitly declares its loop index as a

%ROWTYPE

record, opens a cursor, repeatedly fetches rows of values from the result set into fields in the record, and closes the cursor when all rows have been processed.

PL/SQL Language Elements

13-113

LOOP Statements

cursor_name

This identifies an explicit cursor previously declared within the current scope.

When the cursor

FOR

loop is entered, cursor_name

cannot refer to a cursor already opened by an

OPEN

statement or an enclosing cursor

FOR

loop.

cursor_parameter_name

This identifies a cursor parameter; that is, a variable declared as the formal parameter of a cursor. (For the syntax of cursor_parameter_declaration

, see

"Cursors" on page 13-54.) A cursor parameter can appear in a query wherever a

constant can appear. The formal parameters of a cursor must be

parameters.

for_loop_statement

Whereas the number of iterations through a

WHILE

loop is unknown until the loop completes, the number of iterations through a

FOR

loop is known before the loop is entered. Numeric

FOR

loops iterate over a specified range of integers. The range is part of an iteration scheme, which is enclosed by the keywords

FOR

and

LOOP

The range is evaluated when the

FOR

loop is first entered and is never re-evaluated.

The sequence of statements in the loop is executed once for each integer in the range defined by lower_bound..upper_bound

. After each iteration, the loop index is incremented.

index_name

This is an undeclared identifier that names the loop index (sometimes called a loop counter). Its scope is the loop itself. Therefore, you cannot reference the index outside the loop.

The implicit declaration of index_name overrides any other declaration outside the loop. So, another variable with the same name cannot be referenced inside the loop unless a label is used, as follows:

<<main>>

DECLARE

num NUMBER;

BEGIN

...

FOR num IN 1..10 LOOP

IF main.num > 5 THEN -- refers to the variable num,

... -- not to the loop index

END IF;

END LOOP;

END main;

13-114

PL/SQL User’s Guide and Reference

LOOP Statements

Inside a loop, its index is treated like a constant. The index can appear in expressions, but cannot be assigned a value.

label_name

This is an undeclared identifier that optionally labels a loop. If used, label_name must be enclosed by double angle brackets and must appear at the beginning of the loop. Optionally, label_name

(not enclosed in angle brackets) can also appear at the end of the loop.

You can use label_name

in an

EXIT

statement to exit the loop labelled by label_name

. You can exit not only the current loop, but any enclosing loop.

You cannot reference the index of a

FOR loop from a nested

FOR loop if both indexes have the same name unless the outer loop is labeled by label_name

and you use dot notation, as follows: label_name.index_name

In the following example, you compare two loop indexes that have the same name, one used by an enclosing loop, the other by a nested loop:

<<outer>>

FOR ctr IN 1..20 LOOP

...

<<inner>>

FOR ctr IN 1..10 LOOP

IF outer.ctr > ctr THEN ...

END LOOP inner;

END LOOP outer;

lower_bound .. upper_bound

These are expressions that must yield numbers. Otherwise, PL/SQL raises the predefined exception

VALUE_ERROR

. The expressions are evaluated only when the loop is first entered. The lower bound need not be 1, as the example below shows.

However, the loop counter increment (or decrement) must be 1.

FOR i IN -5..10 LOOP

...

END LOOP;

PL/SQL Language Elements

13-115

LOOP Statements

Internally, PL/SQL assigns the values of the bounds to temporary

PLS_INTEGER variables, and, if necessary, rounds the values to the nearest integer. The magnitude range of a

PLS_INTEGER

+/- 2**31

. So, if a bound evaluates to a number outside that range, you get a numeric overflow error when PL/SQL attempts the assignment.

By default, the loop index is assigned the value of lower_bound

. If that value is not greater than the value of upper_bound

, the sequence of statements in the loop is executed, then the index is incremented. If the value of the index is still not greater than the value of upper_bound

, the sequence of statements is executed again. This process repeats until the value of the index is greater than the value of upper_bound

. At that point, the loop completes.

record_name

This identifies an implicitly declared record. The record has the same structure as a row retrieved by cursor_name

or select_statement

The record is defined only inside the loop. You cannot refer to its fields outside the loop. The implicit declaration of record_name

overrides any other declaration outside the loop. So, another record with the same name cannot be referenced inside the loop unless a label is used.

Fields in the record store column values from the implicitly fetched row. The fields have the same names and datatypes as their corresponding columns. To access field values, you use dot notation, as follows: record_name.field_name

Select-items fetched from the

FOR

loop cursor must have simple names or, if they are expressions, must have aliases. In the following example, wages

is an alias for the select item sal+NVL(comm,0)

CURSOR c1 IS SELECT empno, sal+comm wages, job ...

REVERSE

By default, iteration proceeds upward from the lower bound to the upper bound.

However, if you use the keyword

REVERSE

, iteration proceeds downward from the upper bound to the lower bound.

An example follows:

FOR i IN REVERSE 1..10 LOOP -- i starts at 10, ends at 1

-- statements here execute 10 times

END LOOP;

13-116

PL/SQL User’s Guide and Reference

LOOP Statements

The loop index is assigned the value of upper_bound

. If that value is not less than the value of lower_bound

, the sequence of statements in the loop is executed, then the index is decremented. If the value of the index is still not less than the value of lower_bound

, the sequence of statements is executed again. This process repeats until the value of the index is less than the value of lower_bound

. At that point, the loop completes.

select_statement

This is a query associated with an internal cursor unavailable to you. Its syntax is like that of select_into_statement

without the

INTO

clause. See

INTO Statement" on page 13-166. PL/SQL automatically declares, opens, fetches

from, and closes the internal cursor. Because select_statement

is not an independent statement, the implicit cursor

SQL

does not apply to it.

while_loop_statement

The

WHILE-LOOP

statement associates a Boolean expression with a sequence of statements enclosed by the keywords

LOOP

and

END LOOP

. Before each iteration of the loop, the expression is evaluated. If the expression yields

TRUE

, the sequence of statements is executed, then control resumes at the top of the loop. If the expression yields

FALSE

NULL

, the loop is bypassed and control passes to the next statement.

Usage Notes

You can use the

EXIT WHEN

statement to exit any loop prematurely. If the Boolean expression in the

WHEN

clause yields

TRUE

, the loop is exited immediately.

When you exit a cursor

FOR

loop, the cursor is closed automatically even if you use an

EXIT

GOTO

statement to exit the loop prematurely. The cursor is also closed automatically if an exception is raised inside the loop.

PL/SQL Language Elements

13-117

LOOP Statements

Example

The following cursor

FOR

loop calculates a bonus, then inserts the result into a database table:

DECLARE

bonus REAL;

CURSOR c1 IS SELECT empno, sal, comm FROM emp;

BEGIN

FOR c1rec IN c1 LOOP

bonus := (c1rec.sal * 0.05) + (c1rec.comm * 0.25);

INSERT INTO bonuses VALUES (c1rec.empno, bonus);

END LOOP;

COMMIT;

END;

Related Topics

13-118

PL/SQL User’s Guide and Reference

MERGE Statement

The

MERGE

statement inserts some rows and updates others in a single operation.

The decision about whether to update or insert into the target table is based upon a join condition: rows already in the target table that match the join condition are updated; otherwise a row is inserted using values from a separate subquery.

For the syntax and full details of this statement, see the Oracle9i SQL Reference.

Usage Notes

This statement is primarily useful in data warehousing situations where large amounts of data are commonly inserted and updated.

Examples

The following example creates a bonuses table in the sample schema oe

with a default bonus of 100. It then inserts into the bonuses table all employees who made sales (based on the sales_rep_id column

of the oe.orders

table). Finally, the

Human Resources manager decides that all employees should receive a bonus:

■

Those who have not made sales get a bonus of 1% of their salary.

Those who already made sales get an increase in their bonus equal to 1% of their salary.

The

MERGE

statement implements these changes in one step:

CREATE TABLE bonuses (employee_id NUMBER, bonus NUMBER DEFAULT 100);

INSERT INTO bonuses(employee_id)

(SELECT e.employee_id FROM employees e, orders o

WHERE e.employee_id = o.sales_rep_id

GROUP BY e.employee_id);

SELECT * FROM bonuses;

EMPLOYEE_ID BONUS

----------- ----------

153 100

154 100

155 100

156 100

158 100

159 100

160 100

161 100

PL/SQL Language Elements

13-119

MERGE Statement

163 100

MERGE INTO bonuses D

USING (SELECT employee_id, salary, department_id FROM employees

WHERE department_id = 80) S

ON (D.employee_id = S.employee_id)

WHEN MATCHED THEN UPDATE SET D.bonus = D.bonus + S.salary*.01

WHEN NOT MATCHED THEN INSERT (D.employee_id, D.bonus)

VALUES (S.employee_id, S.salary*0.1);

EMPLOYEE_ID BONUS

----------- ----------

153 180

154 175

155 170

156 200

158 190

159 180

160 175

161 170

163 195

157 950

145 1400

170 960

179 620

152 900

169 1000

...

13-120

PL/SQL User’s Guide and Reference

NULL Statement

The

NULL

statement explicitly specifies inaction; it does nothing other than pass control to the next statement. In a construct allowing alternative actions, the

NULL statement serves as a placeholder. For more information, see

"NULL Statement" on page 4-21.

Syntax null_statement

NULL ;

Usage Notes

The

NULL

statement improves readability by making the meaning and action of conditional statements clear. It tells readers that the associated alternative has not been overlooked, but that indeed no action is necessary.

Each clause in an

statement must contain at least one executable statement. The

NULL

statement meets this requirement. So, you can use the

NULL

statement in clauses that correspond to circumstances in which no action is taken. The

NULL statement and Boolean value

NULL

are unrelated.

Examples

In the following example, the

NULL

statement emphasizes that only salespeople receive commissions:

IF job_title = ’SALESPERSON’ THEN

compute_commission(emp_id);

ELSE

NULL;

END IF;

In the next example, the

NULL

statement shows that no action is taken for unnamed exceptions:

EXCEPTION

...

WHEN OTHERS THEN

NULL;

PL/SQL Language Elements

13-121

Object Types

An object type is a user-defined composite datatype that encapsulates a data structure along with the functions and procedures needed to manipulate the data.

The variables that form the data structure are called attributes. The functions and procedures that characterize the behavior of the object type are called methods. A special kind of method called the constructor creates a new instance of the object type and fills in its attributes.

Object types must be created through SQL and stored in an Oracle database, where they can be shared by many programs. When you define an object type using the

CREATE TYPE statement, you create an abstract template for some real-world object.

The template specifies the attributes and behaviors the object needs in the application environment.

For more information on using object types, see

Chapter 10 .

Syntax object_type_declaration | object_type_spec

OR REPLACE

CREATE TYPE

AUTHID

CURRENT_USER

DEFINER

AS schema_name .

OBJECT ( type_name member_list ) ;

member_list

, attribute_name attribute_type

13-122

PL/SQL User’s Guide and Reference

Object Types

MEMBER

CONSTRUCTOR

STATIC subprogram_spec call_spec

MAP

ORDER

MEMBER function_spec

, PRAGMA_RESTRICT_REFERENCES

object_type_body

OR REPLACE schema_name .

CREATE TYPE BODY type_name

MEMBER

CONSTRUCTOR

STATIC subprogram_body call_spec

;

MAP

ORDER

MEMBER function_body ;

END ;

Keyword and Parameter Description

attribute_datatype

This is any Oracle datatype except

LONG

LONG RAW

ROWID

UROWID

, the

PL/SQL-specific types

BINARY_INTEGER

(and its subtypes),

BOOLEAN

PLS_INTEGER

RECORD

REF CURSOR

%TYPE

, and

%ROWTYPE

, and types defined inside a PL/SQL package.

attribute_name

This identifies an object attribute. The name must be unique within the object type

(but can be reused in other object types). You cannot initialize an attribute in its

PL/SQL Language Elements

13-123

Object Types declaration using the assignment operator or

DEFAULT

clause. Also, you cannot impose the

NOT NULL

constraint on an attribute.

AUTHID Clause

This determines whether all member methods execute with the privileges of their definer (the default) or invoker, and whether their unqualified references to schema objects are resolved in the schema of the definer or invoker. For more information, see

"Invoker Rights Versus Definer Rights" on page 8-49.

call_spec

This publishes a Java method or external C function in the Oracle data dictionary. It publishes the routine by mapping its name, parameter types, and return type to their SQL counterparts. To learn how to write Java call specs, see Oracle9i Java Stored

Procedures Developer’s Guide. To learn how to write C call specs Oracle9i Application

Developer’s Guide - Fundamentals.

function_body

This defines the underlying implementation of a

CONSTRUCTOR

MEMBER

, or

STATIC

function. For the syntax of function_body

, see

"RESTRICT_REFERENCES Pragma" on page 13-156 (in this context, omit the pragma terminator).

MAP

This keyword indicates that a method orders objects by mapping them to values of a scalar datatype such as

CHAR

REAL

, which have a predefined order. PL/SQL uses the ordering to evaluate Boolean expressions such as x > y

, and to do comparisons implied by the

DISTINCT

GROUP BY

, and

ORDER BY

clauses. A map method returns the relative position of an object in the ordering of all such objects.

An object type can contain only one map method, which must be a parameterless function having the return type

DATE

NUMBER

VARCHAR2

, or an ANSI SQL type such as

CHARACTER

INTEGER

, or

REAL

MEMBER | CONSTRUCTOR | STATIC

This keyword lets you declare a subprogram or call spec as a method in an object type spec. A constructor method must have the same name as the object type, while member and static methods must have names that are different from the object type or any of its attributes.

MEMBER

methods are invoked on instances of objects, and read or change the attributes of that particular instance:

13-124

PL/SQL User’s Guide and Reference

Object Types object_instance.method();

CONSTRUCTOR methods create new instances of objects, and fill in some or all of the attributes: object_instance := new object_type_name(attr1 => attr1_value,

attr2 => attr2_value);

The system defines a default constructor method with one parameter for each object attribute, so you only need to define your own constructor methods if you want to construct the object based on a different set of parameters.

STATIC

methods are invoked on the object type, not any specific object instance, and thus must limit themselves to "global" operations that do not involve the object attributes: object_type.method()

For each subprogram spec in an object type spec, there must be a corresponding subprogram body in the object type body. To match specs and bodies, the compiler does a token-by-token comparison of their headers. So, the headers must match word for word.

CONSTRUCTOR

and

MEMBER

methods accept a built-in parameter named

SELF

, which is an instance of the object type. Whether declared implicitly or explicitly, it is always the first parameter passed to a

MEMBER method. However,

STATIC methods cannot accept or reference

SELF

In the method body,

SELF

denotes the object whose method was invoked. For example, method transform

declares

SELF

as an

IN OUT

parameter:

CREATE TYPE Complex AS OBJECT (

MEMBER FUNCTION transform (SELF IN OUT Complex) ...

You cannot specify a different datatype for

SELF

. In constructor functions, SELF always has the parameter mode

IN OUT

. In

MEMBER

functions, if

SELF

is not declared, its parameter mode defaults to

. In

MEMBER

procedures, if

SELF

is not declared, its parameter mode defaults to

IN OUT

. You cannot specify the

OUT parameter mode for

SELF

ORDER

This keyword indicates that a method compares two objects. An object type can contain only one order method, which must be a function that returns a numeric result.

PL/SQL Language Elements

13-125

Object Types

Every order method takes just two parameters: the built-in parameter

SELF

and another object of the same type. If c1

and c2

are

Customer

objects, a comparison such as c1 > c2 calls method match automatically. The method returns a negative number, zero, or a positive number signifying that

SELF

is respectively less than, equal to, or greater than the other parameter. If either parameter passed to an order method is null, the method returns a null.

pragma_restrict_refs

This is pragma

RESTRICT_REFERENCES

, which lets you check for violations of

"purity" rules. To be callable from SQL statements, a member function must obey those rules, which are meant to control side effects. If any SQL statement inside the function body violates a rule, you get an error at run time (when the statement is parsed). For the syntax of the pragma, see

The pragma asserts that a member function does not read and/or write database tables and/or package variables. For more information about the purity rules and pragma

RESTRICT_REFERENCES

, see Oracle9i Application Developer’s Guide -

Fundamentals.

schema_name

This qualifier identifies the schema containing the object type. If you omit schema_name

, Oracle assumes the object type is in your schema.

subprogram_body

This defines the underlying implementation of a

MEMBER

STATIC

function or procedure. Its syntax is like that of function_body

or procedure_body

without the terminator. See

"Functions" on page 13-92 and/or

"Functions" on page 13-92 and/or

subprogram_spec

This declares the interface to a

CONSTRUCTOR

MEMBER

STATIC

function or procedure. Its syntax is like that of function_spec

or procedure_spec

without the terminator. See

type_name

This identifies a user-defined object type that was defined using the datatype specifier

OBJECT

13-126

PL/SQL User’s Guide and Reference

Object Types

Usage Notes

Once an object type is defined and installed in the schema, you can use it to declare objects in any PL/SQL block, subprogram, or package. For example, you can use the object type to specify the datatype of an object attribute, table column, PL/SQL variable, bind variable, record field, collection element, formal procedure parameter, or function result.

Like a package, an object type has two parts: a specification and a body. The specification (spec for short) is the interface to your applications; it declares a data structure (set of attributes) along with the operations (methods) needed to manipulate the data. The body fully defines the methods, and so implements the spec.

An object type encapsulates data and operations. So, you can declare attributes and methods in an object type spec, but not constants, exceptions, cursors, or types. At least one attribute is required (the maximum is 1000); methods are optional.

In an object type spec, all attributes must be declared before any methods. Only subprograms have an underlying implementation. So, if an object type spec declares only attributes and/or call specs, the object type body is unnecessary. You cannot declare attributes in the body. All declarations in the object type spec are public

(visible outside the object type).

You can refer to an attribute only by name (not by its position in the object type). To access or change the value of an attribute, you use dot notation. Attribute names can be chained, which lets you access the attributes of a nested object type.

In an object type, methods can reference attributes and other methods without a qualifier. In SQL statements, calls to a parameterless method require an empty parameter list. In procedural statements, an empty parameter list is optional unless you chain calls, in which case it is required for all but the last call.

From a SQL statement, if you call a

MEMBER method on a null instance (that is,

SELF is null), the method is not invoked and a null is returned. From a procedural statement, if you call a

MEMBER

method on a null instance, PL/SQL raises the predefined exception

SELF_IS_NULL

before the method is invoked.

You can declare a map method or an order method but not both. If you declare either method, you can compare objects in SQL and procedural statements.

However, if you declare neither method, you can compare objects only in SQL

PL/SQL Language Elements

13-127

Object Types

Examples

statements and only for equality or inequality. Two objects of the same type are equal only if the values of their corresponding attributes are equal.

Every object type has a default constructor method (constructor for short), which is a system-defined function with the same name as the object type. You use the constructor to initialize and return an instance of that object type. You can also define your own constructor methods that accept different sets of parameters.

PL/SQL never calls a constructor implicitly, so you must call it explicitly.

Constructor calls are allowed wherever function calls are allowed.

In the SQL*Plus script below, an object type for a stack is defined. The last item added to a stack is the first item removed. The operations push and pop update the stack while preserving last in, first out (LIFO) behavior. The simplest implementation of a stack uses an integer array. Integers are stored in array elements, with one end of the array representing the top of the stack.

CREATE TYPE IntArray AS VARRAY(25) OF INTEGER;

CREATE TYPE Stack AS OBJECT (

max_size INTEGER,

top INTEGER,

position IntArray,

MEMBER PROCEDURE initialize,

MEMBER FUNCTION full RETURN BOOLEAN,

MEMBER FUNCTION empty RETURN BOOLEAN,

MEMBER PROCEDURE push (n IN INTEGER),

MEMBER PROCEDURE pop (n OUT INTEGER)

);

CREATE TYPE BODY Stack AS

MEMBER PROCEDURE initialize IS

-- fill stack with nulls

BEGIN

top := 0;

-- call constructor for varray and set element 1 to NULL

position := IntArray(NULL);

max_size := position.LIMIT; -- use size constraint (25)

position.EXTEND(max_size - 1, 1); -- copy element 1

END initialize;

13-128

PL/SQL User’s Guide and Reference

Object Types

MEMBER FUNCTION full RETURN BOOLEAN IS

-- return TRUE if stack is full

BEGIN

RETURN (top = max_size);

END full;

MEMBER FUNCTION empty RETURN BOOLEAN IS

-- return TRUE if stack is empty

BEGIN

RETURN (top = 0);

END empty;

MEMBER PROCEDURE push (n IN INTEGER) IS

-- push integer onto stack

BEGIN

IF NOT full THEN

top := top + 1;

position(top) := n;

ELSE -- stack is full

RAISE_APPLICATION_ERROR(-20101, ’stack overflow’);

END IF;

END push;

MEMBER PROCEDURE pop (n OUT INTEGER) IS

-- pop integer off stack and return its value

BEGIN

IF NOT empty THEN

n := position(top);

top := top - 1;

ELSE -- stack is empty

RAISE_APPLICATION_ERROR(-20102, ’stack underflow’);

END IF;

END pop;

END;

In methods push

and pop

, the built-in procedure raise_application_error issues user-defined error messages. That way, you can report errors to the client program and avoid returning unhandled exceptions to the host environment. In an object type, methods can reference attributes and other methods without a qualifier, as the following example shows:

CREATE TYPE Stack AS OBJECT (

top INTEGER,

MEMBER FUNCTION full RETURN BOOLEAN,

PL/SQL Language Elements

13-129

Object Types

MEMBER PROCEDURE push (n IN INTEGER),

...

);

CREATE TYPE BODY Stack AS

...

MEMBER PROCEDURE push (n IN INTEGER) IS

BEGIN

IF NOT full THEN

top := top + 1;

...

END push;

END;

The following example shows that you can nest object types:

CREATE TYPE Address AS OBJECT (

street_address VARCHAR2(35),

city VARCHAR2(15),

state CHAR(2),

zip_code INTEGER

);

CREATE TYPE Person AS OBJECT (

first_name VARCHAR2(15),

last_name VARCHAR2(15),

birthday DATE,

home_address Address, -- nested object type

phone_number VARCHAR2(15),

ss_number INTEGER,

);

Related Topics

Packages ,

13-130

PL/SQL User’s Guide and Reference

OPEN Statement

The

OPEN

statement executes the multi-row query associated with an explicit cursor. It also allocates resources used by Oracle to process the query and identifies the result set, which consists of all rows that meet the query search criteria. The cursor is positioned before the first row in the result set. For more information, see

"Cursors" on page 13-54.) A cursor parameter can appear in a query wherever a

Syntax open_statement

(

, cursor_parameter_name )

OPEN cursor_name ;

Keyword and Parameter Description

cursor_name

This identifies an explicit cursor previously declared within the current scope and not currently open.

cursor_parameter_name

This identifies a cursor parameter; that is, a variable declared as the formal parameter of a cursor. (For the syntax of cursor_parameter_declaration

, see

constant can appear.

Usage Notes

Generally, PL/SQL parses an explicit cursor only the first time it is opened and parses a SQL statement (thereby creating an implicit cursor) only the first time the statement is executed. All the parsed SQL statements are cached. A SQL statement must be reparsed only if it is aged out of the cache by a new SQL statement.

So, although you must close a cursor before you can reopen it, PL/SQL need not reparse the associated

SELECT

statement. If you close, then immediately reopen the cursor, a reparse is definitely not needed.

PL/SQL Language Elements

13-131

OPEN Statement

Rows in the result set are not retrieved when the

OPEN

statement is executed.

Rather, the

FETCH

statement retrieves the rows. With a

FOR UPDATE

cursor, the rows are locked when the cursor is opened.

If formal parameters are declared, actual parameters must be passed to the cursor.

The formal parameters of a cursor must be

parameters. Therefore, they cannot return values to actual parameters. The values of actual parameters are used when the cursor is opened. The datatypes of the formal and actual parameters must be compatible. The query can also reference PL/SQL variables declared within its scope.

Unless you want to accept default values, each formal parameter in the cursor declaration must have a corresponding actual parameter in the

OPEN

statement.

Formal parameters declared with a default value need not have a corresponding actual parameter. They can simply assume their default values when the

OPEN statement is executed.

You can associate the actual parameters in an

OPEN

statement with the formal parameters in a cursor declaration using positional or named notation.

If a cursor is currently open, you cannot use its name in a cursor

FOR

loop.

Examples

Given the cursor declaration

CURSOR parts_cur IS SELECT part_num, part_price FROM parts; the following statement opens the cursor:

OPEN parts_cur;

Given the cursor declaration

CURSOR emp_cur(my_ename VARCHAR2, my_comm NUMBER DEFAULT 0)

IS SELECT * FROM emp WHERE ...

any of the following statements opens the cursor:

OPEN emp_cur(’LEE’);

OPEN emp_cur(’BLAKE’, 300);

OPEN emp_cur(employee_name, 150);

Related Topics

13-132

PL/SQL User’s Guide and Reference

OPEN-FOR Statement

The

OPEN-FOR

statement executes the multi-row query associated with a cursor variable. It also allocates resources used by Oracle to process the query and identifies the result set, which consists of all rows that meet the query search criteria. The cursor variable is positioned before the first row in the result set. For more information, see

"Using Cursor Variables" on page 6-16.

Syntax open_for_statement

OPEN cursor_variable_name

: host_cursor_variable_name

FOR select_statement ;

Keyword and Parameter Description

cursor_variable_name

This identifies a cursor variable (or parameter) previously declared within the current scope.

host_cursor_variable_name

This identifies a cursor variable previously declared in a PL/SQL host environment and passed to PL/SQL as a bind variable. The datatype of the host cursor variable is compatible with the return type of any PL/SQL cursor variable. Host variables must be prefixed with a colon.

select_statement

This is a query associated with cursor_variable

, which returns a set of values.

The query can reference bind variables and PL/SQL variables, parameters, and functions. The syntax of select_statement

is similar to the syntax for select_into_statement

defined in

"SELECT INTO Statement" on page 13-166,

except that select_statement

cannot have an

INTO

clause.

PL/SQL Language Elements

13-133

OPEN-FOR Statement

Usage Notes

You can declare a cursor variable in a PL/SQL host environment such as an OCI or

Pro*C program. To open the host cursor variable, you can pass it as a bind variable to an anonymous PL/SQL block. You can reduce network traffic by grouping

OPEN-FOR

statements. For example, the following PL/SQL block opens five cursor variables in a single round-trip:

/* anonymous PL/SQL block in host environment */

BEGIN

OPEN :emp_cv FOR SELECT * FROM emp;

OPEN :dept_cv FOR SELECT * FROM dept;

OPEN :grade_cv FOR SELECT * FROM salgrade;

OPEN :pay_cv FOR SELECT * FROM payroll;

OPEN :ins_cv FOR SELECT * FROM insurance;

END;

Other

OPEN-FOR statements can open the same cursor variable for different queries.

You need not close a cursor variable before reopening it. When you reopen a cursor variable for a different query, the previous query is lost.

Unlike cursors, cursor variables do not take parameters. No flexibility is lost, however, because you can pass whole queries (not just parameters) to a cursor variable.

You can pass a cursor variable to PL/SQL by calling a stored procedure that declares a cursor variable as one of its formal parameters. However, remote subprograms on another server cannot accept the values of cursor variables.

Therefore, you cannot use a remote procedure call (RPC) to open a cursor variable.

When you declare a cursor variable as the formal parameter of a subprogram that opens the cursor variable, you must specify the

IN OUT

mode. That way, the subprogram can pass an open cursor back to the caller.

Examples

To centralize data retrieval, you can group type-compatible queries in a stored procedure. When called, the following packaged procedure opens the cursor variable emp_cv

for the chosen query:

CREATE PACKAGE emp_data AS

TYPE EmpCurTyp IS REF CURSOR RETURN emp%ROWTYPE;

PROCEDURE open_emp_cv (emp_cv IN OUT EmpCurTyp, choice IN INT);

END emp_data;

13-134

PL/SQL User’s Guide and Reference

OPEN-FOR Statement

CREATE PACKAGE BODY emp_data AS

PROCEDURE open_emp_cv (emp_cv IN OUT EmpCurTyp, choice IN INT) IS

BEGIN

IF choice = 1 THEN

OPEN emp_cv FOR SELECT * FROM emp WHERE comm IS NOT NULL;

ELSIF choice = 2 THEN

OPEN emp_cv FOR SELECT * FROM emp WHERE sal > 2500;

ELSIF choice = 3 THEN

OPEN emp_cv FOR SELECT * FROM emp WHERE deptno = 20;

END IF;

END;

END emp_data;

For more flexibility, you can pass a cursor variable and a selector to a stored procedure that executes queries with different return types. Here is an example:

CREATE PACKAGE admin_data AS

TYPE GenCurTyp IS REF CURSOR;

PROCEDURE open_cv (generic_cv IN OUT GenCurTyp, choice INT);

END admin_data;

CREATE PACKAGE BODY admin_data AS

PROCEDURE open_cv (generic_cv IN OUT GenCurTyp, choice INT) IS

BEGIN

IF choice = 1 THEN

OPEN generic_cv FOR SELECT * FROM emp;

ELSIF choice = 2 THEN

OPEN generic_cv FOR SELECT * FROM dept;

ELSIF choice = 3 THEN

OPEN generic_cv FOR SELECT * FROM salgrade;

END IF;

END;

END admin_data;

Related Topics

PL/SQL Language Elements

13-135

OPEN-FOR-USING Statement

The

OPEN-FOR-USING

statement associates a cursor variable with a multi-row query, executes the query, identifies the result set, positions the cursor before the first row in the result set, then zeroes the rows-processed count kept by

%ROWCOUNT

. For more information, see

"Using the OPEN-FOR, FETCH, and CLOSE

Statements" on page 11-7.

Syntax open_for_using_statement

OPEN

: cursor_variable_name host_cursor_variable_name

USING

, bind_argument

;

FOR dynamic_string

Keyword and Parameter Description

cursor_variable_name

This identifies a weakly typed cursor variable (one without a return type) previously declared within the current scope.

bind_argument

This is an expression whose value is passed to the dynamic

SELECT

statement.

dynamic_string

This is a string literal, variable, or expression that represents a multi-row

SELECT statement.

host_cursor_variable_name

This identifies a cursor variable declared in a PL/SQL host environment and passed to PL/SQL as a bind variable. The datatype of the host cursor variable is compatible

13-136

PL/SQL User’s Guide and Reference

OPEN-FOR-USING Statement with the return type of any PL/SQL cursor variable. Host variables must be prefixed with a colon.

USING ...

This optional clause specifies a list of bind arguments. At run time, bind arguments in the

USING

clause replace corresponding placeholders in the dynamic

SELECT statement.

Usage Notes

You use three statements to process a dynamic multi-row query:

OPEN-FOR-USING

FETCH

, and

. First, you

OPEN

a cursor variable

FOR

a multi-row query. Then, you

FETCH

rows from the result set. When all the rows are processed, you

the cursor variable.

The dynamic string can contain any multi-row

SELECT

statement (without the terminator). The string can also contain placeholders for bind arguments. However, you cannot use bind arguments to pass the names of schema objects to a dynamic

SQL statement.

Every placeholder in the dynamic string must be associated with a bind argument in the

USING

clause. Numeric, character, and string literals are allowed in the

USING clause, but Boolean literals (

TRUE

FALSE

NULL

) are not. To pass nulls to the dynamic string, you must use a workaround. See

"Passing Nulls" on page 11-16.

Dynamic SQL supports all the SQL datatypes. For example, bind arguments can be collections,

LOB s, instances of an object type, and refs. As a rule, dynamic SQL does not support PL/SQL-specific types. For instance, bind arguments cannot be

Booleans or index-by tables.

PL/SQL Language Elements

13-137

OPEN-FOR-USING Statement

Example

In the following example, we declare a cursor variable, then associate it with a dynamic

SELECT

statement that returns rows from the emp

table:

DECLARE

TYPE EmpCurTyp IS REF CURSOR; -- define weak REF CURSOR type

emp_cv EmpCurTyp; -- declare cursor variable

my_ename VARCHAR2(15);

my_sal NUMBER := 1000;

BEGIN

OPEN emp_cv FOR -- open cursor variable

’SELECT ename, sal FROM emp WHERE sal > :s’ USING my_sal;

...

END;

Related Topics

EXECUTE IMMEDIATE Statement

13-138

PL/SQL User’s Guide and Reference

Packages

Syntax

A package is a schema object that groups logically related PL/SQL types, items, and subprograms. Packages have two parts: a specification (spec for short) and a body.

For more information, see

Chapter 9

package_declaration | package_spec

OR REPLACE

CREATE

AUTHID

CURRENT_USER

DEFINER

PACKAGE

AS collection_type_definition record_type_definition subtype_definition collection_declaration constant_declaration exception_declaration object_declaration record_declaration variable_declaration cursor_spec function_spec procedure_spec call spec pragma_restrict_refs

END schema_name package_name

package_name

PRAGMA SERIALLY_REUSABLE

;

PL/SQL Language Elements

13-139

Packages

package_body

CREATE

OR REPLACE

PACKAGE BODY

PRAGMA SERIALLY_REUSABLE ;

AS schema_name .

package_name collection_type_definition record_type_definition subtype_definition collection_declaration constant_declaration exception_declaration object_declaration record_declaration variable_declaration cursor_body function_body procedure_body call spec

BEGIN statement

END package_name

Keyword and Parameter Description

AUTHID

This determines whether all the packaged subprograms execute with the privileges of their definer (the default) or invoker, and whether their unqualified references to schema objects are resolved in the schema of the definer or invoker. For more information, see

"Invoker Rights Versus Definer Rights" on page 8-49.

;

13-140

PL/SQL User’s Guide and Reference

Packages

call_spec

This publishes a Java method or external C function in the Oracle data dictionary. It publishes the routine by mapping its name, parameter types, and return type to their SQL counterparts. For more information, see Oracle9i Java Stored Procedures

Developer’s Guide and/or Oracle9i Application Developer’s Guide - Fundamentals.

collection_declaration

This declares a collection (nested table, index-by table, or varray). For the syntax of collection_declaration

, see

"Collections" on page 13-29.

collection_type_definition

This defines a collection type using the datatype specifier

TABLE

VARRAY

constant_declaration

This declares a constant. For the syntax of constant_declaration

, see

cursor_body

This defines the underlying implementation of an explicit cursor. For the syntax of cursor_body

, see

"Cursors" on page 13-54.

cursor_spec

This declares the interface to an explicit cursor. For the syntax of cursor_spec

, see

"Cursors" on page 13-54.

exception_declaration

This declares an exception. For the syntax of exception_declaration

, see

function_body

This defines the underlying implementation of a function. For the syntax of function_body

, see

function_spec

This declares the interface to a function. For the syntax of function_spec

, see

"Object Types" on page 13-122.

PL/SQL Language Elements

13-141

Packages

object_declaration

This declares an object (instance of an object type). For the syntax of object_declaration

, see

package_name

This identifies a package stored in the database. For naming conventions, see

"Identifiers" on page 2-4.

pragma_restrict_refs

This is pragma

RESTRICT_REFERENCES

, which lets you check for violations of

"purity" rules. To be callable from SQL statements, a function must obey those rules, which are meant to control side effects. If any SQL statement inside the function body violates a rule, you get an error at run time (when the statement is parsed).

For the syntax of the pragma, see

"RESTRICT_REFERENCES Pragma" on page 13-156.

The pragma asserts that a function does not read and/or write database tables and/or package variables. For more information about the purity rules and pragma

RESTRICT_REFERENCES

, see Oracle9i Application Developer’s Guide - Fundamentals.

PRAGMA SERIALLY_REUSABLE

This pragma lets you mark a package as serially reusable. You can so mark a package if its state is needed only for the duration of one call to the server (for example, an

OCI call to the server or a server-to-server RPC). For more information, see Oracle9i

Application Developer’s Guide - Fundamentals.

procedure_body

This defines the underlying implementation of a procedure. For the syntax of procedure_body

, see

procedure_spec

This declares the interface to a procedure. For the syntax of procedure_spec

, see

"Records" on page 13-152.

record_declaration

This declares a user-defined record. For the syntax of record_declaration

, see

13-142

PL/SQL User’s Guide and Reference

Packages

record_type_definition

This defines a record type using the datatype specifier

RECORD

or the attribute

%ROWTYPE

schema_name

This qualifier identifies the schema containing the package. If you omit schema_name

, Oracle assumes the package is in your schema.

variable_declaration

This declares a variable. For the syntax of variable_declaration

, see

PL/SQL Procedures" on page 8-3.

Usage Notes

You cannot define packages in a PL/SQL block or subprogram. However, you can use any Oracle tool that supports PL/SQL to create and store packages in an Oracle database. You can issue the

CREATE PACKAGE

and

CREATE PACKAGE BODY statements from an Oracle Precompiler or OCI host program, or interactively from

SQL*Plus.

Most packages have a spec and a body. The spec is the interface to your applications; it declares the types, variables, constants, exceptions, cursors, and subprograms available for use. The body fully defines cursors and subprograms, and so implements the spec.

Only subprograms and cursors have an underlying implementation (definition). So, if a spec declares only types, constants, variables, exceptions, and call specs, the package body is unnecessary. However, the body can still be used to initialize items declared in the spec, as the following example shows:

CREATE PACKAGE emp_actions AS

...

number_hired INTEGER;

END emp_actions;

CREATE PACKAGE BODY emp_actions AS

BEGIN

number_hired := 0;

END emp_actions;

PL/SQL Language Elements

13-143

Packages

You can code and compile a spec without its body. Once the spec has been compiled, stored subprograms that reference the package can be compiled as well.

You need not define the package bodies fully until you are ready to complete the application. Furthermore, you can debug, enhance, or replace a package body without changing the interface (package spec) to the package body. So, you need not recompile calling programs.

Cursors and subprograms declared in a package spec must be defined in the package body. Other program items declared in the package spec cannot be redeclared in the package body.

Related Topics

13-144

PL/SQL User’s Guide and Reference

Procedures

A procedure is a subprogram that can take parameters and be invoked. Generally, you use a procedure to perform an action. A procedure has two parts: the specification and the body. The specification (spec for short) begins with the keyword

PROCEDURE

and ends with the procedure name or a parameter list.

Parameter declarations are optional. Procedures that take no parameters are written without parentheses. The procedure body begins with the keyword

(or

) and ends with the keyword

END

followed by an optional procedure name.

The procedure 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 procedure. The executable part contains statements that assign values, control execution, and manipulate

Oracle data. The exception-handling part contains handlers that deal with exceptions raised during execution. For more information, see

"Understanding

Syntax procedure_spec

PROCEDURE procedure_name

(

, parameter_declaration )

;

procedure_declaration | procedure body

OR REPLACE

CREATE

(

, parameter_declaration )

PROCEDURE procedure_name

AUTHID

CURRENT_USER

DEFINER

PL/SQL Language Elements

13-145

Procedures

PRAGMA AUTONOMOUS_TRANSACTION ; type_definition item_declaration

EXCEPTION exception_handler function_declaration procedure_declaration

END procedure_name

BEGIN statement

;

parameter_declaration

OUT

IN OUT parameter_name

DEFAULT expression

NOCOPY datatype

Keyword and Parameter Description

AUTHID

This clause determines whether a stored procedure 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

CURRENT_USER

. For more information, see

"Invoker Rights Versus Definer Rights" on page 8-49.

CREATE

The optional

CREATE clause lets you create standalone procedures, 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.

13-146

PL/SQL User’s Guide and Reference

Procedures

datatype

This is a type specifier. For the syntax of datatype

, see

exception_handler

This associates an exception with a sequence of statements, which is executed when that exception is raised. For the syntax of exception_handler

, see

expression

This is 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_declaration

This declares a function. For the syntax of function_declaration

, see

IN, OUT, IN OUT

These parameter modes define the behavior of formal parameters. An

IN parameter lets you pass values to the subprogram being called. An

OUT

parameter lets you return values to the caller of the subprogram. An

IN OUT

parameter lets you pass initial values to the subprogram being called and return updated values to the caller.

item_declaration

This declares a program object. For the syntax of item_declaration

, see

"Passing Large Data Structures with the NOCOPY Compiler Hint" on page 8-17.

NOCOPY

This is a compiler hint (not directive), which allows the PL/SQL compiler to pass

OUT and

IN OUT parameters by reference instead of by value (the default). For more information, see

PL/SQL Language Elements

13-147

Procedures

parameter_name

This identifies a formal parameter, which is a variable declared in a procedure spec and referenced in the procedure body.

PRAGMA AUTONOMOUS_TRANSACTION

This pragma instructs the PL/SQL compiler to mark a function as autonomous

"Doing

Independent Units of Work with Autonomous Transactions" on page 6-53.

procedure_name

This identifies a user-defined procedure.

type_definition

This specifies a user-defined datatype. For the syntax of type_definition

, see

"Using Default Values for Subprogram

:= | DEFAULT

This operator or keyword lets you initialize

parameters to default values.

Usage Notes

A procedure is called as a PL/SQL statement. For example, the procedure raise_salary

might be called as follows: raise_salary(emp_num, amount);

Inside a procedure, an

parameter acts like a constant. So, you cannot assign it a value. An

OUT

parameter acts like a local variable. So, you can change its value and reference the value in any way. An

IN OUT

parameter acts like an initialized variable. So, you can assign it a value, which can be assigned to another variable.

For summary information about the parameter modes, see

Table 8–1 on page 8-16.

Unlike

OUT

and

IN OUT

parameters,

parameters can be initialized to default values. For more information, see

Parameters" on page 8-19.

Before exiting a procedure, explicitly assign values to all

OUT formal parameters. An

OUT

actual parameter can have a value before the subprogram is called. However,

13-148

PL/SQL User’s Guide and Reference

Procedures when you call the subprogram, the value is lost unless you specify the compiler hint

NOCOPY

or the subprogram exits with an unhandled exception.

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

At least one statement must appear in the executable part of a procedure. The

NULL statement meets this requirement.

Examples

The following procedure debits a bank account:

PROCEDURE debit_account (acct_id INTEGER, amount REAL) IS

old_balance REAL;

new_balance REAL;

overdrawn EXCEPTION;

BEGIN

SELECT bal INTO old_balance FROM accts WHERE acctno = acct_id;

new_balance := old_balance - amount;

IF new_balance < 0 THEN

RAISE overdrawn;

ELSE

UPDATE accts SET bal = new_balance WHERE acctno = acct_id;

END IF;

EXCEPTION

WHEN overdrawn THEN

...

END debit_account;

In the following example, you call the procedure using named notation: debit_account(amount => 500, acct_id => 10261);

Related Topics

Collection Methods ,

PL/SQL Exceptions" on page 7-7.

Packages

PL/SQL Language Elements

13-149

RAISE Statement

The

RAISE

statement stops normal execution of a PL/SQL block or subprogram and transfers control to the appropriate exception handler. Normally, predefined exceptions are raised implicitly by the runtime system. However,

RAISE statements can also raise predefined exceptions. User-defined exceptions must be raised explicitly by

RAISE

statements. For more information, see

"Defining Your Own

Syntax raise_statement

exception_name

RAISE ;

Keyword and Parameter Description

exception_name

This identifies a predefined or user-defined exception. For a list of the predefined exceptions, see

"Predefined PL/SQL Exceptions" on page 7-4.

Usage Notes

PL/SQL blocks and subprograms should

RAISE

an exception only when an error makes it undesirable or impossible to continue processing. You can code a

RAISE statement for a given exception anywhere within the scope of that exception.

When an exception is raised, if PL/SQL cannot find a handler for it in the current block, the exception propagates. That is, the exception reproduces itself in successive enclosing blocks until a handler is found or there are no more blocks to search. In the latter case, PL/SQL returns an unhandled exception error to the host environment.

Omitting the exception name in a

RAISE

statement, which is allowed only in an exception handler, reraises the current exception. When a parameterless

RAISE statement executes in an exception handler, the first block searched is the enclosing block, not the current block.

13-150

PL/SQL User’s Guide and Reference

RAISE Statement

Example

In the following example, you raise an exception when an inventoried part is out of stock:

IF quantity_on_hand = 0 THEN

RAISE out_of_stock;

END IF;

Related Topics

"What Is a Record?" on page 5-51.

PL/SQL Language Elements

13-151

Records

Records are items of type

RECORD

. Records have uniquely named fields that can store data values of different types. Thus, a record lets you treat related but dissimilar data as a logical unit. For more information, see

Syntax record_type_definition

TYPE type_name IS RECORD (

, field_declaration ) ;

field_declaration

field_name datatype

NOT NULL

DEFAULT expression

record_declaration

record_name type_name ;

Keyword and Parameter Description

datatype

This is a datatype specifier. For the syntax of datatype

, see

"Constants and

Variables" on page 13-39.

expression

This is an arbitrarily complex combination of variables, constants, literals, operators, and function calls. The simplest expression consists of a single variable.

For the syntax of expression

, see

"Expressions" on page 13-73. When the

declaration is elaborated, the value of expression

is assigned to the field. The value and the field must have compatible datatypes.

13-152

PL/SQL User’s Guide and Reference

Records

field_name

This identifies a field in a user-defined record.

NOT NULL

This constraint prevents the assigning of nulls to a field. At run time, trying to assign a null to a field defined as

NOT NULL

raises the predefined exception

VALUE_ERROR

. The constraint

NOT NULL

must be followed by an initialization clause.

record_name

This identifies a user-defined record.

type_name

This identifies a user-defined record type that was defined using the datatype specifier

RECORD

:= | DEFAULT

This operator or keyword lets you initialize fields to default values.

Usage Notes

You can define

RECORD

types and declare user-defined records in the declarative part of any block, subprogram, or package. Also, a record can be initialized in its declaration, as the following example shows:

DECLARE

TYPE TimeTyp IS RECORD(

seconds SMALLINT := 0,

minutes SMALLINT := 0,

hours SMALLINT := 0);

The next example shows that you can use the

%TYPE

attribute to specify the datatype of a field. It also shows that you can add the

NOT NULL

constraint to any field declaration and thereby prevent the assigning of nulls to that field. Fields declared as

NOT NULL

must be initialized.

DECLARE

TYPE DeptRecTyp IS RECORD(

deptno NUMBER(2) NOT NULL := 99,

dname dept.dname%TYPE,

loc dept.loc%TYPE);

dept_rec DeptRecTyp;

PL/SQL Language Elements

13-153

Records

To reference individual fields in a record, you use dot notation. For example, you might assign a value to the field dname

in the record dept_rec

as follows: dept_rec.dname := ’PURCHASING’;

Instead of assigning values separately to each field in a record, you can assign values to all fields at once. This can be done in two ways. First, you can assign one user-defined record to another if they have the same datatype. (Having fields that match exactly is not enough.) You can assign a

%ROWTYPE

record to a user-defined record if their fields match in number and order, and corresponding fields have compatible datatypes.

Second, you can use the

SELECT

FETCH

statement to fetch column values into a record. The columns in the select-list must appear in the same order as the fields in your record.

You can declare and reference nested records. That is, a record can be the component of another record, as the following example shows:

DECLARE

TYPE TimeTyp IS RECORD(

minutes SMALLINT,

hours SMALLINT);

TYPE MeetingTyp IS RECORD(

day DATE,

time_of TimeTyp, -- nested record

place VARCHAR2(20),

purpose VARCHAR2(50));

TYPE PartyTyp IS RECORD(

day DATE,

time_of TimeTyp, -- nested record

place VARCHAR2(15));

meeting MeetingTyp;

seminar MeetingTyp;

party PartyTyp;

The next example shows that you can assign one nested record to another if they have the same datatype: seminar.time_of := meeting.time_of;

Such assignments are allowed even if the containing records have different datatypes.

13-154

PL/SQL User’s Guide and Reference

Records

User-defined records follow the usual scoping and instantiation rules. In a package, they are instantiated when you first reference the package and cease to exist when you end the database session. In a block or subprogram, they are instantiated when you enter the block or subprogram and cease to exist when you exit the block or subprogram.

Like scalar variables, user-defined records can be declared as the formal parameters of procedures and functions. The restrictions that apply to scalar parameters also apply to user-defined records.

You can specify a

RECORD type in the

RETURN clause of a function spec. That allows the function to return a user-defined record of the same type. When calling a function that returns a user-defined record, use the following syntax to reference fields in the record: function_name(parameter_list).field_name

To reference nested fields, use this syntax: function_name(parameter_list).field_name.nested_field_name

If the function takes no parameters, code an empty parameter list. The syntax follows: function_name().field_name

Example

In the following example, you define a

RECORD type named

DeptRecTyp

, declare a record named dept_rec

, then select a row of values into the record:

DECLARE

TYPE DeptRecTyp IS RECORD(

deptno NUMBER(2),

dname VARCHAR2(14),

loc VARCHAR2(13));

dept_rec DeptRecTyp;

...

BEGIN

SELECT deptno, dname, loc INTO dept_rec FROM dept

WHERE deptno = 20;

Related Topics

PL/SQL Language Elements

13-155

RESTRICT_REFERENCES Pragma

To be callable from SQL statements, a stored function must obey certain "purity" rules, which are meant to control side effects. (See

"Controlling Side Effects of

PL/SQL Subprograms" on page 8-9.) 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, you can use the pragma (compiler directive)

RESTRICT_REFERENCES

. The pragma asserts that a function does not read and/or write database tables and/or package variables. For more information, see Oracle9i

Application Developer’s Guide - Fundamentals.

Syntax pragma_restrict_refs

PRAGMA RESTRICT_REFERENCES ( function_name

DEFAULT

RNDS

WNDS

RNPS

WNPS

TRUST

) ;

Keyword and Parameter Description

DEFAULT

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

function_name

This identifies a user-defined function.

PRAGMA

13-156

PL/SQL User’s Guide and Reference

RESTRICT_REFERENCES Pragma

RNDS

This asserts that the function reads no database state (does not query database tables).

RNPS

This asserts that the function reads no package state (does not reference the values of packaged variables)

TRUST

This asserts that the function can be trusted not to violate one or more rules.

WNDS

This asserts that the function writes no database state (does not modify database tables).

WNPS

This asserts that the function 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 the function from parallel queries, you must specify all four constraints. No constraint implies another. For example,

WNPS

does not imply

RNPS

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.

If you specify

DEFAULT

instead of a function name, the pragma applies to all functions in the package spec or object type spec (including, in the latter case, the system-defined constructor). You can still declare the pragma for individual functions. Such pragmas override the default pragma.

RESTRICT_REFERENCES

pragma can apply to only one function declaration. So, a pragma that references the name of overloaded functions always applies to the nearest foregoing function declaration.

PL/SQL Language Elements

13-157

RESTRICT_REFERENCES Pragma

Examples

The following pragma asserts that packaged function balance

writes no database state (

WNDS

) and reads no package state (

RNPS

CREATE PACKAGE loans AS

...

FUNCTION balance RETURN NUMBER;

PRAGMA RESTRICT_REFERENCES (balance, WNDS, RNPS);

END loans;

A pragma that references the name of overloaded functions always applies to the nearest foregoing function declaration. So, in the following example, the pragma applies to the second declaration of credit_ok

CREATE PACKAGE loans AS

FUNCTION credit_ok (amount_limit NUMBER) RETURN BOOLEAN;

FUNCTION credit_ok (time_limit DATE) RETURN BOOLEAN;

PRAGMA RESTRICT_REFERENCES (credit_ok, WNDS);

...

END loans;

Related Topics

AUTONOMOUS_TRANSACTION Pragma

SERIALLY_REUSABLE Pragma

13-158

PL/SQL User’s Guide and Reference

RETURN Statement

The

RETURN

statement immediately completes the execution of a subprogram and returns control to the caller. Execution then 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-8.

Syntax return_statement

( ) expression

RETURN ;

Keyword and Parameter Description

expression

This is an arbitrarily complex 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, none of which need be the last lexical statement. Executing any of them completes the subprogram immediately. However, to have multiple exit points in a subprogram is a poor programming practice.

In procedures, a

RETURN

statement cannot contain an expression. The statement simply returns control to the caller before the normal end of the procedure is reached.

PL/SQL Language Elements

13-159

RETURN Statement

However, 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. Therefore, 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 also be used in an anonymous block to exit the block

(and all enclosing blocks) immediately, but the

RETURN statement cannot contain an expression.

Example

In the following example, the function balance

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

"Overview of Transaction Processing in PL/SQL" on page 6-43.

13-160

PL/SQL User’s Guide and Reference

ROLLBACK Statement

The

ROLLBACK statement is the inverse of the

COMMIT statement. It undoes some or all database changes made during the current transaction. For more information, see

Syntax rollback_statement

SAVEPOINT

WORK TO savepoint_name

ROLLBACK ;

Keyword and Parameter Description

ROLLBACK

When a parameterless

ROLLBACK

statement is executed, all database changes made during the current transaction are undone.

ROLLBACK TO

This statement undoes all database changes (and releases all locks acquired) since the savepoint identified by savepoint_name

was marked.

SAVEPOINT

This keyword is optional and has no effect except to improve readability.

savepoint_name

This is an undeclared identifier, which marks the current point in the processing of a transaction. For naming conventions, see

"Identifiers" on page 2-4.

WORK

This keyword is optional and has no effect except to improve readability.

PL/SQL Language Elements

13-161

ROLLBACK Statement

Usage Notes

All savepoints marked after the savepoint to which you roll back are erased.

However, the savepoint to which you roll back is not erased. For example, if you mark savepoints A, B, C, and D in that order, then roll back to savepoint B, only savepoints C and D are erased.

An implicit savepoint is marked before executing an

INSERT

UPDATE

, or

DELETE statement. If the statement fails, a rollback to the implicit savepoint is done.

Normally, just the failed SQL statement is rolled back, not the whole transaction.

However, if the statement raises an unhandled exception, the host environment determines what is rolled back.

In SQL, the

FORCE

clause manually rolls back an in-doubt distributed transaction.

However, PL/SQL does not support this clause. For example, the following statement is not allowed:

ROLLBACK WORK FORCE ’24.37.85’; -- not allowed

In embedded SQL, the

RELEASE

ROLLBACK WORK RELEASE; -- not allowed

Related Topics

"Using %ROWTYPE" on page 2-14.

SAVEPOINT Statement

13-162

PL/SQL User’s Guide and Reference

%ROWTYPE Attribute

The

%ROWTYPE

attribute provides a record type that represents a row in a database table. The record can store an entire row of data selected from the table or fetched from a cursor or cursor variable. Fields in a record and corresponding columns in a row have the same names and datatypes.

You can use the

%ROWTYPE

attribute in variable declarations as a datatype specifier.

Variables declared using

%ROWTYPE

are treated like those declared using a datatype name. For more information, see

Syntax rowtype_attribute

cursor_name cursor_variable_name table_name

% ROWTYPE

Keyword and Parameter Description

cursor_name

This identifies an explicit cursor previously declared within the current scope.

cursor_variable_name

This identifies a PL/SQL strongly (not weakly) typed cursor variable previously declared within the current scope.

table_name

This identifies a database table (or view) that must be accessible when the declaration is elaborated.

PL/SQL Language Elements

13-163

%ROWTYPE Attribute

Usage Notes

The

%ROWTYPE

attribute lets you declare records structured like a row of data in a database table. To reference a field in the record, you use dot notation. For example, you might reference the deptno

field as follows:

IF emp_rec.deptno = 20 THEN ...

You can assign the value of an expression to a specific field, as follows: emp_rec.sal := average * 1.15;

There are two ways to assign values to all fields in a record at once. First, PL/SQL allows aggregate assignment between entire records if their declarations refer to the same table or cursor. Second, you can assign a list of column values to a record by using the

SELECT or

FETCH statement. The column names must appear in the order in which they were declared. Select-items fetched from a cursor associated with

%ROWTYPE

must have simple names or, if they are expressions, must have aliases.

Examples

In the example below, you use

%ROWTYPE

to declare two records. The first record stores a row selected from the emp

table. The second record stores a row fetched from the c1

cursor.

DECLARE

emp_rec emp%ROWTYPE;

CURSOR c1 IS SELECT deptno, dname, loc FROM dept;

dept_rec c1%ROWTYPE;

In the next example, you select a row from the emp

table into a

%ROWTYPE

record:

DECLARE

emp_rec emp%ROWTYPE;

...

BEGIN

SELECT * INTO emp_rec FROM emp WHERE empno = my_empno;

IF (emp_rec.deptno = 20) AND (emp_rec.sal > 2000) THEN

...

END IF;

END;

Related Topics

"Overview of Transaction Processing in PL/SQL" on page 6-43.

Cursors ,

Cursor Variables ,

FETCH Statement

13-164

PL/SQL User’s Guide and Reference

SAVEPOINT Statement

The

SAVEPOINT

statement names and marks the current point in the processing of a transaction. With the

ROLLBACK TO

statement, savepoints let you undo parts of a transaction instead of the whole transaction. For more information, see

Syntax savepoint_statement

SAVEPOINT savepoint_name ;

Keyword and Parameter Description

savepoint_name

This is an undeclared identifier, which marks the current point in the processing of a transaction.

Usage Notes

When you roll back to a savepoint, any savepoints marked after that savepoint are erased. However, the savepoint to which you roll back is not erased. A simple rollback or commit erases all savepoints. Savepoint names can be reused within a transaction. This moves the savepoint from its old position to the current point in the transaction.

If you mark a savepoint within a recursive subprogram, new instances of the

SAVEPOINT

statement are executed at each level in the recursive descent. However, you can only roll back to the most recently marked savepoint.

An implicit savepoint is marked before executing an

INSERT

UPDATE

, or

DELETE statement. If the statement fails, a rollback to the implicit savepoint is done.

Normally, just the failed SQL statement is rolled back, not the whole transaction.

However, if the statement raises an unhandled exception, the host environment determines what is rolled back.

Related Topics

"Reducing Loop Overhead for

ROLLBACK Statement

PL/SQL Language Elements

13-165

SELECT INTO Statement

The

SELECT INTO

statement retrieves data from one or more database tables, then assigns the selected values to variables or fields. For a full description of the

SELECT

statement, see Oracle9i SQL Reference.

Syntax select_into_statement

DISTINCT

UNIQUE

ALL

SELECT

INTO

, variable_name record_name

BULK COLLECT INTO

FROM

, collection_name

: host_array_name

, table_reference

( subquery

TABLE (

) subquery2

)

, select_item alias rest_of_statement ;

13-166

PL/SQL User’s Guide and Reference

SELECT INTO Statement

select_item

function_name

NULL numeric_literal schema_name .

(

' schema_name .

sequence_name text

, parameter_name ) table_name view_name table_name view_name

CURRVAL

NEXTVAL column_name

AS alias

Keyword and Parameter Description

alias

This is another (usually short) name for the referenced column, table, or view.

BULK COLLECT

This clause instructs the SQL engine to bulk-bind output collections before returning them to the PL/SQL engine. The SQL engine bulk-binds all collections referenced in the

INTO list. For more information, see

Collections with Bulk Binds" on page 5-37.

collection_name

This identifies a declared collection into which select_item

values are bulk fetched. For each select_item

, there must be a corresponding, type-compatible collection in the list.

function_name

This identifies a user-defined function.

PL/SQL Language Elements

13-167

SELECT INTO Statement

host_array_name

This identifies an array (declared in a PL/SQL host environment and passed to

PL/SQL as a bind variable) into which select_item

values are bulk fetched. For each select_item

, there must be a corresponding, type-compatible array in the list. Host arrays must be prefixed with a colon.

numeric_literal

This is a literal that represents a number or a value implicitly convertible to a number.

parameter_name

This identifies a formal parameter of a user-defined function.

record_name

This identifies a user-defined or

%ROWTYPE

record into which rows of values are fetched. For each select_item

value returned by the query, there must be a corresponding, type-compatible field in the record.

rest_of_statement

This is anything that can legally follow the

FROM

clause in a

SELECT

statement except the

SAMPLE

clause.

schema_name

This qualifier identifies the schema containing the table or view. If you omit schema_name

, Oracle assumes the table or view is in your schema.

subquery

This is a

SELECT

statement that provides a set of rows for processing. Its syntax is like that of select_into_statement

without the

INTO

clause. See

table_reference

This identifies a table or view that must be accessible when you execute the

SELECT statement, and for which you must have

SELECT

privileges. For the syntax of table_reference

, see

AUTONOMOUS_TRANSACTION Pragma

13-168

PL/SQL User’s Guide and Reference

SELECT INTO Statement

TABLE (subquery2)

The operand of

TABLE

is a

SELECT

statement that returns a single column value, which must be a nested table or a varray. Operator

TABLE

informs Oracle that the value is a collection, not a scalar value.

variable_name

This identifies a previously declared variable into which a select_item

value is fetched. For each select_item

value returned by the query, there must be a corresponding, type-compatible variable in the list.

Usage Notes

The

BULK COLLECT

clause tells the SQL engine to bulk-bind output collections before returning them. It bulk-binds all collections referenced in the

INTO

list. The corresponding columns can store scalar or composite values including objects.

When you use a

SELECT INTO

statement without the

BULK COLLECT

clause, it should return only one row. If it returns more than one row, PL/SQL raises the predefined exception

TOO_MANY_ROWS

However, if no rows are returned, PL/SQL raises

NO_DATA_FOUND

unless the

SELECT

statement called a SQL aggregate function such as

AVG

SUM

. (SQL aggregate functions always return a value or a null. So, a

SELECT INTO

statement that calls an aggregate function never raises

NO_DATA_FOUND

The implicit cursor

SQL

and the cursor attributes

%NOTFOUND

%FOUND

%ROWCOUNT

, and

%ISOPEN

let you access useful information about the execution of a

SELECT INTO

statement.

PL/SQL Language Elements

13-169

SELECT INTO Statement

Examples

The following

SELECT

statement returns an employee’s name, job title, and salary from the emp

database table:

SELECT ename, job, sal INTO my_ename, my_job, my_sal FROM emp

WHERE empno = my_empno;

In the following example, the SQL engine loads the entire empno

and ename database columns into nested tables before returning the tables to the PL/SQL:

DECLARE

TYPE NumTab IS TABLE OF emp.empno%TYPE;

TYPE NameTab IS TABLE OF emp.ename%TYPE;

enums NumTab; -- no need to initialize

names NameTab;

BEGIN

SELECT empno, ename BULK COLLECT INTO enums, names FROM emp;

...

END;

Related Topics

Assignment Statement

FETCH Statement ,

%ROWTYPE Attribute

13-170

PL/SQL User’s Guide and Reference

SERIALLY_REUSABLE Pragma

The pragma

SERIALLY_REUSABLE

lets you mark a package as serially reusable. You can so mark a package if its state is needed only for the duration of one call to the server (for example, an OCI call to the server or a server-to-server RPC). For more information, see Oracle9i Application Developer’s Guide - Fundamentals.

Syntax serially_reusable_pragma

PRAGMA SERIALLY_REUSABLE ;

Keyword and Parameter Description

PRAGMA

Usage Notes

You can mark a bodiless package as serially reusable. If a package has a spec and body, you must mark both. You cannot mark only the body.

The global memory for serially reusable packages is pooled in the System Global

Area (SGA), not allocated to individual users in the User Global Area (UGA). That way, the package work area can be reused. When the call to the server ends, the memory is returned to the pool. Each time the package is reused, its public variables are initialized to their default values or to

NULL

Serially reusable packages cannot be accessed from database triggers. If you try,

Oracle generates an error.

PL/SQL Language Elements

13-171

SERIALLY_REUSABLE Pragma

Examples

In the following example, you create a serially reusable package:

CREATE PACKAGE pkg1 IS

PRAGMA SERIALLY_REUSABLE;

num NUMBER := 0;

PROCEDURE init_pkg_state(n NUMBER);

PROCEDURE print_pkg_state;

END pkg1;

CREATE PACKAGE BODY pkg1 IS

PRAGMA SERIALLY_REUSABLE;

PROCEDURE init_pkg_state (n NUMBER) IS

BEGIN

pkg1.num := n;

END;

PROCEDURE print_pkg_state IS

BEGIN

dbms_output.put_line(’Num: ’ || pkg1.num);

END;

END pkg1;

Related Topics

RESTRICT_REFERENCES Pragma

13-172

PL/SQL User’s Guide and Reference

SET TRANSACTION Statement

The

SET TRANSACTION

statement begins a read-only or read-write transaction, establishes an isolation level, or assigns the current transaction to a specified rollback segment. Read-only transactions are useful for running multiple queries against one or more tables while other users update the same tables. For more information, see

"Setting Transaction Properties with SET TRANSACTION" on page 6-48.

Syntax

SET TRANSACTION

READ ONLY

READ WRITE

ISOLATION

USE

LEVEL

ROLLBACK

SERIALIZABLE

READ COMMITTED

SEGMENT rollback_segment

NAME ’text’

;

Keyword and Parameter Description

READ ONLY

This clause establishes the current transaction as read-only. If a transaction is set to

READ ONLY

, subsequent queries see only changes committed before the transaction began. The use of

READ ONLY

does not affect other users or transactions.

READ WRITE

This clause establishes the current transaction as read-write. The use of

READ WRITE does not affect other users or transactions. If the transaction executes a data manipulation statement, Oracle assigns the transaction to a rollback segment.

ISOLATION LEVEL

This clause specifies how transactions that modify the database are handled. When you specify

SERIALIZABLE

, if a serializable transaction tries to execute a SQL data manipulation statement that modifies any table already modified by an uncommitted transaction, the statement fails.

PL/SQL Language Elements

13-173

SET TRANSACTION Statement

To enable

SERIALIZABLE

mode, your DBA must set the Oracle initialization parameter

COMPATIBLE

to 7.3.0 or higher.

When you specify

READ COMMITTED

, if a transaction includes SQL data manipulation statements that require row locks held by another transaction, the statement waits until the row locks are released.

USE ROLLBACK SEGMENT

This clause assigns the current transaction to the specified rollback segment and establishes the transaction as read-write. You cannot use this parameter with the

READ ONLY

parameter in the same transaction because read-only transactions do not generate rollback information.

NAME

Lets you specify a name or some comment text for the transaction. This is better than using the

COMMIT COMMENT

feature because the name is available while the transaction is running, making it easier to monitor long-running and in-doubt transactions.

Usage Notes

The

SET TRANSACTION

statement must be the first SQL statement in your transaction and can appear only once in the transaction.

Example

In the following example, you establish a read-only transaction:

COMMIT; -- end previous transaction

SET TRANSACTION READ ONLY;

SELECT ... FROM emp WHERE ...

SELECT ... FROM dept WHERE ...

SELECT ... FROM emp WHERE ...

COMMIT; -- end read-only transaction

Related Topics

ROLLBACK Statement ,

SAVEPOINT Statement

13-174

PL/SQL User’s Guide and Reference

SQL Cursor

Oracle implicitly opens a cursor to process each SQL statement not associated with an explicit cursor. PL/SQL lets you refer to the most recent implicit cursor as the

SQL cursor, which always has these attributes:

%FOUND

%ISOPEN

%NOTFOUND

, and

%ROWCOUNT

. They give you useful information about the execution of data manipulation statements. The

SQL

cursor has additional attributes,

%BULK_ROWCOUNT

and

%BULK_EXCEPTIONS

, designed for use with the

FORALL statement. For more information, see

Error Code and Error Message: SQLCODE and SQLERRM" on page 7-18.

Syntax sql_cursor

SQL %

FOUND

ISOPEN

NOTFOUND

ROWCOUNT

BULK_ROWCOUNT ( index )

Keyword and Parameter Description

%BULK_ROWCOUNT

This is a composite attribute designed for use with the

FORALL

statement. This attribute has the semantics of an index-by table. Its ith element stores the number of rows processed by the ith execution of an

UPDATE

DELETE

statement. If the ith execution affects no rows,

%BULK_ROWCOUNT(i)

returns zero.

%BULK_EXCEPTIONS

%FOUND

This attribute yields

TRUE if an

INSERT

UPDATE

, or

DELETE statement affected one or more rows or a

SELECT INTO

statement returned one or more rows. Otherwise, it yields

FALSE

PL/SQL Language Elements

13-175

SQL Cursor

%ISOPEN

This attribute always yields

FALSE

because Oracle closes the

SQL

cursor automatically after executing its associated SQL statement.

%NOTFOUND

This attribute is the logical opposite of

%FOUND

. It yields

TRUE

if an

INSERT

UPDATE

, or

DELETE

statement affected no rows, or a

SELECT INTO

statement returned no rows. Otherwise, it yields

FALSE

%ROWCOUNT

This attribute yields the number of rows affected by an

INSERT

UPDATE

, or

DELETE

statement, or returned by a

SELECT INTO

statement.

SQL

This is the name of the Oracle implicit cursor.

Usage Notes

You can use cursor attributes in procedural statements but not in SQL statements.

Before Oracle opens the

SQL

cursor automatically, the implicit cursor attributes yield

NULL

The values of cursor attributes always refer to the most recently executed SQL statement, wherever that statement appears. It might be in a different scope. So, if you want to save an attribute value for later use, assign it to a Boolean variable immediately.

If a

SELECT INTO

statement fails to return a row, PL/SQL raises the predefined exception

NO_DATA_FOUND

whether you check

SQL%NOTFOUND

on the next line or not. However, a

SELECT INTO

statement that calls a SQL aggregate function never raises

NO_DATA_FOUND

because those functions always return a value or a null. In such cases,

SQL%NOTFOUND

yields

FALSE

%BULK_ROWCOUNT

is not maintained for bulk inserts because that would be redundant. For example, the

FORALL

statement below inserts one row per iteration.

So, after each iteration,

%BULK_ROWCOUNT

would return 1:

FORALL i IN 1..15

INSERT INTO emp (sal) VALUES (sals(i));

13-176

PL/SQL User’s Guide and Reference

SQL Cursor

You can use the scalar attributes

%FOUND

%NOTFOUND

, and

%ROWCOUNT

with bulk binds. For example,

%ROWCOUNT

returns the total number of rows processed by all executions of the SQL statement.

%FOUND

and

%NOTFOUND

refer only to the last execution of the SQL statement.

However, you can use

%BULK_ROWCOUNT

to infer their values for individual executions. For example, when

%BULK_ROWCOUNT(i)

is zero,

%FOUND

and

%NOTFOUND

are

FALSE

and

TRUE

, respectively.

Examples

In the following example,

%NOTFOUND is used to insert a row if an update affects no rows:

UPDATE emp SET sal = sal * 1.05 WHERE empno = my_empno;

IF SQL%NOTFOUND THEN

INSERT INTO emp VALUES (my_empno, my_ename, ...);

END IF;

In the next example, you use

%ROWCOUNT

to raise an exception if more than 100 rows are deleted:

DELETE FROM parts WHERE status = ’OBSOLETE’;

IF SQL%ROWCOUNT > 100 THEN -- more than 100 rows were deleted

RAISE large_deletion;

END IF;

Here is an example that uses

%BULK_ROWCOUNT

DECLARE

TYPE NumList IS TABLE OF NUMBER;

depts NumList := NumList(10, 20, 50);

BEGIN

FORALL j IN depts.FIRST..depts.LAST

UPDATE emp SET sal = sal * 1.10 WHERE deptno = depts(j);

IF SQL%BULK_ROWCOUNT(3) = 0 THEN

...

END;

Related Topics

Cursors ,

Cursor Attributes

PL/SQL Language Elements

13-177

SQLCODE Function

The function

SQLCODE

returns the number code associated with the most recently raised exception.

SQLCODE

is meaningful only in an exception handler. Outside a handler,

SQLCODE

always returns

For internal exceptions,

SQLCODE returns the number of the associated Oracle error.

The number that

SQLCODE

returns is negative unless the Oracle error is no data

found, in which case

SQLCODE

returns

+100

For user-defined exceptions,

SQLCODE

returns

unless you used the pragma

EXCEPTION_INIT to associate the exception with an Oracle error number, in which case

SQLCODE

returns that error number. For more information, see

"Retrieving the

Syntax sqlcode_function

SQLCODE

Usage Notes

SQLCODE

is especially useful in the

OTHERS

exception handler because it lets you identify which internal exception was raised.

You cannot use

SQLCODE

directly in a SQL statement. First, you must assign the value of

SQLCODE

to a local variable, as follows: my_sqlcode := SQLCODE;

...

INSERT INTO errors VALUES (my_sqlcode, ...);

When using pragma

RESTRICT_REFERENCES

to assert the purity of a stored function, you cannot specify the constraints

WNPS

and

RNPS

if the function calls

SQLCODE

13-178

PL/SQL User’s Guide and Reference

SQLCODE Function

Example

In the following example, you insert the value of

SQLCODE

into an audit table:

DECLARE

my_sqlcode NUMBER;

BEGIN

...

EXCEPTION

WHEN OTHERS THEN

my_sqlcode := SQLCODE;

INSERT INTO audits VALUES (my_sqlcode, ...);

END;

Related Topics

"Retrieving the Error Code and Error Message:

SQLERRM Function

PL/SQL Language Elements

13-179

SQLERRM Function

The function

SQLERRM

returns the error message associated with its error-number argument or, if the argument is omitted, with the current value of

SQLCODE

SQLERRM

with no argument is meaningful only in an exception handler. Outside a handler,

SQLERRM

with no argument always returns the message normal, successful

completion.

For internal exceptions,

SQLERRM

returns the message associated with the Oracle error that occurred. The message begins with the Oracle error code.

For user-defined exceptions,

SQLERRM

returns the message user-defined exception unless you used the pragma

EXCEPTION_INIT

to associate the exception with an

Oracle error number, in which case

SQLERRM

returns the corresponding error message. For more information, see

SQLCODE and SQLERRM" on page 7-18.

Syntax sqlerrm_function

SQLERRM

( error_number )

Keyword and Parameter Description

error_number

This must be a valid Oracle error number. For a list of Oracle errors, see Oracle9i

Database Error Messages.

Usage Notes

SQLERRM

is especially useful in the

OTHERS

exception handler because it lets you identify which internal exception was raised.

You can pass an error number to

SQLERRM

, in which case

SQLERRM

returns the message associated with that error number. The error number passed to

SQLERRM should be negative. Passing a zero to

SQLERRM

always returns the following message:

ORA-0000: normal, successful completion

13-180

PL/SQL User’s Guide and Reference

SQLERRM Function

Passing a positive number to

SQLERRM

always returns the message

User-Defined Exception unless you pass

+100

, in which case

SQLERRM

returns the following message:

ORA-01403: no data found

You cannot use

SQLERRM

directly in a SQL statement. First, you must assign the value of

SQLERRM

to a local variable, as follows: my_sqlerrm := SQLERRM;

...

INSERT INTO errors VALUES (my_sqlerrm, ...);

When using pragma

RESTRICT_REFERENCES

to assert the purity of a stored function, you cannot specify the constraints

WNPS

and

RNPS

if the function calls

SQLERRM

Example

In the following example, the string function

SUBSTR

ensures that a

VALUE_ERROR exception (for truncation) is not raised when you assign the value of

SQLERRM

to my_sqlerrm

DECLARE

my_sqlerrm VARCHAR2(150);

...

BEGIN

...

EXCEPTION

...

WHEN OTHERS THEN

my_sqlerrm := SUBSTR(SQLERRM, 1, 150);

INSERT INTO audits VALUES (my_sqlerrm, ...);

END;

Related Topics

"Using %TYPE" on page 2-13.

SQLCODE Function

PL/SQL Language Elements

13-181

%TYPE Attribute

The

%TYPE

attribute provides the datatype of a field, record, nested table, database column, or variable. You can use the

%TYPE

attribute as a datatype specifier when declaring constants, variables, fields, and parameters. For more information, see

Syntax type_attribute

collection_name cursor_variable_name object_name

field_name record_name db_table_name .

column_name variable_name

% TYPE

Keyword and Parameter Description

collection_name

This identifies a nested table, index-by table, or varray previously declared within the current scope.

cursor_variable_name

This identifies a PL/SQL cursor variable previously declared within the current scope. Only the value of another cursor variable can be assigned to a cursor variable.

db_table_name.column_name

This refers to a table and column that must be accessible when the declaration is elaborated.

13-182

PL/SQL User’s Guide and Reference

%TYPE Attribute

object_name

This identifies an object (instance of an object type) previously declared within the current scope.

record_name

This identifies a user-defined or

%ROWTYPE

record previously declared within the current scope.

record_name.field_name

This identifies a field in a user-defined or

%ROWTYPE

record previously declared within the current scope.

variable_name

This identifies a variable previously declared in the same scope.

Usage Notes

The

%TYPE

attribute is particularly useful when declaring variables, fields, and parameters that refer to database columns. However, the

NOT NULL

column constraint is not inherited by items declared using

%TYPE

Related Topics

%ROWTYPE Attribute

PL/SQL Language Elements

13-183

UPDATE Statement

The

UPDATE statement changes the values of specified columns in one or more rows in a table or view. For a full description of the

UPDATE

statement, see Oracle9i SQL

Reference.

Syntax update_statement

UPDATE table_reference

( subquery

TABLE (

) subquery2

)

, , column_name =

( (

, ,

( ( ) ) = ( alias

)

) )

; ;

Keyword and Parameter Description

alias

This is another (usually short) name for the referenced table or view and is typically used in the

WHERE

clause.

13-184

PL/SQL User’s Guide and Reference

UPDATE Statement

column_name

This is the name of the column (or one of the columns) to be updated. It must be the name of a column in the referenced table or view. A column name cannot be repeated in the column_name

list. Column names need not appear in the

UPDATE statement in the same order that they appear in the table or view.

returning_clause

This clause lets you return values from updated rows, thereby eliminating the need to

SELECT

the rows afterward. You can retrieve the column values into variables and/or host variables, or into collections and/or host arrays. However, you cannot use the

RETURNING

clause for remote or parallel updates. For the syntax of returning_clause

, see

SET column_name = sql_expression

This clause assigns the value of sql_expression

to the column identified by column_name

. If sql_expression

contains references to columns in the table being updated, the references are resolved in the context of the current row. The old column values are used on the right side of the equal sign.

In the following example, you increase every employee’s salary by 10%. The original value of the sal

column is multiplied by

1.10

, then the result is assigned to the sal

column overwriting the original value.

UPDATE emp SET sal = sal * 1.10;

SET column_name = (subquery3)

This clause assigns the value retrieved from the database by subquery3

to the column identified by column_name

. The subquery must return exactly one row and one column.

SET (column_name, column_name, ...) = (subquery4)

This clause assigns the values retrieved from the database by subquery4

to the columns in the column_name

list. The subquery must return exactly one row that includes all the columns listed.

The column values returned by the subquery are assigned to the columns in the column list in order. The first value is assigned to the first column in the list, the second value is assigned to the second column in the list, and so on.

PL/SQL Language Elements

13-185

UPDATE Statement

In the following correlated query, the column item_id

is assigned the value stored in item_num

, and the column price

is assigned the value stored in item_price

UPDATE inventory inv -- alias

SET (item_id, price) =

(SELECT item_num, item_price FROM item_table

WHERE item_name = inv.item_name);

sql_expression

This is any valid SQL expression. For more information, see Oracle9i SQL Reference.

subquery

This is a

SELECT

statement that provides a set of rows for processing. Its syntax is like that of select_into_statement

without the

INTO

clause. See

table_reference

This identifies a table or view that must be accessible when you execute the

UPDATE statement, and for which you must have

UPDATE

privileges. For the syntax of table_reference

, see