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;
}
}
Funções relacionadas
| 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