sp_cursorfetch (Transact-SQL)

適用対象:SQL Server

データベースから 1 つ以上の行のバッファーをフェッチします。 このバッファー内の行のグループは、カーソルの フェッチ バッファーと呼ばれます。 sp_cursorfetchは、表形式データ ストリーム (TDS) パケットで ID = 7 を指定することによって呼び出されます。

Transact-SQL 構文表記規則

構文

  
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)