SQLFreeHandle

SQLFreeHandle

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

Syntax

SQLRETURN  SQLFreeHandle (
    SQLSMALLINT handleType,
    SQLHANDLE   handle );

Arguments

Data Type	Argument	In/Output	Description
SQLSMALLINT	handleType	Input	Handle type to be freed: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT - If the handleType is not the one of these values, SQLFreeHandle() free SQL_INVALID_HANDLE.
SQLHANDLE	handle	Input	Handle to be freed

Return Values

SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR

If SQLFreeHandle() returns SQL_ERROR, the handle is valid.

Description

SQLFreeHandle() can replace with SQLFreeEnv(), SQLFreeConnect(), and SQLFreeStmt() function.

Once the handle is released, an application cannot use the released handle.

Freeing an Environment Handle

Before handleType calls SQLFreeHandle(), SQL_HANDLE_ENV, an application must call SQLFreeHandle() of which handleType is SQL_HANDLE_DBC for all connections allocated in the corresponding environment. Otherwise, calling SQLFreeHandle() will return SQL_ERROR and the corresponding environment and the random activated connection remains still vaild.

Freeing a Connection Handle

If an error is detected on this handle before handleType calls SQLFreeHandle(), SQL_HANDLE_DBC, an application must call SQLDisconnect() for the connection. Otherwise, calling of SQLFreeHandle() will return SQL_ERROR and connection will be still vaild.

Freeing a Statement Hanle

Calling SQLFreeHandle() of which handleType is SQL_HANDLE_STMT will release all resources allocated by calling SQLAllocHandle of which handleType is SQL_HANDLE_STMT. Calling SQLFreeHandle() to release the command with the result suspended by an application will delete the suspended results.

Diagnosis

SQLSTATE	Description	Comments
HY000	General error
HY001	Memory allocation error	Failed to allocate the memory for the explicit handle.

Related Function

SQLAllocHandle

Example

< Refer to: $ALTIBASE_HOME/sample/SQLCLI/demo_meta1.cpp >

if ( dbc != NULL ) 
{
    SQLFreeHandle( SQL_HANDLE_DBC, dbc );
}
if ( env != NULL ) 
{
    SQLFreeHandle( SQL_HANDLE_ENV, env );
}