SQLFreeHandle() - Free a handle
SQLFreeHandle() frees an environment handle,
a connection handle, or a statement handle.
ODBC specifications for SQLFreeHandle()
| ODBC specification level | In X/Open CLI CAE specification? | In ISO CLI specification? |
|---|---|---|
| 3.0 | Yes | Yes |
Syntax
SQLRETURN SQLFreeHandle (SQLSMALLINT HandleType,
SQLHANDLE Handle);Function arguments
The following table lists the data type, use, and description for each argument in this function.
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLSMALLINT | HandleType | input | Specifies the type of handle to be
freed by SQLFreeHandle(). You must specify one of
the following values:
|
| SQLHANDLE | Handle | input | Specifies the name of the handle to be freed. |
Usage
Use SQLFreeHandle() to
free handles for environments, connections, and statements. After
you free a handle, you no longer use that handle in your application.
- Freeing an environment handle
You must free all connection handles before you free the environment handle. If you attempt to free the environment handle while connection handles remain,
SQLFreeHandle()returns SQL_ERROR and the environment and any active connection remains valid. - Freeing a connection handle
You must both free all statement handles and call
SQLDisconnect()on a connection before you free the handle for that connection. If you attempt to free a connection handle while statement handles remain for that connection,SQLFreeHandle()returns SQL_ERROR and the connection remains valid. - Freeing a statement handle
When you call
SQLFreeHandle()to free a statement handle, all resources that a call toSQLAllocHandle()with a HandleType of SQL_HANDLE_STMT allocates are freed. When you callSQLFreeHandle()to free a statement with pending results, those results are deleted.
SQLDisconnect() automatically drops
any statements open on the connection.
Return codes
SQLFreeHandle(),
it returns one of the following values: - SQL_SUCCESS
- SQL_INVALID_HANDLE
- SQL_ERROR
If the HandleType is not a
valid type, SQLFreeHandle() returns SQL_INVALID_HANDLE.
If SQLFreeHandle() returns SQL_ERROR, the handle
is still valid.
Diagnostics
The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | Informational message. (SQLFreeHandle() returns
SQL_SUCCESS_WITH_INFO for this SQLSTATE.) |
| 08003 | Connection is closed. | The HandleType argument specifies SQL_HANDLE_DBC, but the communication link between Db2 ODBC and the data source failed before the function completed processing. |
| HY000 | General error. | An error occurred for which no specific
SQLSTATE exists. The error message that is returned by SQLGetDiagRec() in
the buffer that the MessageText argument
specifies, describes the error and its cause. |
| HY001 | Memory allocation failure. | Db2 ODBC is not able to allocate memory that is required to support execution or completion of the function. |
| HY010 | Function sequence error. | This SQLSTATE is returned for one
or more of the following reasons:
|
| HY013 | Unexpected memory handling error. | The HandleType argument is SQL_HANDLE_STMT and the function call can not be processed because the underlying memory objects can not be accessed. This error can result from low memory conditions. |
| HY506 | Error closing a file. | An error is encountered when trying to close a temporary file. |
Example
Refer to the DSN8O3VP sample application or online in the DSN1110.SDSNSAMP data set.