sp_describe_cursor (Transact-SQL)

適用対象:SQL Server

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

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 は カーソルであり、既定値は指定されず、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 は、SQLSetCursorName を呼び出して名前を付けた ODBC アプリケーションによって開かれる API サーバー カーソルの名前を指定することもできます。

[ @cursor_identity= ] N'input_cursor_variable' ]
開いているカーソルに関連付けられたカーソル変数の名前です。 input_cursor_variable は nvarchar(128)です。

リターン コードの値

なし

返されるカーソル

sp_describe_cursorは、その結果セットを Transact-SQL カーソル 出力パラメーターにカプセル化します。 これにより、Transact-SQL のバッチ、ストアド プロシージャ、およびトリガーは、一度に 1 行ずつ出力を処理できます。 これは、データベース API 関数からプロシージャを直接呼び出すことができないことも意味します。 カーソル出力パラメーターはプログラム変数にバインドする必要がありますが、データベース API ではカーソル・パラメーターまたは変数のバインドはサポートされていません。

次の表に、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 = カーソル名または変数によって参照されるカーソルが開いています。 カーソルが状態非依存、静的、キーセットのいずれかの場合には、結果セットに少なくとも 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 は、カーソルがスクロール可能かどうか、更新可能かどうかなど、サーバー カーソルのグローバルな属性を説明します。 カーソルから返された結果セットの属性の説明が必要な場合は、sp_describe_cursor_columns を使用します。 カーソルが参照するベース テーブルのレポートが必要な場合は、sp_describe_cursor_tables を使用します。 接続時に可視である Transact-SQL Server カーソルのレポートが必要な場合は、sp_cursor_list を使用します。

DECLARE CURSOR ステートメントは、DECLARE CURSOR に含まれる SELECT ステートメントを使用SQL Serverサポートできないカーソルの種類を要求する場合があります。 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  

参照

カーソル
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)