SQLFetchScroll – funkce

Soulad
Představená verze: ODBC 3.0 Shoda s normami: ISO 92

Summary
SQLFetchScroll načítá zadanou sadu řádků dat z výsledné sady a vrací data pro všechny vázané sloupce. Sady řádků lze specifikovat na absolutní nebo relativní pozici, případně záložkou.

Při práci s ovladačem ODBC 2.x Driver Manager mapuje tuto funkci na SQLExtendedFetch. Pro více informací viz Funkce nahrazování mapování pro zpětnou kompatibilitu aplikací.

Syntax

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);

Arguments

StatementHandle
[Vstup] Popisovač příkazu

FetchOrientation
[Vstup]

Typ aportu:

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

Pro více informací viz "Umístění kurzoru" v sekci "Komentáře".

FetchOffset
[Vstup]

Číslo řádku k načtení. Interpretace tohoto argumentu závisí na hodnotě argumentu FetchOrientation . Pro více informací viz "Umístění kurzoru" v sekci "Komentáře".

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostika

Když SQLFetchScroll vrátí buď SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, pokud zavoláte SQLGetDiagRec s HandleType SQL_HANDLE_STMT a Handle CommandHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLFetchScroll běžně vrací, a vysvětluje každou z nich v kontextu této funkce; notace "(DM)" předchází popisům SQLstavů vráceným Správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak. Pokud se chyba objeví v jednom sloupci, lze SQLGetDiagField volat pomocí diagIdentifieru SQL_DIAG_COLUMN_NUMBER k určení sloupce, na kterém chyba nastala; a SQLGetDiagField lze volat pomocí DiagIdentifier SQL_DIAG_ROW_NUMBER pro určení řádku obsahujícího daný sloupec.

Pro všechny ty SQLSTATE, které mohou vrátit SQL_SUCCESS_WITH_INFO nebo SQL_ERROR (kromě 01xxx SQLSTATE), SQL_SUCCESS_WITH_INFO se vrací, pokud se chyba objeví na jednom nebo více, ale ne na všech, řádcích víceřádkové operace, a SQL_ERROR se vrací, pokud chyba nastane při jednořádkové operaci.

SQLSTATE Error Description
01000 Obecné upozornění Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
01004 Řetězcová data, zkrácená vpravo Řetězcová nebo binární data vrácená pro sloupec vedly k okrácení neprázdných znaků nebo ne-NULL binárních dat. Pokud se jednalo o řetězcovou hodnotu, byla zkrácena doprava.
01S01 Chyba v řádku Při načítání jednoho nebo více řádků došlo k chybě.

(Pokud je tento SQLSTATE vrácen, když aplikace ODBC 3*.x* pracuje s ovladačem ODBC 2*.x*, lze jej ignorovat.)
01S06 Pokus o načtení před výslednou sadou vrátil první řádkovou sadu Požadovaná sada řádků se překrývala se začátkem výsledné sady, když byla FetchOrientation SQL_FETCH_PRIOR, aktuální pozice byla za prvním řádkem a počet aktuálních řádků byl menší nebo roven velikosti řádku.

Požadovaná sada řádků se překrývala se začátkem výsledné množiny, když byla FetchOrientation SQL_FETCH_PRIOR, aktuální pozice byla za koncem výsledné sady a velikost řádku byla větší než velikost výsledné sady.

Požadovaná sada řádků se překrývala se začátkem výsledné množiny, když byla SQL_FETCH_RELATIVE FetchOrientation, FetchOffset záporná a absolutní hodnota FetchOffset byla menší nebo rovna velikosti řádku.

Požadovaná sada řádků se překrývala se začátkem výsledné množiny, když byla hodnota FetchOrientation SQL_FETCH_ABSOLUTE, FetchOffset záporná a absolutní hodnota FetchOffset byla větší než velikost výsledné množiny, ale menší nebo rovna velikosti řádkové sady.

(Funkce vrátí SQL_SUCCESS_WITH_INFO.)
01S07 Zlomkové zkrácení Data vrácená pro sloupec byla zkrácena. U číselných datových typů byla zlomková část čísla zkrácena. U datových typů s časovým, časovým razítkem a intervalem obsahujícími časovou složku byla zlomková část času zkrácena.

