Declare Cusror of SQLServer

Defines the attributes of a Transact-SQL server cursor, such as its scrolling behavior and the query used to build the result set on which the cursor operates. DECLARE CURSOR accepts both a syntax based on the ISO standard and a syntax using a set of Transact-SQL extensions.

Syntax

ISO Syntax

DECLARE cursor_name [ INSENSITIVE ] [ SCROLL ] CURSOR

     FOR select_statement

     [ FOR { READ ONLY | UPDATE [ OF column_name [ ,...n ] ] } ]

[;]

Transact-SQL Extended Syntax

DECLARE cursor_name CURSOR [ LOCAL | GLOBAL ]

     [ FORWARD_ONLY | SCROLL ]

     [ STATIC | KEYSET | DYNAMIC | FAST_FORWARD ]

     [ READ_ONLY | SCROLL_LOCKS | OPTIMISTIC ]

     [ TYPE_WARNING ]

     FOR select_statement

     [ FOR UPDATE [ OF column_name [ ,...n ] ] ]

[;]

Arguments

cursor_name

Is the name of the Transact-SQL server cursor defined. cursor_name must conform to the rules for identifiers. For more information about rules for identifiers, see Using Identifiers As Object Names.

INSENSITIVE

Defines a cursor that makes a temporary copy of the data to be used by the cursor. All requests to the cursor are answered from this temporary table in tempdb; therefore, modifications made to base tables are not reflected in the data returned by fetches made to this cursor, and this cursor does not allow modifications. When ISO syntax is used, if INSENSITIVE is omitted, committed deletes and updates made to the underlying tables (by any user) are reflected in subsequent fetches.

SCROLL

Specifies that all fetch options (FIRST, LAST, PRIOR, NEXT, RELATIVE, ABSOLUTE) are available. If SCROLL is not specified in an ISO DECLARE CURSOR, NEXT is the only fetch option supported. SCROLL cannot be specified if FAST_FORWARD is also specified.

select_statement

Is a standard SELECT statement that defines the result set of the cursor. The keywords COMPUTE, COMPUTE BY, FOR BROWSE, and INTO are not allowed within select_statement of a cursor declaration.

SQL Server implicitly converts the cursor to another type if clauses in select_statement conflict with the functionality of the requested cursor type. For more information, see Using Implicit Cursor Conversions.

READ ONLY

Prevents updates made through this cursor. The cursor cannot be referenced in a WHERE CURRENT OF clause in an UPDATE or DELETE statement. This option overrides the default capability of a cursor to be updated.

UPDATE [OF column_name [,...n]]

Defines updatable columns within the cursor. If OF column_name [,...n] is specified, only the columns listed allow modifications. If UPDATE is specified without a column list, all columns can be updated.

cursor_name

Is the name of the Transact-SQL server cursor defined. cursor_name must conform to the rules for identifiers. For more information about rules for identifiers, see Using Identifiers As Object Names.

LOCAL

Specifies that the scope of the cursor is local to the batch, stored procedure, or trigger in which the cursor was created. The cursor name is only valid within this scope. The cursor can be referenced by local cursor variables in the batch, stored procedure, or trigger, or a stored procedure OUTPUT parameter. An OUTPUT parameter is used to pass the local cursor back to the calling batch, stored procedure, or trigger, which can assign the parameter to a cursor variable to reference the cursor after the stored procedure terminates. The cursor is implicitly deallocated when the batch, stored procedure, or trigger terminates, unless the cursor was passed back in an OUTPUT parameter. If it is passed back in an OUTPUT parameter, the cursor is deallocated when the last variable referencing it is deallocated or goes out of scope.

GLOBAL

Specifies that the scope of the cursor is global to the connection. The cursor name can be referenced in any stored procedure or batch executed by the connection. The cursor is only implicitly deallocated at disconnect.

Note
If neither GLOBAL or LOCAL is specified, the default is controlled by the setting of the default to local cursor database option. In SQL Server version 7.0, this option defaults to FALSE to match earlier versions of SQL Server, in which all cursors were global. The default of this option may change in future versions of SQL Server. For more information, see Setting Database Options.

FORWARD_ONLY

