Función SQLFreeHandle

Conformidad
Versión introducida: Cumplimiento de estándares odbc 3.0: ISO 92

Resumen
SQLFreeHandle libera los recursos asociados a un entorno, conexión, instrucción o identificador de descriptor específicos.

Nota

Esta función es una función genérica para liberar identificadores. Reemplaza las funciones DE ODBC 2.0 SQLFreeConnect (para liberar un identificador de conexión) y SQLFreeEnv (para liberar un identificador de entorno). SQLFreeConnect y SQLFreeEnv están en desuso en ODBC 3*.x*. SQLFreeHandle también reemplaza a la función DE ODBC 2.0 SQLFreeStmt (con la opción SQL_DROP) para liberar un identificador de instrucción. Para obtener más información, vea "Comentarios". Para obtener más información sobre lo que asigna el Administrador de controladores a esta función cuando una aplicación ODBC 3*.x* está trabajando con un controlador ODBC 2*.x*, vea Mapping Replacement Functions for Backward Compatibility of Applications.

Sintaxis

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);  

Argumentos

HandleType
[Entrada] Tipo de identificador que SQLFreeHandle va a liberar. Debe ser uno de los siguientes valores:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN controlador solo lo usa el Administrador de controladores y el controlador. Las aplicaciones no deben usar este tipo de identificador. Para obtener más información sobre SQL_HANDLE_DBC_INFO_TOKEN, vea Developing Connection-Pool Awareness in an ODBC Driver.

Si HandleType no es uno de estos valores, SQLFreeHandle devuelve SQL_INVALID_HANDLE.

Handle
[Entrada] Identificador que se va a liberar.

Devoluciones

SQL_SUCCESS, SQL_ERROR o SQL_INVALID_HANDLE.

Si SQLFreeHandle devuelve SQL_ERROR, el identificador sigue siendo válido.

Diagnóstico

Cuando SQLFreeHandle devuelve SQL_ERROR, se puede obtener un valor SQLSTATE asociado de la estructura de datos de diagnóstico para el identificador que SQLFreeHandle intentó liberar pero no. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLFreeHandle y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

