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 之後的資料指標定位。

條件 新資料列集的第一列
開始之前 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 會執行下列動作：

  1. 將長度/指標緩衝區設定為SQL_Null_DATA，並在資料為 Null 時繼續下一個資料行。 如果資料是 Null，而且沒有系結長度/指標緩衝區， SQLFetch 會傳回資料列的 SQLSTATE 22002（需要但未提供指標變數），並繼續進行下一個資料列。 如需如何判斷長度/指標緩衝區位址的資訊，請參閱 SQLBindCol 中的 。

    如果資料行的資料不是 Null， SQLFetch 會繼續進行步驟 2。

  2. 如果 SQL_ATTR_MAX_LENGTH 語句屬性設定為非零值，且資料行包含字元或二進位資料，則資料會截斷為SQL_ATTR_MAX_LENGTH個位元組。

    注意

    SQL_ATTR_MAX_LENGTH 語句屬性的目的是減少網路流量。 資料來源通常會實作，它會先截斷資料，再透過網路傳回資料。 驅動程式和資料來源不需要支援它。 因此，為了保證資料被截斷為特定大小，應用程式應該配置該大小的緩衝區，並在 SQLBindCol 的 cbValueMax 引數中 指定 大小。

  3. 將資料轉換成 SQLBindCol 中 TargetType 所 指定的類型。

  4. 如果資料轉換成可變長度資料類型，例如字元或二進位 ，SQLFetch 會檢查資料的長度是否超過資料緩衝區的長度。 如果字元資料長度（包括 Null 終止字元）超過資料緩衝區的長度， SQLFetch 會將資料截斷為資料緩衝區的長度，減少 Null 終止字元的長度。 然後，它會以 Null 結束資料。 如果二進位資料的長度超過資料緩衝區的長度， SQLFetch 會將它截斷為資料緩衝區的長度。 資料緩衝區的長度是以 SQLBindCol 中的 BufferLength 指定 。

    SQLFetch 絕不會截斷轉換成固定長度資料類型的資料;它一律假設資料緩衝區的長度是資料類型的大小。

  5. 將已轉換的（且可能截斷）資料放入資料緩衝區中。 如需如何判斷資料緩衝區位址的資訊，請參閱 SQLBindCol 中的 「緩衝區位址」。

  6. 將資料的長度放在長度/指標緩衝區中。 如果指標指標和長度指標都設定為相同的緩衝區（如同對 SQLBindCol 的呼叫 一樣），則會在緩衝區中寫入有效資料的長度，並將SQL_Null_DATA寫入 Null 資料的緩衝區中。 如果沒有系結長度/指標緩衝區， SQLFetch 不會傳回長度。

    • 針對字元或二進位資料，這是轉換後的資料長度，以及因為資料緩衝區太小而截斷之前的資料長度。 如果驅動程式在轉換後無法判斷資料的長度，就如同有時候使用長資料的情況，它會將長度設定為SQL_NO_TOTAL。 如果因為 SQL_ATTR_MAX_LENGTH 語句屬性而截斷資料，則此屬性的值會放在長度/指標緩衝區中，而不是實際長度 。 這是因為此屬性的設計目的是在轉換之前截斷伺服器上的資料，因此驅動程式無法找出實際長度。

    • 對於所有其他資料類型，這是轉換後的資料長度;也就是說，它是資料轉換的目標型別大小。

    如需如何判斷長度/指標緩衝區位址的資訊，請參閱 SQLBindCol 中的 。

  7. 如果在轉換期間截斷資料，而不會遺失有效位數（例如，轉換後的實數 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 函式

另請參閱

ODBC API 參考
ODBC 標頭檔