f90SQLFreeHandle (SQLFreeHandle)

Conformance

Version Introduced: ODBC 3.0

Standards Compliance: ISO 92

Summary

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

Note: This function is a generic function for freeing handles. It replaces the ODBC 2.0 functions SQLFreeConnect (for freeing a connection handle), and SQLFreeEnv (for freeing an environment handle). SQLFreeConnect and SQLFreeEnv are both deprecated in ODBC 3.0. f90SQLFreeHandle also replaces the ODBC 2.0 function f90SQLFreeStmt (with the SQL_DROP Option) for freeing a statement handle.

Syntax

Arguments

HandleType [Input]

The type of handle to be freed by f90SQLFreeHandle. 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 these values, f90SQLFreeHandle returns SQL_INVALID_HANDLE.

Handle [Input]

The handle to be freed.

iRet [Output]

SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.

If f90SQLFreeHandle returns SQL_ERROR, the handle is still valid.

Diagnostics

When f90SQLFreeHandle returns SQL_ERROR, an associated SQLSTATE value may be obtained from the diagnostic data structure for the handle that f90SQLFreeHandle attempted to free, but could not. The following table lists the SQLSTATE values commonly returned by f90SQLFreeHandle and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

Comments

f90SQLFreeHandle is used to free handles for environments, connections, statements, and descriptors, as described in the following sections. For general information about handles, see "Handles" in Chapter 4, "ODBC Fundamentals."

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

Freeing an Environment Handle

Prior to calling f90SQLFreeHandle with a HandleType of SQL_HANDLE_ENV, an application must call f90SQLFreeHandle with a HandleType of SQL_HANDLE_DBC for all connections allocated under the environment. Otherwise, the call to f90SQLFreeHandle returns SQL_ERROR, and the environment and any active connection remains valid. For more information, see "Environment Handles" in Chapter 4, "ODBC Fundamentals".

When the Driver Manager processes the call to f90SQLFreeHandle with a HandleType of SQL_HANDLE_ENV, it checks the TraceAutoStop keyword in the [ODBC] section of the ODBC subkey of the system information. If it is set to 1, the Driver Manager disables tracing for all applications and sets the Trace keyword in the [ODBC] section of the ODBC subkey of the system information to 0.

If the environment is a shared environment, the application that calls f90SQLFreeHandle with a HandleType of SQL_HANDLE_ENV no longer has access to the environment after the call, but the environment's resources are not necessarily freed. The call to f90SQLFreeHandle decrements the environment's reference count, which is maintained by the Driver Manager. If the reference count does not reach zero, the shared environment is not freed, because it is still being used by another component. If the reference count reaches zero, the shared environment's resources are freed.

Freeing a Connection Handle

Prior to calling f90SQLFreeHandle with a HandleType of SQL_HANDLE_DBC, an application must call f90SQLDisconnect for the connection if there is a connection on this handle. Otherwise, the call to f90SQLFreeHandle returns SQL_ERROR and the connection remains valid.

For more information, see "Connection Handles" in Chapter 4, "ODBC Fundamentals".

Freeing a Statement Handle

A call to f90SQLFreeHandle with a HandleType of SQL_HANDLE_STMT frees all resources that were allocated by a call to f90SQLAllocHandle with a HandleType of SQL_HANDLE_STMT. When an application calls f90SQLFreeHandle to free a statement that has pending results, the pending results are deleted. When an application frees a statement handle, the driver frees the four automatically allocated descriptors associated with that handle. For more information, see "Statement Handles" in Chapter 4, "ODBC Fundamentals".

Note that f90SQLDisconnect automatically drops any statements and descriptors open on the connection.

Freeing a Descriptor Handle

A call to f90SQLFreeHandle with a HandleType of SQL_HANDLE_DESC frees the descriptor handle in Handle. The call to f90SQLFreeHandle does not release any memory allocated by the application that may be referenced by a pointer field (including SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, and SQL_DESC_OCTET_LENGTH_PTR) of any descriptor record of Handle. The memory allocated by the driver for fields that are not pointer fields is freed when the handle is freed. When a user-allocated descriptor handle is freed, all statements that the freed handle had been associated with revert to their respective automatically allocated descriptor handles.

Note: ODBC 2.x drivers do not support freeing descriptor handles, just as they do not support allocating descriptor handles.

Note that f90SQLDisconnect automatically drops any statements and descriptors open on the connection. When an application frees a statement handle, the driver frees all the automatically generated descriptors associated with that handle.

For more information about descriptors, see Chapter 8, "Descriptors."

Code Example

See f90SQLBrowseConnect and f90SQLConnect and examples in chapters 4, 5 and 7.

Related Subroutines