(Funkce vrátí SQL_SUCCESS_WITH_INFO.)
07006 Porušení atributu omezeného datového typu Datová hodnota sloupce ve výsledné sadě nemohla být převedena na datový typ specifikovaný TargetType v SQLBindCol.

Sloupec 0 byl přiřazen datovému typu SQL_C_BOOKMARK a atribut SQL_ATTR_USE_BOOKMARKS příkazu byl nastaven na SQL_UB_VARIABLE.

Sloupec 0 byl vázaný datovým typem SQL_C_VARBOOKMARK a atribut SQL_ATTR_USE_BOOKMARKS příkazu nebyl nastaven na SQL_UB_VARIABLE.
07009 Index neplatných deskriptorů Ovladač byl ODBC 2*.x* ovladač, který nepodporuje SQLExtendedFetch, a číslo sloupce uvedené ve vazbě pro sloupec bylo 0.

Sloupec 0 byl vázaný a atribut SQL_ATTR_USE_BOOKMARKS příkazu nastaven na SQL_UB_OFF.
08S01 Selhání komunikačního propojení Komunikační propojení mezi ovladačem a zdrojem dat, ke kterému byl ovladač připojen, selhalo před dokončením zpracování funkce.
22001 Řetězcová data, zkrácená vpravo Záložka s proměnnou délkou vrácená pro sloupec byla zkrácena.
22002 Požadovaná proměnná ukazatele, ale není zadána NULL data byla načítána do sloupce, jehož StrLen_or_IndPtr nastavený SQLBindCol (nebo SQL_DESC_INDICATOR_PTR nastavený SQLSetDescField či SQLSetDescRec) byl nullový ukazatel.
22003 Číselná hodnota mimo rozsah Vrácení číselné hodnoty (jako číselné nebo řetězcové) pro jeden nebo více vázaných sloupců by způsobilo zkrácení celé (na rozdíl od zlomkové) části čísla.

Pro více informací viz Převod dat ze SQL do C datových typů v příloze D: Datové typy.
22007 Neplatný formát data a času Sloupec znaků ve výsledné sadě byl vázán na strukturu datu, času nebo časového razítka C a hodnota ve sloupci byla neplatným datem, časem nebo časovým razítkem.
22012 Dělení nulou Byla vrácena hodnota z aritmetického výrazu, což vedlo k dělení nulou.
22015 Přetečení pole intervalu Přiřazení z přesného numerického nebo intervalového SQL typu k intervalovému typu C způsobovalo ztrátu významných číslic v vedoucím poli.

Při načítání dat na typ intervalu C nebyla v intervalu C zobrazena hodnota SQL typu.
22018 Neplatná hodnota znaku pro specifikaci přetypování Sloupec znaků v sadě výsledků byl vázán na buffer znaku C a sloupec obsahoval znak, pro který nebyla v sadě znaků bufferu žádná reprezentace.

Typ C byl přesná nebo přibližná číselná číslice, datový čas nebo intervalový datový typ; SQL typ sloupce byl datový typ znaku; a hodnota ve sloupci nebyla platným literálem vázaného typu C.
24000 Neplatný stav kurzoru CommandHandle byl ve stavu vykonání, ale žádná výsledná sada nebyla spojena s StatementHandle.
40001 Selhání serializace Transakce, při níž byl fetch proveden, byla ukončena, aby se zabránilo zablokování.
40003 Neznámé dokončování příkazů Přidružené připojení se nezdařilo během provádění této funkce a stav transakce nelze určit.
HY000 Obecná chyba Došlo k chybě, pro kterou nebyla definována žádná specifická funkce SQLSTATE a pro kterou nebyla definována žádná implementace sqlSTATE. Chybová zpráva vrácená nástrojem SQLGetDiagRec v vyrovnávací paměti *MessageText popisuje chybu a její příčinu.
HY001 Chyba přidělení paměti Ovladač nemohl přidělit paměť potřebnou k podpoře provádění nebo dokončení funkce.
HY008 Operace byla zrušena. Asynchronní zpracování bylo povoleno pro StatementHandle. Funkce byla volána a před dokončením provádění byla volána funkce SQLCancel nebo SQLCancelHandle pro PříkazHandle. Pak byla funkce znovu volána v StatementHandle.

