DECLARE CURSOR statement The DECLARE CURSOR statement defines a cursor.

Invocation Although an interactive SQL facility might provide an interface that gives the a ppearance of interactive execution, this statement can only be embedded within a n application program. It is not an executable statement and cannot be dynamical ly prepared. Authorization The term "SELECT statement of the cursor" is used to specify the authorization r ules. The SELECT statement of the cursor is one of the following: The prepared select-statement identified by statement-name The specified select-statement For each table or view identified (either directly or by using an alias) in the SELECT statement of the cursor, the privileges held by the authorization ID of t he statement must include at least one of the following: For each table or view identified in the select-statement: SELECT privilege on the table or view, or CONTROL privilege on the table or view SYSADM or DBADM authority 4 If the select-statement contains an SQL data 4 change statement, the authoriza tion requirements of that statement 4 also apply to the DECLARE CURSOR statement . If statement-name is specified: The authorization ID of the statement is the run-time authorization ID. The authorization check is performed when the select-statement is prepared. The cursor cannot be opened unless the select-statement is successfully prepared . If select-statement is specified: GROUP privileges are not checked. The authorization ID of the statement is the authorization ID specified during p rogram preparation. Syntax >>-DECLARE--cursor-name--CURSOR--+-----------+------------------> '-WITH HOLD-' >--+----------------------------+--FOR--+-select-statement-+--->< .-TO CALLER-. '-statement-name---' '-WITH RETURN--+-----------+-' '-TO CLIENT-' Description cursor-name Specifies the name of the cursor created when the source program is run. The nam e must not be the same as the name of another cursor declared in the source prog ram. The cursor must be opened before use. WITH HOLD Maintains resources across multiple units of work. The effect of the WITH HOLD c ursor attribute is as follows: For units of work ending with COMMIT: Open cursors defined WITH HOLD remain open. The cursor is positioned before the next logical row of the results table. If a DISCONNECT statement is issued after a COMMIT statement for a connection wi th WITH HOLD cursors, the held cursors must be explicitly closed or the connecti

on will be assumed to have performed work (simply by having open WITH HELD curso rs even though no SQL statements were issued) and the DISCONNECT statement will fail. All locks are released, except locks protecting the current cursor position of o pen WITH HOLD cursors. The locks held include the locks on the table, and for pa rallel environments, the locks on rows where the cursors are currently positione d. Locks on packages and dynamic SQL sections (if any) are held. Valid operations on cursors defined WITH HOLD immediately following a COMMIT req uest are: FETCH: Fetches the next row of the cursor. CLOSE: Closes the cursor. UPDATE and DELETE CURRENT OF CURSOR are valid only for rows that are fetched wit hin the same unit of work. LOB locators are freed. 4 The set of rows modified by: 4 4 4 A data change statement 4 Routines that mod ify SQL data embedded within open WITH HOLD 4 cursors 4 is committed. For units of work ending with ROLLBACK: All open cursors are closed. All locks acquired during the unit of work are released. LOB locators are freed. For special COMMIT case: Packages may be recreated either explicitly, by binding the package, or implicit ly, because the package has been invalidated and then dynamically recreated the first time it is referenced. All held cursors are closed during package rebind. This may result in errors during subsequent execution. WITH RETURN This clause indicates that the cursor is intended for use as a result set from a procedure. WITH RETURN is relevant only if the DECLARE CURSOR statement is cont ained with the source code for a procedure. In other cases, the precompiler may accept the clause, but it has no effect. Within an SQL procedure, cursors declared using the WITH RETURN clause that are still open when the SQL procedure ends, define the result sets from the SQL proc edure. All other open cursors in an SQL procedure are closed when the SQL proced ure ends. Within an external procedure (one not defined using LANGUAGE SQL), the default for all cursors is WITH RETURN TO CALLER. Therefore, all cursors that a re open when the procedure ends will be considered result sets. TO CALLER Specifies that the cursor can return a result set to the caller. For example, if the caller is another procedure, the result set is returned to that procedure. If the caller is a client application, the result set is returned to the client application. TO CLIENT Specifies that the cursor can return a result set to the client application. Thi s cursor is invisible to any intermediate nested procedures. If a function or me thod called the procedure either directly or indirectly, result sets cannot be r eturned to the client and the cursor will be closed after the procedure finishes . select-statement Identifies the SELECT statement of the cursor. The select-statement must not inc lude parameter markers, but can include references to host variables. The declar ations of the host variables must precede the DECLARE CURSOR statement in the so urce program. statement-name The SELECT statement of the cursor is the prepared SELECT statement identified b y the statement-name when the cursor is opened. The statement-name must not be i dentical to a statement-name specified in another DECLARE CURSOR statement of th e source program.

