SQLFreeStmt-Funktion
Konformität
Version eingeführt: ODBC 1.0-Normenkonformität: ISO 92
Zusammenfassung
SQLFreeStmt beendet die Verarbeitung, die einer bestimmten Anweisung zugeordnet ist, schließt alle geöffneten Cursor, die der Anweisung zugeordnet sind, verwirft ausstehende Ergebnisse oder gibt optional alle Ressourcen frei, die dem Anweisungshandle zugeordnet sind.
Syntax
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Argumente
StatementHandle
[Eingabe] Anweisungshandle
Option
[Eingabe] Eine der folgenden Optionen:
SQL_ CLOSE: Schließt den Mit StatementHandle zugeordneten Cursor (sofern definiert) und verwirft alle ausstehenden Ergebnisse. Die Anwendung kann diesen Cursor später erneut öffnen, indem eine SELECT-Anweisung erneut mit den gleichen oder anderen Parameterwerten ausgeführt wird. Wenn kein Cursor geöffnet ist, hat diese Option keine Auswirkungen auf die Anwendung. SQLCloseCursor kann auch aufgerufen werden, um einen Cursor zu schließen. Weitere Informationen finden Sie unter Schließen des Cursors.
SQL_DROP: Diese Option ist veraltet. Ein Aufruf von SQLFreeStmt mit einer Option von SQL_DROP wird im Treiber-Manager SQLFreeHandle zugeordnet.
SQL_UNBIND: Legt das SQL_DESC_COUNT Feld der ARD auf 0 fest, und gibt alle an SQLBindCol gebundenen Spaltenpuffer für das angegebene StatementHandle frei. Dadurch wird die Bindung der Lesezeichenspalte nicht aufzuheben. Hierzu wird das SQL_DESC_DATA_PTR Feld der ARD für die Lesezeichenspalte auf NULL festgelegt. Beachten Sie, dass, wenn dieser Vorgang für einen explizit zugeordneten Deskriptor ausgeführt wird, der von mehr als einer Anweisung freigegeben wird, der Vorgang die Bindungen aller Anweisungen beeinflusst, die den Deskriptor gemeinsam verwenden. Weitere Informationen finden Sie unter Übersicht über das Abrufen von Ergebnissen (Basic).
SQL_RESET_PARAMS: Legt das SQL_DESC_COUNT Feld der APD auf 0 fest, und gibt alle Parameterpuffer frei, die von SQLBindParameter für den angegebenen StatementHandle festgelegt wurden. Wenn dieser Vorgang für einen explizit zugeordneten Deskriptor ausgeführt wird, der von mehr als einer Anweisung freigegeben wird, wirkt sich dieser Vorgang auf die Bindungen aller Anweisungen aus, die den Deskriptor verwenden. Weitere Informationen finden Sie unter Bindungsparameter.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLFreeStmt SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die normalerweise von SQLFreeStmt zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, 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 |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert 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 keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als SQLFreeStmt aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für statementHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde mit Option auf SQL_RESET_PARAMS aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. (DM) Eine asynchron ausführende Funktion wurde für das StatementHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die StatementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführung gesendet wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY092 | Optionstyp außerhalb des Bereichs | (DM) Der für das Argument Option angegebene Wert lautete nicht: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Der Treiber unterstützt diese Funktion nicht. | (DM) Der der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
Kommentare
Das Aufrufen von SQLFreeStmt mit der option SQL_CLOSE entspricht dem Aufrufen von SQLCloseCursor, mit der Ausnahme, dass SQLFreeStmt mit SQL_CLOSE die Anwendung nicht beeinflusst, wenn kein Cursor für die Anweisung geöffnet ist. Wenn kein Cursor geöffnet ist, gibt ein Aufruf von SQLCloseCursor SQLSTATE 24000 (Ungültiger Cursorzustand) zurück.
Eine Anwendung sollte kein Anweisungshandle verwenden, nachdem es freigegeben wurde. Der Treiber-Manager überprüft nicht die Gültigkeit eines Handles in einem Funktionsaufruf.
Beispiel
Es ist eine gute Programmierpraxis, Griffe frei zu machen. Der Einfachheit halber enthält das folgende Beispiel jedoch keinen Code, der zugeordnete Handles freigibt. Ein Beispiel zum Freigeben von Handles finden Sie unter SQLFreeHandle-Funktion.
// SQLFreeStmt.cpp
// compile with: user32.lib odbc32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
// declare and initialize the environment, connection, statement handles
SQLHENV henv = NULL; // Environment
SQLHDBC hdbc = NULL; // Connection handle
SQLHSTMT hstmt = NULL; // Statement handle
SQLRETURN retCode;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
SQLCHAR connStrbuffer[1024];
SQLSMALLINT connStrBufferLen;
retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);
retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);
retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);
retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retCode = SQLFreeStmt(hstmt, SQL_CLOSE);
retCode = SQLFreeStmt(hstmt, SQL_UNBIND);
retCode = SQLFreeStmt(hstmt, SQL_RESET_PARAMS);
}
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Zuweisen eines Handles | SQLAllocHandle-Funktion |
| Abbrechen der Anweisungsverarbeitung | SQLCancel-Funktion |
| Schließen eines Cursors | SQLCloseCursor-Funktion |
| Freigeben eines Handles | SQLFreeHandle-Funktion |
| Festlegen eines Cursornamens | SQLSetCursorName-Funktion |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für