sp_cursoropen (Transact-SQL)
カーソルを開きます。 sp_cursoropen は、カーソルに関連付ける SQL ステートメントおよびカーソル オプションを定義してから、カーソルにデータを格納します。 sp_cursoropenは、Transact-SQL ステートメントの DECLARE_CURSOR と OPEN を組み合わせたものに相当します。 このプロシージャは、ID = 2 を指定した場合に表形式のデータ ストリーム (TDS) パケットで呼び出されます。
適用対象: SQL Server (SQL Server 2008 から現在のバージョンまで) |
構文
sp_cursoropen cursor OUTPUT, stmt
[, scrollopt [ OUTPUT ] [ , ccopt [ OUTPUT ]
[ ,rowcount OUTPUT [ ,boundparam] [,...n] ] ] ] ]
引数
cursor
SQL Server で生成されたカーソル識別子。 cursor はハンドル値であり、以降のカーソルが関係するすべてのプロシージャ (sp_cursorfetch など) で指定する必要があります。 cursor は int 戻り値と共に必須のパラメーターです。cursor を使用すると、1 つのデータベース接続で複数のカーソルをアクティブにすることができます。
stmt
カーソル結果セットを定義する必須パラメーターです。 任意の文字列型 (Unicode、サイズなど) の任意の有効なクエリ文字列 (構文およびバインド) を有効な stmt 値型として使用できます。scrollopt
スクロール オプションです。 scrollopt は省略可能なパラメーターで、次の int 入力値のいずれかを必要とします。値
説明
0x0001
KEYSET
0x0002
DYNAMIC
0x0004
FORWARD_ONLY
0x0008
STATIC
0x10
FAST_FORWARD
0x1000
PARAMETERIZED_STMT
0x2000
AUTO_FETCH
0x4000
AUTO_CLOSE
0x8000
CHECK_ACCEPTED_TYPES
0x10000
KEYSET_ACCEPTABLE
0x20000
DYNAMIC_ACCEPTABLE
0x40000
FORWARD_ONLY_ACCEPTABLE
0x80000
STATIC_ACCEPTABLE
0x100000
FAST_FORWARD_ACCEPTABLE
要求される値が stmt で定義されているカーソルに適していない可能性があるので、このパラメーターは入力と出力の両方として機能します。 このような場合は、SQL Server によって適切な値が割り当てられます。
ccopt
同時実行制御オプションです。 ccopt は省略可能なパラメーターで、次の int 入力値のいずれかを必要とします。値
説明
0x0001
READ_ONLY
0x0002
SCROLL_LOCKS (以前の LOCKCC)
0x0004
OPTIMISTIC (以前の OPTCC)
0x0008
OPTIMISTIC (以前の OPTCCVAL)
0x2000
ALLOW_DIRECT
0x4000
UPDT_IN_PLACE
0x8000
CHECK_ACCEPTED_OPTS
0x10000
READ_ONLY_ACCEPTABLE
0x20000
SCROLL_LOCKS_ACCEPTABLE
0x40000
OPTIMISTIC_ACCEPTABLE
0x80000
OPTIMISITC_ACCEPTABLE
scrollopt と同様に、要求した ccopt 値が SQL Server によって上書きされる場合があります。
rowcount
AUTO_FETCH で使用するフェッチ バッファー行の数です。 既定値は 20 行です。 rowcount は、入力値として割り当てられる場合と戻り値として割り当てられる場合とでは動作が異なります。入力値
戻り値
scrollopt AUTO_FETCH の値が指定されている場合、rowcount はフェッチ バッファーに格納される行の数を表します。
注意
>0 は、AUTO_FETCH が指定されている場合は有効ですが、その他の場合は無視されます。
scrollopt AUTO_FETCH の値が指定されている場合を除き、結果セット内の行の数を表します。
- boundparam
追加パラメーターを使用することを示します。 boundparam は省略可能なパラメーターですが、scrollopt の PARAMETERIZED_STMT の値が ON に設定されている場合は指定する必要があります。
リターン コード値
エラーが発生しなかった場合、sp_cursoropen は次のいずれかの値を返します。
0
プロシージャは正常に実行されました。0x0001
実行中にエラーが発生しました (操作がエラーにならない程度の軽度のエラー)。0x0002
非同期操作を実行中です。0x0002
FETCH 操作を実行中です。A
このカーソルは SQL Server によって割り当て解除されており、使用できません。
エラーが発生した場合は、一貫性のない値が返される可能性があるため、値の正確さは保証されません。
rowcount パラメーターが戻り値として指定された場合の結果セットを次に示します。
-1
行数が不明または適用外の場合に返されます。-n
非同期設定が有効になっている場合に返されます。 scrollopt AUTO_FETCH の値が指定されている場合、フェッチ バッファーに格納された行の数を表します。
RPC が使用されている場合の戻り値を次に示します。
0
プロシージャは成功しました。1
プロシージャは失敗しました。2
キーセット カーソルが非同期に生成されています。16
高速順方向カーソルが自動的に閉じられました。
注意
sp_cursoropen プロシージャの実行が成功すると、RPC の戻りパラメーターと TDS の列形式の情報 (0xa0 メッセージと 0xa1 メッセージ) を含む結果セットが送信されます。失敗した場合は、1 つ以上の TDS エラー メッセージが送信されます。いずれの場合も、行データは返されず、done メッセージのカウントは 0 になります。7.0 より前のバージョンの SQL Server を使用している場合は、0xa0 と 0xa1 (SELECT ステートメントの標準) が 0xa5 および 0xa4 のトークン ストリームと共に返されます。SQL Server 7.0 を使用している場合は、0x81 (SELECT ステートメントの標準) が 0xa5 および 0xa4 のトークン ストリームと共に返されます。
説明
stmt パラメーター
stmt でストアド プロシージャの実行を指定する場合、入力パラメーターは、stmt の文字列の中で定数として定義することも、boundparam 引数として指定することもできます。 これにより、宣言された変数を、バインドされたパラメーターとして渡すことができます。
stmt パラメーターで使用できる内容は、次のように、ccopt の戻り値 ALLOW_DIRECT が残りの ccopt 値と OR で結合されているかどうかによって異なります。
ALLOW_DIRECT が指定されていない場合は、単一の SELECT ステートメントを含むストアド プロシージャを要求する Transact-SQL SELECT ステートメントまたは EXECUTE ステートメントを使用する必要があります。 その SELECT ステートメントがカーソルの条件を満たしている必要もあります (キーワード SELECT INTO または FOR BROWSE を含むことができません)。
ALLOW_DIRECT が指定されている場合は、1 つ以上の Transact-SQL ステートメント (複数のステートメントを含む他のストアド プロシージャを実行するものを含む) が実行される可能性があります。 SELECT 以外のステートメントや、キーワード SELECT INTO または FOR BROWSE を含む SELECT ステートメントは、単純に実行され、カーソルは作成されません。 複数のステートメントのバッチに含まれている SELECT ステートメントについても同様です。 カーソルのみに関連する句が SELECT ステートメントに含まれている場合、それらの句は無視されます。 たとえば、ccopt の値が 0x2002 の場合は、次のいずれかが要求されます。
スクロール ロックを使用するカーソル (カーソルの条件を満たしている単一の SELECT ステートメントだけがある場合)。
ステートメントの直接実行 (複数のステートメントがある場合、SELECT 以外の単一のステートメントがある場合、またはカーソルの条件を満たしていない SELECT ステートメントがある場合)。
scrollopt パラメーター
scrollopt の最初の 5 つの値 (KEYSEY、DYNAMIC、FORWARD_ONLY、STATIC、および FAST_FORWARD) は、同時に指定できません。
PARAMETERIZED_STMT と CHECK_ACCEPTED_TYPES は、最初の 5 つの値と OR で結合できます。
AUTO_FETCH と AUTO_CLOSE は、FAST_FORWARD と OR で結合できます。
CHECK_ACCEPTED_TYPES が ON の場合は、scrollopt の最後の 5 つの値 (KEYSET_ACCEPTABLE、DYNAMIC_ACCEPTABLE、FORWARD_ONLY_ACCEPTABLE、STATIC_ACCEPTABLE、または FAST_FORWARD_ACCEPTABLE) の少なくとも 1 つが ON である必要があります。
STATIC カーソルは常に READ_ONLY として開かれます。 したがって、このカーソルを使用して基になるテーブルを更新することはできません。
ccopt パラメーター
ccopt の最初の 4 つの値 (READ_ONLY、SCROLL_LOCKS、および 2 つの OPTIMISTIC 値) は、同時に指定できません。
注意
ccopt の最初の 4 つの値のどれを選択するかによって、カーソルを読み取り専用にするかどうかや、更新データの喪失を防ぐためにロックやオプティミスティックの方法を使用するかどうかが決まります。ccopt の値を指定しない場合の既定値は OPTIMISTIC です。
ALLOW_DIRECT と CHECK_ACCEPTED_TYPES は、最初の 4 つの値と OR で結合できます。
UPDT_IN_PLACE は、READ_ONLY、SCROLL_LOCKS、またはいずれかの OPTIMISTIC 値と OR で結合できます。
CHECK_ACCEPTED_TYPES が ON の場合は、ccopt の最後の 4 つの値 (READ_ONLY_ACCEPTABLE、SCROLL_LOCKS_ACCEPTABLE、またはいずれかの OPTIMISTIC_ACCEPTABLE 値) の少なくとも 1 つが ON である必要があります。
位置指定の UPDATE 関数と DELETE 関数は、フェッチ バッファー内でのみ実行できます。そのとき、ccopt の値が SCROLL_LOCKS または OPTIMISTIC である必要もあります。 指定されている値が SCROLL_LOCKS の場合は、操作が成功することが保証されます。 指定されている値が OPTIMISTIC の場合は、行が最後にフェッチされてから変更されている場合には操作が失敗します。
指定されている値が OPTIMISTIC の場合に操作が失敗することがあるのは、タイムスタンプかチェックサム値 (SQL Server によって決定されます) を比較することによってオプティミスティック同時実行制御機能が実行されるためです。 一致しない行があると操作が失敗します。
戻り値として UPDT_IN_PLACE を指定すると、結果を次のように制御できます。
一意インデックスを持つテーブルで位置指定更新を実行するときに UPDT_IN_PLACE を設定しないと、その行がカーソルの作業テーブルから削除されて、カーソルによって使用されているキー列の末尾に挿入されます。その結果、それらの列が変更されます。
UPDT_IN_PLACE を ON に設定すると、単純に作業テーブルの元の行でキー列が更新されます。
bound_param パラメーター
PARAMETERIZED_STMT が指定されている場合は、コード内でのエラー メッセージに従って、パラメーター名を paramdef にする必要があります。 PARAMETERIZED_STMT が指定されていない場合は、エラー メッセージで名前は指定されません。
RPC に関する考慮事項
RPC の RETURN_METADATA 入力フラグを 0x0001 に設定すると、カーソル選択リストのメタデータを TDS ストリームで返すように要求できます。
使用例
bound_param パラメーター
5 番目より後のパラメーターは、入力パラメーターとしてステートメント プランに渡されます。 それらのパラメーターのうちの最初のパラメーターは、次の形式の文字列にする必要があります。
{ local variable name data type } [,…n]
後続のパラメーターは、ステートメント内の local variable name の代わりに使用する値を渡すために使用されます。
関連項目
参照
- boundparam