SQLFreeHandle Function

Conformance
Version Introduced: ODBC 3.0 Standards Compliance: ISO 92

Summary
SQLFreeHandle frees resources associated with a specific environment, connection, statement, or descriptor handle.

Syntax

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);  

Arguments

HandleType
[Input] The type of handle to be freed by SQLFreeHandle. Must be one of the following values:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handle is used only by the Driver Manager and driver. Applications should not use this handle type. For more information about SQL_HANDLE_DBC_INFO_TOKEN, see Developing Connection-Pool Awareness in an ODBC Driver.

If HandleType is not one of these values, SQLFreeHandle returns SQL_INVALID_HANDLE.

Handle
[Input] The handle to be freed.

Returns

SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.

If SQLFreeHandle returns SQL_ERROR, the handle is still valid.

Diagnostics

When SQLFreeHandle returns SQL_ERROR, an associated SQLSTATE value may be obtained from the diagnostic data structure for the handle that SQLFreeHandle tried to free but could not. The following table lists the SQLSTATE values typically returned by SQLFreeHandle and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

Comments

SQLFreeHandle is used to free handles for environments, connections, statements, and descriptors, as described in the following sections. For general information about handles, see Handles.

An application should not use a handle after it has been freed; the Driver Manager does not check the validity of a handle in a function call.

Freeing an Environment Handle

Before it calls SQLFreeHandle with a HandleType of SQL_HANDLE_ENV, an application must call SQLFreeHandle with a HandleType of SQL_HANDLE_DBC for all connections allocated under the environment. Otherwise, the call to SQLFreeHandle returns SQL_ERROR and the environment and any active connection remains valid. For more information, see Environment Handles and Allocating the Environment Handle.

If the environment is a shared environment, the application that calls SQLFreeHandle with a HandleType of SQL_HANDLE_ENV no longer has access to the environment after the call, but the environment's resources are not necessarily freed. The call to SQLFreeHandle decrements the reference count of the environment. The reference count is maintained by the Driver Manager. If it does not reach zero, the shared environment is not freed, because it is still being used by another component. If the reference count reaches zero, the resources of the shared environment are freed.

Freeing a Connection Handle

Before it calls SQLFreeHandle with a HandleType of SQL_HANDLE_DBC, an application must call SQLDisconnect for the connection if there is a connection on this handle*.* Otherwise, the call to SQLFreeHandle returns SQL_ERROR and the connection remains valid.

For more information, see Connection Handles and Disconnecting from a Data Source or Driver.

Freeing a Statement Handle

A call to SQLFreeHandle with a HandleType of SQL_HANDLE_STMT frees all resources that were allocated by a call to SQLAllocHandle with a HandleType of SQL_HANDLE_STMT. When an application calls SQLFreeHandle to free a statement that has pending results, the pending results are deleted. When an application frees a statement handle, the driver frees the four automatically allocated descriptors associated with that handle. For more information, see Statement Handles and Freeing a Statement Handle.

Notice that SQLDisconnect automatically drops any statements and descriptors open on the connection.

Freeing a Descriptor Handle

A call to SQLFreeHandle with a HandleType of SQL_HANDLE_DESC frees the descriptor handle in Handle. The call to SQLFreeHandle does not release any memory allocated by the application that may be referenced by a pointer field (including SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, and SQL_DESC_OCTET_LENGTH_PTR) of any descriptor record of Handle. The memory allocated by the driver for fields that are not pointer fields is freed when the handle is freed. When a user-allocated descriptor handle is freed, all statements that the freed handle had been associated with revert to their respective automatically allocated descriptor handles.

Notice that SQLDisconnect automatically drops any statements and descriptors open on the connection. When an application frees a statement handle, the driver frees all the automatically generated descriptors associated with that handle.

For more information about descriptors, see Descriptors.

Code Example

For additional code samples, see SQLBrowseConnect and SQLConnect.

Code

// 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;   
   }  
}  

Related Functions

See Also

ODBC API Reference
ODBC Header Files
Sample ODBC Program