Student Notebook

Unit 5. Programming - Cursor Handling

What This Unit is About
This unit describes how cursors can be used in application programs to fetch rows from DB2 tables.

What You Should Be Able to Do

After completing this unit, you will Know how to use a cursor to fetch rows from a DB2 table Know how to update and delete rows with a cursor

References
SC26-8958 SC26-8966 DB2 for OS/390 Version 5: Application Programming and SQL Guide DB2 for OS/390 Version 5: SQL Reference

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-1

Student Notebook

Figure

5-1. Objectives (CF825OBJ)

Notes:

5-2

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Student Notebook

5.1 Programming - Cursor Handling

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-3

Student Notebook

Figure

5-2. Row at a Time Processing - The Problem (CF823730)

Notes:
At this point, we have seen the "simple" case where a program selects a single row into a host structure. What will happen if several rows have to be retrieved from a table? It doesn't work.

5-4

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Student Notebook

Figure

5-3. Row at a Time Processing - Cursors... (CF823740)

Notes:
The solution is to use a "Cursor". The select statement is associated with a cursor (once). The cursor is opened (once). It is then used to fetch every row from the result table of the select into the host structure, one row at a time.

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-5

Student Notebook

Figure

5-4. Program Structure with Cursors (CF825040)

Notes:
Note the DECLARE CURSOR statement that is used to associate the select statement with the cursor. It is given a name (DPROJ).

5-6

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Student Notebook

Figure

5-5. Program Structure with Cursors (CF825050)

Notes:
When the cursor is opened, DB2 executes its access path to position the cursor just before the first row of the result set. Subsequent FETCHes are used to retrieve a row at a time and fill the host and indicator variables. SQLSTATE 02000 (SQLCODE +100) signals that there is no more data to be retrieved. The cursor can be closed.

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-7

Student Notebook

Figure

5-6. Cursor Functions (CF823750)

Notes:
The visual describes the basic steps in cursor handling. Before you can use a cursor, it must be DECLAREd.

5-8

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Student Notebook

Figure

5-7. Cursor Declaration (CF823760)

Notes:
The DECLARE CURSOR statement is used to associate a cursor with the SQL statement. No data access is performed at this stage. The WITH HOLD option is important if you want to issue COMMIT inside the fetch loop. If you omit this keyword, you will have to re-open (and DB2 will have to re-execute the access path) the cursor after each COMMIT, because its position will be lost due to the COMMIT.

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-9

Student Notebook

Figure

5-8. Updating/Deleting with a Cursor (CF823770)

Notes:
Once a cursor is positioned on a row, you can do a "positioned" update or delete. It means that the update/delete doesn't require that DB2 re-access the data as it would have to do if you used "delete where key = " . This would mean a new SQL statement to DB2 and therefore re-accessing the data.

5-10

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Student Notebook

Figure

5-9. Read-Only Cursors (CF823780)

Notes:
However, some cursors are "read/only". The reason behind this is that for some SQL statements, it will not be possible for DB2 to "position" itself before the first result row without accessing the entire result set. Take the example of a SELECT .. ORDER BY. DB2 will have to get all qualifying rows and sort them before it can position its cursor. In addition, the cursor will be positioned on an intermediate result table and not on the actual data itself. Isolation UR will force a cursor into RO mode if the cursor has no 'FOR UPDATE of' clause which would overrule the UR option.

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-11

Student Notebook

Figure

5-10. OPTIMIZE FOR n ROWS (CF823785)

Notes:
The 'OPTIMIZE FOR N ROWS' clause is extremely useful in those cases where there is a difference between the result of the cursor and the amount of rows that your program will actually process. This kind of behavior is often experienced in an online environment where people want to implement scrolling or other cases where you don't specify the PK (Primary Key) in the WHERE clause. The OPTIMIZE FOR clause, however, is not a magic clause that will solve all your access performance problems. If there is no good technique to answer your question, DB2 still has to use whatever access path is available. There is no real impact of adding the OPTIMIZE FOR clause to a cursor, as it is only used during the access path determination. You can still fetch all the rows in the answer set, even if you specified a smaller value for n. An additional consideration of the clause is that it will determine the largest block that can be sent in a distributed environment.

5-12

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Student Notebook

Figure

5-11. WITH CS/RR/RS/UR (CF823787)

Notes:
The 'WITH' isolation level clause allows you to override the isolation level of the plan/package. This option can also be used on a simple 'SELECT INTO'. If you combine the WITH isolation level with the FOR UPDATE clause, the latter will take precedence, and the isolation level will be upgraded to CS.

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-13

Student Notebook

KEEP UPDATE LOCKS

FOR UPDATE OF WITH RS/RR KEEP UPDATE LOCKS Maintain X-lock on row/page even if the row was not updated Might reduce the possibility of a deadlock

Figure

5-12. KEEP UPDATE LOCKS (CF825050)

Notes:
If the KEEP UPDATE LOCKS option is used, DB2 acquires a exclusive lock even if the row is not actually updated. This might reduce the possibility of experiencing a deadlock. If not used properly, it could also reduce the degree of concurrency. -------------*

5-14

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Student Notebook

Figure

5-13. Cursor Related Statements - Summary (CF825100)

Notes:
This is a wrap-up of the statements described in this chapter.

Copyright IBM Corp. 1989, 1997 Unit 5. Cursor Handling Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5-15

Student Notebook

5-16

DB2 Appl. Progr.

Copyright IBM Corp. 1989, 1997 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.