Funkce byla volána a před dokončením provádění byla volána funkce SQLCancel neboSQLCancelHandlez jiného vlákna v aplikaci s více vlákny.
HY010 Chyba posloupnosti funkcí (DM) Byla volána asynchronně spuštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato asynchronní funkce se stále vykonávala, když byla volána funkce SQLFetchScroll .

(DM) SQLExecute, SQLExecDirect nebo SQLMoreResults byl volána pro StatementHandle a vrácena SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry.

(DM) Specifikovaný StatementHandle nebyl ve stavu vykonání. Funkce byla volána bez předchozího volání SQLExecDirect, SQLExecute nebo katalogové funkce.

(DM) Pro PříkazHandle byla volána asynchronně spuštěná funkce (ne tato) a při zavolání této funkce se stále spouštěla.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos byly volány pro StatementHandle a vráceny SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce.

(DM) SQLFetch byl volán pro StatementHandle po zavolání SQLExtendedFetch a před voláním SQLFreeStmt s možností SQL_CLOSE.
HY013 Chyba správy paměti Volání funkce nelze zpracovat, protože základní objekty paměti nelze získat přístup, pravděpodobně kvůli nedostatku paměti.
HY090 Neplatná délka řetězce nebo vyrovnávací paměti Atribut SQL_ATTR_USE_BOOKMARK příkazu byl nastaven na SQL_UB_VARIABLE a sloupec 0 byl vázán na buffer, jehož délka nebyla rovna maximální délce záložky pro tuto výslednou sadu. (Tato délka je dostupná v SQL_DESC_OCTET_LENGTH poli IRD a lze ji získat voláním SQLDescribeCol, SQLColAttribute nebo SQLGetDescField.)
HY106 Typ aportu mimo dosah DM) Hodnota zadaná pro argument FetchOrientation byla neplatná.

(DM) Argument FetchOrientation byl SQL_FETCH_BOOKMARK a atribut SQL_ATTR_USE_BOOKMARKS příkazu byl nastaven na SQL_UB_OFF.

Hodnota atributu SQL_ATTR_CURSOR_TYPE příkazu byla SQL_CURSOR_FORWARD_ONLY a hodnota argumentu FetchOrientation nebyla SQL_FETCH_NEXT.

Hodnota atributu SQL_ATTR_CURSOR_SCROLLABLE příkazu byla SQL_NONSCROLLABLE a hodnota argumentu FetchOrientation nebyla SQL_FETCH_NEXT.
HY107 Hodnota řádku mimo rozsah Hodnota zadaná atributem SQL_ATTR_CURSOR_TYPE příkazu byla SQL_CURSOR_KEYSET_DRIVEN, ale hodnota uvedená atributem SQL_ATTR_KEYSET_SIZE byla větší než 0 a menší než hodnota uvedená atributem SQL_ATTR_ROW_ARRAY_SIZE příkazu.
HY111 Neplatná hodnota záložek Argument FetchOrientation byl SQL_FETCH_BOOKMARK a záložka označená hodnotou v atributu SQL_ATTR_FETCH_BOOKMARK_PTR příkazu nebyla platná nebo byla nulovým ukazatelem.
HY117 Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení. (DM) Další informace o pozastaveném stavu naleznete v tématu FUNKCE SQLEndTran.
HYC00 Nepovinná funkce není implementována. Ovladač nebo zdroj dat nepodporuje převod specifikovaný kombinací TargetType v SQLBindCol a SQL datového typu příslušného sloupce.
HYT00 Vypršel časový limit. Vypršení časového limitu dotazu vypršelo, než zdroj dat vrátil požadovanou sadu výsledků. Doba vypršení času je nastavena pomocí SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Vypršel časový limit připojení Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Časový limit připojení je nastavený prostřednictvím sqlSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Ovladač tuto funkci nepodporuje. (DM) Ovladač přidružený k StatementHandle nepodporuje funkci.
IM017 Dotazování je zakázané v asynchronním režimu oznámení. Při každém použití modelu oznámení je dotazování zakázané.
IM018 K dokončení předchozí asynchronní operace na tomto popisovači nebyla volána funkce SQLCompleteAsync. Pokud předchozí volání funkce na popisovači vrátí SQL_STILL_EXECUTING a pokud je povolen režim oznámení, musí být sqlCompleteAsync volán na popisovači, aby bylo možné provést následné zpracování a dokončit operaci.

