Examples: Use a cursor

Suppose your program examines data about people in department D11. The following examples show the SQL statements you would include in a program to define and use a serial and a scrollable cursor.

These cursors can be used to obtain information about the department from the CORPDATA.EMPLOYEE table.

For the serial cursor example, the program processes all of the rows from the table, updating the job for all members of department D11 and deleting the records of employees from the other departments.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

Table 1. A serial cursor example
Serial cursor SQL statement	Described in section
EXEC SQL DECLARE THISEMP CURSOR FOR SELECT EMPNO, LASTNAME, WORKDEPT, JOB FROM CORPDATA.EMPLOYEE FOR UPDATE OF JOB END-EXEC.	Step 1: Define the cursor.
EXEC SQL OPEN THISEMP END-EXEC.	Step 2: Open the cursor.
EXEC SQL WHENEVER NOT FOUND GO TO CLOSE-THISEMP END-EXEC.	Step 3: Specify what to do when end-of-data is reached.
EXEC SQL FETCH THISEMP INTO :EMP-NUM, :NAME2, :DEPT, :JOB-CODE END-EXEC.	Step 4: Retrieve a row using a cursor.
... for all employees in department D11, update the JOB value: EXEC SQL UPDATE CORPDATA.EMPLOYEE SET JOB = :NEW-CODE WHERE CURRENT OF THISEMP END-EXEC. ... then print the row.	Step 5a: Update the current row.
... for other employees, delete the row: EXEC SQL DELETE FROM CORPDATA.EMPLOYEE WHERE CURRENT OF THISEMP END-EXEC.	Step 5b: Delete the current row.
Branch back to fetch and process the next row.
CLOSE-THISEMP. EXEC SQL CLOSE THISEMP END-EXEC.	Step 6: Close the cursor.

For the scrollable cursor example, the program uses the RELATIVE position option to obtain a representative sample of salaries from department D11.

Table 2. Scrollable cursor example
Scrollable cursor SQL statement	Described in section
EXEC SQL DECLARE THISEMP DYNAMIC SCROLL CURSOR FOR SELECT EMPNO, LASTNAME, SALARY FROM CORPDATA.EMPLOYEE WHERE WORKDEPT = 'D11' END-EXEC.	Step 1: Define the cursor.
EXEC SQL OPEN THISEMP END-EXEC.	Step 2: Open the cursor.
EXEC SQL WHENEVER NOT FOUND GO TO CLOSE-THISEMP END-EXEC.	Step 3: Specify what to do when end-of-data is reached.
...initialize program summation salary variable EXEC SQL FETCH RELATIVE 3 FROM THISEMP INTO :EMP-NUM, :NAME2, :JOB-CODE END-EXEC. ...add the current salary to program summation salary ...branch back to fetch and process the next row.	Step 4: Retrieve a row using a cursor.
...calculate the average salary
CLOSE-THISEMP. EXEC SQL CLOSE THISEMP END-EXEC.	Step 6: Close the cursor.

Step 1: Define the cursor
To define a result table to be accessed with a cursor, use the DECLARE CURSOR statement.
Step 2: Open the cursor
To begin processing the rows of the result table, issue the OPEN statement.
Step 3: Specify what to do when end-of-data is reached
To find out when the end of the result table is reached, test the SQLCODE field for a value of 100 or test the SQLSTATE field for a value of '02000' (that is, end-of-data). This condition occurs when the FETCH statement has retrieved the last row in the result table and your program issues a subsequent FETCH.
Step 4: Retrieve a row using a cursor
To move the contents of a selected row into your program's host variables, use the FETCH statement. The SELECT statement within the DECLARE CURSOR statement identifies rows that contain the column values your program wants. However, SQL does not retrieve any data for your application program until the FETCH statement is issued.
Step 5a: Update the current row
When your program has positioned the cursor on a row, you can update its data by using the UPDATE statement with the WHERE CURRENT OF clause. The WHERE CURRENT OF clause specifies a cursor that points to the row you want to update.
Step 5b: Delete the current row
When your program has retrieved the current row, you can delete the row by using the DELETE statement. To do this, you issue a DELETE statement designed for use with a cursor; the WHERE CURRENT OF clause specifies a cursor that points to the row you want to delete.
Step 6: Close the cursor
If you processed the rows of a result table for a serial cursor, and you want to use the cursor again, issue a CLOSE statement to close the cursor prior to re-opening it.

Parent topic: Use a cursor