次の方法で共有


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 キーワードを指定した DECLARE CURSOR ステートメント、または既定値が LOCAL になっている DECLARE CURSOR ステートメントによって作成されたカーソルの名前を指定します。local_cursor_name のデータ型は nvarchar(128) です。

[ @cursor_identity = ] N'global_cursor_name' ]

GLOBAL キーワードを指定した DECLARE CURSOR ステートメント、または既定値が GLOBAL になっている DECLARE CURSOR ステートメントによって作成されたカーソルの名前を指定します。global_cursor_name のデータ型は nvarchar(128) です。

global_cursor_name には、ODBC アプリケーションによってオープンされた API サーバー カーソルの名前も指定できます。この ODBC アプリケーションでは、SQLSetCursorName を呼び出すことによってカーソルが指定されます。

[ @cursor_identity = ] N'input_cursor_variable' ]

オープン カーソルに関連付けられたカーソル変数の名前を指定します。input_cursor_variable のデータ型は nvarchar(128) です。

解説

sp_describe_cursor は、カーソルがスクロール可能かどうか、更新可能かどうかなど、サーバー カーソルのグローバルな属性を説明します。カーソルから返された結果セットの属性の説明が必要な場合は、sp_describe_cursor_columns を使用します。カーソルが参照するベース テーブルのレポートが必要な場合は、sp_describe_cursor_tables を使用します。接続時に可視である Transact-SQL Server カーソルのレポートが必要な場合は、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 は、その結果セットを 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 ステートメントに指定されたカーソルの名前です。SQL Server 2005 では、カーソル変数の設定によってカーソルが作成されると、cursor_name にカーソル変数の名前が返されます。以前のバージョンの SQL Server では、この出力列にはシステムが生成した名前が返されていました。

cursor_scope

tinyint

1 = ローカル

2 = グローバル

status

int

CURSOR_STATUS システム関数によってレポートされたものと同じ値です。

1 = カーソル名または変数によって参照されたカーソルはオープンされています。カーソルが状態非依存、静的、キーセットのいずれかの場合には、結果セットに少なくとも 1 行が含まれます。カーソルが動的の場合には、結果セットに 0 行以上が含まれます。

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 を使用してカーソルの属性をレポートします。

USE AdventureWorks;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR STATIC FOR
SELECT LastName
FROM Person.Contact

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)

その他の技術情報

カーソル (データベース エンジン)

ヘルプおよび情報

SQL Server 2005 の参考資料の入手