SQLEndTran-Funktion
Konformität
Version eingeführt: ODBC 3.0-Normenkonformität: ISO 92
Zusammenfassung
SQLEndTran fordert einen Commit- oder Rollbackvorgang für alle aktiven Vorgänge für alle Anweisungen an, die einer Verbindung zugeordnet sind. SQLEndTran kann auch anfordern, dass für alle Verbindungen, die einer Umgebung zugeordnet sind, ein Commit- oder Rollbackvorgang ausgeführt wird.
Hinweis
Weitere Informationen dazu, was der Treiber-Manager diese Funktion bei ODBC 3 ordnet. Die x-Anwendung arbeitet mit ODBC 2. x-Treiber , siehe Zuordnen von Ersatzfunktionen für die Abwärtskompatibilität von Anwendungen.
Syntax
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Argumente
HandleType
[Eingabe] Handle-Typbezeichner. Enthält entweder SQL_HANDLE_ENV (wenn Handle ein Umgebungshandle ist) oder SQL_HANDLE_DBC (wenn Handle ein Verbindungshandle ist).
Handle
[Eingabe] Das Handle des vom HandleType angegebenen Typs, der den Bereich der Transaktion angibt. Weitere Informationen finden Sie unter "Kommentare".
CompletionType
[Eingabe] Einer der beiden folgenden Werte:
SQL_COMMIT SQL_ROLLBACK
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.
Diagnose
Wenn SQLEndTran SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit dem entsprechenden HandleType und Handle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLEndTran zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, 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. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 08003 | Verbindung nicht geöffnet | (DM) Der HandleType wurde SQL_HANDLE_DBC, und der Handle befand sich nicht in einem verbundenen Zustand. |
| 08007 | Verbindungsfehler während der Transaktion | Der HandleType wurde SQL_HANDLE_DBC, und die dem Handle zugeordnete Verbindung ist während der Ausführung der Funktion fehlgeschlagen, und es kann nicht bestimmt werden, ob der angeforderte COMMIT oder ROLLBACK vor dem Fehler aufgetreten ist. |
| 25S01 | Transaktionsstatus unbekannt | Mindestens eine der Verbindungen in Handle konnte die Transaktion nicht mit dem angegebenen Ergebnis abschließen, und das Ergebnis ist unbekannt. |
| 25S02 | Transaktion ist weiterhin aktiv | Der Treiber konnte nicht garantieren, dass alle Arbeiten in der globalen Transaktion atomar abgeschlossen werden konnten und die Transaktion weiterhin aktiv ist. |
| 25S03 | Transaktion wird zurückgesetzt | Der Treiber konnte nicht garantieren, dass alle Arbeiten in der globalen Transaktion atomar abgeschlossen werden konnten, und alle Arbeiten in der Transaktion, die in Handle aktiv ist, wurden zurückgesetzt. |
| 40001 | Serialisierungsfehler | Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt. |
| 40002 | Verletzung der Integritätseinschränkung | Der CompletionType wurde SQL_COMMIT, und die Verpflichtung von Änderungen führte zu einer Verletzung der Integritätseinschränkungen. Daher wurde ein Rollback für die Transaktion ausgeführt. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *szMessageText-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 Vervollständigung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Für ConnectionHandle wurde die asynchrone Verarbeitung aktiviert. Die Funktion wurde aufgerufen, und bevor die Ausführung der SQLCancelHandle-Funktion auf dem ConnectionHandle-Objekt beendet wurde. Anschließend wurde die Funktion auf der ConnectionHandle erneut aufgerufen. Die Funktion wurde aufgerufen, und bevor die Ausführung von SQLCancelHandle abgeschlossen war, wurde auf dem ConnectionHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für ein Anweisungshandle aufgerufen, das dem ConnectionHandle zugeordnet ist, und wurde weiterhin ausgeführt, als SQLEndTran aufgerufen wurde. (DM) Eine asynchron ausgeführte Funktion (nicht diese Funktion) wurde für ConnectionHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für ein Anweisungshandle-Handle aufgerufen, das dem ConnectionHandle zugeordnet ist, und SQL_NEED_DATA zurückgegeben wurde. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführung gesendet wurden. (DM) Eine asynchron ausgeführte Funktion (nicht diese Funktion) wurde für den Handle mit HandleType auf SQL_HANDLE_DBC aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für eines der Mit Handlezugeordneten Anweisungshandles aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. |
| HY012 | Ungültiger Transaktionsvorgangscode | (DM) Der für das Argument CompletionType angegebene Wert war weder SQL_COMMIT noch SQL_ROLLBACK. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY092 | Ungültiger Attribut-/Optionsbezeichner | (DM) Der für das Argument HandleType angegebene Wert war weder SQL_HANDLE_ENV noch SQL_HANDLE_DBC. |
| HY115 | SQLEndTran ist für eine Umgebung, die eine Verbindung mit aktivierter asynchroner Funktionsausführung enthält, nicht zulässig. | (DM) HandleType kann nicht auf SQL_HANDLE_ENV festgelegt werden, wenn die asynchrone Ausführung von Verbindungsfunktionen für eine Verbindung in der Umgebung aktiviert ist. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie im Abschnitt Kommentare dieses Themas. |
| HYC00 | Optionale Funktion nicht implementiert | Der Treiber oder die Datenquelle unterstützt den ROLLBACK-Vorgang nicht. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Treiber unterstützt diese Funktion nicht. | (DM) Der der ConnectionHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert. | Wenn das Benachrichtigungsmodell verwendet wird, wird die Abfrage deaktiviert. |
| IM018 | SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. | Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachverarbeitung durchzuführen und den Vorgang abzuschließen. |
Kommentare
Für odbc 3. x-Treiber : Wenn HandleType SQL_HANDLE_ENV und Handle ein gültiges Umgebungshandle ist, ruft der Treiber-Manager SQLEndTran in jedem Treiber auf, der der Umgebung zugeordnet ist. Das Handle-Argument für den Aufruf eines Treibers ist das Umgebungshandle des Treibers. Für odbc 2. x-Treiber : Wenn HandleType SQL_HANDLE_ENV ist und Handle ein gültiges Umgebungshandle ist und in dieser Umgebung mehrere Verbindungen in einem verbundenen Zustand vorhanden sind, ruft der Treiber-Manager sqlTransact im Treiber einmal für jede Verbindung in einem verbundenen Zustand in dieser Umgebung auf. Das Handle-Argument in jedem Aufruf ist das Handle der Verbindung. In beiden Fällen versucht der Treiber, Transaktionen abhängig vom Wert von CompletionType für alle Verbindungen, die sich in dieser Umgebung in einem verbundenen Zustand befinden, zu committen oder ein Rollback durchzuführen. Verbindungen, die nicht aktiv sind, wirken sich nicht auf die Transaktion aus.
Hinweis
SQLEndTran kann nicht zum Committen oder Rollback von Transaktionen in einer freigegebenen Umgebung verwendet werden. SQLSTATE HY092 (Ungültiges Attribut/Optionsbezeichner) wird zurückgegeben, wenn SQLEndTran aufgerufen wird, wobei handle entweder auf das Handle einer freigegebenen Umgebung oder das Handle einer Verbindung in einer freigegebenen Umgebung festgelegt ist.
Der Treiber-Manager gibt nur SQL_SUCCESS zurück, wenn er für jede Verbindung SQL_SUCCESS empfängt. Wenn der Treiber-Manager SQL_ERROR für eine oder mehrere Verbindungen empfängt, gibt er SQL_ERROR an die Anwendung zurück, und die Diagnoseinformationen werden in der Diagnosedatenstruktur der Umgebung platziert. Um zu bestimmen, welche Verbindung oder Verbindungen während des Commit- oder Rollbackvorgangs fehlgeschlagen sind, kann die Anwendung SQLGetDiagRec für jede Verbindung aufrufen.
Hinweis
Der Treiber-Manager simuliert keine globale Transaktion über alle Verbindungen hinweg und verwendet daher keine zweistufigen Commitprotokolle.
Wenn CompletionType SQL_COMMIT ist, gibt SQLEndTran eine Commitanforderung für alle aktiven Vorgänge für jede Anweisung aus, die einer betroffenen Verbindung zugeordnet ist. Wenn CompletionType SQL_ROLLBACK ist, gibt SQLEndTran eine Rollbackanforderung für alle aktiven Vorgänge für jede Anweisung aus, die einer betroffenen Verbindung zugeordnet ist. Wenn keine Transaktionen aktiv sind, gibt SQLEndTran SQL_SUCCESS ohne Auswirkungen auf Datenquellen zurück. Weitere Informationen finden Sie unter Committen und Rollback von Transaktionen.
Wenn sich der Treiber im Modus für manuelle Commits befindet (durch Aufrufen von SQLSetConnectAttr mit dem attribut SQL_ATTR_AUTOCOMMIT, das auf SQL_AUTOCOMMIT_OFF festgelegt ist), wird implizit eine neue Transaktion gestartet, wenn eine SQL-Anweisung, die in einer Transaktion enthalten sein kann, für die aktuelle Datenquelle ausgeführt wird. Weitere Informationen finden Sie unter Commitmodus.
Um zu bestimmen, wie sich Transaktionsvorgänge auf Cursor auswirken, ruft eine Anwendung SQLGetInfo mit den Optionen SQL_CURSOR_ROLLBACK_BEHAVIOR und SQL_CURSOR_COMMIT_BEHAVIOR auf. Weitere Informationen finden Sie in den folgenden Absätzen und auch unter Auswirkung von Transaktionen auf Cursor und vorbereitete Anweisungen.
Wenn der SQL_CURSOR_ROLLBACK_BEHAVIOR- oder SQL_CURSOR_COMMIT_BEHAVIOR-Wert gleich SQL_CB_DELETE ist, schließt und löscht SQLEndTran alle geöffneten Cursor für alle Anweisungen, die der Verbindung zugeordnet sind, und verwirft alle ausstehenden Ergebnisse. SQLEndTran lässt jede Anweisung in einem zugeordneten (nicht vorbereiteten) Zustand vorhanden. Die Anwendung kann sie für nachfolgende SQL-Anforderungen wiederverwenden oder SQLFreeStmt oder SQLFreeHandle mit einem HandleType von SQL_HANDLE_STMT aufrufen, um die Zuordnung aufzugeben.
Wenn der SQL_CURSOR_ROLLBACK_BEHAVIOR- oder SQL_CURSOR_COMMIT_BEHAVIOR-Wert gleich SQL_CB_CLOSE ist, schließt SQLEndTran alle geöffneten Cursor für alle Anweisungen, die der Verbindung zugeordnet sind. SQLEndTran belässt alle Anweisungen in einem vorbereiteten Zustand. Die Anwendung kann SQLExecute für eine anweisung aufrufen, die der Verbindung zugeordnet ist, ohne zuerst SQLPrepare aufzurufen.
Wenn der SQL_CURSOR_ROLLBACK_BEHAVIOR- oder SQL_CURSOR_COMMIT_BEHAVIOR-Wert gleich SQL_CB_PRESERVE ist, wirkt sich SQLEndTran nicht auf geöffnete Cursor aus, die der Verbindung zugeordnet sind. Cursor verbleiben in der Zeile, auf die sie vor dem Aufruf von SQLEndTran gezeigt haben.
Für Treiber und Datenquellen, die Transaktionen unterstützen, gibt der Aufruf von SQLEndTran entweder mit SQL_COMMIT oder SQL_ROLLBACK, wenn keine Transaktion aktiv ist, SQL_SUCCESS zurück (dies bedeutet, dass kein Commit oder Rollback ausgeführt werden muss) und hat keine Auswirkungen auf die Datenquelle.
Wenn sich ein Treiber im Autocommit-Modus befindet, ruft der Treiber-Manager SQLEndTran im Treiber nicht auf. SQLEndTran gibt immer SQL_SUCCESS zurück, unabhängig davon, ob es mit einem CompletionType-Wert von SQL_COMMIT oder SQL_ROLLBACK aufgerufen wird.
Treiber oder Datenquellen, die keine Transaktionen unterstützen (SQLGetInfo-Option SQL_TXN_CAPABLE ist SQL_TC_NONE), befinden sich effektiv immer im Autocommit-Modus und geben daher immer SQL_SUCCESS für SQLEndTran zurück, unabhängig davon, ob sie mit einem CompletionType SQL_COMMIT oder SQL_ROLLBACK aufgerufen werden. Solche Treiber und Datenquellen führen tatsächlich kein Rollback für Transaktionen durch, wenn sie dazu aufgefordert werden.
Angehaltener Zustand
In Treiber-Managern, die vor Windows 7 veröffentlicht wurden, war eine Transaktion aktiv, wenn SQLEndTran SQL_ERROR vom Treiber zurückgegeben hat. Es war jedoch möglich, dass die Transaktion erfolgreich auf dem Server committet wurde, aber der Treiber auf dem Client nicht benachrichtigt wurde (z. B. weil ein Netzwerkfehler aufgetreten ist). Dadurch würde die Verbindung in einem fehlerhaften Zustand bleiben. Wenn SQLEndTran ab Windows 7 SQL_ERROR zurückgibt, befindet sich die Verbindung möglicherweise in einem angehaltenen Zustand. Im Angehaltenen Zustand ist es möglich, schreibgeschützte Funktionen aufzurufen. Schließlich sollte die Anwendung SQLDisconnect für eine angehaltene Verbindung zum Freigeben von Ressourcen aufrufen.
Wenn alle folgenden Bedingungen zutreffen, wird die Verbindung in einen angehaltenen Zustand versetzt:
Der Treiber gibt SQL_ERROR aus SQLEndTran zurück.
Der Treiber ist ODBC-Version 3.8 oder höher.
Die Anwendungsversion ist 3.8 oder höher. oder die neu kompilierte ODBC 2.x- oder 3.x-Anwendung bricht die SQLEndTran-Funktion erfolgreich über SQLCancelHandle ab.
Der Treiber hat keine der folgenden Meldungen zurückgegeben, die bestätigen, dass die Transaktion nicht abgeschlossen wurde:
25S03: Für die Transaktion wird ein Rollback ausgeführt
40001: Serialisierungsfehler
40002: Integritätseinschränkung
HYC00: Optionales Feature nicht implementiert
Wenn SQLEndTran für ein Umgebungshandle aufgerufen wurde und eine seiner Verbindungen die oben genannten Bedingungen erfüllt, werden alle Verbindungen, die mit demselben Treiber verbunden sind, in den angehaltenen Zustand versetzt.
Nachdem eine Anwendung SQLDisconnect für eine angehaltene Verbindung aufgerufen hat, kann die Verbindung verwendet werden, um eine erneute Verbindung mit einer anderen Datenquelle oder derselben Datenquelle herzustellen.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Abbrechen einer Funktion, die asynchron für ein Verbindungshandle ausgeführt wird. | SQLCancelHandle-Funktion |
| Zurückgeben von Informationen zu einem Treiber oder einer Datenquelle | SQLGetInfo-Funktion |
| Freigeben eines Handles | SQLFreeHandle-Funktion |
| Freigeben eines Anweisungshandles | SQLFreeStmt-Funktion |
Weitere Informationen
ODBC-API-Referenz
ODBC-Headerdateien
Asynchrone Ausführung (Polling-Methode)
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