次の方法で共有

sp_cursoropen (Transact-SQL)

  • [アーティクル]

適用対象: SQL Server

カーソルを開きます。 sp_cursoropen では、カーソルとカーソルのオプションに関連付けられている SQL ステートメントを定義し、カーソルを設定します。 sp_cursoropen は、Transact-SQL ステートメントの DECLARE_CURSOR と OPENの組み合わせと同じです。 このプロシージャは、表形式データ ストリーム (TDS) パケットの ID = 2 を指定することによって呼び出されます。

Transact-SQL 構文表記規則

構文

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 で、次のいずれかの値を指定できます。

Value 説明
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 入力値を必要とする省略可能なパラメーターです。

Value 説明
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 は次のいずれかの値を返します。

Value 説明
0 プロシージャが正常に実行されました。
0x0001 実行中にエラーが発生しました (マイナー エラーであり、操作でエラーを発生させるほど重大ではありません)。
0x0002 非同期操作が進行中です。
0x0002 FETCH操作が処理中です。
A このカーソルの割り当てが解除され、使用できません。

エラーが発生すると、戻り値に一貫性がなく、精度が保証されない可能性があります。

戻り値として rowcount パラメーターを指定すると、次の結果セットが発生します。

Value 説明
-1 行数が不明または適用外の場合に返されます。
-n 非同期設定が有効になっている場合に返されます。 scrollopt AUTO_FETCH値が指定されたときにフェッチ バッファーに配置された行数を表します。

RPC が使用中の場合、戻り値は次のようになります。

Value 説明
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-SQL SELECTまたは 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> に置き換えられる値を渡すために使用されます。

関連するコンテンツ