SQLCancel-Funktion
Konformität
Eingeführte Version: ODBC 1.0-Standards Compliance: ISO 92
Zusammenfassung
SQLCancel bricht die Verarbeitung einer Anweisung ab.
Verwenden Sie die SQLCancelHandle-Funktion, um die Verarbeitung einer 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.
Diagnose
Wenn SQLCancel 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 Handle von StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLCancel zurückgegeben werden, und die einzelnen Werte werden 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 | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | 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 | Fehler bei der Speicherbelegung | Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die FUNKTION SQLCancel aufgerufen wurde. (DM) Fehler beim Abbrechen des Vorgangs, weil ein asynchroner Vorgang für ein Verbindungshandle ausgeführt wird, das StatementHandle zugeordnet ist. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen. |
| HY018 | Abbruchanforderung vom Server abgelehnt | Der Server hat die Abbruchanforderung abgelehnt. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Treiber unterstützt diese Funktion nicht. | (DM) Der Der 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 die gleiche Wirkung wie SQLFreeStmt mit der option SQL_CLOSE; Dieses Verhalten wird nur aus Gründen der 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 gelöscht, die von der abgebrochenen Funktion bereitgestellt wurden, und SQLCancel stellt eigene Diagnosedatensätze bereit. Wenn SQLCancel aufgerufen wird, um eine Funktion abzubrechen, die in einer Anweisung in einem anderen Thread ausgeführt wird, löscht es jedoch nicht die Diagnosedatensätze der abgebrochenen Funktion und stellt keine eigenen Diagnosedatensätze bereit.
Abbrechen der asynchronen Verarbeitung
Nachdem eine Anwendung eine Funktion asynchron aufgerufen hat, ruft sie die Funktion wiederholt auf, um festzustellen, ob die Verarbeitung abgeschlossen wurde. Wenn die Funktion noch verarbeitet wird, gibt sie SQL_STILL_EXECUTING zurück. Wenn die Verarbeitung der Funktion abgeschlossen ist, gibt sie einen anderen Code zurück.
Nach jedem Aufruf der Funktion, die SQL_STILL_EXECUTING zurückgibt, kann eine Anwendung SQLCancel aufrufen, um die Funktion abzubrechen. Wenn die Abbruchanforderung erfolgreich ist, gibt der Treiber SQL_SUCCESS zurück. Diese Meldung gibt nicht an, dass die Funktion tatsächlich abgebrochen wurde. Es gibt an, dass die Abbruchanforderung verarbeitet wurde. Wann oder 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, lautet der Rückgabecode SQL_ERROR und SQLSTATE HY008 (Vorgang abgebrochen). Wenn die Funktion ihre 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 als HY008 (Vorgang abgebrochen), wenn die Funktion fehlgeschlagen ist.
Hinweis
In ODBC 3.5 wird ein Aufruf von SQLCancel , wenn keine Verarbeitung für die Anweisung erfolgt, nicht als SQLFreeStmt mit der Option SQL_CLOSE behandelt, hat aber überhaupt keine Auswirkung. Zum Schließen eines Cursors sollte eine Anwendung SQLCloseCursor und nicht SQLCancel aufrufen.
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ückgibt und daten für alle Daten bei der Ausführungsparameter 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 zurückgibt und daten für alle Daten bei der Ausführung gesendet wurden, kann eine Anwendung SQLCancel aufrufen, um den Vorgang abzubrechen. Nachdem der Vorgang abgebrochen wurde, kann die Anwendung SQLBulkOperations oder SQLSetPos erneut aufrufen. Canceling 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 in 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 betriebssystem ab. Wie beim Abbrechen einer asynchron ausgeführten Funktion gibt der Rückgabecode von SQLCancel nur an, ob der Treiber die Anforderung erfolgreich verarbeitet hat. Es können nur SQL_SUCCESS oder SQL_ERROR zurückgegeben werden. Es werden keine Diagnoseinformationen zurückgegeben. Wenn die ursprüngliche Funktion abgebrochen wird, gibt sie SQL_ERROR und SQLSTATE HY008 (Vorgang abgebrochen) zurück.
Wenn eine SQL-Anweisung ausgeführt wird, wenn SQLCancel in 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ückgibt, während der Abbruch ebenfalls erfolgreich ist. In diesem Fall geht der Treiber-Manager davon aus, dass der durch die Anweisungsausführung 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
| Informationen über | Finden Sie unter |
|---|---|
| Binden eines Puffers an einen Parameter | SQLBindParameter-Funktion |
| Ausführen von Masseneinfügungs- oder Aktualisierungsvorgängen | SQLBulkOperations-Funktion |
| Bricht eine Funktion ab, die asynchron in 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 |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für