Pobieranie wiersza danych

Aby pobrać wiersz danych, aplikacja wywołuje metodę SQLFetch. Funkcja SQLFetch może być wywoływana za pomocą dowolnego rodzaju kursora, ale przenosi tylko kursor zestawu wierszy w kierunku tylko do przodu. SQLFetch przemieszcza kursor do następnego wiersza i zwraca dane dla dowolnych kolumn powiązanych z wywołaniami SQLBindCol. Gdy kursor osiągnie koniec zestawu wyników, funkcja SQLFetch zwraca SQL_NO_DATA. Przykłady wywoływania metody SQLFetch można znaleźć w temacie Using SQLBindCol (Używanie metody SQLBindCol).

Dokładnie sposób implementacji funkcji SQLFetch jest specyficzny dla sterownika, ale ogólnym wzorcem jest pobranie danych dla wszystkich powiązanych kolumn ze źródła danych, przekonwertowanie go zgodnie z typami powiązanych zmiennych i umieszczenie przekonwertowanych danych w tych zmiennych. Jeśli sterownik nie może przekonwertować żadnych danych, funkcja SQLFetch zwraca błąd. Aplikacja może kontynuować pobieranie wierszy, ale dane dla bieżącego wiersza zostaną utracone. To, co dzieje się z danymi dla kolumn niepowiązanych, zależy od sterownika, ale większość sterowników pobiera je i odrzuca lub nigdy nie pobiera.

Sterownik ustawia również wartości wszelkich związanych buforów długości/wskaźnika. Jeśli wartość danych dla kolumny ma wartość NULL, sterownik ustawia odpowiedni bufor długości/wskaźnika na SQL_NULL_DATA. Jeśli wartość danych nie ma wartości NULL, sterownik ustawia bufor długości/wskaźnika na długość bajtu danych po konwersji. Jeśli nie można określić tej długości, tak jak czasami w przypadku długich danych pobieranych przez więcej niż jedno wywołanie funkcji, sterownik ustawia bufor długości/wskaźnika na SQL_NO_TOTAL. W przypadku typów danych o stałej długości, takich jak liczby całkowite i struktury dat, długość bajtu jest rozmiarem typu danych.

W przypadku danych o zmiennej długości, takich jak dane znakowe i binarne, sterownik sprawdza długość bajtów przekonwertowanych danych względem długości bajtów buforu powiązanego z kolumną; długość buforu jest określona w argumencie BufferLength w elemencie SQLBindCol. Jeśli długość bajtów przekonwertowanych danych jest większa niż długość bajtów buforu, sterownik obcina dane, aby zmieściły się w buforze, zwraca nieobciętą długość w buforze długości/wskaźnika, zwraca SQL_SUCCESS_WITH_INFO i umieszcza SQLSTATE 01004 (Dane obcięte) w diagnostyce. Jedynym wyjątkiem jest sytuacja, w której zakładka o zmiennej długości jest obcięta w momencie zwracania przez SQLFetch, które zwraca wartość SQLSTATE 22001 (dane ciągowe, przycięte z prawej strony).

Dane o stałej długości nigdy nie są obcinane, ponieważ sterownik zakłada, że rozmiar powiązanego buforu jest rozmiarem typu danych. Obcięcie danych jest rzadkie, ponieważ aplikacja zazwyczaj wiąże bufor wystarczająco duży, aby przechowywać całą wartość danych; określa wymagany rozmiar na podstawie metadanych. Jednak aplikacja może jawnie powiązać bufor, który wiadomo, że jest za mały. Może na przykład pobrać i wyświetlić pierwsze 20 znaków opisu części lub pierwszych 100 znaków długiej kolumny tekstowej.

Dane znakowe muszą zostać zakończone przez sterownik znakiem null, zanim zostaną zwrócone do aplikacji, nawet jeśli zostały obcięte. Znak zakończenia zerowego nie jest uwzględniany w zwracanej długości bajtów, ale wymaga miejsca w przeznaczonym buforze. Załóżmy na przykład, że aplikacja używa ciągów składających się z danych znaków w zestawie znaków ASCII, sterownik ma 50 znaków danych do zwrócenia, a bufor aplikacji ma 25 bajtów długości. W buforze aplikacji sterownik zwraca pierwsze 24 znaki, a następnie znak zakończenia o wartości null. W buforze długości/wskaźnika zwraca długość 50 bajtów.

Aplikacja może ograniczyć liczbę wierszy w zestawie wyników, ustawiając atrybut instrukcji SQL_ATTR_MAX_ROWS przed wykonaniem instrukcji, która tworzy zestaw wyników. Na przykład tryb podglądu w aplikacji używanej do formatowania raportów wymaga tylko wystarczającej ilości danych, aby wyświetlić pierwszą stronę raportu. Ograniczając rozmiar zestawu wyników, taka funkcja będzie działać szybciej. Ten atrybut deklaracji ma na celu zmniejszenie ruchu sieciowego i może nie być obsługiwany przez wszystkie sterowniki.