sp_cursorfetch (Transact-SQL)
適用対象: 
SQL Server
データベースから 1 つ以上の行のバッファーをフェッチします。 このバッファー内の行のグループは、カーソルの フェッチ バッファーと呼ばれます。 sp_cursorfetch は、表形式データ ストリーム (TDS) パケットで ID = 7 を指定することによって呼び出されます。
構文
sp_cursorfetch cursor
[ , fetchtype [ , rownum [ , nrows ] ] ]
[ ; ]
引数
cursor
sp_cursoropenによって返される値。 cursor は、 int 入力値を呼び出す必須のパラメーターです。 詳細については、「解説」を参照してください。
fetchtype
フェッチするカーソル バッファーを指定します。 fetchtype は、次のいずれかの整数入力値を必要とする省略可能なパラメーターです。
| Value | 名前 | 説明 |
|---|---|---|
0x0001 |
FIRST |
nrows行の最初のバッファーをフェッチします。 行が 0 の場合、カーソルは結果セットの前に配置され、行は返されません。 |
0x0002 |
NEXT |
nrows 行の次のバッファーをフェッチします。 |
0x0004 |
PREV |
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 クエリに適用されると、そのクエリ内の行の合計数が返されます。
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カーソルの場合、これは、キーセット テーブルが最後の非スキップ FETCH中に設定された値 (実行された場合) を持っていることを意味します。 そうでない場合は、作成中に設定された値です。
DYNAMICカーソルの場合、これは、スキップが更新で実行されると、KEYSETと同じ結果が生成されることを意味します。 その他のフェッチの種類の場合、キーセット テーブルは切り捨てられます。 これは、行が挿入され、タイムスタンプ列の値が未定義であることを意味します。 そのため、DYNAMIC カーソルに対してsp_cursorfetchを実行する場合は、REFRESH以外の操作にSKIP_UPDT_CNCYを使用しないでください。
要求したカーソル位置が結果セットの範囲を超えていたためにフェッチ操作が失敗した場合は、カーソル位置が最後の行の直後に設定されます。 要求したカーソル位置が結果セットより前だったためにフェッチ操作が失敗した場合は、カーソル位置が最初の行の前に設定されます。
rownum パラメーター
rownumを使用すると、指定した行から始まるバッファーがいっぱいになります。
fetchtype値ABSOLUTEは、結果セット全体のrownumの位置を参照します。 ABSOLUTEの負の数は、操作が結果セットの末尾から行をカウントすることを指定します。
fetchtype値RELATIVEはrownum現在のバッファーの先頭でのカーソルの位置を参照します。 RELATIVEの負の数は、カーソルが現在のカーソル位置から後方に移動することを指定します。
nrows パラメーター
fetchtype値はREFRESHされ、このパラメーターは無視INFO。
fetchtype nrow 値が 0 のFIRSTの値を指定すると、フェッチ バッファー内に行がない結果セットの前にカーソルが配置されます。
nrow値 0 のLASTのfetchtype値を指定すると、現在のフェッチ バッファー内に行がない結果セットの後にカーソルが配置されます。
fetchtypeNEXT、PREV、ABSOLUTE、RELATIVE、およびPREV_NOADJUSTの値では、nrow値0は無効です。
RPC に関する考慮事項
RPC の戻り状態は、キーセット サイズ パラメーターが最終的かどうかを示します。つまり、キーセットまたは一時テーブルが非同期的に設定されている場合です。
RPC 状態パラメーターは、次の表に示す値のいずれかに設定されます。
| 値 | 説明 |
|---|---|
0 |
プロシージャが正常に実行されました。 |
0x0001 |
プロシージャが失敗しました。 |
0x0002 |
負の方向のフェッチにより、カーソル位置が結果セットの先頭に設定されました (論理的には、結果セットの前でフェッチが行われるはずでした)。 |
0x10 |
早送りカーソルが自動的に閉じられました。 |
行は一般的な結果セットとして返されます。列形式 (0x2a)、行 (0xd1)、 DONE (0xfd)。 メタデータ トークンは、 sp_cursoropenに指定された形式 ( 0x81、 0xa5 、SQL Server ユーザーの 0xa4 など) で送信されます。 行の状態インジケーターは、 BROWSE モードと同様に、列名 rowstat とデータ型が int の各行の末尾に非表示の列として送信されます。この 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
次に、行が5されているsp_cursorfetch PREVは、結果セットの最初の行の前にカーソルを 2 行論理的に配置します。 このような場合、カーソルが最初の行で開始されるように調整されて、要求した数の行が返されます。 これは、多くの場合、 PRIOR フェッチ バッファーに含まれている行を返します。
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