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
SQLCancel zruší zpracování výpisu.
Pro zrušení zpracování spojení nebo příkazu použijte funkci SQLCancelHandle.
Syntax
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
Arguments
StatementHandle
[Vstup] Popisovač příkazu
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.
Diagnostika
Když SQLCancel vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLSTATE voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a HandleStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLCancel běžně 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á SQLGetDiagRec v argumentu *MessageText buffer 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 vykonávala, když byla volána funkce SQLCancel . (DM) Operace Cancel selhala, protože na spojovacím handle spojeném s StatementHandle probíhá asynchronní operace. |
| 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. |
| HY018 | Server odmítl žádost o zrušení | Server žádost o zrušení odmítl. |
| HY117 | Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení. | (DM) Další informace o pozastaveném stavu naleznete v tématu FUNKCE SQLEndTran. |
| 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
SQLCancel může zrušit následující typy zpracování na příkazu:
Funkce běžící asynchronně na příkazu.
Funkce na příkazu, která potřebuje data.
Funkce běžící na příkazu v jiném vlákně.
V ODBC 2. x, pokud aplikace volá SQLCancel , aniž by se na příkazu zpracovávalo, má SQLCancel stejný efekt jako SQLFreeStmt s možností SQL_CLOSE; toto chování je definováno pouze pro úplnost a aplikace by měly volat SQLFreeStmt nebo SQLCloseCursor pro zavření kurzorů.
Když je SQLCancel vyvolán k zrušení funkce běžící asynchronně v příkazu nebo funkce na příkazu, který vyžaduje data, diagnostické záznamy zveřejněné funkcí, která je rušena, jsou vymazány a SQLCancel zveřejní své vlastní diagnostické záznamy; když je SQLCancel vyvolán k zrušení funkce běžící na příkazu v jiném vlákně, nevymaže však diagnostické záznamy rušené funkce a neodesílá vlastní diagnostické záznamy.
Zrušení asynchronního zpracování
Po asynchronním volání funkce aplikací ji opakovaně volá, aby zjistila, zda byla dokončena zpracování. Pokud funkce stále zpracovává, vrátí SQL_STILL_EXECUTING. Pokud funkce dokončila zpracování, vrátí jiný kód.
Po každém volání funkce, které SQL_STILL_EXECUTING, může aplikace zavolat SQLCancel a zrušit funkci. Pokud je žádost o zrušení úspěšná, ovladač SQL_SUCCESS vrátí. Tato zpráva neznačí, že funkce byla skutečně zrušena; označuje, že žádost o zrušení byla zpracována. Kdy nebo zda je funkce skutečně zrušena, závisí na ovladači a zdroji dat. Aplikace musí pokračovat ve volání původní funkce, dokud není zpětný kód SQL_STILL_EXECUTING. Pokud byla funkce úspěšně zrušena, návratový kód je SQL_ERROR a SQLSTATE HY008 (Operace zrušena). Pokud funkce dokončila své běžné zpracování, je vrácení SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO pokud funkce uspěla nebo SQL_ERROR a SQLSTATE jiný než HY008 (operace zrušena), pokud funkce selhala.
Note
V ODBC 3.5 se volání SQLCancel , když se na příkazu nezpracovává, s možností SQL_CLOSE považuje za SQLFreeStmt , ale nemá žádný efekt. Chcete-li zavřít kurzor, aplikace by měla volat SQLCloseCursor, nikoli SQLCancel.
Pro více informací o asynchronním zpracování viz Asynchronous Execution.
Rušení funkcí, které potřebují data
Po vrácení SQL_NEED_DATA SQLExecute nebo SQLExecDirect a před odesláním dat pro všechny parametry při vykonání dat může aplikace zavolat SQLCancel a zrušit vykonávání příkazu. Po zrušení příkazu může aplikace znovu volat SQLExecute nebo SQLExecDirect . Pro více informací viz SQLBindParameter.
Po vrácení SQLBulkOperations nebo SQLSetPos SQL_NEED_DATA a před odesláním dat pro všechny sloupce dat při vykonání může aplikace zavolat SQLCancel a operaci zrušit. Po zrušení operace může aplikace znovu volat SQLBulkOperations nebo SQLSetPos ; Zrušení neovlivňuje stav kurzoru ani aktuální pozici kurzoru. Pro více informací viz SQLBulkOperations nebo SQLSetPos.
Rušení funkcí vykonávajících na jiném vlákně
V aplikaci s více vlákny může aplikace zrušit funkci, která běží na jiném vlákně. Pro zrušení funkce aplikace volá SQLCancel se stejným příkazovým handlem jako cílová funkce, ale v jiném vlákně. Jak se funkce zruší, závisí na ovladači a operačním systému. Stejně jako při zrušení funkce běžící asynchronně označuje zpětný kód SQLCancel pouze to, zda ovladač úspěšně zpracoval požadavek. Pouze SQL_SUCCESS nebo SQL_ERROR lze vrátit; Nejsou vráceny žádné diagnostické informace. Pokud je původní funkce zrušena, vrátí SQL_ERROR a SQLSTATE HY008 (operace zrušena).
Pokud je SQL příkaz vykonán při volání SQLCancel na jiném vlákně k zrušení příkazu, je možné, že vykonání uspěje a vrátí SQL_SUCCESS a zároveň je zrušení úspěšné. V tomto případě správce ovladačů předpokládá, že kurzor otevřený při provedení příkazu je zrušením uzavřen, takže aplikace kurzor nebude moci použít.
Pro více informací o vláknění viz Multithreading.
Související funkce
| Informace o | Podívejte se |
|---|---|
| Vazba bufferu na parametr | Funkce SQLBindParameter |
| Provádění hromadných vkládání nebo aktualizačních operací | SQLBulkOperations Function |
| Ruší funkci běžící asynchronně na rozhraní pro spojení, kromě funkčnosti SQLCancel. | Funkce SQLCancelHandle |
| Provádění SQL příkazu | SQLExecDirect Function |
| Spuštění připraveného příkazu SQL | FUNKCE SQLExecute |
| Uvolnění rukojeti příkazu | Sqlfreestmt |
| Získání pole diagnostického záznamu nebo pole diagnostického hlavičky | SQLGetDiagField Function |
| Získání více polí struktury diagnostických dat | funkce SQLGetDiagRec |
| Vrácení dalšího parametru pro odesílání dat pro | SQLParamData – funkce |
| Odesílání dat parametrů v době provádění | funkce |
| Umístění kurzoru do řádků, obnovení dat v sadě řádků nebo aktualizace či smazání dat ve výsledné sadě | Funkce SQLSetPos |