SQLFreeHandle 函数

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

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

语法

  
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。

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

返回

SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。

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

诊断

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

评论

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

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

释放环境句柄

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

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

释放连接句柄

在调用具有 SQL_HANDLE_DBC HandleTypeSQLFreeHandle 之前，如果此句柄上有连接，则应用程序必须为此句柄调用 SQLDisconnect。否则，SQLFreeHandle 返回SQL_ERROR且连接仍然有效。

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

释放语句句柄

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

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

释放描述符句柄

使用 HandleTypeSQLFreeHandle 调用SQL_HANDLE_DESC释放 Handle中的描述符句柄。 对 SQLFreeHandle 调用不会释放应用程序分配的任何内存，这些内存可由指针字段（包括SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR）引用的任何描述符记录 Handle。 当释放句柄时，驱动程序为不是指针字段的字段分配的内存将释放。 释放用户分配的描述符句柄时，释放句柄的所有语句都与还原到各自的自动分配描述符句柄相关联。

请注意，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;   
   }  
}  

相关函数

另请参阅

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