SQLFetchScroll 函式
一致性
引進版本：ODBC 3.0 標準合規性：ISO 92
摘要
SQLFetchScroll 會從結果集擷取指定的數據列集，並傳回所有綁定數據行的數據。 數據列集可以在絕對位置或相對位置或書籤指定。
使用 ODBC 2.x 驅動程式時，Driver Manager 會將此函式對應至 SQLExtendedFetch。 如需詳細資訊，請參閱 對應替代函式以取得應用程式的回溯相容性。
語法
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
引數
StatementHandle
[輸入]語句句柄。
FetchOrientation
[輸入]
擷取的類型：
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
SQL_FETCH_RELATIVE
SQL_FETCH_BOOKMARK
如需詳細資訊，請參閱一節中的。
FetchOffset
[輸入]
要擷取的數據列數目。 這個自變數的解譯取決於 FetchOrientation 自變數的值。 如需詳細資訊，請參閱一節中的。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLFetchScroll 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，呼叫具有 SQL_HANDLE_STMT HandleType 和 StatementHandle Handle 的 HandleType 來取得相關聯的 SQLSTATE 值。 下表列出 SQLFetchScroll 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。 如果在單一數據行上發生錯誤， 可以使用 SQL_DIAG_COLUMN_NUMBER 的 DiagIdentifier 呼叫 SQLGetDiagField ，以判斷發生錯誤的數據行;而且 可以使用 SQL_DIAG_ROW_NUMBER 的 DiagIdentifier 呼叫 SQLGetDiagField ，以判斷包含該數據行的數據列。
針對所有可以傳回SQL_SUCCESS_WITH_INFO或SQL_ERROR的 SQLSTATE（01xxx SQLSTATEs 除外 SQL_SUCCESS_WITH_INFO），如果一或多個作業上發生錯誤，但不是所有多重瀏覽作業的數據列，而且如果單一數據列作業發生錯誤，則會傳回SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字串數據，右截斷 | 針對數據行傳回的字串或二進位數據，導致截斷非空白字元或非 NULL 二進位數據。 如果它是字串值，則會將其右截斷。 |
| 01S01 | 數據列中的錯誤 | 擷取一或多個數據列時發生錯誤。 （如果 ODBC 3*.x* 應用程式使用 ODBC 2*.x* 驅動程式時傳回這個 SQLSTATE，則可以忽略它。 |
| 01S06 | 嘗試在結果集傳回第一個數據列集之前擷取 | 當 FetchOrientation SQL_FETCH_PRIOR、目前位置超出第一個數據列時，要求的數據列集會重迭結果集的開頭，而目前數據列的數目小於或等於數據列集大小。 當 FetchOrientation SQL_FETCH_PRIOR時，要求的數據列集會重疊結果集的開始，目前的位置超出結果集的結尾，而數據列集大小大於結果集大小。 當 FetchOrientation SQL_FETCH_RELATIVE、FetchOffset 為負值，且 FetchOffset 的絕對值小於或等於數據列集大小時，要求的數據列集會重迭結果集的開頭。 當 FetchOrientation SQL_FETCH_ABSOLUTE時，要求的數據列集重疊結果集的開頭，FetchOffset 是負數，而 FetchOffset 的絕對值大於結果集大小，但小於或等於數據列集大小。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01S07 | 小數截斷 | 針對數據行傳回的數據已截斷。 針對數值數據類型，數位的小數部分已截斷。 針對包含時間元件的 time、timestamp 和 interval 數據類型，時間的小數部分已截斷。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 07006 | 受限制的數據類型屬性違規 | 結果集中數據行的數據值無法轉換成 SQLBindCol 中 TargetType 所指定的數據類型。 數據行 0 已系結SQL_C_BOOKMARK數據類型，且 SQL_ATTR_USE_BOOKMARKS 語句屬性設定為 SQL_UB_VARIABLE。 數據行 0 系結了數據類型為 SQL_C_VARBOOKMARK，且 SQL_ATTR_USE_BOOKMARKS 語句屬性未設定為 SQL_UB_VARIABLE。 |
| 07009 | 無效的描述元索引 | 驅動程式是不支援 SQLExtendedFetch 的 ODBC 2*.x* 驅動程式，且數據行系結中指定的數據行編號為 0。 數據行 0 已系結，且SQL_ATTR_USE_BOOKMARKS語句屬性設定為 SQL_UB_OFF。 |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| 22001 | 字串數據，右截斷 | 針對數據行傳回的可變長度書籤已截斷。 |
| 22002 | 需要指標變數，但未提供 | NULL 數據擷取到 SQLBindCol 所設定StrLen_or_IndPtr數據行中，該數據行是由 SQLSetDescField 或 SQLSetDescRec 設定的SQL_DESC_INDICATOR_PTR為 Null 指標。 |
| 22003 | 超出範圍的數值 | 傳回一或多個系結數據行的數值（作為數值或字串），會導致截斷數位的整個（而不是小數部分）。 如需詳細資訊，請參閱附錄 D：數據類型中的將數據從 SQL 轉換成 C 數據類型。 |
| 22007 | 無效的日期時間格式 | 結果集中的字元數據行已系結至日期、時間或時間戳 C 結構，而數據行中的值分別為無效的日期、時間或時間戳。 |
| 22012 | 除以零 | 傳回算術表達式的值，導致除以零。 |
| 22015 | 間隔欄位溢位 | 從確切的數值或間隔 SQL 類型指派給間隔 C 類型會導致前置欄位中的有效位數遺失。 將數據擷取至間隔 C 類型時，間隔 C 類型中沒有 SQL 類型的值表示法。 |
| 22018 | 轉換規格的字元值無效 | 結果集中的字元數據行已系結至字元 C 緩衝區，而且數據行包含的字元集沒有緩衝區字元集中的表示。 C 類型是精確或近似數值、日期時間或間隔數據類型;數據行的 SQL 類型是字元數據類型;和數據行中的值不是系結 C 型別的有效常值。 |
| 24000 | 無效的數據指標狀態 | StatementHandle 處於執行狀態，但沒有結果集與 StatementHandle 相關聯。 |
| 40001 | 串行化失敗 | 執行擷取的交易已終止，以防止死結。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLFetchScroll 函式時，這個異步函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect 或 SQLMoreResults，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。 （DM） 指定的 StatementHandle 未處於執行狀態。 未先呼叫 SQLExecDirect、SQLExecute 或目錄函式，就會呼叫函式。 （DM） 呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 （DM） 在呼叫 SQLExtendedFetch 並呼叫 sqlFreeStmt 並呼叫 SQL_CLOSE 選項之前，已針對 StatementHandle 呼叫 SQLFetch。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 無效的字串或緩衝區長度 | SQL_ATTR_USE_BOOKMARK語句屬性已設定為 SQL_UB_VARIABLE，而數據行 0 會系結至長度不等於這個結果集之書籤長度上限的緩衝區。 （此長度可在 IRD 的 SQL_DESC_OCTET_LENGTH 字段中取得，而且可藉由呼叫 來取得SQLDescribeCol、 SQLColAttribute 或 SQLGetDescField.） |
| HY106 | 擷取超出範圍的類型 | DM） 為自變數 FetchOrientation 指定的值無效。 （DM） 自變數 FetchOrientation 已SQL_FETCH_BOOKMARK，且 SQL_ATTR_USE_BOOKMARKS 語句屬性設定為 SQL_UB_OFF。 SQL_ATTR_CURSOR_TYPE語句屬性的值是SQL_CURSOR_FORWARD_ONLY，而且自變數 FetchOrientation 的值並未SQL_FETCH_NEXT。 SQL_ATTR_CURSOR_SCROLLABLE語句屬性的值是SQL_NONSCROLLABLE，而且自變數 FetchOrientation 的值並未SQL_FETCH_NEXT。 |
| HY107 | 超出範圍的數據列值 | 使用 SQL_ATTR_CURSOR_TYPE 語句屬性指定的值是SQL_CURSOR_KEYSET_DRIVEN，但以 SQL_ATTR_KEYSET_SIZE 語句屬性指定的值大於 0，而且小於使用 SQL_ATTR_ROW_ARRAY_SIZE 語句屬性指定的值。 |
| HY111 | 無效的書籤值 | 自變數 FetchOrientation 已SQL_FETCH_BOOKMARK，且 SQL_ATTR_FETCH_BOOKMARK_PTR 語句屬性中值所指向的書籤無效或為 Null 指標。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYC00 | 未實作選擇性功能 | 驅動程式或數據源不支援由 SQLBindCol 中 TargetType 與對應數據行的 SQL 資料類型組合所指定的轉換。 |
| HYT00 | 逾時已超過 | 在數據源傳回要求的結果集之前，查詢逾時期限已過期。 逾時期間是透過 SQLSetStmtAttr 來設定，SQL_ATTR_QUERY_TIMEOUT。 |
| HYT01 | 已超過連線逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
註解
SQLFetchScroll 會從結果集傳回指定的數據列集。 數據列集可以透過絕對或相對位置或書籤來指定。 只有在結果集存在時，才能呼叫 SQLFetchScroll - 也就是說，在建立結果集的呼叫之後，以及關閉該結果集上的數據指標之前。 如果系結任何數據行，則會傳回這些數據行中的數據。 如果應用程式已指定數據列狀態陣列的指標，或是傳回所擷取之數據列數目的緩衝區， SQLFetchScroll 也會傳回這項資訊。 對 SQLFetchScroll 的呼叫可以與對 SQLFetch 的呼叫混合，但無法與對 SQLExtendedFetch 的呼叫混合。
如需詳細資訊，請參閱 使用區塊數據指標 和使用 可捲動的數據指標。
定位游標
建立結果集時，游標會放在結果集的開頭之前。 SQLFetchScroll 會根據 FetchOrientation 和 FetchOffset 自變數的值來放置區塊數據指標，如下表所示。 下一節會顯示決定新數據列集開頭的確切規則。
| FetchOrientation | 意義 |
|---|---|
| SQL_FETCH_NEXT | 傳回下一個數據列集。 這相當於呼叫 SQLFetch。 SQLFetchScroll 會忽略 FetchOffset 的值。 |
| SQL_FETCH_PRIOR | 傳回先前的數據列集。 SQLFetchScroll 會忽略 FetchOffset 的值。 |
| SQL_FETCH_RELATIVE | 從目前數據列集的開頭傳回數據列集 FetchOffset 。 |
| SQL_FETCH_ABSOLUTE | 傳回從數據列 FetchOffset 開始的數據列 集。 |
| SQL_FETCH_FIRST | 傳回結果集中的第一個數據列集。 SQLFetchScroll 會忽略 FetchOffset 的值。 |
| SQL_FETCH_LAST | 傳回結果集中的最後一個完整數據列集。 SQLFetchScroll 會忽略 FetchOffset 的值。 |
| SQL_FETCH_BOOKMARK | 從 SQL_ATTR_FETCH_BOOKMARK_PTR 語句屬性所指定的書簽傳回數據列集 FetchOffset 數據列。 |
驅動程式不需要支援所有擷取方向;應用程式會使用SQL_DYNAMIC_CURSOR_ATTRIBUTES1、SQL_KEYSET_CURSOR_ATTRIBUTES1或SQL_STATIC_CURSOR_ATTRIBUTES1的信息類型來呼叫 SQLGetInfo ，以判斷驅動程式支援哪些擷取方向。 應用程式應該查看這些資訊類型中的SQL_CA1_NEXT、SQL_CA1_RELATIVE、SQL_CA1_ABSOLUTE和WQL_CA1_BOOKMARK位掩碼。 此外，如果數據指標是順向且 FetchOrientation 不是SQL_FETCH_NEXT，SQLFetchScroll 會傳回 SQLSTATE HY106（擷取超出範圍的類型）。
SQL_ATTR_ROW_ARRAY_SIZE語句屬性會指定數據列集中的數據列數目。 如果 SQLFetchScroll 所擷取的數據列集與結果集的結尾重疊，SQLFetchScroll 會傳回部分數據列集。 也就是說，如果 S + R - 1 大於 L，其中 S 是所擷取之數據列集的起始數據列，R 是數據列集大小，而 L 是結果集中的最後一個數據列，則只有數據列集的第一個 L - S + 1 個數據列有效。 其餘的數據列是空的，且狀態為 SQL_ROW_NOROW。
在 SQLFetchScroll 傳回之後，目前的數據列是數據列集的第一個數據列。
數據指標定位規則
下列各節說明 FetchOrientation 每個值的確切規則。 這些規則會使用下列表示法。
| 標記法 | 意義 |
|---|---|
| 開始之前 | 區塊數據指標位於結果集的開頭之前。 如果新數據列集的第一個數據列在結果集的開頭之前， SQLFetchScroll 會傳回SQL_NO_DATA。 |
| 結束之後 | 區塊數據指標位於結果集結尾之後。 如果新數據列集的第一個數據列是在結果集結尾之後， SQLFetchScroll 會傳回SQL_NO_DATA。 |
| CurrRowsetStart | 目前數據列集中第一個數據列的數目。 |
| LastResultRow | 結果集中最後一個數據列的數目。 |
| RowsetSize | 數據列集大小。 |
| FetchOffset | FetchOffset 自變數的值。 |
| BookmarkRow | 對應至SQL_ATTR_FETCH_BOOKMARK_PTR語句屬性所指定書籤的數據列。 |
SQL_FETCH_NEXT
適用下列規則。
| Condition | 新數據列集的第一列 |
|---|---|
| 開始之前 | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | 結束之後 |
| 結束之後 | 結束之後 |
[1] 如果數據列集大小自上一次呼叫擷取數據列之後已變更，這是與上一個呼叫搭配使用的數據列集大小。
SQL_FETCH_PRIOR
適用下列規則。
| Condition | 新數據列集的第一列 |
|---|---|
| 開始之前 | 開始之前 |
| CurrRowsetStart = 1 | 開始之前 |
| 1 < CurrRowsetStart <= RowsetSize [2] | 1 [1] |
| CurrRowsetStart > RowsetSize [2] | CurrRowsetStart - RowsetSize [2] |
| 結束之後 AND LastResultRow < RowsetSize [2] | 1 [1] |
| 結束之後 AND LastResultRow >= RowsetSize [2] | LastResultRow - RowsetSize + 1 [2] |
[1] SQLFetchScroll 會傳回 SQLSTATE 01S06（在結果集傳回第一個數據列集之前嘗試擷取），並SQL_SUCCESS_WITH_INFO。
[2] 如果數據列集大小自上一次呼叫擷取數據列之後已變更，這是新的數據列集大小。
SQL_FETCH_RELATIVE
適用下列規則。
| Condition | 新數據列集的第一列 |
|---|---|
| （開始之前和 FetchOffset > 0） 或 （結束後和 FetchOffset < 0） | --[1] |
| BeforeStart AND FetchOffset <= 0 | 開始之前 |
| CurrRowsetStart = 1 AND FetchOffset < 0 | 開始之前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | > RowsetSize [3] | 開始之前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | <= RowsetSize [3] | 1 [2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | 結束之後 |
| 結束之後 AND FetchOffset >= 0 | 結束之後 |
[1] SQLFetchScroll 會傳回與呼叫 FetchOrientation 設為SQL_FETCH_ABSOLUTE相同的數據列集。 如需詳細資訊，請參閱
[2] SQLFetchScroll 會傳回 SQLSTATE 01S06（嘗試在結果集傳回第一個數據列集之前擷取），並SQL_SUCCESS_WITH_INFO。
[3] 如果數據列集大小自上一次呼叫擷取數據列之後已變更，這是新的數據列集大小。
SQL_FETCH_ABSOLUTE
適用下列規則。
| Condition | 新數據列集的第一列 |
|---|---|
| FetchOffset < 0 AND |FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND |FetchOffset | > LastResultRow AND |FetchOffset | > RowsetSize [2] | 開始之前 |
| FetchOffset < 0 AND |FetchOffset | > LastResultRow AND |FetchOffset | <= RowsetSize [2] | 1 [1] |
| FetchOffset = 0 | 開始之前 |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | 結束之後 |
[1] SQLFetchScroll 會傳回 SQLSTATE 01S06（在結果集傳回第一個數據列集之前嘗試擷取），並SQL_SUCCESS_WITH_INFO。
[2] 如果數據列集大小自上一次呼叫擷取數據列之後已變更，這是新的數據列集大小。
針對動態數據指標執行的絕對擷取無法提供所需的結果，因為動態數據指標中的數據列位置尚未確定。 這類作業相當於先擷取，後面接著擷取相對;它不是不可部分完成的作業，靜態數據指標的絕對擷取也是一樣。
SQL_FETCH_FIRST
適用下列規則。
| Condition | 新數據列集的第一列 |
|---|---|
| 任何 | 1 |
SQL_FETCH_LAST
適用下列規則。
| Condition | 新數據列集的第一列 |
|---|---|
| RowsetSize [1]<= LastResultRow | LastResultRow - RowsetSize + 1 [1] |
| RowsetSize [1]> LastResultRow | 1 |
[1] 如果數據列集大小自上一次呼叫擷取數據列之後已變更，這是新的數據列集大小。
SQL_FETCH_BOOKMARK
適用下列規則。
| Condition | 新數據列集的第一列 |
|---|---|
| BookmarkRow + FetchOffset < 1 | 開始之前 |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | 結束之後 |
如需書籤的相關信息，請參閱 書籤 （ODBC） 。
數據指標移動時已刪除、新增和錯誤數據列的效果
靜態和索引鍵集驅動數據指標有時會偵測新增至結果集的數據列，並移除從結果集刪除的數據列。 藉由使用SQL_STATIC_CURSOR_ATTRIBUTES2和SQL_KEYSET_CURSOR_ATTRIBUTES2選項呼叫 SQLGetInfo ，並查看SQL_CA2_SENSITIVITY_ADDITIONS、SQL_CA2_SENSITIVITY_DELETIONS和SQL_CA2_SENSITIVITY_UPDATES位掩碼，應用程式會判斷特定驅動程式所實作的數據指標是否執行此動作。 對於可以偵測已刪除數據列並移除它們的驅動程式，下列段落描述此行為的影響。 對於可以偵測已刪除數據列但無法移除的驅動程式，刪除不會影響游標移動，而且下列段落不適用。
如果數據指標偵測到加入至結果集的數據列，或移除從結果集刪除的數據列，它就好像只在擷取數據時偵測到這些變更一樣。 這包括 呼叫 SQLFetchScroll 時，將 FetchOrientation 設定為 SQL_FETCH_RELATIVE 且 FetchOffset 設定為 0 以重新撰寫相同的數據列集，但不包含將 fOption 設為 SQL_REFRESH 呼叫 SQLSetPos 的情況。 在後者的情況下，數據列集緩衝區中的數據會重新整理，但不會重新整理，而且不會從結果集中移除已刪除的數據列。 因此，當數據列從目前數據列集中刪除或插入時，數據指標不會修改數據列集緩衝區。 相反地，它會在擷取先前包含已刪除數據列或現在包含插入數據列的任何數據列集時偵測變更。
例如：
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
當 SQLFetchScroll 傳回與目前數據列集相對位置的新數據列集時，即 FetchOrientation 會SQL_FETCH_NEXT、SQL_FETCH_PRIOR或SQL_FETCH_RELATIVE ，但計算新數據列集的起始位置時，不包含目前數據列集的變更。 不過，如果數據列集能夠偵測到變更，它就會包含目前數據列集以外的變更。 此外，當 SQLFetchScroll 傳回與目前數據列集無關的位置的新數據列集時，即 FetchOrientation 是SQL_FETCH_FIRST、SQL_FETCH_LAST、SQL_FETCH_ABSOLUTE或SQL_FETCH_BOOKMARK，它包含它能夠偵測的所有變更，即使它們位於目前的數據列集中也一樣。
判斷新加入的數據列是否在目前數據列集內或外部時，會將部分數據列集視為最後一個有效數據列結尾;也就是說，數據列狀態不是SQL_ROW_NOROW的最後一個數據列。 例如，假設數據指標能夠偵測新加入的數據列、目前的數據列集是部分數據列集、應用程式新增新的數據列，而數據指標會將這些數據列新增至結果集的結尾。 如果應用程式呼叫 SQLFetchScroll 並將 FetchOrientation 設定為 SQL_FETCH_NEXT，SQLFetchScroll 會傳回從第一個新加入的數據列開始的數據列集。
例如，假設目前的數據列集包含數據列 21 到 30、數據列集大小為 10、數據指標會移除從結果集刪除的數據列，而數據指標會偵測新增至結果集的數據列。 下表顯示 SQLFetchScroll 在各種情況下傳回的數據列。
| 變更 | 擷取 | FetchOffset | 新增數據列集[1] |
|---|---|---|---|
| 刪除數據列 21 | NEXT | 0 | 31 到 40 |
| 刪除數據列 31 | NEXT | 0 | 32 到 41 |
| 在數據列 21 和 22 之間插入數據列 | NEXT | 0 | 31 到 40 |
| 在數據列 30 和 31 之間插入數據列 | NEXT | 0 | 插入的數據列，31 到 39 |
| 刪除數據列 21 | PRIOR | 0 | 11 到 20 |
| 刪除數據列 20 | PRIOR | 0 | 10 到 19 人 |
| 在數據列 21 和 22 之間插入數據列 | PRIOR | 0 | 11 到 20 |
| 在數據列 20 和 21 之間插入數據列 | PRIOR | 0 | 12 到 20，插入的數據列 |
| 刪除數據列 21 | RELATIVE | 0 | 22 到 31[2] |
| 刪除數據列 21 | RELATIVE | 1 | 22 到 31 |
| 在數據列 21 和 22 之間插入數據列 | RELATIVE | 0 | 21，插入的數據列，22 到 29 |
| 在數據列 21 和 22 之間插入數據列 | RELATIVE | 1 | 22 到 31 |
| 刪除數據列 21 | ABSOLUTE | 21 | 22 到 31[2] |
| 刪除數據列 22 | ABSOLUTE | 21 | 21， 23 到 31 |
| 在數據列 21 和 22 之間插入數據列 | ABSOLUTE | 22 | 插入的數據列，22 到 29 |
[1] 此資料列會在插入或刪除任何資料列之前使用資料列編號。
[2] 在此情況下，數據指標會嘗試從第 21 列開始傳回數據列。 因為數據列 21 已刪除，所以傳回的第一個數據列是第 22 列。
錯誤資料列 （也就是狀態為 SQL_ROW_ERROR 的數據列）不會影響數據指標移動。 例如，如果目前的數據列集開頭為第 11 列，且數據列 11 的狀態為SQL_ROW_ERROR，則呼叫 SQLFetchScroll 並將 FetchOrientation 設定為 SQL_FETCH_RELATIVE 且 FetchOffset 設定為 5 會傳回從第 16 列開始的數據列集，就像第 11 列的狀態SQL_SUCCESS一樣。
傳回系結數據行中的數據
SQLFetchScroll 會以與 SQLFetch 相同的方式傳回系結數據行中的數據。 如需詳細資訊，請參閱 SQLFetch 函式中的<傳回系結數據行中的數據>。
如果沒有系結數據行，SQLFetchScroll 不會傳回數據，但會將區塊數據指標移至指定的位置。 是否可以使用 SQLGetData 從區塊數據指標的未繫結數據行擷取數據，取決於驅動程式。 如果對 SQLGetInfo 的呼叫傳回SQL_GETDATA_EXTENSIONS資訊類型的SQL_GD_BLOCK位，則支援此功能。
緩衝區位址
SQLFetchScroll 會使用相同的公式，將數據和長度/指標緩衝區的地址判斷為 SQLFetch。 如需詳細資訊，請參閱 SQLBindCol 函式中的。
資料列狀態陣列
SQLFetchScroll 會以與 SQLFetch 相同的方式，設定數據列狀態陣列中的值。 如需詳細資訊，請參閱 SQLFetch 函式中的。
擷取的數據列緩衝區
SQLFetchScroll 會以與 SQLFetch 相同的方式，傳回在擷取緩衝區中擷取的數據列數目。 如需詳細資訊，請參閱 SQLFetch 函式中的「數據列擷取緩衝區」。
錯誤處理
當應用程式在 ODBC 3.x 驅動程式中呼叫 SQLFetchScroll 時，驅動程式管理員會在驅動程式中呼叫 SQLFetchScroll 。 當應用程式在 ODBC 2.x 驅動程式中呼叫 SQLFetchScroll 時，驅動程式管理員會在驅動程式中呼叫 SQLExtendedFetch。 因為 SQLFetchScroll 和 SQLExtendedFetch 會以稍微不同的方式處理錯誤，所以當應用程式在 ODBC 2.x 和 ODBC 3.x 驅動程式中呼叫 SQLFetchScroll 時，會看到稍微不同的錯誤行為。
SQLFetchScroll 會以與 SQLFetch 相同的方式傳回錯誤和警告;如需詳細資訊，請參閱 SQLFetch 中的「錯誤處理」。 SQLExtendedFetch 會以與 SQLFetch 相同的方式傳回錯誤，但有下列例外狀況：
當發生套用至數據列集中特定數據列的警告時，SQLExtendedFetch 會將數據列狀態陣列中的對應項目設定為SQL_ROW_SUCCESS，而不是SQL_ROW_SUCCESS_WITH_INFO。
如果數據列集的每個數據列發生錯誤，SQLExtendedFetch 會傳回SQL_SUCCESS_WITH_INFO，而不是SQL_ERROR。
在每個套用至個別數據列的狀態記錄群組中，SQLExtendedFetch 傳回的第一筆狀態記錄必須包含 SQLSTATE 01S01 （數據列中的錯誤）： SQLFetchScroll 不會傳回此 SQLSTATE。 如果 SQLExtendedFetch 無法傳回其他 SQLSTATE，它仍然必須傳回此 SQLSTATE。
SQLFetchScroll 和開放式並行存取
如果數據指標使用開放式並行存取 ，也就是說，SQL_ATTR_CONCURRENCY語句屬性的值是 SQL_CONCUR_VALUES 或 SQL_CONCUR_ROWVER - SQLFetchScroll 會更新數據源用來偵測數據列是否已變更的開放式並行值。 每當 SQLFetchScroll 擷取新的數據列集時，就會發生這種情況，包括重新擷取目前數據列集時。 （呼叫時會將 FetchOrientation 設定為 SQL_FETCH_RELATIVE，而 FetchOffset 設定為 0。
SQLFetchScroll 和 ODBC 2.x 驅動程式
當應用程式在 ODBC 2.x 驅動程式中呼叫 SQLFetchScroll 時，Driver Manager 會將此呼叫對應至 SQLExtendedFetch。 它會針對 SQLExtendedFetch 的自變數傳遞下列值。
| SQLExtendedFetch 自變數 | 值 |
|---|---|
| StatementHandle | SQLFetchScroll 中的 StatementHandle。 |
| FetchOrientation | SQLFetchScroll 中的 FetchOrientation。 |
| FetchOffset | 如果未SQL_FETCH_BOOKMARK FetchOrientation，則會使用 SQLFetchScroll 中 FetchOffset 自變數的值。 如果 FetchOrientation 是SQL_FETCH_BOOKMARK，則會使用儲存在 SQL_ATTR_FETCH_BOOKMARK_PTR 語句屬性所指定位址的值。 |
| RowCountPtr | SQL_ATTR_ROWS_FETCHED_PTR 語句屬性所指定的位址。 |
| RowStatusArray | SQL_ATTR_ROW_STATUS_PTR 語句屬性所指定的位址。 |
如需詳細資訊，請參閱〈附錄 G：回溯相容性的驅動程式指導方針〉中的區塊游標、可捲動的資料指標和回溯相容性。
描述項和 SQLFetchScroll
SQLFetchScroll 會以與 SQLFetch 相同的方式與描述項互動。 如需詳細資訊，請參閱 SQLFetch 函式中的<描述項和 SQLFetchScroll>一節。
程式碼範例
請參閱 數據行明智系結、 數據列式系結、 定位的Update和Delete語句，以及 使用SQLSetPos更新數據列集中的數據列。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol 函式 |
| 執行大量插入、更新或刪除作業 | SQLBulkOperations 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回結果集中數據行的相關信息 | SQLDescribeCol 函式 |
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 以正向方向擷取單一數據列或數據區塊 | SQLFetch 函式 |
| 關閉語句上的游標 | SQLFreeStmt 函式 |
| 傳回結果集數據行的數目 | SQLNumResultCols 函式 |
| 定位數據指標、重新整理數據列集中的數據，或更新或刪除結果集中的數據 | SQLSetPos 函式 |
| 設定語句屬性 | SQLSetStmtAttr 函式 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應