SQLCancelHandle, funkcja
zgodności
Wersja wprowadzona: Zgodność standardów ODBC 3.8: Brak
Oczekuje się, że większość sterowników ODBC 3.8 (i nowszych) zaimplementuje tę funkcję. Jeśli sterownik nie, wywołanie SQLCancelHandle z uchwytem połączenia w parametrze Handle zwróci SQL_ERROR z parametrem SQLSTATE IM001 i komunikat "Sterownik nie obsługuje tej funkcji" wywołanie SQLCancelHandle z uchwytem instrukcji, ponieważ parametr Handle zostanie zamapowany na wywołanie SQLCancel przez Menedżera sterowników i może zostać przetworzone, jeśli sterownik implementuje SQLCancel. Aplikacja może używać SQLGetFunctions, aby określić, czy sterownik obsługuje SQLCancelHandle.
podsumowania
SQLCancelHandle anuluje przetwarzanie na połączeniu lub instrukcji. Menedżer sterowników mapuje wywołanie SQLCancelHandle wywołanie SQLCancel, gdy HandleType jest SQL_HANDLE_STMT.
Składnia
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Argumenty
HandleType
[Dane wejściowe] Typ uchwytu, na którym ma być anulowane przetwarzanie. Prawidłowe wartości to SQL_HANDLE_DBC lub SQL_HANDLE_STMT.
dojścia
[Dane wejściowe] Uchwyt, na którym ma być anulowane przetwarzanie.
Jeśli Handle nie jest prawidłowym uchwytem typu określonego przez HandleType, SQLCancelHandle zwraca SQL_INVALID_HANDLE.
Zwraca
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR lub SQL_INVALID_HANDLE.
Diagnostyka
Gdy SQLCancelHandle zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, skojarzona wartość SQLSTATE można uzyskać, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT i dojściem instrukcji Handle lub HandleType SQL_HANDLE_DBC i dojściem dojścia połączenia .
W poniższej tabeli wymieniono wartości SQLSTATE, które są często zwracane przez SQLCancelHandle i objaśniono poszczególne wartości 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 |
|---|---|---|
| 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 SQLGetDiagRec w argumencie *MessageText bufor 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 | Asynchronicznie wykonywana funkcja związana z instrukcją została wywołana dla jednego z dojść instrukcji skojarzonych z Handle, a HandleType została ustawiona na SQL_HANDLE_DBC. Funkcja asynchroniczna była nadal wykonywana po wywołaniu SQLCancelHandle. (DM) Argument HandleType był SQL_HANDLE_STMT; asynchronicznie wykonywana funkcja została wywołana na skojarzonym dojściu połączenia; i funkcja była nadal wykonywana, gdy ta funkcja została wywołana. (DM) SQLExecute, SQLExecDirectlub SQLMoreResults został wywołany do jednego z dojść instrukcji skojarzonych z Handle i HandleType został ustawiony na SQL_HANDLE_DBC i zwrócony SQL_PARAM_DATA_AVAILABLE. Ta funkcja została wywołana przed pobraniem danych dla wszystkich parametrów przesyłanych strumieniowo. SQLBrowseConnect została wywołana dla ConnectionHandlei zwróciła SQL_NEED_DATA. Ta funkcja została wywołana przed zakończeniem procesu przeglądania. |
| 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 | Nieprawidłowy atrybut/identyfikator opcji | HandleType został ustawiony na SQL_HANDLE_ENV lub SQL_HANDLE_DESC. |
| 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) Sterownik skojarzony z Handle nie obsługuje funkcji. |
Jeśli sqlCancelHandle jest wywoływana z HandleType ustawioną na SQL_HANDLE_STMT, może zwrócić dowolny element SQLSTATE, który może zostać zwrócony przez funkcję SQLCancel.
Komentarze
Ta funkcja jest podobna do SQLCancel ale może przyjąć obsługę połączenia lub instrukcji jako parametru, a nie tylko uchwyt instrukcji. Menedżer sterowników mapuje wywołanie SQLCancelHandle wywołanie SQLCancel, gdy HandleType jest SQL_HANDLE_STMT. Dzięki temu aplikacje mogą używać SQLCancelHandle do anulowania operacji instrukcji, nawet jeśli sterownik nie implementuje SQLCancelHandle.
Aby uzyskać więcej informacji na temat anulowania operacji instrukcji, zobacz funkcji SQLCancel.
Jeśli nie ma żadnych operacji w toku w Handle wywołanie SQLCancelHandle nie ma żadnego wpływu.
SQLCancelHandle na dojściu połączenia może anulować następujące typy przetwarzania:
Funkcja uruchomiona asynchronicznie na połączeniu.
Funkcja uruchomiona na dojściu połączenia w innym wątku.
Gdy SQLCancelHandle jest wywoływana w celu anulowania funkcji uruchomionej asynchronicznie w połączeniu, rekordy diagnostyczne opublikowane przez SQLCancelHandle są dołączane do tych zwracanych przez anulowaną operację; SQLCancelHandle nie zwraca rekordów diagnostycznych, jednak podczas anulowania funkcji uruchomionej w połączeniu w innym wątku.
Użycie SQLCancelHandle w celu anulowania sqlEndTra n może spowodować wstrzymanie połączenia. Aby uzyskać więcej informacji na temat stanu wstrzymania, zobacz funkcji SQLEndTran.
Nuta
Aby uzyskać informacje na temat używania sqlCancelHandle w aplikacji, która zostanie wdrożona w systemie operacyjnym Windows starszym niż Windows 7, zobacz macierz zgodności .
Anulowanie przetwarzania asynchronicznego Connection-Related
Jeśli funkcja zwróci SQL_STILL_EXECUTING, aplikacja może wywołać SQLCancelHandle, aby anulować operację. Jeśli żądanie anulowania zakończy się pomyślnie, SQLCancelHandle zwraca SQL_SUCCESS. Nie oznacza to, że oryginalna funkcja została anulowana; wskazuje, że żądanie anulowania zostało przetworzone. Sterownik i źródło danych określają, kiedy lub czy operacja została anulowana. Aplikacja musi nadal wywoływać oryginalną funkcję, dopóki kod powrotny nie zostanie SQL_STILL_EXECUTING. Jeśli oryginalna funkcja została anulowana, kod zwrotny jest SQL_ERROR i SQLSTATE HY008 (operacja anulowana). Jeśli oryginalna funkcja zakończyła normalne przetwarzanie (nie zostało anulowane), kod powrotny jest SQL_SUCCESS lub SQL_SUCCESS_WITH_INFO albo SQL_ERROR i SQLSTATE inny niż HY008 (operacja anulowana), jeśli oryginalna funkcja nie powiodła się.
Anulowanie funkcji wykonywanych w innym wątku
W aplikacji wielowątku aplikacja może anulować operację uruchomioną w innym wątku. Aby anulować operację, aplikacja wywołuje SQLCancelHandle z uchwytem używanym przez funkcję, ale w innym wątku. Sterownik i system operacyjny określają sposób anulowania operacji. Kod zwrotny SQLCancelHandle wskazuje, czy sterownik przetworzył żądanie, zwracając SQL_SUCCESS lub SQL_ERROR (nie są zwracane żadne informacje diagnostyczne). Jeśli przetwarzanie oryginalnej funkcji zostanie anulowane, oryginalna funkcja zwraca SQL_ERROR i SQLSTATE HY008 (operacja anulowana).
Jeśli funkcja jest wykonywana, gdy SQLCancelHandle jest wywoływana w innym wątku w celu anulowania funkcji, istnieje możliwość pomyślnego wykonania funkcji i zwrócenia SQL_SUCCESS przed rozpoczęciem anulowania. Wywołanie SQLCancelHandle nie ma wpływu, jeśli operacja została ukończona przed SQLCancelHandle mogła anulować operację.
Powiązane funkcje
Zobacz też
dokumentacja interfejsu API ODBC
plików nagłówków ODBC
asynchroniczne wykonywanie (metoda sondowania)