SQLFreeHandle-Funktion

Konformität
Version eingeführt: ODBC 3.0 Standards Compliance: ISO 92

Zusammenfassung
SQLFreeHandle gibt Ressourcen frei, die einer bestimmten Umgebung, Verbindung, Anweisung oder einem bestimmten Deskriptorhandle zugeordnet sind.

Syntax

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);  

Argumente

HandleType
[Eingabe] Der Typ des Handles, das von SQLFreeHandle freigegeben werden soll. Dies muss einer der folgenden Werte sein:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN Handle wird nur vom Treiber-Manager und treiber verwendet. Anwendungen sollten diesen Handle-Typ nicht verwenden. Weitere Informationen zu SQL_HANDLE_DBC_INFO_TOKEN finden Sie unter Developing Connection-Pool Awareness in an ODBC Driver.For more information about SQL_HANDLE_DBC_INFO_TOKEN, see Developing Connection-Pool Awareness in an ODBC Driver.

Wenn HandleType keiner dieser Werte ist, gibt SQLFreeHandle SQL_INVALID_HANDLE zurück.

Handle
[Eingabe] Das frei zu gebende Handle.

Gibt zurück

SQL_SUCCESS, SQL_ERROR oder SQL_INVALID_HANDLE.

Wenn SQLFreeHandle SQL_ERROR zurückgibt, ist das Handle weiterhin gültig.

Diagnose

Wenn SQLFreeHandle SQL_ERROR zurückgibt, kann ein zugeordneter SQLSTATE-Wert aus der Diagnosedatenstruktur für das Handle abgerufen werden, das SQLFreeHandle frei geben wollte, aber nicht konnte. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLFreeHandle zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der Rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

SQLFreeHandle wird verwendet, um Handles für Umgebungen, Verbindungen, Anweisungen und Deskriptoren frei zu geben, wie in den folgenden Abschnitten beschrieben. Allgemeine Informationen zu Handles finden Sie unter Handles.

Eine Anwendung sollte kein Handle verwenden, nachdem es freigegeben wurde. Der Treiber-Manager überprüft nicht die Gültigkeit eines Handles in einem Funktionsaufruf.

Freigeben eines Umgebungshandles

Bevor SQLFreeHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen wird, muss eine Anwendung SQLFreeHandle mit einem HandleType von SQL_HANDLE_DBC für alle Verbindungen aufrufen, die unter der Umgebung zugeordnet sind. Andernfalls gibt der Aufruf von SQLFreeHandle SQL_ERROR und die Umgebung zurück, und alle aktiven Verbindungen bleiben gültig. Weitere Informationen finden Sie unter Umgebungshandles und Zuordnen des Umgebungshandles.

Wenn die Umgebung eine freigegebene Umgebung ist, hat die Anwendung, die SQLFreeHandle mit einem HandleType von SQL_HANDLE_ENV aufruft, nach dem Aufruf keinen Zugriff mehr auf die Umgebung, aber die Ressourcen der Umgebung werden nicht unbedingt freigegeben. Der Aufruf von SQLFreeHandle verringert die Verweisanzahl der Umgebung. Die Referenzanzahl wird vom Treiber-Manager verwaltet. Wenn sie nicht null erreicht, wird die freigegebene Umgebung nicht freigegeben, da sie noch von einer anderen Komponente verwendet wird. Wenn die Verweisanzahl null erreicht, werden die Ressourcen der freigegebenen Umgebung freigegeben.

Freigeben eines Verbindungshandles

Bevor SQLFreeHandle mit einem HandleType von SQL_HANDLE_DBC aufgerufen wird, muss eine Anwendung SQLDisconnect für die Verbindung aufrufen, wenn eine Verbindung für dieses Handle* vorhanden ist.* Andernfalls gibt der Aufruf von SQLFreeHandle SQL_ERROR zurück, und die Verbindung bleibt gültig.

Weitere Informationen finden Sie unter Verbindungshandles und Trennen einer Datenquelle oder eines Treibers.

Freigeben eines Anweisungshandles

Ein Aufruf von SQLFreeHandle mit einem HandleType von SQL_HANDLE_STMT gibt alle Ressourcen frei, die durch einen Aufruf von SQLAllocHandle mit einem HandleType von SQL_HANDLE_STMT zugeordnet wurden. Wenn eine Anwendung SQLFreeHandle aufruft, um eine Anweisung freizugeben, die ausstehende Ergebnisse enthält, werden die ausstehenden Ergebnisse gelöscht. Wenn eine Anwendung ein Anweisungshandle freigibt, gibt der Treiber die vier automatisch zugeordneten Deskriptoren frei, die diesem Handle zugeordnet sind. Weitere Informationen finden Sie unter Anweisungshandles und Freigeben eines Anweisungshandles.

Beachten Sie, dass SQLDisconnect automatisch alle Anweisungen und Deskriptoren löscht, die für die Verbindung geöffnet sind.

Freigeben eines Deskriptorhandles

Durch einen Aufruf von SQLFreeHandle mit einem HandleType von SQL_HANDLE_DESC wird das Deskriptorhandle in Handle freigegeben. Der Aufruf von SQLFreeHandle gibt keinen von der Anwendung zugeordneten Arbeitsspeicher frei, auf den möglicherweise ein Zeigerfeld (einschließlich SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR und SQL_DESC_OCTET_LENGTH_PTR) eines Handle-Deskriptordatensatzes verweist. Der vom Treiber zugewiesene Arbeitsspeicher für Felder, die keine Zeigerfelder sind, wird freigegeben, wenn das Handle freigegeben wird. Wenn ein benutzerseitig zugeordnetes Deskriptorhandle freigegeben wird, werden alle Anweisungen, denen das freigegebene Handle zugeordnet war, auf ihre jeweiligen automatisch zugeordneten Deskriptorhandles zurückgesetzt.

Beachten Sie, dass SQLDisconnect automatisch alle Anweisungen und Deskriptoren löscht, die für die Verbindung geöffnet sind. Wenn eine Anwendung ein Anweisungshandle freigibt, gibt der Treiber alle automatisch generierten Deskriptoren frei, die diesem Handle zugeordnet sind.

Weitere Informationen zu Deskriptoren finden Sie unter Deskriptoren.

Codebeispiel

Weitere Codebeispiele finden Sie unter SQLBrowseConnect und SQLConnect.

Code

// 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;   
   }  
}  

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
ODBC-Beispielprogramm