Using Cursor Attributes

END LOOP; END;

/

Example 6–2 Passing Parameters to Explicit Cursors

For example, here are several ways to open a cursor:

DECLARE

emp_name employees.last_name%TYPE := 'Austin'; emp_salary employees.salary%TYPE := 30000; my_record employees%ROWTYPE;

CURSOR c1 (name VARCHAR2, max_wage NUMBER) IS

SELECT * FROM employees WHERE last_name = name and salary < max_wage; BEGIN

--Any of the following statements opens the cursor:

--OPEN c1('Austin', 3000);

--OPEN c1('Austin', emp_salary);

--OPEN c1(emp_name, 3000);

--OPEN c1(emp_name, emp_salary);

OPEN c1(emp_name, emp_salary); LOOP

FETCH c1 INTO my_record; EXIT WHEN c1%NOTFOUND; -- process data record

dbms_output.put_line('Name = ' || my_record.last_name || ', salary = ' || my_record.salary);

END LOOP; END;

/

To avoid confusion, use different names for cursor parameters and the PL/SQL variables that you pass into those parameters.

Formal parameters declared with a default value do not need a corresponding actual parameter. If you omit them, they assume their default values when the OPEN statement is executed.

Using 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. You can use cursor attributes in procedural statements but not in SQL statements.

Overview of Explicit Cursor Attributes

Explicit cursor attributes return information about the execution of a multi-row query. When an explicit cursor or a 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.

6-16 PL/SQL User's Guide and Reference

Using Cursor Attributes

%FOUND Attribute: Has a Row Been Fetched?

After a cursor or cursor variable is opened but before the first fetch, %FOUND returns NULL. After any fetches, it returns TRUE if the last fetch returned a row, or FALSE if the last fetch did not return a row. The following example uses %FOUND to select an action:

DECLARE

CURSOR c1 IS SELECT last_name, salary FROM employees WHERE ROWNUM < 11; my_ename employees.last_name%TYPE;

my_salary employees.salary%TYPE; BEGIN

OPEN c1; LOOP

FETCH c1 INTO my_ename, my_salary; IF c1%FOUND THEN -- fetch succeeded

dbms_output.put_line('Name = ' || my_ename || ', salary = ' || my_salary);

ELSE -- fetch failed, so exit loop EXIT;

END IF; END LOOP;

END;

/

If a cursor or cursor variable is not open, referencing it with %FOUND raises the predefined exception INVALID_CURSOR.

%ISOPEN Attribute: Is the Cursor Open?

%ISOPEN returns TRUE if its cursor or cursor variable is open; otherwise, %ISOPEN returns FALSE. The following example uses %ISOPEN to select an action:

DECLARE

CURSOR c1 IS SELECT last_name, salary FROM employees WHERE ROWNUM < 11; the_name employees.last_name%TYPE;

the_salary employees.salary%TYPE; BEGIN

IF c1%ISOPEN = FALSE THEN -- cursor was not already open OPEN c1;

END IF;

FETCH c1 INTO the_name, the_salary; CLOSE c1;

END;

/

%NOTFOUND Attribute: Has a Fetch Failed?

%NOTFOUND is the logical opposite of %FOUND. %NOTFOUND yields FALSE if the last fetch returned a row, or TRUE if the last fetch failed to return a row. In the following example, you use %NOTFOUND to exit a loop when FETCH fails to return a row:

DECLARE

CURSOR c1 IS SELECT last_name, salary FROM employees WHERE ROWNUM < 11; my_ename employees.last_name%TYPE;

my_salary employees.salary%TYPE; BEGIN

OPEN c1; LOOP

FETCH c1 INTO my_ename, my_salary;

IF c1%NOTFOUND THEN -- fetch failed, so exit loop -- A shorter form of this test is "EXIT WHEN c1%NOTFOUND;"

Performing SQL Operations from PL/SQL 6-17

Using Cursor Attributes

EXIT;

ELSE -- fetch succeeded

dbms_output.put_line('Name = ' || my_ename || ', salary = ' || my_salary);

END IF; END LOOP;

END;

/

Before the first fetch, %NOTFOUND returns NULL. If FETCH never executes successfully, the loop is never exited, 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;

If a cursor or cursor variable is not open, referencing it with %NOTFOUND raises an

INVALID_CURSOR exception.

%ROWCOUNT Attribute: How Many Rows Fetched So Far?

When its cursor or cursor variable is opened, %ROWCOUNT is zeroed. Before the first fetch, %ROWCOUNT yields 0. Thereafter, it yields the number of rows fetched so far. The number is incremented if the last fetch returned a row. The following example uses %ROWCOUNT to test if more than ten rows have been fetched:

DECLARE

CURSOR c1 IS SELECT last_name FROM employees WHERE ROWNUM < 11; name employees.last_name%TYPE;

BEGIN

OPEN c1; LOOP

FETCH c1 INTO name; EXIT WHEN c1%NOTFOUND;

dbms_output.put_line(c1%ROWCOUNT || '. ' || name); IF c1%ROWCOUNT = 5 THEN

dbms_output.put_line('--- Fetched 5th record ---'); END IF;

END LOOP; CLOSE c1;

END;

/

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

INVALID_CURSOR.

Table 6–1 shows what each cursor attribute returns before and after you execute an

OPEN, FETCH, or CLOSE statement.

Table 6–1 Cursor Attribute Values

6-18 PL/SQL User's Guide and Reference