一致性
引入的版本：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 来获取关联的 SQLSTATE 值，其 HandleType 为 SQL_HANDLE_DBC，Handle 为 ConnectionHandle。 下表列出了 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） 为与 （DM） 为 ConnectionHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） SQLExecute、SQLExecDirect、SQLBulkOperations或 SQLSetPos 调用了与 ConnectionHandle 关联的 StatementHandle，并返回了SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 连接超时已过期 | 在数据源响应请求之前，连接超时期限已过期，并且连接仍然处于活动状态。 连接超时期限是通过 sqlSetConnectAttr |
| IM001 | 驱动程序不支持此函数 | （DM） 与 ConnectionHandle 关联的驱动程序不支持该函数。 |
| IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时，轮询将被禁用。 |
| IM018 | SQLCompleteAsync 尚未调用以完成此句柄上的上一个异步操作。 | 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用通知模式 ，则必须在句柄上调用 SQLCompleteAsync 才能执行后期处理并完成操作。 |
评论
如果应用程序在 SQLBrowseConnect 返回SQL_NEED_DATA后 SQLDisconnect 返回SQL_NEED_DATA，驱动程序将取消连接浏览过程，并将连接返回到未连接状态。
如果应用程序调用 SQLDisconnect，而连接句柄关联不完整的事务，驱动程序将返回 SQLSTATE 25000 （事务状态无效），指示事务不变且连接已打开。 不完整的事务是尚未提交或回滚的事务，SQLEndTran。
如果应用程序在释放与连接关联的所有语句之前调用 SQLDisconnect，则驱动程序在成功与数据源断开连接后释放这些语句以及已在连接上显式分配的所有描述符。 但是，如果与连接关联的一个或多个语句仍在异步执行，SQLDisconnect 返回SQL_ERROR，其 SQLSTATE 值为 HY010（函数序列错误）。 此外，SQLDisconnect 将释放在连接上显式分配的所有关联语句和所有描述符，如果连接处于挂起状态，或者 SQLDisconnect 已被 SQLCancelHandle成功取消。
有关应用程序如何使用 SQLDisconnect的信息，请参阅 从数据源或驱动程序断开连接。
断开与共用连接的连接
如果为共享环境启用了连接池，并且应用程序在该环境中的连接上调用 SQLDisconnect，则连接将返回到连接池，并且仍可用于使用同一共享环境的其他组件。
代码示例
请参阅 示例 ODBC 程序、SQLBrowseConnect 函数和 SQLConnect 函数。
相关函数
| 有关 | 看 |
|---|---|
| 分配句柄 | SQLAllocHandle 函数 |
| 连接到数据源 | SQLConnect 函数 |
| 使用连接字符串或对话框连接到数据源 | SQLDriverConnect 函数 |
| 执行提交或回滚操作 | SQLEndTran 函数 |
| 释放连接句柄 | SQLFreeConnect 函数 |