SQLCancelHandle-Funktion

Konformitäts-
Version eingeführt: ODBC 3.8-Standardscompliance: Keine

Es wird erwartet, dass die meisten ODBC 3.8 -Treiber (und höher) diese Funktion implementieren. Wenn der Treiber nicht der Fall ist, Ein Aufruf von SQLCancelHandle- mit einem Verbindungshandle im Handle Parameter gibt SQL_ERROR mit einem SQLSTATE von IM001 zurück, und die Meldung "Driver unterstützt diese Funktion nicht". Ein Aufruf um SQLCancelHandle mit einem Anweisungshandle zu , da der Parameter Handle einem Aufruf SQLCancel zugeordnet wird und wenn der Treiber verarbeitet werden kann implementiert SQLCancel. Eine Anwendung kann SQLGetFunctions- verwenden, um festzustellen, ob ein Treiber SQLCancelHandle-unterstützt.

Zusammenfassung
SQLCancelHandle die Verarbeitung für eine Verbindung oder Anweisung abbricht. Der Treiber-Manager ordnet einen Aufruf SQLCancelHandle- einem Aufruf von SQLCancel- zu, wenn HandleType- SQL_HANDLE_STMT ist.

Syntax

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);  

Argumente

HandleType-
[Eingabe] Der Typ des Handles, für das die Verarbeitung abgebrochen werden soll. Gültige Werte sind SQL_HANDLE_DBC oder SQL_HANDLE_STMT.

behandeln
[Eingabe] Das Handle, mit dem die Verarbeitung abgebrochen werden soll.

Wenn Handle kein gültiges Handle des durch HandleTypeangegebenen Typs ist, gibt SQLCancelHandle SQL_INVALID_HANDLE zurück.

Ertrag

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLCancelHandle- SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType- von SQL_HANDLE_STMT und einem Anweisungshandle Handle oder einem HandleType- von SQL_HANDLE_DBC und einem Verbindungshandle Handleabgerufen werden.

In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLCancelHandle- zurückgegeben werden und die einzelnen Werte im Kontext dieser Funktion erläutert werden. die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Wenn SQLCancelHandle- aufgerufen wird, wobei HandleType- auf SQL_HANDLE_STMT festgelegt ist, kann jeder SQLSTATE zurückgegeben werden, der von der Funktion SQLCancelzurückgegeben werden kann.

Kommentare

Diese Funktion ähnelt SQLCancel-, kann jedoch entweder eine Verbindungs- oder Anweisungshandle als Parameter anstelle eines Anweisungshandles verwenden. Der Treiber-Manager ordnet einen Aufruf SQLCancelHandle- einem Aufruf von SQLCancel- zu, wenn HandleType- SQL_HANDLE_STMT ist. Dadurch können Anwendungen SQLCancelHandle- verwenden, um Anweisungsvorgänge abzubrechen, auch wenn der Treiber SQLCancelHandle-nicht implementiert.

Weitere Informationen zum Abbrechen eines Anweisungsvorgangs finden Sie unter SQLCancel Function.

Wenn für Handle der Aufruf von SQLCancelHand le keine Auswirkungen hat, wenn keine Vorgänge ausgeführt werden.

SQLCancelHandle- für ein Verbindungshandle kann die folgenden Verarbeitungstypen abbrechen:

• Eine Funktion, die asynchron auf der Verbindung ausgeführt wird.

• Eine Funktion, die auf dem Verbindungsziehpunkt in einem anderen Thread ausgeführt wird.

Wenn SQLCancelHandle- aufgerufen wird, um eine Funktion abzubrechen, die asynchron in einer Verbindung ausgeführt wird, werden Diagnosedatensätze, die von SQLCancelHandle bereitgestellt werden, an diejenigen angefügt, die vom abgebrochenen Vorgang zurückgegeben werden; SQLCancelHandle- gibt jedoch keine Diagnosedatensätze zurück, wenn eine Funktion abgebrochen wird, die auf einer Verbindung in einem anderen Thread ausgeführt wird.

Die Verwendung SQLCancelHandle- zum Abbrechen SQLEndTran- kann die Verbindung in den angehaltenen Zustand versetzen. Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.

Abbrechen Connection-Related asynchrone Verarbeitung

Wenn eine Funktion SQL_STILL_EXECUTING zurückgibt, kann eine Anwendung SQLCancelHandle- aufrufen, um den Vorgang abzubrechen. Wenn die Abbrechenanforderung erfolgreich ist, gibt SQLCancelHandle- SQL_SUCCESS zurück. Dies bedeutet nicht, dass die ursprüngliche Funktion abgebrochen wurde; sie gibt an, dass die Abbruchanforderung verarbeitet wurde. Der Treiber und die Datenquelle bestimmen, wann oder ob der Vorgang abgebrochen wird. Die Anwendung muss die ursprüngliche Funktion weiterhin aufrufen, bis der Rückgabecode nicht SQL_STILL_EXECUTING ist. Wenn die ursprüngliche Funktion abgebrochen wurde, ist der Rückgabecode SQL_ERROR und SQLSTATE HY008 (Vorgang abgebrochen). Wenn die ursprüngliche Funktion die normale Verarbeitung abgeschlossen hat (nicht abgebrochen), ist der Rückgabecode SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO oder SQL_ERROR und ein anderer SQLSTATE-Wert als HY008 (Vorgang abgebrochen), wenn die ursprüngliche Funktion fehlgeschlagen ist.

Abbrechen von Funktionen, die in einem anderen Thread ausgeführt werden

In einer Multithread-Anwendung kann die Anwendung einen Vorgang abbrechen, der auf einem anderen Thread ausgeführt wird. Um den Vorgang abzubrechen, ruft die Anwendung SQLCancelHandle- mit dem von der Funktion verwendeten Handle, aber in einem anderen Thread auf. Der Treiber und das Betriebssystem bestimmen, wie der Vorgang abgebrochen wird. Der SQLCancelHandle- Rückgabecode gibt an, ob der Treiber die Anforderung verarbeitet hat und entweder SQL_SUCCESS oder SQL_ERROR zurückgibt (es werden keine Diagnoseinformationen zurückgegeben). Wenn die Verarbeitung für die ursprüngliche Funktion abgebrochen wird, gibt die ursprüngliche Funktion SQL_ERROR und SQLSTATE HY008 (Vorgang abgebrochen) zurück.

Wenn eine Funktion ausgeführt wird, wenn SQLCancelHandle- auf einem anderen Thread aufgerufen wird, um die Funktion abzubrechen, ist es möglich, dass die Funktion erfolgreich ist und SQL_SUCCESS zurückgibt, bevor der Abbruch wirksam werden kann. Ein Aufruf von SQLCancelHandle hat keine Auswirkung, wenn der Vorgang abgeschlossen wurde, bevor SQLCancelHandle den Vorgang abbrechen konnte.

Verwandte Funktionen

Siehe auch

ODBC-API-Referenz
ODBC-Headerdateien
asynchrone Ausführung (Polling-Methode)