Cursor Declaration

To execute a multi-row query, Oracle opens an unnamed work area that stores processing information. A cursor lets you name the work area, access the information, and process the rows individually. For more information, see "Querying Data with PL/SQL".

Syntax

cursor declaration ::=

Description of the illustration cursor_declaration.gif

cursor spec ::=

Description of the illustration cursor_spec.gif

cursor body ::=

Description of the illustration cursor_body.gif

cursor parameter declaration ::=

Description of the illustration cursor_parameter_declaration.gif

rowtype ::=

Description of the illustration rowtype.gif

Keyword and Parameter Description

cursor_name

An explicit cursor previously declared within the current scope.

datatype

A type specifier. For the syntax of datatype, see "Constant and Variable Declaration".

db_table_name

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

expression

A 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

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 IN parameters. The query can also reference other PL/SQL variables within its scope.

record_name

A user-defined record previously declared within the current scope.

record_type_name

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

RETURN

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

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

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 Statement". If the cursor declaration declares parameters, each parameter must be used in the query.

%TYPE

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. You must declare a variable before referencing it in a cursor declaration. The word SQL is reserved by PL/SQL as the default name for implicit cursors, and cannot be used in a cursor declaration.

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

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, that is, without precision and scale for numbers, and without length for strings.

Examples

For examples, see the following:

Example 6-9, "Declaring a Cursor"
Example 6-10, "Fetching With a Cursor"
Example 6-13, "Fetching Bulk Data With a Cursor"
Example 6-27, "Passing a REF CURSOR as a Parameter"
Example 6-29, "Stored Procedure to Open a Ref Cursor"
Example 6-30, "Stored Procedure to Open Ref Cursors with Different Queries"
Example 13-1, "Declaring and Assigning Values to Variables"