SQLSTATE	Error	Descripción
HY000	Error general	Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa.
HY001	Error de asignación de memoria	El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función.
HY010	Error de secuencia de función	(DM) El argumento HandleType se SQL_HANDLE_ENV y al menos una conexión estaba en un estado asignado o conectado. Se debe llamar a SQLDisconnect y SQLFreeHandle con un HandleType de SQL_HANDLE_DBC para cada conexión antes de llamar a SQLFreeHandle con un HandleType de SQL_HANDLE_ENV. (DM) El argumento HandleType se SQL_HANDLE_DBC y se llamó a la función antes de llamar a SQLDisconnect para la conexión. (DM) El argumento HandleType se SQL_HANDLE_DBC. Se llamó a una función de ejecución asincrónica con Handle y la función todavía se estaba ejecutando cuando se llamó a esta función. (DM) El argumento HandleType se SQL_HANDLE_STMT. Se llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos con el identificador de instrucción y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución. (DM) El argumento HandleType se SQL_HANDLE_STMT. Se llamó a una función de ejecución asincrónica en el identificador de instrucción o en el identificador de conexión asociado y la función todavía se estaba ejecutando cuando se llamó a esta función. (DM) El argumento HandleType se SQL_HANDLE_DESC. Se llamó a una función de ejecución asincrónica en el identificador de conexión asociado; y la función todavía se estaba ejecutando cuando se llamó a esta función. (DM) No se liberaron todos los identificadores secundarios y otros recursos antes de llamar a SQLFreeHandle . (DM) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para uno de los identificadores de instrucción asociados a Handle y HandleType en SQL_HANDLE_STMT o SQL_HANDLE_DESC devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos.
HY013	Error de administración de memoria	El argumento HandleType se SQL_HANDLE_STMT o SQL_HANDLE_DESC, y no se pudo procesar la llamada a la función porque no se pudo acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY017	Uso no válido de un identificador de descriptor asignado automáticamente.	(DM) El argumento Handle se estableció en el identificador de un descriptor asignado automáticamente.
HY117	La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura.	(DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
HYT01	Se ha agotado el tiempo de espera de la conexión.	El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	El controlador no admite esta función	(DM) El argumento HandleType se SQL_HANDLE_DESC y el controlador era un controlador ODBC 2*.x*. (DM) El argumento HandleType se SQL_HANDLE_STMT y el controlador no era un controlador ODBC válido.

Comentarios

SQLFreeHandle se usa para liberar identificadores para entornos, conexiones, instrucciones y descriptores, como se describe en las secciones siguientes. Para obtener información general sobre los identificadores, vea Identificadores.

Una aplicación no debe usar un identificador una vez liberado; El Administrador de controladores no comprueba la validez de un identificador en una llamada de función.

Liberar un identificador 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 en el entorno. De lo contrario, la llamada a SQLFreeHandle devuelve SQL_ERROR y el entorno y cualquier conexión activa permanece válida. Para obtener más información, vea Identificadores de entorno y Asignación del identificador de entorno.

Si el entorno es un entorno compartido, la aplicación que llama a SQLFreeHandle con un HandleType de SQL_HANDLE_ENV ya no tiene acceso al entorno después de la llamada, pero los recursos del entorno no se liberan necesariamente. La llamada a SQLFreeHandle disminuye el recuento de referencias del entorno. El Administrador de controladores mantiene el recuento de referencias. Si no alcanza cero, el entorno compartido no se libera, ya que sigue siendo utilizado por otro componente. Si el recuento de referencias alcanza cero, se liberan los recursos del entorno compartido.

Liberar un identificador de conexión

Antes de llamar a SQLFreeHandle con un HandleType de SQL_HANDLE_DBC, una aplicación debe llamar a SQLDisconnect para la conexión si hay una conexión en este identificador*.* De lo contrario, la llamada a SQLFreeHandle devuelve SQL_ERROR y la conexión permanece válida.

Para obtener más información, consulte Controladores de conexión y desconexiónde un origen de datos o controlador.

Liberar un identificador de instrucción

Una llamada a SQLFreeHandle con un HandleType de SQL_HANDLE_STMT libera todos los recursos asignados por una llamada a SQLAllocHandle con un HandleType de SQL_HANDLE_STMT. Cuando una aplicación llama a SQLFreeHandle para liberar una instrucción que tiene resultados pendientes, se eliminan los resultados pendientes. Cuando una aplicación libera un identificador de instrucción, el controlador libera los cuatro descriptores asignados automáticamente asociados a ese identificador. Para obtener más información, vea Identificadores de instrucción y Liberar un identificador de instrucción.

Observe que SQLDisconnect quita automáticamente las instrucciones y descriptores abiertos en la conexión.

Liberar un identificador de descriptor

Una llamada a SQLFreeHandle con un HandleType de SQL_HANDLE_DESC libera el identificador del descriptor en Handle. La llamada a SQLFreeHandle no libera ninguna memoria asignada por la aplicación a la que pueda hacer referencia un campo de puntero (incluidos SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR) de ningún registro descriptor de Handle. La memoria asignada por el controlador para los campos que no son campos de puntero se libera cuando se libera el identificador. Cuando se libera un identificador de descriptor asignado por el usuario, se han asociado todas las instrucciones a las que se había asociado el identificador liberado con la reversión a sus respectivos identificadores de descriptor asignados automáticamente.

Nota

Los controladores ODBC 2*.x* no admiten identificadores de descriptores de liberador, al igual que no admiten la asignación de identificadores de descriptor.

Observe que SQLDisconnect quita automáticamente las instrucciones y descriptores abiertos en la conexión. Cuando una aplicación libera un identificador de instrucción, el controlador libera todos los descriptores generados automáticamente asociados a ese identificador.

Para obtener más información sobre los descriptores, vea Descriptores.

Ejemplo de código

Para obtener ejemplos de código adicionales, consulte SQLBrowseConnect y SQLConnect.

Código

// SQLFreeHandle.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <stdio.h>  
  
int main() {  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   // Initialize the environment, connection, statement handles.  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   // Allocate the environment.  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set environment attributes.  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
  
   // Allocate the connection.  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
   // Set the login timeout.  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
  
   // Let the user select the data source and connect to the database.  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // Free handles, and disconnect.     
   if (hstmt) {   
      SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
      hstmt = NULL;   
   }  
   if (hdbc) {   
      SQLDisconnect(hdbc);  
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      hdbc = NULL;   
   }  
   if (henv) {   
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
      henv = NULL;   
   }  
}  

Funciones relacionadas

Para información acerca de	Vea
Asignación de un identificador	Función SQLAllocHandle
Cancelación del procesamiento de instrucciones	SQLCance (Functionl)
Establecimiento de un nombre de cursor	Función SQLSetCursorName

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC
Programa de ejemplo de ODBC