共用方式為


sp_describe_cursor (Transact-SQL)

報告伺服器資料指標的屬性。

主題連結圖示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 是 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