Ref cursor
Download as DOCX, PDF0 likes467 views
- A ref cursor is a variable that references the result of a cursor, allowing it to be passed between procedures and functions. - Ref cursors can be weakly typed, where the returned data type is unknown, or strongly typed by defining the row type being returned. - Examples show opening a ref cursor, passing it to other procedures to be processed, and closing the cursor once processing is complete. Ref cursor variables point to a single underlying cursor.
Ref cursor
- 1. PL/SQL Ref Cursors examples A ref cursor is a variable, defined as a cursor type, which will point to, or reference a cursor result. The advantage that a ref cursor has over a plain cursor is that is can be passed as a variable to a procedure or a function. The REF CURSOR can be assigned to other REF CURSOR variables. This is a powerful capability in that the cursor can be opened, then passed to another block for processing, then returned to the original block to be closed. The cursor variable can also be returned by a function and assigned to another variable. The REF CURSOR variable is not a cursor, but a variable that points to a cursor. Before assigning a cursor variable, a cursor type must be defined. type author_cursor is ref cursor; This REF CURSORis a weak typed cursor variable because it does not define the datatype the cursor will return. Below is the same cursor that is strongly typed. type author_cursor is ref cursor returning author%rowtype; By strongly typing the cursor variable, you define what the cursor can return. If a strongly typed cursor returns something other that its return type, a ROWTYPE_MISMATCH exception is raised. A strongly typed cursor type is less flexible but less prone to programming errors. The PL/SQL compiler will verify that the FETCH clause has the correct variable/record for the cursor return type at compile time. Once the cursor type is defined, the actual variable can be defined as the cursor type. c1 author_cursor; Now c1 is a variable of a cursor type. It is opened using a SQL statement. open c1 for select * from authors; Now c1 has all the attributes of the actual cursor. As with any cursor it is important to close the cursor as soon as you have completed processing. SQL> declare 2 type auth_cursor is ref cursor; 3 c1 auth_cursor; 4 r_c1 author%rowtype; 5 begin 6 open c1 for select * from author; 7 fetch c1 into r_c1;
- 2. 8 if c1%isopen then 9 dbms_output.put_line( 'The Cursor is open.'); 10 end if; 11 dbms_output.put_line( 'Row Count is '||c1%rowcount); 12 close c1; 13 if not c1%isopen then 14 dbms_output.put_line( 'The Cursor is closed.'); 15 end if; 16 end; 17 / The Cursor is open. Row Count is 1 The Cursor is closed. Here some of the cursor attributes are used to process the cursor. Notice that the record used to hold a fetched cursor row is defined as an author table %rowtype. Even though the example cursor variable is defined, the record can not use it because the cursor variable return type is not defined. The example below attempts to create a cursor %rowtype variable for processing. SQL> declare 2 type auth_cursor is ref cursor; 3 c1 auth_cursor; 4 r_c1 c1%rowtype; 5 begin 6 null; 7 end; 8 / r_c1 c1%rowtype; * ERROR at line 4: ORA-06550: line 4, column 8: PLS-00320: the declaration of the type of this expression is incomplete or malformed ORA-06550: line 4, column 8: PL/SQL: Item ignored However, a strongly typed cursor can use the cursor variable to define the cursor record. SQL> declare 2 type auth_cursor is ref cursor return author%rowtype; 3 c1 auth_cursor; 4 r_c1 c1%rowtype; 5 begin 6 null; 7 end; 8 /
- 3. In this example, the auth_cursor type returns an author%rowtype. Because this is defined in line 2, the record defined in line 4 can now use it. Cursor variables that are weakly typed can be defined to return any values. In the example below, the cursor variable c1 is defined as three different statements. SQL> declare 2 type auth_cursor is ref cursor; 3 c1 auth_cursor; 4 r_c1 author%rowtype; 5 r2_c1 book%rowtype; 6 r3_c1 number; 7 begin 8 open c1 for select * from author; 9 fetch c1 into r_c1; 10 close c1; 11 open c1 for select * from book; 12 fetch c1 into r2_c1; 13 close c1; 14 open c1 for select sum(quantity) 15 from store join sales using (store_key) 16 group by store_name; 17 fetch c1 into r3_c1; 18 close c1; 19 end; 20 / Although the block does not do anything but open and close the cursor variable, it does demonstrate that weakly typed variables can be defined differently each time the variable is opened. But what happens when a cursor variable is defined with a SQL statement but returns unexpected values? Below is an example of defining a cursor variable of one type and the record as another. The cursor variable is returning all columns in the book table, but the receiving variable is defined as a record of columns from the author table. SQL> declare 2 type auth_cursor is ref cursor; 3 c1 auth_cursor; 4 r_c1 author%rowtype; 5 begin 6 open c1 for select * from book; 7 fetch c1 into r_c1; 8 close c1; 9 end; 10 / declare * ERROR at line 1: ORA-06504: PL/SQL: Return types of Result Set variables or query do not match ORA-06512: at line 7
- 4. Notice that the error message is pointing to the DECLARE clause. That is because the block successfully compiled and only threw the error when it was executed. The PL/SQL compiler can not catch the error because the cursor type did not define a return type. By changing the definition of the cursor type to a strongly typed definition, the compiler will catch this error when the code is compiled. SQL> declare 2 type auth_cursor is ref cursor 3 return book%rowtype; 4 c1 auth_cursor; 5 r_c1 author%rowtype; 6 begin 7 open c1 for select * from book; 8 fetch c1 into r_c1; 9 close c1; 10 end; 11 / fetch c1 into r_c1; * ERROR at line 8: ORA-06550: line 8, column 5: PLS-00394: wrong number of values in the INTO list of a FETCH statement ORA-06550: line 8, column 5: PL/SQL: SQL Statement ignored Now the compiler catches the error. So far the examples have been using the cursor variables as regular cursors. The real advantage of using a cursor variable is the ability to pass it as a parameter. In the example below a local function is used to open a cursor called c1 and return it. The block body calls the function to assign the cursor to the cursor variable c2. The block body then processes the cursor and closes it. SQL> declare 2 type auth_cursor is ref cursor return author%rowtype; 3 c2 auth_cursor; 4 r_c2 c2%rowtype; 5 6 function get_auth return auth_cursor 7 is 8 c1 auth_cursor; 9 begin 10 open c1 for select * from author; 11 return c1; 12 end; 13 14 begin 15 c2 := get_auth;
- 5. 16 loop 17 fetch c2 into r_c2; 18 exit when c2%notfound; 19 dbms_output.put_line(initcap( r_c2.author_last_name)); 20 end loop; 21 close c2; 22 end; 23 / Jones Hester Weaton Jeckle Withers Petty Clark Mee Shagger Smith Line 2 defines the cursor type. Lines 3 and 4 define the cursor and return record used in the body. Line 6 declares a local function called get_auth that returns anauth_cursor type. Inside this local function, cursor c1 is defined as an auth_cursortype, opened and returned to the calling code. The function is actually executed on line 15 when c2 is assigned the return value of the get_auth function. The cursor c2 is processed and finally closed on line 21. Note that c1 opened the cursor and c2 closed it. This is an important point. The example contains only ONE cursor. When c2 is assign the value of c1, both variables point to the same cursor. Remember that c1 andc2 are variables that point to or reference the actual cursor. The same basic example is shown below except, the output is generated by a local procedure. Note that the procedure print_name gets passed the cursor c2 and then processes it. It then passes the cursor backup to be closed by the body of the PL/SQL block. SQL> declare 2 type auth_cursor is ref cursor return author%rowtype; 3 c2 auth_cursor; 4 r_c2 c2%rowtype; 5 6 function get_auth return auth_cursor 7 is 8 c1 auth_cursor; 9 begin 10 open c1 for select * from author; 11 return c1; 12 end; 13 14 procedure print_name (c3 in out auth_cursor)
- 6. 15 as 16 r_c3 author%rowtype; 17 begin 18 loop 19 fetch c3 into r_c3; 20 exit when c3%notfound; 21 dbms_output.put_line( initcap(r_c3.author_last_name)); 22 end loop; 23 end; 24 25 begin 26 c2 := get_auth; 27 print_name(c2); 28 close c2; 29 end; 30 / Jones Hester Weaton Jeckle Withers Petty Clark Mee Shagger Smith There are three items you should note about this PL/SQL block. First, the body is pretty simple to understand. Get the authors, print the names, and close the cursor. Second, you can pass cursor variables to procedures and functions, and functions can return the variables. Lastly, it can become confusing about when a cursor variable should be closed.