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ść ze standardami ODBC 1.0: Wycofana
Podsumowanie
SQLExtendedFetch 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.
Note
W ODBC 3*.x* SQLExtendedFetch został zastąpiony przez SQLFetchScroll. Aplikacje ODBC 3*.x* nie powinny wywoływać SQLExtendedFetch; zamiast tego powinni wywołać SQLFetchScroll. Driver Manager mapuje SQLFetchScroll na SQLExtendedFetch podczas pracy z sterownikiem ODBC 2*.x*. Sterowniki ODBC 3*.x* powinny obsługiwać SQLExtendedFetch , jeśli chcą pracować z aplikacjami ODBC 2*.x*, które go wywołują. Więcej informacji można znaleźć w sekcji "Komentarze" i kursory bloków, kursory przewijane i kompatybilność wsteczna w Załączniku G: Wytyczne sterowników dotyczące kompatybilności wstecznej.
Syntax
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Arguments
StatementHandle
[Dane wejściowe] Uchwyt instrukcji.
FetchOrientation
[Input] Rodzaj aportu. To jest to samo co FetchOrientation w SQLFetchScroll.
FetchOffset
[Input] Numer rzędu do pobrania. To jest to samo co FetchOffset w SQLFetchScroll, z jednym wyjątkiem. Gdy FetchOrientation jest SQL_FETCH_BOOKMARK, FetchOffset jest zakładką o stałej długości, a nie przesunięciem od zakładki. Innymi słowy, SQLExtendedFetch pobiera zakładkę z tego argumentu, a nie atrybut SQL_ATTR_FETCH_BOOKMARK_PTR instrukcji. Nie obsługuje zakładek o zmiennej długości ani nie umożliwia pobierania wiersza z przesunięciem (innym niż 0) z zakładki.
RowCountPtr
[Wyjście] Wskaźnik do bufora, w którym zwraca liczbę faktycznie pobranych wierszy. Bufor ten jest używany w taki sam sposób jak bufor określony przez atrybut SQL_ATTR_ROWS_FETCHED_PTR instrukcji. Ten bufor jest używany wyłącznie przez SQLExtendedFetch. Nie jest używany przez SQLFetch ani SQLFetchScroll.
RowStatusArray
[Wyjście] Wskaż na tablicę, w której zwracasz status każdego wiersza. Ta tablica jest używana w taki sam sposób jak tablica określona przez atrybut SQL_ATTR_ROW_STATUS_PTR.
Jednak adres tej tablicy nie jest przechowywany w polu SQL_DESC_STATUS_ARRAY_PTR w IRD. Ponadto ta tablica jest używana wyłącznie przez SQLExtendedFetch oraz przez SQLBulkOperations z operacją SQL_ADD lub SQLSetPos , gdy jest wywołana po SQLExtendedFetch. Nie jest używany przez SQLFetch ani SQLFetchScroll, ani nie jest używany przez SQLBulkOperations czy SQLSetPos , gdy są wywoływane po SQLFetch lub SQLFetchScroll. Nie jest również używana, gdy SQLBulkOperations z operacją SQL_ADD jest wywoływana przed wywołaniem dowolnej funkcji pobierania. Innymi słowy, jest używany tylko w stanie zdania S7. Nie jest używany w stanach instrukcji S5 ani S6. Więcej informacji można znaleźć w artykule Przejść zdań w Załączniku B: Tabele Przejścia stanów ODBC.
Aplikacje powinny dostarczać prawidłowy wskaźnik w argumentze RowStatusArray ; jeśli nie, zachowanie SQLExtendedFetch oraz wywołań SQLBulkOperations lub SQLSetPos po ustawieniu kursora przez SQLExtendedFetch pozostają niezdefiniowane.
Zwroty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR lub SQL_INVALID_HANDLE.
Diagnostyka
Gdy SQLExtendedFetch zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLError. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLExtendedFetch 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, pole SQLGetDiagField można wywołać za pomocą DiagIdentifier SQL_DIAG_COLUMN_NUMBER, aby określić kolumnę, na której 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ę.
| 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. Jeśli była to wartość liczbowa, część ułamkowa liczby była skracana. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 01S01 | Błąd w wierszu | Podczas pobierania jednego lub więcej wierszy wystąpił błąd. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 01S06 | Próba pobrania przed zestawem wyników zwraca pierwszy zestaw wierszy | Żądany zestaw wierszy nakładał się na początek zestawu wyników, gdy aktualna pozycja znajdowała się poza pierwszym wierszem, a albo FetchOrientation było SQL_PRIOR, albo FetchOrientation było SQL_RELATIVE ujemnym FetchOffset , którego wartość bezwzględna była mniejsza lub równa aktualnemu SQL_ROWSET_SIZE. (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 nie mogła zostać przekonwertowana na typ danych C określony przez TargetType w SQLBindCol. |
| 07009 | Nieprawidłowy indeks deskryptorów | Kolumna 0 była powiązana z SQLBindCol, a atrybut SQL_ATTR_USE_BOOKMARKS pociągania 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. |
| 22002 | Zmienna wskaźnika jest wymagana, ale nie jest podana | Dane NULL były pobierane do kolumny, której StrLen_or_IndPtr ustawiony przez SQLBindCol był wskaźnikiem null. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 22003 | Wartość liczbowa poza zakresem | Zwracanie wartości liczbowej (jako numerycznej lub ciągowej) dla jednej lub więcej kolumn powodowałoby obcięcie całej (a nie ułamkowej) części liczby. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). Więcej informacji można znaleźć w artykule Wytyczne dotyczące typów danych interwałowych i numerycznych 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. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 22012 | Dzielenie według zera | Zwracano wartość z wyrażenia arytmetycznego, co skutkowało dzieleniem przez zero. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 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. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 22018 | Nieprawidłowa wartość znaku dla specyfikacji rzutu | 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. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 24000 | Nieprawidłowy stan kursora | CommandHandle był w stanie wykonania, ale żaden zestaw wyników nie był powiązany z StatementHandle. |
| 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 SQLError 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. Funkcja została wywołana, a przed zakończeniem wykonania wywołano SQLCancel lub SQLCancelHandle na CommandHandle, a następnie ponownie wywołało ją na CommandHandle. 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ę SQLExtendedFetch . (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łania 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) SQLExtendedFetch był wywoływany dla CommandHandle po wywołaniu SQLFetch lub SQLFetchScroll i przed wywołaniem SQLFreeStmt z opcją SQL_CLOSE. (DM) SQLBulkOperations był wywoływany jako polecenie przed wywołaniem SQLFetch, SQLFetchScroll lub SQLExtendedFetch , a następnie SQLExtendedFetch 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. |
| HY106 | Typ aportowania poza zasięgiem | (DM) Wartość podana dla argumentu FetchOrientation była nieprawidłowa. (Zobacz "Komentarze.") Argument FetchOrientation był SQL_FETCH_BOOKMARK, a atrybut SQL_ATTR_USE_BOOKMARKS instrukcji ustawiono na SQL_UB_OFF. Wartość opcji SQL_CURSOR_TYPE wynosiła SQL_CURSOR_FORWARD_ONLY, a wartość argumentu FetchOrientation nie była SQL_FETCH_NEXT. Argument FetchOrientation był SQL_FETCH_RESUME. |
| HY107 | Wartość wiersza poza zakresem | Wartość podawana opcją SQL_CURSOR_TYPE wynosiła SQL_CURSOR_KEYSET_DRIVEN, ale wartość podana przez atrybut SQL_KEYSET_SIZE była większa niż 0 i mniejsza niż wartość określona przez atrybut SQL_ROWSET_SIZE. |
| HY111 | Nieprawidłowa wartość zakładek | Argument FetchOrientation był SQL_FETCH_BOOKMARK, a zakładka wskazana w argumentze FetchOffset nie była prawidłowa. |
| 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 określonego typu pobierania. 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. Błąd ten występuje tylko wtedy, gdy typ danych SQL kolumny został przypisany do specyficznego dla sterownika typu danych SQL. |
| HYT00 | Upłynął limit czasu | Okres przekroczenia limitu czasu zapytania wygasł przed zwróceniem zestawu wyników przez źródło danych. Okres przekroczenia czasu jest ustalany przez SQLSetStmtOption SQL_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. |
Comments
Zachowanie SQLExtendedFetch jest identyczne jak w SQLFetchScroll, z następującymi wyjątkami:
SQLExtendedFetch i SQLFetchScroll używają różnych metod zwracania liczby pobranych wierszy. SQLExtendedFetch zwraca liczbę wierszy pobranych w *RowCountPtr; SQLFetchScroll zwraca liczbę wierszy pobranych bezpośrednio do bufora wskazanego przez SQL_ATTR_ROWS_FETCHED_PTR. Więcej informacji można znaleźć w argumentze RowCountPtr .
SQLExtendedFetch i SQLFetchScroll zwracają status każdego wiersza w różnych tablicach. Więcej informacji można znaleźć w argumentze RowStatusArray .
SQLExtendedFetch i SQLFetchScroll używają różnych metod pobierania zakładki, gdy FetchOrientation jest SQL_FETCH_BOOKMARK. SQLExtendedFetch nie obsługuje zakładek o zmiennej długości ani pobierania wierszy na przesunięciu innym niż 0 od zakładki. Więcej informacji można znaleźć w argumencie FetchOffset .
SQLExtendedFetch i SQLFetchScroll używają różnych rozmiarów wierszy. SQLExtendedFetch używa wartości atrybutu SQL_ROWSET_SIZE instrukcji, a SQLFetchScroll używa wartości atrybutu SQL_ATTR_ROW_ARRAY_SIZE polecenia.
SQLExtendedFetch ma nieco inną semantykę obsługi błędów niż SQLFetchScroll. Więcej informacji można znaleźć w sekcji "Obsługa błędów" w sekcji "Komentarze" na SQLFetchScroll.
SQLExtendedFetch nie obsługuje powiązania offsetów (atrybut SQL_ATTR_ROW_BIND_OFFSET_PTR instrukcji).
Wywołania SQLExtendedFetch nie mogą być mieszane z wywołaniami do SQLFetch lub SQLFetchScroll, a jeśli SQLBulkOperations zostanie wywołane przed wywołaniem jakiejkolwiek funkcji fetch, SQLExtendedFetch nie może być wywołany, dopóki kursor nie zostanie zamknięty i ponownie otwarty. To znaczy, że SQLExtendedFetch może być wywołany tylko w stanie instrukcji S7. Więcej informacji można znaleźć w artykule Przejść zdań w Załączniku B: Tabele Przejścia stanów ODBC.
Gdy aplikacja wywołuje SQLFetchScroll przy użyciu sterownika ODBC 2*.x*, Menedżer sterowników mapuje to wywołanie na SQLExtendedFetch. Więcej informacji można znaleźć w sekcji "SQLFetchScroll and ODBC 2*.x* Drivers" w SQLFetchScroll.
W ODBC 2*.x* SQLExtendedFetch był wywoływany do pobierania wielu wierszy, a SQLFetch do pobierania jednego wiersza. W ODBC 3*.x* natomiast SQLFetch może być wywołany, aby pobrać wiele wierszy.
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 |
| 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 |