SQLExtendedFetch -提取列的陣列

線上編輯

SQLExtendedFetch() 會針對每一個連結直欄，以陣列形式傳回包含多列 (稱為 列集) 的資料區塊，以延伸 SQLFetch() 的函數。 列集的大小由 SQLSetStmtAttr() 呼叫上的 SQL_ROWSET_SIZE 屬性決定。

若要一次提取一列資料，應用程式應該呼叫 SQLFetch()。

語法

SQLRETURN   SQLExtendedFetch (SQLHSTMT          StatementHandle,
                              SQLSMALLINT       FetchOrientation,
                              SQLINTEGER        FetchOffset,
                              SQLINTEGER        *RowCountPtr,
                              SQLSMALLINT       *RowStatusArray);

函數引數

表 1. SQLExtendedFetch 引數
資料類型 引數 使用 說明
SQLHSTMT StatementHandle 輸入 陳述式控點。
SQLSMALLINT FetchOrientation 輸入 提取方向。 如需可能的值，請參閱 表 2 。
SQLINTEGER FetchOffset 輸入 相對定位的列偏移。
SQLINTEGER * RowCountPtr 輸出 實際提取的列數。 如果在處理期間發生錯誤， RowCountPtr 會指向發生錯誤之列之前的列 (列集中) 序數位置。 如果擷取第一列 RowCountPtr 時發生錯誤，則會指向值 0。
SQLSMALLINT * RowStatus陣列 輸出 狀態值的陣列。 元素數目必須等於列集中的列數 (如 SQL_ROWSET_SIZE 屬性所定義)。 會傳回提取的每一列的狀態值:
  • SQL_ROW_SUCCESS

如果提取的列數小於狀態陣列中的元素數 (亦即，小於列集大小) ，則剩餘狀態元素會設為 SQL_ROW_NOROW。

Db2® for i CLI 無法偵測自開始提取以來是否已更新或刪除列。 因此，不會報告下列 ODBC 定義的狀態值:
  • SQL_ROW_DELETED
  • 已更新 SQL_ROW_UPDATED

用法

SQLExtendedFetch() 用來執行一組列的陣列提取。 應用程式使用 SQL_ROWSET_SIZE 屬性呼叫 SQLSetStmtAttr() ，以指定陣列的大小。

在第一次呼叫 SQLExtendedFetch() 之前，游標會位於第一列之前。 呼叫 SQLExtendedFetch() 之後，游標會定位在結果集中對應於剛擷取之列集中最後一個列元素的列上。

對於結果集中已由 SQLBindCol() 函數連結的任何直欄， Db2 for i CLI 會根據需要轉換連結直欄的資料，並將它儲存在連結至這些直欄的位置。 結果集必須以逐列方式連結。 這表示第一列所有直欄的值都是連續的，後面接著第二列的值，依此類推。 此外，如果使用指示器變數，則會將它們全部傳回到一個連續儲存體位置。

使用此程序擷取多列時，必須連結所有直欄，且儲存體必須連續。 使用此函數從 SQL 程序結果集擷取列時，只支援 SQL_FETCH_NEXT 方向。 使用者負責為 SQL_ROWSET_SIZE 中指定的列數配置足夠的儲存體。

游標必須是可捲動的游標， SQLExtendedFetch() 才能使用 SQL_FETCH_NEXT 以外的任何方向。 如需設定 SQL_ATTR_CURSOR_SCROLLABLE 屬性的相關資訊，請參閱 SQLSetStmt屬性-設定陳述式屬性 。

回覆碼

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • 找到 SQL_NO_DATA_FOUND

錯誤狀況

表 2. SQLExtendedFetch SQLSTATE
SQL狀態 說明 說明
HY009 無效的引數值

引數值 RowCountPtr 或 RowStatusArray 是空值指標。

無法辨識指定給引數 FetchOrientation 的值。
HY010 函數順序錯誤 在呼叫 SQLFetch() 之後且在使用 SQL_CLOSE 選項呼叫 SQLFreeStmt() 之前，會針對 StatementHandle 呼叫 SQLExtendedFetch() 。

在呼叫 StatementHandle的 SQLPrepare() 或 SQLExecDirect() 之前，會先呼叫此函數。

在處理資料時 (SQLParamData()， SQLPutData()) 作業中呼叫此函數。
HY021 無效的內部描述子 內部描述子無法定址或配置，或包含無效的值。

限制

無。

參照