Comments

SQLFetchScroll vrací specifikovanou sadu řádků z výsledné množiny. Sady řádků lze specifikovat absolutní nebo relativní pozicí, případně záložkou. SQLFetchScroll lze volat pouze v době, kdy existuje výsledná množina – tedy po volání, které vytváří výslednou množinu, a před uzavřením kurzoru nad touto množinou výsledků. Pokud jsou některé sloupce vázané, vrátí data v těchto sloupcích. Pokud aplikace specifikovala ukazatel na pole stavů řádků nebo buffer, do kterého se vrací počet načtených řádků, SQLFetchScroll tuto informaci také vrátí. Volání SQLFetchScroll lze kombinovat s voláním SQLFetch , ale nelze je kombinovat s voláním SQLExtendedFetch.

Pro více informací viz Používání blokových kurzorů a Používání posuvných kurzorů.

Umístění kurzoru

Když je výsledná množina vytvořena, kurzor je umístěn před začátkem výsledné množiny. SQLFetchScroll umisťuje blokový kurzor na základě hodnot argumentů FetchOrientation a FetchOffset , jak je uvedeno v následující tabulce. Přesná pravidla pro určení začátku nové sady řádků jsou uvedena v následující sekci.

FetchOrientation Meaning
SQL_FETCH_NEXT Vraťte další sadu řádků. To je ekvivalent volání SQLFetch.

SQLFetchScroll ignoruje hodnotu FetchOffset.
SQL_FETCH_PRIOR Vraťte předchozí sadu řádků.

SQLFetchScroll ignoruje hodnotu FetchOffset.
SQL_FETCH_RELATIVE Vraťte sadu řádků FetchOffset od začátku aktuální sady řádků.
SQL_FETCH_ABSOLUTE Vraťte sadu řádků začínající řádkem FetchOffset.
SQL_FETCH_FIRST Vraťte první řádkovou sadu ve výsledné sadě.

SQLFetchScroll ignoruje hodnotu FetchOffset.
SQL_FETCH_LAST Vraťte poslední kompletní sadu řádků ve výsledné množině.

SQLFetchScroll ignoruje hodnotu FetchOffset.
SQL_FETCH_BOOKMARK Vraťte řádky FetchOffset z záložky určené atributem SQL_ATTR_FETCH_BOOKMARK_PTR příkazu.

Ovladače nemusí podporovat všechny orientace načítaní; aplikace volá SQLGetInfo s informačním typem SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 nebo SQL_STATIC_CURSOR_ATTRIBUTES1 (v závislosti na typu kurzoru), aby určila, které orientace načítaní jsou ovladačem podporovány. Aplikace by měla zkoumat bitmasky SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE a WQL_CA1_BOOKMARK v těchto typech informací. Dále, pokud je kurzor pouze pro dopředání a FetchOrientation není SQL_FETCH_NEXT, SQLFetchScroll vrací SQLSTATE HY106 (Fetch typ mimo dosah).

Atribut SQL_ATTR_ROW_ARRAY_SIZE příkazu určuje počet řádků v sadě řádků. Pokud se řádková sada načítaná pomocí SQLFetchScroll překrývá s koncem výsledné množiny, SQLFetchScroll vrátí částečnou sadu řádků. To znamená, že pokud S + R - 1 je větší než L, kde S je počáteční řádek načítané sady, R je velikost řádku a L je poslední řádek ve výsledné množině, pak platí pouze první řádky L - S + 1 v této sadě. Zbývající řádky jsou prázdné a mají stav SQL_ROW_NOROW.

Po návratu SQLFetchScroll je aktuální řádek prvním řádkem sady řádků.

Pravidla pro umístění kurzoru

Následující sekce popisují přesná pravidla pro každou hodnotu FetchOrientation. Tato pravidla používají následující notaci.

Notace Meaning
Před začátkem Blokový kurzor je umístěn před začátkem výsledné množiny. Pokud je první řádek nové sady řádků před začátkem výsledné množiny, SQLFetchScroll vrátí SQL_NO_DATA.
Po konci Blokový kurzor je umístěn za koncem výsledné množiny. Pokud je první řádek nové sady řádků za koncem výsledné sady, SQLFetchScroll vrátí SQL_NO_DATA.
CurrRowsetStart Číslo prvního řádku v aktuální sadě řádků.
LastResultRow Číslo posledního řádku v množině výsledků.
RowsetSize Velikost řádku.
FetchOffset Hodnota argumentu FetchOffset .
BookmarkRow Řádek odpovídající záložce určené atributem SQL_ATTR_FETCH_BOOKMARK_PTR příkazu.

SQL_FETCH_NEXT

Platí následující pravidla.

Podmínka První řádek nové sady řádků
Před začátkem 1
CurrRowsetStart + RowsetSize[1] <= LastResultRow CurrRowsetStart + RowsetSize[1]
CurrRowsetStart + RowsetSize[1]> LastResultRow Po konci
Po konci Po konci

[1] Pokud byla velikost řádku změněna od předchozího volání pro načtení řádků, toto je velikost řádku, která byla použita při předchozím volání.

SQL_FETCH_PRIOR

Platí následující pravidla.

Podmínka První řádek nové sady řádků
Před začátkem Před začátkem
CurrRowsetStart = 1 Před začátkem
1 < CurrRowsetStart <= RowsetSize[2] 1[1]
CurrRowsetStart > RowsetSize[2] CurrRowsetStart - RowsetSize[2]
Po konci A PoslednímVýsledkuŘádku < RowsetSize[2] 1[1]
Po konci A poslednímVýsledkuŘádku >= Velikost řádku[2] LastResultRow - RowsetSize + 1[2]

[1] SQLFetchScroll vrací SQLSTATE 01S06 (pokus o načtení před vrácením výsledné sady první řádku) a SQL_SUCCESS_WITH_INFO.

[2] Pokud byla velikost řádku změněna od předchozího volání pro načtení řádků, jedná se o novou velikost řádku.

SQL_FETCH_RELATIVE

Platí následující pravidla.

Podmínka První řádek nové sady řádků
(Před startem A FetchOffset > 0) NEBO (Po konci A FetchOffset < 0) -- [1]
BeforeStart A FetchOffset <= 0 Před začátkem
CurrRowsetStart = 1 AND FetchOffset < 0 Před začátkem
CurrRowsetStart > 1 A CurrRowsetStart + FetchOffset < 1 A | FetchOffset | > RowsetSize[3] Před začátkem
CurrRowsetStart > 1 A CurrRowsetStart + FetchOffset < 1 A | FetchOffset | <= RowsetSize[3] 1[2]
1 <= CurrRowsetStart + FetchOffset <= LastResultRow CurrRowsetStart + FetchOffset
CurrRowsetStart + FetchOffset > LastResultRow Po konci
Po konci AND FetchOffset >= 0 Po konci

[1] SQLFetchScroll vrací stejnou sadu řádků, jako by byla volána s nastavením FetchOrientation na SQL_FETCH_ABSOLUTE. Pro více informací viz sekce "SQL_FETCH_ABSOLUTE".

[2] SQLFetchScroll vrací SQLSTATE 01S06 (pokus o načtení před vrácením výsledné sady první řádku) a SQL_SUCCESS_WITH_INFO.

[3] Pokud byla velikost řádků změněna od předchozího volání pro načtení řádků, jedná se o novou velikost řádku.

SQL_FETCH_ABSOLUTE

Platí následující pravidla.

Podmínka První řádek nové sady řádků
FetchOffset < 0 A | FetchOffset | <= PosledníVýsledekŘádek LastResultRow + FetchOffset + 1
FetchOffset < 0 A | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize[2] Před začátkem
FetchOffset < 0 A | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize[2] 1[1]
FetchOffset = 0 Před začátkem
1 <= FetchOffset <= LastResultRow FetchOffset
FetchOffset > LastResultRow Po konci

[1] SQLFetchScroll vrací SQLSTATE 01S06 (pokus o načtení před vrácením výsledné sady první řádku) a SQL_SUCCESS_WITH_INFO.

[2] Pokud byla velikost řádku změněna od předchozího volání pro načtení řádků, jedná se o novou velikost řádku.

Absolutní načtení provedené proti dynamickému kurzoru nemůže poskytnout požadovaný výsledek, protože pozice řádků v dynamickém kurzoru nejsou určeny. Taková operace je ekvivalentní fetch nejprve následovanému fetch relativem; Není to atomická operace, jako je absolutní načtení na statickém kurzoru.

SQL_FETCH_FIRST

Platí následující pravidla.

Podmínka První řádek nové sady řádků
Jakýkoliv 1

SQL_FETCH_LAST

Platí následující pravidla.

Podmínka První řádek nové sady řádků
RowsetSize[1]<= LastResultRow LastResultRow - RowsetSize + 1[1]
RowsetSize[1]> LastResultRow 1

[1] Pokud byla velikost řádků změněna od předchozího volání pro načtení řádků, jedná se o novou velikost řádků.

SQL_FETCH_BOOKMARK

Platí následující pravidla.

Podmínka První řádek nové sady řádků
BookmarkRow + FetchOffset < 1 Před začátkem
1 <= BookmarkRow + FetchOffset <= LastResultRow BookmarkRow + FetchOffset
BookmarkRow + FetchOffset > LastResultRow Po konci

Informace o záložkách najdete v článku Záložky (ODBC).

Vliv smazaných, přidaných a chybových řádků na pohyb kurzoru

Statické a klíčové kurzory někdy detekují řádky přidané do výsledné množiny a odstraňují řádky smazané z výsledné množiny. Voláním SQLGetInfo s možnostmi SQL_STATIC_CURSOR_ATTRIBUTES2 a SQL_KEYSET_CURSOR_ATTRIBUTES2 a prohlížením bitových masek SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS a SQL_CA2_SENSITIVITY_UPDATES aplikace určí, zda kurzory implementované konkrétním ovladačem toto dělají. U ovladačů, které dokážou detekovat smazané řádky a odstranit je, následující odstavce popisují účinky tohoto chování. U ovladačů, které dokážou detekovat smazané řádky, ale nemohou je odstranit, nemají vymazání žádný vliv na pohyb kurzoru a následující odstavce se nevztahují.

Pokud kurzor detekuje řádky přidané do výsledné množiny nebo odstraní řádky smazané z výsledné množiny, zdá se, že tyto změny detekuje pouze při načítání dat. To zahrnuje případ, kdy je SQLFetchScroll volán s nastavením FetchOrientation na SQL_FETCH_RELATIVE a FetchOffset na 0 pro opětovné načtení stejné sady řádků, ale nezahrnuje případ, kdy je SQLSetPos volán s fOption nastaveným na SQL_REFRESH. V druhém případě jsou data v bufferech řádků obnovena, ale nejsou znovu načtena, a smazané řádky nejsou z výsledné sady odstraněny. Když je tedy řádek smazán nebo vložen do aktuální sady řádků, kurzor nemění řádkové vyrovnávací paměti. Místo toho detekuje změnu při načtení libovolné sady řádků, která dříve obsahovala smazaný řádek, nebo nyní obsahuje vložený řádek.

Příklady:

// 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);

Když SQLFetchScroll vrátí novou sadu řádků, která má pozici vzhledem k aktuální sadě řádků – tedy FetchOrientation je SQL_FETCH_NEXT, SQL_FETCH_PRIOR nebo SQL_FETCH_RELATIVE – nezahrnuje změny v aktuální sadě řádků při výpočtu počáteční pozice nové sady řádků. Nicméně zahrnuje změny mimo aktuální řádkovou sadu, pokud je schopna je detekovat. Dále, když SQLFetchScroll vrátí novou sadu řádků, která má pozici nezávislou na aktuální sadě řádků – tedy FetchOrientation je SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE nebo SQL_FETCH_BOOKMARK – zahrnuje všechny změny, které je schopen detekovat, i když jsou v aktuální sadě řádků.

Při určování, zda nově přidané řádky jsou uvnitř nebo vně aktuální sady řádků, se částečná sada řádků považuje za končící posledním platným řádkem; tedy poslední řádek, pro který není stav řádku SQL_ROW_NOROW. Například předpokládejme, že kurzor je schopen detekovat nově přidané řádky, aktuální sada řádků je částečná, aplikace přidá nové řádky a kurzor přidá tyto řádky na konec výsledné množiny. Pokud aplikace zavolá SQLFetchScroll s nastavením FetchOrientation na SQL_FETCH_NEXT, SQLFetchScroll vrátí sadu řádků začínající prvním nově přidaným řádkem.

Například předpokládejme, že aktuální sada řádků obsahuje řádky 21 až 30, velikost řádku je 10, kurzor odstraní řádky smazané z výsledné množiny a kurzor detekuje řádky přidané do výsledné množiny. Následující tabulka ukazuje řádky, které SQLFetchScroll vrací v různých situacích.

Změnit Fetch typ FetchOffset Nová sada řad[1]
Smazat řádek 21 NEXT 0 31 až 40
Smazat řádek 31 NEXT 0 32 až 41
Vložte řádek mezi řádky 21 a 22 NEXT 0 31 až 40
Vložte řádek mezi řádky 30 a 31 NEXT 0 Vložený řádek, 31 až 39
Smazat řádek 21 PRIOR 0 11 až 20
Smazat řádek 20 PRIOR 0 10 až 19
Vložte řádek mezi řádky 21 a 22 PRIOR 0 11 až 20
Vložte řádek mezi řádky 20 a 21 PRIOR 0 12 až 20, vložený řádek
Smazat řádek 21 RELATIVNÍ 0 22 až 31[2]
Smazat řádek 21 RELATIVNÍ 1 22 až 31
Vložte řádek mezi řádky 21 a 22 RELATIVNÍ 0 21, vložený řádek, 22 až 29
Vložte řádek mezi řádky 21 a 22 RELATIVNÍ 1 22 až 31
Smazat řádek 21 ABSOLUTE 21 22 až 31[2]
Smazat řádek 22 ABSOLUTE 21 21, 23 až 31
Vložte řádek mezi řádky 21 a 22 ABSOLUTE 22 Vložený řádek, 22 až 29

[1] Tento sloupec používá čísla řádků před vložením nebo odstraněním řádků.

[2] V tomto případě se kurzor snaží vrátit řádky začínající řádkem 21. Protože byl smazán řádek 21, první řádek, který vrací, je řádek 22.

Chybové řádky (tedy řádky se stavem SQL_ROW_ERROR) neovlivňují pohyb kurzoru. Například pokud aktuální řádková sada začíná řádkem 11 a stav řádku 11 je SQL_ROW_ERROR, volání SQLFetchScroll s nastavením FetchOrientation na SQL_FETCH_RELATIVE a FetchOffset na 5 vrátí řádkovou sadu začínající řádkem 16, stejně jako by to bylo v případě, že by byl stav řádku 11 SQL_SUCCESS.

Vrácení dat ve vázaných sloupcích

SQLFetchScroll vrací data ve vázaných sloupcích stejným způsobem jako SQLFetch. Pro více informací viz "Vrácení dat ve vázaných sloupcích" v SQLFetch Function.

Pokud nejsou vázány žádné sloupce, SQLFetchScroll nevrátí data, ale přesune blokový kurzor na zadanou pozici. Zda lze data získat z nevázaných sloupců blokového kurzoru pomocí SQLGetData , závisí na konkrétním ovladači. Tato schopnost je podporována, pokud volání SQLGetInfo vrátí SQL_GD_BLOCK bit pro typ SQL_GETDATA_EXTENSIONS informace.

Adresy bufferů

SQLFetchScroll používá stejný vzorec pro určení adresy dat a bufferů délky/indikátorů jako SQLFetch. Pro více informací viz "Buffer Addresses" v SQLBindCol Function.

Pole stavu řádku

SQLFetchScroll nastavuje hodnoty v řádkovém stavovém poli stejným způsobem jako SQLFetch. Pro více informací viz "Row Status Array" v SQLFetch Function.

Řádky načítané buffer

SQLFetchScroll vrací počet řádků načtených v bufferu načítaných řádků stejným způsobem jako SQLFetch. Pro více informací viz "Řádky načítané buffer" ve funkci SQLFetch.

Zpracování chyb

Když aplikace volá SQLFetchScroll v ovladači ODBC 3.x, správce ovladačů volá SQLFetchScroll v ovladači. Když aplikace volá SQLFetchScroll v ovladači ODBC 2.x, správce ovladačů volá SQLExtendedFetch v ovladači. Protože SQLFetchScroll a SQLExtendedFetch zpracovávají chyby trochu odlišně, aplikace zaznamenává mírně odlišné chování chyb při volání SQLFetchScroll v ovladačích ODBC 2.x a ODBC 3.x.

