sp_describe_cursor （Transact-SQL）
適用於：
SQL Server
報告伺服器數據指標的屬性。
語法
sp_describe_cursor
[ @cursor_return = ] cursor_return OUTPUT
, [ @cursor_source = ] { N'local' | N'global' | N'*cursor_source*' }
, [ @cursor_identity = ] N'cursor_identity'
[ ; ]
引數
[ @cursor_return = ] cursor_return OUTPUT
要接收數據指標輸出之宣告數據指標變數的名稱。 @cursor_return是int類型的 OUTPUT 參數，沒有預設值，而且在呼叫時sp_describe_cursor不得與任何數據指標相關聯。 傳回的數據指標是可捲動的動態只讀數據指標。
[ @cursor_source = ] { N'local' |N'global' |N'cursor_source' }
指定所報告的數據指標是使用本機數據指標、全域數據指標或數據指標變數的名稱來指定。 @cursor_source為 nvarchar（30），沒有預設值。
[ @cursor_identity = ] N'cursor_identity'
語句所 DECLARE CURSOR 建立之數據指標的名稱。 @cursor_identity為 nvarchar（128），沒有預設值。
如果 cursor 具有
LOCAL關鍵字，或預設為LOCAL， @cursor_identity 為local。如果 cursor 具有
GLOBAL關鍵字，或預設為GLOBAL， @cursor_identity 為global。 @cursor_identity也可以是 ODBC 應用程式開啟的 API 伺服器資料指標名稱，然後藉由呼叫SQLSetCursorName來命名。否則， @cursor_identity 是與開啟數據指標相關聯的數據指標變數名稱。
傳回碼值
無。
傳回的數據指標
sp_describe_cursor 在 Transact-SQL cursor 輸出參數中封裝其結果集。 這可讓 Transact-SQL 批次、預存程式和觸發程式一次處理一個數據列。 這也表示無法直接從資料庫 API 函式呼叫程式。 cursor輸出參數必須係結至程式變數，但資料庫 API 不支援係結cursor參數或變數。
下表顯示使用 sp_describe_cursor傳回的數據指標格式。 數據指標的格式與使用 sp_cursor_list所傳回的格式相同。
| 資料行名稱 | 資料類型 | 描述 |
|---|---|---|
reference_name |
sysname | 用來參考數據指標的名稱。 如果數據指標的參考是透過語句上 DECLARE CURSOR 指定的名稱，則參考名稱與數據指標名稱相同。 如果數據指標的參考是透過變數，則參考名稱是變數的名稱。 |
cursor_name |
sysname | 語句 DECLARE CURSOR 中的數據指標名稱。 如果數據指標是藉由將數據指標變數設定為數據指標所建立， cursor_name 則傳回數據指標變數的名稱。 在舊版的 SQL Server 中，此輸出數據行會傳回系統產生的名稱。 |
cursor_scope |
tinyint | 1 = LOCAL2 = GLOBAL |
status |
int | 與系統函式所 CURSOR_STATUS 報告的相同值：1 = 資料指標名稱或變數所參考的數據指標已開啟。 如果數據指標不區分、靜態或索引鍵集，則至少有一個數據列。 如果數據指標是動態的，結果集就會有零個或多個數據列。0 = 數據指標名稱或變數所參考的數據指標已開啟，但沒有數據列。 動態數據指標永遠不會傳回此值。-1 = 資料指標名稱或變數所參考的數據指標已關閉。-2 = 僅適用於數據指標變數。 沒有指派給變數的數據指標。 可能， OUTPUT 參數會將數據指標指派給 變數，但預存程式會在傳回之前關閉數據指標。-3 = 具有指定名稱的數據指標或數據指標變數不存在，或數據指標變數沒有配置給它的數據指標。 |
model |
tinyint | 1 = 不區分大小寫 （或靜態）2 = 索引鍵集3 = 動態4 = 快速向前 |
concurrency |
tinyint | 1 = 唯讀2 = 捲動鎖定3 = 開放式 |
scrollable |
tinyint | 0 = 僅轉寄1 = 可捲動 |
open_status |
tinyint | 0 = 已關閉1 = 開啟 |
cursor_rows |
十進位（10,0） | 結果集中合格數據列的數目。 如需詳細資訊，請參閱 @@CURSOR_ROWS。 |
fetch_status |
smallint | 此數據指標上最後一次擷取的狀態。 如需詳細資訊，請參閱 @@FETCH_STATUS。0 = 擷取成功。-1 = 擷取失敗或超出數據指標的範圍。-2 = 遺漏要求的數據列。-9 = 資料指標上沒有發生擷取。 |
column_count |
smallint | 數據指標結果集中的數據行數目。 |
row_count |
十進位（10,0） | 數據指標上最後一個作業所影響的數據列數目。 如需詳細資訊，請參閱 @@ROWCOUNT。 |
last_operation |
tinyint | 在資料指標上執行的最後一個作業：0 = 資料指標上未執行任何作業。1 = OPEN2 = FETCH3 = INSERT4 = UPDATE5 = DELETE6 = CLOSE7 = DEALLOCATE |
cursor_handle |
int | 伺服器範圍內數據指標的唯一值。 |
備註
sp_describe_cursor 描述伺服器數據指標的全域屬性，例如卷動和更新的能力。 用於 sp_describe_cursor_columns 數據指標所傳回結果集屬性的描述。 用於 sp_describe_cursor_tables 數據指標所參考之基表的報表。 若要取得連接上可見的 Transact-SQL 伺服器資料指標報表，請使用 sp_cursor_list。
DECLARE CURSOR語句可能會要求 SQL Server 無法使用 包含在中的 DECLARE CURSOR語句來SELECT要求數據指標類型。 SQL Server 會隱含地將游標轉換成可以使用 語句支援的 SELECT 型別。 如果在 TYPE_WARNING 語句中 DECLARE CURSOR 指定，SQL Server 會傳送應用程式資訊訊息，指出轉換已完成。 sp_describe_cursor 然後可以呼叫 來判斷已實作的數據指標類型。
權限
需要 public 角色的成員資格。
範例
下列範例會開啟全域數據指標，並使用 sp_describe_cursor 來報告數據指標的屬性。
USE AdventureWorks2022;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR STATIC FOR
SELECT LastName
FROM Person.Person;
OPEN abc;
-- Declare a cursor variable to hold the cursor output variable
-- from sp_describe_cursor.
DECLARE @Report CURSOR;
-- Execute sp_describe_cursor into the cursor variable.
EXEC master.dbo.sp_describe_cursor
@cursor_return = @Report OUTPUT,
@cursor_source = N'global',
@cursor_identity = N'abc';
-- Fetch all the rows from the sp_describe_cursor output cursor.
FETCH NEXT from @Report;
WHILE (@@FETCH_STATUS <> -1)
BEGIN
FETCH NEXT from @Report;
END
-- Close and deallocate the cursor from sp_describe_cursor.
CLOSE @Report;
DEALLOCATE @Report;
GO
-- Close and deallocate the original cursor.
CLOSE abc;
DEALLOCATE abc;
GO