SQLCancel-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Summary
SQLCancel avbryter bearbetningen av ett sats.

För att avbryta bearbetning av en anslutning eller sats, använd SQLCancelHandle Function.

Syntax

  
SQLRETURN SQLCancel(  
     SQLHSTMT     StatementHandle);  

Arguments

StatementHandle
[Indata] Instruktionshandtag.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLCancel returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med HandleType SQL_HANDLE_STMT och Handle of StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLCancel och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Comments

SQLCancel kan avbryta följande typer av bearbetning på ett sats:

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

• En funktion på ett uttalande som behöver data.

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

I ODBC 2. x, om en applikation anropar SQLCancel när ingen bearbetning sker på satsen, har SQLCancel samma effekt som SQLFreeStmt med SQL_CLOSE-alternativet; detta beteende definieras endast för fullständighet och applikationer bör anropa SQLFreeStmt eller SQLCloseCursor för att stänga kursorer.

När SQLCancel anropas för att avbryta en funktion som körs asynkront i en sats eller en funktion på en sats som behöver data, raderas diagnostiska poster som postas av den funktion som avbryts, och SQLCancel postar sina egna diagnostiska poster; när SQLCancel anropas för att avbryta en funktion som körs på en sats i en annan tråd, rensar den dock inte diagnostikposterna för den avbrutna funktionen och publicerar inte sina egna diagnostiska poster.

Avslutar asynkron bearbetning

Efter att en applikation anropar en funktion asynkront, anropar den funktionen upprepade gånger för att avgöra om den har avslutat bearbetningen. Om funktionen fortfarande bearbetas returnerar den SQL_STILL_EXECUTING. Om funktionen har avslutat bearbetningen returnerar den en annan kod.

Efter varje anrop till funktionen som returnerar SQL_STILL_EXECUTING kan en applikation anropa SQLCancel för att avbryta funktionen. Om avbokningsförfrågan lyckas returnerar föraren SQL_SUCCESS. Det här meddelandet anger inte att funktionen faktiskt avbröts. det anger att avbokningsbegäran bearbetades. När eller om funktionen faktiskt avbryts är drivrutinsberoende och datakällasberoende. Applikationen måste fortsätta anropa den ursprungliga funktionen tills returkoden inte är SQL_STILL_EXECUTING. Om funktionen framgångsrikt avbrutits är returkoden SQL_ERROR och SQLSTATE HY008 (Operation avbryts). Om funktionen slutförde sin normala bearbetning är returkoden SQL_SUCCESS eller SQL_SUCCESS_WITH_INFO om funktionen lyckades eller SQL_ERROR och en SQLSTATE annan än HY008 (Operation avbryten) om funktionen misslyckades.

För mer information om asynkron bearbetning, se Asynkron exekvering.

Avbryta funktioner som behöver data

Efter att SQLExecute eller SQLExecDirect returnerat SQL_NEED_DATA och innan data har skickats för alla data-at-exekveringsparametrar kan en applikation anropa SQLCancel för att avbryta satsexekveringen. Efter att satsen har avbrutits kan applikationen anropa SQLExecute eller SQLExecDirect igen. För mer information, se SQLBindParameter.

Efter att SQLBulkOperations eller SQLSetPos returnerat SQL_NEED_DATA och innan data har skickats för alla data-at-exekveringskolumner kan en applikation anropa SQLCancel för att avbryta operationen. Efter att operationen har avbrutits kan applikationen anropa SQLBulkOperations eller SQLSetPos igen; Avbrytning påverkar inte markörens tillstånd eller den aktuella markörpositionen. För mer information, se SQLBulkOperations eller SQLSetPos.

Avbrytande av funktioner som körs på en annan tråd

I en multitrådsapplikation kan applikationen avbryta en funktion som körs på en annan tråd. För att avbryta funktionen anropar applikationen SQLCancel med samma satshandtag som den som används av målfunktionen, men i en annan tråd. Hur funktionen avbryts beror på drivrutinen och operativsystemet. Precis som när man avbryter en funktion som körs asynkront, indikerar returkoden i SQLCancel endast om drivrutinen behandlade förfrågan framgångsrikt. Endast SQL_SUCCESS eller SQL_ERROR kan återlämnas; Ingen diagnostisk information returneras. Om den ursprungliga funktionen avbryts returnerar den SQL_ERROR och SQLSTATE HY008 (Operation avbryten).

Om en SQL-sats körs när SQLCancel anropas i en annan tråd för att avbryta satsexekveringen, är det möjligt att exekveringen lyckas och returnerar SQL_SUCCESS samtidigt som avbrytningen också är framgångsrik. I detta fall antar Driver Manager att markören som öppnas av satsexekveringen stängs av cancel, så applikationen kommer inte kunna använda markören.

För mer information om trådning, se Multitrådning.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler