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.

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.

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.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Programma di esempio ODBC