Specifies that the cursor can only be scrolled from the first to the last row. FETCH NEXT is the only supported fetch option. If FORWARD_ONLY is specified without the STATIC, KEYSET, or DYNAMIC keywords, the cursor operates as a DYNAMIC cursor. When neither FORWARD_ONLY nor SCROLL is specified, FORWARD_ONLY is the default, unless the keywords STATIC, KEYSET, or DYNAMIC are specified. STATIC, KEYSET, and DYNAMIC cursors default to SCROLL. Unlike database APIs such as ODBC and ADO, FORWARD_ONLY is supported with STATIC, KEYSET, and DYNAMIC Transact-SQL cursors.

STATIC

KEYSET

Specifies that the membership and order of rows in the cursor are fixed when the cursor is opened. The set of keys that uniquely identify the rows is built into a table in tempdb known as the keyset.

Note
If the query references at least one table without a unique index, the keyset cursor is converted to a static cursor.

Changes to nonkey values in the base tables, either made by the cursor owner or committed by other users, are visible as the owner scrolls around the cursor. Inserts made by other users are not visible (inserts cannot be made through a Transact-SQL server cursor). If a row is deleted, an attempt to fetch the row returns an @@FETCH_STATUS of -2. Updates of key values from outside the cursor resemble a delete of the old row followed by an insert of the new row. The row with the new values is not visible, and attempts to fetch the row with the old values return an @@FETCH_STATUS of -2. The new values are visible if the update is done through the cursor by specifying the WHERE CURRENT OF clause.

DYNAMIC

Defines a cursor that reflects all data changes made to the rows in its result set as you scroll around the cursor. The data values, order, and membership of the rows can change on each fetch. The ABSOLUTE fetch option is not supported with dynamic cursors.

FAST_FORWARD

Specifies a FORWARD_ONLY, READ_ONLY cursor with performance optimizations enabled. FAST_FORWARD cannot be specified if SCROLL or FOR_UPDATE is also specified.

Note
In SQL Server 2000, FAST_FORWARD and FORWARD_ONLY cursor options are mutually exclusive. If both are specified, an error is raised. In SQL Server 2005 and later, both keywords can be used in the same DECLARE CURSOR statement.

READ_ONLY

SCROLL_LOCKS

Specifies that positioned updates or deletes made through the cursor are guaranteed to succeed. SQL Server locks the rows as they are read into the cursor to ensure their availability for later modifications. SCROLL_LOCKS cannot be specified if FAST_FORWARD or STATIC is also specified.

OPTIMISTIC

Specifies that positioned updates or deletes made through the cursor do not succeed if the row has been updated since it was read into the cursor. SQL Server does not lock rows as they are read into the cursor. It instead uses comparisons of timestamp column values, or a checksum value if the table has no timestamp column, to determine whether the row was modified after it was read into the cursor. If the row was modified, the attempted positioned update or delete fails. OPTIMISTIC cannot be specified if FAST_FORWARD is also specified.

TYPE_WARNING

Specifies that a warning message is sent to the client when the cursor is implicitly converted from the requested type to another.

select_statement

Is a standard SELECT statement that defines the result set of the cursor. The keywords COMPUTE, COMPUTE BY, FOR BROWSE, and INTO are not allowed within select_statement of a cursor declaration.

Note
You can use a query hint within a cursor declaration; however, if you also use the FOR UPDATE OF clause, specify OPTION (query_hint) after FOR UPDATE OF.

FOR UPDATE [OF column_name [,...n]]

Defines updatable columns within the cursor. If OF column_name [,...n] is supplied, only the columns listed allow modifications. If UPDATE is specified without a column list, all columns can be updated, unless the READ_ONLY concurrency option was specified.

Remarks

DECLARE CURSOR defines the attributes of a Transact-SQL server cursor, such as its scrolling behavior and the query used to build the result set on which the cursor operates. The OPEN statement populates the result set, and FETCH returns a row from the result set. The CLOSE statement releases the current result set associated with the cursor. The DEALLOCATE statement releases the resources used by the cursor.

The first form of the DECLARE CURSOR statement uses the ISO syntax for declaring cursor behaviors. The second form of DECLARE CURSOR uses Transact-SQL extensions that allow you to define cursors using the same cursor types used in the database API cursor functions of ODBC or ADO.

You cannot mix the two forms. If you specify the SCROLL or INSENSITIVE keywords before the CURSOR keyword, you cannot use any keywords between the CURSOR and FOR select_statement keywords. If you specify any keywords between the CURSOR and FOR select_statement keywords, you cannot specify SCROLL or INSENSITIVE before the CURSOR keyword.

