SQLEndTran-Funktion
Konformität
Version eingeführt: ODBC 3.0 Standards Compliance: 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 ein Commit- oder Rollbackvorgang für alle Verbindungen ausgeführt wird, die einer Umgebung zugeordnet sind.
Hinweis
Weitere Informationen dazu, was der Treiber-Manager dieser Funktion zuordnet, wenn ein ODBC 3 ist.x-Anwendung arbeitet mit einem ODBC 2.x-Treiber finden Sie unter Mapping Replacement Functions for Backward Compatibility of Applications.
Syntax
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Argumente
HandleType
[Eingabe] Behandeln sie den 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 typs, der von HandleType angegeben wird, der den Bereich der Transaktion angibt. Weitere Informationen finden Sie unter "Kommentare".
CompletionType
[Eingabe] Einer der folgenden beiden Werte:
SQL_COMMIT SQL_ROLLBACK
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.
Diagnostik
Wenn SQLEndTran SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit dem entsprechenden HandleType und Handle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLEndTran 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.) |
| 08003 | Verbindung nicht geöffnet | (DM) Der HandleType wurde SQL_HANDLE_DBC, und der Handle war nicht in einem verbundenen Zustand. |
| 08007 | Verbindungsfehler während der Transaktion | Der HandleType wurde SQL_HANDLE_DBC, und die Verbindung, die dem Handle zugeordnet ist, 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 im Handle konnte die Transaktion mit dem angegebenen Ergebnis nicht abschließen, und das Ergebnis ist unbekannt. |
| 25S02 | Transaktion ist noch aktiv | Der Treiber konnte nicht garantieren, dass alle Arbeiten in der globalen Transaktion atomisch abgeschlossen werden konnten und die Transaktion noch aktiv ist. |
| 25S03 | Transaktion wird zurückgesetzt | Der Treiber konnte nicht garantieren, dass alle Arbeiten in der globalen Transaktion atomisch abgeschlossen werden konnten, und alle Arbeiten in der Transaktion, die im Handle aktiv sind, wurden zurückgesetzt. |
| 40001 | Serialisierungsfehler | Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt. |
| 40002 | Integritätseinschränkungsverletzung | " CompletionType " wurde SQL_COMMIT, und die Verpflichtung von Änderungen führte zu Einer Verletzung der Integritätseinschränkung. Daher wurde die Transaktion zurückgesetzt. |
| 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 *szMessageText-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. |
| HY008 | Vorgang abgebrochen | Die asynchrone Verarbeitung wurde für " ConnectionHandle" aktiviert. Die Funktion wurde aufgerufen, und bevor sie die Ausführung der SQLCancelHandle-Funktion abgeschlossen hat, wurde für connectionHandle aufgerufen. Anschließend wurde die Funktion erneut für das ConnectionHandle aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung von SQLCancelHandle abgeschlossen hat, wurde für das ConnectionHandle von 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 noch ausgeführt wurde, als SQLEndTran aufgerufen wurde. (DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das ConnectionHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für ein Anweisungshandle aufgerufen, das dem ConnectionHandle zugeordnet ist und SQL_NEED_DATA zurückgegeben wurde. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden. (DM) Eine asynchron ausgeführte Funktion (nicht diese Funktion) wurde für das Handle mit HandleType-Wert aufgerufen, der auf SQL_HANDLE_DBC festgelegt ist und noch ausgeführt wurde, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für einen der Mit Handle zugeordneten 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 | Speicherverwaltungsfehler | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen. |
| 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 des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie im Abschnitt "Kommentare" dieses Themas. |
| HYC00 | Optionales Feature wurde 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 geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt. |
| IM001 | Dieser Treiber unterstützt diese Funktion nicht. | (DM) Der dem ConnectionHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert. | Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung 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 Nachbearbeitung durchzuführen und den Vorgang abzuschließen. |
Kommentare
Für einen 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 der Umgebungshandle des Treibers. Für ein ODBC 2.x-Treiber , wenn HandleType SQL_HANDLE_ENV und Handle ein gültiges Umgebungshandle ist und mehrere Verbindungen in einem verbundenen Zustand in dieser Umgebung vorhanden sind, ruft der Treiber-Manager SQLTransact 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 in einem verbundenen Zustand in dieser Umgebung zu übernehmen oder zurückzuschalten. Nicht aktive Verbindungen wirken sich nicht auf die Transaktion aus.
Hinweis
SQLEndTran kann nicht zum Commit oder Zurücksetzen von Transaktionen in einer freigegebenen Umgebung verwendet werden. SQLSTATE HY092 (Ungültiger Attribut-/Optionsbezeichner) wird zurückgegeben, wenn SQLEndTran mit Handle aufgerufen wird, das entweder auf das Handle einer freigegebenen Umgebung oder das Handle einer Verbindung in einer freigegebenen Umgebung festgelegt ist.
Der Treiber-Manager gibt SQL_SUCCESS nur zurück, wenn er SQL_SUCCESS für jede Verbindung empfängt. Wenn der Treiber-Manager SQL_ERROR für eine oder mehrere Verbindungen empfängt, wird SQL_ERROR an die Anwendung zurückgegeben, und die Diagnoseinformationen werden in der Diagnosedatenstruktur der Umgebung platziert. Um festzustellen, 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 Commit-Anforderung 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 Auswirkung auf Datenquellen zurück. Weitere Informationen finden Sie unter Commit und Rollback-Transaktionen.
Wenn sich der Treiber im manuellen Commitmodus befindet (durch Aufrufen von SQLSetConnectAttr mit dem SQL_ATTR_AUTOCOMMIT Attribut, das auf SQL_AUTOCOMMIT_OFF festgelegt ist), wird eine neue Transaktion implizit 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 Commit-Modus.
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 "Auswirkungen von Transaktionen auf Cursor" und "Vorbereitete Aussagen".
Wenn der SQL_CURSOR_ROLLBACK_BEHAVIOR- oder SQL_CURSOR_COMMIT_BEHAVIOR-Wert SQL_CB_DELETE entspricht, schließt SQLEndTran alle geöffneten Cursor für alle mit der Verbindung verbundenen Anweisungen und verwirft alle ausstehenden Ergebnisse. SQLEndTran verlässt jede Anweisung, die in einem zugewiesenen (nicht analysierten) Zustand vorhanden ist. Die Anwendung kann sie für nachfolgende SQL-Anforderungen wiederverwenden oder SQLFreeStmt oder SQLFreeHandle mit einem HandleType von SQL_HANDLE_STMT aufrufen, um sie zu behandeln.
Wenn der SQL_CURSOR_ROLLBACK_BEHAVIOR- oder SQL_CURSOR_COMMIT_BEHAVIOR-Wert SQL_CB_CLOSE entspricht, schließt SQLEndTran alle geöffneten Cursor für alle Anweisungen, die der Verbindung zugeordnet sind. SQLEndTran verlässt jede Anweisung, die in einem vorbereiteten Zustand vorhanden ist. 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 SQL_CB_PRESERVE entspricht, wirkt sich SQLEndTran nicht auf geöffnete Cursor aus, die der Verbindung zugeordnet sind. Cursor verbleiben an der Zeile, auf die sie vor dem Aufruf von SQLEndTran verwiesen haben.
Für Treiber und Datenquellen, die Transaktionen unterstützen, gibt das Aufrufen von SQLEndTran mit SQL_COMMIT oder SQL_ROLLBACK zurück, wenn keine Transaktion aktiv ist, SQL_SUCCESS zurückgibt (was angibt, dass kein Commit ausgeführt oder zurückgesetzt werden soll) und hat keine Auswirkungen auf die Datenquelle.
Wenn sich ein Treiber im Autocommit-Modus befindet, ruft der Treiber-Manager sqlEndTran nicht im Treiber auf. SQLEndTran gibt immer SQL_SUCCESS zurück, unabhängig davon, ob sie mit einem CompletionType von SQL_COMMIT oder SQL_ROLLBACK aufgerufen wird.
Treiber oder Datenquellen, die Transaktionen nicht unterstützen (SQLGetInfo-Option SQL_TXN_CAPABLE ist SQL_TC_NONE) sind effektiv immer im Autocommit-Modus und geben daher immer SQL_SUCCESS für SQLEndTran zurück, unabhängig davon, ob sie mit einem CompletionType von SQL_COMMIT oder SQL_ROLLBACK aufgerufen werden. Solche Treiber und Datenquellen führen keine Rollback-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 ausgeführt wurde, aber der Treiber auf dem Client nicht benachrichtigt wurde (z. B. weil ein Netzwerkfehler aufgetreten ist). Dies würde die Verbindung in einem schlechten Zustand belassen. Ab Windows 7 befindet sich die Verbindung möglicherweise in einem angehaltenen Zustand, wenn SQLEndTran SQL_ERROR zurückgibt. In einem angehaltenen Zustand ist es möglich, schreibgeschützte Funktionen aufzurufen. Schließlich sollte die Anwendung SQLDisconnect für eine angehaltene Verbindung aufrufen, um Ressourcen freizugeben.
Wenn alle folgenden Bedingungen erfüllt sind, 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 Nachrichten zurückgegeben, die bestätigen, dass die Transaktion nicht abgeschlossen wurde:
25S03: Transaktion wird zurückgesetzt
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
| Weitere Informationen zu | Siehe |
|---|---|
| Abbrechen einer Funktion, die asynchron auf einem 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 (Abrufmethode)