Freeing handles in CLI applications

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.