If a DECLARE CURSOR using Transact-SQL syntax does not specify READ_ONLY, OPTIMISTIC, or SCROLL_LOCKS, the default is as follows:

If the SELECT statement does not support updates (insufficient permissions, accessing remote tables that do not support updates, and so on), the cursor is READ_ONLY.
STATIC and FAST_FORWARD cursors default to READ_ONLY.
DYNAMIC and KEYSET cursors default to OPTIMISTIC.

Cursor names can be referenced only by other Transact-SQL statements. They cannot be referenced by database API functions. For example, after declaring a cursor, the cursor name cannot be referenced from OLE DB, ODBC or ADO functions or methods. The cursor rows cannot be fetched using the fetch functions or methods of the APIs; the rows can be fetched only by Transact-SQL FETCH statements.

After a cursor has been declared, these system stored procedures can be used to determine the characteristics of the cursor.

System stored procedures	Description
sp_cursor_list	Returns a list of cursors currently visible on the connection and their attributes.
sp_describe_cursor	Describes the attributes of a cursor, such as whether it is a forward-only or scrolling cursor.
sp_describe_cursor_columns	Describes the attributes of the columns in the cursor result set.
sp_describe_cursor_tables	Describes the base tables accessed by the cursor.

Variables may be used as part of the select_statement that declares a cursor. Cursor variable values do not change after a cursor is declared. In SQL Server version 6.5 and earlier, variable values are refreshed every time a cursor is reopened.

Permissions

DECLARE CURSOR permissions default to any user that has SELECT permissions on the views, tables, and columns used in the cursor.

Examples

A. Using simple cursor and syntax

The result set generated at the opening of this cursor includes all rows and all columns in the table. This cursor can be updated, and all updates and deletes are represented in fetches made against this cursor. FETCH NEXT is the only fetch available because the SCROLL option has not been specified.

USE AdventureWorks2008R2;

GO

DECLARE vend_cursor CURSOR

    FOR SELECT BusinessEntityID, Name, CreditRating FROM Purchasing.Vendor

OPEN vend_cursor

FETCH NEXT FROM vend_cursor;

B. Using nested cursors to produce report output

The following example shows how cursors can be nested to produce complex reports. The inner cursor is declared for each vendor.

USE AdventureWorks2008R2;

GO

SET NOCOUNT ON;

DECLARE @vendor_id int, @vendor_name nvarchar(50),

    @message varchar(80), @product nvarchar(50);

PRINT '-------- Vendor Products Report --------';

DECLARE vendor_cursor CURSOR FOR

SELECT BusinessEntityID, Name

FROM Purchasing.Vendor

WHERE PreferredVendorStatus = 1

ORDER BY BusinessEntityID;

OPEN vendor_cursor;

FETCH NEXT FROM vendor_cursor

INTO @vendor_id, @vendor_name;

WHILE @@FETCH_STATUS = 0

BEGIN

    PRINT ' ';

    SELECT @message = '----- Products From Vendor: ' +

        @vendor_name;

    PRINT @message;

    -- Declare an inner cursor based

    -- on vendor_id from the outer cursor.

    DECLARE product_cursor CURSOR FOR

    SELECT v.Name

    FROM Purchasing.ProductVendor AS pv

    INNER JOIN Production.Product AS v

        ON pv.ProductID = v.ProductID AND

           pv.BusinessEntityID = @vendor_id;  -- Variable value from the outer cursor

    OPEN product_cursor;

    FETCH NEXT FROM product_cursor INTO @product;

    IF @@FETCH_STATUS <> 0

        PRINT '         <<None>>' ;    

    WHILE @@FETCH_STATUS = 0

    BEGIN

        SELECT @message = '         ' + @product

        PRINT @message

        FETCH NEXT FROM product_cursor INTO @product;

        END;

    CLOSE product_cursor;

    DEALLOCATE product_cursor;

        -- Get the next vendor.

    FETCH NEXT FROM vendor_cursor

    INTO @vendor_id, @vendor_name;

END

CLOSE vendor_cursor;

DEALLOCATE vendor_cursor;

Reference

@@FETCH_STATUS (Transact-SQL)

CLOSE (Transact-SQL)

Cursors (Transact-SQL)

DEALLOCATE (Transact-SQL)

FETCH (Transact-SQL)

SELECT (Transact-SQL)

