Načtení řádku dat

Pro načtení řádku dat volá aplikace SQLFetch. Funkci SQLFetch lze volat libovolným druhem kurzoru, ale přesune kurzor sady řádků pouze směrem dopředu. SqlFetch přejde kurzor na další řádek a vrátí data pro všechny sloupce, které byly svázané s voláními SQLBindCol. Když kurzor dosáhne konce sady výsledků, funkce SQLFetch vrátí SQL_NO_DATA. Příklady volání sqlFetch naleznete v tématu Použití SQLBindCol.

Přesný způsob, jak je SQLFetch implementován, je specifický pro ovladač, ale obecně platí, že ovladač načte data pro všechny vázané sloupce ze zdroje dat, převede je podle typů vázaných proměnných a umístí převedená data do těchto proměnných. Pokud ovladač nemůže převést žádná data, vrátí funkce SQLFetch chybu. Aplikace může pokračovat v načítání řádků, ale data pro aktuální řádek budou ztracena. Co se stane s daty pro nevázané sloupce, závisí na ovladači, ale většina ovladačů je buď načte a zahodí, nebo je vůbec nenačte.

Ovladač také nastaví hodnoty všech vyrovnávacích pamětí délky a indikátorů, které byly vázány. Pokud je hodnota datového sloupce NULL, ovladač nastaví odpovídající vyrovnávací paměť délky/indikátoru na SQL_NULL_DATA. Pokud datová hodnota není NULL, ovladač nastaví vyrovnávací paměť délky/ukazatele na bajtovou délku dat po převodu. Pokud tuto délku nelze určit, stejně jako u dlouhých dat načtených více než jedním voláním funkce, ovladač nastaví vyrovnávací paměť délky/indikátoru na SQL_NO_TOTAL. U datových typů s pevnou délkou, jako jsou celá čísla a struktury kalendářních dat, je délka bajtu velikost datového typu.

U dat s proměnlivou délkou, jako jsou znaková a binární data, ovladač zkontroluje délku bajtu převedených dat proti délce bajtu vyrovnávací paměti vázané na sloupec; Délka vyrovnávací paměti je zadána v argumentu BufferLength v SQLBindCol. Pokud je délka bajtu převedených dat větší než délka bajtu vyrovnávací paměti, ovladač zkrátí data tak, aby se vešla do vyrovnávací paměti, vrátí nerušovanou délku v vyrovnávací paměti délky nebo indikátoru, vrátí SQL_SUCCESS_WITH_INFO a umístí SQLSTATE 01004 (Data zkrácená) do diagnostiky. Jedinou výjimkou je, pokud je záložka s proměnnou délkou zkrácena, když je vrácena pomocí SQLFetch, které vrátí SQLSTATE 22001 (řetězcová data, zkrácená vpravo).

Data s pevnou délkou se nikdy nezkrátí, protože ovladač předpokládá, že velikost vázané vyrovnávací paměti je velikost datového typu. Zkrácení dat bývá vzácné, protože aplikace obvykle alokuje vyrovnávací paměť dostatečně velkou, aby pojmula celou hodnotu dat; potřebnou velikost odvozuje z metadat. Aplikace však může explicitně svázat vyrovnávací paměť, o které ví, že je příliš malá. Může například načíst a zobrazit prvních 20 znaků popisu části nebo prvních 100 znaků dlouhého textového sloupce.

Data znaků musí být před vrácením do aplikace ukončena nulovým znakem ovladačem, i pokud byla zkrácena. Znak ukončení null není součástí vrácené délky bajtů, ale vyžaduje mezeru v vázané vyrovnávací paměti. Předpokládejme například, že aplikace používá řetězce složené z dat znaků v znakové sadě ASCII, ovladač má vrátit 50 znaků dat a vyrovnávací paměť aplikace má délku 25 bajtů. Ve vyrovnávací paměti aplikace ovladač vrátí prvních 24 znaků následovaných znakem ukončení s hodnotou null. V vyrovnávací paměti délky/ukazatele vrátí bajtovou délku 50.

Aplikace může omezit počet řádků v sadě výsledků nastavením atributu příkazu SQL_ATTR_MAX_ROWS před spuštěním příkazu, který vytvoří sadu výsledků. Například režim náhledu v aplikaci, která se používá k formátování sestav, potřebuje jenom dostatek dat k zobrazení první stránky sestavy. Omezením velikosti sady výsledků by taková funkce běžela rychleji. Tento atribut příkazu je určený ke snížení síťového provozu a nemusí být podporován všemi ovladači.