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.

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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien