SQLEndTran 函式
一致性
引進版本：ODBC 3.0 標準合規性：ISO 92
摘要
SQLEndTran 會針對與連接相關聯之所有語句上的所有作用中作業要求認可或復原作業。 SQLEndTran 也可以要求針對與環境相關聯的所有連線執行認可或復原作業。
注意
如需 Driver Manager 在 ODBC 3 時將此函式對應至之內容的詳細資訊。x 應用程式正在使用 ODBC 2。x 驅動程式，請參閱 對應替代函式以取得應用程式的回溯相容性。
語法
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
引數
HandleType
[輸入]處理類型識別碼。 包含SQL_HANDLE_ENV（如果 Handle 是環境句柄）或SQL_HANDLE_DBC（如果 Handle 是連接句柄）。
Handle
[輸入]HandleType 所指示之型別的句柄，表示交易的範圍。 如需詳細資訊，請參閱。
CompletionType
[輸入]下列兩個值的其中一個：
SQL_COMMIT SQL_ROLLBACK
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。
診斷
當 SQLEndTran 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以使用適當的 HandleType 和 Handle 呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值。 下表列出 SQLEndTran 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08003 | 線上未開啟 | （DM） HandleType 已SQL_HANDLE_DBC，而 Handle 不是處於連線狀態。 |
| 08007 | 交易期間的連線失敗 | HandleType 已SQL_HANDLE_DBC，且與 Handle 相關聯的連接在執行函式期間失敗，而且無法判斷要求的認可或 ROLLBACK 是否在失敗之前發生。 |
| 25S01 | 交易狀態未知 | Handle 中的一或多個連線無法完成具有指定結果的交易，且結果未知。 |
| 25S02 | 交易仍在使用中 | 驅動程式無法保證全域交易中的所有工作都可以以不可部分完成，而且交易仍在使用中。 |
| 25S03 | 交易已回復 | 驅動程式無法保證全域交易中的所有工作都可以以不可部分完成，且在 Handle 中作用中交易中的所有工作都會回復。 |
| 40001 | 串行化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40002 | 完整性條件約束違規 | CompletionType 已SQL_COMMIT，且變更的承諾會導致完整性條件約束違規。 因此，交易已回復。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *szMessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | ConnectionHandle 已啟用異步處理。 已呼叫函式，並在 ConnectionHandle 上呼叫完成執行 SQLCancelHandle 函式之前。 然後在 ConnectionHandle 上再次呼叫函式。 呼叫函式，並在完成執行 SQLCancelHandle 之前，從 多線程應用程式中的不同線程呼叫 ConnectionHandle 。 |
| HY010 | 函式順序錯誤 | （DM） 針對與 ConnectionHandle 相關聯的語句句柄呼叫異步執行函式，而且在呼叫 SQLEndTran 時仍在執行。 （DM） 呼叫 ConnectionHandle 的異步執行函式（不是此函式），而且在呼叫此函式時仍在執行中。 （DM） SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已針對與 ConnectionHandle 相關聯的語句句柄呼叫，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 （DM） 異步執行的函式 （不是此函式）已針對 HandleType 設定為 SQL_HANDLE_DBC 呼叫句柄，而且在呼叫此函式時仍在執行中。 （DM） SQLExecute、SQLExecDirect 或 SQLMoreResults 已針對與 Handle 相關聯的其中一個語句句柄呼叫，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。 |
| HY012 | 無效的交易作業程序代碼 | （DM） 針對 Argument CompletionType 指定的值既不是SQL_COMMIT也不是SQL_ROLLBACK。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY092 | 無效的屬性/選項識別碼 | （DM） 自變數 HandleType 指定的值既不是SQL_HANDLE_ENV也不是SQL_HANDLE_DBC。 |
| HY115 | 不允許 SQLEndTran 用於包含已啟用異步函式執行連線的環境 | （DM） HandleType 無法在環境中啟用連接功能的異步執行時，將 handleType 設定為 SQL_HANDLE_ENV。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱本主題的一節。 |
| HYC00 | 未實作選擇性功能 | 驅動程式或數據源不支援 ROLLBACK 作業。 |
| HYT01 | 已超過連線逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 ConnectionHandle 相關聯的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
註解
針對 ODBC 3。x 驅動程式，如果 HandleType 是SQL_HANDLE_ENV句 柄是有效的環境句 柄，則 Driver Manager 會在與環境相關聯的每個驅動程式中呼叫 SQLEndTran 。 呼叫 驅動程式的 Handle 自變數將會是驅動程式的環境句柄。 針對 ODBC 2。x 驅動程式，如果 HandleType 是SQL_HANDLE_ENV句柄，而 Handle 是有效的環境句 柄，而且在該環境中處於連線狀態有多個連線，則 Driver Manager 會 針對該環境中處於連線狀態的每個連線呼叫 SQLTransact 一次。 每個呼叫中的 Handle 自變數將會是連接的句柄。 不論是哪一種情況，驅動程式都會嘗試認可或回復交易，視 CompletionType 的值而定，該環境處於連線狀態的所有連線。 未使用中的連線不會影響交易。
注意
SQLEndTran 無法用來認可或回復共享環境中的交易。 如果 SQLEndTran 的句 柄設定為共用環境的句柄或共用環境的連接句柄，則會傳回 SQLSTATE HY092 （無效的屬性/選項識別符）。
只有在每個連線收到SQL_SUCCESS時，驅動程式管理員才會傳回SQL_SUCCESS。 如果驅動程式管理員在一或多個連線上收到SQL_ERROR，則會將SQL_ERROR傳回應用程式，並將診斷資訊放在環境的診斷數據結構中。 若要判斷認可或回復作業期間哪個連線或連線失敗，應用程式可以針對每個連線呼叫 SQLGetDiagRec 。
注意
驅動程式管理員不會模擬跨所有連線的全域交易，因此不會使用雙階段認可通訊協定。
如果 CompletionType 是SQL_COMMIT，SQLEndTran 會在與受影響連線相關聯的任何語句上發出所有作用中作業的認可要求。 如果 CompletionType 是SQL_ROLLBACK，SQLEndTran 會在與受影響連線相關聯的任何語句上發出所有作用中作業的回復要求。 如果沒有使用中交易， SQLEndTran 會傳回SQL_SUCCESS，而不會影響任何數據源。 如需詳細資訊，請參閱 認可和回復交易。
如果驅動程式處於手動認可模式（藉由呼叫 SQLSetConnectAttr 並將 SQL_ATTR_AUTOCOMMIT 屬性設定為 SQL_AUTOCOMMIT_OFF），則會在對目前數據源執行可包含在交易內的 SQL 語句時，隱含啟動新的交易。 如需詳細資訊，請參閱 認可模式。
若要判斷交易作業如何影響數據指標，應用程式會使用SQL_CURSOR_ROLLBACK_BEHAVIOR和SQL_CURSOR_COMMIT_BEHAVIOR選項呼叫 SQLGetInfo 。 如需詳細資訊，請參閱下列段落，另請參閱 交易對數據指標和備妥語句的影響。
如果SQL_CURSOR_ROLLBACK_BEHAVIOR或SQL_CURSOR_COMMIT_BEHAVIOR值等於SQL_CB_DELETE，SQLEndTran 會關閉並刪除所有與連接相關聯的語句上所有開啟的數據指標，並捨棄所有暫止的結果。 SQLEndTran 會保留任何處於已配置（未準備）狀態的語句;應用程式可以重複使用這些語句以供後續的 SQL 要求使用，或者可以使用SQL_HANDLE_STMT的 HandleType 呼叫 SQLFreeStmt 或 SQLFreeHandle 來解除分配它們。
如果SQL_CURSOR_ROLLBACK_BEHAVIOR或SQL_CURSOR_COMMIT_BEHAVIOR值等於 SQL_CB_CLOSE，SQLEndTran 會關閉與連接相關聯之所有語句上所有開啟的數據指標。 SQLEndTran 會保留任何處於備妥狀態的語句;應用程式可以針對與連接相關聯的語句呼叫 SQLExecute ，而不需先呼叫 SQLPrepare。
如果SQL_CURSOR_ROLLBACK_BEHAVIOR或SQL_CURSOR_COMMIT_BEHAVIOR值等於 SQL_CB_PRESERVE，SQLEndTran 不會影響與連接相關聯的開啟數據指標。 數據指標會保留在呼叫 SQLEndTran 之前所指向的數據列。
對於支援交易的驅動程式和數據源，在沒有使用中交易傳回SQL_SUCCESS時，使用 SQL_COMMIT 或 SQL_ROLLBACK 呼叫 SQLEndTran （表示沒有任何工作可認可或回復），而且對數據源沒有任何作用。
當驅動程式處於自動認可模式時，驅動程式管理員不會在驅動程式中呼叫 SQLEndTran 。 不論是否以SQL_COMMIT或SQL_ROLLBACK的 CompletionType 呼叫 SQLEndTran 一律會傳回SQL_SUCCESS。
不支援交易的驅動程式或數據源（SQLGetInfo 選項 SQL_TXN_CAPABLE SQL_TC_NONE）實際上一律處於自動認可模式，因此一律會針對 SQLEndTran 傳回SQL_SUCCESS，不論它們是否以 SQL_COMMIT或SQL_ROLLBACK的 CompletionType 呼叫。 這類驅動程式和數據源在要求這麼做時，實際上不會回復交易。
暫停狀態
在 Windows 7 之前發行的驅動程式管理員中，如果 SQLEndTran 從驅動程式傳回SQL_ERROR，交易就會作用中。 不過，交易有可能在伺服器上成功認可，但用戶端上的驅動程式尚未收到通知（例如，因為發生網路錯誤）。 這會讓連線處於不良狀態。 從 Windows 7 開始，當 SQLEndTran 傳回SQL_ERROR時，連線可能處於暫停狀態。 處於暫停狀態，可以呼叫只讀函式。 最後，應用程式應該在暫停連線上呼叫 SQLDisconnect ，以釋放資源。
如果下列所有條件都成立，連線將會處於暫停狀態：
驅動程式會從 SQLEndTran 傳回SQL_ERROR。
驅動程式是 ODBC 3.8 版或更新版本。
應用程式版本為 3.8 或更新版本;或重新編譯的 ODBC 2.x 或 3.x 應用程式會透過 SQLCancelHandle 成功取消 SQLEndTran 函式。
驅動程式未傳回下列其中一則訊息，確認交易未完成：
25S03：交易已回復
40001：串行化失敗
40002：完整性條件約束
HYC00：未實作選擇性功能
如果在 環境句柄上呼叫 SQLEndTran ，且其中一個連線符合上述條件，則連線到相同驅動程式的所有連線都會進入暫停狀態。
應用程式在暫停的連線上呼叫 SQLDisconnect 之後，連線可用來重新連線至另一個數據源或相同的數據源。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 取消以異步方式在連接句柄上執行的函式。 | SQLCancelHandle 函式 |
| 傳回驅動程式或數據源的相關信息 | SQLGetInfo 函式 |
| 釋放句柄 | SQLFreeHandle 函式 |
| 釋放語句句柄 | SQLFreeStmt 函式 |