sp_cursorfetch (Transact-SQL)
適用対象: 
SQL サーバー
データベースから 1 つ以上の行のバッファーをフェッチします。 このバッファー内の行のグループは、カーソルの フェッチ バッファーと呼ばれます。 sp_cursorfetchは、表形式データ ストリーム (TDS) パケットで ID = 7 を指定して呼び出されます。
構文
sp_cursorfetch cursor
[ , fetchtype[ , rownum [ , nrows] ]]
引数
cursor
fetchtype
フェッチするカーソル バッファーを指定します。 fetchtype は、次のいずれかの整数入力値を必要とする省略可能なパラメーターです。
| Value | 名前 | 説明 |
|---|---|---|
| 0x0001 | FIRST | nrows行の最初のバッファーをフェッチします。 行が 0 の場合、カーソルは結果セットの前に配置され、行は返されません。 |
| 0x0002 | NEXT | nrows 行の次のバッファーをフェッチします。 |
| 0x0004 | 前 | nrows 行の前のバッファーをフェッチします。 注: FORWARD_ONLY カーソルに PREV を使用すると、FORWARD_ONLYでは一方向のスクロールのみがサポートされるため、エラー メッセージが返されます。 |
| 0x0008 | LAST | nrows 行の最後のバッファーをフェッチします。 行が 0 の場合、カーソルは結果セットの後に配置され、行は返されません。 注: FORWARD_ONLY カーソルに LAST を使用すると、FORWARD_ONLYは一方向のスクロールのみをサポートするため、エラー メッセージが返されます。 |
| 0x10 | ABSOLUTE | rownum 行から始まる行行のバッファーフェッチします。 注: DYNAMIC カーソルまたはFORWARD_ONLY カーソルに ABSOLUTE を使用すると、FORWARD_ONLYでは一方向のスクロールのみがサポートされるため、エラー メッセージが返されます。 |
| 0x20 | RELATIVE | 現在のブロックの最初の行の行の行数値として指定された行で始まる行行のバッファーをフェッチします。 この場合、 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 値のいずれかと共に使用する必要があります。 |
Note
値0x40はサポートされません。
詳細については、このトピックで後述する「解説」を参照してください。
rownum
入力または出力の整数値のみを使用して、ABSOLUTE 値と INFO fetchtype 値 値の行位置を指定するために使用する省略可能なパラメーターです。またはその両方です。 rownum は、 fetchtype ビット値 RELATIVE の行オフセットとして機能します。 rownum は、他のすべての値では無視されます。 詳細については、このトピックで後述する「解説」を参照してください。
nrows
フェッチする行数を指定するために使用される省略可能なパラメーターです。 行が指定されていない場合、既定値は 20 行です。 データを返さずに位置を設定するには、値 0 を指定します。 が fetchtype INFO クエリに適用されると、そのクエリ内の行の合計数が返されます。
Note
nrows は、REFRESH fetchtype ビット値では無視されます。
詳細については、このトピックで後述する「解説」を参照してください。
リターン コードの値
ビット値 INFO を指定すると、返される可能性がある値を次の表に示します。
Note
: 行が返されない場合、バッファーの内容はそのまま残ります。
| <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 の FIRST のfetchtype値を指定すると、フェッチ バッファーに行がない結果セットの前にカーソルが配置されます。
nrow 値が 0 の last のfetchtype値を指定すると、カーソルは、現在のフェッチ バッファーに行がない結果セットの後に配置されます。
fetchtype NEXT、PREV、ABSOLUTE、RELATIVE、およびPREV_NOADJUSTの値の場合、nrow値 0 は無効です。
RPC に関する考慮事項
RPC の戻りステータスでは、キーセット サイズのパラメーターが final かどうか (keyset テーブル (一時テーブル) が非同期に作成されるかどうか) が示されます。
RPC 状態パラメーターは、次の表に示す値のいずれかに設定されます。
| Value | 説明 |
|---|---|
| 0 | プロシージャが正常に実行されました。 |
| 0x0001 | プロシージャが失敗しました。 |
| 0x0002 | 負の方向のフェッチにより、カーソル位置が結果セットの先頭に設定されました (論理的には、結果セットの前でフェッチが行われるはずでした)。 |
| 0x10 | 早送りカーソルが自動的に閉じられました。 |
行は一般的な結果セットとして返されます。つまり、列形式 (0x2a)、行 (0xd1)、その後に done (0xfd) が返されます。 メタデータ トークンは、sp_cursoropenに指定された形式で送信されます。つまり、SQL Server 7.0 ユーザーの0x81、0xa5、0xa4などです。 行の状態インジケーターは、ブラウズ モードのように、各行の末尾の非表示の列として送信されます (列名は rowstat、データ型は INT4)。 この rowstat 列には、次のいずれかの値が含まれます。
| Value | 説明 |
|---|---|
| 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 行論理的に配置します。 このような場合、カーソルが最初の行で開始されるように調整されて、要求した数の行が返されます。 その結果、通常は、前のフェッチ バッファーに含まれていた行が返されることになります。
Note
これは、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)
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示