SQLCancel, funkcja

Zgodność
Wersja wprowadzona: Zgodność ze standardami ODBC 1.0: ISO 92

Podsumowanie
SQLCancel anuluje przetwarzanie wyciągu.

Aby anulować przetwarzanie połączenia lub instrukcji, użyj funkcji SQLCancelHandle.

Syntax

  
SQLRETURN SQLCancel(  
     SQLHSTMT     StatementHandle);

Arguments

StatementHandle
[Dane wejściowe] Uchwyt instrukcji.

Zwroty

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR lub SQL_INVALID_HANDLE.

Diagnostyka

Gdy SQLCancel zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT oraz HandleStatementHandle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLCancel 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 SQLGetDiagRec w argumentze *MessageText buffer 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 była nadal wykonywana, gdy wywoływano funkcję SQLCancel .

(DM) Operacja anulowania zakończyła się niepowodzeniem, ponieważ na uchwytie połączenia powiązanym z CommandHandle trwa operacja asynchroniczna.
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.
HY018 Serwer odrzucił prośbę o anulowanie Serwer odrzucił prośbę o anulowanie.
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 SQLEndTran, funkcja.
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

SQLCancel może anulować następujące typy przetwarzania na wyrażeniu:

  • Funkcja działająca asynchronicznie na tym zaleceniu.

  • Funkcja na kontucie, która potrzebuje danych.

  • Funkcja działająca na instrukcji w innym wątku.

W ODBC 2. x, jeśli aplikacja wywoła SQLCancel , gdy nie odbywa się żadnego przetwarzania na żądaniu, SQLCancel ma taki sam efekt jak SQLFreeStmt z opcją SQL_CLOSE; to zachowanie jest definiowane wyłącznie dla zupełności i aplikacje powinny wywoływać SQLFreeStmt lub SQLCloseCursor , aby zamknąć kursory.

Gdy SQLCancel zostaje wywołany w celu anulowania funkcji działającej asynchronicznie w instrukcji lub funkcji na instrukcji wymagającej danych, rekordy diagnostyczne zamieszczone przez anulowaną funkcję są czyszczone, a SQLCancel publikuje własne rekordy diagnostyczne; gdy SQLCancel zostaje wywołany w celu anulowania funkcji działającej na innej instrukcji w innym wątku, nie usuwa on rejestrów diagnostycznych funkcji anulowanej i nie publikuje własnych rekordów diagnostycznych.

Anulowanie przetwarzania asynchronicznego

Po asynchronicznym wywołaniu funkcji przez aplikację, wywołuje ją wielokrotnie, aby sprawdzić, czy zakończyła przetwarzanie. Jeśli funkcja nadal przetwarza, zwraca SQL_STILL_EXECUTING. Jeśli funkcja zakończyła przetwarzanie, zwraca inny kod.

Po każdym wywołaniu funkcji, które zwraca SQL_STILL_EXECUTING, aplikacja może wywołać SQLCancel , aby anulować tę funkcję. Jeśli żądanie anulowania zakończy się sukcesem, sterownik zwraca SQL_SUCCESS. Ten komunikat nie wskazuje, że funkcja została rzeczywiście anulowana; wskazuje, że żądanie anulowania zostało przetworzone. To, czy funkcja faktycznie zostanie anulowana, zależy od sterownika i źródła danych. Aplikacja musi kontynuować wywoływanie oryginalnej funkcji, dopóki kod zwrotny nie zostanie SQL_STILL_EXECUTING. Jeśli funkcja została pomyślnie anulowana, kod zwrotny to SQL_ERROR oraz SQLSTATE HY008 (Operacja anulowana). Jeśli funkcja zakończyła normalne przetwarzanie, kod zwrotny to SQL_SUCCESS lub SQL_SUCCESS_WITH_INFO jeśli funkcja zakończyła się sukcesem lub SQL_ERROR oraz stan SQL inny niż HY008 (Operacja anulowana), jeśli funkcja zawiodła.

Note

