Použití polí parametrů

Chcete-li použít pole parametrů, aplikace volá SQLSetStmtAttr s argumentem Attribute SQL_ATTR_PARAMSET_SIZE pro určení počtu sad parametrů. Volá SQLSetStmtAttr s argumentem Attribute SQL_ATTR_PARAMS_PROCESSED_PTR pro určení adresy proměnné, do které může ovladač vrátit počet sad zpracovaných parametrů, včetně chybových sad. Volá SQLSetStmtAttr s argumentem Attribute nastaveným na SQL_ATTR_PARAM_STATUS_PTR, aby ukazoval na pole, ve kterém se vrátí informace o stavu pro každý řádek hodnot parametrů. Ovladač ukládá tyto adresy do struktury, kterou udržuje pro daný příkaz.

Poznámka:

V rozhraní ODBC 2.x byla SQLParamOptions volána k určení více hodnot pro parametr. V rozhraní ODBC 3.x bylo volání SQLParamOptions nahrazeno voláním SQLSetStmtAttr pro nastavení atributů SQL_ATTR_PARAMSET_SIZE a SQL_ATTR_PARAMS_PROCESSED_ARRAY.

Před spuštěním příkazu aplikace nastaví hodnotu každého prvku každého vázaného pole. Při spuštění příkazu ovladač použije informace, které uložil k načtení hodnot parametrů a jejich odeslání do zdroje dat; pokud je to možné, ovladač by měl tyto hodnoty odeslat jako pole. I když je použití polí parametrů nejlépe implementováno spuštěním příkazu SQL se všemi parametry v matici s jediným voláním zdroje dat, tato funkce není v současnosti v DBMS široce dostupná. Ovladače ho ale můžou simulovat spuštěním příkazu SQL několikrát, přičemž každý z nich má jednu sadu parametrů.

Než aplikace použije pole parametrů, musí se ujistit, že jsou podporovány ovladači používanými aplikací. Můžete to udělat dvěma způsoby:

• Používejte pouze ovladače, které jsou známé pro podporu polí parametrů. Aplikace může pevně zakódovat názvy těchto ovladačů nebo může být uživateli dáváno pokyn, aby používal pouze tyto ovladače. Vlastní aplikace a vertikální aplikace běžně používají omezenou sadu ovladačů.

• Zkontrolujte podporu polí parametrů za běhu. Ovladač podporuje pole parametrů, pokud je možné nastavit atribut příkazu SQL_ATTR_PARAMSET_SIZE na hodnotu větší než 1. Obecné aplikace a vertikální aplikace obvykle kontrolují podporu polí parametrů za běhu.

Dostupnost počtu řádků a sad výsledků v parametrizovaném spuštění lze určit voláním sqlGetInfo s možnostmi SQL_PARAM_ARRAY_ROW_COUNTS a SQL_PARAM_ARRAY_SELECTS. U příkazů INSERT, UPDATE a DELETE možnost SQL_PARAM_ARRAY_ROW_COUNTS určuje, zda jsou k dispozici jednotlivé počty řádků (jeden pro každou sadu parametrů) (SQL_PARC_BATCH), nebo zda jsou počty řádků sloučeny do jednoho souhrnného počtu (SQL_PARC_NO_BATCH). U příkazů SELECT určuje možnost SQL_PARAM_ARRAY_SELECTS, jestli je sada výsledků k dispozici pro každou sadu parametrů (SQL_PAS_BATCH), nebo jestli je dostupná jenom jedna sada výsledků (SQL_PAS_NO_BATCH). Pokud ovladač nepovolí spuštění příkazů generující sady výsledků pomocí pole parametrů, SQL_PARAM_ARRAY_SELECTS vrátí SQL_PAS_NO_SELECT. Je specifické pro zdroj dat, zda lze pole parametrů použít s jinými typy příkazů, zejména proto, že použití parametrů v těchto příkazech by bylo specifické pro zdroj dat a nebylo by dodržovat gramatiku ODBC SQL.

Pole odkazované atributem příkazu SQL_ATTR_PARAM_OPERATION_PTR lze použít k ignorování řádků parametrů. Pokud je prvek pole nastaven na SQL_PARAM_IGNORE, sada parametrů odpovídající danému prvku je vyloučena z volání SQLExecute nebo SQLExecDirect . Pole, na které odkazuje atribut SQL_ATTR_PARAM_OPERATION_PTR, je přiděleno a vyplněno aplikací a přečteno ovladačem. Pokud se jako vstupní parametry používají načtené řádky, dají se hodnoty pole stavu řádku použít v poli operací parametrů.

Zpracování chyb

