| Specification: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLFreeHandle() frees resources associated with a specific environment, connection, or statement handle.
This function is a generic function for freeing resources. It replaces SQLFreeConnect (for freeing a connection handle) and SQLFreeEnv() (for freeing an environment handle). SQLFreeHandle() also replaces SQLFreeStmt() (with the SQL_DROP Option) for freeing a statement handle.
Syntax
SQLRETURN SQLFreeHandle (SQLSMALLINT HandleType,
SQLHANDLE Handle);
Function arguments
Table 60. 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 name of the handle to be freed. |
Usage
SQLFreeHandle() is used to free handles for environments, connections, and statements.
An application should not use a handle after the handle is 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. If there are results pending when SQLFreeHandle() is called, the result sets are discarded.
SQLDisconnect() automatically drops any statements open on the connection.
Return codes
If SQLFreeHandle() returns SQL_ERROR, the handle is still valid.
Diagnostics
Table 61. SQLFreeHandle SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Communication link failure. | The HandleType argument is SQL_HANDLE_DBC, and the communication link between DB2 CLI and the data source to which it is trying to connect failed before the function completed processing. |
| HY000 | General error. | An error occurred for which there is 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 is unable to allocate memory required to support execution or completion of the function. |
| HY010 | Function sequence error. | The HandleType argument is SQL_HANDLE_ENV, and at least one
connection is 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 is SQL_HANDLE_DBC, and
the function is called before calling SQLDisconnect() for the
connection.
The HandleType argument is SQL_HANDLE_STMT; SQLExecute() or SQLExecDirect() is called with the statement handle, and returned SQL_NEED_DATA. (DM) All subsidiary handles and other resources were not released before SQLFreeHandle() is called. |
| HY013 | Unexpected memory handling error. | The HandleType argument is SQL_HANDLE_STMT 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 is set to the handle for an automatically allocated descriptor or an implementation descriptor. |
Restrictions
None.
Related reference