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.

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.

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.

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

Consulte también

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