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