SQLEndTran-funktion

Överensstämmelse
Version introducerad: ODBC 3.0 Standardsefterlevnad: ISO 92

Summary
SQLEndTran begär en commit- eller rollback-operation för alla aktiva operationer på alla satser kopplade till en anslutning. SQLEndTran kan också begära att en commit- eller rollback-operation utförs för alla anslutningar kopplade till en miljö.

Syntax

  
SQLRETURN SQLEndTran(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle,  
     SQLSMALLINT   CompletionType);  

Arguments

HandleType
[Input] Handtagstypidentifierare. Innehåller antingen SQL_HANDLE_ENV (om Handle är ett miljöhandtag) eller SQL_HANDLE_DBC (om Handtag är ett anslutningshandtag).

Hanterare
[Input] Handtaget, av typen som anges av HandleType, anger transaktionens omfattning. Se "Kommentarer" för mer information.

CompletionType
[Input] Ett av följande två värden:

SQL_COMMIT SQL_ROLLBACK

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE eller SQL_STILL_EXECUTING.

Diagnostics

När SQLEndTran returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med rätt HandleType och Handle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLEndTran och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Comments

För en ODBC 3. x-drivrutin , om HandleType är SQL_HANDLE_ENV och Handle är ett giltigt miljöhandtag, så kommer Driver Manager att anropa SQLEndTran i varje drivrutin som är kopplad till miljön. Handle-argumentet för anropet till en drivrutin kommer att vara drivrutinens miljöhandtag. För en ODBC 2. x-drivrutin , om HandleType är SQL_HANDLE_ENV och Handle är ett giltigt miljöhandtag, och det finns flera anslutningar i ett sammankopplat tillstånd i den miljön, så kommer Driver Manager att anropa SQLTransact i drivrutinen en gång för varje anslutning i ett anslutet tillstånd i den miljön. Handle-argumentet i varje samtal är anslutningens handtag. I båda fallen kommer drivrutinen att försöka committa eller rulla tillbaka transaktioner, beroende på värdet av CompletionType, på alla anslutningar som är i ett anslutet tillstånd i den miljön. Anslutningar som inte är aktiva påverkar inte transaktionen.

Driver Manager returnerar SQL_SUCCESS endast om den får SQL_SUCCESS för varje anslutning. Om Driver Manager tar emot SQL_ERROR på en eller flera anslutningar returnerar den SQL_ERROR till applikationen och diagnosinformationen placeras i miljöns diagnostiska datastruktur. För att avgöra vilken anslutning eller vilka anslutningar som misslyckades under commit- eller rollback-operationen kan applikationen anropa SQLGetDiagRec för varje anslutning.

Om CompletionType är SQL_COMMIT skickar SQLEndTran en commit-förfrågan för alla aktiva operationer på alla satser kopplade till en berörd anslutning. Om CompletionType är SQL_ROLLBACK, skickar SQLEndTran en återställningsbegäran för alla aktiva operationer på alla satser kopplade till en påverkad anslutning. Om inga transaktioner är aktiva returnerar SQLEndTran SQL_SUCCESS utan någon effekt på några datakällor. För mer information, se Committing and Rolling Back Transactions.

Om drivrutinen är i manuellt commit-läge (genom att anropa SQLSetConnectAttr med SQL_ATTR_AUTOCOMMIT-attributet satt till SQL_AUTOCOMMIT_OFF), startas en ny transaktion implicit när en SQL-sats som kan finnas i en transaktion körs mot den aktuella datakällan. För mer information, se Commit Mode.

För att avgöra hur transaktionsoperationer påverkar markörer anropar en applikation SQLGetInfo med alternativen SQL_CURSOR_ROLLBACK_BEHAVIOR och SQL_CURSOR_COMMIT_BEHAVIOR. För mer information, se följande stycken och även Effekten av transaktioner på kursorer och förberedda konton.

