SQLMoreResults 函式

  • 發行項

一致性
引進的版本：ODBC 1.0 標準合規性：ODBC

摘要
SQLMoreResults 會決定是否在包含 SELECT 、 UPDATE 、 INSERT 或 DELETE 語句的語句上取得更多結果，如果是的話，會初始化這些結果的處理。

語法

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);

引數

StatementHandle
[輸入]語句控制碼。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE 或 SQL_PARAM_DATA_AVAILABLE。

診斷

當 SQLMoreResults 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句 柄 ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLMoreResults 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S02 選項值已變更 語句屬性的值在處理批次時變更。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
08S01 通訊連結失敗 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
40001 序列化失敗 交易因為與另一個交易發生資源死結而回復。
40003 語句完成未知 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY008 作業已取消 已針對 StatementHandle 啟用非同步處理。 已呼叫 SQLMoreResults 函式，並在完成執行之前， 在 StatementHandle 上 呼叫 SQLCancel 或 SQLCancelHandle 。 然後，在 StatementHandle 上 再次呼叫 SQLMoreResults 函 式。

已呼叫 SQLMoreResults 函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 SQLCancel 或 SQLCancelHandle 。
HY010 函式順序錯誤 （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLMoreResults 函式時 ，這個非同步函 式仍在執行中。

（DM） 呼叫 StatementHandle 的非同步執行函式（而非此函式），並在呼叫此函式時仍在執行中。

（DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos ，並傳回SQL_NEED_DATA。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
HYT01 已超過連線逾時 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。
IM017 在非同步通知模式中停用輪詢 每當使用通知模型時，輪詢就會停用。
IM018 尚未呼叫 SQLCompleteAsync ，以完成此控制碼上的先前非同步作業。 如果控制碼上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在控制碼上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。

註解

SELECT 語句會傳回結果集。 UPDATE 、 INSERT 和 DELETE 語句會傳回受影響的資料列計數。 如果其中任一個語句是批次的，則以參數陣列提交（以遞增參數順序編號、依照批次中出現的順序），或程式中，他們可以傳回多個結果集或資料列計數。 如需語句批次和參數陣列的相關資訊，請參閱 SQL 語句 的批次和 參數值的 陣列。

執行批次之後，應用程式會放在第一個結果集上。 應用程式可以在第一個或任何後續的結果集上呼叫 SQLBindCol 、 SQLBulkOperations 、 SQLFetch 、 SQLGetData 、 SQLFetchScroll 、 SQLSetPos 和所有中繼資料函式，就如同只有單一結果集一樣。 完成第一個結果集之後，應用程式會呼叫 SQLMoreResults 以移至下一個結果集。 如果有另一個結果集或計數可用， SQLMoreResults 會傳回SQL_SUCCESS，並初始化結果集或計數以進行其他處理。 如果結果集產生語句之間出現任何資料列計數產生語句，則可以呼叫 SQLMoreResults 來逐步執行這些語句。呼叫 UPDATE、INSERT 或 DELETE 子句的 SQLMoreResults 之後，應用程式可以呼叫 SQLRowCount 。

如果有具有未擷取資料列的目前結果集， SQLMoreResults 會捨棄該結果集，並讓下一個結果集或計數可供使用。 如果已處理所有結果， SQLMoreResults 會傳回SQL_NO_DATA。 對於某些驅動程式，輸出參數和傳回值在處理所有結果集和資料列計數之前都無法使用。 對於這類驅動程式，當 SQLMoreResults 傳回SQL_NO_DATA時 ，輸出參數和傳回值就會變成可用。

針對先前結果集建立的任何系結仍然有效。 如果此結果集的資料行結構不同，則呼叫 SQLFetch 或 SQLFetchScroll 可能會導致錯誤或截斷。 若要避免這種情況，應用程式必須呼叫 SQLBindCol ，才能適當地明確重新系結（或藉由設定描述元欄位來進行重新系結）。 或者，應用程式可以使用 SQL_UNBIND 選項 呼叫 SQLFreeStmt ，以解除系結所有資料行緩衝區。

語句屬性的值，例如資料指標類型、資料指標並行、索引鍵集大小或最大長度，可能會在應用程式透過呼叫 SQLMoreResults 流覽批次時變更。 如果發生這種情況， SQLMoreResults 會傳回SQL_SUCCESS_WITH_INFO和 SQLSTATE 01S02 （選項值已變更）。

呼叫 SQLCloseCursor 或 具有 選項的 SQLFreeStmt SQL_CLOSE，會捨棄批次執行結果集和資料列計數的所有可用結果集和資料列計數。 語句控制碼會傳回已配置或備妥的狀態。 呼叫 SQLCancel 以在批次執行且語句控制碼處於執行中、資料指標定位或非同步狀態時，取消非同步執行的函式，如果取消呼叫成功，則批次所產生的所有結果集和資料列計數都會被捨棄。 然後，語句會傳回已備妥或已配置的狀態。

如果語句批次或程式混合其他 SQL 語句與 SELECT 、 UPDATE 、 INSERT 和 DELETE 語句，這些其他語句不會影響 SQLMoreResults 。

如需詳細資訊，請參閱 多個結果 。

如果批次語句中搜尋的更新、插入或刪除語句不會影響資料來源的任何資料列， SQLMoreResults 會傳回SQL_SUCCESS。 這與透過 SQLExecDirect 、SQLExecute 或 SQLParamData 執行的搜尋更新、 插入或刪除 語句的情況不同，如果它不會影響資料來源的任何資料列，則會傳回SQL_NO_DATA。 如果應用程式呼叫 SQLRowCount 來擷取 SQLMoreResults 呼叫 後擷取資料列計數並不會影響任何資料列， SQLRowCount 將會傳回SQL_NO_DATA。

如需結果處理函式之有效排序的其他資訊，請參閱 附錄 B：ODBC 狀態轉換資料表 。

如需SQL_PARAM_DATA_AVAILABLE和串流輸出參數的詳細資訊，請參閱 使用 SQLGetData 擷取輸出參數。

資料列計數的可用性

當批次包含多個連續的資料列計數產生語句時，可能會將這些資料列計數匯總成一個資料列計數。 例如，如果批次有五個 insert 語句，則特定資料來源能夠傳回五個個別的資料列計數。 某些其他資料來源只會傳回一個資料列計數，代表五個個別資料列計數的總和。

當批次包含結果集產生和資料列計數產生語句的組合時，資料列計數可能或完全無法使用。 驅動程式與資料列計數可用性相關的行為，會列舉在透過呼叫 SQLGetInfo 取得的SQL_BATCH_ROW_COUNT資訊類型中。 例如，假設批次包含 SELECT ，後面接著兩 個 INSERT 和另一個 SELECT 。 然後，可能會發生下列情況：

  • 對應至兩 個 INSERT 語句的資料列計數完全無法使用。 第一次呼叫 SQLMoreResults 會將您放在第二個 SELECT 語句的結果集上。

  • 對應至兩 個 INSERT 語句的資料列計數可個別使用。 （呼叫 SQLGetInfo 不會傳回SQL_BATCH_ROW_COUNT資訊類型的SQL_BRC_ROLLED_UP位。第一次呼叫 SQLMoreResults 會將您放在第一 個 INSERT 的資料列計數上，而第二個呼叫會將您放在第二 個 INSERT 的資料列計數上。 第三次呼叫 SQLMoreResults 會將您放在第二個 SELECT 語句的結果集上。

  • 對應至兩 個 INSERT 的資料列計數會匯總成一個可用的單一資料列計數。 （呼叫 SQLGetInfo 會傳回SQL_BATCH_ROW_COUNT資訊類型的SQL_BRC_ROLLED_UP位。第一次呼叫 SQLMoreResults 會將您放在匯總的資料列計數上，而對 SQLMoreResults 的第二次呼叫 會將您放在第二 個 SELECT 的結果集上。

某些驅動程式只會針對明確批次使用資料列計數，而不適用於預存程式。

如需下列資訊 請參閱
取消語句處理 SQLCancel 函式
擷取資料區塊或捲動結果集 SQLFetchScroll 函式
以正向方向擷取單一資料列或資料區塊 SQLFetch 函式
擷取部分或所有資料行的資料 SQLGetData 函式

另請參閱

ODBC API 參考
ODBC 標頭檔
使用 SQLGetData 擷取輸出參數