sp_configure (Transact-SQL)

FROM http://technet.microsoft.com/en-us/library/ms180169(v=sql.105).aspx

More code example：

Regard STATIC and Dynamic. If run below scripts for session 1 isolated, then it will give you the results as below.

   --session 1
IF OBJECT_ID('dbo.Groups') IS NOT NULL
DROP TABLE dbo.Groups;

 GO

 CREATE TABLE dbo.Groups

 (

   groupid  VARCHAR(10) NOT NULL,

   memberid INT         NOT NULL,

   string   VARCHAR(10) NOT NULL,

   val      INT         NOT NULL,

   PRIMARY KEY (groupid, memberid)

 );

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('a', 3, 'stra1', 6);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('a', 9, 'stra2', 7);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('b', 2, 'strb1', 3);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('b', 4, 'strb2', 7);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('b', 5, 'strb3', 3);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('b', 9, 'strb4', 11);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('c', 3, 'strc1', 8);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('c', 7, 'strc2', 10);

 INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('c', 9, 'strc3', 12);

 DECLARE

   @Result TABLE(groupid VARCHAR(10), product BIGINT);

 DECLARE

   @groupid AS VARCHAR(10), @prvgroupid AS VARCHAR(10),

   @val AS INT, @product AS BIGINT;

 DECLARE C CURSOR FAST_FORWARD FOR

   SELECT groupid, val FROM dbo.Groups ORDER BY groupid;

 OPEN C

 FETCH NEXT FROM C INTO @groupid, @val;

 SELECT @prvgroupid = @groupid, @product = 1;

 WHILE @@fetch_status = 0

 BEGIN

   IF @groupid > @prvgroupid

   BEGIN

     INSERT INTO @Result VALUES(@prvgroupid, @product);

     SELECT @prvgroupid = @groupid, @product = 1;

   END

   SET @product = @product * @val;

   FETCH NEXT FROM C INTO @groupid, @val;

 END

 IF @prvgroupid IS NOT NULL

   INSERT INTO @Result VALUES(@prvgroupid, @product);

 CLOSE C;

 DEALLOCATE C;

 SELECT groupid, product FROM @Result;

 GO

groupid    product

---------- --------------------

a                            42

b                           693

c                           960



drop table Groups;

GO

--session 2
-- if you start above code in debug and after open the cursor and go into the loop, then run below scripts in session 2
-- make sure the session 2 is auto committed or you commit the data manully.
-- then go back to session 1 to continue the scipts
-- you will fount the output contains data from session2.
-- that's because the cursor is default to dynamic.It is not like oralce which is read consistent by default.
-- you can declare the cursor to static to avoid this.

INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('d', 9, 'strc5', 28);
GO
INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('e', 10, 'strc7', 30);
GO
INSERT INTO dbo.Groups(groupid, memberid, string, val) VALUES('f', 10, 'strc7', 30);

FAST_FORWARD option is conflict with STATIC option, so use FORWARD_ONLY READ_ONLY STATIC to simulate the FAST_FORWARD with STATIC.

If neither GLOBAL or LOCAL is specified, the default is controlled by the setting of the Default Cursor database option.

For different version, the option name maybe various. below is a screenshot for SQLServer 2008. You can use below code to change it to LOCAL .

or just select the LOCAL from drop down.

USE [master]

GO

ALTER DATABASE [TraceAnalysis] SET CURSOR_DEFAULT LOCAL WITH NO_WAIT

GO

You can use below scripts to verify whether it is a GLOBAL cursor.If the procedure ReadCrsr can read data successfully, then it default to GLOBAL.


USE AdventureWorks2008;

GO

CREATE PROCEDURE OpenCrsr AS

DECLARE SampleCrsr CURSOR fast_forward FOR

SELECT TOP (20)LastName

FROM Person.Person

WHERE LastName LIKE 'S%';

OPEN SampleCrsr;

GO

CREATE PROCEDURE ReadCrsr AS

FETCH NEXT FROM SampleCrsr

WHILE (@@FETCH_STATUS <> -1)

BEGIN

FETCH NEXT FROM SampleCrsr

END

GO

EXEC OpenCrsr; /* DECLARES and OPENS SampleCrsr. */

GO

EXEC ReadCrsr; /* Fetches the rows from SampleCrsr. */

GO

CLOSE SampleCrsr;

GO

DEALLOCATE SampleCrsr;

GO