SQLCancel-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92

Zusammenfassung
SQLCancel bricht die Verarbeitung für eine Anweisung ab.

Verwenden Sie die SQLCancelHandle-Funktion, um die Verarbeitung für eine Verbindung oder Anweisung abzubrechen.

Syntax

  
SQLRETURN SQLCancel(  
     SQLHSTMT     StatementHandle);  

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLCancel SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die sqlSTATE-Werte aufgeführt, die häufig von SQLCancel zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. 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.

Kommentare

SQLCancel kann die folgenden Verarbeitungstypen für eine Anweisung abbrechen:

• Eine Funktion, die asynchron für die Anweisung ausgeführt wird.

• Eine Funktion für eine Anweisung, die Daten benötigt.

• Eine Funktion, die für die Anweisung in einem anderen Thread ausgeführt wird.

In ODBC 2.x, wenn eine Anwendung SQLCancel aufruft, wenn keine Verarbeitung für die Anweisung erfolgt, hat SQLCancel dieselbe Auswirkung wie SQLFreeStmt mit der Option SQL_CLOSE; dieses Verhalten wird nur für Vollständigkeit definiert, und Anwendungen sollten SQLFreeStmt oder SQLCloseCursor aufrufen, um Cursor zu schließen.

Wenn SQLCancel aufgerufen wird, um eine Funktion abzubrechen, die asynchron in einer Anweisung oder einer Funktion für eine Anweisung ausgeführt wird, die Daten benötigt, werden diagnosedatensätze, die von der abgebrochenen Funktion gepostet wurden, gelöscht, und SQLCancel stellt eigene Diagnosedatensätze bereit. Wenn SQLCancel aufgerufen wird, um eine Funktion abzubrechen, die auf einer Anweisung in einem anderen Thread ausgeführt wird, werden die Diagnosedatensätze der abgebrochenen Funktion jedoch nicht gelöscht und keine eigenen Diagnosedatensätze veröffentlicht.

Abbrechen der asynchronen Verarbeitung

Nachdem eine Anwendung eine Funktion asynchron aufgerufen hat, wird die Funktion wiederholt aufgerufen, um festzustellen, ob die Verarbeitung abgeschlossen ist. Wenn die Funktion noch verarbeitet wird, wird SQL_STILL_EXECUTING zurückgegeben. Wenn die Verarbeitung der Funktion abgeschlossen ist, wird ein anderer Code zurückgegeben.

Nach einem Aufruf der Funktion, die SQL_STILL_EXECUTING zurückgibt, kann eine Anwendung SQLCancel aufrufen, um die Funktion abzubrechen. Wenn die Abbrechenanforderung erfolgreich ist, gibt der Treiber SQL_SUCCESS zurück. Diese Meldung weist nicht darauf hin, dass die Funktion tatsächlich abgebrochen wurde. sie gibt an, dass die Abbruchanforderung verarbeitet wurde. Wenn die Funktion tatsächlich abgebrochen wird, ist treiberabhängig und datenquellenabhängig. Die Anwendung muss die ursprüngliche Funktion weiterhin aufrufen, bis der Rückgabecode nicht SQL_STILL_EXECUTING ist. Wenn die Funktion erfolgreich abgebrochen wurde, ist der Rückgabecode SQL_ERROR und SQLSTATE HY008 (Vorgang abgebrochen). Wenn die Funktion die normale Verarbeitung abgeschlossen hat, wird der Rückgabecode SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO, wenn die Funktion erfolgreich war oder SQL_ERROR und ein anderer SQLSTATE-Wert als HY008 (Vorgang abgebrochen) ist, wenn die Funktion fehlgeschlagen ist.

Weitere Informationen zur asynchronen Verarbeitung finden Sie unter "Asynchrone Ausführung".

Abbrechen von Funktionen, die Daten benötigen

Nachdem SQLExecute oder SQLExecDirect SQL_NEED_DATA zurückgegeben haben und bevor Daten für alle Daten bei ausführungsparametern gesendet wurden, kann eine Anwendung SQLCancel aufrufen, um die Ausführung der Anweisung abzubrechen. Nachdem die Anweisung abgebrochen wurde, kann die Anwendung SQLExecute oder SQLExecDirect erneut aufrufen. Weitere Informationen finden Sie unter SQLBindParameter.

Nachdem SQLBulkOperations oder SQLSetPos SQL_NEED_DATA und bevor Daten für alle Daten bei ausführungsspalten gesendet wurden, kann eine Anwendung SQLCancel aufrufen, um den Vorgang abzubrechen. Nachdem der Vorgang abgebrochen wurde, kann die Anwendung SQLBulkOperations oder SQLSetPos erneut aufrufen. Das Abbrechen wirkt sich nicht auf den Cursorzustand oder die aktuelle Cursorposition aus. Weitere Informationen finden Sie unter SQLBulkOperations oder SQLSetPos.

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

In einer Multithreadanwendung kann die Anwendung eine Funktion abbrechen, die auf einem anderen Thread ausgeführt wird. Um die Funktion abzubrechen, ruft die Anwendung SQLCancel mit demselben Anweisungshandle auf, das von der Zielfunktion verwendet wird, aber in einem anderen Thread. Wie die Funktion abgebrochen wird, hängt vom Treiber und vom Betriebssystem ab. Wie beim asynchronen Abbrechen einer Funktion gibt der Rückgabecode von SQLCancel nur an, ob der Treiber die Anforderung erfolgreich verarbeitet hat. Nur SQL_SUCCESS oder SQL_ERROR können zurückgegeben werden; es werden keine Diagnoseinformationen zurückgegeben. Wenn die ursprüngliche Funktion abgebrochen wird, wird SQL_ERROR und SQLSTATE HY008 (Vorgang abgebrochen) zurückgegeben.

Wenn eine SQL-Anweisung ausgeführt wird, wenn SQLCancel auf einem anderen Thread aufgerufen wird, um die Ausführung der Anweisung abzubrechen, ist es möglich, dass die Ausführung erfolgreich ist und SQL_SUCCESS zurückgegeben wird, während der Abbruch ebenfalls erfolgreich ist. In diesem Fall geht der Treiber-Manager davon aus, dass der durch die Anweisung geöffnete Cursor durch den Cancel geschlossen wird, sodass die Anwendung den Cursor nicht verwenden kann.

Weitere Informationen zum Threading finden Sie unter Multithreading.

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien