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.
| SQLSTATE | Error | Beschreibung |
|---|---|---|
| 01000 | Allgemeiner Warnhinweis | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im Argument *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY001 | Speicherzuweisungsfehler | Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLCancel-Funktion aufgerufen wurde. (DM) Fehler beim Abbrechen des Vorgangs, da ein asynchroner Vorgang in einem Verbindungshandle ausgeführt wird, das mit "StatementHandle" verknüpft ist. |
| HY013 | Speicherverwaltungsfehler | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen. |
| HY018 | Anforderung für abgelehnte Serverabbruch | Der Server hat die Kündigungsanforderung abgelehnt. |
| HY117 | Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt. |
| IM001 | Dieser Treiber unterstützt diese Funktion nicht. | (DM) Der dem StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
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.
Hinweis
In ODBC 3.5 wird ein Aufruf von SQLCancel , wenn keine Verarbeitung für die Anweisung ausgeführt wird, nicht als SQLFreeStmt mit der Option SQL_CLOSE behandelt, hat aber überhaupt keine Auswirkung. Zum Schließen eines Cursors sollte eine Anwendung SQLCloseCursor aufrufen, nicht SQLCancel.
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 zu | Siehe |
|---|---|
| Binden eines Puffers an einen Parameter | SQLBindParameter-Funktion |
| Ausführen von Masseneinfüge- oder Aktualisierungsvorgängen | SQLBulkOperations-Funktion |
| Bricht eine Funktion ab, die asynchron auf einem Verbindungshandle ausgeführt wird, zusätzlich zur Funktionalität von SQLCancel. | SQLCancelHandle-Funktion |
| Ausführen einer SQL-Anweisung | SQLExecDirect-Funktion |
| Ausführen einer vorbereiteten SQL-Anweisung | SQLExecute-Funktion |
| Freigeben eines Anweisungshandles | SQLFreeStmt |
| Abrufen eines Felds eines Diagnosedatensatzes oder eines Felds des Diagnoseheaders | SQLGetDiagField-Funktion |
| Abrufen mehrerer Felder einer Diagnosedatenstruktur | SQLGetDiagRec-Funktion |
| Zurückgeben des nächsten Parameters zum Senden von Daten für | SQLParamData-Funktion |
| Senden von Parameterdaten zur Ausführungszeit | SQLPutData-Funktion |
| Positionieren des Cursors in einem Rowset, Aktualisieren von Daten im Rowset oder Aktualisieren oder Löschen von Daten im Resultset | SQLSetPos-Funktion |