SQLExtendedFetch 函式
一致性
引進的版本：ODBC 1.0 標準合規性：已淘汰
摘要
SQLExtendedFetch 會從結果集擷取指定的資料列集，並傳回所有系結資料行的資料。 資料列集可以在絕對位置或相對位置或書簽指定。
注意
在 ODBC 3*.x*中， SQLExtendedFetch 已由 SQLFetchScroll 取代。 ODBC 3*.x* 應用程式不應該呼叫 SQLExtendedFetch ，而是應該呼叫 SQLFetchScroll 。 使用 ODBC 2*.x* 驅動程式時，驅動程式管理員會將 SQLFetchScroll 對應 至 SQLExtendedFetch 。 如果您想要使用呼叫它的 ODBC 2*.x* 應用程式，ODBC 3*.x* 驅動程式應該支援 SQLExtendedFetch 。 如需詳細資訊，請參閱附錄 G：回溯相容性的驅動程式指導方針中的和 、可捲動的資料指標和回溯相容性 。
語法
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
引數
StatementHandle
[輸入]語句控制碼。
FetchOrientation
[輸入]擷取的類型。 這與 SQLFetchScroll 中的 FetchOrientation 相同。
FetchOffset
[輸入]要擷取的資料列數目。 這與 SQLFetchScroll 中的 FetchOffset 相同，但有一個例外狀況。 當 FetchOrientation SQL_FETCH_BOOKMARK時 ， FetchOffset 是固定長度的書簽，而不是書簽的位移。 換句話說， SQLExtendedFetch 會從這個引數擷取書簽，而不是SQL_ATTR_FETCH_BOOKMARK_PTR語句屬性。 它不支援可變長度的書簽，也不支援從書簽擷取位移 （0 以外的 0） 的資料列集。
RowCountPtr
[輸出]緩衝區的指標，用來傳回實際擷取的資料列數目。 這個緩衝區與 SQL_ATTR_ROWS_FETCHED_PTR 語句屬性所指定的緩衝區相同。 此緩衝區僅供 SQLExtendedFetch 使用。 SQLFetch 或 SQLFetchScroll 不會使用它 。
RowStatusArray
[輸出]陣列的指標，用來傳回每個資料列的狀態。 此陣列會以與 SQL_ATTR_ROW_STATUS_PTR 語句屬性所指定的陣列相同方式使用。
不過，此陣列的位址不會儲存在 IRD 的 SQL_DESC_STATUS_ARRAY_PTR 欄位中。 此外，當 SQLExtendedFetch 呼叫 SQLExtendedFetch 之後呼叫此陣列時 ，只有 SQLExtendedFetch 和 SQLBulkOperations 搭配 operation of SQL_ADD 或 SQLSetPos 使用。 SQLFetch 或 SQLFetchScroll 不會使用它 ，而且在 SQLFetch 或 SQLFetchScroll 之後 呼叫 SQLBulkOperations 或 SQLSetPos 時，不會使用 SQLBulkOperations 或 SQLSetPos 。 呼叫 任何擷取函式之前，呼叫具有 SQL_ADD 作業 的 SQLBulkOperations 時，也不會使用它。 換句話說，它只會用於語句狀態 S7。 語句中不會使用 S5 或 S6。 如需詳細資訊，請參閱 附錄 B：ODBC 狀態轉換資料表中的語句轉換 。
應用程式應該在 RowStatusArray 引數中 提供有效的指標;如果不是，SQLExtendedFetch 的行為，以及在 SQLExtendedFetch 定位資料指標 之後呼叫 SQLBulkOperations 或 SQLSetPos 的行為 是未定義的。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLExtendedFetch 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以藉由呼叫 SQLError 來取得相關聯的 SQLSTATE 值。 下表列出 SQLExtendedFetch 通常傳 回的 SQLSTATE 值，並在此函式的內容中說明每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。 如果在單一資料行上發生錯誤， 可以使用 SQL_DIAG_COLUMN_NUMBER 的 DiagIdentifier 呼叫 SQLGetDiagField ，以判斷發生錯誤的資料行;而且 可以使用 SQL_DIAG_ROW_NUMBER 的 DiagIdentifier 呼叫 SQLGetDiagField ，以判斷包含該資料行的資料列。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字串資料，右截斷 | 針對資料行傳回的字串或二進位資料，導致截斷非空白字元或非 Null 二進位資料。 如果它是字串值，則會將其右截斷。 如果是數值，則會截斷數位的小數部分。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01S01 | 資料列中的錯誤 | 擷取一或多個資料列時發生錯誤。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01S06 | 嘗試在結果集傳回第一個資料列集之前擷取 | 當目前位置超出第一個資料列時，要求的資料列集會重迭結果集的開始，而且 FetchOrientation 已SQL_PRIOR或 FetchOrientation 已SQL_RELATIVE負 的 FetchOffset ，其絕對值小於或等於目前的SQL_ROWSET_SIZE。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01S07 | 小數截斷 | 針對資料行傳回的資料已截斷。 針對數值資料類型，數位的小數部分已截斷。 針對包含時間元件的 time、timestamp 和 interval 資料類型，時間的小數部分已截斷。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 07006 | 受限制的資料類型屬性違規 | 資料值無法轉換成 SQLBindCol 中 TargetType 所 指定的 C 資料類型。 |
| 07009 | 不正確描述元索引 | 資料行 0 與 SQLBindCol 系結，且 SQL_ATTR_USE_BOOKMARKS 語句屬性設定為 SQL_UB_OFF。 |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。 |
| 22002 | 需要指標變數，但未提供 | Null 資料擷取到 SQLBindCol 所 設定StrLen_or_IndPtr 為 Null 指標的資料行。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 22003 | 超出範圍的數值 | 傳回一或多個資料行的數值（作為數值或字串），會導致截斷數位的整個（而不是小數部分）。 （函式會傳回SQL_SUCCESS_WITH_INFO。） 如需詳細資訊，請參閱 附錄 D：資料類型中的間隔和數值資料類型 指導方針。 |
| 22007 | 不正確日期時間格式 | 結果集中的字元資料行已系結至日期、時間或時間戳記 C 結構，而資料行中的值分別為不正確日期、時間或時間戳記。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 22012 | 除以零 | 傳回算術運算式的值，導致除以零。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 22015 | 間隔欄位溢位 | 從確切的數值或間隔 SQL 類型指派給間隔 C 類型會導致前置欄位中的有效位數遺失。 將資料擷取至間隔 C 類型時，間隔 C 類型中沒有 SQL 類型的值標記法。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 22018 | 轉換規格的字元值無效 | C 類型是精確或近似數值、日期時間或間隔資料類型;資料行的 SQL 類型是字元資料類型;和 資料行中的值不是系結 C 型別的有效常值。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 24000 | 不正確資料指標狀態 | StatementHandle 處於執行狀態，但沒有結果集與 StatementHandle 相關聯。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLError 傳 回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用非同步處理。 已呼叫函式，並在完成執行之前， 在 StatementHandle 上 呼叫 SQLCancel 或 SQLCancelHandle ，然後在 StatementHandle 上 再次呼叫函式。 呼叫函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 語句Handle 或 SQLCancelHandle 。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLExtendedFetch 函式時 ，這個非同步函式仍在執行中。 （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） 在呼叫 SQLFetch 或 SQLFetchScroll 之後 ，以及使用 SQL_CLOSE 選項呼叫 SQLFreeStmt 之前 ，已針對 StatementHandle 呼叫 SQLExtendedFetch 。 （DM） SQLBulkOperations 在呼叫 SQLFetch、 SQLFetchScroll 或 SQLExtendedFetch 之前 呼叫語句，然後在 使用 SQL_CLOSE 選項呼叫 SQLFreeStmt 之前 呼叫 SQLExtendedFetch 。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY106 | 擷取超出範圍的類型 | （DM） 為引數 FetchOrientation 指定的值無效。 （請參閱「批註」。） fetchOrientation 引數 已SQL_FETCH_BOOKMARK，且 SQL_ATTR_USE_BOOKMARKS 語句屬性設定為 SQL_UB_OFF。 SQL_CURSOR_TYPE語句選項的值是SQL_CURSOR_FORWARD_ONLY，而且引數 FetchOrientation 的值並未SQL_FETCH_NEXT。 fetchOrientation 引數 已SQL_FETCH_RESUME。 |
| HY107 | 超出範圍的資料列值 | 使用 SQL_CURSOR_TYPE 語句選項指定的值是SQL_CURSOR_KEYSET_DRIVEN，但以 SQL_KEYSET_SIZE 語句屬性指定的值大於 0，而且小於使用 SQL_ROWSET_SIZE 語句屬性指定的值。 |
| HY111 | 不正確書簽值 | 引數 FetchOrientation 已SQL_FETCH_BOOKMARK，而且 FetchOffset 引數中指定的 書簽無效。 |
| HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。 |
| HYC00 | 未實作選擇性功能 | 驅動程式或資料來源不支援指定的擷取類型。 驅動程式或資料來源不支援由 SQLBindCol 中 TargetType 與對應資料行的 SQL 資料類型組合所指定的轉換。 只有當資料行的 SQL 資料類型對應至驅動程式特定的 SQL 資料類型時，才會發生此錯誤。 |
| HYT00 | 逾時已超過 | 資料來源傳回結果集之前，查詢逾時期限已過期。 逾時期間是透過 SQLSetStmtOption 設定，SQL_QUERY_TIMEOUT。 |
| HYT01 | 已超過連線逾時 | 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
註解
SQLExtendedFetch 的行為與 SQLFetchScroll 的行為 相同，但有下列例外狀況：
SQLExtendedFetch 和 SQLFetchScroll 使用不同的方法來傳回所擷取的資料列數目。 SQLExtendedFetch 會傳回 *RowCountPtr 中 擷取的資料列數目; SQLFetchScroll 會傳回直接擷取到SQL_ATTR_ROWS_FETCHED_PTR所指向之緩衝區的資料列數目。 如需詳細資訊，請參閱 RowCountPtr 引數。
SQLExtendedFetch 和 SQLFetchScroll 會傳回不同陣列中每個資料列的狀態。 如需詳細資訊，請參閱 RowStatusArray 引數。
當 FetchOrientation SQL_FETCH_BOOKMARK時 ，SQLExtendedFetch 和 SQLFetchScroll 使用不同的方法來擷取書簽。 SQLExtendedFetch 不支援可變長度書簽，或從書簽擷取 0 以外的位移擷取資料列集。 如需詳細資訊，請參閱 FetchOffset 引數。
SQLExtendedFetch 和 SQLFetchScroll 使用不同的資料列集大小。 SQLExtendedFetch 會使用 SQL_ROWSET_SIZE 語句屬性的值，而 SQLFetchScroll 會使用 SQL_ATTR_ROW_ARRAY_SIZE 語句屬性的值。
SQLExtendedFetch 的錯誤處理語意與 SQLFetchScroll 稍有不同。 如需詳細資訊，請參閱 SQLFetchScroll 的一節中的 。
SQLExtendedFetch 不支援系結位移（SQL_ATTR_ROW_BIND_OFFSET_PTR語句屬性）。
對 SQLExtendedFetch 的 呼叫無法與對 SQLFetch 或 SQLFetchScroll 的呼叫 混合，而且如果在 呼叫任何提取函式之前呼叫 SQLBulkOperations ， 則必須先關閉並重新開啟資料指標，才能呼叫 SQLExtendedFetch 。 也就是說， SQLExtendedFetch 只能在語句狀態 S7 中呼叫。 如需詳細資訊，請參閱 附錄 B：ODBC 狀態轉換資料表中的語句轉換 。
當應用程式在使用 ODBC 2*.x* 驅動程式時呼叫 SQLFetchScroll 時，驅動程式管理員會將此呼叫對應至 SQLExtendedFetch 。 如需詳細資訊，請參閱 SQLFetchScroll 和 SQLFetchScroll 中的 ODBC 2*.x* 驅動程式。
在 ODBC 2*.x*中， 呼叫 SQLExtendedFetch 來擷取多個資料列，並 呼叫 SQLFetch 來擷取單一資料列。 另一方面，在 ODBC 3*.x*中， 可以呼叫 SQLFetch 來擷取 多個資料列。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol 函式 |
| 執行大量插入、更新或刪除作業 | SQLBulkOperations 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回結果集中資料行的相關資訊 | SQLDescribeCol 函式 |
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 傳回結果集資料行的數目 | SQLNumResultCols 函式 |
| 定位資料指標、重新整理資料列集中的資料，或更新或刪除結果集中的資料 | SQLSetPos 函式 |
| 設定語句屬性 | SQLSetStmtAttr 函式 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應