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

要求された値が stmt によって定義されたカーソルに適していない可能性があるため、このパラメーターは入力と出力の両方として機能します。 このような場合は、SQL Server によって適切な値が割り当てられます。

ccopt

コンカレンシー制御オプション。 ccopt は、次のいずれかの int 入力値を必要とする省略可能なパラメーターです。

scrolloptと同様に、SQL Server は要求された ccopt 値をオーバーライドできます。

rowcount

AUTO_FETCHで使用するフェッチ バッファー行の数。 既定値は 20 行です。 rowcount は、入力値と戻り値として割り当てられた場合の動作が異なります。

boundparam

追加パラメーターの使用を示します。 boundparam は、 scrolloptPARAMETERIZED_STMT 値が ONに設定されている場合に指定する必要がある省略可能なパラメーターです。

リターン コードの値

エラーが発生しない場合、 sp_cursoropen は次のいずれかの値を返します。

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

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

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

sp_cursoropen プロシージャが正常に実行されると、RPC の戻り値パラメーターと、TDS 列形式情報 (0xa0および0xa1 メッセージ) を含む結果セットが送信されます。 失敗した場合は、1 つ以上の TDS エラー メッセージが送信されます。 いずれの場合も、行データは返されません。 DONE メッセージ数は 0。 0x81は、SELECTおよび0xa5トークン ストリームと共に (0xa4 ステートメントの標準) が返されます。

解説

stmt パラメーター

stmtがストアド プロシージャの実行を指定する場合、入力パラメーターは、stmt文字列の一部として定数として定義されるか、boundparam 引数として指定されます。 宣言された変数は、このようにバインドされたパラメーターとして渡すことができます。

stmt パラメーターの許可される内容は、ccoptALLOW_DIRECT戻り値が OR 値の残りの部分にによってリンクされたかどうかによって異なります。

• ALLOW_DIRECTを指定しない場合は、単一のSELECT ステートメントを含むストアド プロシージャを呼び出す Transact-SQL EXECUTEまたは SELECT ステートメントを使用する必要があります。 さらに、 SELECT ステートメントはカーソルとして修飾する必要があります。つまり、キーワード SELECT INTO または FOR BROWSEを含めることはできません。

• ALLOW_DIRECT指定すると、1 つ以上の Transact-SQL ステートメント (複数のステートメントで他のストアド プロシージャを実行するステートメントを含む) が発生する可能性があります。 SELECT以外のステートメント、またはキーワードSELECTまたはSELECT INTOを含むFOR BROWSEステートメントが実行され、カーソルが作成されることはありません。 複数のステートメントのバッチに含まれる 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_FETCH AUTO_CLOSEは、ORにFAST_FORWARDしてリンクできます。

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 値) は相互に排他的です。

ALLOW_DIRECT と CHECK_ACCEPTED_TYPES は、最初の 4 つの値のいずれかに OR してリンクできます。

UPDT_IN_PLACEは、OR、READ_ONLY、またはいずれかのSCROLL_LOCKS値にOPTIMISTICによってリンクできます。

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する必要があります。 PARAMETERIZED_STMTが指定されていない場合、エラー メッセージに名前は指定されません。

RPC に関する考慮事項

RPC RETURN_METADATA 入力フラグを 0x0001 に設定して、カーソル選択リストのメタデータが TDS ストリームに返されるように要求できます。

例

A. bound_param パラメーター

5 番目以降のすべてのパラメーターは、入力パラメーターとしてステートメント プランに渡されます。 このような最初のパラメーターは、次の形式の文字列である必要があります。

<parameter_name> <data_type> [ ,... n ]

後続のパラメーターは、ステートメント内の <parameter_name> に置き換えられる値を渡すために使用されます。

関連するコンテンツ

• sp_cursorfetch (Transact-SQL)
• システム ストアド プロシージャ (Transact-SQL)