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

另请参阅

ODBC API 参考
ODBC 头文件