SQLFreeHandle, funkcja
zgodności
Wersja wprowadzona: Zgodność ze standardami ODBC 3.0: ISO 92
podsumowania
SQLFreeHandle zwalnia zasoby skojarzone z określonym środowiskiem, połączeniem, instrukcją lub deskryptorem.
Nuta
Ta funkcja jest funkcją ogólną do zwalniania dojść. Zastępuje ona funkcje ODBC 2.0 SQLFreeConnect (do zwalniania uchwytu połączenia) i SQLFreeEnv (do zwalniania uchwytu środowiska). sqlFreeConnect i SQLFreeEnv są przestarzałe w odBC 3*.x*. SQLFreeHandle zastępuje również funkcję ODBC 2.0 SQLFreeStmt (z SQL_DROP Option) w celu zwolnienia uchwytu instrukcji. Aby uzyskać więcej informacji, zobacz "Komentarze". Aby uzyskać więcej informacji o tym, co menedżer sterowników mapuje tę funkcję na kiedy aplikacja ODBC 3*.x* współpracuje ze sterownikiem ODBC 2*.x*, zobacz Mapowanie funkcji zastępczych w celu zapewnienia zgodności z poprzednimi wersjami aplikacji.
Składnia
SQLRETURN SQLFreeHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Argumenty
HandleType
[Dane wejściowe] Typ uchwytu do zwolnienia przez SQLFreeHandle. Musi być jedną z następujących wartości:
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN dojście jest używane tylko przez Menedżera sterowników i sterownik. Aplikacje nie powinny używać tego typu dojścia. Aby uzyskać więcej informacji na temat SQL_HANDLE_DBC_INFO_TOKEN, zobacz Developing Connection-Pool Awareness in an ODBC Driver(Tworzenie świadomości Connection-Pool sterowników ODBC).
Jeśli HandleType nie jest jedną z tych wartości, sqlFreeHandle zwraca SQL_INVALID_HANDLE.
dojścia
[Dane wejściowe] Uchwyt do zwolnienia.
Zwraca
SQL_SUCCESS, SQL_ERROR lub SQL_INVALID_HANDLE.
Jeśli sqlFreeHandle zwraca SQL_ERROR, dojście jest nadal prawidłowe.
Diagnostyka
Gdy SQLFreeHandle zwraca SQL_ERROR, skojarzona wartość SQLSTATE może zostać uzyskana ze struktury danych diagnostycznych dla uchwytu, który SQLFreeHandle próbował zwolnić, ale nie mógł. W poniższej tabeli wymieniono wartości SQLSTATE zwykle zwracane przez SQLFreeHandle i objaśnia je w kontekście tej funkcji; notacja "(DM)" poprzedza opisy obiektów SQLSTATEs zwróconych przez menedżera sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.
| SQLSTATE | Błąd | Opis |
|---|---|---|
| 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 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) Argument (DM) Argument (DM) Argument HandleType został SQL_HANDLE_DBC. Asynchronicznie wykonywana funkcja została wywołana za pomocą Handle, a funkcja była nadal wykonywana, gdy ta funkcja została wywołana. (DM) Argument (DM) Argument (DM) Argument (DM) Wszystkie dojścia spółki zależnej i inne zasoby nie zostały wydane przed wywołaniem SQLFreeHandle. (DM) SQLExecute, SQLExecDirectlub SQLMoreResults został wywołany do jednego z dojść instrukcji skojarzonych z Handle i HandleType został ustawiony na SQL_HANDLE_STMT lub SQL_HANDLE_DESC zwrócony SQL_PARAM_DATA_AVAILABLE. Ta funkcja została wywołana przed pobraniem danych dla wszystkich parametrów przesyłanych strumieniowo. |
| HY013 | Błąd zarządzania pamięcią | Argument HandleType był SQL_HANDLE_STMT lub SQL_HANDLE_DESC, a 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. |
| HY017 | Nieprawidłowe użycie automatycznie przydzielonego uchwytu deskryptora. | (DM) Argument obsługi |
| HY117 | Połączenie jest zawieszone z powodu nieznanego stanu transakcji. Dozwolone są tylko funkcje rozłączania i tylko do odczytu. | (DM) Aby uzyskać więcej informacji na temat stanu wstrzymania, zobacz funkcja SQLEndTran. |
| 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ą SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Sterownik nie obsługuje tej funkcji | (DM) Argument (DM) Argument |
Komentarze
SQLFreeHandle służy do bezpłatnych dojść dla środowisk, połączeń, instrukcji i deskryptorów, zgodnie z opisem w poniższych sekcjach. Aby uzyskać ogólne informacje na temat dojść, zobacz Handles.
Aplikacja nie powinna używać uchwytu po jego uwolnieniu; Menedżer sterowników nie sprawdza poprawności uchwytu w wywołaniu funkcji.
Zwalnianie dojścia środowiska
Zanim wywoła sqlFreeHandle z HandleType SQL_HANDLE_ENV, aplikacja musi wywołać SQLFreeHandle z HandleType SQL_HANDLE_DBC dla wszystkich połączeń przydzielonych w środowisku. W przeciwnym razie wywołanie SQLFreeHandle zwraca SQL_ERROR i środowisko, a wszystkie aktywne połączenia pozostają prawidłowe. Aby uzyskać więcej informacji, zobacz Environment Handles and Allocating the Environment Handle.
Jeśli środowisko jest środowiskiem udostępnionym, aplikacja, która wywołuje SQLFreeHandle z HandleType SQL_HANDLE_ENV nie ma już dostępu do środowiska po wywołaniu, ale zasoby środowiska nie muszą być zwalniane. Wywołanie SQLFreeHandle dekrementuje liczbę odwołań środowiska. Liczba odwołań jest utrzymywana przez Menedżera sterowników. Jeśli nie osiągnie zera, środowisko udostępnione nie zostanie zwolnione, ponieważ jest ono nadal używane przez inny składnik. Jeśli liczba odwołań osiągnie zero, zasoby środowiska udostępnionego zostaną zwolnione.
Zwalnianie uchwytu połączenia
Zanim wywoła sqlFreeHandle z HandleType SQL_HANDLE_DBC, aplikacja musi wywołać SQLDisconnect połączenia, jeśli istnieje połączenie na tym dojściu*.* W przeciwnym razie wywołanie SQLFreeHandle zwraca SQL_ERROR, a połączenie pozostaje prawidłowe.
Aby uzyskać więcej informacji, zobacz Connection Handles and Disconnecting from a Data Source or Driver.
Zwalnianie dojścia instrukcji
Wywołanie SQLFreeHandle z HandleType SQL_HANDLE_STMT zwalnia wszystkie zasoby przydzielone przez wywołanie SQLAllocHandle z HandleType SQL_HANDLE_STMT. Gdy aplikacja wywołuje SQLFreeHandle, aby zwolnić instrukcję z oczekującymi wynikami, oczekujące wyniki zostaną usunięte. Gdy aplikacja zwalnia uchwyt instrukcji, sterownik zwalnia cztery automatycznie przydzielone deskryptory skojarzone z tym uchwytem. Aby uzyskać więcej informacji, zobacz Statement Handles and Freeing a Statement Handle.
Zwróć uwagę, że sqlDisconnect automatycznie odrzuca wszystkie instrukcje i deskryptory otwarte w połączeniu.
Zwalnianie uchwytu deskryptora
Wywołanie SQLFreeHandle za pomocą HandleType SQL_HANDLE_DESC zwalnia uchwyt deskryptora w Handle. Wywołanie SQLFreeHandle nie zwalnia żadnej pamięci przydzielonej przez aplikację, do których może odwoływać się pole wskaźnika (w tym SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR i SQL_DESC_OCTET_LENGTH_PTR) żadnego rekordu deskryptora Handle. Pamięć przydzielona przez sterownik dla pól, które nie są polami wskaźnika, jest zwalniana po zwolnieniu dojścia. Po uwolnieniu uchwytu deskryptora przydzielonego przez użytkownika wszystkie instrukcje, które zwolniono dojścia zostały skojarzone z przywróceniem odpowiednich automatycznie przydzielonych uchwytów deskryptora.
Nuta
Sterowniki ODBC 2*.x* nie obsługują zwalniania uchwytów deskryptora, tak jak nie obsługują przydzielania uchwytów deskryptora.
Zwróć uwagę, że sqlDisconnect automatycznie odrzuca wszystkie instrukcje i deskryptory otwarte w połączeniu. Gdy aplikacja zwalnia uchwyt instrukcji, sterownik zwalnia wszystkie automatycznie wygenerowane deskryptory skojarzone z tym uchwytem.
Aby uzyskać więcej informacji na temat deskryptorów, zobacz Deskryptory.
Przykład kodu
Aby uzyskać dodatkowe przykłady kodu, zobacz SQLBrowseConnect i SQLConnect.
Kod
// SQLFreeHandle.cpp
// compile with: user32.lib odbc32.lib
#include <windows.h>
#include <sqlext.h>
#include <stdio.h>
int main() {
SQLRETURN retCode;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
SQLCHAR connStrbuffer[1024];
SQLSMALLINT connStrBufferLen;
// Initialize the environment, connection, statement handles.
SQLHENV henv = NULL; // Environment
SQLHDBC hdbc = NULL; // Connection handle
SQLHSTMT hstmt = NULL; // Statement handle
// Allocate the environment.
retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set environment attributes.
retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);
// Allocate the connection.
retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set the login timeout.
retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);
// Let the user select the data source and connect to the database.
retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);
retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Free handles, and disconnect.
if (hstmt) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
hstmt = NULL;
}
if (hdbc) {
SQLDisconnect(hdbc);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
hdbc = NULL;
}
if (henv) {
SQLFreeHandle(SQL_HANDLE_ENV, henv);
henv = NULL;
}
}
Powiązane funkcje
| Aby uzyskać informacje o | Widzieć |
|---|---|
| Przydzielanie uchwytu | funkcji SQLAllocHandle |
| Anulowanie przetwarzania instrukcji | funkcji SQLCancel |
| Ustawianie nazwy kursora | funkcji |
Zobacz też
dokumentacja interfejsu API ODBC
plików nagłówków ODBC
przykładowego programu ODBC