Teilen über

SQLFreeStmt-Funktion

  • Artikel

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

ODBC-API-Referenz
ODBC-Headerdateien