Funkce SQLMoreResults

shoda
Zavedená verze: Dodržování standardů ODBC 1.0: ODBC

Shrnutí
SQLMoreResults určuje, zda jsou k dispozici více výsledků v příkazu obsahujícím příkazy SELECT, UPDATE, INSERT nebo DELETE a pokud ano, inicializuje zpracování těchto výsledků.

Syntaxe

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);  

Argumenty

StatementHandle
[Vstup] Popisovač příkazu

Návraty

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

Diagnostika

Když sqlMoreResults vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze přidruženou hodnotu SQLSTATE získat voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a popisovačStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE běžně vrácené funkcí SQLMoreResults a vysvětluje každý z nich 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.

SQLSTATE	Chyba	Popis
01000	Obecné upozornění	Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
01S02	Hodnota možnosti se změnila.	Hodnota atributu příkazu se změnila při zpracování dávky. (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
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.
40001	Selhání serializace	Transakce byla vrácena zpět kvůli vzájemnému zablokování prostředku s jinou transakcí.
40003	Neznámé dokončování příkazů	Přidružené připojení selhalo 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ěť 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 SQLMoreResults byla volána a před dokončením provádění byla volána funkce SQLCancel nebo SQLCancelHandle pro StatementHandle. Potom byla funkce SQLMoreResults znovu volána v StatementHandle. Funkce SQLMoreResults byla volána a před dokončením provádění byla volána funkce SQLCancel neboSQLCancelHandlez jiného vlákna ve vícevláknové aplikaci.
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 při volání funkce SQLMoreResults . (DM) Pro StatementHandle byla volána asynchronně spouštěná funkce (ne tato) a při zavolání této funkce se stále spouštěla. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationsnebo SQLSetPos byl volána pro StatementHandle a vrácena SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce.
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.
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.
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

Příkazy SELECT vrací sady výsledků. Příkazy UPDATE, INSERT a DELETE vrací počet ovlivněných řádků. Pokud se některý z těchto příkazů zasílají do dávek, odesílají se polem parametrů (číslovaným vzestupným pořadím parametrů, v pořadí, v jakém se zobrazují v dávce), nebo v postupech, můžou vrátit více sad výsledků nebo počet řádků. Informace o dávkách příkazů a polí parametrů naleznete v tématu Dávky příkazů SQL a pole hodnot parametrů.

Po spuštění dávky se aplikace umístí do první sady výsledků. Aplikace může volat SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos a všechny funkce metadat, na první nebo jakékoli následné sady výsledků, stejně jako kdyby tam byla jen jedna sada výsledků. Jakmile se dokončí s první sadou výsledků, aplikace volá SQLMoreResults , aby se přesunula na další sadu výsledků. Pokud je k dispozici jiná sada výsledků nebo počet výsledků, vrátí funkce SQLMoreResults SQL_SUCCESS a inicializuje sadu výsledků nebo počet pro další zpracování. Pokud se mezi příkazy generování sady výsledků zobrazí nějaké příkazy generování počtu řádků, můžete je stupňovat voláním SQLMoreResults. Po volání SQLMoreResults pro příkazy UPDATE, INSERT nebo DELETE může aplikace volat SQLRowCount.

Pokud byla aktuální sada výsledků s nenačítanými řádky, sqlMoreResults tuto sadu výsledků zahodí a zpřístupní další sadu výsledků nebo počet výsledků. Pokud byly zpracovány všechny výsledky, vrátí funkce SQLMoreResults SQL_NO_DATA. U některých ovladačů nejsou výstupní parametry a návratové hodnoty k dispozici, dokud nebudou zpracovány všechny sady výsledků a počty řádků. Pro tyto ovladače se výstupní parametry a návratové hodnoty zpřístupní, když sqlMoreResults vrátí SQL_NO_DATA.

Všechny vazby, které byly vytvořeny pro předchozí sadu výsledků, zůstávají platné. Pokud se struktury sloupců pro tuto sadu výsledků liší, může volání SQLFetch nebo SQLFetchScroll způsobit chybu nebo zkrácení. Aby tomu zabránila, musí aplikace volat SQLBindCol explicitně znovu vazby podle potřeby (nebo to udělat nastavením polí popisovače). Případně může aplikace volat SQLFreeStmt s možností SQL_UNBIND zrušit vazbu všech vyrovnávacích pamětí sloupců.

Hodnoty atributů příkazů, jako je typ kurzoru, souběžnost kurzoru, velikost sady klíčů nebo maximální délka, se můžou změnit při procházení dávky voláními SQLMoreResults. Pokud k tomu dojde, vrátí funkce SQLMoreResults SQL_SUCCESS_WITH_INFO a SQLSTATE 01S02 (hodnota možnosti se změnila).

Volání SQLCloseCursor nebo SQLFreeStmt s možností SQL_CLOSE zahodí všechny sady výsledků a počty řádků, které byly k dispozici v důsledku spuštění dávky. Popisovač příkazu se vrátí do přiděleného nebo připraveného stavu. Volání sqlCancel zrušit asynchronně spouštěnou funkci při spuštění dávky a popisovač příkazu je ve spuštěném, umístění kurzoru nebo asynchronním stavu způsobí, že všechny sady výsledků a počty řádků vygenerované dávkou zahodí, pokud bylo volání zrušení úspěšné. Příkaz se pak vrátí do připraveného nebo přiděleného stavu.

Pokud dávka příkazů nebo procedur kombinuje jiné příkazy SQL s příkazy SELECT, UPDATE, INSERT a DELETE , tyto další příkazy nemají vliv na SQLMoreResults.

Další informace najdete v tématu Více výsledků.

Pokud hledaná aktualizace, vložení nebo odstranění příkazu v dávce příkazů neovlivní žádné řádky ve zdroji dat, vrátí funkce SQLMoreResults SQL_SUCCESS. To se liší od případu hledané aktualizace, vložení nebo odstranění příkazu, který se provádí prostřednictvím sqlExecDirect, SQLExecute nebo SQLParamData, který vrací SQL_NO_DATA pokud nemá vliv na žádné řádky ve zdroji dat. Pokud aplikace volá SQLRowCount k načtení počtu řádků po volání SQLMoreResults nemá vliv na žádné řádky, SQLRowCount vrátí SQL_NO_DATA.

Další informace o platném sekvencování funkcí zpracování výsledků najdete v dodatku B: Tabulky přechodu stavu ODBC.

Další informace o SQL_PARAM_DATA_AVAILABLE a streamovaných výstupních parametrech naleznete v tématu Načítání výstupních parametrů pomocí SQLGetData.

Dostupnost počtu řádků

Pokud dávka obsahuje více po sobě jdoucích příkazů pro generování počtu řádků, je možné, že se tyto počty řádků zahrnou do jen jednoho počtu řádků. Pokud má například dávka pět příkazů vložení, můžou některé zdroje dat vracet pět jednotlivých řádků. Některé jiné zdroje dat vrátí pouze jeden počet řádků, který představuje součet pěti jednotlivých řádků.

Pokud dávka obsahuje kombinaci příkazů generování sady výsledků a generování počtu řádků, počet řádků může nebo nemusí být vůbec k dispozici. Chování ovladače s ohledem na dostupnost počtu řádků se vyčísluje v SQL_BATCH_ROW_COUNT informačním typu, který je k dispozici prostřednictvím volání SQLGetInfo. Předpokládejme například, že dávka obsahuje select, následované dvěma příkazy INSERT a další select. Pak jsou možné následující případy:

• Počty řádků odpovídající dvěma příkazům INSERT nejsou vůbec k dispozici. První volání SQLMoreResults vás umístí do sady výsledků druhého příkazu SELECT .

• Počet řádků odpovídající dvěma příkazům INSERT je k dispozici jednotlivě. (Volání sqlGetInfo nevrací SQL_BRC_ROLLED_UP bit pro typ informací SQL_BATCH_ROW_COUNT.) První volání funkce SQLMoreResults vás umístí na počet řádků prvního příkazu INSERT a druhé volání vás umístí na počet řádků druhého příkazu INSERT. Třetí volání SQLMoreResults vás umístí do sady výsledků druhého příkazu SELECT .

• Počty řádků odpovídající dvěma objektům INSERT se zahrnou do jednoho dostupného počtu řádků. (Volání sqlGetInfo vrátí bit SQL_BRC_ROLLED_UP pro typ informací SQL_BATCH_ROW_COUNT.) První volání funkce SQLMoreResults vás umístí na počet řádků shrnovanými daty a druhé volání funkce SQLMoreResults vás umístí do sady výsledků druhého příkazu SELECT.

Některé ovladače zpřístupňuje počty řádků pouze pro explicitní dávky a ne pro uložené procedury.

Související funkce

Informace o	Podívejte se
Zrušení zpracování příkazů	funkce SQLCancel
Načtení bloku dat nebo procházení sady výsledků	funkce SQLFetchScroll
Načtení jednoho řádku nebo bloku dat ve směru jen dopředu	funkce SQLFetch
Načtení části nebo celého sloupce dat	Funkce SQLGetData

Viz také

Referenční rozhraní ODBC API
soubory hlaviček ODBC
načítání výstupních parametrů pomocí SQLGetData