Defines a cursor.
declare cursor_name cursor
for select_statement
[for {read only | update [of column_name_list]}]
is the name of the cursor being defined.
is the query that defines the cursor result set. See select for more information.
specifies that the cursor result set cannot be updated.
specifies that the cursor result set is updatable.
is the list of columns from the cursor result set (specified by the select_statement) defined as updatable. Adaptive Server also allows you to include columns that are not specified in the list of columns of the cursor’s select_statement (and excluded from the result set), but that are part of the tables specified in the select_statement.
Defines a result set for the authors_crsr cursor that contains all authors from the authors table who do not reside in California:
declare authors_crsr cursor for select au_id, au_lname, au_fname from authors where state != 'CA'
Defines a read-only result set for the titles_crsr cursor that contains the business-type books from the titles table:
declare titles_crsr cursor for select title, title_id from titles where title_id like "BU%" for read only
Defines an updatable result set for the pubs_crsr cursor that contains all of the rows from the publishers table. It defines the address of each publisher (cityand state columns) for update:
declare pubs_crsr cursor for select pub_name, city, state from publishers for update of city, state
A declare cursor statement must precede any open statement for that cursor.
You cannot include other statements with declare cursor in the same Transact-SQL batch.
You can include up to 1024 columns in an update clause of a client’s declare cursor statement.
cursor_name must be a valid Adaptive Server identifier.
select_statement can use the full syntax and semantics of a Transact-SQL select statement, with these restrictions:
Must contain a from clause.
Cannot contain a compute, for browse, or into clause.
Can contain the holdlock keyword.
The select_statement can contain references to Transact-SQL parameter names or Transact-SQL local variables (for all cursor types except language). The names must reference the Transact-SQL parameters and local variables defined in the procedure, trigger, or statement batch that contains the declare cursor statement.
The parameters and local variables referenced in the declare cursor statement do not have to contain valid values until the cursor is opened.
The select_statement can contain references to the inserted and deleted temporary tables that are used in triggers.
A cursor’s existence depends on its scope. The scope refers to the context in which the cursor is used, that is, within a user session, within a stored procedure, or within a trigger.
Within a user session, the cursor exists only until the user ends the session. The cursor does not exist for any additional sessions started by other users. After the user logs off, Adaptive Server deallocates the cursors created in that session.
If a declare cursor statement is part of a stored procedure or trigger, the cursor created within it applies to stored procedure or trigger scope and to the scope that launched the stored procedure or trigger. Cursors declared inside a trigger on an inserted or a deleted table are not accessible to any nested stored procedures or triggers. However, cursors declared inside a trigger on an inserted or a deleted table are accessible within the scope of the trigger. Once the stored procedure or trigger completes, Adaptive Server deallocates the cursors created within it.
Figure 7-1 illustrates how cursors operate between scopes.
Figure 7-1: How cursors operate within scopes
A cursor name must be unique within a given scope. Adaptive Server detects name conflicts within a particular scope only during runtime. A stored procedure or trigger can define two cursors with the same name if only one is executed. For example, the following stored procedure works because only one names_crsr cursor is defined in its scope:
create procedure proc2 @flag int as if @flag > 0 declare names_crsr cursor for select au_fname from authors else declare names_crsr cursor for select au_lname from authors return
Cursor result set rows may not reflect the values in the actual base table rows. For example, a cursor declared with an order by clause usually requires the creation of an internal table to order the rows for the cursor result set. Adaptive Server does not lock the rows in the base table that correspond to the rows in the internal table, which permits other clients to update these base table rows. In that case, the rows returned to the client from the cursor result set would not be in sync with the base table rows.
A cursor result set is generated as the rows are returned through a fetch of that cursor. This means that a cursor select query is processed like a normal select query. This process, known as a cursor scan, provides a faster turnaround time and eliminates the need to read rows that are not required by the application.
A restriction of cursor scans is that they can only use the unique indexes of a table. However, if none of the base tables referenced by the cursor result set are updated by another process in the same lock space as the cursor, the restriction is unnecessary. Adaptive Server allows the declaration of cursors on tables without unique indexes, but any attempt to update those tables in the same lock space closes all cursors on the tables.
After defining a cursor using declare cursor, Adaptive Server determines whether the cursor is updatable or read-only. If a cursor is updatable, you can update or delete rows within the cursor result set. If a cursor is read-only, you cannot change the result set.
Use the for update or for read only clause to explicitly define a cursor as updatable or read-only. You cannot define an updatable cursor if its select_statement contains one of the following constructs:
distinct option
group by clause
Aggregate function
Subquery
union operator
at isolation read uncommitted clause
If you omit either the for update or the read only clause, Adaptive Server checks to see whether the cursor is updatable.
Adaptive Server also defines a cursor as read-only if you declare a language- or server-type cursor that includes an order by clause as part of its select_statement. Adaptive Server handles updates differently for client- and execute-type cursors, thereby eliminating this restriction.
If you do not specify a column_name_list with the for update clause, all the specified columns in the query are updatable. Adaptive Server attempts to use unique indexes for updatable cursors when scanning the base table. For cursors, Adaptive Server considers an index containing an IDENTITY column to be unique, even if it is not so declared.
If you do not specify the for update clause, Adaptive Server chooses any unique index, although it can also use other indexes or table scans if no unique index exists for the specified table columns. However, when you specify the for update clause, Adaptive Server must use a unique index defined for one or more of the columns to scan the base table. If none exists, it returns an error.
In most cases, include only columns to be updated in the column_name_list of the for update clause. If the table has only one unique index, you do not need to include its column in the for update column_name_list; Adaptive Server will find it when it performs the cursor scan. If the table has more than one unique index, include its column in the for update column_name_list, so that Adaptive Server can find it quickly for the cursor scan.
This allows Adaptive Server to use that unique index for its cursor scan, which helps prevent an update anomaly called the Halloween problem. Another way to prevent the Halloween problem is to create tables with the unique auto_identity index database option. For more information, see the System Administration Guide.
The Halloween problem occurs when a client updates a column of a cursor result set row that defines the order in which the rows are returned from the base tables. For example, if Adaptive Server accesses a base table using an index, and the index key is updated by the client, the updated index row can move within the index and be read again by the cursor. This is a result of an updatable cursor only logically creating a cursor result set. The cursor result set is actually the base tables that derive the cursor.
If you specify the read only option, the cursor result set cannot be updated using the delete or update statement.
SQL92 – Compliance level: Entry-level compliant.
The for update and for read only options are Transact-SQL extensions.
declare cursor permission defaults to all users. No permission is required to use it.
Commands open
