Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
megfelelőségi
Bevezetett verzió: ODBC 1.0 szabványmegfelelőség: ISO 92
Összefoglalás
Az SQLFetch lekéri a következő adathalmazt az eredményhalmazból, és az összes kötött oszlop adatait adja vissza.
Szemantika
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Érvek
StatementHandle
[Bemenet] Utasításkezelő.
Visszatérítések
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR vagy SQL_INVALID_HANDLE.
Diagnosztika
Amikor az SQLFetch SQL_ERROR vagy SQL_SUCCESS_WITH_INFO ad vissza, a társított SQLSTATE-érték az SQLGetDiagRec függvény meghívásával érhető el a SQL_HANDLE_STMT HandleType és az StatementHandleleírójával. Az alábbi táblázat felsorolja az SQLFetch által visszaadott SQLSTATE-értékeket, és ismerteti azokat a függvény kontextusában; a(z) "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATES-ek leírását. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve. Ha egy oszlopban hiba történik, az SQLGetDiagField meghívható SQL_DIAG_COLUMN_NUMBER diagIdentifierjével annak az oszlopnak a meghatározásához, amelyen a hiba történt; és az SQLGetDiagField meghívható SQL_DIAG_ROW_NUMBER diagIdentifierjével az oszlopot tartalmazó sor meghatározásához.
A SQL_SUCCESS_WITH_INFO vagy SQL_ERROR (a 01xxx SQLSTATEs kivételével) visszaadható SQLSTATE-k esetében a SQL_SUCCESS_WITH_INFO akkor jelenik meg, ha hiba történik egy vagy több, de nem az összes, egy többsoros művelet soraiban, és SQL_ERROR ad vissza, ha egy egysoros művelet során hiba történik.
| SQLSTATE | Hiba | Leírás |
|---|---|---|
| 01000 | Általános figyelmeztetés | Illesztőprogram-specifikus tájékoztató üzenet. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.) |
| 01004 | Sztringadatok, jobb csonkolt | Az oszlophoz visszaadott sztring- vagy bináris adatok nem üres karakter vagy nem NULL bináris adatok csonkolását eredményezték. Ha sztringérték volt, akkor jobbról csonkolt. |
| 01S01 | Hiba a sorban | Hiba történt egy vagy több sor beolvasása közben. (Ha ez az SQLSTATE akkor jelenik meg, amikor egy ODBC 3*.x* alkalmazás odBC 2*.x* illesztőprogrammal dolgozik, figyelmen kívül hagyható.) |
| 01S07 | Tört csonkolás | Az oszlophoz visszaadott adatok csonkoltak. Numerikus adattípusok esetén a szám törtrésze csonkolt. Az időösszetevőt tartalmazó idő-, időbélyeg- és intervallum-adattípusok esetében az idő tört része csonkolva lett. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.) |
| 07006 | Korlátozott adattípus-attribútumok megsértése | Az eredményhalmaz egyik oszlopának adatértéke nem konvertálható az SQLBindColTargetType által megadott adattípusára. A 0. oszlophoz egy SQL_C_BOOKMARK adattípus volt kötve, és a SQL_ATTR_USE_BOOKMARKS utasítás attribútum SQL_UB_VARIABLE lett beállítva. A 0. oszlop adattípusú SQL_C_VARBOOKMARK volt kötve, és a SQL_ATTR_USE_BOOKMARKS utasítás attribútum nincs SQL_UB_VARIABLE értékre állítva. |
| 07009 | Érvénytelen leíró index | Az illesztő egy ODBC 2*.x* illesztőprogram volt, amely nem támogatja az SQLExtendedFetch-et, és egy oszlop kötésében megadott oszlopszám 0 volt. A 0. oszlop kötött, a SQL_ATTR_USE_BOOKMARKS utasítás attribútum pedig SQL_UB_OFF lett beállítva. |
| 08S01 | Kommunikációs kapcsolat hibája | Az illesztőprogram és az adatforrás közötti kommunikációs kapcsolat, amelyhez az illesztőprogram csatlakoztatva volt, nem sikerült, mielőtt a függvény befejeződött a feldolgozás. |
| 22001 | Sztringadatok, jobb csonkolt | Az oszlophoz visszaadott változó hosszúságú könyvjelző csonkolt. |
| 22002 | A mutatóváltozó kötelező, de nincs megadva | A NULL adatok olyan oszlopba lett beolvasva, amelynek az SQLBindCol által beállított StrLen_or_IndPtr (vagy az SQLSetDescField vagy az SQLSetDescRec által beállított SQL_DESC_INDICATOR_PTR) null mutató volt. |
| 22003 | Numerikus érték a tartományon kívül | Ha egy vagy több kötött oszlop numerikus vagy sztringjeként adja vissza a numerikus értéket, az a szám egészének (a törtrész helyett) egész részét csonkolja. További információ: Adatok konvertálása SQL-ből C adattípusokká a D függelék adattípusai között. |
| 22007 | Érvénytelen dátum/idő formátum | Az eredményhalmaz egyik karakteroszlopa egy dátum, idő vagy időbélyeg C szerkezethez volt kötve, és az oszlop egy értéke érvénytelen dátum, idő vagy időbélyeg volt. |
| 22012 | Osztás nullával | Visszaadottunk egy aritmetikai kifejezésből származó értéket, amely nullával való osztást eredményezett. |
| 22015 | Intervallummező túlcsordult | Ha pontos numerikus vagy intervallum TÍPUSÚ SQL-típust rendel egy C intervallumtípushoz, az jelentős számjegyek elvesztését okozta a kezdő mezőben. Amikor adatokat szeretne beolvasni egy C intervallumtípusba, nem volt ábrázolva az SQL-típus értéke a C intervallumtípusban. |
| 22018 | Érvénytelen karakterérték az öntött specifikációhoz | Az eredményhalmaz egyik karakteroszlopa egy C karakterpufferhez volt kötve, és az oszlop tartalmazott egy karaktert, amelynek nem volt ábrázolása a puffer karakterkészletében. A C típus pontos vagy hozzávetőleges numerikus, dátum- vagy intervallum típusú volt; az oszlop SQL-típusa karakteres adattípus volt; és az oszlop értéke nem a kötött C típus érvényes literálja volt. |
| 24000 | Érvénytelen kurzorállapot | Az StatementHandle végrehajtott állapotban volt, de nincs eredménykészlet társítva az StatementHandle-hez. |
| 40001 | Szerializálási hiba | A lekérés végrehajtásának tranzakciója leállt a holtpont elkerülése érdekében. |
| 40003 | Az utasítás befejezése ismeretlen | A társított kapcsolat a függvény végrehajtása során meghiúsult, és a tranzakció állapota nem határozható meg. |
| HY000 | Általános hiba | Hiba történt, amely miatt nem volt konkrét SQLSTATE, és amelyhez nem definiáltak implementációspecifikus SQLSTATE-t. Az SQLGetDiagRec által a *MessageText pufferben visszaadott hibaüzenet leírja a hibát és annak okát. |
| HY001 | Memóriafoglalási hiba | Az illesztőprogram nem tudta lefoglalni a függvény végrehajtásának vagy befejezésének támogatásához szükséges memóriát. |
| HY008 | Művelet megszakítva | Az aszinkron feldolgozás engedélyezve lett a StatementHandle. Meghívták az SQLFetch függvényt , és a végrehajtás befejezése előtt az SQLCancel vagy az SQLCancelHandle meghívása megtörtént az Utasításkezelőben. Ezután a rendszer ismét meghívta az SQLFetch függvényt az Utasításkezelőben. Vagy meghívták az SQLFetch függvényt, és a végrehajtás befejezése előtt az SQLCancel vagy az SQLCancelHandle meghívást kapott az Utasításkezelőre egy másik szálról egy többszálas alkalmazásban. |
| HY010 | Függvényütemezési hiba | (DM) A rendszer aszinkron módon végrehajtó függvényt hívott meg a StatementHandletársított kapcsolati leíróhoz. Ez az aszinkron függvény továbbra is az SQLFetch függvény meghívásakor lett végrehajtva. (DM) SQLExecute, SQLExecDirectvagy SQLMoreResults meghívást kapott a StatementHandle, és visszaadta SQL_PARAM_DATA_AVAILABLE. Ez a függvény az összes streamelt paraméter adatainak lekérése előtt lett meghívva. (DM) A megadott StatementHandle nem volt végrehajtva. A függvény meghívása SQLExecDirect, SQLExecute vagy katalógusfüggvény meghívása nélkül történt. (DM) A StatementHandle aszinkron módon végrehajtó függvény (nem ez) lett meghívva, és a függvény meghívásakor továbbra is végrehajtó volt. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationsvagy SQLSetPos meghívást kapott az StatementHandle, és visszaadta SQL_NEED_DATA. Ezt a függvényt az összes adatvégrehajtási paraméter vagy oszlop adatküldése előtt hívták meg. (DM) Az SQLFetch az SQLExtendedFetch meghívása után és az SQLFreeStmt előtt lett meghívva az SQL_CLOSE beállítással. |
| HY013 | Memóriakezelési hiba | A függvényhívás nem dolgozható fel, mert a mögöttes memóriaobjektumok nem érhetők el, esetleg a memóriahiány miatt. |
| HY090 | Érvénytelen sztring vagy puffer hossza | A SQL_ATTR_USE_BOOKMARK utasítás attribútum SQL_UB_VARIABLE lett beállítva, a 0. oszlop pedig olyan pufferhez volt kötve, amelynek hossza nem volt egyenlő az eredményhalmaz könyvjelzőjének maximális hosszával. (Ez a hossz az IRD SQL_DESC_OCTET_LENGTH mezőjében érhető el, és az SQLDescribeCol, az SQLColAttribute vagy az SQLGetDescField meghívásával érhető el.) |
| HY107 | Sorérték kívül esik a tartományon | Az SQL_ATTR_CURSOR_TYPE utasításattribútummal megadott érték SQL_CURSOR_KEYSET_DRIVEN volt, de a SQL_ATTR_KEYSET_SIZE utasítás attribútummal megadott érték nagyobb, mint 0, és kisebb, mint a SQL_ATTR_ROW_ARRAY_SIZE utasításattribútumban megadott érték. |
| HY117 | A kapcsolat ismeretlen tranzakciós állapot miatt fel van függesztve. Csak a leválasztási és írásvédett függvények engedélyezettek. | (DM) További információ a felfüggesztett állapotról: SQLEndTran függvény. |
| HYC00 | A választható funkció nem implementálva | Az illesztőprogram vagy az adatforrás nem támogatja az SQLBindColTargetType és a megfelelő oszlop SQL-adattípusának kombinációjával megadott átalakítást. |
| HYT00 | Az időtúllépés lejárt | A lekérdezés időtúllépési időtartama lejárt, mielőtt az adatforrás visszaadta a kért eredményhalmazt. Az időtúllépési időszak az SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT keresztül van beállítva. |
| HYT01 | A kapcsolat időtúllépés miatt megszakadt | A kapcsolat időtúllépési időtartama lejárt, mielőtt az adatforrás válaszolt a kérésre. A kapcsolat időtúllépési időszaka SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Az illesztőprogram nem támogatja ezt a függvényt | (DM) A StatementHandle illesztőprogramja nem támogatja a függvényt. |
| IM017 | A lekérdezés aszinkron értesítési módban le van tiltva | Az értesítési modell használata esetén a lekérdezés le van tiltva. |
| IM018 | SQLCompleteAsync nem lett meghívva az előző aszinkron művelet végrehajtásához ezen a leírón. | Ha a leíró előző függvényhívása SQL_STILL_EXECUTING ad vissza, és ha az értesítési mód engedélyezve van, SQLCompleteAsync kell meghívni a leíróra a művelet utófeldolgozásához és befejezéséhez. |
Megjegyzések
Az SQLFetch az eredményhalmaz következő sorkészletét adja vissza. Csak akkor hívható meg, ha egy eredményhalmaz létezik: vagyis egy eredményhalmazt létrehozó hívás után, és mielőtt a kurzor az eredményhalmaz felett le van zárva. Ha bármelyik oszlop kötött, az ezekben az oszlopokban szereplő adatokat adja vissza. Ha az alkalmazás adott meg egy mutatót egy sorállapot-tömbhöz vagy egy pufferhez, amelyben a beolvasott sorok számát szeretné visszaadni, az SQLFetch ezt az információt is visszaadja. Az SQLFetch hívásai keverhetők az SQLFetchScroll hívásaival, de nem keverhetők az SQLExtendedFetch hívásaival. További információ: Adatsor beolvasása.
Ha egy ODBC 3*.x* alkalmazás egy ODBC 2*.x* illesztőprogrammal működik, az Illesztőprogram-kezelő az SQLFetch-hívásokat az SQLExtendedFetch-nek leképezi egy OLYAN ODBC 2*.x* illesztőprogramhoz, amely támogatja az SQLExtendedFetch-et. Ha az ODBC 2*.x* illesztőprogram nem támogatja az SQLExtendedFetchet, a Driver Manager az SQLFetch-hívásokat az ODBC 2*.x* illesztőben leképezi, amely csak egyetlen sort tud lekérni.
További információ: Kurzorok, görgethető kurzorok és visszamenőleges kompatibilitási a G függelékben: Illesztőprogramok útmutatója a visszamenőleges kompatibilitáshoz.
A kurzor elhelyezése
Az eredményhalmaz létrehozásakor a kurzor az eredményhalmaz kezdete előtt lesz elhelyezve. Az SQLFetch lekéri a következő sorkészletet. Ez egyenértékű az SQLFetchScroll meghívásával , a FetchOrientation beállítása SQL_FETCH_NEXT. A kurzorokról további információt a Kurzorok és a Kurzorok blokkolása című témakörben talál.
A SQL_ATTR_ROW_ARRAY_SIZE utasítás attribútum a sorhalmaz sorainak számát adja meg. Ha az SQLFetch által beolvasandó sorhalmaz átfedésben van az eredményhalmaz végén, az SQLFetch egy részleges sorkészletet ad vissza. Ez azt jelenti, hogy ha az S + R - 1 nagyobb, mint az L, ahol az S a beolvasandó sorhalmaz kezdő sora, az R a sorhalmaz mérete, az L pedig az eredményhalmaz utolsó sora, akkor csak az első L - S + 1 sor érvényes. A többi sor üres, és SQL_ROW_NOROW állapotú.
Az SQLFetch visszatérése után az aktuális sor a sorhalmaz első sora.
Az alábbi táblázatban felsorolt szabályok az SQLFetch hívása után a kurzor elhelyezését írják le a szakasz második táblázatában felsorolt feltételek alapján.
| Állapot | Új sorkészlet első sora |
|---|---|
| Kezdés előtt | 1 |
| CurrRowsetStart<= LastResultRow – RowsetSize[1] | CurrRowsetStart + Sorokkészletek[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Befejezés után |
| Befejezés után | Befejezés után |
[1] Ha a sorhalmaz mérete a beolvasások között változik, akkor ez az előző beolvasás során használt sorhalmazméret.
[2] Ha a sorkészlet mérete a beolvasások között változik, akkor ez az új beolvasáshoz használt sorhalmazméret.
| Jelölés | Értelmezés |
|---|---|
| Kezdés előtt | A blokkkurzor az eredményhalmaz kezdete előtt van elhelyezve. Ha az új sorhalmaz első sora az eredményhalmaz kezdete előtt van, az SQLFetch SQL_NO_DATA ad vissza. |
| Befejezés után | A blokkkurzor az eredményhalmaz vége után van elhelyezve. Ha az új sorhalmaz első sora az eredményhalmaz vége után van, az SQLFetch SQL_NO_DATA ad vissza. |
| CurrRowsetStart | Az aktuális sorhalmaz első sorának száma. |
| LastResultRow | Az eredményhalmaz utolsó sorának száma. |
| Sorokkészletek | A sorkészlet mérete. |
Tegyük fel például, hogy egy eredményhalmaznak 100 sora van, a sorhalmaz mérete pedig 5. Az alábbi táblázat az SQLFetch által visszaadott sorkészletet és visszatérési kódot mutatja be a különböző kezdőpozíciókhoz.
| Aktuális sorkészlet | Kód visszaadása | Új sorkészlet | Beolvasott sorok száma |
|---|---|---|---|
| Kezdés előtt | SQL_SUCCESS | 1–5 | 5 |
| 1–5 | SQL_SUCCESS | 6–10 | 5 |
| 52–56 | SQL_SUCCESS | 57–61 | 5 |
| 91–95 | SQL_SUCCESS | 96–100 | 5 |
| 93–97 | SQL_SUCCESS | 98 és 100 között. A sorállapot-tömb 4. és 5. sora SQL_ROW_NOROW. | 3 |
| 96–100 | SQL_NO_DATA | Nincs. | 0 |
| 99–100 | SQL_NO_DATA | Nincs. | 0 |
| Befejezés után | SQL_NO_DATA | Nincs. | 0 |
Adatok visszaadása kötött oszlopokban
Mivel az SQLFetch minden sort visszaad, az adott oszlophoz kötött puffer minden kötött oszlopának adatait helyezi el. Ha nincsenek megkötve oszlopok, az SQLFetch nem ad vissza adatokat, de a blokkkurzort előre helyezi. Az adatok továbbra is lekérhetők az SQLGetData használatával. Ha a kurzor egy többhelyes kurzor (azaz a SQL_ATTR_ROW_ARRAY_SIZE nagyobb, mint 1), az SQLGetData csak akkor hívható meg, ha SQL_GD_BLOCK akkor ad vissza, amikor az SQLGetInfo SQL_GETDATA_EXTENSIONS InfoType-jával van meghívva. (További információ: SQLGetData.)
Az SQLFetch a sor minden kötött oszlopához a következőket teszi:
A hossz/mutató pufferét SQL_NULL_DATA értékre állítja, és a következő oszlopra lép, ha az adatok NULL értékűek. Ha az adatok NULL értékűek, és nem kötöttek hossz-/mutatópuffert, az SQLFetch az SQLSTATE 22002 -et (a mutatóváltozót kötelező megadni, de nem adja meg) adja vissza a sorhoz, és a következő sorra lép. A hossz/mutató puffer címének meghatározásáról az SQLBindCol "Puffercímek" című szakaszában olvashat.
Ha az oszlop adatai nem NULL értékűek, az SQLFetch a 2. lépésre lép.
Ha a SQL_ATTR_MAX_LENGTH utasítás attribútuma nemero értékű, és az oszlop karakter- vagy bináris adatokat tartalmaz, az adatok SQL_ATTR_MAX_LENGTH bájtra csonkulnak.
Megjegyzés:
A SQL_ATTR_MAX_LENGTH utasítás attribútum célja a hálózati forgalom csökkentése. Általában az adatforrás implementálja, amely csonkolja az adatokat, mielőtt a hálózaton keresztül visszaadja azokat. Az illesztőprogramok és adatforrások nem szükségesek a támogatásához. Ezért annak biztosítása érdekében, hogy az adatok csonkolva legyenek egy adott méretre, az alkalmazásnak ki kell foglalnia egy ilyen méretű puffert, és meg kell adnia a méretet az SQLBindColcbValueMax argumentumában.
Átalakítja az adatokat az SQLBindColTargetType által megadott típusra.
Ha az adatokat változó hosszúságú adattípussá konvertálták, például karakter vagy bináris adattípussá, az SQLFetch ellenőrzi, hogy az adatok hossza meghaladja-e az adatpuffer hosszát. Ha a karakteradatok hossza (beleértve a null-végpont karaktert is) meghaladja az adatpuffer hosszát, az SQLFetch csonkolja az adatokat az adatpuffer hosszára, és nem veszi figyelembe a null-végződés karakterének hosszát. Ezután null értékűre bontja az adatokat. Ha a bináris adatok hossza meghaladja az adatpuffer hosszát, az SQLFetch csonkolja az adatpuffer hosszára. Az adatpuffer hosszát az SQLBindColPufferLength paramétere határozza meg.
Az SQLFetch soha nem csonkolja a rögzített hosszúságú adattípusokká konvertált adatokat; mindig azt feltételezi, hogy az adatpuffer hossza az adattípus mérete.
A konvertált (és esetleg csonkolt) adatokat az adatpufferbe helyezi. Az adatpuffer címének meghatározásáról az SQLBindCol "Puffercímek" című témakörében olvashat.
Az adatok hosszát a hossz-/mutatópufferbe helyezi. Ha a mutatómutató és a hosszmutató is ugyanarra a pufferre van állítva (ahogy az SQLBindCol hívása teszi), a hossz a pufferben lesz megírva érvényes adatokhoz, és SQL_NULL_DATA a NULL adatok pufferében van megírva. Ha nem kötött meg hossz/mutató puffert, az SQLFetch nem adja vissza a hosszt.
Karakteres vagy bináris adatok esetében ez az adatok hossza az átalakítás után és a csonkolás előtt, mivel az adatpuffer túl kicsi. Ha az illesztő nem tudja meghatározni az adatok hosszát az átalakítás után, ahogyan a hosszú adatok esetében is előfordul, a hossz SQL_NO_TOTAL. Ha az adatokat a SQL_ATTR_MAX_LENGTH utasítás attribútuma miatt csonkolta, az attribútum értéke a tényleges hossz helyett a hossz/mutató pufferbe kerül. Ennek az az oka, hogy ez az attribútum úgy lett kialakítva, hogy az átalakítás előtt csonkítsa az adatokat a kiszolgálón, így az illesztőprogramnak nincs módja annak megállapítására, hogy mi a tényleges hossz.
Az összes többi adattípus esetében ez az adatok hossza az átalakítás után; vagyis annak a típusnak a mérete, amelyre az adatokat konvertálták.
A hossz/mutató puffer címének meghatározásáról az SQLBindCol "Puffercímek" című szakaszában olvashat.
Ha az adatok csonkolva lesznek az átalakítás során jelentős számjegyek elvesztése nélkül (például az 1.234-es valós számot az 1 egész számra csonkolja konvertáláskor), az SQLFetch az SQLSTATE 01S07 (tört csonkolás) és SQL_SUCCESS_WITH_INFO ad vissza. Ha az adatok csonkolt, mert az adatpuffer hossza túl kicsi (például az "abcdef" sztring egy 4 bájtos pufferbe kerül), az SQLFetch az SQLSTATE 01004 -et (Az adatok csonkolt) és SQL_SUCCESS_WITH_INFO adja vissza. Ha az adatok csonkolása a SQL_ATTR_MAX_LENGTH utasítás attribútum miatt történik, az SQLFetch SQL_SUCCESS ad vissza, és nem ad vissza SQLSTATE 01S07 (tört csonkolás) vagy SQLSTATE 01004 (Csonkolt adatok). Ha az adatok csonkulnak az átalakítás során jelentős számjegyek elvesztésével (például ha egy 100 000-nél nagyobb SQL_INTEGER értéket konvertáltak SQL_C_TINYINT), az SQLFetch az SQLSTATE 22003-at (a numerikus érték tartományon kívül) és SQL_ERROR (ha a sorhalmaz mérete 1) vagy SQL_SUCCESS_WITH_INFO (ha a sorhalmaz mérete nagyobb, mint 1).
Ha az SQLFetch vagy az SQLFetchScroll nem ad vissza SQL_SUCCESS vagy SQL_SUCCESS_WITH_INFO, a kötött adatpuffer és a hossz-/mutatópuffer tartalma nincs meghatározva.
Sorállapot mezők tömbje
A sorállapot-tömb a sorhalmaz egyes sorainak állapotát adja vissza. A tömb címe a SQL_ATTR_ROW_STATUS_PTR utasítás attribútummal van megadva. A tömböt az alkalmazás foglalja le, és a SQL_ATTR_ROW_ARRAY_SIZE utasítás attribútum által megadott számú elemet kell tartalmaznia. Értékeit az SQLFetch, az SQLFetchScroll és az SQLBulkOperations vagy az SQLSetPos állítja be (kivéve, ha a kurzor SQLExtendedFetch általi elhelyezése után lettek meghívva). Ha a SQL_ATTR_ROW_STATUS_PTR utasítás attribútum értéke null mutató, ezek a függvények nem adják vissza a sor állapotát.
A sorállapottömb pufferének tartalma nincs meghatározva, ha az SQLFetch vagy az SQLFetchScroll nem ad vissza SQL_SUCCESS vagy SQL_SUCCESS_WITH_INFO.
A következő értékek lesznek visszaadva a sorállapot-tömbben.
| Sorállapottömb értéke | Leírás |
|---|---|
| SQL_ROW_SUCCESS | A sor beolvasása sikeresen megtörtént, és nem változott, mivel az utolsó beolvasása ebből az eredménykészletből történt. |
| SQL_ROW_SUCCESS_WITH_INFO | A sor beolvasása sikeresen megtörtént, és nem változott, mivel az utolsó beolvasása ebből az eredménykészletből történt. A sorra vonatkozó figyelmeztetés azonban vissza lett adva. |
| SQL_ROW_ERROR | Hiba történt a sor beolvasása közben. |
| SQL_ROW_UPDATED[1],[2] és [3] | A sor beolvasása sikeresen megtörtént, és azóta módosult, hogy utoljára beolvasták ebből az eredményhalmazból. Ha a sor ismét lekéri ezt az eredményhalmazt, vagy az SQLSetPos frissíti, az állapot a sor új állapotára módosul. |
| SQL_ROW_DELETED[3] | A sor törölve lett, mióta utoljára beolvasták ebből az eredményhalmazból. |
| SQL_ROW_ADDED[4] | A sort az SQLBulkOperations szúrta be. Ha a sor ismét lekéri ezt az eredményhalmazt, vagy az SQLSetPos frissíti, az állapota SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | A sorhalmaz átfedte az eredményhalmaz végét, és a rendszer nem adott vissza olyan sort, amely megfelelt a sorállapot-tömb ezen elemének. |
[1] Kulcskészletek, vegyes és dinamikus kurzorok esetén, ha egy kulcsérték frissül, a rendszer úgy tekinti, hogy az adatsor törölve lett, és új sor lett hozzáadva.
[2] Egyes illesztőprogramok nem tudják észlelni az adatok frissítéseit, ezért nem tudják visszaadni ezt az értéket. Annak megállapításához, hogy az illesztőprogram képes-e észlelni az újrabecsült sorok frissítéseit, az alkalmazás meghívja az SQLGetInfo-t a SQL_ROW_UPDATES beállítással.
[3] Az SQLFetch csak akkor tudja visszaadni ezt az értéket, ha az SQLFetchScroll hívásaival van összekapcsolva. Ennek az az oka, hogy az SQLFetch előrehalad az eredményhalmazon, és ha kizárólagosan használja, nem hajtja újra a sorokat. Mivel nincsenek újrabecsülve sorok, az SQLFetch nem észleli a korábban beolvasott sorok módosításait. Ha azonban az SQLFetchScroll a kurzort a korábban beolvasott sorok elé viszi, és az SQLFetch ezeket a sorokat kéri le, az SQLFetch képes észlelni a sorok módosításait.
[4] Csak az SQLBulkOperations adja vissza. Az SQLFetch vagy az SQLFetchScroll nem állítja be.
Lekért sorok puffere
A lekért sorok puffere a beolvasott sorok számát adja vissza, beleértve azokat a sorokat is, amelyek esetében a beolvasás során hiba történt. Más szóval azoknak a soroknak a száma, amelyeknél a sorállapot-tömb értéke nem SQL_ROW_NOROW. A puffer címe a SQL_ATTR_ROWS_FETCHED_PTR utasítás attribútummal van megadva. A puffert az alkalmazás foglalja le. Ezt az SQLFetch és az SQLFetchScroll állítja be. Ha a SQL_ATTR_ROWS_FETCHED_PTR utasítás attribútum értéke null értékű, ezek a függvények nem adják vissza a beolvasott sorok számát. Az eredményhalmaz aktuális sorának számának meghatározásához az alkalmazás meghívhatja az SQLGetStmtAttr parancsot a SQL_ATTR_ROW_NUMBER attribútummal.
Ha az SQLFetch vagy az SQLFetchScroll nem ad vissza SQL_SUCCESS vagy SQL_SUCCESS_WITH_INFO, a lekért sorok tartalma nem határozható meg, kivéve, ha SQL_NO_DATA ad vissza, ebben az esetben a lekért sorok pufferének értéke 0.
Hibakezelés
A hibák és figyelmeztetések egyes sorokra vagy az egész függvényre vonatkozhatnak. A diagnosztikai rekordokról további információt a Diagnostics és az SQLGetDiagField című témakörben talál.
Hibák és figyelmeztetések a teljes függvényen
Ha egy hiba a teljes függvényre vonatkozik, például az SQLSTATE HYT00 (Időtúllépés lejárt) vagy az SQLSTATE 24000 (Érvénytelen kurzorállapot), az SQLFetch SQL_ERROR és a vonatkozó SQLSTATE értéket adja vissza. A sorkészlet puffereinek tartalma nincs definiálva, és a kurzor pozíciója változatlan.
Ha egy figyelmeztetés a teljes függvényre vonatkozik, az SQLFetch visszaadja a SQL_SUCCESS_WITH_INFO és a vonatkozó SQLSTATE-t. A teljes függvényre vonatkozó figyelmeztetések állapotrekordjait a rendszer az egyes sorokra vonatkozó állapotrekordok előtt adja vissza.
Hibák és figyelmeztetések az egyes sorokban
Ha egy hiba (például SQLSTATE 22012 (Osztás nullával)) vagy figyelmeztetés (például SQLSTATE 01004 (Csonkolt adatok)) egyetlen sorra vonatkozik, az SQLFetch a következőket teszi:
A sorállapot-tömb megfelelő elemét úgy állítja be, hogy SQL_ROW_ERROR hibák vagy figyelmeztetések SQL_ROW_SUCCESS_WITH_INFO.
Nulla vagy több olyan állapotrekordot ad hozzá, amely SQLSTATE-ket tartalmaz a hibához vagy figyelmeztetéshez.
Beállítja az állapotrekordok sor- és oszlopszámmezőit. Ha az SQLFetch nem tudja meghatározni a sor- vagy oszlopszámot, akkor ezt a számot SQL_ROW_NUMBER_UNKNOWN vagy SQL_COLUMN_NUMBER_UNKNOWN értékre állítja. Ha az állapotrekord nem vonatkozik egy adott oszlopra, az SQLFetch az oszlopszámot SQL_NO_COLUMN_NUMBER értékre állítja.
Az SQLFetch addig folytatja a sorok beolvasását, amíg be nem olvassa a sorhalmaz összes sorát. SQL_SUCCESS_WITH_INFO ad vissza, kivéve, ha hiba történik a sorhalmaz minden sorában (a SQL_ROW_NOROW állapotú sorokat nem), ebben az esetben SQL_ERROR ad vissza. Ha a sorhalmaz mérete 1, és hiba történik a sorban, az SQLFetch SQL_ERROR ad vissza.
Az SQLFetch a sorszám sorrendjében adja vissza az állapotrekordokat. Vagyis az ismeretlen sorok összes állapotrekordját visszaadja (ha van ilyen); ezután az első sor összes állapotrekordját visszaadja (ha van ilyen), majd a második sor összes állapotrekordját visszaadja (ha van ilyen), és így tovább. Az egyes sorok állapotrekordjai az állapotrekordok rendelésére vonatkozó normál szabályok szerint vannak rendezve; További információ: "Állapotrekordok sorrendje" az SQLGetDiagFieldben.
Leírók és SQLFetch
Az alábbi szakaszok azt mutatják be, hogy az SQLFetch hogyan kommunikál a leírókkal.
Argumentumleképezések
Az illesztő nem állít be leíró mezőket az SQLFetch argumentumai alapján.
Egyéb leíró mezők
Az SQLFetch az alábbi leíró mezőket használja.
| Leíró mező | Desc. | Mező a következőben: | Beállítás |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | fejléc | SQL_ATTR_ROW_ARRAY_SIZE utasítás attribútum |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | fejléc | SQL_ATTR_ROW_STATUS_PTR utasítás attribútum |
| SQL_DESC_BIND_OFFSET_PTR | ARD | fejléc | SQL_ATTR_ROW_BIND_OFFSET_PTR utasítás attribútum |
| SQL_DESC_BIND_TYPE | ARD | fejléc | SQL_ATTR_ROW_BIND_TYPE utasítás attribútum |
| SQL_DESC_COUNT | ARD | fejléc | Az SQLBindColColumnNumber argumentuma |
| SQL_DESC_DATA_PTR | ARD | rekord | Az SQLBindColTargetValuePtr argumentuma |
| SQL_DESC_INDICATOR_PTR | ARD | rekord | StrLen_or_IndPtr argumentum az SQLBindColban |
| SQL_DESC_OCTET_LENGTH | ARD | rekord | BufferLength argumentum az SQLBindColban |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | rekord | StrLen_or_IndPtr argumentum az SQLBindColban |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | fejléc | SQL_ATTR_ROWS_FETCHED_PTR utasítás attribútum |
| SQL_DESC_TYPE | ARD | rekord | TargetType argumentum az SQLBindColban |
Az összes leíró mező az SQLSetDescField használatával is beállítható.
Külön hossz- és mutatópufferek
Az alkalmazások egyetlen vagy két különálló puffert köthetnek össze, amelyek hossz- és mutatóértékek tárolására használhatók. Amikor egy alkalmazás meghívja az SQLBindColt, az illesztő az ARD SQL_DESC_OCTET_LENGTH_PTR és SQL_DESC_INDICATOR_PTR mezőit ugyanarra a címre állítja be, amelyet a StrLen_or_IndPtr argumentumban ad át. Amikor egy alkalmazás meghívja az SQLSetDescFieldet vagy az SQLSetDescRecet, ezt a két mezőt különböző címekre állíthatja be.
Az SQLFetch meghatározza, hogy az alkalmazás külön hossz- és mutatópuffereket adott-e meg. Ebben az esetben, ha az adatok nem NULL értékűek, az SQLFetch a mutatópuffert 0 értékre állítja, és a hosszpuffer hosszát adja vissza. Ha az adatok NULL értékűek, az SQLFetch a mutatópuffert SQL_NULL_DATA értékre állítja, és nem módosítja a hosszpuffert.
Kódpélda
Lásd: SQLBindCol, SQLColumns, SQLGetData és SQLProcedures.
Kapcsolódó függvények
| Információ erről: | Nézze |
|---|---|
| Puffer kötése egy eredményhalmaz oszlopához | SQLBindCol függvény |
| Utasításfeldolgozás megszakítása | SQLCancel-függvény |
| Eredményhalmaz oszlopával kapcsolatos információk visszaadása | SQLDescribeCol függvény |
| SQL-utasítás végrehajtása | SQLExecDirect függvény |
| Előkészített SQL-utasítás végrehajtása | SQLExecute függvény |
| Adatblokk beolvasása vagy egy eredményhalmaz görgetése | SQLFetchScroll függvény |
| A kurzor bezárása az utasításon | SQLFreeStmt függvény |
| Adatoszlop egy részének vagy egészének beolvasása | SQLGetData függvény |
| Eredményhalmaz oszlopainak számának visszaadása | SQLNumResultCols függvény |
| Utasítás előkészítése végrehajtáshoz | SQLPrepare függvény |
Lásd még:
ODBC API-referencia
ODBC-fejlécfájlok