SQLFreeHandle 函数

项目
05/23/2023

一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92

摘要
SQLFreeHandle 释放与特定环境、连接、语句或描述符句柄关联的资源。

注意

此函数是用于释放句柄的泛型函数。它替换了用于释放连接句柄) 的 ODBC 2.0 函数 SQLFreeConnect (和用于释放环境句柄) 的 SQLFreeEnv (。 SQLFreeConnect 和 SQLFreeEnv 在 ODBC 3*.x* 中均已弃用。 SQLFreeHandle 还将 ODBC 2.0 函数 SQLFreeStmt (替换为用于释放语句句柄的 SQL_DROP Option) 。有关详细信息，请参阅“注释”。有关当 ODBC 3*.x* 应用程序使用 ODBC 2*.x* 驱动程序时驱动程序管理器将此函数映射到的内容的详细信息，请参阅映射替换函数以实现应用程序的后向兼容性。

语法

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);

参数

HandleType
[输入]要由 SQLFreeHandle 释放的句柄类型。必须是以下值之一：

SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN句柄仅由驱动程序管理器和驱动程序使用。应用程序不应使用此句柄类型。有关SQL_HANDLE_DBC_INFO_TOKEN的详细信息，请参阅在 ODBC 驱动程序中开发Connection-Pool感知。

如果 HandleType 不是这些值之一， 则 SQLFreeHandle 返回SQL_INVALID_HANDLE。

Handle
[输入]要释放的句柄。

SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。

如果 SQLFreeHandle 返回SQL_ERROR，则句柄仍然有效。

诊断

当 SQLFreeHandle 返回SQL_ERROR时，可以从 SQLFreeHandle 尝试释放但无法释放的句柄的诊断数据结构中获取关联的 SQLSTATE 值。下表列出了通常由 SQLFreeHandle 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE	错误	说明
HY000	常规错误	发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 MessageText 缓冲区中 SQLGetDiagRec* 返回的错误消息描述了错误及其原因。
HY001	内存分配错误	驱动程序无法分配支持执行或完成函数所需的内存。
HY010	函数序列错误	(DM) handleType 参数已SQL_HANDLE_ENV，并且至少有一个连接处于已分配或连接状态。在调用 HandleType 为 SQL_HANDLE_ENV 的 SQLFreeHandle 之前，必须为每个连接调用 handleType 为 SQL_HANDLE_DBC 的 SQLDisconnect 和 SQLFreeHandle。 (DM) SQL_HANDLE_DBC HandleType 参数，并在为连接调用 SQLDisconnect 之前调用函数。 (DM) SQL_HANDLE_DBC HandleType 参数。使用 Handle 调用了异步执行的函数，调用此函数时该函数仍在执行。 (DM) SQL_HANDLE_STMT HandleType 参数。 SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 是使用语句句柄调用的，SQL_NEED_DATA返回。在为所有数据执行时参数或列发送数据之前调用了此函数。 (DM) SQL_HANDLE_STMT HandleType 参数。在语句句柄或关联的连接句柄上调用了异步执行的函数，调用此函数时该函数仍在执行。 (DM) 已SQL_HANDLE_DESC HandleType 参数。在关联的连接句柄上调用了异步执行的函数;调用此函数时，函数仍在执行。 (DM) 调用 SQLFreeHandle 之前未释放所有附属句柄和其他资源。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 为与 Handle 关联的语句句柄之一调用， HandleType 设置为SQL_HANDLE_STMT或SQL_HANDLE_DESC返回SQL_PARAM_DATA_AVAILABLE。此函数是在检索所有流式处理参数的数据之前调用的。
HY013	内存管理错误	HandleType 参数SQL_HANDLE_STMT或SQL_HANDLE_DESC，并且无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。
HY017	自动分配的描述符句柄使用无效。	(DM ) Handle 参数设置为自动分配的描述符的句柄。
HY117	由于未知的事务状态，连接已挂起。仅允许断开连接和只读函数。	(DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYT01	超过连接超时时间	在数据源响应请求之前，连接超时期限已过期。连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。
IM001	驱动程序不支持此函数	(DM) handleType 参数SQL_HANDLE_DESC，驱动程序是 ODBC 2.x 驱动程序。 (DM) handleType 参数已SQL_HANDLE_STMT，并且驱动程序不是有效的 ODBC 驱动程序。

注释

SQLFreeHandle 用于释放环境、连接、语句和描述符的句柄，如以下部分所述。有关句柄的一般信息，请参阅句柄。

应用程序在释放句柄后不应使用句柄;驱动程序管理器不会检查函数调用中句柄的有效性。

释放环境句柄

在调用 HandleType 为 SQL_HANDLE_ENV 的 SQLFreeHandle 之前，应用程序必须为环境中分配的所有连接调用 handleType 为 SQL_HANDLE_DBC 的 SQLFreeHandle。否则，对 SQLFreeHandle 的调用将返回SQL_ERROR，并且环境以及任何活动连接仍然有效。有关详细信息，请参阅环境句柄和分配环境句柄。

如果环境是共享环境，则调用 handleType 为 SQL_HANDLE_ENV 的 SQLFreeHandle 的应用程序在调用后不再有权访问环境，但不一定释放环境的资源。调用 SQLFreeHandle 会减少环境的引用计数。引用计数由驱动程序管理器维护。如果它未达到零，则不会释放共享环境，因为另一个组件仍在使用它。如果引用计数达到零，则释放共享环境的资源。

释放连接句柄

在调用 HandleType 为 SQL_HANDLE_DBC 的 SQLFreeHandle 之前，如果此句柄上存在连接*，则应用程序必须为连接调用 SQLDisconnect。否则，对 SQLFreeHandle 的调用将返回SQL_ERROR并且连接仍然有效。

有关详细信息，请参阅连接句柄和与数据源或驱动程序断开连接。

释放语句句柄

使用 handleType 为 SQL_HANDLE_STMT 调用 SQLFreeHandle 可释放通过调用 SQLAllocHandle 分配的所有资源，HandleType 为 SQL_HANDLE_STMT。当应用程序调用 SQLFreeHandle 释放具有挂起结果的语句时，将删除挂起的结果。当应用程序释放语句句柄时，驱动程序释放与该句柄关联的四个自动分配的描述符。有关详细信息，请参阅语句句柄和释放语句句柄。

请注意， SQLDisconnect 会自动删除连接上打开的任何语句和描述符。

释放描述符句柄

调用 SQLFreeHandle 且 HandleType 为 SQL_HANDLE_DESC 释放 Handle 中的描述符句柄。对 SQLFreeHandle 的调用不会释放应用程序分配的任何内存，这些内存可由指针字段 (包括句柄的任何描述符记录SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR) 。释放句柄时，驱动程序为非指针字段分配的内存将释放。释放用户分配的描述符句柄时，释放的句柄与关联的所有语句将还原为其各自的自动分配的描述符句柄。

注意

ODBC 2*.x* 驱动程序不支持释放描述符句柄，就像它们不支持分配描述符句柄一样。

请注意， SQLDisconnect 会自动删除连接上打开的任何语句和描述符。当应用程序释放语句句柄时，驱动程序将释放与该句柄关联的所有自动生成的描述符。

有关描述符的详细信息，请参阅描述符。

代码示例

有关其他代码示例，请参阅 SQLBrowseConnect 和 SQLConnect。

代码

// SQLFreeHandle.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <stdio.h>  
  
int main() {  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   // Initialize the environment, connection, statement handles.  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   // Allocate the environment.  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set environment attributes.  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
  
   // Allocate the connection.  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
   // Set the login timeout.  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
  
   // Let the user select the data source and connect to the database.  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // Free handles, and disconnect.     
   if (hstmt) {   
      SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
      hstmt = NULL;   
   }  
   if (hdbc) {   
      SQLDisconnect(hdbc);  
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      hdbc = NULL;   
   }  
   if (henv) {   
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
      henv = NULL;   
   }  
}

有关以下方面的信息	请参阅
分配句柄	SQLAllocHandle 函数
取消语句处理	SQLCance Functionl
设置游标名称	SQLSetCursorName 函数

另请参阅

ODBC API 参考
 ODBC 头文件
 示例 ODBC 程序

通过