sp_cursorfetch (Transact-SQL)
適用対象:SQL Server
データベースから 1 つ以上の行のバッファーをフェッチします。 このバッファー内の行のグループは、カーソルの フェッチ バッファーと呼ばれます。 sp_cursorfetchは、表形式データ ストリーム (TDS) パケットで ID = 7 を指定することによって呼び出されます。
構文
sp_cursorfetch cursor
[ , fetchtype[ , rownum [ , nrows] ]]
引数
cursor
SQL Serverによって生成され、sp_cursoropenによって返されるハンドル値です。 cursor は、 int 入力値を呼び出す必須パラメーターです。 詳細については、このトピックで後述する「解説」を参照してください。
fetchtype
フェッチするカーソル バッファーを指定します。 fetchtype は、次のいずれかの整数入力値を必要とする省略可能なパラメーターです。
値 | 名前 | 説明 |
---|---|---|
0x0001 | FIRST | nrows 行の最初のバッファーをフェッチします。 nrows が 0 の場合、カーソルは結果セットの前に配置され、行は返されません。 |
0x0002 | NEXT | nrows 行の次のバッファーをフェッチします。 |
0x0004 | 前 | nrows 行の前のバッファーをフェッチします。 注: FORWARD_ONLY カーソルに PREV を使用すると、FORWARD_ONLYは一方向のスクロールのみをサポートするため、エラー メッセージが返されます。 |
0x0008 | LAST | nrows 行の最後のバッファーをフェッチします。 nrows が 0 の場合、カーソルは結果セットの後に配置され、行は返されません。 注: FORWARD_ONLY カーソルに LAST を使用すると、エラー メッセージが返されます。FORWARD_ONLYでは一方向のスクロールのみがサポートされるためです。 |
0x10 | ABSOLUTE | rownum 行から始まる nrows 行のバッファーをフェッチします。 注: DYNAMIC カーソルまたはFORWARD_ONLY カーソルに ABSOLUTE を使用すると、FORWARD_ONLYは一方向のスクロールのみをサポートするため、エラー メッセージが返されます。 |
0x20 | RELATIVE | 現在のブロックの最初の行から行の rownum 値として指定された行で始まる nrows 行のバッファーをフェッチします。 この場合、 rownum には負の数を指定できます。 注: FORWARD_ONLY カーソルに RELATIVE を使用すると、FORWARD_ONLYは一方向のスクロールのみをサポートするため、エラー メッセージが返されます。 |
0x80 | REFRESH | 基になるテーブルのデータをバッファーに再読み込みします。 |
0x100 | INFO | カーソルに関する情報を取得します。 この情報は、 rownum パラメーターと nrows パラメーターを 使用して返されます。 そのため、INFO を指定すると、 rownum と nrows が 出力パラメーターになります。 |
0x200 | PREV_NOADJUST | PREV と同じように使用されます。 ただし、途中で結果セットの先頭に到達した場合に結果が変わる可能性があります。 |
0x400 | SKIP_UPDT_CNCY | INFO を除き、他のいずれかの fetchtype 値と共に使用する必要があります。 |
注意
値0x40はサポートされません。
詳細については、このトピックで後述する「解説」を参照してください。
Rownum
入力または出力に整数値のみを使用するか、またはその両方を使用して ABSOLUTE および INFO フェッチタイプ 値の行位置を指定するために使用される省略可能なパラメーターです。 rownum は、 fetchtype ビット値 RELATIVE の行オフセットとして機能します。 rownum は、他のすべての値では無視されます。 詳細については、このトピックで後述する「解説」を参照してください。
Nrows
フェッチする行数を指定するために使用される省略可能なパラメーターです。 nrows が指定されていない場合、既定値は 20 行です。 データを返さずに位置を設定するには、値 0 を指定します。 nrows がフェッチタイプ INFO クエリに適用されると、そのクエリ内の行の合計数が返されます。
注意
nrows は REFRESH fetchtype ビット値によって無視されます。
詳細については、このトピックで後述する「解説」を参照してください。
リターン コードの値
ビット値 INFO を指定すると、返される可能性のある値を次の表に示します。
注意
: 行が返されない場合、バッファーの内容はそのまま残ります。
<Rownum> | 設定値 |
---|---|
開かない場合 | 0 |
結果セットより前の場合 | 0 |
結果セットの後に配置された場合 | -1 |
KEYSET カーソルと STATIC カーソルの場合 | 結果セット内の現在位置の絶対行番号 |
DYNAMIC カーソルの場合 | 1 |
ABSOLUTE の場合 | -1 は、セット内の最後の行を返します。 -2 を指定すると、セット内の最後から 2 番目の行が返されます (以降、同様に続きます)。 注: この場合、複数の行のフェッチが要求された場合は、結果セットの最後の 2 行が返されます。 |
<Nrows> | 設定値 |
---|---|
開かない場合 | 0 |
KEYSET カーソルと STATIC カーソルの場合 | 通常は、現在のキーセット サイズです。 -m カーソルが非同期作成中で、この時点で m 行が見つかった場合。 |
DYNAMIC カーソルの場合 | -1 |
解説
cursor パラメーター
フェッチ操作が行われる前は、カーソルの既定の位置は結果セットの最初の行の前になります。
fetchtype パラメーター
SKIP_UPD_CNCYを除き、 fetchtype 値は相互に排他的です。
SKIP_UPDT_CNCYを指定すると、行がフェッチまたは更新されるときに、タイムスタンプ列の値はキーセット テーブルに書き込まれません。 キーセット行が更新されている場合、タイムスタンプ列の値は前の値のままです。 行が挿入された場合は timestamp 列の値が未定義になります。
その結果、KEYSET カーソルでは、keyset テーブルの値が、前回通常の FETCH が実行されたときに設定された値か (通常の FETCH が実行されている場合)、 そうでない場合は、作成中に値が設定されます。
DYNAMIC カーソルの場合、これは、スキップが更新で実行されると、KEYSET と同じ結果が生成されることを意味します。 その他のフェッチの種類の場合、キーセット テーブルは切り捨てられます。 これは、行が挿入され、タイムスタンプ列の値が未定義であることを意味します。 このため、DYNAMIC カーソルで sp_cursorfetch を実行する際には、REFRESH 以外の操作に対して SKIP_UPDT_CNCY を使用しないようにしてください。
要求したカーソル位置が結果セットの範囲を超えていたためにフェッチ操作が失敗した場合は、カーソル位置が最後の行の直後に設定されます。 要求したカーソル位置が結果セットより前だったためにフェッチ操作が失敗した場合は、カーソル位置が最初の行の前に設定されます。
rownum パラメーター
rownum を使用すると、バッファーは指定した行から始まります。
fetchtype 値 ABSOLUTE は、結果セット全体内の rownum の位置を参照します。 ABSOLUTE の負の数は、操作が結果セットの末尾から行をカウントすることを指定します。
fetchtype 値 RELATIVE は、現在のバッファーの先頭でのカーソルの位置に対する rownum の位置を参照します。 RELATIVE の負の数は、カーソルが現在のカーソル位置から後方に移動することを指定します。
nrows パラメーター
fetchtype 値 REFRESH と INFO は、このパラメーターを無視します。
nrow 値が 0 の fetchtype 値 FIRST を指定すると、カーソルは、フェッチ バッファー内に行がない結果セットの前に配置されます。
nrow 値が 0 の fetchtype 値 LAST を指定すると、カーソルは、現在のフェッチ バッファーに行がない結果セットの後に配置されます。
NEXT、PREV、ABSOLUTE、RELATIVE、および PREV_NOADJUST の fetchtype 値の場合、 nrow 値 0 は無効です。
RPC に関する考慮事項
RPC の戻りステータスでは、キーセット サイズのパラメーターが final かどうか (keyset テーブル (一時テーブル) が非同期に作成されるかどうか) が示されます。
RPC 状態パラメーターは、次の表に示す値のいずれかに設定されています。
値 | 説明 |
---|---|
0 | プロシージャが正常に実行されました。 |
0x0001 | プロシージャが失敗しました。 |
0x0002 | 負の方向のフェッチにより、カーソル位置が結果セットの先頭に設定されました (論理的には、結果セットの前でフェッチが行われるはずでした)。 |
0x10 | 早送りカーソルが自動的に閉じられました。 |
行は一般的な結果セットとして返されます。つまり、列形式 (0x2a)、行 (0xd1)、その後に done (0xfd) が返されます。 メタデータ トークンは、sp_cursoropenに指定された形式と同じ形式で送信されます。つまり、0x81、0xa5、0xa4 SQL Server 7.0 ユーザーなどです。 行の状態インジケーターは、ブラウズ モードのように、各行の末尾の非表示の列として送信されます (列名は rowstat、データ型は INT4)。 この rowstat 列には、次のいずれかの値が含まれます。
値 | 説明 |
---|---|
0x0001 | FETCH_SUCCEEDED |
0x0002 | FETCH_MISSING |
TDS プロトコルでは、前の列を送信せずに末尾の状態列だけを送信することはできないため、欠けている行に対してはダミー データが送信されます (NULL 値許容フィールドは NULL に設定され、固定長フィールドは 0、空白、または列の既定値に設定されます)。
DONE 行数は常に 0 になります。 DONE メッセージに結果セットの実際の行数が含まれます。TDS メッセージの間にエラー メッセージや情報メッセージが表示される場合もあります。
カーソルの選択リストに関するメタデータを TDS ストリームで返すように要求するには、RPC RETURN_METADATA入力フラグを 1 に設定します。
例
A. PREV を使用してカーソル位置を変更する
カーソル h2 は、次の内容を持つ結果セットを生成し、次に示すように現在の位置を持つと仮定します。
row 1 contents
row 2 contents
row 3 contents
row 4 contents <-- current position
row 5 contents
row 6 contents
次に、 nrows 値が 5 のsp_cursorfetch PREV は、カーソルを結果セットの最初の行の 2 行前に論理的に配置します。 このような場合、カーソルが最初の行で開始されるように調整されて、要求した数の行が返されます。 その結果、通常は、前のフェッチ バッファーに含まれていた行が返されることになります。
注意
これは、RPC 状態パラメーターが 2 に設定されている正確なケースです。
B. PREV_NOADJUSTを使用して PREV より少ない行を返す
PREV_NOADJUSTは、返される行ブロック内の現在のカーソル位置以降の行を含めることはありません。 PREV が現在の位置より後の行を返す場合、PREV_NOADJUSTは nrows で要求された行よりも少ない行を返します。 たとえば、前の例 A の現在位置で PREV を適用した場合、sp_cursorfetch(h2, 4, 1, 5) で次の行がフェッチされます。
row1 contents
row2 contents
row3 contents
row4 contents
row5 contents
一方、PREV_NOADJUST を適用した場合は、sp_cursorfetch(h2, 512, 6, 5) で次の行のみがフェッチされます。
row1 contents
row2 contents
row3 contents
参照
sp_cursoropen (Transact-SQL)
システム ストアド プロシージャ (Transact-SQL)
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示