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 函式

另請參閱

ODBC API 參考
ODBC 標頭檔
非同步執行 (輪詢方法)