SQLFreeHandle-Funktion

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

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

Syntax

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);  

Argumente

HandleType-
[Eingabe] Der Handletyp, der von SQLFreeHandlefreigegeben werden soll. 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 Handletyp nicht verwenden. Weitere Informationen zu SQL_HANDLE_DBC_INFO_TOKEN finden Sie unter Developing Connection-Pool Awareness in einem ODBC-Treiber-.

Wenn HandleType- nicht einer dieser Werte ist, gibt SQLFreeHandle SQL_INVALID_HANDLE zurück.

behandeln
[Eingabe] Der zu befreiende Ziehpunkt.

Ertrag

SQL_SUCCESS, SQL_ERROR oder SQL_INVALID_HANDLE.

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

Diagnostik

Wenn SQLFreeHandle- SQL_ERROR zurückgibt, kann ein zugeordneter SQLSTATE-Wert aus der Diagnosedatenstruktur für das Handle abgerufen werden, das SQLFreeHandle frei, aber nicht. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLFreeHandle- zurückgegeben werden und die einzelnen Werte im Kontext dieser Funktion erläutert werden. 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 machen, wie in den folgenden Abschnitten beschrieben. Allgemeine Informationen zu Handles finden Sie unter Handles.

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

Freigeben eines Umgebungshandles

Bevor sie SQLFreeHandle- mit einem HandleType- von SQL_HANDLE_ENV aufruft, muss eine Anwendung SQLFreeHandle- mit einem HandleType- von SQL_HANDLE_DBC für alle Verbindungen aufrufen, die 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 Environment Handles and Allocating the Environment Handle.

Wenn es sich bei der Umgebung um eine freigegebene Umgebung handelt, hat die Anwendung, die SQLFreeHandle- mit einem HandleType- von SQL_HANDLE_ENV nach dem Aufruf keinen Zugriff mehr auf die Umgebung hat, die Ressourcen der Umgebung werden jedoch nicht unbedingt freigegeben. Der Aufruf von SQLFreeHandle erhöht die Referenzanzahl der Umgebung. Die Referenzanzahl wird vom Treiber-Manager verwaltet. Wenn sie nicht zu Null gelangt, wird die freigegebene Umgebung nicht freigegeben, da sie noch von einer anderen Komponente verwendet wird. Wenn die Referenzanzahl null erreicht, werden die Ressourcen der freigegebenen Umgebung freigegeben.

Freigeben eines Verbindungsziehpunkts

Bevor sie SQLFreeHandle- mit einem HandleType- von SQL_HANDLE_DBC aufruft, muss eine Anwendung SQLDisconnect- für die Verbindung aufrufen, wenn eine Verbindung auf diesem Handle*.* 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 Anweisungshandle

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 zugewiesen wurden. Wenn eine Anwendung SQLFreeHandle- aufruft, um eine Anweisung frei zu geben, die ausstehende Ergebnisse enthält, werden die ausstehenden Ergebnisse gelöscht. Wenn eine Anwendung ein Anweisungshandle freigibt, gibt der Treiber die vier automatisch zugewiesenen Deskriptoren frei, die diesem Handle zugeordnet sind. Weitere Informationen finden Sie unter Statement Handles und Freeing a Statement Handle.

Beachten Sie, dass SQLDisconnect alle Anweisungen und Deskriptoren automatisch in der Verbindung öffnet.

Freigeben eines Deskriptorhandle

Ein Aufruf von SQLFreeHandle mit einem HandleType- von SQL_HANDLE_DESC gibt den Deskriptorhandle in Handlefrei. Der Aufruf von SQLFreeHandle- gibt keinen Speicher frei, der von der Anwendung zugewiesen wird, auf die von einem Zeigerfeld (einschließlich SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR und SQL_DESC_OCTET_LENGTH_PTR) eines Beschreibungsdatensatzes von Handleverwiesen werden kann. Der vom Treiber zugewiesene Speicher für Felder, die keine Zeigerfelder sind, wird beim Freigeben des Handles freigegeben. Wenn ein vom Benutzer zugewiesener Deskriptorhandle freigegeben wird, wurden alle Anweisungen, denen das freigegebene Handle zugeordnet war, mit dem Zurücksetzen auf die jeweils automatisch zugewiesenen Deskriptorhandles verknüpft.

Beachten Sie, dass SQLDisconnect alle Anweisungen und Deskriptoren automatisch in der Verbindung öffnet. 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

Siehe auch

ODBC-API-Referenz
ODBC-Headerdateien
ODBC-Beispielprogramm