Delen via

SQLCancelHandle, functie

  • Artikel

conformance
Versie geïntroduceerd: NALEVING van ODBC 3.8-standaarden: geen

Verwacht wordt dat de meeste ODBC 3.8-stuurprogramma's (en hoger) deze functie implementeren. Als een stuurprogramma dat niet doet, een aanroep van SQLCancelHandle- met een verbindingsgreep in de parameter Handle retourneert SQL_ERROR met een SQLSTATE van IM001 en het bericht 'Stuurprogramma biedt geen ondersteuning voor deze functie'' Een aanroep SQLCancelHandle- met een instructiegreep als de parameter Handle wordt toegewezen aan een aanroep van SQLCancel door Driver Manager en kan worden verwerkt als het stuurprogramma implementeert SQLCancel-. Een toepassing kan SQLGetFunctions gebruiken om te bepalen of een stuurprogramma ondersteuning biedt voor SQLCancelHandle-.

Samenvattings-
SQLCancelHandle annuleert de verwerking van een verbinding of instructie. Driver Manager wijst een aanroep toe aan SQLCancelHandle- aan een aanroep naar SQLCancel wanneer HandleType- is SQL_HANDLE_STMT.

Syntaxis

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);

Argumenten

HandleType-
[Invoer] Het type ingang waarop de verwerking moet worden geannuleerd. Geldige waarden zijn SQL_HANDLE_DBC of SQL_HANDLE_STMT.

verwerken
[Invoer] De ingang waarop de verwerking moet worden geannuleerd.

Als handle geen geldige ingang is van het type dat is opgegeven door HandleType, retourneert SQLCancelHandle SQL_INVALID_HANDLE.

Retourneert

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR of SQL_INVALID_HANDLE.

Diagnostiek

Wanneer SQLCancelHandle SQL_ERROR of SQL_SUCCESS_WITH_INFO retourneert, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec- aan te roepen met een HandleType- van SQL_HANDLE_STMT en een instructiegreep Handle of een HandleType van SQL_HANDLE_DBC en een verbindingsgreep Handle.

De volgende tabel bevat de SQLSTATE-waarden die vaak worden geretourneerd door SQLCancelHandle- en legt elke waarden uit in de context van deze functie; de notatie (DM)' voorafgaat aan de beschrijvingen van SQLSTATEs die worden geretourneerd door Driver Manager. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

SQLSTATE Fout Beschrijving
01000 Algemene waarschuwing Stuurprogrammaspecifiek informatiebericht. (Functie retourneert SQL_SUCCESS_WITH_INFO.)
HY000 Algemene fout Er is een fout opgetreden waarvoor er geen specifieke SQLSTATE is en waarvoor geen implementatiespecifieke SQLSTATE is gedefinieerd. Het foutbericht dat wordt geretourneerd door SQLGetDiagRec- in het argument *MessageText buffer beschrijft de fout en de oorzaak ervan.
HY001 Fout bij geheugentoewijzing Het stuurprogramma kan geen geheugen toewijzen dat nodig is om de uitvoering of voltooiing van de functie te ondersteunen.
HY010 Fout in functiereeks Er is een asynchrone, instructiegerelateerde functie aangeroepen voor een van de instructiegrepen die zijn gekoppeld aan de Handleen HandleType- is ingesteld op SQL_HANDLE_DBC. De asynchrone functie werd nog steeds uitgevoerd toen SQLCancelHandle- werd aangeroepen.

(DM) Het argument HandleType is SQL_HANDLE_STMT; een asynchroon uitgevoerde functie werd aangeroepen op de bijbehorende verbindingsgreep; en de functie werd nog steeds uitgevoerd toen deze functie werd aangeroepen.

(DM) SQLExecute, SQLExecDirectof SQLMoreResults is aangeroepen voor een van de instructiegrepen die zijn gekoppeld aan de Handle en HandleType is ingesteld op SQL_HANDLE_DBC en SQL_PARAM_DATA_AVAILABLE geretourneerd. Deze functie is aangeroepen voordat gegevens zijn opgehaald voor alle gestreamde parameters.

SQLBrowseConnect- is aangeroepen voor ConnectionHandle-en SQL_NEED_DATA geretourneerd. Deze functie is aangeroepen voordat het browseproces is voltooid.
HY013 Fout bij geheugenbeheer De functie-aanroep kan niet worden verwerkt omdat de onderliggende geheugenobjecten niet kunnen worden geopend, mogelijk vanwege weinig geheugen.
HY092 Ongeldig kenmerk/optie-id HandleType- is ingesteld op SQL_HANDLE_ENV of SQL_HANDLE_DESC.
HY117 De verbinding is onderbroken vanwege een onbekende transactiestatus. Alleen de verbinding verbreken en alleen-lezenfuncties zijn toegestaan. (DM) Zie SQLEndTran Functionvoor meer informatie over de onderbroken status.
HYT01 Time-out voor verbinding verlopen De time-outperiode voor de verbinding is verlopen voordat de gegevensbron op de aanvraag heeft gereageerd. De time-outperiode voor de verbinding wordt ingesteld via SQLSetConnectAttr-, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Stuurprogramma biedt geen ondersteuning voor deze functie (DM) Het stuurprogramma dat is gekoppeld aan de Handle biedt geen ondersteuning voor de functie.

