sp_describe_cursor (Transact-SQL)

適用対象: SQL サーバー

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

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_sourcenvarchar(30)で、既定値はありません。

[ @cursor_identity = ] N'cursor_identity'

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

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

  • カーソルに GLOBAL キーワードがある場合、または既定で GLOBAL に設定されている場合、 @cursor_identityglobal@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