SQLDisconnect 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLDisconnect 關閉與特定連接句柄相關聯的連線。
語法
SQLRETURN SQLDisconnect(
SQLHDBC ConnectionHandle);
參數
ConnectionHandle
[輸入]連接句柄。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。
診斷
當 SQLDisconnect 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可能會呼叫 SQLGetDiagRec，並以 SQL_HANDLE_DBC HandleType，以及 ConnectionHandle的 Handle 來取得相關聯的 SQLSTATE 值。 下表列出 SQLDisconnect 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值：表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE |
錯誤 |
描述 |
| 01000 |
一般警告 |
驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01002 |
中斷連線錯誤 |
中斷連線期間發生錯誤。 不過，中斷連線成功。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08003 |
線上未開啟 |
（DM） 未開啟 ConnectionHandle 自變數中指定的連接。 |
| 25000 |
無效的交易狀態 |
自變數 ConnectionHandle所指定的連接上有交易。 交易會維持使用中狀態。 |
| HY000 |
一般錯誤 |
發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。
*MessageText 緩衝區中 SQLGetDiagRec 所傳回的錯誤訊息會描述錯誤及其原因。 |
| HY001 |
記憶體配置錯誤 |
驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 |
作業已取消 |
已針對 ConnectionHandle啟用異步處理。 已呼叫函式，並在 sqlCancelHandle 函式 完成執行之前，ConnectionHandle上呼叫。 然後在 ConnectionHandle上再次呼叫函式。
已呼叫函式，並在完成執行 SQLCancelHandle 之前，在多線程應用程式中 ConnectionHandle 上呼叫它。 |
| HY010 |
函式順序錯誤 |
（DM） 針對與 ConnectionHandle 相關聯的 StatementHandle 呼叫異步執行函式，而且在呼叫 SQLDisconnect 時仍在執行。
（DM） 異步執行函式 （不是此函式）已針對 ConnectionHandle 呼叫，而且在呼叫此函式時仍在執行中。
（DM） SQLExecute、SQLExecDirect、SQLBulkOperations，或 SQLSetPos，針對與 ConnectionHandle 相關聯的 StatementHandle 呼叫，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 |
| HY013 |
記憶體管理錯誤 |
無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY117 |
聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 |
（DM） 如需暫停狀態的詳細資訊，請參閱 sqlEndTran 函式 。 |
| HYT01 |
線上逾時已過期 |
在數據源回應要求之前，連線逾時期限已過期，且連線仍在使用中。 連線逾時期間是透過 SQLSetConnectAttr設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 |
驅動程式不支援此函式 |
（DM） 與 ConnectionHandle 相關聯的驅動程式不支援 函式。 |
| IM017 |
在異步通知模式中停用輪詢 |
每當使用通知模型時，輪詢就會停用。 |
| IM018 |
尚未呼叫 SQLCompleteAsync，以完成此句柄上先前的異步操作。 |
如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式 ，則必須在句柄上呼叫 SQLCompleteAsync，才能執行後續處理並完成作業。 |
如果應用程式在 SQLBrowseConnect 之後呼叫 SQLDisconnect 會傳回SQL_NEED_DATA，並在傳回不同的傳回碼之前，驅動程式會取消連線瀏覽程式，並將連線傳回至未連線狀態。
如果應用程式呼叫 SQLDisconnect，而連接句柄有未完成的交易，驅動程式會傳回 SQLSTATE 25000 （無效的交易狀態），表示交易未變更且連接已開啟。 未完成的交易是未透過 SQLEndTran 認可或回復的交易。
如果應用程式在釋放與連線相關聯的所有語句之前，先呼叫 SQLDisconnect，則驅動程式會在成功中斷與數據源的連線之後，釋放這些語句，以及已在連接上明確配置的所有描述項。 不過，如果與連接相關聯的一或多個語句仍在異步執行，SQLDisconnect 會傳回具有 HY010 的 SQLSTATE 值SQL_ERROR （函數順序錯誤）。 此外，SQLDisconnect 會釋放連線上明確配置的所有關聯語句和所有描述項、如果連線處於暫止狀態，或 SQLDisconnect 已成功取消，SQLCancelHandle。
如需應用程式如何使用 SQLDisconnect的詳細資訊，請參閱 從數據源或驅動程式中斷連線。
中斷與集區連線的連線
如果已針對共用環境啟用連線共用，且應用程式呼叫 該環境中的連線 SQLDisconnect，則會將連線傳回至連線集區，而且仍然可供使用相同共享環境的其他元件使用。
程式代碼範例
請參閱 範例 ODBC 程式、SQLBrowseConnect 函式和 SQLConnect 函式。
另請參閱
ODBC API 參考
ODBC 頭檔