sp_cursoropen (Transact-SQL)

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

Transact-SQL 構文表記規則

構文

        sp_cursoropen 
        cursor OUTPUT
        , 
        stmt
        
        
    [, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ]    [ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]

引数

• cursor
  SQL Server によって生成されるカーソル識別子です。cursor は、このカーソルを使用する後続のすべてのプロシージャ (sp_cursorfetch など) に渡す必要があるハンドル値です。cursor は、戻り値が int の必須パラメーターです。

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

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

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

  値	説明
  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 と同様に、要求した ccopt 値が SQL Server によって上書きされる場合があります。

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

  入力値	戻り値
  scrollopt AUTO_FETCH の値が指定されている場合、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
  高速順方向カーソルが自動的に閉じられました。

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

説明

stmt パラメーター

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

stmt パラメーターで使用できる内容は、次のように、ccopt の戻り値 ALLOW_DIRECT が残りの ccopt 値と OR で結合されているかどうかによって異なります。

• ALLOW_DIRECT が指定されていない場合は、単一の SELECT ステートメントを含むストアド プロシージャを要求する Transact-SQL SELECT ステートメントまたは EXECUTE ステートメントを使用する必要があります。その SELECT ステートメントがカーソルの条件を満たしている必要もあります (キーワード SELECT INTO、FOR BROWSE、および COMPUTE を含むことができません)。

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

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

  • ステートメントの直接実行 (複数のステートメントがある場合、SELECT 以外の単一のステートメントがある場合、またはカーソルの条件を満たしていない SELECT ステートメントがある場合)。

scrollopt パラメーター

scrollopt の最初の 5 つの値 (KEYSEY、DYNAMIC、FORWARD_ONLY、STATIC、および FAST_FORWARD) は、同時に指定できません。

PARAMETERIZED_STMT と CHECK_ACCEPTED_TYPES は、最初の 5 つの値と OR で結合できます。

AUTO_FETCH と AUTO_CLOSE は、FAST_FORWARD と OR で結合できます。

CHECK_ACCEPTED_TYPES が ON の場合は、scrollopt の最後の 5 つの値 (KEYSET_ACCEPTABLE、DYNAMIC_ACCEPTABLE、FORWARD_ONLY_ACCEPTABLE、STATIC_ACCEPTABLE、または FAST_FORWARD_ACCEPTABLE) の少なくとも 1 つが ON である必要があります。

STATIC カーソルは常に READ_ONLY として開かれます。したがって、このカーソルを使用して基になるテーブルを更新することはできません。

ccopt パラメーター

ccopt の最初の 4 つの値 (READ_ONLY、SCROLL_LOCKS、および 2 つの OPTIMISTIC 値) は、同時に指定できません。

注
ccopt の最初の 4 つの値のどれを選択するかによって、カーソルを読み取り専用にするかどうかや、更新データの喪失を防ぐためにロックやオプティミスティックの方法を使用するかどうかが決まります。ccopt の値を指定しない場合の既定値は OPTIMISTIC です。

ALLOW_DIRECT と CHECK_ACCEPTED_TYPES は、最初の 4 つの値と OR で結合できます。

UPDT_IN_PLACE は、READ_ONLY、SCROLL_LOCKS、またはいずれかの OPTIMISTIC 値と OR で結合できます。

CHECK_ACCEPTED_TYPES が ON の場合は、ccopt の最後の 4 つの値 (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 を指定すると、結果を次のように制御できます。

• 一意インデックスを持つテーブルで位置指定更新を実行するときに UPDT_IN_PLACE を設定しないと、その行がカーソルの作業テーブルから削除されて、カーソルによって使用されているキー列の末尾に挿入されます。その結果、それらの列が変更されます。

• UPDT_IN_PLACE を ON に設定すると、単純に作業テーブルの元の行でキー列が更新されます。

bound_param パラメーター

PARAMETERIZED_STMT が指定されている場合は、コード内でのエラー メッセージに従って、パラメーター名を paramdef にする必要があります。PARAMETERIZED_STMT が指定されていない場合は、エラー メッセージで名前は指定されません。

RPC に関する考慮事項

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

例

bound_param パラメーター

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

{ local variable name data type } [,…n]

後続のパラメーターは、ステートメント内の local variable name の代わりに使用する値を渡すために使用されます。

関連項目

参照

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

その他の技術情報

sp_cursorfetch (Transact-SQL)