Partilhar via


Função SQLFreeHandle

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: ISO 92

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

Observação

Essa função é uma função genérica para liberar identificadores. 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 (pela opção SQL_DROP) para liberar um identificador de instrução. Para obter mais informações, confira "Comentários". Para obter mais informações sobre como o Gerenciador de Driver mapeia essa função para quando um aplicativo ODBC 3*.x* está trabalhando com um driver ODBC 2*.x*, consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.

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 identificador é usado apenas pelo Driver Manager 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 Developing Connection-Pool Awareness in an ODBC Driver.

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

Handle
[Entrada] O identificador a ser liberado.

Retornos

SQL_SUCCESS, SQL_ERROR ou SQL_INVALID_HANDLE.

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

Diagnósticos

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 pôde. 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 retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado o contrário.

SQLSTATE Erro Descrição
HY000 Erro geral Ocorreu um erro para o qual não havia nenhum SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa.
HY001 Erro de alocação de memória O driver não pôde alocar memória necessária para dar suporte à execução ou à conclusão da função.
HY010 Erro de sequência de funções (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 devem ser chamados 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 em 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, SQLBulkOperations ou SQLSetPos foi chamado com o identificador de instrução e retornado SQL_NEED_DATA. Essa 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 essa função foi chamada.

(DM) Todos os identificadores de subsidiária e outros recursos não foram liberados antes de SQLFreeHandle ser chamado.

(DM) SQLExecute, SQLExecDirect ou 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. Essa função foi chamada antes de os dados serem 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 memória insuficiente.
HY017 Uso inválido de um identificador de descritor alocado automaticamente. (DM) O argumento Handle foi definido como o identificador de um descritor alocado automaticamente.
HY117 A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar e somente leitura são permitidas. (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran.
HYT01 O tempo limite da conexão expirou O período de tempo limite da conexão expirou antes da fonte de dados responder à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 O driver não dá suporte a essa 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.

Comentários

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 Identificadores.

Um aplicativo não deve usar um identificador 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 retornará SQL_ERROR e o ambiente e qualquer conexão ativa permanecerá válida. Para obter mais informações, consulte Identificadores de ambiente e Alocando o identificador de ambiente.

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 Gerenciador de Driver. Se ele não atingir zero, o ambiente compartilhado não será liberado, pois ainda está sendo usado por outro componente. Se a contagem de referência atingir zero, os recursos do ambiente compartilhado serão liberados.

Liberando um identificador de conexão

Antes de chamar SQLFreeHandle com um HandleType de SQL_HANDLE_DBC, um aplicativo deverá 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 Desconectando 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 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 Identificadores de instrução e Liberando um identificador de instrução.

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

Liberando um identificador de descritor

Uma chamada para SQLFreeHandle com um HandleType de SQL_HANDLE_DESC libera o identificador do descritor no 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 às quais o identificador liberado foi associado são revertidas para seus respectivos identificadores de descritor alocados automaticamente.

Observação

Os drivers ODBC 2*.x* não dão suporte à liberação de identificadores de descritor, assim como não dão suporte à alocação de identificadores de descritor.

Observe que o SQLDisconnect remove 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 Consulte
Alocando um identificador Função SQLAllocHandle
Cancelando o processamento da instrução SQLCance Functionl
Definindo um nome de cursor Função SQLSetCursorName

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Programa ODBC de exemplo