For an explanation of prepared SELECT statements, see "PREPARE". Notes A program called from another program, or from a different source file within th e same program, cannot use the cursor that was opened by the calling program. Unnested procedures, with LANGUAGE other than SQL, will have WITH RETURN TO CALL ER as the default behavior if DECLARE CURSOR is specified without a WITH RETURN clause, and the cursor is left open in the procedure. This provides compatibilit y with procedures from previous versions that allow procedures to return result sets to applicable client applications. To avoid this behavior, close all cursor s opened in the procedure. If the SELECT statement of a cursor contains CURRENT DATE, CURRENT TIME, or CURR ENT TIMESTAMP, all references to these special registers will yield the same res pective datetime value on each FETCH. This value is determined when the cursor i s opened. For more efficient processing of data, the database manager can block data for r ead-only cursors when retrieving data from a remote server. The use of the FOR U PDATE clause helps the database manager decide whether a cursor is updatable or not. Updatability is also used to determine the access path selection as well. I f a cursor is not going to be used in a Positioned UPDATE or DELETE statement, i t should be declared as FOR READ ONLY. A cursor in the open state designates a result table and a position relative to the rows of that table. The table is the result table specified by the SELECT st atement of the cursor. A cursor is deletable if each of the following is true: each FROM clause of the outer fullselect identifies only one base table or delet able view (cannot identify a nested or common table expression or a nickname) wi thout use of the OUTER clause the outer fullselect does not include a VALUES clause the outer fullselect does not include a GROUP BY clause or HAVING clause the outer fullselect does not include column functions in the select list the outer fullselect does not include SET operations (UNION, EXCEPT, or INTERSEC T) with the exception of UNION ALL the select list of the outer fullselect does not include DISTINCT 4 the outer fullselect does not include an ORDER BY 4 clause (even if the ORDER BY clause is nested in a view), and the FOR 4 UPDATE clause has not been specifi ed the select-statement does not include a FOR READ ONLY clause 4 the FROM clause of the outer fullselect does not include 4 a data-change-table -reference one or more of the following is true: the FOR UPDATE clause is specified 4 the cursor is statically defined, unless the 4 STATICREADONLY bind option is Y ES the LANGLEVEL bind option is MIA or SQL92E A column in the select list of the outer fullselect associated with a cursor is updatable if each of the following is true: the cursor is deletable the column resolves to a column of the base table the LANGLEVEL bind option is MIA, SQL92E or the select-statement includes the FO R UPDATE clause (the column must be specified explicitly or implicitly in the FO R UPDATE clause) A cursor is read-only if it is not deletable. A cursor is ambiguous if each of the following is true: the select-statement is dynamically prepared the select-statement does not include either the FOR READ ONLY clause or the FOR UPDATE clause