Om värdet SQL_CURSOR_ROLLBACK_BEHAVIOR eller SQL_CURSOR_COMMIT_BEHAVIOR är lika med SQL_CB_DELETE, stänger och raderar SQLEndTran alla öppna markörer på alla satser kopplade till anslutningen och slänger alla väntande resultat. SQLEndTran lämnar varje sats närvarande i ett allokerat (opreparerat) tillstånd; applikationen kan återanvända dem för efterföljande SQL-förfrågningar eller anropa SQLFreeStmt eller SQLFreeHandle med en HandleType SQL_HANDLE_STMT för att frigöra dem.

Om värdet SQL_CURSOR_ROLLBACK_BEHAVIOR eller SQL_CURSOR_COMMIT_BEHAVIOR är lika med SQL_CB_CLOSE, stänger SQLEndTran alla öppna markörer på alla satser kopplade till anslutningen. SQLEndTran lämnar varje sats närvarande i ett förberedt tillstånd; applikationen kan anropa SQLExecute för en sats kopplad till anslutningen utan att först anropa SQLPrepare.

Om värdet SQL_CURSOR_ROLLBACK_BEHAVIOR eller SQL_CURSOR_COMMIT_BEHAVIOR är lika med SQL_CB_PRESERVE påverkar inte SQLEndTran öppna markörer kopplade till anslutningen. Cursors står kvar på raden de pekade på före anropet till SQLEndTran.

För drivrutiner och datakällor som stödjer transaktioner återger anrop av SQLEndTran med antingen SQL_COMMIT eller SQL_ROLLBACK när ingen transaktion är aktiv SQL_SUCCESS (vilket indikerar att inget arbete behöver committas eller rullas tillbaka) och har ingen effekt på datakällan.

När en drivrutin är i autocommit-läge anropar inte Driver Manager SQLEndTran i drivrutinen. SQLEndTran returnerar alltid SQL_SUCCESS oavsett om det anropas med en CompletionType SQL_COMMIT eller SQL_ROLLBACK.

Drivrutiner eller datakällor som inte stödjer transaktioner (SQLGetInfo-alternativet SQL_TXN_CAPABLE är SQL_TC_NONE) är i princip alltid i autocommit-läge och returnerar därför alltid SQL_SUCCESS för SQLEndTran, oavsett om de anropas med en CompletionType SQL_COMMIT eller SQL_ROLLBACK. Sådana drivrutiner och datakällor rullar faktiskt inte tillbaka transaktioner när de begärs göra det.

Suspenderad delstat

I drivrutinshanterare som släpptes före Windows 7 var en transaktion aktiv om SQLEndTran returnerade SQL_ERROR från drivrutinen. Det var dock möjligt att transaktionen hade genomförts framgångsrikt på servern, men att drivrutinen på klienten inte hade blivit meddelad (till exempel på grund av ett nätverksfel). Detta skulle lämna anslutningen i dåligt skick. Från och med Windows 7, när SQLEndTran återvänder SQL_ERROR, kan anslutningen vara i ett suspenderat tillstånd. I ett suspenderat tillstånd är det möjligt att anropa skrivskyddade funktioner. Så småningom bör applikationen anropa SQLDisconnect på en avstängd anslutning för att frigöra resurser.

Om alla följande villkor är uppfyllda, kommer kopplingen att sättas i ett suspenderat tillstånd:

• Drivrutinen returnerar SQL_ERROR från SQLEndTran.

• Drivrutinen är ODBC version 3.8 eller senare.

• Applikationsversionen är 3.8 eller senare; eller om den omkompilerade ODBC 2.x- eller 3.x-applikationen framgångsrikt avbryter SQLEndTran-funktionen via SQLCancelHandle.

• Drivrutinen returnerade inte något av följande meddelanden, som bekräftar att transaktionen inte slutfördes:

  • 25S03: Transaktionen rullas tillbaka

  • 40001: Serialiseringsfel

  • 40002: Integritetsbegränsning

  • HYC00: Valfri funktion ej implementerad

Om SQLEndTran anropades på ett miljöhandtag och en av dess anslutningar uppfyllde ovanstående villkor, kommer alla anslutningar som ansluter till samma drivrutin att sättas i det suspenderade tillståndet.

Efter att en applikation anropat SQLDisconnect på en avbruten anslutning kan anslutningen användas för att återansluta till en annan datakälla eller samma datakälla.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler
• Asynkron körning (pollningsmetod)