SQLFreeHandle() - Free a handle

SQLFreeHandle() frees an environment handle, a connection handle, or a statement handle.

ODBC specifications for SQLFreeHandle()

Table 1. SQLFreeHandle() specifications
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.

Table 2. SQLFreeHandle() arguments
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:
  • SQL_HANDLE_ENV to free the environment handle
  • SQL_HANDLE_DBC to free a connection handle
  • SQL_HANDLE_STMT to free a statement handle
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 to SQLAllocHandle() with a HandleType of SQL_HANDLE_STMT allocates are freed. When you call SQLFreeHandle() to free a statement with pending results, those results are deleted.

SQLDisconnect() automatically drops any statements open on the connection.

Return codes

After you call 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.

Table 3. SQLFreeHandle() SQLSTATEs
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:
  • If the HandleType argument is SQL_HANDLE_ENV, and at least one connection is in an allocated or connected state, you must call SQLDisconnect() and SQLFreeHandle() to disconnect and free each connection before you can free the environment handle. If the HandleType argument is SQL_HANDLE_DBC you must free all statement handles on the connection, and disconnect before you can free the connection handle.
  • If the HandleType argument specifies SQL_HANDLE_STMT, SQLExecute() or SQLExecDirect() is called with the statement handle, and return SQL_NEED_DATA. This function is called before data is sent for all data-at-execution parameters or columns. You must issue SQLCancel() to free the statement handle.
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.