Função SQLFreeHandle

Conformidade
Versão introduzida: Conformidade com as normas ODBC 3.0: ISO 92

Resumo
SQLFreeHandle libera recursos associados a um ambiente, conexão, instrução ou identificador de descritor específico.

Observação

Esta função é uma função genérica para libertar alças. Ele substitui as funções ODBC 2.0 SQLFreeConnect (para liberar um identificador de conexão) e SQLFreeEnv (para liberar um identificador de ambiente). SQLFreeConnect e SQLFreeEnv foram preteridos no ODBC 3*.x*. SQLFreeHandle também substitui a função ODBC 2.0 SQLFreeStmt (com o SQL_DROP Option) para liberar um identificador de instrução. Para obter mais informações, consulte "Comentários". Para obter mais informações sobre o que o Gerenciador de Driver mapeia essa função para quando um aplicativo ODBC 3*.x* está trabalhando com um driver ODBC 2*.x*, consulte Mapping Replacement Functions for Backward Compatibility of Applications.

Sintaxe

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);

Argumentos

HandleType
[Entrada] O tipo de identificador a ser liberado por SQLFreeHandle. Deve ser um dos seguintes valores:

SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN alça é usada apenas pelo Gerenciador de Driver e pelo driver. Os aplicativos não devem usar esse tipo de identificador. Para obter mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Desenvolvendo o reconhecimento Connection-Pool em um driver ODBC.

Se HandleType não for um desses valores, SQLFreeHandle retornará SQL_INVALID_HANDLE.

Manipular
[Entrada] A alça a ser libertada.

Devoluções

SQL_SUCCESS, SQL_ERROR ou SQL_INVALID_HANDLE.

Se SQLFreeHandle retornar SQL_ERROR, o identificador ainda será válido.

Diagnóstico

Quando SQLFreeHandle retorna SQL_ERROR, um valor SQLSTATE associado pode ser obtido da estrutura de dados de diagnóstico para o identificador que SQLFreeHandle tentou liberar, mas não conseguiu. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLFreeHandle e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornados pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

SQLSTATE	Erro	Descrição
HY000	Erro geral	Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico de implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer de *MessageText descreve o erro e sua causa.
HY001	Erro de alocação de memória	O driver não pôde alocar a memória necessária para suportar a execução ou conclusão da função.
HY010	Erro de sequência de função	(DM) O argumento HandleType foi SQL_HANDLE_ENV e pelo menos uma conexão estava em um estado alocado ou conectado. SQLDisconnect e SQLFreeHandle com um HandleType de SQL_HANDLE_DBC deve ser chamado para cada conexão antes de chamar SQLFreeHandle com um HandleType de SQL_HANDLE_ENV. (DM) O argumento HandleType foi SQL_HANDLE_DBC e a função foi chamada antes de chamar SQLDisconnect para a conexão. (DM) O argumento HandleType foi SQL_HANDLE_DBC. Uma função de execução assíncrona foi chamada com Handle e a função ainda estava em execução quando essa função foi chamada. (DM) O argumento HandleType foi SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperationsou SQLSetPos foi chamado com o identificador de instrução e retornou SQL_NEED_DATA. Esta função foi chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados em execução. (DM) O argumento HandleType foi SQL_HANDLE_STMT. Uma função de execução assíncrona foi chamada no identificador de instrução ou no identificador de conexão associado e a função ainda estava em execução quando essa função foi chamada. (DM) O argumento HandleType foi SQL_HANDLE_DESC. Uma função de execução assíncrona foi chamada no identificador de conexão associado; e a função ainda estava em execução quando esta função foi chamada. (DM) Todos os identificadores de subsidiária e outros recursos não foram liberados antes SQLFreeHandle foi chamado. (DM) SQLExecute, SQLExecDirectou SQLMoreResults foi chamado para um dos identificadores de instrução associados ao Handle e HandleType foi definido como SQL_HANDLE_STMT ou SQL_HANDLE_DESC retornado SQL_PARAM_DATA_AVAILABLE. Esta função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos.
HY013	Erro de gerenciamento de memória	O argumento HandleType foi SQL_HANDLE_STMT ou SQL_HANDLE_DESC, e a chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de pouca memória.
HY017	Uso inválido de um identificador de descritor alocado automaticamente.	(DM) O argumento Handle foi definido como o identificador para um descritor alocado automaticamente.
HY117	A conexão é suspensa devido ao estado desconhecido da transação. Apenas as funções de desconexão e somente leitura são permitidas.	(DM) Para obter mais informações sobre o estado suspenso, consulte função SQLEndTran.
HYT01	O tempo limite de conexão expirou	O período de tempo limite de conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Driver não suporta esta função	(DM) O argumento HandleType foi SQL_HANDLE_DESC e o driver era um driver ODBC 2.x. (DM) O argumento HandleType foi SQL_HANDLE_STMT e o driver não era um driver ODBC válido.

