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 句 柄 呼叫相關聯的 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 已啟用 非同步處理。 已呼叫函式，並在 ConnectionHandle 上 呼叫執行 SQLCancelHandle 函 式之前。 然後在 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 傳回SQL_NEED_DATA之後呼叫 SQLDisconnect，並在傳回不同的傳回碼之前呼叫 SQLDisconnect ，驅動程式會取消連線流覽程式，並將連線傳回至未連線的狀態。
如果應用程式在連接控制碼有未完成的交易時呼叫 SQLDisconnect ，驅動程式會傳回 SQLSTATE 25000 （不正確交易狀態），表示交易未變更且連接已開啟。 不完整的交易是未使用 SQLEndTran 認可或回復的交易。
如果應用程式在 釋放與連線相關聯的所有語句之前呼叫 SQLDisconnect ，驅動程式會在成功中斷與資料來源的連線之後，釋放這些語句，以及已在連接上明確配置的所有描述項。 不過，如果一或多個與連接相關聯的語句仍在非同步執行， SQLDisconnect 會傳回具有 HY010 的 SQLSTATE 值（函數順序錯誤）的SQL_ERROR。 此外， 如果連接處於暫止狀態，或 SQLCancelHandle 成功取消 SQLDisconnect ，SQLDisconnect 將會釋放連線上明確配置的所有相關聯語句和所有描述項 。
如需應用程式 如何使用 SQLDisconnect 的詳細資訊，請參閱 中斷與資料來源或驅動程式 的連線。
中斷與集區連線的連線
如果連線共用已針對共用環境啟用，且應用程式在該環境的連線中呼叫 SQLDisconnect，則連線會傳回至連線集區，並仍可供其他使用相同共用環境的元件使用。
程式碼範例
請參閱 ODBC 程式 範例、 SQLBrowseConnect 函 式和 SQLConnect 函式 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 配置控制碼 | SQLAllocHandle 函式 |
| 連線到資料來源 | SQLConnect 函式 |
| 使用連接字串或對話方塊連接到資料來源 | SQLDriverConnect 函式 |
| 執行認可或復原作業 | SQLEndTran 函式 |
| 釋放連接控制碼 | SQLFreeConnect 函式 |