Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
shoda
Zavedená verze: Dodržování standardů ODBC 1.0: ISO 92
Shrnutí
SQLFetch načte další sadu řádků dat ze sady výsledků a vrátí data pro všechny vázané sloupce.
Syntaxe
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Argumenty
StatementHandle
[Vstup] Popisovač příkazu
Návraty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.
Diagnostika
Když funkce SQLFetch vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze přidruženou hodnotu SQLSTATE získat voláním funkce SQLGetDiagRec s HandleType SQL_HANDLE_STMT a popisovačemStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které obvykle vrací funkce SQLFetch , a vysvětluje je v kontextu této funkce; notace "(DM)" předchází popisy funkcí SQLSTATEs vrácených správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak. Pokud dojde k chybě v jednom sloupci, sqlGetDiagField lze volat pomocí DiagIdentifier SQL_DIAG_COLUMN_NUMBER určit sloupec, na který došlo k chybě; a SQLGetDiagField lze volat pomocí DiagIdentifier SQL_DIAG_ROW_NUMBER určit řádek, který obsahuje daný sloupec.
Pro všechny tyto funkce SQLSTATEs, které můžou vrátit SQL_SUCCESS_WITH_INFO nebo SQL_ERROR (s výjimkou 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO se vrátí, pokud dojde k chybě u jedné nebo více, ale ne všechny řádky operace s více řádky a SQL_ERROR se vrátí, pokud dojde k chybě u operace s jedním řádkem.
| SQLSTATE | Chyba | Popis |
|---|---|---|
| 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 způsobila zkrácení neprázdného znaku nebo binárních dat bez hodnoty NULL. 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 se tento stav SQLSTATE vrátí, když aplikace ODBC 3*.x* pracuje s ovladačem ODBC 2*.x*, lze jej ignorovat.) |
| 01S07 | Zlomkové zkrácení | Data vrácená pro sloupec byla zkrácena. U číselných datových typů byla zlomková část čísla zkrácena. Pro časové razítko a datové typy intervalů, které obsahují časovou komponentu, byla zlomková část času zkrácena. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 07006 | Porušení atributu omezeného datového typu | Datovou hodnotu sloupce v sadě výsledků nelze převést na datový typ zadaný typem TargetType v SQLBindCol. Sloupec 0 byl svázán s datovým typem SQL_C_BOOKMARK a atribut příkazu SQL_ATTR_USE_BOOKMARKS byl nastaven na SQL_UB_VARIABLE. Sloupec 0 byl svázán s datovým typem SQL_C_VARBOOKMARK a atribut příkazu SQL_ATTR_USE_BOOKMARKS nebyl nastaven na SQL_UB_VARIABLE. |
| 07009 | Neplatný index popisovače | Ovladač byl ovladač ODBC 2*.x*, který nepodporuje sqlExtendedFetch, a číslo sloupce zadané ve vazbě pro sloupec bylo 0. Sloupec 0 byl vázaný a atribut příkazu SQL_ATTR_USE_BOOKMARKS byl 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 | Data NULL byla načtena do sloupce, jehož StrLen_or_IndPtr nastavena sqlBindCol (nebo SQL_DESC_INDICATOR_PTR nastavena sqlSetDescField nebo SQLSetDescRec) byla nulový ukazatel. |
| 22003 | Číselná hodnota mimo rozsah | Vrácení číselné hodnoty jako číselného nebo řetězce pro jeden nebo více vázaných sloupců by způsobilo zkrácení celé části čísla (na rozdíl od zlomků). Další informace naleznete v tématu Převod dat z SQL na datové typy jazyka C v dodatku D: Datové typy. |
| 22007 | Neplatný formát data a času | Sloupec znaků v sadě výsledků byl vázán na strukturu jazyka C data, času nebo časového razítka a hodnota ve sloupci byla neplatné datum, čas nebo časové razítko. |
| 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 číselného nebo intervalového typu SQL k typu intervalu jazyka C způsobilo ztrátu významných číslic v úvodním poli. Při načítání dat do typu intervalu jazyka C neexistovala žádná reprezentace hodnoty typu SQL v typu interval C. |
| 22018 | Neplatná hodnota znaku pro specifikaci přetypování | Sloupec znaků v sadě výsledků byl vázán na vyrovnávací paměť znaku C a sloupec obsahoval znak, pro který nebyla v znakové sadě vyrovnávací paměti žádná reprezentace. Typ C byl přesný nebo přibližný číselný typ, datum a čas nebo datový typ intervalu; typ SQL sloupce byl datový typ znaku; a hodnota ve sloupci nebyla platným literálem vázaného typu C. |
| 24000 | Neplatný stav kurzoru | PříkazHandle byl ve spuštěném stavu, ale žádná sada výsledků nebyla přidružena k StatementHandle. |
| 40001 | Selhání serializace | Transakce, ve které byla načtena byla provedena, byla ukončena, aby se zabránilo vzájemnému 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á sqlGetDiagRec v *MessageText vyrovnávací paměti popisuje chybu a její příčinu. |
| HY001 | Chyba přidělení paměti | Ovladač nemohl přidělit paměť, která je nutná k podpoře provádění nebo dokončování funkce. |
| HY008 | Operace byla zrušena. | Asynchronní zpracování bylo povoleno pro StatementHandle. Byla volána funkce SQLFetch a před dokončením provádění byla volána funkce SQLCancel neboSQLCancelHandle pro PříkazHandle. Potom byla funkce SQLFetch znovu volána na StatementHandle. Nebo byla volána funkce SQLFetch 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ě spouštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato asynchronní funkce se stále spouštěla, když byla volána funkce SQLFetch . (DM) (DM) Zadaný StatementHandle nebyl ve spuštěném stavu. Funkce byla volána bez prvního volání SQLExecDirect, SQLExecute nebo funkce katalogu. (DM) Pro (DM) (DM) SqlFetch byl volána pro StatementHandle po volání SQLExtendedFetch a před SQLFreeStmt s SQL_CLOSE možnost byla volána. |
| 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 příkazu SQL_ATTR_USE_BOOKMARK byl nastaven na SQL_UB_VARIABLE a sloupec 0 byl vázán na vyrovnávací paměť, jejíž délka nebyla rovna maximální délce záložky pro tuto sadu výsledků. (Tato délka je k dispozici v poli SQL_DESC_OCTET_LENGTH IRD a lze ji získat voláním SQLDescribeCol, SQLColAttribute nebo SQLGetDescField.) |
| HY107 | Hodnota řádku mimo rozsah | Hodnota zadaná atributem příkazu SQL_ATTR_CURSOR_TYPE byla SQL_CURSOR_KEYSET_DRIVEN, ale hodnota zadaná atributem příkazu SQL_ATTR_KEYSET_SIZE byla větší než 0 a menší než hodnota zadaná atributem příkazu SQL_ATTR_ROW_ARRAY_SIZE. |
| 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 určený kombinací TargetType v SQLBindCol a datový typ SQL odpovídající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ů. Časový limit je nastavený prostřednictvím sqlSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Vypršení časového limitu připojení | Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Doba časového limitu připojení je nastavena prostřednictvím SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Ovladač tuto funkci nepodporuje. | (DM) Ovladač přidružený k StatementHandle funkci nepodporuje. |
| 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 | sqlCompleteAsync nebyl volán k dokončení předchozí asynchronní operace na tomto popisovači. | Pokud předchozí volání funkce na popisovači vrátí SQL_STILL_EXECUTING a pokud je povolený režim oznámení, SQLCompleteAsync musí být volána v popisovači, aby bylo možné provést následné zpracování a dokončit operaci. |
Komentáře
Funkce SQLFetch vrátí další sadu řádků v sadě výsledků. Lze ji volat pouze v případě, že existuje sada výsledků: to znamená po volání, které vytvoří sadu výsledků a před zavřeným kurzorem na tuto sadu výsledků. Pokud jsou některé sloupce vázané, vrátí data v těchto sloupcích. Pokud aplikace zadala ukazatel na pole stavu řádku nebo vyrovnávací paměť, ve které se má vrátit počet načtených řádků, vrátí funkce SQLFetch také tyto informace. Volání sqlFetch lze kombinovat s voláními SQLFetchScroll , ale nelze je kombinovat s voláními SQLExtendedFetch. Další informace najdete v tématu Načtení řádku dat.
Pokud aplikace ODBC 3*.x* pracuje s ovladačem ODBC 2*.x*, správce ovladačů mapuje volání SQLFetch na sqlExtendedFetch pro ovladač ODBC 2*.x*, který podporuje SQLExtendedFetch. Pokud ovladač ODBC 2*.x* nepodporuje funkci SQLExtendedFetch, správce ovladačů mapuje volání SQLFetch na sqlFetch v ovladači ODBC 2*.x*, který může načíst pouze jeden řádek.
Další informace naleznete v tématu Blokové kurzory, posouvatelné kurzory a zpětnou kompatibilitu v dodatku G: Pokyny pro ovladače ohledně zpětné kompatibility.
Umístění kurzoru
Po vytvoření sady výsledků se kurzor umístí před začátek sady výsledků. SqlFetch načte další sadu řádků. Je ekvivalentní volání SQLFetchScroll s FetchOrientation nastavena na SQL_FETCH_NEXT. Další informace okurzorch
Atribut příkazu SQL_ATTR_ROW_ARRAY_SIZE určuje počet řádků v sadě řádků. Pokud sada řádků načtená nástrojem SQLFetch překrývá konec sady výsledků, vrátí funkce SQLFetch částečnou sadu řádků. To znamená, že pokud je S + R - 1 větší než L, kde S je počáteční řádek načtené sady řádků, R je velikost sady řádků a L je poslední řádek ve výsledné sadě, pak jsou platné pouze první L - S + 1 řádky sady řádků. Zbývající řádky jsou prázdné a mají stav SQL_ROW_NOROW.
Po vrácení funkce SQLFetch je aktuálním řádkem první řádek sady řádků.
Pravidla uvedená v následující tabulce popisují umístění kurzoru po volání funkce SQLFetch na základě podmínek uvedených v druhé tabulce v této části.
| Podmínka | První řádek nové sady řádků |
|---|---|
| Před zahájením | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + Sada řádků[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Po ukončení |
| Po ukončení | Po ukončení |
[1] Pokud se velikost sady řádků mezi načteními změní, jedná se o velikost sady řádků, která byla použita s předchozím načtením.
[2] Pokud se velikost sady řádků mezi načteními změní, jedná se o velikost sady řádků, která byla použita s novým načtením.
| Zápis | Význam |
|---|---|
| Před zahájením | Kurzor bloku se umístí před začátek sady výsledků. Pokud je první řádek nové sady řádků před začátkem sady výsledků, vrátí funkce SQLFetch SQL_NO_DATA. |
| Po ukončení | Kurzor bloku se umístí za konec sady výsledků. Pokud je první řádek nové sady řádků za koncem sady výsledků, vrátí funkce SQLFetch SQL_NO_DATA. |
| CurrRowsetStart | Číslo prvního řádku v aktuální sadě řádků. |
| LastResultRow | Číslo posledního řádku v sadě výsledků |
| RowetSize | Velikost sady řádků. |
Předpokládejme například, že sada výsledků má 100 řádků a velikost sady řádků je 5. Následující tabulka ukazuje sadu řádků a návratový kód vrácený funkcí SQLFetch pro různé počáteční pozice.
| Aktuální sada řádků | Návratový kód | Nová sada řádků | Počet načtených řádků |
|---|---|---|---|
| Před zahájením | SQL_SUCCESS | 1 až 5 | 5 |
| 1 až 5 | SQL_SUCCESS | 6 až 10 | 5 |
| 52 až 56 | SQL_SUCCESS | 57 až 61 | 5 |
| 91 až 95 | SQL_SUCCESS | 96 až 100 | 5 |
| 93 až 97 | SQL_SUCCESS | 98 až 100. Řádky 4 a 5 pole stavu řádku jsou nastaveny na SQL_ROW_NOROW. | 3 |
| 96 až 100 | SQL_NO_DATA | Žádné. | 0 |
| 99 až 100 | SQL_NO_DATA | Žádné. | 0 |
| Po ukončení | SQL_NO_DATA | Žádné. | 0 |
Vrácení dat ve vázaných sloupcích
Když SQLFetch vrátí každý řádek, umístí data pro každý vázaný sloupec do vyrovnávací paměti vázané na tento sloupec. Pokud nejsou vázané žádné sloupce, sqlFetch nevrátí žádná data, ale přesune kurzor bloku dopředu. Data se stále dají načíst pomocí SQLGetData. Pokud je kurzor vícenásobným kurzorem (to znamená, že SQL_ATTR_ROW_ARRAY_SIZE je větší než 1), sqlGetData lze volat pouze v případě, že SQL_GD_BLOCK je vrácena při volání SQLGetInfo s InfoType SQL_GETDATA_EXTENSIONS. (Další informace najdete v tématu SQLGetData.)
Pro každý vázaný sloupec v řádku provede SQLFetch následující:
Nastaví vyrovnávací paměť pro délku a indikátor na SQL_NULL_DATA a pokračuje dalším sloupcem, pokud jsou data null. Pokud jsou data null a nebyla vázána žádná vyrovnávací paměť ukazatele/ délka, vrátí SQLFetch SQLSTATE 22002 (proměnná indikátoru požadovaná, ale není zadána) pro řádek a pokračuje na další řádek. Informace o tom, jak určit adresu vyrovnávací paměti délky nebo indikátoru, naleznete v tématu "Adresy vyrovnávací paměti" v SQLBindCol.
Pokud data pro sloupec nemají hodnotu NULL, SQLFetch pokračuje krokem 2.
Pokud je atribut příkazu SQL_ATTR_MAX_LENGTH nastaven na nenulovou hodnotu a sloupec obsahuje znaková nebo binární data, data se zkrátí na SQL_ATTR_MAX_LENGTH bajtů.
Poznámka:
Atribut příkazu SQL_ATTR_MAX_LENGTH je určen ke snížení síťového provozu. Obvykle je implementována zdrojem dat, který zkracuje data před jejich vrácením přes síť. Ovladače a zdroje dat se k jeho podpoře nevyžadují. Proto, aby bylo zaručeno, že data jsou zkrácena na konkrétní velikost, měla by aplikace přidělit vyrovnávací paměť této velikosti a určit velikost v argumentu cbValueMax v SQLBindCol.
Převede data na typ určený typem TargetType v SQLBindCol.
Pokud byla data převedena na datový typ s proměnnou délkou, například znak nebo binární soubor, sqlFetch zkontroluje, zda délka dat překračuje délku vyrovnávací paměti dat. Pokud délka znakových dat (včetně znaku ukončení s hodnotou null) překročí délku vyrovnávací paměti dat, funkce SQLFetch zkrátí data na délku vyrovnávací paměti dat menší než délka znaku ukončení s hodnotou null. Data se pak ukončí hodnotou null. Pokud délka binárních dat přesahuje délku vyrovnávací paměti dat, sqlFetch ji zkrátí na délku vyrovnávací paměti dat. Délka vyrovnávací paměti dat je zadána pomocí BufferLength v SQLBindCol.
SQLFetch nikdy nezkrátí data převedená na datové typy s pevnou délkou; Vždy předpokládá, že délka vyrovnávací paměti dat je velikost datového typu.
Vloží převedená (a pravděpodobně zkrácená) data do vyrovnávací paměti dat. Informace o tom, jak určit adresu vyrovnávací paměti dat, naleznete v tématu "Adresy vyrovnávací paměti" v SQLBindCol.
Vloží délku dat do vyrovnávací paměti délky/ukazatele. Pokud ukazatel ukazatele i ukazatel délky byly nastaveny na stejnou vyrovnávací paměť (jako volání SQLBindCol ), délka se zapíše do vyrovnávací paměti pro platná data a SQL_NULL_DATA je zapsán do vyrovnávací paměti pro data NULL. Pokud nebyla vázána žádná vyrovnávací paměť délky nebo ukazatele, funkce SQLFetch nevrací délku.
U znakových nebo binárních dat se jedná o délku dat po převodu a před zkrácením kvůli příliš malé vyrovnávací paměti dat. Pokud ovladač nemůže určit délku dat po převodu, stejně jako v některých případech u dlouhých dat, nastaví délku na SQL_NO_TOTAL. Pokud byla data zkrácena z důvodu atributu příkazu SQL_ATTR_MAX_LENGTH, hodnota tohoto atributu se místo skutečné délky vloží do vyrovnávací paměti ukazatele délky a ukazatele . Důvodem je to, že tento atribut je navržen tak, aby před převodem zkrátil data na serveru, takže ovladač nemá způsob, jak zjistit, jaká je skutečná délka.
U všech ostatních datových typů se jedná o délku dat po převodu; to znamená, že se jedná o velikost typu, na který byla data převedena.
Informace o tom, jak určit adresu vyrovnávací paměti délky nebo indikátoru, naleznete v tématu "Adresy vyrovnávací paměti" v SQLBindCol.
Pokud jsou data během převodu zkrácena bez ztráty významných číslic (například reálné číslo 1,234 je zkráceno na celé číslo 1 při převodu), vrátí funkce SQLFetch hodnotu SQLSTATE 01S07 (zlomkové zkrácení) a SQL_SUCCESS_WITH_INFO. Pokud jsou data zkrácena, protože délka vyrovnávací paměti dat je příliš malá (například řetězec "abcdef" je vložen do vyrovnávací paměti 4 bajtů), SQLFetch vrátí SQLSTATE 01004 (data zkrácena) a SQL_SUCCESS_WITH_INFO. Pokud jsou data zkrácena z důvodu atributu příkazu SQL_ATTR_MAX_LENGTH, sqlFetch vrátí SQL_SUCCESS a nevrací SQLSTATE 01S07 (zlomkové zkrácení) nebo SQLSTATE 01004 (data zkrácena). Pokud během převodu dojde ke zkrácení dat se ztrátou významných číslic (například pokud byla hodnota SQL_INTEGER větší než 100 000 převedena na SQL_C_TINYINT), vrátí funkce SQLFetch hodnotu SQLSTATE 22003 (číselná hodnota mimo rozsah) a SQL_ERROR (pokud je velikost sady řádků 1) nebo SQL_SUCCESS_WITH_INFO (pokud je velikost sady řádků větší než 1).
Obsah vázané vyrovnávací paměti dat a vyrovnávací paměti délky a indikátoru nejsou definovány, pokud SQLFetch nebo SQLFetchScroll nevrací SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO.
Pole stavu řádku
Pole stavu řádku slouží k vrácení stavu každého řádku v sadě řádků. Adresa tohoto pole je určena atributem příkazu SQL_ATTR_ROW_STATUS_PTR. Pole je přiděleno aplikací a musí mít tolik prvků, kolik je určeno atributem SQL_ATTR_ROW_ARRAY_SIZE příkazu. Jeho hodnoty jsou nastaveny SQLFetch, SQLFetchScroll a SQLBulkOperations nebo SQLSetPos (s výjimkou případů, kdy byly volány po umístění kurzoru sqlExtendedFetch). Pokud hodnota atributu příkazu SQL_ATTR_ROW_STATUS_PTR je ukazatel null, tyto funkce nevrací stav řádku.
Obsah vyrovnávací paměti pole stavu řádku není definován, pokud SQLFetch nebo SQLFetchScroll nevrací SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO.
Následující hodnoty se vrátí v poli stavu řádku.
| Hodnota pole stavu řádku | Popis |
|---|---|
| SQL_ROW_SUCCESS | Řádek byl úspěšně načten a od posledního načtení z této sady výsledků se nezměnil. |
| SQL_ROW_SUCCESS_WITH_INFO | Řádek byl úspěšně načten a od posledního načtení z této sady výsledků se nezměnil. Nicméně, upozornění bylo vráceno o řádku. |
| SQL_ROW_ERROR | Při načítání řádku došlo k chybě. |
| SQL_ROW_UPDATED[1],[2] a [3] | Řádek se úspěšně načte a od posledního načtení z této sady výsledků se změnil. Pokud se řádek znovu načte z této sady výsledků nebo se aktualizuje službou SQLSetPos, stav se změní na nový stav řádku. |
| SQL_ROW_DELETED[3] | Řádek byl odstraněn od posledního načtení z této sady výsledků. |
| SQL_ROW_ADDED[4] | Řádek vložil SQLBulkOperations. Pokud se řádek znovu načte z této sady výsledků nebo se aktualizuje službou SQLSetPos, její stav se SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | Sada řádků překrývala konec sady výsledků a nebyl vrácen žádný řádek, který odpovídá tomuto prvku pole stavu řádku. |
[1] U sad klíčů, smíšených a dynamických kurzorů se při aktualizaci hodnoty klíče považuje řádek dat za odstraněný a přidaný nový řádek.
[2] Některé ovladače nemohou rozpoznat aktualizace dat, a proto nemohou tuto hodnotu vrátit. Chcete-li zjistit, zda ovladač může rozpoznat aktualizace pro opětovné načtení řádků, aplikace volá SQLGetInfo s možností SQL_ROW_UPDATES.
[3] Funkce SQLFetch může tuto hodnotu vrátit pouze v případě, že je intermixovaná s voláními sqlFetchScroll. Důvodem je to, že funkce SQLFetch prochází sadou výsledků a když se používá výhradně, nenačítá žádné řádky. Vzhledem k tomu, že se nenačítají žádné řádky, sqlFetch nezjistí změny, které byly provedeny v dříve načtených řádcích. Pokud ale SQLFetchScroll umístí kurzor před všechny dříve načtené řádky a sqlFetch se použije k načtení těchto řádků, sqlFetch dokáže detekovat všechny změny těchto řádků.
[4] Vráceno pouze sqlBulkOperations. Nenastavuje sqlFetch nebo SQLFetchScroll.
Načtená vyrovnávací paměť řádků
Načtená vyrovnávací paměť řádků se používá k vrácení počtu načtených řádků, včetně řádků, pro které nebyla vrácena žádná data, protože při načítání došlo k chybě. Jinými slovy, jedná se o počet řádků, pro které není hodnota v poli stavu řádku SQL_ROW_NOROW. Adresa této vyrovnávací paměti je určena atributem příkazu SQL_ATTR_ROWS_FETCHED_PTR. Vyrovnávací paměť je přidělena aplikací. Nastavuje se sqlFetch a SQLFetchScroll. Pokud hodnota atributu příkazu SQL_ATTR_ROWS_FETCHED_PTR je ukazatel null, tyto funkce nevrací počet načtených řádků. Chcete-li určit počet aktuálního řádku v sadě výsledků, může aplikace volat SQLGetStmtAttr s atributem SQL_ATTR_ROW_NUMBER.
Obsah načtené vyrovnávací paměti řádků není definován, pokud SQLFetch nebo SQLFetchScroll nevrací SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO, s výjimkou SQL_NO_DATA je vrácena hodnota v řádcích načtené vyrovnávací paměti na hodnotu 0.
Zpracování chyb
Chyby a upozornění se můžou vztahovat na jednotlivé řádky nebo na celou funkci. Další informace o diagnostických záznamech naleznete v tématu Diagnostika a SQLGetDiagField.
Chyby a upozornění pro celou funkci
Pokud se chyba vztahuje na celou funkci, například SQLSTATE HYT00 (vypršení časového limitu) nebo SQLSTATE 24000 (neplatný stav kurzoru), vrátí funkce SQLFetch SQL_ERROR a příslušný stav SQLSTATE. Obsah vyrovnávací paměti sady řádků není definován a pozice kurzoru se nezmění.
Pokud se upozornění vztahuje na celou funkci, vrátí funkce SQLFetch SQL_SUCCESS_WITH_INFO a příslušný stav SQLSTATE. Záznamy o stavu pro upozornění, která platí pro celou funkci, se vrátí před záznamy stavu, které platí pro jednotlivé řádky.
Chyby a upozornění v jednotlivých řádcích
Pokud se na jeden řádek vztahuje chyba (například SQLSTATE 22012 (Dělení nulou)) nebo upozornění (například SQLSTATE 01004 (Data zkráceno)), sqlFetch provede následující:
Nastaví odpovídající prvek pole stavu řádku na SQL_ROW_ERROR pro chyby nebo SQL_ROW_SUCCESS_WITH_INFO pro upozornění.
Přidá nulové nebo více stavových záznamů, které obsahují SQLSTATEs pro chybu nebo upozornění.
Nastaví pole čísel řádků a sloupců v záznamech stavu. Pokud sqlFetch nemůže určit číslo řádku nebo sloupce, nastaví toto číslo na SQL_ROW_NUMBER_UNKNOWN nebo SQL_COLUMN_NUMBER_UNKNOWN. Pokud se záznam stavu nevztahuje na konkrétní sloupec, sqlFetch nastaví číslo sloupce na SQL_NO_COLUMN_NUMBER.
SqlFetch pokračuje v načítání řádků, dokud nenačte všechny řádky v sadě řádků. Vrátí SQL_SUCCESS_WITH_INFO, pokud nedojde k chybě v každém řádku sady řádků (neobsahuje řádky se stavem SQL_ROW_NOROW), v takovém případě vrátí SQL_ERROR. Konkrétně pokud je velikost sady řádků 1 a v daném řádku dojde k chybě, sqlFetch vrátí SQL_ERROR.
Funkce SQLFetch vrátí záznamy o stavu v pořadí čísel řádků. To znamená, že vrátí všechny záznamy o stavu pro neznámé řádky (pokud existuje); pak vrátí všechny záznamy stavu pro první řádek (pokud existuje) a pak vrátí všechny stavové záznamy pro druhý řádek (pokud existuje) a tak dále. Záznamy o stavu pro každý řádek jsou seřazeny podle normálních pravidel pro řazení záznamů o stavu; Další informace naleznete v tématu Posloupnost záznamů stavu v SQLGetDiagField.
Popisovače a sqlFetch
Následující části popisují, jak SQLFetch komunikuje s popisovači.
Mapování argumentů
Ovladač nenastavuje žádná pole popisovače na základě argumentů funkce SQLFetch.
Další pole popisovače
SqlFetch používá následující pole popisovače.
| Pole popisovače | Desc. | Pole v | Nastavit prostřednictvím |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | záhlaví | atribut příkazu SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | záhlaví | atribut příkazu SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | ARD | záhlaví | atribut příkazu SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | ARD | záhlaví | atribut příkazu SQL_ATTR_ROW_BIND_TYPE |
| SQL_DESC_COUNT | ARD | záhlaví | Argument ColumnNumber funkce SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | záznamů | Argument TargetValuePtr pro SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | záznamů | StrLen_or_IndPtr argument v SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | záznamů | Argument BufferLength v sqlBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | záznamů | StrLen_or_IndPtr argument v SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | záhlaví | atribut příkazu SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | ARD | záznamů | Argument TargetType v SQLBindCol |
Všechna pole popisovače lze také nastavit prostřednictvím SQLSetDescField.
Samostatné vyrovnávací paměti délky a indikátoru
Aplikace můžou svázat jednu vyrovnávací paměť nebo dvě samostatné vyrovnávací paměti, které lze použít k uložení hodnot délky a ukazatele. Když aplikace volá SQLBindCol, ovladač nastaví SQL_DESC_OCTET_LENGTH_PTR a SQL_DESC_INDICATOR_PTR pole ARD na stejnou adresu, která se předá v argumentu StrLen_or_IndPtr . Když aplikace volá SQLSetDescField nebo SQLSetDescRec, může tato dvě pole nastavit na různé adresy.
SQLFetch určuje, zda aplikace zadala samostatnou délku a vyrovnávací paměti indikátoru. V tomto případě, pokud data nejsou NULL, SQLFetch nastaví vyrovnávací paměť indikátoru na 0 a vrátí délku vyrovnávací paměti délky vyrovnávací paměti délky. Pokud data mají hodnotu NULL, sqlFetch nastaví vyrovnávací paměť indikátoru na SQL_NULL_DATA a neupravuje vyrovnávací paměť délky.
Příklad kódu
Viz SQLBindCol, SQLColumns, SQLGetData a SQLProcedures.
Související funkce
| Informace o | Podívejte se |
|---|---|
| Vytvoření vazby vyrovnávací paměti ke sloupci v sadě výsledků | funkce SQLBindCol |
| Zrušení zpracování příkazů | funkce SQLCancel |
| Vrácení informací o sloupci v sadě výsledků | funkce SQLDescribeCol |
| Spuštění příkazu SQL | funkce SQLExecDirect |
| Spuštění připraveného příkazu SQL | funkce SQLExecute |
| Načtení bloku dat nebo procházení sady výsledků | funkce SQLFetchScroll |
| Zavření kurzoru na příkazu | FUNKCE SQLFreeStmt |
| Načtení části nebo celého sloupce dat | Funkce SQLGetData |
| Vrácení počtu sloupců sady výsledků | SQLNumResultCols – funkce |
| Příprava příkazu pro spuštění | Funkce SQLPrepare |
Viz také
Referenční
soubory hlaviček ODBC