SQLCancelHandle – funkce

shoda
Zavedená verze: Dodržování standardů ODBC 3.8: Žádné

Očekává se, že tuto funkci implementuje většina ovladačů ODBC 3.8 (a novějších). Pokud ovladač ne, Volání SQLCancelHandle s popisovačem připojení v parametru Handle vrátí SQL_ERROR s funkcí SQLSTATE im001 a zprávou Driver nepodporuje tuto funkci volání A. to SQLCancelHandle s popisovačem příkazu jako Handle parametr bude mapován na volání SQLCancel správcem ovladačů a lze jej zpracovat, pokud ovladač implementuje SQLCancel. Aplikace může použít SQLGetFunctions určit, zda ovladač podporuje SQLCancelHandle.

souhrnu
SQLCancelHandle zruší zpracování připojení nebo příkazu. Správce ovladačů mapuje volání SQLCancelHandle volání SQLCancel při HandleType SQL_HANDLE_STMT.

Syntax

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);  

Argumenty

HandleType
[Vstup] Typ popisovače, u kterého chcete zrušit zpracování. Platné hodnoty jsou SQL_HANDLE_DBC nebo SQL_HANDLE_STMT.

popisovač
[Vstup] Popisovač, u kterého chcete zrušit zpracování.

Pokud popisovač není platný popisovač typu určeného HandleType, SQLCancelHandle vrátí SQL_INVALID_HANDLE.

Návraty

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostika

Když SQLCancelHandle vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze přidruženou hodnotu SQLSTATE získat voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a popisovač příkazu Popisovač nebo HandleType SQL_HANDLE_DBC a obslužného úchytu popisovač.

Následující tabulka uvádí hodnoty SQLSTATE běžně vrácené SQLCancelHandle a vysvětluje každý z nich v kontextu této funkce; notace "(DM)" předchází popisy funkcí SQLSTATEs vrácených správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.

SQLSTATE	Chyba	Popis
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 vyrovnávací paměti 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í	Asynchronně spouštěná funkce související s příkazy byla volána pro jeden z popisovačů příkazů přidružených k Popisovača HandleType byla nastavena na SQL_HANDLE_DBC. Asynchronní funkce se stále spouštěla při volání SQLCancelHandle. (DM) Argument HandleType byl SQL_HANDLE_STMT; Na přidruženém popisovači připojení byla volána asynchronně spuštěná funkce; a funkce se stále spouštěla, když byla tato funkce volána. (DM) SQLExecute, SQLExecDirectnebo SQLMoreResults byl volána pro jeden z popisovačů příkazů přidružených k popisovač a HandleType byl nastaven na SQL_HANDLE_DBC a vrácen SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry. SQLBrowseConnect byl volána pro ConnectionHandlea vrátil SQL_NEED_DATA. Tato funkce byla volána před dokončením procesu procházení.
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.
HY092	Neplatný identifikátor atributu nebo možnosti	HandleType byla nastavena na SQL_HANDLE_ENV nebo SQL_HANDLE_DESC.
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. Doba časového limitu připojení je nastavena prostřednictvím SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Ovladač tuto funkci nepodporuje.	(DM) Ovladač přidružený k Popisovač funkci nepodporuje.

Pokud SQLCancelHandle je volána s HandleType nastavena na SQL_HANDLE_STMT, může vrátit libovolný SQLSTATE, který může vrátit funkce SQLCancel.

Komentáře

Tato funkce je podobná SQLCancel ale může jako parametr použít buď připojení, nebo popisovač příkazu, nikoli pouze popisovač příkazu. Správce ovladačů mapuje volání SQLCancelHandle volání SQLCancel při HandleType SQL_HANDLE_STMT. To umožňuje aplikacím používat SQLCancelHandle zrušit operace příkazů, i když ovladač neimplementuje SQLCancelHandle.

Další informace o zrušení operace příkazu naleznete v tématu SQLCancel Function.

Pokud na Zpracování volání SQLCancelHandle neprobíhá žádné operace.

SQLCancelHandle na popisovači připojení může zrušit následující typy zpracování:

• Funkce spuštěná asynchronně na připojení.

• Funkce spuštěná na popisovači připojení v jiném vlákně.

Při SQLCancelHandle je volána k zrušení funkce spuštěné asynchronně v připojení, diagnostické záznamy publikované SQLCancelHandle jsou připojeny k těm, které vrátí zrušena operace; SQLCancelHandle nevrací diagnostické záznamy, ale při zrušení funkce spuštěné na připojení v jiném vlákně.

Použití SQLCancelHandle ke zrušení SQLEndTran může umístit připojení do pozastaveného stavu. Další informace o pozastaveném stavu najdete v tématu funkce SQLEndTran.

Poznámka

Informace o použití SQLCancelHandle v aplikaci, která bude nasazena v operačním systému Windows starším než Windows 7, naleznete v tématu Compatibility Matrix.

Zrušení asynchronního zpracování Connection-Related

Pokud funkce vrátí SQL_STILL_EXECUTING, aplikace může volat SQLCancelHandle zrušit operaci. Pokud je žádost o zrušení úspěšná, sqlCancelHandle vrátí SQL_SUCCESS. To neznamená, že původní funkce byla zrušena; označuje, že žádost o zrušení byla zpracována. Ovladač a zdroj dat určují, kdy nebo jestli je operace zrušena. Aplikace musí pokračovat v volání původní funkce, dokud návratový kód nebude SQL_STILL_EXECUTING. Pokud byla původní funkce zrušena, návratový kód je SQL_ERROR a SQLSTATE HY008 (operace zrušena). Pokud původní funkce dokončila normální zpracování (nebyla zrušena), návratový kód je SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO nebo SQL_ERROR a SQLSTATE jiné než HY008 (operace zrušena), pokud původní funkce selhala.

Zrušení spouštění funkcí v jiném vlákně

V aplikaci s více vlákny může aplikace zrušit operaci spuštěnou v jiném vlákně. Chcete-li operaci zrušit, aplikace volá SQLCancelHandle s popisovačem používaným funkcí, ale v jiném vlákně. Ovladač a operační systém určují, jak se operace zruší. SQLCancelHandle návratový kód indikuje, jestli ovladač žádost zpracoval, vrací SQL_SUCCESS nebo SQL_ERROR (nevrátí se žádné diagnostické informace). Pokud je zpracování původní funkce zrušeno, vrátí původní funkce SQL_ERROR a SQLSTATE HY008 (operace byla zrušena).

Pokud je funkce spuštěna při SQLCancelHandle je volána na jiném vlákně zrušit funkci, je možné, aby funkce uspěla a vrátila SQL_SUCCESS předtím, než se zrušení projeví. Volání SQLCancelHandle nemá žádný vliv, pokud operace byla dokončena před SQLCancelHandle byla schopna operaci zrušit.

Související funkce

Informace o	Vidět
Zrušení funkce spuštěné asynchronně na popisovači příkazu, zrušení funkce v příkazu, který potřebuje data, nebo zrušení funkce spuštěné na příkazu v jiném vlákně.	funkce SQLCancel

Viz také

Referenční rozhraní ODBC API
soubory hlaviček ODBC
asynchronního spuštění (metoda polling)