Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Zgodność
Wprowadzona wersja: Zgodność z normami ODBC 3.0: ISO 92
Podsumowanie
SQLEndTran żąda zatwierdzenia lub cofnięcia operacji dla wszystkich aktywnych operacji na wszystkich instrukcjach powiązanych z połączeniem.
SQLEndTran może również żądać wykonania operacji commit lub rollback dla wszystkich połączeń powiązanych ze środowiskiem.
Note
Aby uzyskać więcej informacji o tym, do czego Driver Manager mapuje tę funkcję przy ODBC 3. Aplikacja x działa z ODBC 2. x driver, zobacz Funkcje zastępcze mapowania dla kompatybilności wstecznej aplikacji.
Syntax
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Arguments
HandleType
[Input] Identyfikator typu uchwytu. Zawiera albo SQL_HANDLE_ENV (jeśli Handle jest handlem środowiskowym) lub SQL_HANDLE_DBC (jeśli Handle jest handlem połączenia).
Uchwyt
[Input] Uchwyt, oznaczony przez HandleType, wskazuje zakres transakcji. Zobacz "Komentarze" po więcej informacji.
Typ ukończenia
[Input] Jedna z następujących dwóch wartości:
SQL_COMMIT SQL_ROLLBACK
Zwroty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE lub SQL_STILL_EXECUTING.
Diagnostyka
Gdy SQLEndTran zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLGetDiagRec z odpowiednimi HandleType i Handle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLEndTran i wyjaśnia każdą z nich w kontekście tej funkcji; notacja "(DM)" poprzedza opisy stanów SQL zwracanych przez Menedżera Sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Ostrzeżenie ogólne | Komunikat informacyjny specyficzny dla sterownika. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 08003 | Połączenie nie jest otwarte | (DM) HandleType był SQL_HANDLE_DBC, a Handle nie był w stanie połączonym. |
| 08007 | Awaria połączenia podczas transakcji | HandleType był SQL_HANDLE_DBC, a połączenie powiązane z Handlem zawiodło podczas wykonywania funkcji i nie można ustalić, czy żądany COMMIT czy ROLLBACK nastąpił przed niepowodzeniem. |
| 25S01 | Stan transakcji nieznany | Jedno lub więcej połączeń w Handle nie zakończyło transakcji z określonym wynikiem, a wynik pozostaje nieznany. |
| 25S02 | Transakcja nadal jest aktywna | Sterownik nie był w stanie zagwarantować, że cała praca w globalnej transakcji może zostać ukończona atomowo, a transakcja nadal jest aktywna. |
| 25S03 | Transakcja jest cofana | Sterownik nie był w stanie zagwarantować, że cała praca w globalnej transakcji może zostać ukończona atomowo, a cała praca w transakcji aktywnej w Handle została cofnięta. |
| 40001 | Niepowodzenie serializacji | Transakcja została wycofana z powodu zakleszczenia zasobu z inną transakcją. |
| 40002 | Naruszenie ograniczeń integralności | CompletionType był SQL_COMMIT, a zobowiązanie do wprowadzania zmian powodowało naruszenie ograniczeń integralności. W rezultacie transakcja została cofnięta. |
| HY000 | Błąd ogólny | Wystąpił błąd, dla którego nie było określonego stanu SQLSTATE i dla którego nie zdefiniowano parametru SQLSTATE specyficznego dla implementacji. Komunikat o błędzie zwracany przez SQLGetDiagRec w buforze *szMessageText opisuje błąd i jego przyczynę. |
| HY001 | Błąd alokacji pamięci | Sterownik nie może przydzielić pamięci wymaganej do obsługi wykonywania lub ukończenia funkcji. |
| HY008 | Operacja anulowana | Przetwarzanie asynchroniczne zostało włączone dla ConnectionHandle. Funkcja została wywołana, a zanim zakończyła wykonanie, funkcja SQLCancelHandle została wywołana na ConnectionHandle. Następnie funkcja została wywołana ponownie na ConnectionHandle. Funkcja została wywołana, a zanim się zakończyła, SQLCancelHandle został wywołany na ConnectionHandle z innego wątku w aplikacji wielowątkowej. |
| HY010 | Błąd sekwencji funkcji | (DM) Funkcja asynchronicznie wykonująca była wywoływana dla uchwytu instrukcji powiązanego z ConnectionHandle i nadal działała, gdy wywoływano SQLEndTran . (DM) Funkcja wykonująca asynchronicznie (nie ta) była wywoływana dla ConnectionHandle i nadal działała w momencie wywołania tej funkcji. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations lub SQLSetPos zostały wywołane dla uchwytu instrukcji powiązanego z ConnectionHandle i zwracały SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn. (DM) Funkcja wykonująca asynchronicznie (nie ta) była wywoływana dla Handle z ustawionym HandleType na SQL_HANDLE_DBC i nadal działała, gdy ta funkcja została wywołana. (DM) SQLExecute, SQLExecDirect lub SQLMoreResults zostały wywołane dla jednej z poleceń powiązanych z handlem i zwracały SQL_PARAM_DATA_AVAILABLE. Ta funkcja została wywołana przed pobraniem danych dla wszystkich parametrów przesyłanych strumieniowo. |
| HY012 | Nieprawidłowy kod operacji transakcyjnej | (DM) Wartość określona dla argumentu CompletionType nie była ani SQL_COMMIT, ani SQL_ROLLBACK. |
| HY013 | Błąd zarządzania pamięcią | Nie można przetworzyć wywołania funkcji, ponieważ nie można uzyskać dostępu do bazowych obiektów pamięci, prawdopodobnie z powodu niskich warunków pamięci. |
| HY092 | Nieprawidłowy identyfikator atrybutu/opcji | (DM) Wartość podana dla argumentu HandleType nie była ani SQL_HANDLE_ENV, ani SQL_HANDLE_DBC. |
| HY115 | SQLEndTran nie jest dozwolony w środowisku zawierającym połączenie z włączonym asynchronicznym wykonywaniem funkcji | (DM) HandleType nie może być ustawiony na SQL_HANDLE_ENV, jeśli asynchroniczne wykonywanie funkcji połączenia jest włączone dla połączenia w środowisku. |
| HY117 | Połączenie jest zawieszone z powodu nieznanego stanu transakcji. Dozwolone są tylko funkcje rozłączania i tylko do odczytu. | (DM) Więcej informacji o stanie zawieszonego można znaleźć w sekcji Komentarze w tym temacie. |
| HYC00 | Opcjonalna funkcja nie zaimplementowana | Sterownik lub źródło danych nie obsługuje operacji ROLLBACK . |
| HYT01 | Upłynął limit czasu połączenia | Okres przekroczenia limitu czasu połączenia wygasł, zanim źródło danych odpowiedziało na żądanie. Limit czasu połączenia jest ustawiany za pomocą parametru SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Sterownik nie obsługuje tej funkcji | (DM) Sterownik powiązany z ConnectionHandle nie obsługuje tej funkcji. |
| IM017 | Sondowanie jest wyłączone w trybie powiadomień asynchronicznych | Za każdym razem, gdy jest używany model powiadomień, sondowanie jest wyłączone. |
| IM018 | Funkcja SQLCompleteAsync nie została wywołana w celu ukończenia poprzedniej operacji asynchronicznej na tym dojściu. | Jeśli poprzednie wywołanie funkcji na dojściu zwraca SQL_STILL_EXECUTING i jeśli tryb powiadomień jest włączony, narzędzie SQLCompleteAsync musi być wywoływane na dojściu, aby wykonać przetwarzanie końcowe i zakończyć operację. |
Comments
Dla ODBC 3. x sterownik, jeśli HandleType jest SQL_HANDLE_ENV a Handle jest poprawnym handlem środowiskowym, Driver Manager wywoła SQLEndTran w każdym sterowniku powiązanym ze środowiskiem. Argument Handle dla wywołania do kierowcy będzie handlem środowiskowym kierowcy. Dla ODBC 2. x sterownik, jeśli HandleType jest SQL_HANDLE_ENV a Handle jest poprawnym handlem środowiskowym, a w tym środowisku jest wiele połączeń w stanie połączonym, to Driver Manager wywoła SQLTransact w sterowniku raz dla każdego połączenia w stanie połączonym w tym środowisku. Argument Handle w każdym połączeniu będzie handlem połączenia. W obu przypadkach sterownik będzie próbował zatwierdzić lub cofnąć transakcje, w zależności od wartości CompletionType, na wszystkich połączeniach będących w stanie połączonym w tym środowisku. Połączenia, które nie są aktywne, nie wpływają na transakcję.
Note
SQLEndTran nie może być używany do zatwierdzania lub cofania transakcji w środowisku współdzielonym. SQLSTATE HY092 (Nieprawidłowy identyfikator atrybutu/opcji) zostanie zwrócony, jeśli SQLEndTran zostanie wywołany z uchwytem Handle ustawionym na uchwyt środowiska współdzielonego lub uchwyt połączenia w środowisku współdzielonym.
Driver Manager zwraca SQL_SUCCESS tylko wtedy, gdy otrzymuje SQL_SUCCESS dla każdego połączenia. Jeśli Driver Manager otrzyma SQL_ERROR na jednym lub więcej połączeniach, zwraca SQL_ERROR do aplikacji, a informacje diagnostyczne są umieszczane w diagnosticznej strukturze danych środowiska. Aby ustalić, które połączenie lub połączenia zawiodły podczas operacji commit lub cofnięcia, aplikacja może wywołać SQLGetDiagRec dla każdego połączenia.
Note
Driver Manager nie symuluje globalnej transakcji przez wszystkie połączenia i dlatego nie używa protokołów dwufazowych zatwierdzeń.
Jeśli CompletionType jest SQL_COMMIT, SQLEndTran wysyła zatwierdzenie wszystkich aktywnych operacji na dowolnym kontucie powiązanym z dotkniętym połączeniem. Jeśli CompletionType jest SQL_ROLLBACK, SQLEndTran wysyła żądanie cofnięcia wszystkich aktywnych operacji na dowolnym kontucie powiązanym z dotkniętym połączeniem. Jeśli nie ma aktywnych transakcji, SQLEndTran zwraca SQL_SUCCESS bez wpływu na żadne źródła danych. Więcej informacji można znaleźć w artykule Committing and Rolling Backs Transactions.
Jeśli sterownik jest w trybie ręcznego zatwierdzania (wywołując SQLSetConnectAttr z atrybutem SQL_ATTR_AUTOCOMMIT ustawionym na SQL_AUTOCOMMIT_OFF), nowa transakcja jest niejawnie rozpoczynana, gdy wykonanie jest polecenia SQL zawarte w transakcji nad aktualnym źródłem danych. Więcej informacji można znaleźć w Trybie Commit.
Aby określić, jak operacje transakcyjne wpływają na kursory, aplikacja wywołuje SQLGetInfo z opcjami SQL_CURSOR_ROLLBACK_BEHAVIOR i SQL_CURSOR_COMMIT_BEHAVIOR. Więcej informacji można znaleźć w poniższych akapitach, a także w Wpływ transakcji na kursory i przygotowane wyciągi.
Jeśli wartość SQL_CURSOR_ROLLBACK_BEHAVIOR lub SQL_CURSOR_COMMIT_BEHAVIOR jest równa SQL_CB_DELETE, SQLEndTran zamyka i usuwa wszystkie otwarte kursory we wszystkich instrukcjach powiązanych z połączeniem oraz odrzuca wszystkie oczekujące wyniki. SQLEndTran pozostawia każde zdanie obecne w przydzielonym (nieprzygotowanym) stanie; aplikacja może je ponownie wykorzystać do kolejnych żądań SQL lub wywołać SQLFreeStmt lub SQLFreeHandle z HandleType SQL_HANDLE_STMT w celu ich deallokacji.
Jeśli wartość SQL_CURSOR_ROLLBACK_BEHAVIOR lub SQL_CURSOR_COMMIT_BEHAVIOR jest równa SQL_CB_CLOSE, SQLEndTran zamyka wszystkie otwarte kursory na wszystkich instrukcjach powiązanych z połączeniem. SQLEndTran pozostawia każde obecne zdanie w stanie przygotowanym; aplikacja może wywołać SQLExecute dla instrukcji powiązanej z połączeniem bez wcześniejszego wywoływania SQLPrepare.
Jeśli wartość SQL_CURSOR_ROLLBACK_BEHAVIOR lub SQL_CURSOR_COMMIT_BEHAVIOR jest równa SQL_CB_PRESERVE, SQLEndTran nie wpływa na otwarte kursory powiązane z połączeniem. Kursory pozostają w wierszu, na który wskazywały przed wywołaniem do SQLEndTran.
W przypadku sterowników i źródeł danych obsługujących transakcje, wywołanie SQLEndTran z SQL_COMMIT lub SQL_ROLLBACK, gdy żadna transakcja nie jest aktywna, zwraca SQL_SUCCESS (co oznacza, że nie ma pracy do zatwierdzenia ani cofnięcia) i nie wpływa na źródło danych.
Gdy sterownik jest w trybie automatycznego zatwierdzania, Menedżer Sterowników nie wywołuje SQLEndTran w sterowniku. SQLEndTran zawsze zwraca SQL_SUCCESS niezależnie od tego, czy jest wywołany za pomocą CompletionType SQL_COMMIT czy SQL_ROLLBACK.
Sterowniki lub źródła danych, które nie obsługują transakcji (opcjaSQLGetInfo SQL_TXN_CAPABLE jest SQL_TC_NONE), są w praktyce zawsze w trybie automatycznego zatwierdzania i dlatego zawsze zwracają SQL_SUCCESS dla SQLEndTran, niezależnie od tego, czy są wywoływane z CompletionType SQL_COMMIT czy SQL_ROLLBACK. Takie sterowniki i źródła danych nie cofają transakcji na żądanie.
Zawieszony stan
W Menedżerach sterowników wydanych przed Windows 7 transakcja była aktywna, jeśli SQLEndTran zwracał SQL_ERROR z sterownika. Jednak możliwe było, że transakcja została pomyślnie zatwierdzona na serwerze, ale sterownik na kliencie nie został powiadomiony (na przykład z powodu błędu sieciowego). To pozostawiłoby połączenie w złym stanie. Zaczynając od Windows 7, gdy SQLEndTran zwraca SQL_ERROR, połączenie może być zawieszone. W stanie zawieszenia możliwe jest wywoływanie funkcji tylko do odczytu. Ostatecznie aplikacja powinna wywołać SQLDisconnect na zawieszonym połączeniu, aby uwolnić zasoby.
Jeśli spełnione są wszystkie następujące warunki, połączenie zostanie przeniesione w stan zawieszenia:
Sterownik zwraca SQL_ERROR z SQLEndTran.
Sterownik to wersja ODBC 3.8 lub nowsza.
Wersja aplikacji to 3.8 lub nowsza; lub ponownie skompilowana aplikacja ODBC 2.x lub 3.x skutecznie anuluje funkcję SQLEndTran za pomocą SQLCancelHandle.
Sterownik nie zwrócił żadnej z następujących wiadomości, które potwierdzają, że transakcja nie została ukończona:
25S03: Transakcja zostaje cofnięta
40001: Niepowodzenie serializacji
40002: Ograniczenie integralności
HYC00: Funkcja opcjonalna niezaimplementowana
Jeśli SQLEndTran został wywołany na handle środowiska i jedno z jego połączeń spełniło powyższe warunki, wszystkie połączenia łączące się z tym samym sterownikiem zostaną przeniesione w stan zawieszenia.
Po wywołaniu połączenia SQLDisconnect przez aplikację, połączenie to może zostać użyte do ponownego połączenia z innym źródłem danych lub tym samym źródłem danych.
Powiązane funkcje
| Aby uzyskać informacje o | Zobacz |
|---|---|
| Anulowanie funkcji działającej asynchronicznie na uchwytie połączenia. | Funkcja SQLCancelHandle |
| Zwracanie informacji o sterowniku lub źródle danych | Funkcja SQLGetInfo |
| Uwalnianie uchwytu | Funkcja SQLFreeHandle |
| Uwalnianie uchwytu instrukcji | SQLFreeStmt, funkcja |