SQLFetch 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLFetch 會從結果集擷取下一個數據列集，並傳回所有綁定數據行的數據。
語法
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
引數
StatementHandle
[輸入]語句句柄。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLFetch 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以使用SQL_HANDLE_STMT的 HandleType 和 StatementHandle 的 HandleType 呼叫 SQLGetDiagRec 函式來取得相關聯的 SQLSTATE 值。 下表列出 SQLFetch 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。 如果在單一數據行上發生錯誤，可以使用 SQL_DIAG_COLUMN_NUMBER 的 DiagIdentifier 呼叫 SQLGetDiagField，以判斷發生錯誤的數據行;而 SQLGetDiagField 可以使用 SQL_DIAG_ROW_NUMBER 的 DiagIdentifier 呼叫，以判斷包含該數據行的數據列。
針對所有可以傳回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，則可以忽略它。 |
| 01S07 | 小數截斷 | 針對數據行傳回的數據已截斷。 針對數值數據類型，數位的小數部分已截斷。 對於包含時間元件的時間、時間戳和間隔數據類型，截斷時間的小數部分。 （函式會傳回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 啟用異步處理。 已呼叫 SQLFetch 函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後，在 StatementHandle 上再次呼叫 SQLFetch 函式。 或者，呼叫 SQLFetch 函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫 SQLCancel 或 SQLCancelHandle。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLFetch 函式時，這個異步函式仍在執行中。 （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.） |
| HY107 | 超出範圍的數據列值 | 使用 SQL_ATTR_CURSOR_TYPE 語句屬性指定的值是SQL_CURSOR_KEYSET_DRIVEN，但以 SQL_ATTR_KEYSET_SIZE 語句屬性指定的值大於 0，而且小於使用 SQL_ATTR_ROW_ARRAY_SIZE 語句屬性指定的值。 |
| 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 ，才能執行後續處理並完成作業。 |
註解
SQLFetch 會傳回結果集中的下一個數據列集。 只有在結果集存在時，才能呼叫它：也就是在建立結果集的呼叫之後，以及關閉該結果集上的數據指標之前。 如果系結任何數據行，則會傳回這些數據行中的數據。 如果應用程式已指定數據列狀態陣列的指標，或是傳回所擷取之數據列數目的緩衝區， SQLFetch 也會傳回這項資訊。 對 SQLFetch 的呼叫可以與對 SQLFetchScroll 的呼叫混合，但無法與對 SQLExtendedFetch 的呼叫混合。 如需詳細資訊，請參閱 擷取數據列。
如果 ODBC 3*.x* 應用程式與 ODBC 2*.x* 驅動程式搭配運作，Driver Manager 會將 SQLFetch 呼叫對應至 SQLExtendedFetch，以取得支援 SQLExtendedFetch 的 ODBC 2*.x* 驅動程式。 如果 ODBC 2*.x* 驅動程式不支援 SQLExtendedFetch，驅動程式管理員會將 SQLFetch 呼叫對應至 ODBC 2*.x* 驅動程式中的 SQLFetch，而該驅動程式只能擷取單一數據列。
如需詳細資訊，請參閱〈附錄 G：回溯相容性的驅動程式指導方針〉中的區塊游標、可捲動的資料指標和回溯相容性。
定位游標
建立結果集時，游標會放在結果集的開頭之前。 SQLFetch 會擷取 下一個數據列集。 它相當於呼叫 SQLFetchScroll ，並將 FetchOrientation 設定為 SQL_FETCH_NEXT。 如需數據指標的詳細資訊，請參閱 數據指標 和 區塊數據指標。
SQL_ATTR_ROW_ARRAY_SIZE語句屬性會指定數據列集中的數據列數目。 如果 SQLFetch 所擷取的數據列集與結果集的結尾重疊，SQLFetch 會傳回部分數據列集。 也就是說，如果 S + R - 1 大於 L，其中 S 是所擷取之數據列集的起始數據列，R 是數據列集大小，而 L 是結果集中的最後一個數據列，則只有數據列集的第一個 L - S + 1 個數據列有效。 其餘的數據列是空的，且狀態為 SQL_ROW_NOROW。
在 SQLFetch 傳回之後，目前的數據列是數據列集的第一個數據列。
下表所列的規則會根據本節中第二個數據表所列的條件，描述呼叫 SQLFetch 之後的數據指標定位。
| Condition | 新數據列集的第一列 |
|---|---|
| 開始之前 | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | 結束之後 |
| 結束之後 | 結束之後 |
[1] 如果在擷取之間變更數據列集大小，這是與先前擷取搭配使用的數據列集大小。
[2] 如果在擷取之間變更數據列集大小，這是與新擷取搭配使用的數據列集大小。
| 標記法 | 意義 |
|---|---|
| 開始之前 | 區塊數據指標位於結果集的開頭之前。 如果新數據列集的第一個數據列是在結果集開頭之前， SQLFetch 會傳回SQL_NO_DATA。 |
| 結束之後 | 區塊數據指標位於結果集結尾之後。 如果新數據列集的第一個數據列是在結果集結尾之後， SQLFetch 會傳回SQL_NO_DATA。 |
| CurrRowsetStart | 目前數據列集中第一個數據列的數目。 |
| LastResultRow | 結果集中最後一個數據列的數目。 |
| RowsetSize | 數據列集大小。 |
例如，假設結果集有100個數據列，而數據列集大小為5。 下表顯示 SQLFetch 針對不同起始位置傳回的數據列集和傳回碼。
| 目前的數據列集 | 傳回碼 | 新增數據列集 | 擷取的數據列數目 |
|---|---|---|---|
| 開始之前 | SQL_SUCCESS | 1 到 5 人 | 5 |
| 1 到 5 人 | SQL_SUCCESS | 6 到 10 | 5 |
| 52 到 56 | SQL_SUCCESS | 57 到 61 | 5 |
| 91 到 95 | SQL_SUCCESS | 96 到 100 | 5 |
| 93 到 97 | SQL_SUCCESS | 98 到 100。 數據列狀態陣列的數據列 4 和 5 會設定為 SQL_ROW_NOROW。 | 3 |
| 96 到 100 | SQL_NO_DATA | 無。 | 0 |
| 99 到 100 | SQL_NO_DATA | 無。 | 0 |
| 結束之後 | SQL_NO_DATA | 無。 | 0 |
傳回系結數據行中的數據
當 SQLFetch 傳回每個數據列時，會將每個系結數據行的數據放入系結至該數據行的緩衝區中。 如果沒有系結數據行，SQLFetch 不會傳回任何數據，但會向前移動區塊數據指標。 數據仍然可以使用 SQLGetData 來擷取。 如果數據指標是多重流覽數據指標（也就是SQL_ATTR_ROW_ARRAY_SIZE大於 1），則只有在使用 infoType SQL_GETDATA_EXTENSIONS 呼叫 SQLGetInfo 時傳回SQL_GD_BLOCK時，才能呼叫 SQLGetData。 （如需詳細資訊，請參閱 SQLGetData.）
針對數據列中的每個系結數據行， SQLFetch 會執行下列動作：
將長度/指標緩衝區設定為SQL_NULL_DATA，並在數據為 NULL 時繼續下一個數據行。 如果數據是 NULL，而且沒有系結長度/指標緩衝區， SQLFetch 會傳回數據列的 SQLSTATE 22002（需要但未提供指標變數），並繼續進行下一個數據列。 如需如何判斷長度/指標緩衝區地址的資訊，請參閱 SQLBindCol 中的。
如果數據行的數據不是 NULL，SQLFetch 會繼續進行步驟 2。
如果 SQL_ATTR_MAX_LENGTH 語句屬性設定為非零值，且數據行包含字元或二進位數據，則數據會截斷為SQL_ATTR_MAX_LENGTH個字節。
注意
SQL_ATTR_MAX_LENGTH 語句屬性的目的是減少網路流量。 數據源通常會實作，它會先截斷數據，再透過網路傳回數據。 驅動程式和數據源不需要支援它。 因此，為了保證數據被截斷為特定大小，應用程式應該配置該大小的緩衝區，並在 SQLBindCol 的 cbValueMax 自變數中 指定大小。
將數據轉換成 SQLBindCol 中 TargetType 所指定的類型。
如果數據轉換成可變長度數據類型，例如字元或二進位 ，SQLFetch 會檢查數據的長度是否超過數據緩衝區的長度。 如果字元數據長度（包括 Null 終止字元）超過數據緩衝區的長度， SQLFetch 會將數據截斷為數據緩衝區的長度，減少 Null 終止字元的長度。 然後，它會以 Null 結束數據。 如果二進位數據的長度超過數據緩衝區的長度， SQLFetch 會將它截斷為數據緩衝區的長度。 數據緩衝區的長度是以 SQLBindCol 中的 BufferLength 指定。
SQLFetch 絕不會截斷轉換成固定長度數據類型的數據;它一律假設數據緩衝區的長度是數據類型的大小。
將已轉換的（且可能截斷）數據放入數據緩衝區中。 如需如何判斷數據緩衝區位址的資訊，請參閱 SQLBindCol 中的「緩衝區位址」。
將數據的長度放在長度/指標緩衝區中。 如果指標指標指標和長度指標都設定為相同的緩衝區（如同對 SQLBindCol 的呼叫一樣），則會在緩衝區中寫入有效數據的長度，並將SQL_NULL_DATA寫入 NULL 數據的緩衝區中。 如果沒有系結長度/指標緩衝區， SQLFetch 不會傳回長度。
針對字元或二進位數據，這是轉換后的數據長度，以及因為數據緩衝區太小而截斷之前的數據長度。 如果驅動程式在轉換后無法判斷數據的長度，就如同有時候使用長數據的情況，它會將長度設定為SQL_NO_TOTAL。 如果因為 SQL_ATTR_MAX_LENGTH 語句屬性而截斷資料，則此屬性的值會放在長度/指標緩衝區中，而不是實際長度 。 這是因為此屬性的設計目的是在轉換之前截斷伺服器上的數據，因此驅動程式無法找出實際長度。
對於所有其他數據類型，這是轉換后的數據長度;也就是說，它是數據轉換的目標類型大小。
如需如何判斷長度/指標緩衝區地址的資訊，請參閱 SQLBindCol 中的。
如果在轉換期間截斷數據，而不會遺失有效位數（例如，轉換后的實數 1.234 會截斷為整數 1）， SQLFetch 會傳回 SQLSTATE 01S07（小數截斷）和SQL_SUCCESS_WITH_INFO。 如果數據被截斷，因為數據緩衝區的長度太小（例如，字元串 」abcdef“ 會放在 4 位元組緩衝區中）， SQLFetch 會傳回 SQLSTATE 01004 （數據截斷）和SQL_SUCCESS_WITH_INFO。 如果因為SQL_ATTR_MAX_LENGTH語句屬性而截斷數據， SQLFetch 會傳回SQL_SUCCESS，而且不會傳回 SQLSTATE 01S07 （小數截斷）或 SQLSTATE 01004 （數據截斷）。 如果在轉換期間截斷數據，但遺失了有效位數（例如，如果SQL_INTEGER值大於 100,000 已轉換為SQL_C_TINYINT）， SQLFetch 會傳回 SQLSTATE 22003（超出範圍的數值），SQL_ERROR（如果數據列集大小為 1）或SQL_SUCCESS_WITH_INFO（如果數據列集大小大於 1）。
如果 SQLFetch 或 SQLFetchScroll 未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，系結數據緩衝區和長度/指標緩衝區的內容為未定義。
資料列狀態陣列
數據列狀態陣列是用來傳回數據列集中每個數據列的狀態。 這個陣列的位址是使用 SQL_ATTR_ROW_STATUS_PTR 語句屬性來指定。 陣列是由應用程式所配置，而且必須有SQL_ATTR_ROW_ARRAY_SIZE語句屬性所指定的元素數目。 其值是由 SQLFetch、SQLFetchScroll 和 SQLBulkOperations 或 SQLSetPos 所設定（除非在 SQLExtendedFetch 定位數據指標之後呼叫它們）。 如果 SQL_ATTR_ROW_STATUS_PTR 語句屬性的值是 Null 指標，則這些函式不會傳回數據列狀態。
如果 SQLFetch 或 SQLFetchScroll 未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，則數據列狀態陣列緩衝區的內容未定義。
下列值會在數據列狀態陣列中傳回。
| 資料列狀態陣列值 | Description |
|---|---|
| SQL_ROW_SUCCESS | 已成功擷取數據列，而且自上次從這個結果集擷取之後，尚未變更。 |
| SQL_ROW_SUCCESS_WITH_INFO | 已成功擷取數據列，而且自上次從這個結果集擷取之後，尚未變更。 不過，系統有傳回關於該資料列的警告。 |
| SQL_ROW_ERROR | 擷取該資料列時發生錯誤。 |
| SQL_ROW_UPDATED[1]，[2]， 和 [3] | 數據列已成功擷取，且自上次從此結果集擷取之後已變更。 如果從這個結果集再次擷取數據列，或由 SQLSetPos 重新整理，狀態就會變更為數據列的新狀態。 |
| SQL_ROW_DELETED[3] | 自從上次從這個結果集擷取數據列之後，數據列已經刪除。 |
| SQL_ROW_ADDED[4] | 該資料列由 SQLBulkOperations 插入。 如果數據列再次從這個結果集擷取，或由 SQLSetPos 重新整理，則其狀態為SQL_ROW_SUCCESS。 |
| SQL_ROW_NOROW | 資料列集與結果集的結尾重疊，而且沒有傳回任何對應到資料列狀態陣列中這個元素的資料列。 |
[1] 對於索引鍵集、混合和動態數據指標，如果索引鍵值已更新，則會將數據列視為已刪除，並加入新的數據列。
[2] 某些驅動程式無法偵測數據的更新，因此無法傳回此值。 若要判斷驅動程式是否可以偵測重新擷取之資料列的更新，應用程式會使用 SQL_ROW_UPDATES 選項呼叫 SQLGetInfo。
[3] 只有當 SQLFetch 與對 SQLFetchScroll 的呼叫混在一起時，SQLFetch 才能傳回此值。 這是因為 SQLFetch 會透過結果集向前移動，而且當它獨佔使用時，不會重新整理任何數據列。 由於未重新編列， 因此 SQLFetch 不會偵測對先前擷取的數據列所做的變更。 不過，如果 SQLFetchScroll 將游標放在任何先前擷取的數據列之前，而 SQLFetch 則用來擷取這些數據列，SQLFetch 可以偵測這些數據列的任何變更。
[4] 只有 SQLBulkOperations 傳回。 未由 SQLFetch 或 SQLFetchScroll 設定。
擷取的數據列緩衝區
擷取的數據列緩衝區是用來傳回所擷取的數據列數目，包括因為擷取數據時發生錯誤而未傳回數據的列數。 換句話說，這是數據列狀態陣列中值未SQL_ROW_NOROW的數據列數目。 這個緩衝區的位址是使用 SQL_ATTR_ROWS_FETCHED_PTR 語句屬性來指定。 緩衝區是由應用程式所配置。 它是由 SQLFetch 和 SQLFetchScroll 所設定。 如果 SQL_ATTR_ROWS_FETCHED_PTR 語句屬性的值是 Null 指標，則這些函式不會傳回所擷取的數據列數目。 若要判斷結果集中目前數據列的數目，應用程式可以使用 SQL_ATTR_ROW_NUMBER 屬性呼叫 SQLGetStmtAttr 。
如果 SQLFetch 或 SQLFetchScroll 不會傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，則擷取緩衝區的內容是未定義的，除非傳回SQL_NO_DATA，在此情況下，擷取緩衝區中的數據列值會設定為 0。
錯誤處理
錯誤和警告可以套用至個別數據列或整個函式。 如需診斷記錄的詳細資訊，請參閱 診斷 和 SQLGetDiagField。
整個函式上的錯誤和警告
如果錯誤適用於整個函式，例如 SQLSTATE HYT00 （逾時過期）或 SQLSTATE 24000 （資料指標狀態無效）， SQLFetch 會傳回SQL_ERROR和適用的 SQLSTATE。 數據列集緩衝區的內容未定義，且數據指標位置不變。
如果警告適用於整個函式， SQLFetch 會傳回SQL_SUCCESS_WITH_INFO和適用的 SQLSTATE。 套用至整個函式之警告的狀態記錄會在套用至個別數據列的狀態記錄之前傳回。
個別數據列中的錯誤和警告
如果錯誤 （例如 SQLSTATE 22012 （除以零）或警告 （例如 SQLSTATE 01004 （數據截斷）套用至單一數據列， SQLFetch會執行下列動作：
將數據列狀態陣列的對應項目設定為SQL_ROW_ERROR錯誤或警告SQL_ROW_SUCCESS_WITH_INFO。
新增零個或多個狀態記錄，其中包含錯誤或警告的 SQLSTATE。
設定狀態記錄中的數據列和數據行編號欄位。 如果 SQLFetch 無法判斷數據列或數據行編號，則會將該數位分別設定為SQL_ROW_NUMBER_UNKNOWN或SQL_COLUMN_NUMBER_UNKNOWN。 如果狀態記錄不適用於特定數據行， SQLFetch 會將數據行編號設定為SQL_NO_COLUMN_NUMBER。
SQLFetch 會繼續擷取數據列，直到它擷取數據列集中的所有數據列為止。 除非數據列集的每個數據列發生錯誤（不包括狀態為SQL_ROW_NOROW的數據列），否則它會傳回SQL_ERROR，否則它會傳回SQL_SUCCESS_WITH_INFO。 特別是，如果數據列集大小為 1 且該數據列中發生錯誤， SQLFetch 會傳回SQL_ERROR。
SQLFetch 會以數據列編號順序傳回狀態記錄。 也就是說，它會傳回未知數據列的所有狀態記錄（如果有）：接下來，它會傳回第一個數據列的所有狀態記錄（如果有的話），然後傳回第二個數據列的所有狀態記錄（如果有的話），依此傳回。 每個數據列的狀態記錄會根據排序狀態記錄的一般規則來排序;如需詳細資訊，請參閱 SQLGetDiagField 中的。
描述項和 SQLFetch
下列各節說明 SQLFetch 如何與描述項互動。
自變數對應
驅動程式不會根據 SQLFetch 的自變數來設定任何描述元欄位。
其他描述元欄位
SQLFetch 會使用下列描述元欄位。
| 描述項欄位 | Desc. | 中的欄位 | 設定至 |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | 標頭 | SQL_ATTR_ROW_ARRAY_SIZE語句屬性 |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | 標頭 | SQL_ATTR_ROW_STATUS_PTR 語句屬性 |
| SQL_DESC_BIND_OFFSET_PTR | ARD | 標頭 | SQL_ATTR_ROW_BIND_OFFSET_PTR 語句屬性 |
| SQL_DESC_BIND_TYPE | ARD | 標頭 | SQL_ATTR_ROW_BIND_TYPE 語句屬性 |
| SQL_DESC_COUNT | ARD | 標頭 | SQLBindCol 的 ColumnNumber 自變數 |
| SQL_DESC_DATA_PTR | ARD | 記錄 | SQLBindCol 的 TargetValuePtr 自變數 |
| SQL_DESC_INDICATOR_PTR | ARD | 記錄 | SQLBindCol 中的 StrLen_or_IndPtr 自變數 |
| SQL_DESC_OCTET_LENGTH | ARD | 記錄 | SQLBindCol 中的 BufferLength 自變數 |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | 記錄 | SQLBindCol 中的 StrLen_or_IndPtr 自變數 |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | 標頭 | SQL_ATTR_ROWS_FETCHED_PTR語句屬性 |
| SQL_DESC_TYPE | ARD | 記錄 | SQLBindCol 中的 TargetType 自變數 |
所有描述元欄位也可以透過 SQLSetDescField 來設定。
分隔長度和指標緩衝區
應用程式可以系結單一緩衝區或兩個不同的緩衝區，以用來保存長度和指標值。 當應用程式呼叫 SQLBindCol 時，驅動程式會將 ARD 的SQL_DESC_OCTET_LENGTH_PTR和SQL_DESC_INDICATOR_PTR欄位設定為相同位址，而此位址會在 StrLen_or_IndPtr 自變數中傳遞。 當應用程式呼叫 SQLSetDescField 或 SQLSetDescRec 時，可以將這兩個字段設定為不同的位址。
SQLFetch 會判斷應用程式是否指定了個別的長度和指標緩衝區。 在此情況下，當數據不是 NULL 時，SQLFetch 會將指標緩衝區設定為 0，並傳回長度緩衝區中的長度。 當數據為 NULL 時， SQLFetch 會將指標緩衝區設定為SQL_NULL_DATA，而且不會修改長度緩衝區。
程式碼範例
請參閱 SQLBindCol、 SQLColumns、 SQLGetData 和 SQLProcedures。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回結果集中數據行的相關信息 | SQLDescribeCol 函式 |
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 擷取數據區塊或捲動結果集 | SQLFetchScroll 函式 |
| 關閉語句上的游標 | SQLFreeStmt 函式 |
| 擷取部分或所有數據行的數據 | SQLGetData 函式 |
| 傳回結果集數據行的數目 | SQLNumResultCols 函式 |
| 準備語句以供執行 | SQLPrepare 函式 |