Freeing handles in CLI applications
SQLFreeHandle() function.
Environment handle
Before calling the SQLFreeHandle() function
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 remains valid, as well as any connection associated
with that environment.
Connection handle
If a connection is open
on the handle, an application must call SQLDisconnect() for
the connection before calling SQLFreeHandle() with
a HandleType of SQL_HANDLE_DBC. Otherwise,
the call to SQLFreeHandle() returns SQL_ERROR and
the connection remains valid.
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 discarded. When
an application frees a statement handle, CLI frees
all the automatically generated descriptors associated with that handle.
Note that SQLDisconnect() automatically
drops any statements and descriptors open on the connection.
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 the deferred fields (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR,
and SQL_DESC_OCTET_LENGTH_PTR) of any descriptor record of Handle.
When an explicitly allocated descriptor handle is freed, all statements
that the freed handle had been associated with revert to their automatically
allocated descriptor handle.
Note that SQLDisconnect() automatically
drops any statements and descriptors open on the connection. When
an application frees a statement handle, CLI frees
all the automatically generated descriptors associated with that handle.