sp_cursorfetch （Transact-SQL）

適用於：SQL Server

從資料庫擷取一或多個資料列的緩衝區。 這個緩衝區中的資料列群組稱為資料指標的擷 取緩衝區 。 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 資料列的 緩衝區 。 注意：針對動態資料指標或FORWARD_ONLY資料指標使用 ABSOLUTE 會傳回錯誤訊息，因為FORWARD_ONLY只支援以單向捲動。
0x20	RELATIVE	擷取 nrows 資料列的 緩衝區，其開頭為指定為 目前區塊中第一個資料列之資料列的 rownum 值。 在此情況下 ，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 fetchtype 值的資料列位置，方法是只針對輸入或輸出使用整數值，或兩者。 rownum 可作為 fetchtype 位值 RELATIVE 的資料 列位移。 所有其他值都會忽略 rownum 。 如需詳細資訊，請參閱本主題稍後的一節。

nrows
這是選擇性參數，用來指定要擷取的資料列數目。 如果未 指定 nrows ，則預設值為 20 個數據列。 若要設定位置而不傳回資料，請指定 0 的值。 當 nrows 套用至 fetchtype INFO 查詢時 ，它會傳回該查詢中的資料列總數。

注意

REFRESH fetchtype 位值會忽略 nrows 。

如需詳細資訊，請參閱本主題稍後的一節。

傳回碼值

當您指定位值 INFO 時，下表會顯示可能傳回的值。

注意

：如果未傳回任何資料列，緩衝區內容會維持原狀。

<rownum>	設定為
如果未開啟	0
如果位於結果集之前	0
如果位於結果集之後	-1
KEYSET 和 STATIC 資料指標	結果集中目前位置的絕對資料列編號
針對 DYNAMIC 資料指標	1
針對 ABSOLUTE	-1 會傳回集合中的最後一個資料列。 -2 會傳回集合中的第二個到最後一個資料列，依此傳回。 注意：如果在此案例中要求擷取多個資料列，則會傳回結果集的最後兩個數據列。

<nrows>	設定為
如果未開啟	0
KEYSET 和 STATIC 資料指標	一般而言，目前的索引鍵集大小。 -m 如果資料指標處於非同步建立中，且 有找到此點的 m 資料列。
針對 DYNAMIC 資料指標	-1

備註

cursor 參數

在有任何擷取作業之前，資料指標的預設位置是在結果集的第一個資料列之前。

fetchtype 參數

除了SKIP_UPD_CNCY以外， fetchtype 值是互斥的。

指定SKIP_UPDT_CNCY時，在擷取或重新整理資料列時，時間戳記資料行值不會寫入索引鍵集資料表。 如果索引鍵集資料列正在更新，時間戳記資料行的值會維持為先前的值。 如果插入索引鍵集資料列，則時間戳記資料行的值是未定義的。

若為 KEYSET 資料指標，這表示如果已執行索引鍵集資料表，索引鍵集資料表在最後一個非SKIP FETCH 期間設定的值。 如果沒有，它會在母體擴展期間設定值。

對於 DYNAMIC 資料指標，這表示如果略過是使用重新整理來執行，它會產生與 KEYSET 相同的結果。 針對任何其他擷取類型，會截斷索引鍵集資料表。 這表示正在插入資料列，且時間戳記資料行的值未定義。 因此，當您針對 DYNAMIC 資料指標執行sp_cursorfetch時，請避免針對 REFRESH 以外的任何作業使用SKIP_UPDT_CNCY。

如果擷取作業失敗，因為要求的資料指標位置超出結果集，則資料指標位置會在最後一個資料列之後設定。 如果擷取作業失敗，因為要求的資料指標位置位於結果集之前，則會在第一個資料列之前設定資料指標位置。

rownum 參數

當您使用 rownum 時，會從指定的資料列開始填入緩衝區。

fetchtype 值 ABSOLUTE 是指整個結果集內 rownum 的位置 。 具有 ABSOLUTE 的負數指定作業會計算結果集結尾的資料列。

fetchtype 值 RELATIVE 是指與目前緩衝區開頭資料指標位置相關的 rownum 位置 。 具有 RELATIVE 的負數指定資料指標從目前游標位置往後移動。

nrows 參數

fetchtype 值 REFRESH 和 INFO 會忽略此參數。

當您指定 FIRST 的 fetchtype 值，其 nrow 值為 0 時，資料指標會放在沒有提取緩衝區中任何資料列的結果集之前。

當您指定 LAST 的 fetchtype 值， 其 nrow 值為 0 時，資料指標會放在目前擷取緩衝區中沒有資料列的結果集之後。

對於 NEXT、PREV、ABSOLUTE、RELATIVE 和 PREV_NOADJUST 的 fetchtype 值， nrow 值 0 無效。

RPC 考慮

RPC 傳回狀態指出索引鍵集大小參數是否為最終參數，也就是說，如果索引鍵集或臨時表是以非同步方式填入。

RPC 狀態參數會設定為下表所示的其中一個值。

值	描述
0	程式已順利執行。
0x0001	程式失敗。
0x0002	負方向的擷取會導致資料指標位置設定為結果集的開頭，而當提取在結果之前邏輯上。
0x10	快轉游標會自動關閉。

資料列會以一般的結果集傳回，也就是：資料行格式（0x2a）、資料列（0xd1），後面接著完成 （0xfd）。 中繼資料權杖的傳送格式與針對 sp_cursoropen 指定的格式相同，也就是：SQL Server 7.0 使用者的0x81、0xa5和0xa4等等。 資料列狀態指標會以隱藏資料行的形式傳送，類似于 BROWSE 模式，且每個資料列結尾都有資料行名稱 rowstat 和資料類型 INT4。 此 rowstat 資料行具有下表所示的其中一個值。

值	Description
0x0001	FETCH_SUCCEEDED
0x0002	FETCH_MISSING

由於 TDS 通訊協定無法傳送尾端狀態資料行，而不傳送先前的資料行，因此會針對遺漏的資料列傳送虛擬資料（可為 Null 的欄位設定為 null、固定長度欄位設定為 0、空白或該資料行的預設值，視需要）。

DONE 資料列計數一律為零。 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 的 prev sp_cursorfetch，會在結果集的第一個資料列之前，以邏輯方式將游標放置兩個數據列。 在這些情況下，資料指標會調整為從第一個資料列開始，並傳回所要求的資料列數目。 這通常表示它會傳回 PRIOR 擷取緩衝區中的資料列。

注意

這是 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)