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时，可以通过使用 handleType 为 SQL_HANDLE_DBC 和 ConnectionHandle 句柄调用 SQLGetDiagRec 来获取关联的 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。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| 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 返回SQL_NEED_DATA之后调用 SQLDisconnect，并在返回其他返回代码之前，驱动程序将取消连接浏览过程，并将连接返回到未连接状态。
如果应用程序调用 SQLDisconnect 而存在与连接句柄关联的不完整事务，驱动程序将返回 SQLSTATE 25000 (无效事务状态) ，指示事务未更改且连接处于打开状态。 未完成的事务是尚未使用 SQLEndTran 提交或回滚的事务。
如果应用程序在释放与连接关联的所有语句之前调用 SQLDisconnect ，则驱动程序在成功断开与数据源的连接后，释放这些语句和已在连接上显式分配的所有描述符。 但是，如果一个或多个与连接关联的语句仍在异步执行， SQLDisconnect 将返回 SQLSTATE 值为 HY010 (Function 序列错误) SQL_ERROR。 此外，如果连接处于挂起状态或 SQLCancelHandle 成功取消 SQLDisconnect，SQLDisconnect 将释放在连接上显式分配的所有关联语句和所有描述符。
有关应用程序如何使用 SQLDisconnect 的信息，请参阅 从数据源或驱动程序断开连接。
从共用连接断开连接
如果为共享环境启用了连接池，并且应用程序在该环境中的连接上调用 SQLDisconnect ，则连接将返回到连接池，并且仍可用于使用同一共享环境的其他组件。
代码示例
请参阅 示例 ODBC 程序、 SQLBrowseConnect 函数和 SQLConnect 函数。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 分配句柄 | SQLAllocHandle 函数 |
| 连接到数据源 | SQLConnect 函数 |
| 使用连接字符串或对话框连接到数据源 | SQLDriverConnect 函数 |
| 执行提交或回滚操作 | SQLEndTran 函数 |
| 释放连接句柄 | SQLFreeConnect 函数 |