Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Zgodność
Wersja wprowadzona: Zgodność ze standardami ODBC 1.0: ISO 92
Podsumowanie
SQLFreeStmt zatrzymuje przetwarzanie powiązanego z konkretnym zaleceniem, zamyka wszystkie otwarte kursory powiązane z tym zdaniem, odrzuca oczekujące wyniki lub, opcjonalnie, uwalnia wszystkie zasoby związane z uchwytem instrukcji.
Syntax
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Arguments
StatementHandle
[Input] Uchwyt instrukcji
Opcja
[Input] Jedna z następujących opcji:
SQL_ ZAMKNIJ: Zamyka kursor powiązany z StatementHandle (jeśli był zdefiniowany) i odrzuca wszystkie oczekujące wyniki. Aplikacja może ponownie otworzyć ten kursor, wykonując ponownie polecenie SELECT z tymi samymi lub innymi wartościami parametrów. Jeśli nie ma otwartego kursora, ta opcja nie ma wpływu na aplikację. SQLCloseCursor może być również wywołany do zamknięcia kursora. Więcej informacji można znaleźć w artykule Zamknięcie kursora.
SQL_DROP: Ta opcja jest wycofana. Wywołanie do SQLFreeStmt z opcją SQL_DROP jest mapowane w Driver Manager na SQLFreeHandle.
SQL_UNBIND: Ustawia pole SQL_DESC_COUNT ARD na 0, zwalniając wszystkie bufory kolumn ograniczone przez SQLBindCol dla danego CommandHandle. To nie rozwiązuje kolumny zakładek; aby to zrobić, pole SQL_DESC_DATA_PTR w ARD dla kolumny zakładek ustawia się na NULL. Zwróć uwagę, że jeśli operacja ta jest wykonywana na wyraźnie przydzielonym deskryptorze, który jest współdzielony przez więcej niż jedno zawołanie, operacja wpłynie na powiązania wszystkich instrukcji dzielących ten deskryptor. Więcej informacji można znaleźć w artykule Przegląd wyników wyszukiwania (podstawowy).
SQL_RESET_PARAMS: Ustawia pole SQL_DESC_COUNT APD na 0, zwalniając wszystkie bufory parametrów ustawione przez SQLBindParameter dla danego StatementHandle. Jeśli operacja ta jest wykonywana na wyraźnie przydzielonym deskryptorze, który jest współdzielony przez więcej niż jedno zdanie, operacja ta wpłynie na powiązania wszystkich instrukcji dzielących ten deskryptor. Więcej informacji można znaleźć w sekcji Parametry wiązania.
Zwroty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR lub SQL_INVALID_HANDLE.
Diagnostyka
Gdy SQLFreeStmt zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, powiązaną wartość SQLSTATE można uzyskać, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT oraz HandleStatementHandle. Poniższa tabela przedstawia wartości SQLSTATE typowo zwracane przez SQLFreeStmt i wyjaśnia każdą z nich w kontekście tej funkcji; notacja "(DM)" poprzedza opisy stanów SQL zwracanych przez Menedżera Sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Ostrzeżenie ogólne | Komunikat informacyjny specyficzny dla sterownika. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| HY000 | Błąd ogólny | Wystąpił błąd, dla którego nie było określonego stanu SQLSTATE i dla którego nie zdefiniowano parametru SQLSTATE specyficznego dla implementacji. Komunikat o błędzie zwrócony przez element SQLGetDiagRec w buforze *MessageText opisuje błąd i jego przyczynę. |
| HY001 | Błąd alokacji pamięci | Sterownik nie może przydzielić pamięci wymaganej do obsługi wykonywania lub ukończenia funkcji. |
| HY010 | Błąd sekwencji funkcji | (DM) Asynchronicznie wykonywana funkcja została wywołana dla dojścia połączenia skojarzonego z instrukcją StatementHandle. Ta asynchroniczna funkcja nadal działała, gdy wywoływano SQLFreeStmt . (DM) SqlExecute, SQLExecDirect lub SQLMoreResults została wywołana dla instrukcji StatementHandle i zwrócona SQL_PARAM_DATA_AVAILABLE. Funkcja ta była wywoływana z opcją ustawioną na SQL_RESET_PARAMS przed pobraniem danych dla wszystkich parametrów strumieniowych. (DM) Funkcja wykonująca asynchronicznie została wywołana dla CommandHandle i nadal działała, gdy ta funkcja została wywołana. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations lub SQLSetPos został wywołany dla instrukcjiHandle i zwrócił SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn. |
| HY013 | Błąd zarządzania pamięcią | Nie można przetworzyć wywołania funkcji, ponieważ nie można uzyskać dostępu do bazowych obiektów pamięci, prawdopodobnie z powodu niskich warunków pamięci. |
| HY092 | Typ opcji poza zasięgiem | (DM) Wartość określona dla argumentu Option nie była: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| HYT01 | Upłynął limit czasu połączenia | Okres przekroczenia limitu czasu połączenia wygasł, zanim źródło danych odpowiedziało na żądanie. Limit czasu połączenia jest ustawiany za pomocą parametru SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Sterownik nie obsługuje tej funkcji | (DM) Sterownik skojarzony z instrukcją StatementHandle nie obsługuje funkcji. |
Comments
Wywołanie SQLFreeStmt z opcją SQL_CLOSE jest równoważne wywoływaniu SQLCloseCursor, z tą różnicą, że SQLFreeStmt z SQL_CLOSE nie wpływa na aplikację, jeśli na instrukcji nie ma otwartego kursora. Jeśli nie ma otwartego kursora, wywołanie do SQLCloseCursor zwraca SQLSTATE 24000 (Nieprawidłowy stan kursora).
Aplikacja nie powinna używać uchwytu instrukcji po jego uwolnieniu; Driver Manager nie sprawdza poprawności uchwytu w wywołaniu funkcji.
Example
To dobra praktyka programistyczna do swobodnego ujęcia ręką. Jednak dla uproszczenia, poniższy przykładowy przykład nie zawiera kodu uwalniającego przydzielone uchwyty. Przykład wolnych uchwytów można znaleźć w 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);
}
Powiązane funkcje
| Aby uzyskać informacje o | Zobacz |
|---|---|
| Przydzielanie uchwytu | SQLAllocHandle Function |
| Anulowanie przetwarzania instrukcji | SQLCancel, funkcja |
| Zamykanie kursora | Funkcja SQLCloseCursor |
| Uwalnianie uchwytu | Funkcja SQLFreeHandle |
| Ustawianie nazwy kursora | SQLSetCursorName, funkcja |