Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Soulad
Představená verze: ODBC 3.0 Shoda s normami: ISO 92
Summary
SQLEndTran požaduje operaci commit nebo rollback pro všechny aktivní operace na všech příkazech spojených s připojením.
SQLEndTran může také požadovat provedení operace commit nebo rollback pro všechna spojení spojená s prostředím.
Note
Pro více informací o tom, na co Driver Manager mapuje tuto funkci při ODBC 3. x aplikace pracuje s ODBC 2. x ovladač, viz Funkce nahrazování mapování pro zpětnou kompatibilitu aplikací.
Syntax
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Arguments
HandleType
[Vstup] Identifikátor typu handle (identifikátor typu handle). Obsahuje buď SQL_HANDLE_ENV (pokud je Handle environment handle), nebo SQL_HANDLE_DBC (pokud Handle je handlem spojení).
Ukazatel
[Vstup] Rukojeť, typu označeného HandleType, označuje rozsah transakce. Více informací naleznete v sekci "Komentáře".
Typ dokončení
[Vstup] Jedna z následujících dvou hodnot:
SQL_COMMIT SQL_ROLLBACK
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE nebo SQL_STILL_EXECUTING.
Diagnostika
Když SQLEndTran vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, pokud se zavolá SQLGetDiagRec s příslušným HandleType a Handle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLEndTran běžně vrací, a vysvětluje každou z nich v kontextu této funkce; notace "(DM)" předchází popisům SQLstavů vráceným Správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Obecné upozornění | Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 08003 | Připojení není otevřené | (DM) Typ rukojeti byl SQL_HANDLE_DBC a Handle nebyl ve spojeném stavu. |
| 08007 | Selhání spojení během transakce | Typ rukojeti byl SQL_HANDLE_DBC a spojení spojené s tímto příkazem selhalo během vykonávání funkce, a nelze určit, zda požadovaný COMMIT nebo ROLLBACK proběhl před selháním. |
| 25S01 | Stav transakce neznámý | Jedno nebo více spojení v Handle nedokázalo dokončit transakci s požadovaným výsledkem a výsledek není znám. |
| 25S02 | Transakce je stále aktivní | Ovladač nebyl schopen zaručit, že veškerá práce v globální transakci může být dokončena atomicky, a transakce je stále aktivní. |
| 25S03 | Transakce je vrácena zpět | Ovladač nebyl schopen zaručit, že veškerá práce v globální transakci může být dokončena atomicky, a veškerá práce v transakci aktivní v Handle byla vrácena zpět. |
| 40001 | Selhání serializace | Transakce byla vrácena zpět kvůli vzájemnému zablokování prostředku s jinou transakcí. |
| 40002 | Porušení omezení integrity | CompletionType byl SQL_COMMIT a závazek ke změnám způsobil porušení integrity omezení. V důsledku toho byla transakce zrušena. |
| HY000 | Obecná chyba | Došlo k chybě, pro kterou nebyla definována žádná specifická funkce SQLSTATE a pro kterou nebyla definována žádná implementace sqlSTATE. Chybová zpráva vrácená SQLGetDiagRec v bufferu *szMessageText popisuje chybu a její příčinu. |
| HY001 | Chyba přidělení paměti | Ovladač nemohl přidělit paměť potřebnou k podpoře provádění nebo dokončení funkce. |
| HY008 | Operace byla zrušena. | Asynchronní zpracování bylo povoleno pro ConnectionHandle. Funkce byla vyvolána a před dokončením byla funkce SQLCancelHandle vyvolána na ConnectionHandle. Poté byla funkce znovu vyvolána na ConnectionHandle. Funkce byla vyvolána a před dokončením spuštění byl SQLCancelHandle vyvolán na ConnectionHandle z jiného vlákna v multithread aplikaci. |
| HY010 | Chyba posloupnosti funkcí | (DM) Asynchronně vykonávající funkce byla volána pro příkazovou rukojeť spojenou s ConnectionHandle a stále se spouštěla, když byl volán SQLEndTran . (DM) Asynchronně vykonávající funkce (ne tato) byla volána pro ConnectionHandle a stále se spouštěla, když byla tato funkce vyvolána. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos byl vyvolán pro příkazový handle spojený s ConnectionHandle a vrátil SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce. (DM) Asynchronně vykonávající funkce (ne tato) byla volána pro Handle s nastavením HandleType na SQL_HANDLE_DBC a stále se spouštěla, když byla tato funkce vyvolána. (DM) SQLExecute, SQLExecDirect nebo SQLMoreResults byly vyvolány pro jeden z příkazových rukojetí spojených s Handle a vrátily SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry. |
| HY012 | Neplatný kód operace transakce | (DM) Hodnota zadaná pro argument CompletionType nebyla ani SQL_COMMIT, ani SQL_ROLLBACK. |
| HY013 | Chyba správy paměti | Volání funkce nelze zpracovat, protože základní objekty paměti nelze získat přístup, pravděpodobně kvůli nedostatku paměti. |
| HY092 | Neplatný identifikátor atributu/opce | (DM) Hodnota určená pro argument HandleType nebyla ani SQL_HANDLE_ENV, ani SQL_HANDLE_DBC. |
| HY115 | SQLEndTran není povolen pro prostředí, které obsahuje spojení s povoleným asynchronním vykonáváním funkcí | (DM) HandleType nelze nastavit na SQL_HANDLE_ENV, pokud je v prostředí povoleno asynchronní provádění funkcí spojení. |
| HY117 | Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení. | (DM) Pro více informací o pozastaveném stavu viz sekce Komentáře k tomuto tématu. |
| HYC00 | Nepovinná funkce není implementována. | Ovladač nebo zdroj dat nepodporuje operaci ROLLBACK . |
| HYT01 | Vypršel časový limit připojení | Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Časový limit připojení je nastavený prostřednictvím sqlSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Ovladač tuto funkci nepodporuje. | (DM) Ovladač spojený s ConnectionHandle tuto funkci nepodporuje. |
| IM017 | Dotazování je zakázané v asynchronním režimu oznámení. | Při každém použití modelu oznámení je dotazování zakázané. |
| IM018 | K dokončení předchozí asynchronní operace na tomto popisovači nebyla volána funkce SQLCompleteAsync. | Pokud předchozí volání funkce na popisovači vrátí SQL_STILL_EXECUTING a pokud je povolen režim oznámení, musí být sqlCompleteAsync volán na popisovači, aby bylo možné provést následné zpracování a dokončit operaci. |
Comments
U ODBC 3. x ovladač, pokud je HandleType SQL_HANDLE_ENV a Handle je platný environmentální handle, pak Driver Manager zavolá SQLEndTran v každém ovladači spojeném s prostředím. Argument Handle pro volání ovladači bude environmentální handle ovladače. Pro ODBC 2. x ovladač, pokud je HandleType SQL_HANDLE_ENV a Handle je platný handle prostředí, a v tomto prostředí je více připojení v připojeném stavu, pak Driver Manager zavolá SQLTransact v ovladači jednou pro každé spojení v propojeném stavu v daném prostředí. Argument Handle v každém hovoru bude handle spojení. V obou případech se ovladač pokusí zavázat nebo vrátit zpět transakce v závislosti na hodnotě CompletionType na všech spojeních, která jsou v tomto prostředí v propojeném stavu. Spojení, která nejsou aktivní, transakci neovlivňují.
Note
SQLEndTran nelze použít k potvrzení nebo vrácení transakcí ve sdíleném prostředí. SQLSTATE HY092 (Invalid attribute/option identifier) bude vrácen, pokud je SQLEndTran volán s handle nastaveným buď na handle sdíleného prostředí, nebo handle spojení ve sdíleném prostředí.
Driver Manager SQL_SUCCESS vrátí pouze tehdy, pokud obdrží SQL_SUCCESS pro každé připojení. Pokud správce ovladačů obdrží SQL_ERROR na jednom nebo více připojeních, vrátí SQL_ERROR aplikaci a diagnostické informace jsou umístěny do diagnostické datové struktury prostředí. Pro určení, které spojení nebo spojení selhaly během operace commit nebo rollback, může aplikace pro každé spojení volat SQLGetDiagRec .
Note
Driver Manager nesimuluje globální transakci napříč všemi připojeními, a proto nepoužívá dvoufázové protokoly pro potvrzení.
Pokud je CompletionType SQL_COMMIT, SQLEndTran vydá požadavek na commit pro všechny aktivní operace na jakémkoli příkazu spojeném s postiženým spojením. Pokud je CompletionType SQL_ROLLBACK, SQLEndTran vydá požadavek na vrácení všech aktivních operací na jakýkoli příkaz spojený s postiženým spojením. Pokud nejsou žádné transakce aktivní, SQLEndTran vrací SQL_SUCCESS bez vlivu na žádné datové zdroje. Pro více informací viz Committing and Rollback Transactions (Committing and Rollback Transactions).
Pokud je ovladač v režimu manuálního potvrzení (voláním SQLSetConnectAttr s atributem SQL_ATTR_AUTOCOMMIT nastaveným na SQL_AUTOCOMMIT_OFF), nová transakce je implicitně zahájena, když je SQL příkaz, který lze obsahovat v transakci, vykonán nad současným datovým zdrojem. Pro více informací viz Režim závazku.
Pro určení, jak transakční operace ovlivňují kurzory, aplikace volá SQLGetInfo s možnostmi SQL_CURSOR_ROLLBACK_BEHAVIOR a SQL_CURSOR_COMMIT_BEHAVIOR. Pro více informací viz následující odstavce a také Vliv transakcí na kurzory a připravené výpisy.
Pokud hodnota SQL_CURSOR_ROLLBACK_BEHAVIOR nebo SQL_CURSOR_COMMIT_BEHAVIOR odpovídá SQL_CB_DELETE, SQLEndTran zavře a smaže všechny otevřené kurzory u všech příkazů spojených s připojením a všechny čekající výsledky vyřadí. SQLEndTran ponechává jakýkoli příkaz v alokovaném (nepřipraveném) stavu; aplikace je může znovu použít pro následné SQL požadavky nebo může volat SQLFreeStmt či SQLFreeHandle pomocí HandleType SQL_HANDLE_STMT pro jejich deallokaci.
Pokud hodnota SQL_CURSOR_ROLLBACK_BEHAVIOR nebo SQL_CURSOR_COMMIT_BEHAVIOR odpovídá SQL_CB_CLOSE, SQLEndTran uzavře všechny otevřené kurzory u všech příkazů spojených s připojením. SQLEndTran ponechává jakýkoli příkaz v připraveném stavu; aplikace může volat SQLExecute pro příkaz spojený s připojením, aniž by nejprve volala SQLPrepare.
Pokud hodnota SQL_CURSOR_ROLLBACK_BEHAVIOR nebo SQL_CURSOR_COMMIT_BEHAVIOR odpovídá SQL_CB_PRESERVE, SQLEndTran neovlivňuje otevřené kurzory spojené s připojením. Kurzory zůstávají na řádku, na který ukazovaly před voláním do SQLEndTran.
U ovladačů a datových zdrojů podporujících transakce volání SQLEndTran buď s SQL_COMMIT nebo SQL_ROLLBACK, když není žádná transakce aktivní, se vrátí SQL_SUCCESS (což znamená, že není potřeba žádná práce k dokončení nebo vrácení) a nemá žádný vliv na datový zdroj.
Když je ovladač v režimu automatického závazku, správce ovladačů v ovladači nevolá SQLEndTran . SQLEndTran vždy vrací SQL_SUCCESS bez ohledu na to, zda je volán s CompletionType SQL_COMMIT nebo SQL_ROLLBACK.
Ovladače nebo datové zdroje, které nepodporují transakce (volbaSQLGetInfo SQL_TXN_CAPABLE je SQL_TC_NONE), jsou v podstatě vždy v režimu automatického potvrzení a proto vždy vracejí SQL_SUCCESS pro SQLEndTran, ať už jsou volány s CompletionType SQL_COMMIT nebo SQL_ROLLBACK. Takové ovladače a zdroje dat ve skutečnosti neruší transakce na žádost.
Pozastavený stav
V správcích ovladačů, které byly uvolněny před Windows 7, byla transakce aktivní, pokud SQLEndTran vrátil SQL_ERROR z ovladače. Bylo však možné, že transakce byla úspěšně provedena na serveru, ale ovladač na klientovi nebyl upozorněn (například kvůli chybě v síti). To by zanechalo spojení ve špatném stavu. Od Windows 7, když SQLEndTran vrátí SQL_ERROR, spojení může být pozastavené. V pozastaveném stavu je možné volat pouze čtenošské funkce. Nakonec by aplikace měla na pozastavené spojení zavolat SQLDisconnect , aby uvolnila zdroje.
Pokud jsou splněny všechny následující podmínky, spojení bude uvedeno do pozastaveného stavu:
Ovladač vrací SQL_ERROR ze SQLEndTran.
Ovladač je verze ODBC 3.8 nebo novější.
Verze aplikace je 3.8 nebo novější; nebo že rekompilovaná aplikace ODBC 2.x nebo 3.x úspěšně zruší funkci SQLEndTran prostřednictvím SQLCancelHandle.
Ovladač nevrátil jednu z následujících zpráv, které potvrzují, že transakce nebyla dokončena:
25S03: Transakce je zrušena zpět
40001: Selhání serializace
40002: Omezení integrity
HYC00: Volitelná funkce neimplementovaná
Pokud byl SQLEndTran vyvolán na environmentálním handle a jedno z jeho spojení splnilo výše uvedené podmínky, všechna spojení připojená ke stejnému ovladači budou převedena do pozastaveného stavu.
Po zavolání SQLDisconnect aplikací na pozastavené spojení lze připojení použít k opětovnému připojení k jinému nebo stejnému datovému zdroji.
Související funkce
| Informace o | Podívejte se |
|---|---|
| Zrušení funkce běžící asynchronně na spojovacím handle. | Funkce SQLCancelHandle |
| Vrácení informací o ovladači nebo datovém zdroji | Funkce SQLGetInfo |
| Uvolnění rukojeti | Funkce SQLFreeHandle |
| Uvolnění rukojeti příkazu | FUNKCE SQLFreeStmt |