sp_describe_cursor (Transact-SQL)
報告伺服器資料指標的屬性。
.gif "主題連結圖示")
語法
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 是 cursor，沒有預設值，在呼叫 sp_describe_cursor 時，不能與任何資料指標產生關聯。傳回的資料指標是一個可捲動的動態唯讀資料指標。[ @cursor_source = ] { N'local' | N'global' | N'variable' }
指定要報告的資料指標是利用本機資料指標、全域資料指標或資料指標變數的名稱來指定。參數是 nvarchar(30)。[ @cursor_identity = ] N'local_cursor_name' ]
這是可能含有 LOCAL 關鍵字或預設為 LOCAL 的 DECLARE CURSOR 陳述式所建立之資料指標的名稱。local_cursor_name 是 nvarchar(128)。[ @cursor_identity = ] N'global_cursor_name' ]
這是可能含有 GLOBAL 關鍵字或預設為 GLOBAL 的 DECLARE CURSOR 陳述式所建立之資料指標的名稱。global_cursor_name 是 nvarchar(128)。global_cursor_name 也可以是 ODBC 應用程式所開啟，再藉由呼叫 SQLSetCursorName 來命名之 API 伺服器資料指標的名稱。
[ @cursor_identity = ] N'input_cursor_variable' ]
這是與開啟的資料指標有關聯的資料指標變數名稱。input_cursor_variable 是 nvarchar(128)。
傳回碼值
無
傳回的資料指標
sp_describe_cursor 會將它的結果集封裝在 Transact-SQLcursor 輸出參數中。這會使 Transact-SQL 批次、預存程序和觸發程序能夠使用輸出，每次處理一個資料列。另外，這也表示無法直接從資料庫 API 函數呼叫程序。cursor 輸出參數必須繫結到程式變數，但資料庫 API 並不支援繫結 cursor 參數或變數。
下表顯示利用 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 = 含指定名稱的資料指標或資料指標變數不存在，或資料指標變數還沒有配置資料指標。 |
model |
tinyint |
1 = 不區分 (或靜態) 2 = 索引鍵集 3 = 動態 4 = 向前快轉 |
concurrency |
tinyint |
1 = 唯讀 2 = 捲動鎖定 3 = 開放式 |
scrollable |
tinyint |
0 = 順向 1 = 可捲動 |
open_status |
tinyint |
0 = 已關閉 1 = 開啟 |
cursor_rows |
decimal(10,0) |
結果集中符合的資料列數目。如需詳細資訊，請參閱＜@@CURSOR_ROWS (Transact-SQL)＞。 |
fetch_status |
smallint |
這個資料指標上一次提取的狀態。如需詳細資訊，請參閱＜@@FETCH_STATUS (Transact-SQL)＞。 0 = 順利提取。 -1 = 提取失敗，或超出資料指標界限。 -2 = 遺漏要求的資料列。 -9 = 資料指標尚無任何提取動作。 |
column_count |
smallint |
資料指標結果集中的資料行數目。 |
row_count |
decimal(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 AdventureWorks2008R2;
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