Dela via

SQLCancelHandle-funktion

  • Artikel

Efterlevnad
Version introducerad: ODBC 3.8 Standardefterlevnad: Ingen

Det förväntas att de flesta ODBC 3.8-drivrutiner (och senare) implementerar den här funktionen. Om en drivrutin inte gör det ett anrop till SQLCancelHandle- med ett anslutningshandtag i parametern Handle returnerar SQL_ERROR med EN SQLSTATE av IM001 och meddelandet "Drivrutinen stöder inte den här funktionen" Ett anrop för att SQLCancelHandle- med en instruktionsreferens som parametern Handle mappas till ett anrop till SQLCancel av Driver Manager och kan bearbetas om drivrutinen implementerar SQLCancel. Ett program kan använda SQLGetFunctions för att avgöra om en drivrutin stöder SQLCancelHandle-.

Sammanfattning
SQLCancelHandle avbryter bearbetningen av en anslutning eller instruktion. Driver Manager mappar ett anrop till SQLCancelHandle till ett anrop till SQLCancel- när HandleType är SQL_HANDLE_STMT.

Syntax

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);

Argument

HandleType
[Indata] Typ av referens som bearbetningen ska avbrytas på. Giltiga värden är SQL_HANDLE_DBC eller SQL_HANDLE_STMT.

Hantera
[Indata] Handtaget som bearbetningen ska avbrytas på.

Om Handle inte är ett giltigt handtag av den typ som anges av HandleTypereturnerar SQLCancelHandle SQL_INVALID_HANDLE.

Returnerar

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostik

När SQLCancelHandle- returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan du hämta ett associerat SQLSTATE-värde genom att anropa SQLGetDiagRec med en HandleType- av SQL_HANDLE_STMT och en instruktionsreferens Hantera eller en HandleType- av SQL_HANDLE_DBC och ett hantera.

I följande tabell visas de SQLSTATE-värden som ofta returneras av SQLCancelHandle- och förklarar var och en i kontexten för den här funktionen. notationen "(DM)" föregår beskrivningarna av SQLSTATEs som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

SQLSTATE Fel Beskrivning
01000 Allmän varning Informationsmeddelande för drivrutinsspecifikt. (Funktionen returnerar SQL_SUCCESS_WITH_INFO.)
HY000 Allmänt fel Ett fel uppstod för vilket det inte fanns någon specifik SQLSTATE och för vilken ingen implementeringsspecifik SQLSTATE definierades. Felmeddelandet som returneras av SQLGetDiagRec i argumentet *MessageText buffert beskriver felet och orsaken.
HY001 Fel vid minnesallokering Drivrutinen kunde inte allokera minne som krävs för körning eller slutförande av funktionen.
HY010 Funktionssekvensfel En asynkront körande, instruktionsrelaterad funktion anropades för en av de instruktionsreferenser som är associerade med Handleoch HandleType angavs till SQL_HANDLE_DBC. Den asynkrona funktionen kördes fortfarande när SQLCancelHandle- anropades.

(DM) Argumentet HandleType var SQL_HANDLE_STMT. en asynkront körande funktion anropades på det associerade anslutningshandtaget. och funktionen kördes fortfarande när den här funktionen anropades.

(DM) SQLExecute, SQLExecDirecteller SQLMoreResults anropades för någon av de instruktionsreferenser som är associerade med Handle och HandleType angavs till SQL_HANDLE_DBC och returnerades SQL_PARAM_DATA_AVAILABLE. Den här funktionen anropades innan data hämtades för alla strömmade parametrar.

SQLBrowseConnect- anropades för ConnectionHandleoch returnerades SQL_NEED_DATA. Den här funktionen anropades innan bläddringsprocessen slutfördes.
HY013 Minneshanteringsfel Det gick inte att bearbeta funktionsanropet eftersom det inte gick att komma åt underliggande minnesobjekt, möjligen på grund av minnesbrist.
HY092 Ogiltig attribut-/alternatividentifierare HandleType har angetts till SQL_HANDLE_ENV eller SQL_HANDLE_DESC.
HY117 Anslutningen pausas på grund av okänt transaktionstillstånd. Endast frånkopplings- och skrivskyddade funktioner tillåts. (DM) Mer information om inaktiverat tillstånd finns i SQLEndTran Function.
HYT01 Tidsgränsen för anslutningen har upphört att gälla Tidsgränsen för anslutningen löpte ut innan datakällan svarade på begäran. Tidsgränsen för anslutningen anges via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Drivrutinen stöder inte den här funktionen (DM) Drivrutinen som är associerad med Handle stöder inte funktionen.