W ODBC 3.5 wywołanie do SQLCancel , gdy nie jest wykonywane żadne przetwarzanie wyroku, nie jest traktowane jako SQLFreeStmt z opcją SQL_CLOSE, ale nie ma żadnego efektu. Aby zamknąć kursor, aplikacja powinna wywołać metodę SQLCloseCursor, a nie SQLCancel.

Więcej informacji o przetwarzaniu asynchronicznym można znaleźć w artykule Asynchronous Execution.

Anulowanie funkcji wymagających danych

Po zwrotach SQLExecute lub SQLExecDirect SQL_NEED_DATA i przed wysłaniem danych dla wszystkich parametrów danych przy wykonaniu, aplikacja może wywołać SQLCancel , aby anulować wykonanie polecenia. Po anulowaniu instrukcji aplikacja może ponownie wywołać SQLExecute lub SQLExecDirect . Więcej informacji można znaleźć w SQLBindParametr.

Po zwróceniu SQL_NEED_DATA SQLBulkOperations lub SQLSetPos i przed wysłaniem danych dla wszystkich kolumn danych podczas wykonywania, aplikacja może wywołać SQLCancel , aby anulować operację. Po anulowaniu operacji aplikacja może ponownie wywołać SQLBulkOperations lub SQLSetPos ; Anulowanie nie wpływa na stan kursora ani na aktualną pozycję kursora. Więcej informacji można znaleźć w SQLBulkOperations lub SQLSetPos.

Funkcje anulujące wykonywane na innym wątku

W aplikacji wielowątkowej aplikacja może anulować funkcję działającą na innym wątku. Aby anulować funkcję, aplikacja wywołuje SQLCancel z tym samym uchwytem instrukcji, który używany jest przez funkcję docelową, ale w innym wątku. Sposób anulowania funkcji zależy od sterownika i systemu operacyjnego. Podobnie jak przy anulowaniu funkcji działającej asynchronicznie, kod powrotny SQLCancel wskazuje jedynie, czy sterownik pomyślnie przetworzył żądanie. Tylko SQL_SUCCESS lub SQL_ERROR można zwrócić; Nie otrzymujemy żadnych informacji diagnostycznych. Jeśli oryginalna funkcja zostanie anulowana, zwraca SQL_ERROR oraz SQLSTATE HY008 (Operacja anulowana).

Jeśli wykonywane jest polecenie SQL podczas wywoływania SQLCancel w innym wątku w celu anulowania wykonania instrukcji, możliwe jest, że wykonanie zakończy się sukcesem i zwróci SQL_SUCCESS podczas gdy anulowanie również jest skuteczne. W takim przypadku Driver Manager zakłada, że kursor otwarty przez wykonanie instrukcji jest zamknięty przez cancel, więc aplikacja nie będzie mogła użyć kursora.

Więcej informacji o wątkowaniu można znaleźć w artykule Multithreading.

Aby uzyskać informacje o Zobacz
Powiązanie bufora z parametrem Funkcja SQLBindParameter
Wykonywanie operacji wstawiania lub aktualizacji masowej Funkcja SQLBulkOperations
Anuluje funkcję działającą asynchronicznie na uchwytie połączenia, oprócz funkcjonalności SQLCancel. Funkcja SQLCancelHandle
Wykonywanie instrukcji SQL Funkcja SQLExecDirect
Wykonywanie przygotowanej instrukcji SQL SQLExecute, funkcja
Uwalnianie uchwytu instrukcji Sqlfreestmt
Uzyskanie pola w rekordzie diagnostycznym lub pola nagłówka diagnostycznego Funkcja SQLGetDiagField
Uzyskiwanie wielu pól struktury danych diagnostycznych funkcji SQLGetDiagRec
Zwracanie następnego parametru w celu wysłania danych dla SQLParamData, funkcja
Wysyłanie danych parametrów w czasie wykonywania SQLPutData, funkcja
Ustawianie kursora w wierszu, odświeżanie danych w wierszu lub aktualizacja lub usuwanie danych w zbiorze wyników Funkcja SQLSetPos

Treści powiązane

  • Last updated on