次の方法で共有


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 の代わりに使用する値を渡すために使用されます。