Als SQLCancelHandle- wordt aangeroepen met HandleType ingesteld op SQL_HANDLE_STMT, kan elke SQLSTATE worden geretourneerd die kan worden geretourneerd door de functie SQLCancel.

Opmerkingen

Deze functie is vergelijkbaar met SQLCancel, maar kan een verbindings- of instructiegreep als een parameter gebruiken in plaats van alleen een instructiehandgreep. Driver Manager wijst een aanroep toe aan SQLCancelHandle- aan een aanroep naar SQLCancel wanneer HandleType- is SQL_HANDLE_STMT. Hierdoor kunnen toepassingen SQLCancelHandle- gebruiken om instructiebewerkingen te annuleren, zelfs als het stuurprogramma geen SQLCancelHandle-implementeert.

Zie SQLCancel Functionvoor meer informatie over het annuleren van een instructiebewerking.

Als er geen bewerkingen worden uitgevoerd op Verwerken de aanroep naar SQLCancelHandle- geen effect heeft.

SQLCancelHandle- op een verbindingsgreep kan de volgende typen verwerking annuleren:

  • Een functie die asynchroon wordt uitgevoerd op de verbinding.

  • Een functie die wordt uitgevoerd op de verbindingsgreep op een andere thread.

Wanneer SQLCancelHandle- wordt aangeroepen om een functie die asynchroon wordt uitgevoerd in een verbinding te annuleren, worden diagnostische records die zijn gepost door SQLCancelHandle- toegevoegd aan de records die worden geretourneerd door de bewerking die wordt geannuleerd; SQLCancelHandle- retourneert echter geen diagnostische records wanneer een functie wordt geannuleerd die wordt uitgevoerd op een verbinding op een andere thread.

Als u SQLCancelHandle- gebruikt om SQLEndTran- te annuleren, wordt de verbinding mogelijk onderbroken. Zie SQLEndTran Functionvoor meer informatie over de onderbroken status.

Notitie

Zie Compatibiliteitsmatrixvoor informatie over het gebruik van SQLCancelHandle- in een toepassing die wordt geïmplementeerd op een Windows-besturingssysteem dat ouder is dan Windows 7.

Als een functie SQL_STILL_EXECUTING retourneert, kan een toepassing SQLCancelHandle- aanroepen om de bewerking te annuleren. Als de annuleringsaanvraag is geslaagd, retourneert SQLCancelHandle SQL_SUCCESS. Dit betekent niet dat de oorspronkelijke functie is geannuleerd; hiermee wordt aangegeven dat de annuleringsaanvraag is verwerkt. Het stuurprogramma en de gegevensbron bepalen wanneer of of de bewerking wordt geannuleerd. De toepassing moet de oorspronkelijke functie blijven aanroepen totdat de retourcode niet SQL_STILL_EXECUTING is. Als de oorspronkelijke functie is geannuleerd, wordt de retourcode SQL_ERROR en SQLSTATE HY008 (Bewerking geannuleerd). Als de oorspronkelijke functie de normale verwerking heeft voltooid (niet geannuleerd), wordt de retourcode SQL_SUCCESS of SQL_SUCCESS_WITH_INFO, of SQL_ERROR en een andere SQLSTATE dan HY008 (Bewerking geannuleerd), als de oorspronkelijke functie is mislukt.

Functies annuleren die worden uitgevoerd op een andere thread

In een multithread-toepassing kan de toepassing een bewerking annuleren die wordt uitgevoerd op een andere thread. Als u de bewerking wilt annuleren, roept de toepassing SQLCancelHandle- aan met de ingang die door de functie wordt gebruikt, maar op een andere thread. Het stuurprogramma en besturingssysteem bepalen hoe de bewerking wordt geannuleerd. De SQLCancelHandle retourcode geeft aan of het stuurprogramma de aanvraag heeft verwerkt, SQL_SUCCESS of SQL_ERROR retourneert (er worden geen diagnostische gegevens geretourneerd). Als de verwerking van de oorspronkelijke functie wordt geannuleerd, retourneert de oorspronkelijke functie SQL_ERROR en SQLSTATE HY008 (Bewerking geannuleerd).

Als een functie wordt uitgevoerd wanneer SQLCancelHandle- wordt aangeroepen op een andere thread om de functie te annuleren, is het mogelijk dat de functie slaagt en SQL_SUCCESS retourneert voordat de annulering van kracht kan worden. Een aanroep van SQLCancelHandle- heeft geen effect als de bewerking is voltooid voordat SQLCancelHandle de bewerking kon annuleren.

Voor informatie over Zien
Annuleren van een functie die asynchroon wordt uitgevoerd op een instructiegreep, het annuleren van een functie op een instructie die gegevens nodig heeft of het annuleren van een functie die wordt uitgevoerd op een instructie in een andere thread. SQLCancel Function-

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden
Asynchrone uitvoering (pollingmethode)