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)