sp_describe_cursor （Transact-SQL）

適用於：SQL Server

報表服務器資料指標的屬性。

Transact-SQL 語法慣例

語法

  
sp_describe_cursor [ @cursor_return = ] output_cursor_variable OUTPUT   
     { [ , [ @cursor_source = ] N'local'  
    , [ @cursor_identity = ] N'local_cursor_name' ]   
   | [ , [ @cursor_source = ] N'global'  
    , [ @cursor_identity = ] N'global_cursor_name' ]   
   | [ , [ @cursor_source = ] N'variable'  
     , [ @cursor_identity = ] N'input_cursor_variable' ]   
     }   
[;]  

引數

[ @cursor_return= ] output_cursor_variable OUTPUT
這是要接收資料指標輸出的宣告資料指標變數名稱。 output_cursor_variable 是 資料指標 ，沒有預設值，而且在呼叫sp_describe_cursor時不得與任何資料指標產生關聯。 傳回的資料指標是可捲動的動態唯讀資料指標。

[ @cursor_source= ] { N'local' |N'global' |N'variable' }
指定所報告的資料指標是使用本機資料指標、全域資料指標或資料指標變數的名稱來指定。 參數為 Nvarchar（30） 。

[ @cursor_identity= ] N'local_cursor_name ' ]
這是 DECLARE CURSOR 語句所建立的資料指標名稱，該語句具有 LOCAL 關鍵字或預設為 LOCAL。 local_cursor_name是 Nvarchar（128） 。

[ @cursor_identity= ] N'global_cursor_name ' ]
這是 DECLARE CURSOR 語句所建立的資料指標名稱，該語句具有 GLOBAL 關鍵字或預設為 GLOBAL。 global_cursor_name 是 Nvarchar（128） 。

global_cursor_name 也可以是由 ODBC 應用程式開啟的 API 伺服器資料指標名稱，然後藉由呼叫 SQLSetCursorName 來命名。

[ @cursor_identity= ] N'input_cursor_variable ' ]
這是與開啟的資料指標相關聯的資料指標變數名稱。 input_cursor_variable是 Nvarchar（128） 。

傳回碼值

無

傳回的資料指標

sp_describe_cursor將其結果集封裝在 Transact-SQL 資料指標 輸出參數中。 這可讓 Transact-SQL 批次、預存程式和觸發程式一次處理一個資料列。 這也表示無法直接從資料庫 API 函式呼叫程式。 資料 指標 輸出參數必須系結至程式變數，但資料庫 API 不支援系結 資料指標 參數或變數。

下表顯示使用 sp_describe_cursor 傳回的資料指標格式。 資料指標的格式與使用 sp_cursor_list 傳回的格式相同。

資料行名稱	資料類型	描述
reference_name	sysname	用來參考資料指標的名稱。 如果資料指標的參考是透過 DECLARE CURSOR 語句上指定的名稱，則參考名稱與資料指標名稱相同。 如果資料指標的參考是透過變數，則參考名稱是變數的名稱。
cursor_name	sysname	DECLARE CURSOR 語句中的資料指標名稱。 在 SQL Server 中，如果資料指標是藉由將資料指標變數設定為數據指標來建立，cursor_name會傳回資料指標變數的名稱。 在舊版的 SQL Server 中，此輸出資料行會傳回系統產生的名稱。
cursor_scope	tinyint	1 = LOCAL 2 = GLOBAL
status	int	與CURSOR_STATUS系統函式所報告的相同值： 1 = 資料指標名稱或變數所參考的資料指標已開啟。 如果資料指標不區分、靜態或索引鍵集，則至少有一個資料列。 如果資料指標是動態的，結果集就會有零個或多個資料列。 0 = 資料指標名稱或變數所參考的資料指標已開啟，但沒有資料列。 動態資料指標永遠不會傳回此值。 -1 = 資料指標名稱或變數所參考的資料指標已關閉。 -2 = 僅適用于資料指標變數。 沒有指派給變數的資料指標。 可能，OUTPUT 參數會將資料指標指派給變數，但預存程式會在傳回之前關閉資料指標。 -3 = 具有指定名稱的資料指標或資料指標變數不存在，或者資料指標變數沒有配置給它的資料指標。
機型	tinyint	1 = 不區分（或靜態） 2 = 索引鍵集 3 = 動態 4 = 快速向前
concurrency	tinyint	1 = 唯讀 2 = 捲動鎖定 3 = 開放式
滾動	tinyint	0 = 正向 1 = 可捲動
open_status	tinyint	0 = 已關閉 1 = 開啟
cursor_rows	十進位（10，0）	結果集中合格資料列的數目。 如需詳細資訊，請參閱 @@CURSOR_ROWS （Transact-SQL） 。
fetch_status	smallint	此資料指標上最後一次擷取的狀態。 如需詳細資訊，請參閱 @@FETCH_STATUS (Transact-SQL)。 0 = 擷取成功。 -1 = 擷取失敗，或超出資料指標的範圍。 -2 = 遺漏要求的資料列。 -9 = 資料指標上沒有擷取。
column_count	smallint	資料指標結果集中的資料行數目。
row_count	十進位（10，0）	資料指標上最後一個作業所影響的資料列數目。 如需詳細資訊，請參閱 @@ROWCOUNT (Transact-SQL)。
last_operation	tinyint	在資料指標上執行的最後一個作業： 0 = 資料指標上未執行任何作業。 1 = OPEN 2 = FETCH 3 = INSERT 4 = UPDATE 5 = DELETE 6 = CLOSE 7 = 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 語句，以隱含方式將游標轉換成它可支援的類型。 如果在 DECLARE CURSOR 語句中指定了TYPE_WARNING，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  

另請參閱

游標
CURSOR_STATUS (Transact-SQL)
DECLARE CURSOR (Transact-SQL)
sp_cursor_list （Transact-SQL）
sp_describe_cursor_columns （Transact-SQL）
sp_describe_cursor_tables （Transact-SQL）