RAISE Statement

RAISE Statement

The RAISE statement stops normal execution of a PL/SQL block or subprogram and transfers control to an exception handler.

RAISE statements can raise predefined exceptions, such as ZERO_DIVIDE or NO_DATA_FOUND, or user-defined exceptions whose names you decide. For more information, see "Defining Your Own PL/SQL Exceptions" on page 10-6.

Syntax

raise_statement

exception_name

Keyword and Parameter Description

exception_name

A predefined or user-defined exception. For a list of the predefined exceptions, see "Summary of Predefined PL/SQL Exceptions" on page 10-4.

Usage Notes

PL/SQL blocks and subprograms should RAISE an exception only when an error makes it impractical 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 to successive enclosing blocks, until a handler is found or there are no more blocks to search. If no handler is found, PL/SQL returns an unhandled exception error to the host environment.

In an exception handler, you can omit the exception name in a RAISE statement, which raises the current exception again. This technique allows you to take some initial corrective action (perhaps just logging the problem), then pass control to another handler that does more extensive correction. When an exception is reraised, the first block searched is the enclosing block, not the current block.

Example

The following example raises an exception when an inventoried part is out of stock, or when a divide-by-zero situation is about to occur:

DECLARE

out_of_stock EXCEPTION; quantity_on_hand NUMBER := 0; denominator NUMBER := 0;

BEGIN

IF quantity_on_hand = 0 THEN RAISE out_of_stock;

END IF;

IF denominator = 0 THEN raise ZERO_DIVIDE;

END IF;

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

RAISE Statement

EXCEPTION

WHEN out_of_stock THEN

dbms_output.put_line('No more parts in stock.'); WHEN ZERO_DIVIDE THEN

dbms_output.put_line('Attempt to divide by zero.'); WHEN OTHERS THEN

dbms_output.put_line('Some other kind of problem...');

END;

/

Related Topics

Exceptions

PL/SQL Language Elements 13-109

Records

Records

Records are composite variables that can store data values of different types, similar to a struct type in C, C++, or Java. For more information, see "What Is a PL/SQL Record?" on page 5-32.

In PL/SQL records are useful for holding data from table rows, or certain columns from table rows. For ease of maintenance, you can declare variables as table%ROWTYPE or cursor%ROWTYPE instead of creating new record types.

Syntax

record_declaration

record_name type_name ;

Keyword and Parameter Description

datatype

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

expression

A 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-52. When the declaration is elaborated, the value of expression is assigned to the field. The value and the field must have compatible datatypes.

field_name

A field in a user-defined record.

NOT NULL

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

A user-defined record.

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

Records

type_name

A user-defined record type that was defined using the datatype specifier RECORD.

:= | DEFAULT

Initializes 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.

A record can be initialized in its declaration:

DECLARE

TYPE TimeTyp IS RECORD ( seconds SMALLINT := 0, minutes SMALLINT := 0, hours SMALLINT := 0 );

You can use the %TYPE attribute to specify the datatype of a field. You can add the NOT NULL constraint to any field declaration to prevent the assigning of nulls to that field. Fields declared as NOT NULL must be initialized.

DECLARE

TYPE DeptRecTyp IS RECORD

(

);

dept_rec DeptRecTyp; BEGIN

dept_rec.dname := 'PURCHASING'; END;

/

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:

■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.

■You can use the SELECT or 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:

PL/SQL Language Elements 13-111

Records

place VARCHAR2(20), purpose VARCHAR2(50) );

meeting MeetingTyp; seminar MeetingTyp;

BEGIN

seminar.time_of := meeting.time_of; END;

/

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.

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

The following example defines a RECORD type named DeptRecTyp, declares a record named dept_rec, then selects a row of values into the record:

DECLARE

TYPE DeptRecTyp IS RECORD (

deptno departments.department_id%TYPE,

dept_rec DeptRecTyp; BEGIN

SELECT department_id, department_name, location_id INTO dept_rec FROM departments WHERE department_id = 20;

END;

/

Related Topics

Collections, Functions, Packages, Procedures

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