SQLFreeHandle--Liberar recursos de descriptor de contexto

Finalidad


Especificación: CLI de DB2 5.0 ODBC 3.0 ISO CLI

SQLFreeHandle() libera recursos asociados a un descriptor de entorno, conexión o sentencia específico.

Esta función es una función genérica para liberar recursos. Sustituye a SQLFreeConnect (para liberar un descriptor de conexión) y a SQLFreeEnv() (para liberar un descriptor de entorno). SQLFreeHandle() también sustituye a SQLFreeStmt() (con la opción SQL_DROP) para liberar un descriptor de sentencia.

Sintaxis 

SQLRETURN   SQLFreeHandle    (SQLSMALLINT       HandleType,
                              SQLHANDLE         Handle);

Argumentos de la función

Tabla 60. Argumentos de SQLFreeHandle

Tipo de datos Argumento Uso Descripción
SQLSMALLINT HandleType entrada El tipo de descriptor de contexto que debe ser liberado por SQLFreeHandle(). Debe ser uno de los valores siguientes:

SQL_HANDLE_ENV

SQL_HANDLE_DBC

SQL_HANDLE_STMT

Si HandleType no es uno de los valores anteriores, SQLFreeHandle() devuelve SQL_INVALID_HANDLE.
SQLHANDLE Handle entrada El nombre del descriptor de contexto que se debe liberar.

Uso

SQLFreeHandle() se utiliza para liberar descriptores de contexto para entornos, conexiones y sentencias.

Una vez liberado un descriptor de contexto, no debe ser utilizado por una aplicación; CLI de DB2 no comprueba la validez de un descriptor de contexto en una llamada a función.

Liberación de un descriptor de entorno

Antes de llamar a SQLFreeHandle() con un HandleType de SQL_HANDLE_ENV, una aplicación debe llamar a SQLFreeHandle() con un HandleType de SQL_HANDLE_DBC para todas las conexiones asignadas bajo el entorno. De lo contrario, la llamada a SQLFreeHandle() devuelve SQL_ERROR y el entorno y las conexiones activas que haya siguen siendo válidos.

Liberación de un descriptor de conexión

Antes de invocar SQLFreeHandle() con HandleType establecido en SQL_HANDLE_DBC, la aplicación debe invocar SQLDisconnect() para la conexión. De lo contrario, la llamada a SQLFreeHandle() devuelve SQL_ERROR y la conexión sigue siendo válida.

Liberación de un descriptor de sentencia

La llamada a SQLFreeHandle() con HandleType establecido en SQL_HANDLE_STMT libera todos los recursos que fueron asignados por una llamada a SQLAllocHandle() con HandleType establecido en SQL_HANDLE_STMT. Cuando una aplicación invoca SQLFreeHandle() para liberar una sentencia que tiene resultados pendientes, éstos se eliminan. Si hay resultados pendientes cuando se invoca SQLFreeHandle(), se descartan los conjuntos resultantes.

SQLDisconnect() descarta automáticamente las sentencias que estén abiertas en la conexión.

Códigos de retorno

Si SQLFreeHandle() devuelve SQL_ERROR, el descriptor de contexto es válido todavía.

Diagnósticos

Tabla 61. SQLSTATE de SQLFreeHandle

SQLSTATE Descripción Explicación
01000 Aviso. Mensaje informativo. (La función devuelve SQL_SUCCESS_WITH_INFO).
08S01 Error en el enlace de comunicaciones. El argumento HandleType es SQL_HANDLE_DBC, y el enlace de comunicaciones entre CLI de DB2 y la fuente de datos con el que estaba intentando conectar ha fallado antes de que la función terminara su proceso.
HY000 Error general. Se ha producido un error para el que no existe ningún SQLSTATE específico. El mensaje de error devuelto por SQLGetDiagRec() en el almacenamiento intermedio *MessageText describe el error y su causa.
HY001 Error de asignación de memoria. CLI de DB2 no puede asignar la memoria necesaria para ejecutar o finalizar la función.
HY010 Error de secuencia de función. El argumento HandleType es SQL_HANDLE_ENV y el estado de al menos una conexión es asignado o conectado. Antes de llamar a SQLFreeHandle() con un HandleType de SQL_HANDLE_ENV, se debe llamar para cada conexión a SQLDisconnect() y SQLFreeHandle() con un HandleType de SQL_HANDLE_DBC. El argumento HandleType es SQL_HANDLE_DBC, y se llama a la función antes de llamar a SQLDisconnect() para la conexión.

El argumento HandleType es SQL_HANDLE_STMT; se llamó a SQLExecute() o SQLExecDirect() con el descriptor de contexto de sentencia, y la función devolvió SQL_NEED_DATA. (DM) Todos los descriptores de contexto auxiliares y otros recursos no se liberaron antes de llamar a SQLFreeHandle().

HY013 Error inesperado de gestión de la memoria. El argumento HandleType es SQL_HANDLE_STMT y no se pudo procesar la llamada a la función debido a que no se pudo acceder a los objetos de memoria asociados, posiblemente debido a una falta de memoria.
HY017 Utilización no válida de un descriptor de contexto de descriptor asignado automáticamente. El argumento Handle se establece en el descriptor de contexto para un descriptor asignado automáticamente o para un descriptor de implementación.

Restricciones

Ninguna.

Consulta relacionada