SQLFreeStmt-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92

Summary
SQLFreeStmt stoppt die Verarbeitung, die mit einer bestimmten Anweisung verbunden ist, schließt alle offenen Cursor, die mit der Anweisung verbunden sind, verworfen ausstehende Ergebnisse oder freigibt optional alle mit dem Anweisungshandle verbundenen Ressourcen.

Syntax

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

Argumente

StatementHandle
[Eingabe] Anweisungshandle

Auswahl
[Eingabe] Eine der folgenden Optionen:

SQL_ CLOSE: Schließt den mit StatementHandle verbundenen Cursor (falls einer definiert war) und verwirft alle ausstehenden Ergebnisse. Die Anwendung kann diesen Cursor später wieder öffnen, indem sie eine SELECT-Anweisung erneut mit denselben oder anderen Parameterwerten ausführt. Wenn kein Cursor offen 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 eingestellt. Ein Aufruf zu SQLFreeStmt mit der Option SQL_DROP wird im Treibermanager auf SQLFreeHandle abgebildet.

SQL_UNBIND: Setzt das SQL_DESC_COUNT Feld der ARD auf 0 und gibt alle durch SQLBindCol gebundenen Spaltenpuffer für das gegebene StatementHandle frei. Dies entbindet die Lesezeichenspalte nicht; dazu wird das SQL_DESC_DATA_PTR Feld der ARD für die Lesezeichenspalte auf NULL gesetzt. Beachten Sie, dass, wenn diese Operation auf einem explizit zugewiesenen Deskriptor ausgeführt wird, der von mehreren Anweisungen geteilt wird, die Operation die Bindungen aller Anweisungen beeinflusst, die den Deskriptor teilen. Weitere Informationen finden Sie unter Überblick über das Abrufen von Ergebnissen (Basic).

SQL_RESET_PARAMS: Setzt das SQL_DESC_COUNT Feld der APD auf 0 und gibt alle von SQLBindParameter für den gegebenen StatementHandle gesetzten Parameterpuffer frei. Wenn diese Operation auf einem explizit zugewiesenen Deskriptor ausgeführt wird, der von mehreren Anweisungen geteilt wird, beeinflusst sie die Bindungen aller Aussagen, die den Deskriptor teilen. Weitere Informationen finden Sie unter Bindungsparameter.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLFreeStmt SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert erhalten werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von StatementHandle aufgerufen wird. Die folgende Tabelle listet die SQLSTATE-Werte auf, die typischerweise von SQLFreeStmt zurückgegeben werden, und erklärt jeden einzelnen im Kontext dieser Funktion; die Notation "(DM)" geht den vom Treibermanager zurückgegebenen SQLSTATE-Beschreibungen voraus. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

Das Aufrufen von SQLFreeStmt mit der SQL_CLOSE-Option entspricht dem Aufruf von SQLCloseCursor, außer dass SQLFreeStmt mit SQL_CLOSE die Anwendung nicht beeinflusst, wenn kein Cursor auf der Anweisung geöffnet ist. Wenn kein Cursor offen ist, gibt ein Aufruf von SQLCloseCursor SQLSTATE 24000 (Invalid Cursor State) zurück.

Eine Anwendung sollte keinen Anweisungshandle mehr verwenden, nachdem sie freigegeben wurde; prüft der Driver Manager nicht die Gültigkeit eines Handles in einem Funktionsaufruf.

Example

Es ist eine gute Programmiermethode, Handles freizumachen. Der Einfachheit halber enthält das folgende Beispiel jedoch keinen Code, der zugewiesene Handles freigibt. Ein Beispiel dafür, wie man Handles freisetzt, siehe SQLFreeHandle Function.

// 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

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien