SQLFreeHandle Function
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Riepilogo
SQLFreeHandle libera le risorse associate a un ambiente, una connessione, un'istruzione o un handle descrittore specifico.
Nota
Questa funzione è una funzione generica per liberare handle. Sostituisce le funzioni ODBC 2.0 SQLFreeConnect (per liberare un handle di connessione) e SQLFreeEnv (per liberare un handle di ambiente). SQLFreeConnect e SQLFreeEnv sono entrambi deprecati in ODBC 3*.x*. SQLFreeHandle sostituisce anche la funzione ODBC 2.0 SQLFreeStmt (con l'opzione SQL_DROP) per liberare un handle di istruzione. Per altre informazioni, vedere "Commenti". Per altre informazioni sul mapping di questa funzione a quando un'applicazione ODBC 3*.x* utilizza un driver ODBC 2*.x*, vedere Mapping di funzioni di sostituzione per compatibilità con le versioni precedenti delle applicazioni.
Sintassi
SQLRETURN SQLFreeHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Argomenti
HandleType
[Input] Tipo di handle da liberare da SQLFreeHandle. Deve essere uno dei valori seguenti:
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN handle viene usato solo da Gestione driver e driver. Le applicazioni non devono usare questo tipo di handle. Per altre informazioni sulle SQL_HANDLE_DBC_INFO_TOKEN, vedere Sviluppo di consapevolezza del pool di connessioni in un driver ODBC.
Se HandleType non è uno di questi valori, SQLFreeHandle restituisce SQL_INVALID_HANDLE.
Handle
[Input] Handle da liberare.
Resi
SQL_SUCCESS, SQL_ERROR o SQL_INVALID_HANDLE.
Se SQLFreeHandle restituisce SQL_ERROR, l'handle è ancora valido.
Diagnostica
Quando SQLFreeHandle restituisce SQL_ERROR, è possibile ottenere un valore SQLSTATE associato dalla struttura dei dati di diagnostica per l'handle che SQLFreeHandle ha tentato di liberare ma non è stato possibile. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLFreeHandle e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| HY000 | Errore generale: | Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa. |
| HY001 | Errore di allocazione della memoria | Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY010 | Errore della sequenza di funzioni | (DM) L'argomento HandleType è stato SQL_HANDLE_ENV e almeno una connessione era allocata o connessa. È necessario chiamare SQLDisconnect e SQLFreeHandle con handleType di SQL_HANDLE_DBC per ogni connessione prima di chiamare SQLFreeHandle con handleType di SQL_HANDLE_ENV. (DM) L'argomento HandleType è stato SQL_HANDLE_DBC e la funzione è stata chiamata prima di chiamare SQLDisconnect per la connessione. (DM) L'argomento HandleType è stato SQL_HANDLE_DBC. Una funzione in esecuzione asincrona è stata chiamata con Handle e la funzione era ancora in esecuzione quando è stata chiamata questa funzione. (DM) L'argomento HandleType è stato SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato con l'handle di istruzione e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution. (DM) L'argomento HandleType è stato SQL_HANDLE_STMT. È stata chiamata una funzione in esecuzione asincrona sull'handle di istruzione o sull'handle di connessione associato e la funzione era ancora in esecuzione quando è stata chiamata questa funzione. (DM) L'argomento HandleType è stato SQL_HANDLE_DESC. È stata chiamata una funzione in esecuzione asincrona sull'handle di connessione associato; e la funzione era ancora in esecuzione quando questa funzione è stata chiamata. (DM) Tutti gli handle sussidiari e altre risorse non sono stati rilasciati prima della chiamata di SQLFreeHandle . (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per uno degli handle di istruzione associati a Handle e HandleType è stato impostato su SQL_HANDLE_STMT o SQL_HANDLE_DESC restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. |
| HY013 | Errore di gestione della memoria | L'argomento HandleType è stato SQL_HANDLE_STMT o SQL_HANDLE_DESC e non è stato possibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente. |
| HY017 | Uso non valido di un handle descrittore allocato automaticamente. | (DM) L'argomento Handle è stato impostato sull'handle per un descrittore allocato automaticamente. |
| HY117 | La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. | (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran. |
| HYT01 | Il timeout della connessione è scaduto | Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Il driver non supporta questa funzione | (DM) L'argomento HandleType è stato SQL_HANDLE_DESC e il driver era un driver ODBC 2*.x*. (DM) L'argomento HandleType è stato SQL_HANDLE_STMT e il driver non era un driver ODBC valido. |
Commenti
SQLFreeHandle viene usato per liberare handle per ambienti, connessioni, istruzioni e descrittori, come descritto nelle sezioni seguenti. Per informazioni generali sugli handle, vedere Handle.
Un'applicazione non deve usare un handle dopo che è stato liberato; Gestione driver non controlla la validità di un handle in una chiamata di funzione.
Liberare un handle di ambiente
Prima di chiamare SQLFreeHandle con handleType di SQL_HANDLE_ENV, un'applicazione deve chiamare SQLFreeHandle con handleType di SQL_HANDLE_DBC per tutte le connessioni allocate nell'ambiente. In caso contrario, la chiamata a SQLFreeHandle restituisce SQL_ERROR e l'ambiente e qualsiasi connessione attiva rimane valida. Per altre informazioni, vedere Handle di ambiente e allocazione dell'handle di ambiente.
Se l'ambiente è un ambiente condiviso, l'applicazione che chiama SQLFreeHandle con handleType di SQL_HANDLE_ENV non ha più accesso all'ambiente dopo la chiamata, ma le risorse dell'ambiente non vengono necessariamente liberate. La chiamata a SQLFreeHandle decrementa il conteggio dei riferimenti dell'ambiente. Il conteggio dei riferimenti viene gestito da Gestione driver. Se non raggiunge zero, l'ambiente condiviso non viene liberato perché viene ancora usato da un altro componente. Se il conteggio dei riferimenti raggiunge zero, le risorse dell'ambiente condiviso vengono liberate.
Liberare un handle di connessione
Prima di chiamare SQLFreeHandle con handleType di SQL_HANDLE_DBC, un'applicazione deve chiamare SQLDisconnect per la connessione se è presente una connessione in questo handle*.* In caso contrario, la chiamata a SQLFreeHandle restituisce SQL_ERROR e la connessione rimane valida.
Per altre informazioni, vedere Handle di connessione e disconnessione da un'origine dati o un driver.
Rilascio di un handle di istruzione
Una chiamata a SQLFreeHandle con handleType di SQL_HANDLE_STMT libera tutte le risorse allocate da una chiamata a SQLAllocHandle con handleType di SQL_HANDLE_STMT. Quando un'applicazione chiama SQLFreeHandle per liberare un'istruzione con risultati in sospeso, i risultati in sospeso vengono eliminati. Quando un'applicazione libera un handle di istruzione, il driver libera i quattro descrittori allocati automaticamente associati a tale handle. Per altre informazioni, vedere Handle di istruzioni e liberamento di un handle di istruzione.
Si noti che SQLDisconnect elimina automaticamente tutte le istruzioni e i descrittori aperti nella connessione.
Liberare un handle del descrittore
Una chiamata a SQLFreeHandle con handleTypedi SQL_HANDLE_DESC libera l'handle del descrittore in Handle. La chiamata a SQLFreeHandle non rilascia memoria allocata dall'applicazione a cui può fare riferimento un campo puntatore (inclusi SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR) di qualsiasi record descrittore di Handle. La memoria allocata dal driver per i campi che non sono campi puntatore viene liberata quando l'handle viene liberato. Quando viene liberato un handle di descrittore allocato dall'utente, tutte le istruzioni associate all'handle liberato sono state associate al ripristino dei rispettivi handle del descrittore allocati automaticamente.
Nota
I driver ODBC 2*.x* non supportano la liberazione degli handle del descrittore, così come non supportano l'allocazione degli handle del descrittore.
Si noti che SQLDisconnect elimina automaticamente tutte le istruzioni e i descrittori aperti nella connessione. Quando un'applicazione libera un handle di istruzione, il driver libera tutti i descrittori generati automaticamente associati a tale handle.
Per altre informazioni sui descrittori, vedere Descrittori.
Esempio di codice
Per altri esempi di codice, vedere SQLBrowseConnect e SQLConnect.
Codice
// 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;
}
}
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Allocazione di un handle | Funzione SQLAllocHandle |
| Annullamento dell'elaborazione delle istruzioni | Funzione SQLCance |
| Impostazione di un nome di cursore | Funzione SQLSetCursorName |
Vedi anche
Riferimento API ODBC
File di intestazione ODBC
Programma di esempio ODBC