| Specification: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLFreeHandle() frees resources associated with a specific environment, connection, statement, or descriptor handle.
| Note: | This function is a generic function for freeing resources. It replaces the Version 2 functions SQLFreeConnect (for freeing a connection handle), and SQLFreeEnv() (for freeing an environment handle). SQLFreeHandle() also replaces the Version 2 function SQLFreeStmt() (with the SQL_DROP Option) for freeing a statement handle. |
Syntax
SQLRETURN SQLFreeHandle (SQLSMALLINT HandleType,
SQLHANDLE Handle);
Function Arguments
Table 86. SQLFreeHandle Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLSMALLINT | HandleType | input | The type of handle to be freed by SQLFreeHandle(). Must
be one of the following values:
|
| SQLHANDLE | Handle | input | The handle to be freed. |
Usage
SQLFreeHandle() is used to free handles for environments, connections, statements, and descriptors, as described below.
An application should not use a handle after it has been freed; DB2 CLI does not check the validity of a handle in a function call.
Freeing an Environment Handle
Prior to calling 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.
Freeing a Connection Handle
Prior to calling SQLFreeHandle() with a HandleType of SQL_HANDLE_DBC, an application must call SQLDisconnect() for the connection. Otherwise, the call to SQLFreeHandle() returns SQL_ERROR and the connection remains valid.
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, DB2 CLI frees all the automatically generated descriptors associated with that handle. If there are results pending when SQLFreeHandle() is called, the result sets are discarded.
Note 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 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, DB2 CLI frees all the automatically generated descriptors associated with that handle.
Return Codes
If SQLFreeHandle() returns SQL_ERROR, the handle is still valid.
Diagnostics
Table 87. SQLFreeHandle SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Communication link failure. | The HandleType argument was SQL_HANDLE_DBC, and the communication link between DB2 CLI and the data source to which it was trying to connect failed before the function completed processing. |
| HY000 | General error. | An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation failure. | DB2 CLI was unable to allocate memory required to support execution or completion of the function. |
| HY010 | Function sequence error. | The HandleType argument was SQL_HANDLE_ENV, and at least one
connection was in an allocated or connected state.
SQLDisconnect() and SQLFreeHandle() with a
HandleType of SQL_HANDLE_DBC must be called for each connection
before calling SQLFreeHandle() with a HandleType of
SQL_HANDLE_ENV. The HandleType argument was SQL_HANDLE_DBC,
and the function was called before calling SQLDisconnect() for the
connection.
The HandleType argument was SQL_HANDLE_STMT; an asynchronously executing function was called on the statement handle; and the function was still executing when this function was called. The HandleType argument was SQL_HANDLE_STMT; SQLExecute() or SQLExecDirect() was called with the statement handle, and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns. (DM) All subsidiary handles and other resources were not released before SQLFreeHandle() was called. |
| HY013 | Unexpected memory handling error. | The HandleType argument was SQL_HANDLE_STMT or SQL_HANDLE_DESC, and the function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions. |
| HY017 | Invalid use of an automatically allocated descriptor handle. | The Handle argument was set to the handle for an automatically allocated descriptor or an implementation descriptor. |
Restrictions
None.
(The complete sample utilcli.c is also available here .)
/* From the CLI sample utilcli.c */
/* ... */
/* free the environment handle */
printf("\nFreeing the environment handle ...\n");
sqlrc = SQLFreeHandle( SQL_HANDLE_ENV, *pHenv ) ;
rc = HandleInfoPrint( SQL_HANDLE_ENV, *pHenv,
sqlrc, __LINE__, __FILE__);
if( rc == 0)
{ printf("The environment handle is free.\n");
}
References