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.
Soulad
Zavedená verze: Soulad standardů ODBC 1.0: Zastaralé
Summary
SQLExtendedFetch 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.
Note
V ODBC 3*.x* byl SQLExtendedFetch nahrazen SQLFetchScroll. Aplikace ODBC 3*.x* by neměly volat SQLExtendedFetch; místo toho by měli volat SQLFetchScroll. Driver Manager mapuje SQLFetchScroll na SQLExtendedFetch při práci s ODBC 2*.x* ovladačem. Ovladače ODBC 3*.x* by měly podporovat SQLExtendedFetch , pokud chtějí pracovat s aplikacemi ODBC 2*.x*, které ho volají. Pro více informací viz "Komentáře" a blokové kurzory, posouvatelné kurzory a zpětná kompatibilita v příloze G: Pokyny pro zpětnou kompatibilitu ovladačů.
Syntax
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Arguments
StatementHandle
[Vstup] Popisovač příkazu
FetchOrientation
[Vstup] Typ aportu. To je stejné jako FetchOrientation v SQLFetchScroll.
FetchOffset
[Vstup] Číslo řádku k načtení. To je stejné jako FetchOffset v SQLFetchScroll, s jednou výjimkou. Když je FetchOrientation SQL_FETCH_BOOKMARK, FetchOffset je záložka s pevnou délkou, nikoli posun od záložky. Jinými slovy, SQLExtendedFetch získává záložku z tohoto argumentu, nikoli atribut SQL_ATTR_FETCH_BOOKMARK_PTR příkazu. Nepodporuje záložky s proměnnou délkou a neumožňuje načtení sady řádků s offsetem (jiným než 0) ze záložky.
RowCountPtr
[Výstup] Ukazatel na buffer, do kterého se vrací počet skutečně načtených řádků. Tento buffer se používá stejným způsobem jako buffer specifikovaný atributem SQL_ATTR_ROWS_FETCHED_PTR příkazu. Tento buffer používá pouze SQLExtendedFetch. Není používán v SQLFetch ani SQLFetchScroll.
RowStatusArray
[Výstup] Ukazatelem na pole, ve kterém se vrátí stav každého řádku. Toto pole se používá stejným způsobem jako pole specifikované atributem SQL_ATTR_ROW_STATUS_PTR příkazu.
Adresa tohoto pole však není uložena v SQL_DESC_STATUS_ARRAY_PTR poli v IRD. Dále toto pole používá pouze SQLExtendedFetch a SQLBulkOperations s operací SQL_ADD nebo SQLSetPos , pokud je voláno po SQLExtendedFetch. Nepoužívá ho SQLFetch ani SQLFetchScroll a nepoužívá ho SQLBulkOperations ani SQLSetPos , když jsou volány po SQLFetch nebo SQLFetchScroll. Také se nepoužívá, když je před voláním jakékoli funkce načtení volán SQLBulkOperations s operací SQL_ADD. Jinými slovy, používá se pouze ve stavu příkazu S7. Nepoužívá se ve stavech příkazů S5 ani S6. Pro více informací viz Přechody mezi výroky v příloze B: ODBC tabulky přechodů stavů.
Aplikace by měly poskytovat platný ukazatel v argumentu RowStatusArray ; pokud ne, chování SQLExtendedFetch a volání SQLBulkOperations nebo SQLSetPos po umístění kurzoru pomocí SQLExtendedFetch není definováno.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.
Diagnostika
Když SQLExtendedFetch vrátí buď SQL_ERROR, nebo SQL_SUCCESS_WITH_INFO, lze získat přiřazenou hodnotu SQLSTATE voláním SQLError. Následující tabulka uvádí hodnoty SQLSTATE, které SQLExtendedFetch 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 vyvolat pomocí diagidentifikátoru SQL_DIAG_COLUMN_NUMBER k určení sloupce, na kterém chyba nastala; a SQLGetDiagField lze volat pomocí diagidentifikátoru SQL_DIAG_ROW_NUMBER pro určení řádku obsahujícího daný sloupec.
| 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. Pokud šlo o číselnou hodnotu, zlomková část čísla byla zkrácena. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 01S01 | Chyba v řádku | Při načítání jednoho nebo více řádků došlo k chybě. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 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é množiny, když byla aktuální pozice za prvním řádkem, a buď byla FetchOrientation SQL_PRIOR, nebo FetchOrientation byla SQL_RELATIVE záporným FetchOffset , jehož absolutní hodnota byla menší nebo rovna aktuální SQL_ROWSET_SIZE. (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 nemohla být převedena na C datový typ specifikovaný TargetType v SQLBindCol. |
| 07009 | Index neplatných deskriptorů | Sloupec 0 byl vázaný s SQLBindCol a atribut SQL_ATTR_USE_BOOKMARKS příkazu 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. |
| 22002 | Požadovaná proměnná ukazatele, ale není zadána | NULL data byla načítána do sloupce, jehož StrLen_or_IndPtr nastavený SQLBindCol byl nullový ukazatel. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 22003 | Číselná hodnota mimo rozsah | Vrácení číselné hodnoty (jako číselné nebo řetězcové) pro jeden nebo více sloupců by způsobilo zkrácení celé (na rozdíl od zlomkové) části čísla. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) Pro více informací viz Pokyny pro intervalové a numerické datové typy 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. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 22012 | Dělení nulou | Byla vrácena hodnota z aritmetického výrazu, což vedlo k dělení nulou. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 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. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 22018 | Neplatná hodnota znaku pro specifikaci přetypování | 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. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 24000 | Neplatný stav kurzoru | CommandHandle byl ve stavu vykonání, ale žádná výsledná sada nebyla spojena s StatementHandle. |
| 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á SQLError 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ěť 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 vyvolána a před dokončením vykonávání byl na StatementHandlezavolán SQLCancel nebo SQLCancelHandle a poté byla funkce znovu volána na 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 SQLExtendedFetch . (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) SQLExtendedFetch byl volán pro StatementHandle po zavolání SQLFetch nebo SQLFetchScroll a před voláním SQLFreeStmt s možností SQL_CLOSE. (DM) SQLBulkOperations byl vyvolán jako příkaz před voláním SQLFetch, SQLFetchScroll nebo SQLExtendedFetch , a poté byl volán SQLExtendedFetch 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. |
| HY106 | Typ aportu mimo dosah | (DM) Hodnota zadaná pro argument FetchOrientation byla neplatná. (Viz "Komentáře.") Argument FetchOrientation byl SQL_FETCH_BOOKMARK a atribut SQL_ATTR_USE_BOOKMARKS příkazu byl nastaven na SQL_UB_OFF. Hodnota SQL_CURSOR_TYPE příkazu byla SQL_CURSOR_FORWARD_ONLY a hodnota argumentu FetchOrientation nebyla SQL_FETCH_NEXT. Argument FetchOrientation byl SQL_FETCH_RESUME. |
| HY107 | Hodnota řádku mimo rozsah | Hodnota zadaná volbou příkazu SQL_CURSOR_TYPE byla SQL_CURSOR_KEYSET_DRIVEN, ale hodnota uvedená atributem SQL_KEYSET_SIZE příkazu byla větší než 0 a menší než hodnota uvedená atributem SQL_ROWSET_SIZE příkazu. |
| HY111 | Neplatná hodnota záložek | Argument FetchOrientation byl SQL_FETCH_BOOKMARK a záložka uvedená v argumentu FetchOffset nebyla platná. |
| 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 specifikovaný typ načítaní. Ovladač nebo zdroj dat nepodporuje převod specifikovaný kombinací TargetType v SQLBindCol a SQL datového typu příslušného sloupce. Tato chyba se uplatní pouze tehdy, když byl SQL datový typ sloupce mapován na SQL datový typ specifický pro ovladač. |
| HYT00 | Vypršel časový limit. | Platnost časového limitu dotazu vypršela, než zdroj dat vrátil sadu výsledků. Časová doba je nastavena pomocí SQLSetStmtOption SQL_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. |
Comments
Chování SQLExtendedFetch je totožné s SQLFetchScroll, s následujícími výjimkami:
SQLExtendedFetch a SQLFetchScroll používají různé metody pro vrácení počtu načtených řádků. SQLExtendedFetch vrací počet řádků načtených v *RowCountPtr; SQLFetchScroll vrací počet řádků načtených přímo do bufferu, na který ukazuje SQL_ATTR_ROWS_FETCHED_PTR. Pro více informací viz argument RowCountPtr .
SQLExtendedFetch a SQLFetchScroll vracejí stav každého řádku v různých polích. Pro více informací viz argument RowStatusArray .
SQLExtendedFetch a SQLFetchScroll používají různé metody pro získání záložky, když je FetchOrientation SQL_FETCH_BOOKMARK. SQLExtendedFetch nepodporuje záložky s proměnnou délkou ani načítání řádků s offsetem jiným než 0 od záložky. Pro více informací viz argument FetchOffset .
SQLExtendedFetch a SQLFetchScroll používají různé velikosti řádků. SQLExtendedFetch používá hodnotu atributu SQL_ROWSET_SIZE příkazu a SQLFetchScroll hodnotu atributu SQL_ATTR_ROW_ARRAY_SIZE příkazu.
SQLExtendedFetch má mírně odlišnou sémantiku zpracování chyb než SQLFetchScroll. Pro více informací viz "Zpracování chyb" v sekci "Komentáře" na SQLFetchScroll.
SQLExtendedFetch nepodporuje vazby offsetů (atribut SQL_ATTR_ROW_BIND_OFFSET_PTR příkazu).
Volání SQLExtendedFetch nelze kombinovat s voláním SQLFetch nebo SQLFetchScroll, a pokud je SQLBulkOperations vyvolán před voláním jakékoli fetch funkce, SQLExtendedFetch nelze volat, dokud není kurzor uzavřen a znovu otevřen. To znamená, že SQLExtendedFetch lze volat pouze ve stavu příkazu S7. Pro více informací viz Přechody mezi výroky v příloze B: ODBC tabulky přechodů stavů.
Když aplikace volá SQLFetchScroll při použití ovladače ODBC 2*.x*, Driver Manager tuto volbu přemapuje na SQLExtendedFetch. Pro více informací viz "SQLFetchScroll and ODBC 2*.x* Drivers" v SQLFetchScroll.
V ODBC 2*.x* byl volán SQLExtendedFetch pro načtení více řádků a SQLFetch pro načtení jednoho řádku. V ODBC 3*.x* naopak lze volat SQLFetch pro načtení více řádků.
Související funkce
| 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 |
| 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 |