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
適用下列規則。
條件 | 新資料列集的第一列 |
---|---|
開始之前 | 1 |
CurrRowsetStart + RowsetSize [1] < = LastResultRow | CurrRowsetStart + RowsetSize [1] |
CurrRowsetStart + RowsetSize [1] > LastResultRow | 結束之後 |
結束之後 | 結束之後 |
[1] 如果資料列集大小自上一次呼叫擷取資料列之後已變更,這是與上一個呼叫搭配使用的資料列集大小。
SQL_FETCH_PRIOR
適用下列規則。
條件 | 新資料列集的第一列 |
---|---|
開始之前 | 開始之前 |
CurrRowsetStart = 1 | 開始之前 |
1 < CurrRowsetStart < = RowsetSize [2] | 1 [1] |
CurrRowsetStart > RowsetSize [2] | CurrRowsetStart - RowsetSize [2] |
結束之後 AND LastResultRow < RowsetSize [2] | 1 [1] |
End AND LastResultRow > = RowsetSize [2] | LastResultRow - RowsetSize + 1 [2] |
[1] SQLFetchScroll 會傳回 SQLSTATE 01S06(在結果集傳回第一個資料列集之前嘗試擷取),並SQL_SUCCESS_WITH_INFO。
[2] 如果資料列集大小自上一次呼叫擷取資料列之後已變更,這是新的資料列集大小。
SQL_FETCH_RELATIVE
適用下列規則。
條件 | 新資料列集的第一列 |
---|---|
(開始之前和 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
適用下列規則。
條件 | 新資料列集的第一列 |
---|---|
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
適用下列規則。
條件 | 新資料列集的第一列 |
---|---|
Any | 1 |
SQL_FETCH_LAST
適用下列規則。
條件 | 新資料列集的第一列 |
---|---|
RowsetSize [1] < = LastResultRow | LastResultRow - RowsetSize + 1 [1] |
RowsetSize [1] > LastResultRow | 1 |
[1] 如果資料列集大小自上一次呼叫擷取資料列之後已變更,這是新的資料列集大小。
SQL_FETCH_BOOKMARK
適用下列規則。
條件 | 新資料列集的第一列 |
---|---|
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 函式 |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應