sp_cursoropen (Transact-SQL)
適用対象: 
SQL Server
カーソルを開きます。 sp_cursoropen では、カーソルとカーソルのオプションに関連付けられている SQL ステートメントを定義し、カーソルを設定します。 sp_cursoropen は、Transact-SQL ステートメントの DECLARE_CURSOR と OPENの組み合わせと同じです。 このプロシージャは、表形式データ ストリーム (TDS) パケットの ID = 2 を指定することによって呼び出されます。
構文
sp_cursoropen cursor OUTPUT
, stmt
[ , scrollopt [ OUTPUT ]
[ , ccopt [ OUTPUT ]
[ , rowcount OUTPUT [ , boundparam ] [ , ...n ] ] ] ]
[ ; ]
引数
cursor
SQL Server で生成されたカーソル識別子。 cursor は handle 値であり、 sp_cursorfetchなど、カーソルに関連するすべての後続のプロシージャで指定する必要があります。 cursor パラメーターは int であり、NULLすることはできません。
cursor を使用すると、1 つのデータベース接続で複数のカーソルをアクティブにすることができます。
stmt
カーソル結果セットを定義する必須パラメーター。 任意の文字列型 (Unicode、サイズなどに関係なく) の有効なクエリ文字列 (構文とバインド) は、有効な stmt 値型として機能できます。
scrollopt
スクロール オプションです。 scrollopt パラメーターは int で、既定値は NULL で、次のいずれかの値を指定できます。
| 値 | 説明 |
|---|---|
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と同様に、SQL Server は要求された ccopt 値をオーバーライドできます。
rowcount
AUTO_FETCHで使用するフェッチ バッファー行の数。 既定値は 20 行です。 rowcount は、入力値と戻り値として割り当てられた場合の動作が異なります。
| 入力値として | 戻り値として |
|---|---|
AUTO_FETCH scrollopt値を指定すると、rowcountはフェッチ バッファーに配置する行数を表します。注: > 0 は、 AUTO_FETCH が指定されている場合は有効な値ですが、それ以外の場合は無視されます。 |
scrollopt AUTO_FETCH値が指定されている場合を除き、結果セット内の行数を表します。 |
boundparam
追加パラメーターの使用を示します。 boundparam は、 scrollopt PARAMETERIZED_STMT 値が ONに設定されている場合に指定する必要がある省略可能なパラメーターです。
リターン コードの値
エラーが発生しない場合、 sp_cursoropen は次のいずれかの値を返します。
| 値 | 説明 |
|---|---|
0 |
プロシージャが正常に実行されました。 |
0x0001 |
実行中にエラーが発生しました (マイナー エラーであり、操作でエラーを発生させるほど重大ではありません)。 |
0x0002 |
非同期操作が進行中です。 |
0x0002 |
FETCH操作が処理中です。 |
A |
このカーソルの割り当てが解除され、使用できません。 |
エラーが発生すると、戻り値に一貫性がなく、精度が保証されない可能性があります。
戻り値として rowcount パラメーターを指定すると、次の結果セットが発生します。
| 値 | 説明 |
|---|---|
-1 |
行数が不明または適用外の場合に返されます。 |
-n |
非同期設定が有効になっている場合に返されます。 scrollopt AUTO_FETCH値が指定されたときにフェッチ バッファーに配置された行数を表します。 |
RPC が使用中の場合、戻り値は次のようになります。
| 値 | 説明 |
|---|---|
0 |
プロシージャが成功しました。 |
1 |
プロシージャが失敗しました。 |
2 |
キーセット カーソルが非同期に生成されています。 |
16 |
早送りカーソルが自動的に閉じられました。 |
sp_cursoropen プロシージャが正常に実行されると、RPC の戻り値パラメーターと、TDS 列形式情報 (0xa0および0xa1 メッセージ) を含む結果セットが送信されます。 失敗した場合は、1 つ以上の TDS エラー メッセージが送信されます。 いずれの場合も、行データは返されません。 DONE メッセージ数は 0。 0x81は、0xa5および0xa4トークン ストリームと共に (SELECT ステートメントの標準) が返されます。
解説
stmt パラメーター
stmtがストアド プロシージャの実行を指定する場合、入力パラメーターは、stmt文字列の一部として定数として定義されるか、boundparam 引数として指定されます。 宣言された変数は、このようにバインドされたパラメーターとして渡すことができます。
stmt パラメーターの許可される内容は、ccopt ALLOW_DIRECT戻り値が ccopt 値の残りの部分にORによってリンクされたかどうかによって異なります。
ALLOW_DIRECTを指定しない場合は、単一のSELECTステートメントを含むストアド プロシージャを呼び出す Transact-SQLSELECTまたはEXECUTEステートメントを使用する必要があります。 さらに、SELECTステートメントはカーソルとして修飾する必要があります。つまり、キーワードSELECT INTOまたはFOR BROWSEを含めることはできません。ALLOW_DIRECT指定すると、1 つ以上の Transact-SQL ステートメント (複数のステートメントで他のストアド プロシージャを実行するステートメントを含む) が発生する可能性があります。SELECT以外のステートメント、またはキーワードSELECT INTOまたはFOR BROWSEを含むSELECTステートメントが実行され、カーソルが作成されることはありません。 複数のステートメントのバッチに含まれるSELECTステートメントについても同様です。SELECTステートメントにカーソルのみに関連する句が含まれている場合、それらの句は無視されます。 たとえば、 ccopt の値が0x2002場合、これは次の要求になります。カーソルとして修飾する
SELECTステートメントが 1 つだけ存在する場合は、スクロール ロックのあるカーソル。または複数のステートメント、1 つの
SELECTでないステートメント、またはカーソルとして修飾されないSELECTステートメントがある場合の直接ステートメントの実行。
scrollopt パラメーター
最初の 5 scrollopt 値 (KEYSEY、 DYNAMIC、 FORWARD_ONLY、 STATIC、および FAST_FORWARD) は相互に排他的です。
PARAMETERIZED_STMT と CHECK_ACCEPTED_TYPES は、最初の 5 つの値のいずれかに OR してリンクできます。
AUTO_FETCHAUTO_CLOSEは、FAST_FORWARDにORしてリンクできます。
CHECK_ACCEPTED_TYPESがONの場合は、最後の 5 つの scrollopt 値 (KEYSET_ACCEPTABLE、DYNAMIC_ACCEPTABLE、FORWARD_ONLY_ACCEPTABLE、STATIC_ACCEPTABLE、またはFAST_FORWARD_ACCEPTABLE) の少なくとも 1 つもONする必要があります。
STATIC カーソルは常に READ_ONLYとして開かれます。 これは、基になるテーブルをこのカーソルで更新できないことを意味します。
ccopt パラメーター
最初の 4 つの ccopt 値 (READ_ONLY、 SCROLL_LOCKS、両方の OPTIMISTIC 値) は相互に排他的です。
Note
最初の 4 つの ccopt 値のいずれかを選択すると、カーソルが読み取り専用かどうか、またはロックまたはオプティミスティックメソッドを使用して更新が失われるのを防ぐことができます。 ccopt値が指定されていない場合、既定値はOPTIMISTIC。
ALLOW_DIRECT と CHECK_ACCEPTED_TYPES は、最初の 4 つの値のいずれかに OR してリンクできます。
UPDT_IN_PLACEは、READ_ONLY、SCROLL_LOCKS、またはいずれかのOPTIMISTIC値にORによってリンクできます。
CHECK_ACCEPTED_TYPESがONの場合、最後の 4 つの ccopt 値 (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 を指定すると、次の結果が制御されます。
一意のインデックスを持つテーブルに対して位置指定された更新を実行するときに設定しない場合、カーソルは作業テーブルから行を削除し、カーソルで使用されるキー列の末尾に挿入し、それらの列を変更します。
ON設定すると、カーソルは作業テーブルの元の行のキー列を更新します。
bound_param パラメーター
パラメーター名は、コード内のエラー メッセージに従ってPARAMETERIZED_STMTが指定されている場合はparamdef する必要があります。 PARAMETERIZED_STMTが指定されていない場合、エラー メッセージに名前は指定されません。
RPC に関する考慮事項
RPC RETURN_METADATA 入力フラグを 0x0001 に設定して、カーソル選択リストのメタデータが TDS ストリームに返されるように要求できます。
例
A. bound_param パラメーター
5 番目以降のすべてのパラメーターは、入力パラメーターとしてステートメント プランに渡されます。 このような最初のパラメーターは、次の形式の文字列である必要があります。
<parameter_name> <data_type> [ ,... n ]
後続のパラメーターは、ステートメント内の <parameter_name> に置き換えられる値を渡すために使用されます。