sp_describe_cursor (Transact-SQL)

適用対象: SQL Server

サーバー カーソルの属性を報告します。

Transact-SQL 構文表記規則

構文

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' }

レポート対象のカーソルを、 local カーソル、 global カーソル、またはカーソル変数の名前を使用して指定するかどうかを指定します。 @cursor_source は nvarchar(30)で、既定値はありません。

[ @cursor_identity = ] N'cursor_identity'

DECLARE CURSOR ステートメントによって作成されたカーソルの名前。 @cursor_identity は nvarchar(128)で、既定値はありません。

• カーソルに LOCAL キーワードがある場合、または既定で LOCAL に設定されている場合、 @cursor_identity は local。

• カーソルに GLOBAL キーワードがある場合、または既定で GLOBAL に設定されている場合、 @cursor_identity は global。 @cursor_identity ODBC アプリケーションによって開かれた API サーバー カーソルの名前を指定し、 SQLSetCursorNameを呼び出すことによって名前を付けることもできます。

• それ以外の場合、 @cursor_identity は、開いているカーソルに関連付けられているカーソル変数の名前です。

リターン コードの値

なし。

返されるカーソル

sp_describe_cursor は、その結果セットを Transact-SQL cursor 出力パラメーターにカプセル化します。 これにより、Transact-SQL のバッチ、ストアド プロシージャ、およびトリガーは、一度に 1 行ずつ出力を操作できます。 これは、データベース 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 = LOCAL 2 = GLOBAL
status	int	CURSOR_STATUS システム関数によって報告される値と同じです。 1 = カーソル名または変数によって参照されるカーソルが開いています。 カーソルが非依存、静的、またはキーセットの場合は、少なくとも 1 行です。 カーソルが動的な場合、結果セットには 0 行以上の行があります。 0 = カーソル名または変数によって参照されるカーソルは開いていますが、行がありません。 動的カーソルがこの値を返すことはありません。 -1 = カーソル名または変数によって参照されるカーソルが閉じられます。 -2 = カーソル変数にのみ適用されます。 変数にカーソルが割り当てされていません。 場合によっては、 OUTPUT パラメーターによって変数にカーソルが割り当てられたが、ストアド プロシージャは、戻る前にカーソルを閉じた。 -3 = 指定した名前のカーソルまたはカーソル変数が存在しないか、カーソル変数にカーソルが割り当てられません。
model	tinyint	1 = 非依存 (または静的) 2 = Keyset 3 = 動的 4= 早送り
concurrency	tinyint	1 = 読み取り専用 2 = スクロール ロック 3 = オプティミスティック
scrollable	tinyint	0 = 前方のみ 1 = スクロール可能
open_status	tinyint	0 = Closed 1 = 開く
cursor_rows	decimal(10,0)	結果セット内の修飾行の数。 詳細については、「 @@CURSOR_ROWS」を参照してください。
fetch_status	smallint	このカーソルの最後のフェッチの状態。 詳細については、「 @@FETCH_STATUS」を参照してください。 0 = フェッチに成功しました。 -1 = フェッチに失敗したか、カーソルの境界を超えています。 -2 = 要求された行がありません。 -9 = カーソルでフェッチが行われません。
column_count	smallint	カーソル結果セット内の列数。
row_count	decimal(10,0)	カーソルに対する最後の操作の影響を受ける行数。 詳細については、 @@ROWCOUNTを参照してください。
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

関連するコンテンツ

• カーソル (SQL Server)
• 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)