Om SQLCancelHandle- anropas med HandleType inställt på SQL_HANDLE_STMT, kan den returnera alla SQLSTATE som kan returneras av funktionen SQLCancel.

Kommentarer

Den här funktionen liknar SQLCancel- men kan ta antingen en anslutnings- eller instruktionsreferens som en parameter i stället för bara en instruktionsreferens. Driver Manager mappar ett anrop till SQLCancelHandle till ett anrop till SQLCancel- när HandleType är SQL_HANDLE_STMT. På så sätt kan program använda SQLCancelHandle- för att avbryta instruktionsåtgärder även om drivrutinen inte implementerar SQLCancelHandle-.

Mer information om hur du avbryter en instruktionsåtgärd finns i SQLCancel Function.

Om det inte pågår några åtgärder på Handle anropet till SQLCancelHandle har ingen effekt.

SQLCancelHandle- på en anslutningsreferens kan avbryta följande typer av bearbetning:

  • En funktion som körs asynkront på anslutningen.

  • En funktion som körs på anslutningshandtaget på en annan tråd.

När SQLCancelHandle- anropas för att avbryta en funktion som körs asynkront i en anslutning läggs diagnostikposter som publiceras av SQLCancelHandle till dem som returneras av åtgärden som avbryts. SQLCancelHandle- returnerar dock inte diagnostikposter när en funktion som körs på en anslutning på en annan tråd avbryts.

Om du använder SQLCancelHandle för att avbryta SQLEndTran kan försätta anslutningen i pausat tillstånd. Mer information om pausat tillstånd finns i SQLEndTran Function.

Not

Information om hur du använder SQLCancelHandle i ett program som ska distribueras på ett Windows-operativsystem som är äldre än Windows 7 finns i Compatibility Matrix.

Om en funktion returnerar SQL_STILL_EXECUTING kan ett program anropa SQLCancelHandle för att avbryta åtgärden. Om avbokningsbegäran lyckas returnerar SQLCancelHandle SQL_SUCCESS. Det innebär inte att den ursprungliga funktionen avbröts. det anger att avbokningsbegäran bearbetades. Drivrutinen och datakällan avgör när eller om åtgärden avbryts. Programmet måste fortsätta att anropa den ursprungliga funktionen tills returkoden inte SQL_STILL_EXECUTING. Om den ursprungliga funktionen avbröts är returkoden SQL_ERROR och SQLSTATE HY008 (åtgärden avbröts). Om den ursprungliga funktionen slutförde sin normala bearbetning (avbröts inte) är returkoden SQL_SUCCESS eller SQL_SUCCESS_WITH_INFO, eller SQL_ERROR och en annan SQLSTATE än HY008 (åtgärden avbröts) om den ursprungliga funktionen misslyckades.

Avbryta funktioner som körs på en annan tråd

I ett flertrådsprogram kan programmet avbryta en åtgärd som körs på en annan tråd. För att avbryta åtgärden anropar programmet SQLCancelHandle med handtaget som används av funktionen, men på en annan tråd. Drivrutinen och operativsystemet avgör hur åtgärden avbryts. SQLCancelHandle- returkod anger om drivrutinen bearbetade begäran och returnerade antingen SQL_SUCCESS eller SQL_ERROR (ingen diagnostikinformation returneras). Om bearbetningen av den ursprungliga funktionen avbryts returnerar den ursprungliga funktionen SQL_ERROR och SQLSTATE HY008 (åtgärden avbröts).

Om en funktion körs när SQLCancelHandle anropas på en annan tråd för att avbryta funktionen, är det möjligt att funktionen lyckas och returnerar SQL_SUCCESS innan avbokningen kan börja gälla. Ett anrop till SQLCancelHandle har ingen effekt om åtgärden slutfördes innan SQLCancelHandle kunde avbryta åtgärden.

Mer information om Se
Avbryta en funktion som körs asynkront på en instruktionsreferens, avbryta en funktion på en instruktion som behöver data eller avbryta en funktion som körs på en instruktion i en annan tråd. SQLCancel-funktion

Se även

ODBC API-referens
ODBC-huvudfiler
asynkron körning (avsökningsmetod)