declare cursor

Description

Defines a cursor, by associating a select statement with a cursor name. You can use declare cursor with an archive database.

Syntax

declare cursor_name 
[semi_sensitive | insensitive] [scroll | no scroll] [release_locks_on_close]
	cursor for select_statement 
	[for {read only | update [of column_name_list]}]

Parameters

cursor_name

is the name of the cursor being defined.

select_statement

is the query that defines the cursor result set. See select for more information.

semi_sensitive

specifies that the data changes made independently of the cursor may be visible to the cursor result set. The visibility of the dependent data changes depends on the query plan chosen by the optimizer. If there is no worktable created in the plan, the data changes are visible to the result set. The default is semi_sensitive.

insensitive

specifies that the data changes made independently of the cursor are not visible to the cursor result set. If you do not specify this argument, the default is semi_sensitive. You cannot update an insensitive cursor.

scroll | no scroll

specifies whether the declared cursor is scrollable. Scrollable cursors allowing you fetch the cursor result set nonsequentially, allowing you to scan the cursor back and forth. You cannot update a scrollable cursor.

release_locks_on_close

allows you to configure the lock-releasing behavior of each cursor so that the shared locks can be released when the cursor is closed, even if the transaction is active. This option applies to cursors of all types.

for read only

specifies that the cursor result set cannot be updated.

for update

specifies that the cursor result set is updatable.

of column_name_list

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.

Examples

Example 1

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'

Example 2

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

Example 3

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 (city and state columns) for update:

declare pubs_crsr cursor
for select pub_name, city, state
from publishers
for update of city, state

Example 4

Defines an insensitive scrollable result set for the stores_scrollcrsr that contains the book stores in California:

declare stores_scrollcrsr insensitive scroll cursor
for select stor_id, stor_name 
from stores where state = 'CA'

Example 5

Defines an insensitive nonscrollable result set for the stores_scrollcrsr that contains the book stores in California:

declare stores_scrollcrsr insensitive no scroll cursor
for select stor_id, stor_name 
from stores where state = 'CA'

Usage


Restrictions on cursors


Cursor select statements


Cursor scope


Result set


Updatable cursors


Releasing locks at cursor close

release_locks_on_close has no effect if the cursor scan occurs at isolation level 1.

The default behavior at isolation levels 2 and 3 if the transaction is committed or rolled back before the cursor is closed is for Adaptive Server to release the shared locks acquired by the cursor until that point, with the exception of the lock on the last fetched row. If you use release_on_locks_close, the shared locks acquired by the cursor exist until the cursor is closed.

Use sp_cursorinfo to determine if a cursor was declared with the release_on_locks_close parameter:

1) sp_cursorinfo
2> go
Cursor name 'c' is declared at nesting level '0'.
The cursor is declared as NON-SCROLLABLE 
RELEASE_LOCKS_ON_CLOSE cursor.
The cursor id is 917505.
The cursor has been successfully opened 0 times.
The cursor will remain open when a transaction is
committed or rolled back.

Updatable cursors and allpages locking

If you specify the read only option, you cannot update the cursor result set using the cursor name to perform update or delete.


Using scrollable cursors

Standards

ANSI SQL – Compliance level: Entry-level compliant.

Permissions

No permission is required to use declare cursor.

See also

Commands open