.NET Framework Developer Center

HandleType

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

SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC

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

Handle

[Input] The handle to be freed.

SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.

If SQLFreeHandle returns SQL_ERROR, the handle is still valid.

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.

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.

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.

When the Driver Manager processes the call to SQLFreeHandle with a HandleType of SQL_HANDLE_ENV, it checks the TraceAutoStop keyword in the [ODBC] section of the ODBC subkey of the system information. If it is set to 1, the Driver Manager disables tracing for all applications and sets the Trace keyword in the [ODBC] section of the ODBC subkey of the system information to 0. For information about what happens to tracing when SQLFreeHandle is called, see ODBC Subkey.

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.

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.

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.

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.

Note
ODBC 2.x drivers do not support freeing descriptor handles, just as they do not support allocating 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.

For additional code samples, see SQLBrowseConnect and 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) { 
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
      hdbc = NULL; 
   }
   if (henv) { 
      SQLFreeHandle(SQL_HANDLE_ENV, henv);
      henv = NULL; 
   }
   if (hdbc)
      SQLDisconnect(hdbc);
}

Concepts

Other Resources