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ég
Bemutatott verzió: ODBC 3.0 szabványoknak megfelelés: ISO 92
Summary
Az SQLFetchScroll leállítja az eredményhalmazból a megadott sorkészletet, és minden kötött oszlop adatait adja vissza. A sorhalmazok abszolút vagy relatív pozícióban vagy könyvjelzővel határozhatók meg.
ODBC 2.x illevezetővel dolgozva a Driver Manager ezt a függvényt az SQLExtendedFetch-hez képezi. További információért lásd: Mapping Replacement Functions for Backward Compatibility of Applications.
Syntax
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
Arguments
StatementHandle
[Bemenet] Utasításkezelő.
FetchOrientation
[Bemenet]
A hozás típusa:
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
SQL_FETCH_RELATIVE
SQL_FETCH_BOOKMARK
További információért lásd: "A kurzor pozícionálása" a "Hozzászólások" szakaszban.
FetchOffset
[Bemenet]
A sor száma, amit el kell hozni. Ennek az érvelésnek az értelmezése a FetchOrientation érv értékétől függ. További információért lásd: "A kurzor pozícionálása" a "Hozzászólások" szakaszban.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR vagy SQL_INVALID_HANDLE.
Diagnostics
Amikor az SQLFetchScroll SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad, egy hozzárendelt SQLSTATE érték elérhető SQLGetDiagRec hívásával, amely egy SQL_HANDLE_STMT HandleType és egy HandleType of StatementHandle (HandleType) segítségével érhető el. Az alábbi táblázat felsorolja az SQLFetchScroll által gyakran visszaadott SQLSTATE értékeket, és mindegyiket ennek a függvénynek a kontextusában magyarázza; a "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATE-leírásokat. 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 egyetlen oszlopon hiba jelentkezik, az SQLGetDiagField SQL_DIAG_COLUMN_NUMBER DiagIdentifierrel hívható, hogy meghatározzuk, melyik oszlopon történt a hiba; és az SQLGetDiagField meghívható SQL_DIAG_ROW_NUMBER DiagIdentifier értékű DiagIdentifier alapján, hogy meghatározzuk, melyik sor tartalmazza az adott oszlopot.
Minden olyan SQLSTATE-nél, amely SQL_SUCCESS_WITH_INFO vagy SQL_ERROR vissza tud adni (kivéve a 01xxx SQLSTATE-eket), SQL_SUCCESS_WITH_INFO akkor jelenik meg, ha hiba egy vagy több, de nem az összes sorban történik egy többsoros műveletben, és SQL_ERROR akkor jelenik meg, ha hiba egysoros műveletnél is előfordul.
| SQLSTATE | Hiba | Description |
|---|---|---|
| 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 string vagy bináris adat nem üres karakter vagy nem NULL bináris adatok lerövidítését eredményezte. Ha sztringérték volt, akkor jobbról csonkolt. |
| 01S01 | Hiba a sorban | Hiba történt egy vagy több sor lekérése közben. (Ha ez az SQLSTATE akkor jelenik meg, amikor egy ODBC 3*.x* alkalmazás ODBC 2*.x* illezőgéppel dolgozik, akkor figyelmen kívül hagyható.) |
| 01S06 | Próbálkozz előre az eredményhalmazt elő behozni az első sorhalmazt | A kért sorhalmaz átfedte az eredményhalmaz kezdetét, amikor a FetchOrientation SQL_FETCH_PRIOR volt, a jelenlegi pozíció az első sor fölött volt, és a jelenlegi sor száma kisebb, mint a sorhalmaz mérete. A kért sorkészlet átfedte az eredményhalmaz kezdetét, amikor a FetchOrientation SQL_FETCH_PRIOR volt, a jelenlegi pozíció az eredményhalmaz végén volt, és a sorhalmaz mérete nagyobb volt, mint az eredményhalmaz. A kért sorhalmaz átfedte az eredményhalmaz kezdetét, amikor a FetchOrientation SQL_FETCH_RELATIVE, a FetchOffset negatív, és a FetchOffset abszolút értéke kisebb, mint a sorhalmaz mérete. A kért sorhalmaz átfedte az eredményhalmaz kezdetét, amikor a FetchOrientation SQL_FETCH_ABSOLUTE, a FetchOffset negatív, és a FetchOffset abszolút értéke nagyobb, mint az eredményhalmaz, de kisebb vagy egyenlő volt a sorhalmaz méretével. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.) |
| 01S07 | Tört csonkolás | Az oszlophoz visszaadott adatokat lerövidítették. Számos adattípusok esetén a szám törtrész része lerövidített. Az idő-, időbélyeg- és intervallum adattípusok esetében, amelyek időkomponenst tartalmaznak, az idő törtrész részét lerövidítették. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.) |
| 07006 | Korlátozott adattípus-attribútumok megsértése | Az eredményhalmazban lévő oszlop adatértéke nem volt átalakítható a TargetType által az SQLBindCol-ban megadott adattípusra. A 0. oszlopot SQL_C_BOOKMARK adattípussal kötötték, és a SQL_ATTR_USE_BOOKMARKS állítás attribútuma SQL_UB_VARIABLE-re volt beállítva. A 0. oszlop egy SQL_C_VARBOOKMARK adattípushoz volt kötve, és a SQL_ATTR_USE_BOOKMARKS utasítás attribútuma nem volt SQL_UB_VARIABLE-re állítva. |
| 07009 | Érvénytelen descriptor index | Az illesztőprogram egy ODBC 2*.x* illesztőprogram volt, amely nem támogatja az SQLExtendedFetch-et, és az oszlop kötésében megadott oszlopszám 0 volt. A 0. oszlop kötött volt, és a SQL_ATTR_USE_BOOKMARKS állítás attribútuma SQL_UB_OFF-re volt 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 | Egy változó hosszúságú könyvjelzőt egy oszlophoz visszaállítottak. |
| 22002 | A mutatóváltozó kötelező, de nincs megadva | A NULL adatokat egy oszlopba hozták be, amelynek StrLen_or_IndPtrSQLBindCol által (vagy SQL_DESC_INDICATOR_PTR SQLSetDescField vagy SQLSetDescRec által állított be) null pointer volt. |
| 22003 | Numerikus érték a tartományon kívül | Ha visszaadjuk a numerikus értéket (numerikus vagy láncszálként) egy vagy több kötött oszlopnál, az egész (nem törtrész) rész lerövidítéséhez vezetett. További információért lásd: Adatátalakítás SQL-ből C-re az Adattípusok a D. mellékletben: Adattípusok. |
| 22007 | Érvénytelen dátum/idő formátum | Az eredményhalmaz egy karakteroszlopa egy dátum, idő vagy időbélyeg C szerkezethez volt kötve, és az oszlopban lévő érték érvénytelen dátum, idő vagy időbélyeg volt. |
| 22012 | Osztás nullával | Egy aritmetikai kifejezésből származó értéket adtak vissza, ami nullával osztott részt. |
| 22015 | Intervallummező túlcsordult | Egy pontos numerikus vagy intervallum SQL típusból C intervallum típushoz való hozzárendelés jelentős számjegyek elvesztését okozta az első mezőben. Amikor adatokat egy C intervallum típusba hívtak, nem mutatkoztak be az SQL típus értékének ábrázolása a C intervallum típusban. |
| 22018 | Érvénytelen karakterérték az öntött specifikációhoz | Az eredményhalmaz egy karakteroszlopa egy C karakter pufferhez volt kötve, és az oszlop tartalmazott egy olyan karaktert, amelynek nem volt ábrázolása a puffer karakterhalmazában. A C típus pontos vagy közelítő numerikus, dátumi vagy intervallum adattípus volt; az oszlop SQL típusa karakteradattípus volt; és az oszlopban lévő érték nem volt érvényes literális a kötött C típusból. |
| 24000 | Érvénytelen kurzorállapot | A StatementHandle végrehajtott állapotban volt, de nem volt hozzá semmilyen eredményhalmaz. |
| 40001 | Szerializálási hiba | A tranzakciót, amelyben a felhívást végrehajtották, megszüntették, hogy elkerüljék a holtpontot. |
| 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 | A műveletet megszakították | Az aszinkron feldolgozás engedélyezve lett a StatementHandle-ben. A függvény meghívása megtörtént, é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 függvény ismét meghívásra került az Utasításkezelőben. A függvény meghívása megtörtént, és a végrehajtás befejezése előtt az SQLCancel vagy az SQLCancelHandle egy másik szálról lett meghívva a StatementHandle-ra egy többszálas alkalmazásból. |
| HY010 | Függvényütemezési hiba | (DM) A StatementHandle-hez társított kapcsolati leíróhoz aszinkron módon végrehajtó függvény lett meghívva. Ez az aszinkron függvény még akkor futott, amikor az SQLFetchScroll függvényt hívták. (DM) SQLExecute, SQLExecDirect vagy SQLMoreResults lett meghívva az Utasításkezelőhöz , és SQL_PARAM_DATA_AVAILABLE ad vissza. 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égrehajtott állapotban. A függvényt anélkül hívták, hogy előbb az SQLExecDirect, SQLExecute vagy egy katalógus függvény hívták volna meg. (DM) Egy aszinkron módon végrehajtó függvény (nem ez) lett meghívva az StatementHandle-hez , és a függvény meghívásakor továbbra is végrehajtó volt. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations vagy SQLSetPos lett meghívva az Utasításkezelőhöz , és 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 a StatementHandle miatt az SQLExtendedFetch hívása után és az SQLFreeStmt SQL_CLOSE opcióval való előhívása előtt lett meg. |
| 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 állítás attribútumát SQL_UB_VARIABLE-re állították, és a 0. oszlopot egy olyan pufferhez kötötték, amelynek hossza nem egyezett meg ennek az eredményhalmaznak a könyvjelző maximális hosszával. (Ez a hossz elérhető az IRD SQL_DESC_OCTET_LENGTH mezőjében, és SQLDescribeCol, SQLColAttribute vagy SQLGetDescField hívásával érhető el.) |
| HY106 | A hatótávolságon kívüli hívó típus | DM) A FetchOrientation argument értéke érvénytelen volt. (DM) A FetchOrientation érv SQL_FETCH_BOOKMARK volt, és a SQL_ATTR_USE_BOOKMARKS állítás attribútuma SQL_UB_OFF-re volt beállítva. A SQL_ATTR_CURSOR_TYPE állítás attribútumának értéke SQL_CURSOR_FORWARD_ONLY volt, és az érv FetchOrientation értéke nem volt SQL_FETCH_NEXT. A SQL_ATTR_CURSOR_SCROLLABLE állítás attribútumának értéke SQL_NONSCROLLABLE volt, és a FetchOrientation érv értéke nem volt SQL_FETCH_NEXT. |
| HY107 | Sor értéke a tartományon kívül | Az SQL_ATTR_CURSOR_TYPE állítás attribútumával megadott érték SQL_CURSOR_KEYSET_DRIVEN volt, de a SQL_ATTR_KEYSET_SIZE állítás attribútumával megadott érték nagyobb, mint 0, és kisebb volt a SQL_ATTR_ROW_ARRAY_SIZE állítás attribútumnál megadott értéknél. |
| HY111 | Érvénytelen könyvjelző érték | A FetchOrientation érv SQL_FETCH_BOOKMARK volt, és a SQL_ATTR_FETCH_BOOKMARK_PTR állítás attribútumában lévő érték által jelölt könyvjelző nem volt érvényes, vagy null mutató volt. |
| 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) A felfüggesztett állapotról további információt az SQLEndTran függvényben talál. |
| HYC00 | A választható funkció nem implementálva | Az illeszőr vagy adatforrás nem támogatja azt az átalakítást, amelyet az SQLBindColTargetType és a megfelelő oszlop SQL adattípusának kombinációja határoz meg. |
| HYT00 | Időtúllépés történt | 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úli időszakot SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT segítségével állítják be. |
| HYT01 | A kapcsolati időkorlát lejárt | 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 az SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT keresztül van beállítva. |
| IM001 | Az illesztőprogram nem támogatja ezt a függvényt | (DM) Az StatementHandle-hez társított illesztőprogram 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 | Az 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, az SQLCompleteAsync-et a leírón kell meghívni a művelet utófeldolgozásához és befejezéséhez. |
Comments
Az SQLFetchScroll egy meghatározott sorhalmazt ad vissza az eredményhalmazból. A sorhalmazok abszolút vagy relatív pozícióval, vagy könyvjelzővel határozhatók meg. Az SQLFetchScroll csak akkor hívható, amíg létezik eredményhalmaz – azaz egy hívás után, amely eredményhalmazt hoz létre, és mielőtt az adott eredményhalmaz kurzora lezárulna. Ha bármely oszlop be van kötve, visszaadja az adott oszlopokban lévő adatokat. Ha az alkalmazás kijelölt egy mutatót egy sorállapot tömbre vagy puffert, amelyben visszaadja a lehozott sorok számát, az SQLFetchScroll ezt az információt is visszaadja. Az SQLFetchScroll hívásai keverhetők SQLFetch hívásokkal, de nem keverhetők SQLExtendedFetch hívásokkal.
További információért lásd: Blokkkurzorok használata és görgethető kurzorok használata.
A kurzor elhelyezése
Amikor létrehozzák az eredményhalmazt, a kurzor az eredményhalmaz kezdete előtt helyezkedik el. Az SQLFetchScroll a blokk kurzort a FetchOrientation és FetchOffset argumentumok értékei alapján helyezi el, ahogy az alábbi táblázatban látható. Az új sorhalmaz kezdetének pontos szabályait a következő szakaszban mutatjuk be.
| FetchOrientation | Meaning |
|---|---|
| SQL_FETCH_NEXT | A következő sorkészletet add vissza. Ez egyenértékű azzal, mint az SQLFetch hívása. Az SQLFetchScroll figyelmen kívül hagyja a FetchOffset értékét. |
| SQL_FETCH_PRIOR | Adja vissza az előző sorkészletet. Az SQLFetchScroll figyelmen kívül hagyja a FetchOffset értékét. |
| SQL_FETCH_RELATIVE | Térítsd vissza a FetchOffset sorhalmazt a jelenlegi sorhalmaz elejéről. |
| SQL_FETCH_ABSOLUTE | A sorkészletet a FetchOffset sortól kezdve térítsd vissza. |
| SQL_FETCH_FIRST | A eredményhalmaz első sorhalmazát állítsd vissza. Az SQLFetchScroll figyelmen kívül hagyja a FetchOffset értékét. |
| SQL_FETCH_LAST | Visszaadja az utolsó teljes sorhalmazt az eredményhalmazban. Az SQLFetchScroll figyelmen kívül hagyja a FetchOffset értékét. |
| SQL_FETCH_BOOKMARK | A FetchOffset sorhalmazát a SQL_ATTR_FETCH_BOOKMARK_PTR utasítás attribútumja által megadott könyvjelzőből térítsd vissza. |
A sofőrök nem kötelesek minden fogási orientációt támogatniuk; egy alkalmazás az SQLGetInfo-t SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 vagy SQL_STATIC_CURSOR_ATTRIBUTES1 információtípussal hívja (a kurzor típusától függően), hogy meghatározza, mely betöltési orientációkat támogatja az illesztőprogram. Az alkalmazásnak meg kell vizsgálnia az SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE és WQL_CA1_BOOKMARK bitmaszkokat ezekben az információs típusokban. Továbbá, ha a kurzor csak előre halad, és a FetchOrientation nem SQL_FETCH_NEXT, akkor a SQLFetchScroll visszaadja az SQLSTATE HY106-ot (Fetch type out of range).
A SQL_ATTR_ROW_ARRAY_SIZE állítás attribútuma meghatározza a sorhalmazban lévő sorok számát. Ha az SQLFetchScroll által behozott sorhalmaz átfedi az eredményhalmaz végét, akkor az SQLFetchScroll részleges sorhalmazt ad vissza. Vagyis, ha S + R - 1 nagyobb, mint L, ahol S a lehozható sorhalmaz kezdő sora, R a sorhalmaz mérete, és L az eredményhalmaz utolsó sora, akkor csak az első L - S + 1 sor érvényes a sorhalmazból. A megmaradt sorok üresek, és SQL_ROW_NOROW státuszúak.
Miután visszatér az SQLFetchScroll , a jelenlegi sor a sorhalmaz első sora.
Kurzor pozicionálási szabályok
A következő szakaszok részletesen leírják a FetchOrientation minden értékének pontos szabályait. Ezek a szabályok a következő jelölést használják.
| Notation | Meaning |
|---|---|
| A 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, akkor a SQLFetchScroll SQL_NO_DATA-et ad vissza. |
| A vég után | A blokkkurzor az eredményhalmaz vége után helyezkedik el. Ha az új sorhalmaz első sora az eredményhalmaz vége után van, akkor a SQLFetchScroll SQL_NO_DATA-et ad vissza. |
| CurrRowsetStart | Az aktuális sorkészlet első sorának száma. |
| LastResultRow | Az eredményhalmaz utolsó sor száma. |
| Sorsorméret | A sorméret. |
| FetchOffset | A FetchOffset érv értéke. |
| BookmarkRow | Az a sor, amely a SQL_ATTR_FETCH_BOOKMARK_PTR állítás attribútumja által megadott könyvjelzőhöz tartozik. |
SQL_FETCH_NEXT
Az alábbi szabályok érvényesek.
| Condition | Az új sorkészlet első sora |
|---|---|
| A kezdés előtt | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | A vég után |
| A vég után | A vég után |
[1] Ha a sorhalmaz mérete változott az előző sorok hívása óta, ez az a sorhalmaz mérete, amelyet az előző hívásnál használtak.
SQL_FETCH_PRIOR
Az alábbi szabályok érvényesek.
| Condition | Az új sorkészlet első sora |
|---|---|
| A kezdés előtt | A kezdés előtt |
| CurrRowsetStart = 1 | A kezdés előtt |
| 1 < CurrRowsetStart <= RowsetSize[2] | 1[1] |
| CurrRowsetStart > Sorsorméret[2] | CurrRowsetStart - RowsetSize[2] |
| A vég ÉS a LastResultRow < után Sorsorméret[2] | 1[1] |
| A vég ÉS LastResultRow >= RowsetSize[2] után | LastResultRow - RowsetSize + 1[2] |
[1] Az SQLFetchScroll visszaadja az SQLSTATE 01S06-ot (Próbál beszerezni az eredményhalmaz előtt az első sorhalmazt) és SQL_SUCCESS_WITH_INFO.
[2] Ha a sorhalmaz mérete változott az előző sorok hívása óta, ez az új sorhalmaz méret.
SQL_FETCH_RELATIVE
Az alábbi szabályok érvényesek.
| Condition | Az új sorkészlet első sora |
|---|---|
| (Indítás előtt ÉS FetchOffset > 0) VAGY (Vég ÉS FetchOffset < 0 után) | -- [1] |
| BeforeStart ÉS FetchOffset <= 0 | A kezdés előtt |
| CurrRowsetStart = 1 ÉS FetchOffset < 0 | A kezdés előtt |
| CurrRowsetStart > 1 ÉS CurrRowsetStart + FetchOffset < 1 ÉS | FetchOffset | > SorsorMéret[3] | A kezdés előtt |
| CurrRowsetStart > 1 ÉS CurrRowsetStart + FetchOffset < 1 ÉS | FetchOffset | <= SorsorMéret[3] | 1[2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | A vég után |
| Vég után ÉS FetchOffset >= 0 | A vég után |
[1] Az SQLFetchScroll ugyanazt a sorhalmazt adja vissza, mintha a FetchOrientation SQL_FETCH_ABSOLUTE-ra állítva hívná. További információért lásd a "SQL_FETCH_ABSOLUTE" szakaszt.
[2] SQLFetchScroll visszaadja SQLSTATE 01S06-ot (Próbál beszerezni az eredményhalmaz előtti első sorhalmazt) és SQL_SUCCESS_WITH_INFO.
[3] Ha a sorhalmaz mérete változott az előző sorok lekérése óta, ez az új sorhalmaz méret.
SQL_FETCH_ABSOLUTE
Az alábbi szabályok érvényesek.
| Condition | Az új sorkészlet első sora |
|---|---|
| FetchOffset < 0 ÉS | FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 ÉS | FetchOffset | > LastResultRow ÉS | FetchOffset | > Sorsorméret[2] | A kezdés előtt |
| FetchOffset < 0 ÉS | FetchOffset | > LastResultRow ÉS | FetchOffset | <= Sorsorméret[2] | 1[1] |
| FetchOffset = 0 | A kezdés előtt |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | A vég után |
[1] Az SQLFetchScroll visszaadja az SQLSTATE 01S06-ot (Próbál beszerezni az eredményhalmaz előtt az első sorhalmazt) és SQL_SUCCESS_WITH_INFO.
[2] Ha a sorhalmaz mérete változott az előző sorok hívása óta, ez az új sorhalmaz méret.
Egy abszolút fetch, amelyet egy dinamikus kurzorral hajtanak végre, nem adja meg a szükséges eredményt, mert a dinamikus kurzor sorpozíciói nem határozzák meg. Egy ilyen művelet ekvivalens azzal, hogy először egy fetch relatív jön a fetch; Ez nem atomi művelet, ahogy az abszolút lehúzás egy statikus kurzoron.
SQL_FETCH_FIRST
Az alábbi szabályok érvényesek.
| Condition | Az új sorkészlet első sora |
|---|---|
| Bármely | 1 |
SQL_FETCH_LAST
Az alábbi szabályok érvényesek.
| Condition | Az új sorkészlet első sora |
|---|---|
| RowsetSize[1]<= LastResultRow | LastResultRow - RowsetSize + 1[1] |
| SorsorMéret[1]> VégeredménySor | 1 |
[1] Ha a sorhalmaz mérete megváltozott az előző sorok hívása óta, ez az új sorhalmaz méret.
SQL_FETCH_BOOKMARK
Az alábbi szabályok érvényesek.
| Condition | Az új sorkészlet első sora |
|---|---|
| BookmarkRow + FetchOffset < 1 | A kezdés előtt |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | A vég után |
A könyvjelzőkkel kapcsolatos információkért lásd: Könyvjelzők (ODBC) oldala.
A törölt, hozzáadott és hibasorok hatása a kurzormozgásra
A statikus és kulcskészlethez kötött kurzorok néha észlelik az eredményhalmazhoz hozzáadott sorokat, és eltávolítják az eredményhalmazból törölt sorokat. Az SQLGetInfo hívásával a SQL_STATIC_CURSOR_ATTRIBUTES2 és SQL_KEYSET_CURSOR_ATTRIBUTES2 opciókkal, valamint a SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS és SQL_CA2_SENSITIVITY_UPDATES bitmaszkok vizsgálatával az alkalmazás eldönti, hogy egy adott driver által implementált kurzorok ezt teszik-e. Azoknál a meghajtóknál, amelyek képesek azonosítani a törölt sorokat és eltávolítani azokat, a következő bekezdések írják le ennek a viselkedésnek a hatásait. Azoknál az illezővezetőknél, amelyek képesek felismerni a törölt sorokat, de nem tudják eltávolítani őket, a törlések nem befolyásolják a kurzormozgást, és a következő bekezdések nem érvényesek.
Ha a kurzor észleli az eredményhalmazhoz hozzáadott sorokat, vagy eltávolítja az eredményhalmazból törölt sorokat, úgy tűnik, hogy ezeket a változtatásokat csak akkor érzékeli, amikor adatokat kér. Ez magában foglalja azt az esetet is, amikor az SQLFetchScroll úgy hívjuk, hogy a FetchOrientation SQL_FETCH_RELATIVE-re, a FetchOffset 0-ra állítva visszamutassa ugyanazt a sorhalmazt, de nem tartalmazza azt az esetet, amikor az SQLSetPos-t fOption SQL_REFRESH-re állítva hívják. Ebben az esetben a sorhalmaz puffereiben lévő adatok frissülnek, de nem újrahasznosíthatók, és a törölt sorok nem kerülnek az eredményhalmazból. Így amikor egy sort törölnek vagy beillesztenek az aktuális sorhalmazba, a kurzor nem módosítja a sorhalmaz puffereit. Ehelyett akkor érzékeli a változást, amikor lekér bármely olyan sorhalmazt, amely korábban tartalmazta a törölt sort, vagy most tartalmazza a beillesztett sort.
Például:
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
Amikor a SQLFetchScroll egy új sorhalmazt ad vissza, amelynek pozíciója van a jelenlegi sorhalmazhoz képest – azaz a FetchOrientation SQL_FETCH_NEXT, SQL_FETCH_PRIOR vagy SQL_FETCH_RELATIVE –, akkor nem tartalmazza a jelenlegi sorhalmaz változásait az új sorhalmaz kezdő pozíciójának kiszámításakor. Ugyanakkor a jelenlegi sorhalmazon kívüli változásokat is tartalmaz, ha képes észlelni azokat. Továbbá, amikor az SQLFetchScroll egy új sorhalmazt ad vissza, amelynek pozíciója független az aktuális sorhalmaztól – azaz a FetchOrientation SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE vagy SQL_FETCH_BOOKMARK –, minden változást magában foglal, amit képes észlelni, még akkor is, ha azok a jelenlegi sorhalmazban vannak.
Amikor meghatározzuk, hogy az újonnan hozzáadott sorok a jelenlegi sorhalmazon belül vagy kívül vannak-e, egy részleges sorhalmazt úgy tekintünk, hogy az utolsó érvényes sorban végződik; vagyis az utolsó sor, amelynek státusza nem SQL_ROW_NOROW. Például, tegyük fel, hogy a kurzor képes felismerni az újonnan hozzáadott sorokat, a jelenlegi sorhalmaz részleges sorhalmaz, az alkalmazás új sorokat ad hozzá, és a kurzor ezeket a sorokat az eredményhalmaz végéhez adja. Ha az alkalmazás az SQLFetchScroll-t hívja SQL_FETCH_NEXT-re állítva a FetchOrientation-t, akkor a SQLFetchScroll visszaadja a sorhalmazt, amely az első újonnan hozzáadott sorral kezdve.
Például, tegyük fel, hogy a jelenlegi sorhalmaz a 21-től 30-ig terjedő sorokból áll, a sorhalmaz mérete 10, a kurzor eltávolítja az eredményhalmazból törölt sorokat, és a kurzor felismeri az eredményhalmazhoz hozzáadott sorokat. Az alábbi táblázat mutatja azokat a sorokat, amelyeket az SQLFetchScroll különböző helyzetekben visszaad.
| Módosítás | Fetch típus | FetchOffset | Új sorsorsor[1] |
|---|---|---|---|
| Töröld a 21. sort | KÖVETKEZŐ | 0 | 31-től 40-ig |
| Töröld a 31. sort | KÖVETKEZŐ | 0 | 32-től 41-ig |
| Helyezd be a sort a 21. és 22. sor közé | KÖVETKEZŐ | 0 | 31-től 40-ig |
| Helyezd be a sort a 30. és 31. sor közé | KÖVETKEZŐ | 0 | Beillesztett sor, 31–39. |
| Töröld a 21. sort | PRIOR | 0 | 11-től 20-ig |
| Töröld a 20. sort | PRIOR | 0 | 10-től 19-ig |
| Helyezd be a sort a 21. és 22. sor közé | PRIOR | 0 | 11-től 20-ig |
| Helyezd be a sort a 20. és 21. sor közé | PRIOR | 0 | 12-től 20-ig, beillesztett sor |
| Töröld a 21. sort | RELATÍV | 0 | 22–31[2] |
| Töröld a 21. sort | RELATÍV | 1 | 22–31 |
| Helyezd be a sort a 21. és 22. sor közé | RELATÍV | 0 | 21, beszúrt sor, 22–29 |
| Helyezd be a sort a 21. és 22. sor közé | RELATÍV | 1 | 22–31 |
| Töröld a 21. sort | ABSOLUTE | 21 | 22–31[2] |
| Töröld a 22. sort | ABSOLUTE | 21 | 21, 23 és 31 |
| Helyezd be a sort a 21. és 22. sor közé | ABSOLUTE | 22 | Beillesztett sor, 22–29. |
[1] Ez az oszlop a sorszámokat használja, mielőtt bármilyen sort beillesztettek vagy törölték volna.
[2] Ebben az esetben a kurzor megpróbálja visszaadni a 21. sorral kezdődő sorokat. Mivel a 21. sor törölve lett, az első sor, amit visszaad, a 22. sor.
A hibasorok (azaz SQL_ROW_ERROR státuszú sorok) nem befolyásolják a kurzor mozgását. Például, ha a jelenlegi sorhalmaz a 11. sorral kezdődik, és a 11. sor státusza SQL_ROW_ERROR, ha az SQLFetchScroll hívása a FetchOrientation SQL_FETCH_RELATIVE-re, a FetchOffset 5-re állítva pedig a 16. sorral induló sorhalmazt adja vissza, ahogy az lenne, ha a 11. sor státusza SQL_SUCCESS lenne.
Adatok visszaküldése kötött oszlopokban
Az SQLFetchScroll ugyanúgy adja vissza az adatokat kötött oszlopokban, mint az SQLFetch. További információért lásd: "Adatok visszaküldése kötött oszlopokban" az SQLFetch függvényben.
Ha nincs kijelölt oszlop, az SQLFetchScroll nem ad vissza adatokat, de a blokk kurzort a megadott pozícióba mozgatja. Az, hogy az adatok visszanyerhetők-e a blokk kurzor korlátlan oszlopaiból SQLGetData-val , az illesztőprogramtól függ. Ez a képesség akkor támogatott, ha az SQLGetInfo-hoz hívás visszaadja a SQL_GETDATA_EXTENSIONS információtípus SQL_GD_BLOCK bitjét.
Puffercímek
Az SQLFetchScroll ugyanazt a képletet használja az adatok címének és a hosszúság/indikátor pufferek meghatározására, mint az SQLFetch. További információért lásd: "Puffercímek" az SQLBindCol függvényben.
Sorállapot mezők tömbje
Az SQLFetchScroll ugyanúgy állít be értékeket a sor status tömbben, mint az SQLFetch. További információért lásd: "Sorállapot tömb" az SQLFetch függvényben.
Sorok Lehozott Puffer
Az SQLFetchScroll ugyanúgy adja vissza a sorok számát, amelyeket a sorok behozott pufferben is lehoznak. További információért lásd: "Sorok behozott puffer" az SQLFetch függvényben.
Hibakezelés
Amikor egy alkalmazás az ODBC 3.x illezserben az SQLFetchScroll-et hívja, a Driver Manager az illezőgépben az SQLFetchScroll-et hívja. Amikor egy alkalmazás az SQLFetchScroll-et hívja egy ODBC 2.x driverben, a Driver Manager az illezőgépben az SQLExtendedFetch-et hívja. Mivel az SQLFetchScroll és az SQLExtendedFetch kissé más módon kezeli a hibákat, az alkalmazás kissé eltérő hibaviselkedést tapasztal, amikor az SQLFetchScroll-t hívja az ODBC 2.x és az ODBC 3.x illesztőprogramokban.
Az SQLFetchScroll ugyanúgy adja vissza a hibákat és figyelmeztetéseket, mint az SQLFetch; További információért lásd: "Hibakezelés" az SQLFetch-ben. Az SQLExtendedFetch ugyanúgy ad vissza hibákat, mint az SQLFetch, a következő kivételekkel:
Amikor egy adott sorra vonatkozó figyelmeztetés történik, az SQLExtendedFetch a sorállapot tömbjében a megfelelő bejegyzést SQL_ROW_SUCCESS-re állítja be, nem SQL_ROW_SUCCESS_WITH_INFO-re.
Ha hiba történik minden sorban a sorhalmazban, az SQLExtendedFetch SQL_SUCCESS_WITH_INFO-et ad vissza, nem SQL_ERROR.
Minden egyes sorra vonatkozó státuszrekordcsoportban az SQLExtendedFetch által visszaadott első státuszrekordnak tartalmaznia kell SQLSTATE 01S01 (Error in sor); Az SQLFetchScroll nem adja vissza ezt az SQLSTATE-t. Ha az SQLExtendedFetch nem tud további SQLSTATE-eket visszaadni, akkor is vissza kell adnia ezt az SQLSTATE-et.
SQLFetchScroll és optimista egyidejű
Ha egy kurzor optimista egyidejű értéket használ – vagyis a SQL_ATTR_CONCURRENCY állítás attribútumának értéke SQL_CONCUR_VALUES vagy SQL_CONCUR_ROWVER –, a SQLFetchScroll frissíti az adatforrás által használt optimista egyidejű értékeket, hogy felismerje, változott-e egy sor. Ez akkor fordul elő, amikor az SQLFetchScroll új sorhalmazt hoz be, beleértve akkor is, amikor visszakapcsolja a jelenlegi sorhalmazt. (Úgy hívják, hogy a FetchOrientation SQL_FETCH_RELATIVE-re, a FetchOffset 0-ra van állítva.)
SQLFetchScroll és ODBC 2.x Driverek
Amikor egy alkalmazás az SQLFetchScroll-et hívja egy ODBC 2.x illezőgépben, a Driver Manager ezt a hívást az SQLExtendedFetch felé rendeli. Az alábbi értékeket továbbítja az SQLExtendedFetch argumentumaihoz.
| SQLExtendedFetch argument | Value |
|---|---|
| StatementHandle | StatementHandle in SQLFetchScroll. |
| FetchOrientation | FetchOrientation az SQLFetchScroll programban. |
| FetchOffset | Ha a FetchOrientation nem SQL_FETCH_BOOKMARK, akkor a FetchOffset argumentum értékét használják az SQLFetchScroll-ben . Ha a FetchOrientation SQL_FETCH_BOOKMARK, akkor a SQL_ATTR_FETCH_BOOKMARK_PTR állítás attribútuma által megadott címen tárolt értéket használják. |
| RowCountPtr | A SQL_ATTR_ROWS_FETCHED_PTR mondattribútumban megadott cím. |
| RowStatusArray | A SQL_ATTR_ROW_STATUS_PTR mondattribútumban megadott cím. |
További információkért lásd a Blokk kurzorok, görgethető kurzorok és visszamenőleges kompatibilitás részt a G függelékben: Illesztőprogramok útmutatója a visszamenőleges kompatibilitáshoz.
Descriptors és SQLFetchScroll
Az SQLFetchScroll ugyanúgy lép kölcsönhatásba a leírókkal, mint az SQLFetch. További információért lásd az SQLFetch Function "Descriptors and SQLFetchScroll" szakaszát.
Kódpélda
Lásd Column-Wise binding, Row-Wise binding, positioned update és delete utasításokat, valamint a sorok frissítését a sorhalmazban SQLSetPos-szal.
Kapcsolódó funkciók
| Információ erről: | Nézze |
|---|---|
| Puffer kötése egy eredményhalmaz oszlopához | SQLBindCol függvény |
| Tömeges behelyezési, frissítési vagy törlési műveletek végrehajtása | SQLBulkOperations Function |
| Utasításfeldolgozás megszakítása | SQLCancel függvény |
| Információ visszaküldése egy oszlopról az eredményhalmazban | 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 |
| Egy sor vagy adatblokk előrelépési irányban történő lekérése | SQLFetch függvény |
| A kurzor lezárása a kijelentésen | SQLFreeStmt függvény |
| Az eredményhalmaz oszlopainak számának visszaállítása | SQLNumResultCols függvény |
| A kurzor pozicionálása, az adatok frissítése a sorhalmazban, vagy az adatok frissítése vagy törlése az eredményhalmazban | SQLSetPos függvény |
| Utasításattribútum beállítása | SQLSetStmtAttr függvény |