SQLCancelHandle-Funktion

  • Artikel

Konformität
Version eingeführt: ODBC 3.8-Standardkonformität: Keine

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

Zusammenfassung
SQLCancelHandle bricht die Verarbeitung einer Verbindung oder Anweisung ab. Der Treiber-Manager ordnet einen Aufruf von 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 Ziehpunkts, für den die Verarbeitung durchgeführt werden soll. Gültige Werte sind SQL_HANDLE_DBC oder SQL_HANDLE_STMT.

Handle
[Eingabe] Das Handle, für das die Verarbeitung abgebrochen werden soll.

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

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

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 oder einem HandleType von SQL_HANDLE_DBC und einem Verbindungshandle-Handle aufgerufen wird.

In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLCancelHandle zurückgegeben werden, und sie werden jeweils 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 Eine asynchron ausgeführte, anweisungsbezogene Funktion wurde für eines der Anweisungshandles aufgerufen, die dem Handle zugeordnet sind, und HandleType wurde auf SQL_HANDLE_DBC festgelegt. Die asynchrone Funktion wurde noch ausgeführt, als SQLCancelHandle aufgerufen wurde.

(DM) Das HandleType-Argument wurde SQL_HANDLE_STMT; Eine asynchron ausgeführte Funktion wurde für das zugeordnete Verbindungshandle aufgerufen. und die Funktion wurde noch ausgeführt, als diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für eines der Anweisungshandles aufgerufen, die dem Handle zugeordnet sind, und HandleType wurde auf SQL_HANDLE_DBC festgelegt und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden.

SQLBrowseConnect wurde für ConnectionHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor der Browservorgang abgeschlossen wurde.
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.
HY092 Ungültiger Attribut-/Optionsbezeichner HandleType wurde auf SQL_HANDLE_ENV oder SQL_HANDLE_DESC festgelegt.
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 dem Handle zugeordnete Treiber unterstützt die Funktion nicht.

Wenn SQLCancelHandle aufgerufen wird, wobei HandleType auf SQL_HANDLE_STMT festgelegt ist, kann ein beliebiger SQLSTATE-Wert zurückgegeben werden, der von der Funktion SQLCancel zurückgegeben werden kann.

Kommentare

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

Weitere Informationen zum Abbrechen eines Anweisungsvorgangs finden Sie unter SQLCancel-Funktion.

Wenn beim Verarbeiten des Aufrufs von SQLCancelHandle keine Vorgänge ausgeführt werden, hat dies keine Auswirkungen.

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

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

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

Wenn SQLCancelHandle aufgerufen wird, um eine Funktion abzubrechen, die asynchron in einer Verbindung ausgeführt wird, werden von SQLCancelHandle bereitgestellte Diagnosedatensätze 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.

Wenn Sie SQLCancelHandle zum Abbrechen von SQLEndTran verwenden, wird die Verbindung möglicherweise in den Zustand angehalten versetzt. Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.

Hinweis

Informationen zur Verwendung von SQLCancelHandle in einer Anwendung, die unter einem Windows-Betriebssystem bereitgestellt wird, das älter als Windows 7 ist, finden Sie unter Kompatibilitätsmatrix.

Wenn eine Funktion SQL_STILL_EXECUTING zurückgibt, kann eine Anwendung SQLCancelHandle aufrufen, um den Vorgang abzubrechen. Wenn die Abbruchanforderung erfolgreich ist, gibt SQLCancelHandle SQL_SUCCESS zurück. Dies bedeutet nicht, dass die ursprüngliche Funktion abgebrochen wurde. Es 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, lautet der Rückgabecode SQL_ERROR und SQLSTATE HY008 (Vorgang abgebrochen). Wenn die ursprüngliche Funktion ihre normale Verarbeitung abgeschlossen hat (wurde nicht abgebrochen), wird der Rückgabecode SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO oder SQL_ERROR und ein anderer SQLSTATE als HY008 (Vorgang abgebrochen), wenn die ursprüngliche Funktion fehlgeschlagen ist.

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

In einer Multithreadanwendung kann die Anwendung einen Vorgang abbrechen, der in einem anderen Thread ausgeführt wird. Um den Vorgang abzubrechen, ruft die Anwendung SQLCancelHandle mit dem von der Funktion verwendeten Handle auf, jedoch in einem anderen Thread. Treiber und Betriebssystem bestimmen, wie der Vorgang abgebrochen wird. Der SQLCancelHandle-Rückgabecode gibt an, ob der Treiber die Anforderung verarbeitet hat, und gibt entweder SQL_SUCCESS oder SQL_ERROR zurück (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 für einen 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.

Informationen über Finden Sie unter
Abbrechen einer Funktion, die asynchron für ein Anweisungshandle ausgeführt wird, Abbrechen einer Funktion für eine Anweisung, die Daten benötigt, oder Abbrechen einer Funktion, die für eine Anweisung in einem anderen Thread ausgeführt wird. SQLCancel-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
Asynchrone Ausführung (Abfragemethode)