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 は、カーソル に 関係するすべての後続のプロシージャ (sp_cursorfetch など) で指定する必要があるハンドル 値です。 cursor は int 戻り値を持つ必須パラメーターです。

カーソル を使用すると、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 オプティミスティック (旧称 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 値をオーバーライドできます。

行数
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 エラー メッセージが送信されます。 いずれの場合も、行データは返されません。完了したメッセージ数は 0 になります。 7.0 より前のバージョンの SQL Server を使用している場合、0xa0、0xa1 (Standard Edition LECT ステートメントの標準) が0xa5および0xa4トークン ストリームと共に返されます。 SQL Server 7.0 を使用している場合は、0xa5および0xa4トークン ストリームと共に0x81が返されます (Standard Edition LECT ステートメントの標準)。

解説

stmt パラメーター

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

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

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

  • ALLOW_DIRECT指定すると、1 つ以上の Transact-SQL ステートメントが発生する可能性があります。これには、複数のステートメントで他のストアド プロシージャが実行されるステートメントも含まれます。 非Standard Edition LECT ステートメント、または キーワード (KEYWORD) Standard Edition LECT INTO または FOR BROW を含む任意のStandard Edition LECT ステートメントStandard Editionは単に実行され、カーソルが作成されることはありません。 複数のステートメントのバッチに含まれている SELECT ステートメントについても同様です。 Standard Edition LECT ステートメントにカーソルのみに関連する句が含まれている場合、それらの句は無視されます。 たとえば、ccopt の値が0x2002場合、これは次の要求です。

    • スクロール ロックを使用するカーソル (カーソルの条件を満たしている単一の SELECT ステートメントだけがある場合)。

    • 複数のステートメント、1 つの非Standard Edition LECT ステートメント、またはカーソルとして修飾されない Standard Edition LECT ステートメントがある場合は、直接ステートメントを実行します。

scrollopt パラメーター

最初の 5 つの scrollopt 値 (KEY Standard Edition Y、DYNAMIC、FORWARD_ONLY、STATIC、FAST_FORWARD) は相互に排他的です。

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

AUTO_FETCHとAUTO_CLOStandard Editionは、OR を使用してFAST_FORWARDにリンクできます。

CHECK_ACCEPTED_TYPESが ON の場合、最後の 5 つの scrollopt 値 (KEY Standard EditionT_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 によって決定されたタイムスタンプまたは チェックsum 値を比較することによって、オプティミスティック通貨制御関数が実行されるためです。 一致しない行があると操作が失敗します。

戻り値として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)