SQLFetchScroll vrací chyby a varování stejným způsobem jako SQLFetch; pro více informací viz "Zpracování chyb" v SQLFetch. SQLExtendedFetch vrací chyby stejným způsobem jako SQLFetch, s následujícími výjimkami:

Když nastane varování, které se vztahuje na konkrétní řádek v sadě řádků, SQLExtendedFetch nastaví odpovídající položku v řádkovém stavovém poli na SQL_ROW_SUCCESS, nikoli na SQL_ROW_SUCCESS_WITH_INFO.

Pokud se chyby vyskytnou v každém řádku v sadě řádků, SQLExtendedFetch vrátí SQL_SUCCESS_WITH_INFO, nikoli SQL_ERROR.

V každé skupině stavových záznamů, která se vztahuje na jednotlivý řádek, musí první stavový záznam vrácený SQLExtendedFetch obsahovat SQLSTATE 01S01 (Chyba v řádku); SQLFetchScroll tento SQLSTATE nevrací. Pokud SQLExtendedFetch není schopen vrátit další SQLstavy, musí tento SQLSTATE vrátit.

SQLFetchScroll a optimistická souběžnost

Pokud kurzor používá optimistickou souběžnost – tedy atribut SQL_ATTR_CONCURRENCY příkazu má hodnotu SQL_CONCUR_VALUES nebo SQL_CONCUR_ROWVER – SQLFetchScroll aktualizuje optimistické hodnoty souběžnosti používané datovým zdrojem k detekci, zda se řádek změnil. To se děje vždy, když SQLFetchScroll načítá novou sadu řádků, včetně opětovného načítání aktuální sady řádků. (Je volán s nastavením FetchOrientation na SQL_FETCH_RELATIVE a FetchOffset na 0.)

Ovladače SQLFetchScroll a ODBC 2.x

Když aplikace volá SQLFetchScroll v ovladači ODBC 2.x, Driver Manager tuto volbu mapuje na SQLExtendedFetch. Předává následující hodnoty pro argumenty SQLExtendedFetch.

SQLExtendedFetch argument Value
StatementHandle StatementHandle v SQLFetchScroll.
FetchOrientation FetchOrientation v SQLFetchScroll.
FetchOffset Pokud FetchOrientation není SQL_FETCH_BOOKMARK, použije se hodnota argumentu FetchOffset v SQLFetchScroll .

Pokud je FetchOrientation SQL_FETCH_BOOKMARK, použije se hodnota uložená na adrese určené atributem SQL_ATTR_FETCH_BOOKMARK_PTR příkazu.
RowCountPtr Adresa určená atributem SQL_ATTR_ROWS_FETCHED_PTR příkazu.
RowStatusArray Adresa specifikovaná atributem SQL_ATTR_ROW_STATUS_PTR výroku.

Další informace naleznete v části Block Cursors, Scrollable Cursors, and Backward Compatibility v Příloze G: Pokyny pro ovladače k zpětné kompatibilitě.

Descriptors a SQLFetchScroll

SQLFetchScroll pracuje s deskriptory stejným způsobem jako SQLFetch. Pro více informací viz sekce "Descriptors and SQLFetchScroll" v SQLFetch Function.

Příklad kódu

Viz Column-Wise Binding, Row-Wise binding, positioned update a delete příkazy a aktualizace řádků v sadě řádků pomocí SQLSetPos.

Informace o Podívejte se
Vytvoření vazby vyrovnávací paměti ke sloupci v sadě výsledků SQLBindCol – funkce
Provádění hromadných operací vkládání, aktualizace nebo mazání SQLBulkOperations Function
Zrušení zpracování příkazů SQLCancel – funkce
Vrácení informací o sloupci v množině výsledků SQLDescribeCol Function
Provádění SQL příkazu SQLExecDirect Function
Spuštění připraveného příkazu SQL FUNKCE SQLExecute
Načítání jednoho řádku nebo bloku dat pouze ve směru dopředu Funkce SQLFetch
Zavření kurzoru na výkazu FUNKCE SQLFreeStmt
Vrácení počtu sloupců výsledků SQLNumResultCols Function
Umístění kurzoru, obnovení dat v sadě řádků nebo aktualizace či mazání dat ve výsledné sadě Funkce SQLSetPos
Nastavení atributu příkazu FUNKCE SQLSetStmtAttr

Související obsah

  • Last updated on