Observações

SQLFreeHandle é usado para liberar identificadores para ambientes, conexões, instruções e descritores, conforme descrito nas seções a seguir. Para obter informações gerais sobre identificadores, consulte Handles.

Um aplicativo não deve usar uma alça depois de ter sido liberado; o Gerenciador de Driver não verifica a validade de um identificador em uma chamada de função.

Liberando um identificador de ambiente

Antes de chamar SQLFreeHandle com um HandleType de SQL_HANDLE_ENV, um aplicativo deve chamar SQLFreeHandle com um HandleType de SQL_HANDLE_DBC para todas as conexões alocadas no ambiente. Caso contrário, a chamada para SQLFreeHandle retorna SQL_ERROR e o ambiente e qualquer conexão ativa permanece válida. Para obter mais informações, consulte Environment Handles e Allocating the Environment Handle.

Se o ambiente for um ambiente compartilhado, o aplicativo que chama SQLFreeHandle com um HandleType de SQL_HANDLE_ENV não terá mais acesso ao ambiente após a chamada, mas os recursos do ambiente não serão necessariamente liberados. A chamada para SQLFreeHandle diminui a contagem de referência do ambiente. A contagem de referência é mantida pelo Driver Manager. Se não chegar a zero, o ambiente compartilhado não é liberado, porque ainda está sendo usado por outro componente. Se a contagem de referência chegar a zero, os recursos do ambiente compartilhado serão liberados.

Liberando uma alça de conexão

Antes de chamar SQLFreeHandle com um HandleType de SQL_HANDLE_DBC, um aplicativo deve chamar SQLDisconnect para a conexão se houver uma conexão nesse identificador*.* Caso contrário, a chamada para SQLFreeHandle retornará SQL_ERROR e a conexão permanecerá válida.

Para obter mais informações, consulte identificadores de conexão e Desconexão de uma fonte de dados ou driver.

Liberando um identificador de instrução

Uma chamada para SQLFreeHandle com um HandleType de SQL_HANDLE_STMT libera todos os recursos que foram alocados por uma chamada para SQLAllocHandle com um HandleType de SQL_HANDLE_STMT. Quando um aplicativo chama SQLFreeHandle para liberar uma instrução que tem resultados pendentes, os resultados pendentes são excluídos. Quando um aplicativo libera um identificador de instrução, o driver libera os quatro descritores alocados automaticamente associados a esse identificador. Para obter mais informações, consulte Statement Handles e Freeing a Statement Handle.

Observe que SQLDisconnect descarta automaticamente todas as instruções e descritores abertos na conexão.

Liberando um identificador descritor

Uma chamada para SQLFreeHandle com um HandleType de SQL_HANDLE_DESC libera o identificador descritor em Handle. A chamada para SQLFreeHandle não libera nenhuma memória alocada pelo aplicativo que possa ser referenciada por um campo de ponteiro (incluindo SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR) de qualquer registro descritor de Handle. A memória alocada pelo driver para campos que não são campos de ponteiro é liberada quando o identificador é liberado. Quando um identificador de descritor alocado pelo usuário é liberado, todas as instruções com as quais o identificador liberado foi associado revertem para seus respetivos identificadores de descritor alocados automaticamente.

Observação

Os drivers ODBC 2*.x* não suportam a liberação de identificadores de descritores, assim como não suportam a alocação de identificadores de descritores.

Observe que SQLDisconnect descarta automaticamente todas as instruções e descritores abertos na conexão. Quando um aplicativo libera um identificador de instrução, o driver libera todos os descritores gerados automaticamente associados a esse identificador.

Para obter mais informações sobre descritores, consulte Descritores.

Exemplo de código

Para obter exemplos de código adicionais, consulte SQLBrowseConnect e 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;   
   }  
}

Para obter informações sobre	Ver
Alocando uma alça	de função SQLAllocHandle
Cancelamento do processamento de instruções	da função SQLCancel
Definir um nome de cursor	da função SQLSetCursorName

Comentários

Esta página foi útil?

Last updated on 2026-07-21