SQLFreeHandle function (CLI) - Free handle resources

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

Specification:

CLI 5.0
ODBC 3.0
ISO CLI

Note: This function is a generic function for freeing resources. It replaces the ODBC 2.0 functions SQLFreeConnect() (for freeing a connection handle), and SQLFreeEnv() (for freeing an environment handle). SQLFreeHandle() also replaces the ODBC 2.0 function SQLFreeStmt() (with the SQL_DROP Option) for freeing a statement handle.

Syntax

SQLRETURN   SQLFreeHandle (
               SQLSMALLINT       HandleType,  /* fHandleType */
               SQLHANDLE         Handle);     /* hHandle */

Function arguments

Table 1. 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: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC If HandleType is not one of SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT, or SQL_HANDLE_DESC value, SQLFreeHandle() returns SQL_INVALID_HANDLE.
SQLHANDLE	Handle	input	The handle to be freed.

Usage

SQLFreeHandle() is used to free handles for environments, connections, statements, and descriptors.

An application should not use a handle after it has been freed; CLI does not check the validity of a handle in a function call.

Return codes

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE

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

Diagnostics

Table 2. 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 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 is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
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.

Example

  /* free the statement handle */
  cliRC = SQLFreeHandle(SQL_HANDLE_STMT, hstmt2);
  SRV_HANDLE_CHECK_SETTING_SQLRC_AND_MSG(SQL_HANDLE_STMT,
                                         hstmt2,
                                         cliRC,
                                         henv,
                                         hdbc,
                                         pOutSqlrc,
                                         outMsg,
                                         "SQLFreeHandle");
  /* ... */
  /* free the database handle */
  cliRC = SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
  SRV_HANDLE_CHECK_SETTING_SQLRC_AND_MSG(SQL_HANDLE_DBC,
                                         hdbc,
                                         cliRC,
                                         henv,
                                         hdbc,
                                         pOutSqlrc,
                                         outMsg,
                                         "SQLFreeHandle");

  /* free the environment handle */
  cliRC = SQLFreeHandle(SQL_HANDLE_ENV, henv);
  SRV_HANDLE_CHECK_SETTING_SQLRC_AND_MSG(SQL_HANDLE_ENV,
                                         henv,
                                         cliRC,
                                         henv,
                                         hdbc,
                                         pOutSqlrc,
                                         outMsg,
                                         "SQLFreeHandle");