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.
Hinweis
Diese Funktion ist eine generische Funktion zum Freigeben von Handles. Sie ersetzt die ODBC 2.0-Funktionen SQLFreeConnect (zum Freigeben eines Verbindungshandles) und SQLFreeEnv (zum Freigeben eines Umgebungshandles). SQLFreeConnect und SQLFreeEnv sind in ODBC 3*.x* veraltet. SQLFreeHandle ersetzt auch die ODBC 2.0-Funktion SQLFreeStmt (durch die SQL_DROP Option), um ein Anweisungshandle frei zu geben. Weitere Informationen finden Sie unter "Kommentare". Weitere Informationen dazu, was der Treiber-Manager dieser Funktion zuordnet, wenn eine ODBC 3*.x*-Anwendung mit einem ODBC 2*.x*-Treiber arbeitet, finden Sie unter Zuordnen von Ersatzfunktionen für die Abwärtskompatibilität von Anwendungen.
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.
| SQLSTATE | Fehler | Beschreibung |
|---|---|---|
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber konnte arbeitsspeicher nicht zuordnen, der zur Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. |
| HY010 | Funktionssequenzfehler | (DM) Das HandleType-Argument wurde SQL_HANDLE_ENV, und mindestens eine Verbindung befand sich in einem zugeordneten oder verbundenen Zustand. SQLDisconnect und SQLFreeHandle mit einem HandleType von SQL_HANDLE_DBC müssen für jede Verbindung aufgerufen werden, bevor SQLFreeHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen wird. (DM) Das HandleType-Argument wurde SQL_HANDLE_DBC, und die Funktion wurde aufgerufen, bevor SQLDisconnect für die Verbindung aufgerufen wurde. (DM) Das HandleType-Argument wurde SQL_HANDLE_DBC. Eine asynchron ausgeführte Funktion wurde mit Handle aufgerufen, und die Funktion wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) Das HandleType-Argument wurde SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde mit dem Anweisungshandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführungsparameter oder -spalten gesendet wurden. (DM) Das HandleType-Argument wurde SQL_HANDLE_STMT. Eine asynchron ausgeführte Funktion wurde für das Anweisungshandle oder für das zugeordnete Verbindungshandle aufgerufen, und die Funktion wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) Das HandleType-Argument wurde SQL_HANDLE_DESC. Eine asynchron ausgeführte Funktion wurde für das zugeordnete Verbindungshandle aufgerufen. und die Funktion wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) Alle Untergeordneten Handles und andere Ressourcen wurden nicht veröffentlicht , bevor SQLFreeHandle aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für eines der Anweisungshandles aufgerufen, die dem Handle zugeordnet sind, und HandleType wurde auf SQL_HANDLE_STMT festgelegt oder SQL_HANDLE_DESC SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Das HandleType-Argument wurde SQL_HANDLE_STMT oder SQL_HANDLE_DESC, und der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen. |
| HY017 | Ungültige Verwendung eines automatisch zugeordneten Deskriptorhandles. | (DM) Das Handle-Argument wurde auf das Handle für einen automatisch zugeordneten Deskriptor festgelegt. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Treiber unterstützt diese Funktion nicht. | (DM) Das HandleType-Argument wurde SQL_HANDLE_DESC, und der Treiber war ein ODBC 2*.x*-Treiber. (DM) Das HandleType-Argument wurde SQL_HANDLE_STMT, und der Treiber war kein gültiger ODBC-Treiber. |
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.
Hinweis
ODBC 2*.x*-Treiber unterstützen das Freigeben von Deskriptorhandles nicht, genauso wie sie das Zuweisen von Deskriptorhandles nicht unterstützen.
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
| Informationen über | Finden Sie unter |
|---|---|
| Zuweisen eines Handles | SQLAllocHandle-Funktion |
| Abbrechen der Anweisungsverarbeitung | SQLCance-Funktion |
| Festlegen eines Cursornamens | SQLSetCursorName-Funktion |