Skip to content

Commit c67b570

Browse files
rwestMSFTrwestMSFT
authored
Refresh CURSOR_STATUS (UUF 431910) (#34335)
1 parent 9be6823 commit c67b570

File tree

1 file changed

+93
-87
lines changed

1 file changed

+93
-87
lines changed

‎docs/t-sql/functions/cursor-status-transact-sql.md

Lines changed: 93 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
22
title: "CURSOR_STATUS (Transact-SQL)"
3-
description: "CURSOR_STATUS (Transact-SQL)"
3+
description: CURSOR_STATUS shows whether or not a cursor declaration has returned a cursor and result set.
44
author: markingmyname
55
ms.author: maghan
6-
ms.date: "07/24/2017"
6+
ms.reviewer: randolphwest
7+
ms.date: 06/05/2025
78
ms.service: sql
89
ms.subservice: t-sql
910
ms.topic: reference
@@ -18,107 +19,112 @@ dev_langs:
1819
- "TSQL"
1920
---
2021
# CURSOR_STATUS (Transact-SQL)
22+
2123
[!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance](../../includes/applies-to-version/sql-asdb-asdbmi.md)]
2224

2325
For a given parameter, `CURSOR_STATUS` shows whether or not a cursor declaration has returned a cursor and result set.
24-
26+
2527
:::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: [Transact-SQL syntax conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
26-
27-
## Syntax
28-
28+
29+
## Syntax
30+
2931
```syntaxsql
30-
CURSOR_STATUS
31-
(
32-
{ 'local' , 'cursor_name' }
33-
| { 'global' , 'cursor_name' }
34-
| { 'variable' , 'cursor_variable' }
35-
)
36-
```
37-
32+
CURSOR_STATUS
33+
(
34+
{ 'local' , 'cursor_name' }
35+
| { 'global' , 'cursor_name' }
36+
| { 'variable' , 'cursor_variable' }
37+
)
38+
```
39+
3840
## Arguments
39-
'local'
40-
Specifies a constant indicating that the cursor source is a local cursor name.
41-
42-
'*cursor_name*'
43-
The name of the cursor. A cursor name must conform to the [database identifier rules](../../relational-databases/databases/database-identifiers.md).
44-
45-
'global'
46-
Specifies a constant indicating that the source of the cursor is a global cursor name.
47-
48-
'variable'
41+
42+
#### 'local'
43+
44+
Specifies a constant indicating that the cursor source is a [local cursor](../language-elements/declare-cursor-transact-sql.md#local).
45+
46+
- **'*cursor_name*'**
47+
48+
The name of the cursor. A cursor name must conform to the [database identifier rules](../../relational-databases/databases/database-identifiers.md).
49+
50+
#### 'global'
51+
52+
Specifies a constant indicating that the source of the cursor is a [global cursor](../language-elements/declare-cursor-transact-sql.md#global).
53+
54+
#### 'variable'
55+
4956
Specifies a constant indicating that the source of the cursor is a local variable.
50-
51-
'*cursor_variable*'
52-
The name of the cursor variable. A cursor variable must be defined using the **cursor** data type.
53-
57+
58+
- **'*cursor_variable*'**
59+
60+
The name of the cursor variable. A cursor variable must be defined using the **cursor** data type.
61+
5462
## Return types
63+
5564
**smallint**
56-
57-
|Return value|Cursor name|Cursor variable|
58-
|---|---|---|
59-
|1|The cursor result set has at least one row.<br /><br /> For insensitive and keyset cursors, the result set has at least one row.<br /><br /> For dynamic cursors, the result set can have zero, one, or more rows.|The cursor allocated to this variable is open.<br /><br /> For insensitive and keyset cursors, the result set has at least one row.<br /><br /> For dynamic cursors, the result set can have zero, one, or more rows.|
60-
|0|The cursor result set is empty.*|The cursor allocated to this variable is open, but the result set is definitely empty.*|
61-
|-1|The cursor is closed.|The cursor allocated to this variable is closed.|
62-
|-2|Not applicable.|Has one of these possibilities:<br /><br /> The previously called procedure did not assign a cursor to this OUTPUT variable.<br /><br /> The previously assigned procedure assigned a cursor to this OUTPUT variable, but the cursor was in a closed state when the procedure completed. Therefore, the cursor is deallocated, and not returned to the calling procedure.<br /><br /> No cursor is assigned to the declared cursor variable.|
63-
|-3|A cursor with the specified name does not exist.|A cursor variable with the specified name does not exist, or if one exists, no cursor is yet allocated to it.|
64-
65-
*Dynamic cursors never return this result.
66-
67-
## Examples
65+
66+
| Return value | Cursor name | Cursor variable |
67+
| --- | --- | --- |
68+
| `1` | The cursor result set has at least one row.<br /><br />For insensitive and keyset cursors, the result set has at least one row.<br /><br />For dynamic cursors, the result set can have zero, one, or more rows. | The cursor allocated to this variable is open.<br /><br />For insensitive and keyset cursors, the result set has at least one row.<br /><br />For dynamic cursors, the result set can have zero, one, or more rows. |
69+
| `0` | The cursor result set is empty. <sup>1</sup> | The cursor allocated to this variable is open, but the result set is definitely empty.* |
70+
| `-1` | The cursor is closed. | The cursor allocated to this variable is closed. |
71+
| `-2` | Not applicable. | Has one of these possibilities:<br /><br />The previously called procedure didn't assign a cursor to this `OUTPUT` variable.<br /><br />The previously assigned procedure assigned a cursor to this `OUTPUT` variable, but the cursor was in a closed state when the procedure completed. Therefore, the cursor is deallocated, and not returned to the calling procedure.<br /><br />No cursor is assigned to the declared cursor variable. |
72+
| `-3` | A cursor with the specified name doesn't exist. | A cursor variable with the specified name doesn't exist, or if one exists, no cursor is yet allocated to it. |
73+
74+
<sup>1</sup> Dynamic cursors never return this result.
75+
76+
## Examples
77+
6878
This example uses the `CURSOR_STATUS` function to show the status of a cursor, after its declaration, after it opens, and after it closes.
69-
79+
7080
```sql
71-
CREATE TABLE #TMP
72-
(
73-
ii INT
74-
)
75-
GO
76-
77-
INSERT INTO #TMP(ii) VALUES(1)
78-
INSERT INTO #TMP(ii) VALUES(2)
79-
INSERT INTO #TMP(ii) VALUES(3)
80-
81-
GO
82-
83-
--Create a cursor.
84-
DECLARE cur CURSOR
85-
FOR SELECT * FROM #TMP
86-
87-
--Display the status of the cursor before and after opening
88-
--closing the cursor.
89-
90-
SELECT CURSOR_STATUS('global','cur') AS 'After declare'
91-
OPEN cur
92-
SELECT CURSOR_STATUS('global','cur') AS 'After Open'
93-
CLOSE cur
94-
SELECT CURSOR_STATUS('global','cur') AS 'After Close'
95-
96-
--Remove the cursor.
97-
DEALLOCATE cur
98-
99-
--Drop the table.
100-
DROP TABLE #TMP
101-
102-
```
103-
104-
[!INCLUDE[ssResult](../../includes/ssresult-md.md)]
105-
81+
CREATE TABLE #TMP (ii INT);
82+
GO
83+
84+
INSERT INTO #TMP (ii) VALUES (1);
85+
INSERT INTO #TMP (ii) VALUES (2);
86+
INSERT INTO #TMP (ii) VALUES (3);
87+
GO
88+
89+
-- Create a cursor
90+
DECLARE cur CURSOR
91+
FOR SELECT * FROM #TMP;
92+
93+
-- Display the status of the cursor before and after opening
94+
-- and closing the cursor
95+
96+
SELECT CURSOR_STATUS('global', 'cur') AS 'After declare';
97+
98+
OPEN cur;
99+
SELECT CURSOR_STATUS('global', 'cur') AS 'After Open';
100+
101+
CLOSE cur;
102+
SELECT CURSOR_STATUS('global', 'cur') AS 'After Close';
103+
104+
-- Remove the cursor.
105+
DEALLOCATE cur;
106+
107+
-- Drop the table.
108+
DROP TABLE #TMP;
106109
```
110+
111+
[!INCLUDE [ssResult](../../includes/ssresult-md.md)]
112+
113+
```output
107114
After declare
108115
---------------
109-
-1
110-
116+
-1
117+
111118
After Open
112119
----------
113-
1
114-
120+
1
121+
115122
After Close
116123
-----------
117124
-1
118-
```
119-
120-
## See also
121-
[Cursor Functions &#40;Transact-SQL&#41;](../../t-sql/functions/cursor-functions-transact-sql.md)
122-
[Data Types &#40;Transact-SQL&#41;](../../t-sql/data-types/data-types-transact-sql.md)
123-
124-
125+
```
126+
127+
## Related content
128+
129+
- [Cursor Functions (Transact-SQL)](cursor-functions-transact-sql.md)
130+
- [Data types (Transact-SQL)](../data-types/data-types-transact-sql.md)

0 commit comments

Comments
 (0)