次の方法で共有

sp_cursoropen (Transact-SQL)

  • [アーティクル]

適用対象: SQL サーバー

カーソルを開きます。 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 戻り値を持つ必須のパラメーターです。

cursor を使用すると、1 つのデータベース接続で複数のカーソルをアクティブにすることができます。

stmt
カーソル結果セットを定義する必須パラメーターです。 任意の文字列型 (Unicode、サイズなどに関係なく) の有効なクエリ文字列 (構文とバインド) は、有効な stmt 値型として機能できます。

scrollopt
スクロール オプションです。 scrollopt は、次のいずれかの int 入力値を必要とする省略可能なパラメーターです。

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 オプティミスティック (旧称 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
このカーソルは SQL Server によって割り当て解除され、使用できません。

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

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

-1
行数が不明または適用外の場合に返されます。

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

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

0
プロシージャが成功しました。

1
プロシージャが失敗しました。

2
キーセット カーソルが非同期に生成されています。

16
早送りカーソルが自動的に閉じられました。

Note

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

解説

stmt パラメーター

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

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

  • 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 つの非 SELECT ステートメント、またはカーソルとして修飾されない SELECT ステートメントがある場合は、直接ステートメントを実行します。

scrollopt パラメーター

最初の 5 つの scrollopt 値 (KEYSEY、DYNAMIC、FORWARD_ONLY、STATIC、および FAST_FORWARD) は相互に排他的です。

PARAMETERIZED_STMTとCHECK_ACCEPTED_TYPESは、OR で最初の 5 つの値のいずれかにリンクできます。

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、および両方のオプティミスティック値) は相互に排他的です。

Note

最初の 4 つの ccopt 値のいずれかを選択すると、カーソルが読み取り専用かどうか、またはロックまたはオプティミスティックメソッドを使用して更新が失われるのを防ぐことができます。 ccopt値が指定されていない場合、既定値は OPTIMISTIC です。

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

UPDT_IN_PLACEは、READ_ONLY、SCROLL_LOCKS、またはいずれかのオプティミスティック値に 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 ストリームに返すように要求できます。

例

bound_param パラメーター

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

{ ローカル変数名データ型 }[,...n]

後続のパラメーターは、ステートメント内の ローカル変数名 に置き換えられる値を渡すために使用されます。

参照

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