| 规范： | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLFreeHandle() 释放与特定环境、连接或语句句柄相关联的资源。
此函数是用于释放资源的类属函数。它替换 SQLFreeConnect（用于释放连接句柄）和 SQLFreeEnv()（用于释放环境句柄）。 SQLFreeHandle() 还替换用于释放语句句柄的 SQLFreeStmt()（指定 SQL_DROP 选项）。
语法
SQLRETURN SQLFreeHandle (SQLSMALLINT HandleType,
SQLHANDLE Handle);
函数自变量
| 数据类型 | 自变量 | 使用 | 描述 |
|---|---|---|---|
| SQLSMALLINT | HandleType | 输入 | SQLFreeHandle()
要释放的句柄的类型。必须是下列其中一值：
|
| SQLHANDLE | Handle | 输入 | 要释放的句柄的名称。 |
用法
SQLFreeHandle() 用来释放环境、连接和语句的句柄。
在释放句柄之后，应用程序不应再使用该句柄；DB2 CLI 不检查函数调用中句柄的有效性。
释放环境句柄
在调用 SQLFreeHandle()（HandleType 为 SQL_HANDLE_ENV）之前，应用程序必须对环境中分配的所有连接调用 SQLFreeHandle()（HandleType 为 SQL_HANDLE_DBC）。否则，对 SQLFreeHandle() 的调用返回 SQL_ERROR，且环境和任何活动连接仍有效。
释放连接句柄
在调用 SQLFreeHandle()（HandleType 为 SQL_HANDLE_DBC）之前，应用程序必须对连接调用 SQLDisconnect()。否则，对 SQLFreeHandle() 的调用返回 SQL_ERROR，且连接仍有效。
释放语句句柄
对 SQLFreeHandle() 的调用（HandleType 为 SQL_HANDLE_STMT） 释放 SQLAllocHandle() 调用（HandleType 为 SQL_HANDLE_STMT）分配的所有资源。当应用程序调用 SQLFreeHandle() 来释放带有暂挂结果的语句时，暂挂的结果被删除。调用 SQLFreeHandle() 时，如果有暂挂的结果，则结果集被废弃。
SQLDisconnect() 自动删除在该连接上打开的所有语句。
返回码
如果 SQLFreeHandle() 返回 SQL_ERROR，则句柄仍有效。
诊断
| SQLSTATE | 描述 | 解释 |
|---|---|---|
| 01000 | 警告。 | 参考消息。（函数返回 SQL_SUCCESS_WITH_INFO。） |
| 08S01 | 通信链路故障。 | HandleType 自变量是 SQL_HANDLE_DBC，在函数完成处理之前，DB2 CLI 与它尝试连接的数据源之间的通信链路失效。 |
| HY000 | 一般错误。 | 出错，该错误没有特定的 SQLSTATE。*MessageText 缓冲区中由 SQLGetDiagRec() 返回的错误消息描述该错误及其原因。 |
| HY001 | 内存分配失败。 | DB2 CLI 无法分配支持函数的执行或完成所需的内存。 |
| HY010 | 函数顺序错误。 | HandleType 自变量为 SQL_HANDLE_ENV 且至少有一个连接处于已分配或已连接状态。在调用 HandleType 为 SQL_HANDLE_ENV
的 SQLFreeHandle() 之前，必须对每个连接调用 HandleType 为
SQL_HANDLE_DBC 的 SQLDisconnect() 和 SQLFreeHandle()。HandleType
自变量是 SQL_HANDLE_DBC，而在对连接调用 SQLDisconnect()
之前调用了该函数。
HandleType 自变量是 SQL_HANDLE_STMT；使用语句句柄调用了 SQLExecute() 或 SQLExecDirect()，且返回了 SQL_NEED_DATA。（DM）在调用 SQLFreeHandle() 之前，未释放任何附属句柄和其它资源。 |
| HY013 | 发生意外的内存处理错误。 | HandleType 自变量是 SQL_HANDLE_STMT；因为未能访问底层内存对象（可能是因为内存不足），所以未能处理函数调用。 |
| HY017 | 自动分配的描述符句柄的使用无效。 | Handle 自变量设置为自动分配的描述符或实现描述符的句柄。 |
限制
无。
相关参考