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

另請參閱

ODBC API 參考
ODBC 標頭檔