the LANGLEVEL bind option is SAA1 the cursor otherwise satisfies the conditions of a deletable cursor An ambiguous cursor is considered read-only if the BLOCKING bind option is ALL, otherwise it is considered updatable. Cursors in procedures that are called by application programs written using CLI can be used to define result sets that are returned directly to the client appli cation. Cursors in SQL procedures can also be returned to a calling SQL procedur e only if they are defined using the WITH RETURN clause. Cursors declared in routines that are invoked directly or indirectly from a curs or declared WITH HOLD, do not inherit the WITH HOLD option. Thus, unless the cur sor in the routine is explicitly defined WITH HOLD, a COMMIT in the application will close it. Consider the following application and two UDFs: Application: DECLARE APPCUR CURSOR WITH HOLD FOR SELECT UDF1() ... OPEN APPCUR FETCH APPCUR ... COMMIT UDF1: DECLARE UDF1CUR CURSOR FOR SELECT UDF2() ... OPEN UDF1CUR FETCH UDF1CUR ... UDF2: DECLARE UDF2CUR CURSOR WITH HOLD FOR SELECT UDF2() ... OPEN UDF2CUR FETCH UDF2CUR ... After the application fetches cursor APPCUR, all three curs ors are open. When the application issues the COMMIT statement, APPCUR remains o pen, because it was declared WITH HOLD. In UDF1, however, the cursor UDF1CUR is closed, because it was not defined with the WITH HOLD option. When the cursor UD F1CUR is closed, all routine invocations in the corresponding select-statement c omplete (receiving a final call, if so defined). UDF2 completes, which causes UD F2CUR to close. Examples Example 1: The DECLARE CURSOR statement associates the cursor name C1 with the results of the SELECT. EXEC SQL DECLARE C1 CURSOR FOR SELECT DEPTNO, DEPTNAME, MGRNO FROM DEPARTMENT WHERE ADMRDEPT = 'A00'; 4 Example 2: 4 Assume that the EMPLOYEE table has been altered to add a generated 4 column, WEEKLYPAY, that calculates the weekly pay based on the yearly 4 salary. 4 Declare a cursor to retrieve the system-gene rated column value from a 4 row to be inserted. 4 4 EXEC SQL DECLARE C2 CURSOR FOR 4 SELECT E.WEEKLYPAY 4 FROM NEW TABLE 4 (INSERT INTO EMPLOYEE 4 (EMPNO, FIRSTNME, MIDINIT, LASTNAME, EDLEVEL, SALARY) 4 VALUES('000420', 'Peter', 'U', 'Bender', 16, 31842) AS E;

CICS and CURSOR WITH HOLD option Use CURSOR WITH HOLD in your CICS program to keep the cursor open and in positio n during a SYNCPOINT. The WITH HOLD option on a CURSOR declaration in a CICS program causes the follow ing effects during a SYNCPOINT: The cursor is kept open. The cursor is left in position after the last row which was retrieved, and befor e the next row in the results table. Dynamic SQL statements are still prepared. All locks are released, except for those required to maintain the cursor's posit ion. Any exclusive page locks are downgraded to shared locks. In conversational CICS applications, you can use DECLARE CURSOR...WITH HOLD to r equest that the cursor is not closed at syncpoint time. However, all cursors are always closed at end of task (EOT) and on SYNCPOINT ROLLBACK. Across EOTs, a cu rsor declared WITH HOLD must be reopened and repositioned just as if the WITH HO LD option were not specified. The scope of the held cursor is a single task. In summary: The next FETCH following a syncpoint must come from the same task. You cannot hold a cursor across end of task. Therefore, cursors are not held across the EOT portions of pseudoconversational transactions. If you try to hold a cursor across EOT, the cursor is closed and you get an SQLC ODE -501 when you execute the next FETCH. The precompiler cannot detect this and you do not get a warning message notifying you of this situation. In general, threads can become candidates for reuse at each syncpoint. When you use DECLARE CURSOR...WITH HOLD in the CICS applications, consider the following recommendations: Close held cursors as soon as they are no longer needed. Once all held cursors a re closed, syncpoint can free the thread for thread reuse. Always close held cursors before EOT. If you do not close your held cursors