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
SQLFetchScroll pobiera określony zestaw wierszy danych ze zbioru wyników i zwraca dane dla wszystkich kolumn powiązanych. Wiersze mogą być określone w pozycji absolutnej lub względnej albo za pomocą zakładki.
Podczas pracy z sterownikiem ODBC 2.x, Driver Manager mapuje tę funkcję na SQLExtendedFetch. Więcej informacji można znaleźć w artykule Mapping Replacement Functions for Backward Compatibility of Applications.
Syntax
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
Arguments
StatementHandle
[Dane wejściowe] Uchwyt instrukcji.
FetchOrientation
[Input]
Rodzaj fetchu:
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
SQL_FETCH_RELATIVE
SQL_FETCH_BOOKMARK
Więcej informacji można znaleźć w sekcji "Ustawianie kursora" w sekcji "Komentarze".
FetchOffset
[Input]
Numer rzędu do pobrania. Interpretacja tego argumentu zależy od wartości argumentu FetchOrientation . Więcej informacji można znaleźć w sekcji "Ustawianie kursora" w sekcji "Komentarze".
Zwroty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR lub SQL_INVALID_HANDLE.
Diagnostyka
Gdy SQLFetchScroll zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT oraz Handle StatementHandle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLFetchScroll 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. Jeśli błąd wystąpi na jednej kolumnie, SQLGetDiagField można wywołać za pomocą DiagIdentifier SQL_DIAG_COLUMN_NUMBER, aby określić, na której kolumnie wystąpił błąd; a SQLGetDiagField można wywołać za pomocą DiagIdentifier SQL_DIAG_ROW_NUMBER, aby określić wiersz zawierający tę kolumnę.
Dla wszystkich stanów SQL, które mogą zwracać SQL_SUCCESS_WITH_INFO lub SQL_ERROR (z wyjątkiem 01xxx SQLSTATE), SQL_SUCCESS_WITH_INFO zwracany, jeśli błąd wystąpi na jednym lub więcej, ale nie we wszystkich wierszach operacji wielowierszowej, a SQL_ERROR zwracany, jeśli błąd wystąpi w operacji pojedynczej wierszowej.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Ostrzeżenie ogólne | Komunikat informacyjny specyficzny dla sterownika. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 01004 | Dane ciągów, prawe obcięte | Dane ciągowe lub binarne zwracane dla kolumny powodowały obcięcie znaków niepustych lub nie-NULL danych binarnych. Jeśli była to wartość ciągu, została ona obcięta prawym przyciskiem. |
| 01S01 | Błąd w wierszu | Podczas pobierania jednego lub więcej wierszy wystąpił błąd. (Jeśli ten SQLSTATE jest zwracany, gdy aplikacja ODBC 3*.x* pracuje z driverem ODBC 2*.x*, można go zignorować.) |
| 01S06 | Próba pobrania przed zestawem wyników zwraca pierwszy zestaw wierszy | Żądany zestaw wierszy nakładał się na początek zbioru wyników, gdy FetchOrientation było SQL_FETCH_PRIOR, aktualna pozycja znajdowała się poza pierwszym wierszem, a liczba aktualnego wiersza była mniejsza lub równa rozmiarowi zestawu wierszowego. Żądany zestaw wierszy nakładał się na początek zbioru wyników, gdy FetchOrientation było SQL_FETCH_PRIOR, aktualna pozycja znajdowała się poza końcem zbioru wyników, a rozmiar wiersza był większy niż rozmiar zbioru wyników. Żądany zestaw wierszy nakładał się na początek zbioru wyników, gdy FetchOrientation było SQL_FETCH_RELATIVE, FetchOffset było ujemne, a wartość bezwzględna FetchOffset była mniejsza lub równa rozmiarowi wiersza. Żądany zestaw wierszy nakładał się na początek zbioru wyników, gdy FetchOrientation było SQL_FETCH_ABSOLUTE, FetchOffset było ujemne, a wartość bezwzględna FetchOffset była większa niż rozmiar zbioru wyników, ale mniejsza lub równa rozmiarowi zbioru wierszowego. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 01S07 | Obcięcie ułamkowe | Dane zwracane dla kolumny były obcinane. Dla typów danych numerycznych część ułamkowa była obcięta. Dla typów danych czasowych, znaczników czasowych i interwałowych zawierających skład czasowy, część ułamkowa tego czasu była obcięta. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 07006 | Naruszenie atrybutu typu danych z ograniczeniami | Wartość danych kolumny w zbiorze wyników nie mogła zostać przekonwertowana na typ danych określony przez TargetType w SQLBindCol. Kolumna 0 była powiązana z typem danych SQL_C_BOOKMARK, a atrybut SQL_ATTR_USE_BOOKMARKS instrukcji ustawiono na SQL_UB_VARIABLE. Kolumna 0 była powiązana z typem danych SQL_C_VARBOOKMARK, a atrybut SQL_ATTR_USE_BOOKMARKS instrukcji nie był ustawiony na SQL_UB_VARIABLE. |
| 07009 | Nieprawidłowy indeks deskryptorów | Sterownik był sterownikiem ODBC 2*.x*, który nie obsługuje SQLExtendedFetch, a numer kolumny określony w przypisaniu kolumny wynosił 0. Kolumna 0 była powiązana, a atrybut SQL_ATTR_USE_BOOKMARKS instrukcji ustawiono na SQL_UB_OFF. |
| 08S01 | Błąd połączenia komunikacyjnego | Połączenie komunikacyjne między sterownikiem a źródłem danych, z którym sterownik został połączony, nie powiodło się przed zakończeniem przetwarzania funkcji. |
| 22001 | Dane ciągów, prawe obcięte | Zakładka o zmiennej długości zwracana dla kolumny była obcięta. |
| 22002 | Zmienna wskaźnika jest wymagana, ale nie jest podana | Dane NULL były pobierane do kolumny, której StrLen_or_IndPtr ustalany przez SQLBindCol (lub SQL_DESC_INDICATOR_PTR przez SQLSetDescField lub SQLSetDescRec) był wskaźnikiem null. |
| 22003 | Wartość liczbowa poza zakresem | Zwracanie wartości liczbowej (jako liczbowej lub ciągowej) dla jednej lub więcej kolumn wiązanych powodowałoby obcięcie całej (w przeciwieństwie do ułamkowej) części liczby. Więcej informacji można znaleźć w artykule Konwersja danych z SQL do C typów danych w Załączniku D: Typy danych. |
| 22007 | Nieprawidłowy format daty/godziny | Kolumna znaków w zestawie wyników była przypisana do struktury daty, godziny lub znacznika czasu C, a wartość w kolumnie była odpowiednio nieprawidłową datą, godziną lub znacznikiem czasu. |
| 22012 | Dzielenie według zera | Zwracano wartość z wyrażenia arytmetycznego, co skutkowało dzieleniem przez zero. |
| 22015 | Przepełnienie pola interwału | Przypisanie z dokładnego numerycznego lub przedziałowego typu SQL do typu przedziału C powodowało utratę istotnych cyfr w polu wiodącym. Podczas pobierania danych do typu przedziału C nie było reprezentacji wartości typu SQL w typie przedziału C. |
| 22018 | Nieprawidłowa wartość znaku dla specyfikacji rzutu | Kolumna znaków w zbiorze wyników była przypisana do bufora znaków C, a kolumna zawierała znak, którego nie było reprezentacji w zbiorze znaków bufora. Typ C był dokładnym lub przybliżonym numerem, datą lub typem danych interwałowych; typ SQL kolumny był typem danych znaków; a wartość w kolumnie nie była prawidłowym literalem typu C z wiązaniem. |
| 24000 | Nieprawidłowy stan kursora | CommandHandle był w stanie wykonania, ale żaden zestaw wyników nie był powiązany z StatementHandle. |
| 40001 | Niepowodzenie serializacji | Transakcja, w której wykonano fetch, została zakończona, aby zapobiec impasowi. |
| 40003 | Ukończenie instrukcji nieznane | Skojarzone połączenie nie powiodło się podczas wykonywania tej funkcji, a nie można określić stanu transakcji. |
| 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 zwrócony przez element SQLGetDiagRec w buforze *MessageText 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 instrukcji StatementHandle. Wywołano funkcję , a przed zakończeniem wykonywania wywołano metodę SQLCancel lub SQLCancelHandle w obiekcie StatementHandle. Następnie funkcja została ponownie wywołana w instrukcji StatementHandle. Wywołano funkcję , a przed zakończeniem wykonywania wywołano funkcję SQLCancel lub SQLCancelHandle na instrukcjiHandle z innego wątku w aplikacji wielowątku. |
| HY010 | Błąd sekwencji funkcji | (DM) Asynchronicznie wykonywana funkcja została wywołana dla dojścia połączenia skojarzonego z instrukcją StatementHandle. Ta asynchroniczna funkcja nadal działała, gdy wywoływano funkcję SQLFetchScroll . (DM) SqlExecute, SQLExecDirect lub SQLMoreResults została wywołana dla instrukcji StatementHandle i zwrócona SQL_PARAM_DATA_AVAILABLE. Ta funkcja została wywołana przed pobraniem danych dla wszystkich parametrów przesyłanych strumieniowo. (DM) Określony CommandHandle nie był w stanie wykonania. Funkcja była wywoływana bez wcześniejszego wywoływania SQLExecDirect, SQLExecute lub funkcji katalogowej. (DM) Asynchronicznie wykonująca funkcję (a nie tę) została wywołana dla instrukcji StatementHandle i nadal była wykonywana, gdy ta funkcja została wywołana. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations lub SQLSetPos został wywołany dla instrukcjiHandle i zwrócił SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn. (DM) SQLFetch był wywoływany dla StatementHandle po wywołaniu SQLExtendedFetch i przed wywołaniem SQLFreeStmt z opcją SQL_CLOSE. |
| 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. |
| HY090 | Nieprawidłowa długość ciągu lub buforu | Atrybut SQL_ATTR_USE_BOOKMARK instrukcji został ustawiony na SQL_UB_VARIABLE, a kolumna 0 była przypisana do bufora, którego długość nie była równa maksymalnej długości zakładki dla tego zbioru wyników. (Ta długość jest dostępna w polu SQL_DESC_OCTET_LENGTH IRD i można ją uzyskać, wywołując SQLDescribeCol, SQLColAttribute lub SQLGetDescField.) |
| HY106 | Typ aportowania poza zasięgiem | DM) Wartość podana dla argumentu FetchOrientation była nieprawidłowa. (DM) Argument FetchOrientation był SQL_FETCH_BOOKMARK, a atrybut SQL_ATTR_USE_BOOKMARKS instrukcji ustawiono na SQL_UB_OFF. Wartość atrybutu SQL_ATTR_CURSOR_TYPE instrukcji wynosiła SQL_CURSOR_FORWARD_ONLY, a wartość argumentu FetchOrientation nie była SQL_FETCH_NEXT. Wartość atrybutu SQL_ATTR_CURSOR_SCROLLABLE wynosiła SQL_NONSCROLLABLE, a wartość argumentu FetchOrientation nie była SQL_FETCH_NEXT. |
| HY107 | Wartość wiersza poza zakresem | Wartość podawana przez atrybut SQL_ATTR_CURSOR_TYPE instrukcji była SQL_CURSOR_KEYSET_DRIVEN, ale wartość podawana przez atrybut SQL_ATTR_KEYSET_SIZE była większa niż 0 i mniejsza niż wartość podana przez atrybut SQL_ATTR_ROW_ARRAY_SIZE. |
| HY111 | Nieprawidłowa wartość zakładek | Argument FetchOrientation był SQL_FETCH_BOOKMARK, a zakładka wskazana przez wartość w atributie SQL_ATTR_FETCH_BOOKMARK_PTR instrukcji była niepoprawna lub stanowiła wskaźnik zerowy. |
| HY117 | Połączenie jest zawieszone z powodu nieznanego stanu transakcji. Dozwolone są tylko funkcje rozłączania i tylko do odczytu. | (DM) Aby uzyskać więcej informacji na temat stanu wstrzymania, zobacz SQLEndTran, funkcja. |
| HYC00 | Opcjonalna funkcja nie zaimplementowana | Sterownik lub źródło danych nie obsługuje konwersji określonej przez połączenie TargetType w SQLBindCol oraz typu danych SQL odpowiadającej kolumny. |
| HYT00 | Upłynął limit czasu | Okres przekroczenia limitu czasu zapytania wygasł, zanim źródło danych zwróciło żądany zestaw wyników. Okres przekroczenia czasu jest ustalany przez SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 skojarzony z instrukcją StatementHandle nie obsługuje 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
SQLFetchScroll zwraca określony zestaw wierszy z tego zbioru wyników. Wiersze mogą być określone przez pozycję bezwzględną lub bezwzględną, albo zakładkę. SQLFetchScroll można wywołać tylko wtedy, gdy istnieje zbiór wyników – czyli po wywołaniu tworzącym zbiór wyników i przed zamknięciem kursora nad tym zbiorem. Jeśli jakiekolwiek kolumny są powiązane, zwraca dane z tych kolumn. Jeśli aplikacja określiła wskaźnik do tablicy statusów wiersza lub bufora, do którego zwraca liczbę pobranych wierszy, SQLFetchScroll zwraca również tę informację. Wywołania do SQLFetchScroll mogą być mieszane z wywołaniami do SQLFetch , ale nie mogą być mieszane z wywołaniami do SQLExtendedFetch.
Więcej informacji można znaleźć w artykule Używanie kursorów blokowych oraz Używanie przewijanych kursorów.
Ustawianie kursora
Po utworzeniu zbioru wyników kursor jest umieszczony przed początkiem zbioru wyników. SQLFetchScroll pozycjonuje kursor bloku na podstawie wartości argumentów FetchOrientation i FetchOffset , jak pokazano w poniższej tabeli. Dokładne zasady określania początku nowego zestawu wierszy przedstawiono w następnej sekcji.
| FetchOrientation | Meaning |
|---|---|
| SQL_FETCH_NEXT | Zwróć następny zestaw wierszy. To jest równoważne z wywoływaniem SQLFetch. SQLFetchScroll ignoruje wartość FetchOffset. |
| SQL_FETCH_PRIOR | Zwróć poprzedni zestaw wierszy. SQLFetchScroll ignoruje wartość FetchOffset. |
| SQL_FETCH_RELATIVE | Zwróć zestaw wierszy FetchOffset od początku bieżącego zbioru wierszów. |
| SQL_FETCH_ABSOLUTE | Zwróć zestaw wierszy zaczynający od wiersza FetchOffset. |
| SQL_FETCH_FIRST | Zwróć pierwszy zestaw wierszy w zbiorze wyników. SQLFetchScroll ignoruje wartość FetchOffset. |
| SQL_FETCH_LAST | Zwróć ostatni kompletny zestaw wierszy w zbiorze wyników. SQLFetchScroll ignoruje wartość FetchOffset. |
| SQL_FETCH_BOOKMARK | Zwróć wiersze FetchOffset z zakładki określonej przez atrybut SQL_ATTR_FETCH_BOOKMARK_PTR. |
Sterowniki nie muszą obsługiwać wszystkich orientacji pobierania; aplikacja wywołuje SQLGetInfo za pomocą typu informacji SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 lub SQL_STATIC_CURSOR_ATTRIBUTES1 (w zależności od typu kursora), aby określić, które orientacje pobierania są obsługiwane przez sterownik. Aplikacja powinna analizować SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE i WQL_CA1_BOOKMARK bitmaski w tych typach informacji. Ponadto, jeśli kursor jest tylko do przodu, a FetchOrientation nie jest SQL_FETCH_NEXT, SQLFetchScroll zwraca SQLSTATE HY106 (Fetch type poza zakresem).
Atrybut SQL_ATTR_ROW_ARRAY_SIZE określa liczbę wierszy w zestawie wierszy. Jeśli zestaw wierszy pobierany przez SQLFetchScroll nakłada się na koniec zbioru wyników, SQLFetchScroll zwraca częściowy zestaw wierszy. To znaczy, jeśli S + R - 1 jest większe niż L, gdzie S to wiersz początkowy pobieranego zbioru, R to rozmiar zbioru wierszowego, a L to ostatni wiersz w zbiorze wyników, to tylko pierwsze wiersze L - S + 1 są prawidłowe. Pozostałe wiersze są puste i mają status SQL_ROW_NOROW.
Po powrocie SQLFetchScroll , aktualny wiersz jest pierwszym wierszem zestawu wierszy.
Zasady pozycjonowania kursora
Poniższe sekcje opisują dokładne reguły dla każdej wartości FetchOrientation. Zasady te wykorzystują następującą notację.
| Notation | Meaning |
|---|---|
| Przed rozpoczęciem | Kursor blokowy jest umieszczony przed początkiem zbioru wyników. Jeśli pierwszy wiersz nowego zestawu wierszy znajduje się przed początkiem zbioru wyników, SQLFetchScroll zwraca SQL_NO_DATA. |
| Po zakończeniu | Kursor blokowy jest umieszczony po końcu zbioru wyników. Jeśli pierwszy wiersz nowego zestawu wierszy znajduje się po końcu zbioru wyników, SQLFetchScroll zwraca SQL_NO_DATA. |
| CurrRowsetStart | Numer pierwszego wiersza w aktualnym zestawie wierszy. |
| OstatniWiersz Rezultatu | Liczba ostatniego wiersza w zbiorze wyników. |
| RowsetSize | Rozmiar rzędu. |
| FetchOffset | Wartość argumentu FetchOffset . |
| BookmarkRow | Wiersz odpowiadający zakładce określonej przez atrybut SQL_ATTR_FETCH_BOOKMARK_PTR polecenia. |
SQL_FETCH_NEXT
Obowiązują następujące zasady.
| Warunek | Pierwszy rząd nowego zestawu wierszy |
|---|---|
| Przed rozpoczęciem | 1 |
| CurrRowsetStart + RowsetSize[1] <= OstatniWiersz Rezultatu | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | Po zakończeniu |
| Po zakończeniu | Po zakończeniu |
[1] Jeśli rozmiar wiersza został zmieniony od poprzedniego wywołania pobierania wierszy, jest to rozmiar wiersza użyty przy poprzednim wywołaniu.
SQL_FETCH_PRIOR
Obowiązują następujące zasady.
| Warunek | Pierwszy rząd nowego zestawu wierszy |
|---|---|
| Przed rozpoczęciem | Przed rozpoczęciem |
| CurrRowsetStart = 1 | Przed rozpoczęciem |
| 1 < CurrRowsetStart <= RowsetSize[2] | 1[1] |
| CurrRowsetStart > RowsetSize[2] | CurrRowsetStart - RowsetSize[2] |
| Po zakończeniu ORAZ OstatnimRzędzie < Rezultatowym RowsetSize[2] | 1[1] |
| Po końcu AND LastResultRow >= RowsetSize[2] | LastResultRow - RowsetSize + 1[2] |
[1] SQLFetchScroll zwraca SQLSTATE 01S06 (Próba pobrania przed zwróceniem pierwszego zestawu wiersza) i SQL_SUCCESS_WITH_INFO.
[2] Jeśli rozmiar wiersza został zmieniony od poprzedniego wywołania pobierania wierszy, jest to nowy rozmiar wiersza.
SQL_FETCH_RELATIVE
Obowiązują następujące zasady.
| Warunek | Pierwszy rząd nowego zestawu wierszy |
|---|---|
| (Przed startem AND FetchOffset > 0) LUB (Po end AND FetchOffset < 0) | -- [1] |
| Przedstartować AND FetchOffset <= 0 | Przed rozpoczęciem |
| CurrRowsetStart = 1 AND FetchOffset < 0 | Przed rozpoczęciem |
| CurrRowsetStart > 1 I CurrRowsetStart + FetchOffset < 1 ORAZ | FetchOffset | > RowsetSize[3] | Przed rozpoczęciem |
| CurrRowsetStart > 1 I CurrRowsetStart + FetchOffset < 1 ORAZ | FetchOffset | <= RowsetSize[3] | 1[2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | Po zakończeniu |
| Po końcu AND FetchOffset >= 0 | Po zakończeniu |
[1] SQLFetchScroll zwraca ten sam zestaw wierszy, jakby był wywołany z FetchOrientation ustawionym na SQL_FETCH_ABSOLUTE. Więcej informacji można znaleźć w sekcji "SQL_FETCH_ABSOLUTE".
[2] SQLFetchScroll zwraca SQLSTATE 01S06 (Próba pobrania przed zwróceniem pierwszego zestawu wiersza) i SQL_SUCCESS_WITH_INFO.
[3] Jeśli rozmiar wiersza został zmieniony od poprzedniego wywołania pobierania wierszy, jest to nowy rozmiar wiersza.
SQL_FETCH_ABSOLUTE
Obowiązują następujące zasady.
| Warunek | Pierwszy rząd nowego zestawu wierszy |
|---|---|
| FetchOffset < 0 And | FetchOffset | <= OstatniWiersz Rezultatu | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 And | FetchOffset | > OstatniWierszRezultatI | FetchOffset | > RowsetSize[2] | Przed rozpoczęciem |
| FetchOffset < 0 And | FetchOffset | > OstatniWierszRezultatI | FetchOffset | <= RowsetSize[2] | 1[1] |
| FetchOffset = 0 | Przed rozpoczęciem |
| 1 <= FetchOffset <= OstatniWiersz Rezultatu | FetchOffset |
| FetchOffset > LastResultRow | Po zakończeniu |
[1] SQLFetchScroll zwraca SQLSTATE 01S06 (Próba pobrania przed zwróceniem pierwszego zestawu wiersza) i SQL_SUCCESS_WITH_INFO.
[2] Jeśli rozmiar wiersza został zmieniony od poprzedniego wywołania pobierania wierszy, jest to nowy rozmiar wiersza.
Absolutne pobieranie wykonane na dynamicznym kursorze nie może dać wymaganego wyniku, ponieważ pozycje wierszy w dynamicznym kursorze są nieokreślone. Taka operacja jest równoważna najpierw pobieraniu, a następnie relatywowi pobierania; nie jest to operacja atomowa, jak absolutne pobieranie kursora statycznego.
SQL_FETCH_FIRST
Obowiązują następujące zasady.
| Warunek | Pierwszy rząd nowego zestawu wierszy |
|---|---|
| Dowolne | 1 |
SQL_FETCH_LAST
Obowiązują następujące zasady.
| Warunek | Pierwszy rząd nowego zestawu wierszy |
|---|---|
| RowsetSize[1]=< LastResultRow | LastResultRow - RowsetSize + 1[1] |
| RowsetSize[1]> LastResultRowRow | 1 |
[1] Jeśli rozmiar zbioru wierszy został zmieniony od poprzedniego wywołania pobierania wierszy, to jest to nowy rozmiar wiersza.
SQL_FETCH_BOOKMARK
Obowiązują następujące zasady.
| Warunek | Pierwszy rząd nowego zestawu wierszy |
|---|---|
| BookmarkRow + FetchOffset < 1 | Przed rozpoczęciem |
| 1 <= Wiersz zakładek + RetchOffset <= OstatniWiersz wyniku. | BookmarkRow + FetchOffset |
| Wiersz zakładek + RetchOffset > OstatniWiersz wyników | Po zakończeniu |
Informacje o zakładkach można znaleźć w sekcji Zakładki (ODBC).
Wpływ usuniętych, dodanych i błędnych wierszy na ruch kursora
Statyczne i sterowane przez zestaw klawiszy kursory czasami wykrywają wiersze dodane do zbioru wyników i usuwają usunięte wiersze z tego zbioru. Wywołując SQLGetInfo z opcjami SQL_STATIC_CURSOR_ATTRIBUTES2 i SQL_KEYSET_CURSOR_ATTRIBUTES2 oraz patrząc na bitmaski SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS i SQL_CA2_SENSITIVITY_UPDATES, aplikacja ustala, czy kursory zaimplementowane przez dany sterownik robią takie rozwiązanie. Dla sterowników, które potrafią wykrywać usunięte wiersze i je usuwać, poniższe akapity opisują skutki tego zachowania. Dla sterowników, które wykrywają usunięte wiersze, ale nie mogą ich usunąć, usunięcie nie ma wpływu na ruchy kursora i poniższe akapity nie mają zastosowania.
Jeśli kursor wykryje wiersze dodane do zbioru wyników lub usunie usunięte wiersze z tego zbioru, wydaje się, że wykrywa te zmiany tylko podczas pobierania danych. Dotyczy to sytuacji, gdy SQLFetchScroll jest wywoływany z FetchOrientation ustawionym na SQL_FETCH_RELATIVE i FetchOffset na 0, aby ponownie pobrać ten sam zestaw wierszy, ale nie dotyczy sytuacji, gdy SQLSetPos jest wywoływany z fOption ustawionym na SQL_REFRESH. W tym drugim przypadku dane w buforach wierszy są odświeżane, ale nie pobierane ponownie, a usunięte wiersze nie są usuwane z zestawu wyników. W związku z tym, gdy wiersz zostanie usunięty lub wstawiony do bieżącego zbioru wierszy, kursor nie modyfikuje buforów wiersza. Zamiast tego wykrywa zmianę, gdy pobiera dowolny zestaw wierszy, który wcześniej zawierał usunięty wiersz lub teraz zawiera wstawiony wiersz.
Przykład:
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
Gdy SQLFetchScroll zwraca nowy zestaw wierszy, który ma pozycję względem obecnego zestawu wierszy – czyli FetchOrientation to SQL_FETCH_NEXT, SQL_FETCH_PRIOR lub SQL_FETCH_RELATIVE – nie uwzględnia zmian w bieżącym zestawie wierszy podczas obliczania pozycji początkowej nowego zbioru. Jednak obejmuje zmiany poza aktualnym zbiorem wierszy, jeśli jest w stanie je wykryć. Ponadto, gdy SQLFetchScroll zwraca nowy zestaw wierszy, którego pozycja jest niezależna od aktualnego zestawu wierszy – czyli FetchOrientation to SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE lub SQL_FETCH_BOOKMARK – obejmuje wszystkie zmiany, które jest w stanie wykryć, nawet jeśli znajdują się one w aktualnym zestawie wierszów.
Przy ustalaniu, czy nowo dodane wiersze znajdują się wewnątrz czy poza aktualnym zbiorem wierszów, częściowy zbiór wierszy uznaje się za kończący się na ostatnim prawidłowym wierszu; to znaczy ostatni wiersz, dla którego status wiersza nie jest SQL_ROW_NOROW. Na przykład, załóżmy, że kursor jest w stanie wykrywać nowo dodane wiersze, aktualny zestaw wierszy jest częściowy, aplikacja dodaje nowe wiersze, a kursor dodaje te wiersze na koniec zbioru wyników. Jeśli aplikacja wywoła SQLFetchScroll z ustawieniem FetchOrientation na SQL_FETCH_NEXT, SQLFetchScroll zwraca zestaw wierszy zaczynając od pierwszego nowo dodanego wiersza.
Na przykład, załóżmy, że obecny zestaw wierszy składa się z wierszy od 21 do 30, rozmiar zbioru wierszy wynosi 10, kursor usuwa usunięte wiersze z zbioru wyników, a kursor wykrywa wiersze dodane do zbioru wyników. Poniższa tabela pokazuje wiersze, które SQLFetchScroll zwraca w różnych sytuacjach.
| Zmiana | Typ pobierania | FetchOffset | Nowy zestaw wierszy[1] |
|---|---|---|---|
| Usuń wiersz 21 | DALEJ | 0 | 31 do 40 |
| Usuń wiersz 31 | DALEJ | 0 | 32 do 41 |
| Wstaw wiersz między wierszami 21 i 22 | DALEJ | 0 | 31 do 40 |
| Wstaw wiersz między rzędami 30 a 31 | DALEJ | 0 | Wstawiony wiersz, 31 do 39 |
| Usuń wiersz 21 | PRIOR | 0 | 11 do 20 |
| Usuń wiersz 20 | PRIOR | 0 | 10 do 19 |
| Wstaw wiersz między wierszami 21 i 22 | PRIOR | 0 | 11 do 20 |
| Wstaw wiersz między wierszami 20 i 21 | PRIOR | 0 | 12 do 20, wprowadzony wiersz |
| Usuń wiersz 21 | KREWNY | 0 | 22 do 31[2] |
| Usuń wiersz 21 | KREWNY | 1 | 22 do 31 |
| Wstaw wiersz między wierszami 21 i 22 | KREWNY | 0 | 21, wstawiony rząd, 22 do 29 |
| Wstaw wiersz między wierszami 21 i 22 | KREWNY | 1 | 22 do 31 |
| Usuń wiersz 21 | ABSOLUTE | 21 | 22 do 31[2] |
| Usuń wiersz 22 | ABSOLUTE | 21 | 21, 23 do 31 |
| Wstaw wiersz między wierszami 21 i 22 | ABSOLUTE | 22 | Wstawiony wiersz, 22 do 29 |
[1] Ta kolumna używa numerów wierszy przed wstawieniem lub usunięciem jakichkolwiek wierszy.
[2] W tym przypadku kursor próbuje zwracać wiersze zaczynające się od wiersza 21. Ponieważ wiersz 21 został usunięty, pierwszy wiersz, który zwraca, to wiersz 22.
Wiersze błędu (czyli wiersze o statusie SQL_ROW_ERROR) nie wpływają na ruch kursora. Na przykład, jeśli aktualny zestaw wierszy zaczyna się od wiersza 11, a status wiersza 11 to SQL_ROW_ERROR, wywołanie SQLFetchScroll z FetchOrientation ustawionym na SQL_FETCH_RELATIVE i FetchOffset na 5 zwraca zestaw wierszy zaczynający się od wiersza 16, tak jak gdyby status wiersza 11 był SQL_SUCCESS.
Zwracanie danych w kolumnach powiązanych
SQLFetchScroll zwraca dane w kolumnach powiązanych tak samo jak SQLFetch. Więcej informacji można znaleźć w sekcji "Zwracanie danych w powiązanych kolumnach" w funkcji SQLFetch.
Jeśli żadne kolumny nie są powiązane, SQLFetchScroll nie zwraca danych, ale przesuwa kursor bloku na wskazaną pozycję. To, czy dane można pobrać z kolumn niepowiązanych kursora blokowego za pomocą SQLGetData , zależy od sterownika. Ta funkcja jest obsługiwana, jeśli wywołanie do SQLGetInfo zwraca bit SQL_GD_BLOCK dla typu informacji SQL_GETDATA_EXTENSIONS.
Adresy buforów
SQLFetchScroll używa tego samego wzoru do określania adresu danych oraz buforów długości/wskaźników co SQLFetch. Więcej informacji można znaleźć w sekcji "Adresy buforów" w Funkcji SQLBindCol.
Tablica stanu wiersza
SQLFetchScroll ustawia wartości w tablicy statusu wiersza w taki sam sposób jak SQLFetch. Więcej informacji można znaleźć w sekcji "Row Status Array" w SQLFetch Function.
Bufor pobierany w wierszach
SQLFetchScroll zwraca liczbę wierszy pobranych w buforze pobranym wierszem w taki sam sposób jak SQLFetch. Więcej informacji można znaleźć w sekcji "Retched Buffer" w SQLFetch Function.
Obsługa błędów
Gdy aplikacja wywołuje SQLFetchScroll w sterowniku ODBC 3.x, Driver Manager wywołuje SQLFetchScroll w sterowniku. Gdy aplikacja wywołuje SQLFetchScroll w sterowniku ODBC 2.x, Driver Manager wywołuje SQLExtendedFetch w sterowniku. Ponieważ SQLFetchScroll i SQLExtendedFetch obsługują błędy nieco inaczej, aplikacja wykazuje nieco inne zachowanie błędów podczas wywoływania SQLFetchScroll w sterownikach ODBC 2.x i ODBC 3.x.
SQLFetchScroll zwraca błędy i ostrzeżenia w ten sam sposób co SQLFetch; więcej informacji można znaleźć w sekcji "Obsługa błędów" w SQLFetch. SQLExtendedFetch zwraca błędy w taki sam sposób jak SQLFetch, z następującymi wyjątkami:
Gdy pojawia się ostrzeżenie dotyczące konkretnego wiersza w wierszu, SQLExtendedFetch ustawia odpowiadający wpis w tablicy statusu wiersza na SQL_ROW_SUCCESS, a nie SQL_ROW_SUCCESS_WITH_INFO.
Jeśli błędy występują w każdym wierszu w zestawie wierszy, SQLExtendedFetch zwraca SQL_SUCCESS_WITH_INFO, a nie SQL_ERROR.
W każdej grupie rekordów statusu odnoszących się do pojedynczego wiersza, pierwszy rekord statusu zwracany przez SQLExtendedFetch musi zawierać SQLSTATE 01S01 (Błąd w wierszu); SQLFetchScroll nie zwraca tego stanu SQL. Jeśli SQLExtendedFetch nie jest w stanie zwrócić dodatkowych stanów SQL, nadal musi zwrócić ten stan.
SQLFetchScroll i optymistyczna współbieżność
Jeśli kursor używa optymistycznego współbieżności – czyli atrybut SQL_ATTR_CONCURRENCY ma wartość SQL_CONCUR_VALUES lub SQL_CONCUR_ROWVER – SQLFetchScroll aktualizuje optymistyczne wartości współbieżności używane przez źródło danych, aby wykryć, czy wiersz się zmienił. Dzieje się tak za każdym razem, gdy SQLFetchScroll pobiera nowy zestaw wierszy, w tym gdy pobiera aktualny zestaw wierszy. (Jest wywoływana z FetchOrientation ustawionym na SQL_FETCH_RELATIVE i FetchOffset na 0.)
Sterowniki SQLFetchScroll i ODBC 2.x
Gdy aplikacja wywołuje SQLFetchScroll w sterowniku ODBC 2.x, Driver Manager mapuje to wywołanie na SQLExtendedFetch. Przekazuje następujące wartości dla argumentów SQLExtendedFetch.
| SQLExtendedFetch argument | Wartość |
|---|---|
| StatementHandle | CommandHandle w SQLFetchScroll. |
| FetchOrientation | FetchOrientation w SQLFetchScroll. |
| FetchOffset | Jeśli FetchOrientation nie jest SQL_FETCH_BOOKMARK, używa się wartości argumentu FetchOffset w SQLFetchScroll . Jeśli FetchOrientation jest SQL_FETCH_BOOKMARK, używana jest wartość przechowywana pod adresem określonym przez atrybut SQL_ATTR_FETCH_BOOKMARK_PTR instrukcji. |
| RowCountPtr | Adres określony przez atrybut SQL_ATTR_ROWS_FETCHED_PTR instrukcji. |
| RowStatusArray | Adres określony przez atrybut SQL_ATTR_ROW_STATUS_PTR instrukcji. |
Aby uzyskać więcej informacji, zobacz Blokuj kursory, Kursory przewijania i Zgodność wsteczną w dodatku G: Wytyczne dla sterowników dotyczące zgodności wstecznej.
Deskryptory i SQLFetchScroll
SQLFetchScroll współpracuje z deskryptorami w ten sam sposób co SQLFetch. Więcej informacji można znaleźć w sekcji "Descriptors and SQLFetchScroll" w SQLFetch Function.
Przykład kodu
Zobacz Column-Wise binding, Row-Wise binding, pozycjonowane instrukcje update i delete oraz aktualizację wierszy w rowsetie za pomocą SQLSetPos.
Powiązane funkcje
| Aby uzyskać informacje o | Zobacz |
|---|---|
| Wiązanie buforu z kolumną w zestawie wyników | SQLBindCol, funkcja |
| Wykonywanie operacji wstawiania, aktualizacji lub usuwania masowego | Funkcja SQLBulkOperations |
| Anulowanie przetwarzania instrukcji | SQLCancel, funkcja |
| Zwracanie informacji o kolumnie w zbiorze wyników | SQLDescribeCol Function |
| Wykonywanie instrukcji SQL | Funkcja SQLExecDirect |
| Wykonywanie przygotowanej instrukcji SQL | SQLExecute, funkcja |
| Pobieranie pojedynczego wiersza lub bloku danych w kierunku tylko do przodu | SQLFetch, funkcja |
| Zamykanie kursora na zdaniu | SQLFreeStmt, funkcja |
| Zwracanie liczby kolumn zbioru wyników | Funkcja SQLNumResultCols |
| Ustawianie kursora, odświeżanie danych w zestawie wierszy lub aktualizacja bądź usuwanie danych w zbiorze wyników | Funkcja SQLSetPos |
| Ustawianie atrybutu instrukcji | SQLSetStmtAttr, funkcja |