Pokud při provádění příkazu dojde k chybě, funkce spuštění vrátí chybu a nastaví číselnou proměnnou řádku na číslo řádku obsahující chybu. Jedná se o konkrétní zdroj dat, zda jsou provedeny všechny řádky s výjimkou sady chyb nebo zda jsou provedeny všechny řádky před (ale ne po) sady chyb. Protože zpracovává sady parametrů, ovladač nastaví vyrovnávací paměť určenou atributem příkazu SQL_ATTR_PARAMS_PROCESSED_PTR na počet aktuálně zpracovávaných řádků. Pokud jsou spuštěny všechny sady kromě sady chyb, ovladač nastaví tuto vyrovnávací paměť na SQL_ATTR_PARAMSET_SIZE po zpracování všech řádků.

Pokud byl nastaven atribut příkazu SQL_ATTR_PARAM_STATUS_PTR, SQLExecute nebo SQLExecDirect vrátí pole stavu parametrů, které poskytuje stav každé sady parametrů. Pole stavu parametru je přiděleno aplikací a vyplněno ovladačem. Jeho prvky označují, zda byl příkaz SQL úspěšně proveden pro řádek parametrů nebo zda došlo k chybě při zpracování sady parametrů. Pokud došlo k chybě, ovladač nastaví odpovídající hodnotu v poli stavu parametru na SQL_PARAM_ERROR a vrátí SQL_SUCCESS_WITH_INFO. Aplikace může zkontrolovat stavové pole a určit, které řádky byly zpracovány. Pomocí čísla řádku může aplikace často opravit chybu a pokračovat ve zpracování.

Způsob použití pole stavu parametru určuje SQL_PARAM_ARRAY_ROW_COUNTS a SQL_PARAM_ARRAY_SELECTS možnosti vrácené voláním SQLGetInfo. U příkazů INSERT, UPDATE a DELETE se pole stavů parametrů vyplní informacemi o stavu, pokud je pro SQL_PARAM_ARRAY_ROW_COUNTS vrácena hodnota SQL_PARC_BATCH, nikoli však tehdy, když je vrácena hodnota SQL_PARC_NO_BATCH. U příkazů SELECT je pole stavu parametru vyplněno, pokud SQL_PAS_BATCH je vrácena pro SQL_PARAM_ARRAY_SELECT, ale ne, pokud je vrácena SQL_PAS_NO_BATCH nebo SQL_PAS_NO_SELECT.

Parametry dat při spuštění

Pokud jsou některé z hodnot v poli délky a indikátoru SQL_DATA_AT_EXEC nebo výsledek makra SQL_LEN_DATA_AT_EXEC(délka), data pro tyto hodnoty se posílají pomocí SQLPutData obvyklým způsobem. Následující aspekty tohoto procesu nesou zvláštní komentář, protože nejsou snadno zřejmé:

• Když ovladač vrátí SQL_NEED_DATA, musí nastavit adresu číselné proměnné řádku na řádek, pro který potřebuje data. Stejně jako v případě s jednou hodnotou nemůže aplikace provádět žádné předpoklady o pořadí, ve kterém ovladač bude požadovat hodnoty parametrů v rámci jedné sady parametrů. Pokud při provádění parametru data-at-execution dojde k chybě, vyrovnávací paměť určená atributem příkazu SQL_ATTR_PARAMS_PROCESSED_PTR je nastavena na počet řádků, na kterém došlo k chybě, stav řádku v poli stavu řádku určeném atributem příkazu SQL_ATTR_PARAM_STATUS_PTR je nastaven na SQL_PARAM_ERROR, a volání SQLExecute, SQLExecDirect, SQLParamData nebo SQLPutData vrátí SQL_ERROR. Obsah této vyrovnávací paměti není definován, pokud SQLExecute, SQLExecDirect nebo SQLParamData vrací SQL_STILL_EXECUTING.

• Vzhledem k tomu, že ovladač neinterpretuje hodnotu v parametru ParameterValuePtrsqlBindParameter pro parametry data-at-execution, pokud aplikace poskytuje ukazatel na pole, SQLParamData neextrahuje a nevrací prvek tohoto pole do aplikace. Místo toho vrátí skalární hodnotu, kterou aplikace zadala. To znamená, že hodnota vrácená SQLParamData není dostatečná k určení parametru, pro který aplikace potřebuje odesílat data; aplikace musí také zvážit číslo aktuálního řádku.

  Pokud jsou pouze některé prvky pole parametrů parametry data-at-execution, musí aplikace předat adresu pole v ParameterValuePtr, která obsahuje prvky pro všechny parametry. Pro normální parametry, které nejsou zpracovávané při spuštění, se toto pole interpretuje běžně. U parametrů dat při provádění je hodnota, kterou SQLParamData poskytuje aplikaci a kterou by se normálně dalo použít k identifikaci dat, jež ovladač žádá, vždy adresa pole.