Função SQLFreeHandle
de conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: ISO 92
de Resumo do
SQLFreeHandle libera recursos associados a um ambiente específico, conexão, instrução ou identificador de descritor.
Nota
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 são preteridos no ODBC 3*.x*. SQLFreeHandle também substitui a função ODBC 2.0 SQLFreeStmt (com a opção SQL_DROP ) para liberar um identificador de instrução. Para obter mais informações, consulte "Comentários". Para obter mais informações sobre como o Gerenciador de Driver mapeia essa função para quando um aplicativo ODBC 3*.x* estiver 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 pelo 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 Desenvolvendo reconhecimento de Connection-Pool em umdo Driver ODBC.
Se HandleType não for um desses valores, SQLFreeHandle retornará SQL_INVALID_HANDLE.
manipular
[Entrada] O identificador a ser liberado.
Retorna
SQL_SUCCESS, SQL_ERROR ou SQL_INVALID_HANDLE.
Se SQLFreeHandle retornar SQL_ERROR, o identificador ainda será válido.
Diagnostics
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 observado o contrário.
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 Handles.
Um aplicativo não deve usar um identificador depois de ser 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
Se o ambiente for um ambiente compartilhado, o aplicativo que chama SQLFreeHandle com um HandleType de SQL_HANDLE_ENV não tem mais acesso ao ambiente após a chamada, mas os recursos do ambiente não sã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 ele 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 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 desconectando de uma fonte de dados oude driver.
Liberando um identificador de instrução
Uma chamada para
Observe que SQLDisconnect descarta 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 de 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 de 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 foram associadas serão revertidas para seus respectivos identificadores de descritor alocado automaticamente.
Nota
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 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;
}
}
Funções relacionadas
| Para obter informações sobre | Ver |
|---|---|
| Alocando um identificador | de função SQLAllocHandle |
| Cancelando o processamento de instruções | de função SQLCancel |
| Definindo um nome de cursor | função SQLSetCursorName |
Consulte Também
referência da API ODBC
arquivos de cabeçalho ODBC
do programa ODBC de exemplo de