Adatsor beolvasása

Adatsor lekéréséhez egy alkalmazás meghívja az SQLFetch-et. Az SQLFetch bármilyen kurzorral meghívható, de csak előrefelé mozgatja a sorhalmaz kurzorát. Az SQLFetch a kurzort a következő sorba viszi, és visszaadja az SQLBindCol-hívásokkal kötött oszlopok adatait. Amikor a kurzor eléri az eredményhalmaz végét, az SQLFetch SQL_NO_DATA ad vissza. Az SQLFetch meghívására példaként lásd az SQLBindCol használatát.

Az SQLFetch implementálása pontosan illesztőprogram-specifikus, de az általános minta az, hogy az illesztőprogram lekéri a kötött oszlopok adatait az adatforrásból, átalakítja azokat a kötött változók típusai szerint, és a konvertált adatokat ezekben a változókban helyezi el. Ha az illesztő nem tud adatokat konvertálni, az SQLFetch hibát ad vissza. Az alkalmazás folytathatja a sorok beolvasását, de az aktuális sor adatai elvesznek. Hogy mi történik a kötetlen oszlopok adataival, az az illesztőprogramtól függ, de a legtöbb illesztőprogram vagy lekéri és elveti, vagy egyáltalán nem kéri le.

Az illesztőprogram beállítja a kötött hossz-/mutatópufferek értékeit is. Ha egy oszlop adatértéke NULL, az illesztő a megfelelő hossz/mutató puffert SQL_NULL_DATA értékre állítja. Ha az adatérték nem NULL, az illesztő a hossz-/mutatópuffert az adat bájthosszára állítja az átalakítás után. Ha ez a hossz nem határozható meg, ahogyan az egyes függvényhívások által lekért hosszú adatok esetében is előfordul, az illesztő a hossz-/mutatópuffert SQL_NO_TOTAL értékre állítja. Rögzített hosszúságú adattípusok, például egész számok és dátumstruktúrák esetén a bájthossz az adattípus mérete.

Változó hosszúságú adatok, például karakter- és bináris adatok esetében az illesztő ellenőrzi az átalakított adatok bájthosszát az oszlophoz kötött puffer bájthosszával; a puffer hossza az SQLBindColBufferLength argumentumában van megadva. Ha a konvertált adatok bájthossza nagyobb, mint a puffer bájthossza, az illesztő csonkolja az adatokat, hogy azok beférjenek a pufferbe, visszaadja az eredeti, nem csonkolt hosszot a hossz/mutató pufferben, visszaadja az SQL_SUCCESS_WITH_INFO értéket, és az SQLSTATE 01004 (Adatok csonkolva) értéket helyezi el a diagnosztikában. Ez alól az egyetlen kivétel, ha egy változó hosszúságú könyvjelző az SQLFetch által visszaadáskor csonkolódik, ami az SQLSTATE 22001-et (szövegadatok, jobbra csonkolva) adja vissza.

A rögzített hosszúságú adatok mérete soha nem kerül csonkolásra, mert a meghajtóprogram feltételezi, hogy a kötött puffer mérete megegyezik az adattípus méretével. Az adatok csonkolása általában ritka, mert az alkalmazás általában elég nagy méretű puffert köt a teljes adatérték tárolásához; a metaadatokból határozza meg a szükséges méretet. Előfordulhat azonban, hogy az alkalmazás explicit módon köt egy puffert, amelyről tudja, hogy túl kicsi. Lekérheti és megjelenítheti például egy részleírás első 20 karakterét vagy egy hosszú szöveges oszlop első 100 karakterét.

A karakteradatokat a drivernek nullával lezártan kell visszaadnia az alkalmazásnak, még akkor is, ha az adatokat csonkolták. A null-végződés karakter nem szerepel a visszaadott bájthosszban, de helyet igényel a kötött pufferben. Tegyük fel például, hogy egy alkalmazás karakteradatokból álló sztringeket használ az ASCII-karakterkészletben, az illesztők 50 karakternyi adatot adnak vissza, az alkalmazás puffere pedig 25 bájt hosszú. Az alkalmazás pufferében az illesztőprogram az első 24 karaktert, majd egy null-végződésű karaktert ad vissza. A hossz/mutató pufferben 50 bájthosszt ad vissza.

Az alkalmazás korlátozhatja az eredményhalmaz sorainak számát a SQL_ATTR_MAX_ROWS utasítás attribútum beállításával az eredményhalmazt létrehozó utasítás végrehajtása előtt. Például a jelentések formázásához használt alkalmazások előnézeti módjának csak elegendő adatra van szüksége a jelentés első oldalának megjelenítéséhez. Az eredményhalmaz méretének korlátozásával egy ilyen funkció gyorsabban futna. Ez az utasításattribútum a hálózati forgalom csökkentésére szolgál, és előfordulhat, hogy az összes illesztőprogram nem támogatja.