Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Soulad
Zavedená verze: Dodržování standardů ODBC 1.0: ISO 92
Summary
SQLFreeStmt zastaví zpracování přiřazeného konkrétnímu příkazu, uzavře všechny otevřené kurzory spojené s tímto příkazem, vyřadí čekající výsledky nebo volitelně uvolní všechny zdroje spojené s handle příkazu.
Syntax
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Arguments
StatementHandle
[Vstup] Příkazová rukojeť
Možnost
[Vstup] Jedna z následujících možností:
SQL_ ZAVŘÍT: Zavře kurzor spojený s StatementHandle (pokud byl definován) a zahodí všechny čekající výsledky. Aplikace může tento kurzor později znovu otevřít vykonáním příkazu SELECT se stejnými nebo odlišnými hodnotami parametrů. Pokud není otevřený žádný kurzor, tato možnost nemá na aplikaci žádný vliv. SQLCloseCursor lze také volat k uzavření kurzoru. Pro více informací viz Zavření kurzoru.
SQL_DROP: Tato možnost je zastaralá. Volání do SQLFreeStmt s možností SQL_DROP je v Driver Manageru mapováno na SQLFreeHandle.
SQL_UNBIND: Nastaví pole SQL_DESC_COUNT ARD na 0, čímž se uvolní všechny sloupcové buffery omezené SQLBindCol pro daný StatementHandle. Tímto se sloupec záložek neodvázává; k tomu je pole SQL_DESC_DATA_PTR ARD pro sloupec záložek nastaveno na NULL. Všimněte si, že pokud je tato operace provedena na explicitně přiděleném deskriptoru, který je sdílen více než jedním příkazem, operace ovlivní vazby všech příkazů, které sdílejí tento popis. Pro více informací viz Přehled výsledků vyhledávání (Basic).
SQL_RESET_PARAMS: Nastaví pole SQL_DESC_COUNT APD na 0, čímž uvolní všechny parametrické buffery nastavené SQLBindParameter pro daný StatementHandle. Pokud je tato operace provedena na explicitně přiděleném deskriptoru, který je sdílen více než jedním příkazem, ovlivní tato operace vazby všech příkazů, které sdílejí tento deskriptor. Pro více informací viz Parametry vazby.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.
Diagnostika
Když SQLFreeStmt vrací SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, pokud se zavolá SQLGetDiagRec s HandleType SQL_HANDLE_STMT a Handle of StatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLFreeStmt obvykle vrací, a vysvětluje každou z nich v kontextu této funkce; notace "(DM)" předchází popisům SQLstavů vráceným Správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Obecné upozornění | Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| HY000 | Obecná chyba | Došlo k chybě, pro kterou nebyla definována žádná specifická funkce SQLSTATE a pro kterou nebyla definována žádná implementace sqlSTATE. Chybová zpráva vrácená nástrojem SQLGetDiagRec v vyrovnávací paměti *MessageText popisuje chybu a její příčinu. |
| HY001 | Chyba přidělení paměti | Ovladač nemohl přidělit paměť potřebnou k podpoře provádění nebo dokončení funkce. |
| HY010 | Chyba posloupnosti funkcí | (DM) Byla volána asynchronně spuštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato asynchronní funkce se stále spouštěla, když byl volán SQLFreeStmt . (DM) SQLExecute, SQLExecDirect nebo SQLMoreResults byl volána pro StatementHandle a vrácena SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána s nastavením Option na SQL_RESET_PARAMS před získáním dat pro všechny streamované parametry. (DM) Byla volána asynchronně vykonávající funkce pro CommandHandle a stále se spouštěla, když byla tato funkce vyvolána. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos byly volány pro StatementHandle a vráceny SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce. |
| HY013 | Chyba správy paměti | Volání funkce nelze zpracovat, protože základní objekty paměti nelze získat přístup, pravděpodobně kvůli nedostatku paměti. |
| HY092 | Typ volby mimo dosah | (DM) Hodnota určená pro argument Option nebyla: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| HYT01 | Vypršel časový limit připojení | Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Časový limit připojení je nastavený prostřednictvím sqlSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Ovladač tuto funkci nepodporuje. | (DM) Ovladač přidružený k StatementHandle nepodporuje funkci. |
Comments
Volání SQLFreeStmt s volbou SQL_CLOSE je ekvivalentní volání SQLCloseCursor, s tím rozdílem, že SQLFreeStmt s SQL_CLOSE neovlivňuje aplikaci, pokud na příkazu není otevřený kurzor. Pokud není otevřený žádný kurzor, volání SQLCloseCursor vrátí SQLSTATE 24000 (Invalid cursor state).
Aplikace by neměla používat příkazovou rukojeť poté, co byla uvolněna; Driver Manager nekontroluje platnost rukojeti ve volání funkce.
Example
Je to dobrá programátorská praxe volně ovládat rukojeti. Pro jednoduchost však následující ukázka neobsahuje kód, který by uvolňoval přidělené rukojeti. Pro příklad, jak volně používat rukojeti, viz 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);
}
Související funkce
| Informace o | Podívejte se |
|---|---|
| Přiřazení rukojeti | SQLAllocHandle Function |
| Zrušení zpracování příkazů | SQLCancel – funkce |
| Zavírání kurzoru | Funkce SQLCloseCursor |
| Uvolnění rukojeti | Funkce SQLFreeHandle |
| Nastavení názvu kurzoru | FUNKCE SQLSetCursorName |