sp_cursorfetch （Transact-SQL）
適用於：
SQL Server
從資料庫擷取一或多個數據列的緩衝區。 這個緩衝區中的數據列群組稱為數據指標的擷 取緩衝區。 sp_cursorfetch 是在表格式資料流 （TDS） 封包中指定 ID = 7 來叫用。
語法
sp_cursorfetch cursor
[ , fetchtype [ , rownum [ , nrows ] ] ]
[ ; ]
引數
cursor
由 SQL Server 產生的句柄值，並由傳sp_cursoropen回。 cursor 是呼叫 int 輸入值的必要參數。 如需詳細資訊，請參閱備註一節。
fetchtype
指定要擷取的數據指標緩衝區。 fetchtype 是選擇性參數，需要下列其中一個整數輸入值。
| 值 | 名稱 | 描述 |
|---|---|---|
0x0001 |
FIRST |
擷取 nrows 數據列的第一個緩衝區。 如果 nrows 等於 0，則游標會放在結果集之前，而且不會傳回任何數據列。 |
0x0002 |
NEXT |
擷取 nrows 數據列的下一個緩衝區。 |
0x0004 |
PREV |
擷取 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只支援以單一DYNAMIC方向捲動。 |
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 |
必須搭配其中一個其他 fetchtype 值使用，但 除外 INFO。 |
注意
不支援 值 0x40。
如需詳細資訊，請參閱備註一節。
rownum
選擇性參數，用來指定 和 INFO fetchtype 值的數據列位置ABSOLUTE，只使用輸入或輸出的整數值，或兩者。 rownum 做為 fetchtype 位值 RELATIVE的數據列位移。 所有其他值都會忽略 rownum 。 如需詳細資訊，請參閱備註一節。
nrows
選擇性參數，用來指定要擷取的數據列數目。 如果未 指定 nrows ，則預設值為 20 個數據列。 若要設定位置而不傳回數據，請指定的值 0。 當 nrows 套用至 fetchtype INFO 查詢時，它會傳回該查詢中的數據列總數。
擷取類型位值會REFRESH忽略 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 數據指標，這表示索引鍵集數據表在最後一個非斯基普 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時，數據指標會放在提取緩衝區中沒有數據列的結果集之前。
當您指定的 fetchtype 值為 LAST 0 時，數據指標會位於目前提取緩衝區中沒有數據列的結果集之後。
對於 、 PREV、 、ABSOLUTERELATIVE 和 PREV_NOADJUST的 NEXTfetchtype 值，nrow 值0無效。
RPC 考慮
RPC 傳回狀態會指出索引鍵集大小參數是否為最終參數;也就是說，如果索引鍵集或臨時表是以異步方式填入。
RPC 狀態參數會設定為下表所示的其中一個值。
| 值 | Description |
|---|---|
0 |
程式已順利執行。 |
0x0001 |
程序失敗。 |
0x0002 |
負方向的擷取會導致數據指標位置設定為結果集的開頭，而當提取在結果之前邏輯上。 |
0x10 |
快轉游標會自動關閉。 |
數據列會以一般結果集的形式傳回：數據行格式 （）、數據列 （0x2a0xd1），後面接著 DONE （0xfd）。 元數據令牌的傳送格式與針對 sp_cursoropen： 和 0xa4 指定給 SQL 0x810xa5 Server 使用者的格式相同，依此方式傳送。 數據列狀態指標會以隱藏數據行的形式傳送，類似於 BROWSE 模式，且每個數據列結尾都有數據行名稱 rowstat 和數據類型 int。此 rowstat 數據行具有下表所示的其中一個值。
| 值 | Description |
|---|---|
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
接下來，sp_cursorfetchPREV其中 nrows 5 會在結果集的第一個數據列之前，以邏輯方式將游標放置兩個數據列。 在這些情況下，數據指標會調整為從第一個數據列開始，並傳回所要求的數據列數目。 這通常表示它會傳回擷取緩衝區中的數據 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