Funkce SQLSetPos

Soulad
Zavedená verze: ODBC 1.0 Soulad standardů: ODBC

Summary
SQLSetPos nastavuje pozici kurzoru v sadě řádků a umožňuje aplikaci obnovit data v sadě řádků nebo aktualizovat či mazat data ve výsledné sadě.

Syntax

  
SQLRETURN SQLSetPos(  
      SQLHSTMT        StatementHandle,  
      SQLSETPOSIROW   RowNumber,  
      SQLUSMALLINT    Operation,  
      SQLUSMALLINT    LockType);

Arguments

StatementHandle
[Vstup] Popisovač příkazu

Číslo řádku
[Vstup] Pozice řádku v sadě řádků, na které se provádí operace zadaná argumentem Operace . Pokud je argument RowNumber 0, operace se vztahuje na každý řádek v sadě řádků.

Pro další informace viz "Komentáře."

Operation
[Vstup] Operace, kterou je třeba provést:

SQL_POSITION SQL_REFRESH SQL_UPDATE SQL_DELETE

Note

Hodnota SQL_ADD pro argument Operace byla pro ODBC 3.x zastaralá. Ovladače ODBC 3.x budou muset podporovat SQL_ADD kvůli zpětné kompatibilitě. Tato funkce byla nahrazena voláním SQLBulkOperations s operací SQL_ADD. Když aplikace ODBC 3.x pracuje s ovladačem ODBC 2.x , Driver Manager mapuje volání na SQLBulkOperations s operací SQL_ADD na SQLSetPos s operací SQL_ADD.

Pro více informací viz "Komentáře."

Typ zámku
[Vstup] Specifikuje, jak uzamknout řádek po provedení operace specifikované v argumentu Operace .

SQL_LOCK_NO_CHANGE SQL_LOCK_EXCLUSIVE SQL_LOCK_UNLOCK

Pro více informací viz "Komentáře."

Returns

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

Diagnostika

Když SQLSetPos vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLSTATE voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a HandleStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLSetPos 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.

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.)
01001	Konflikt operace kurzoru	Argument Operace byl SQL_DELETE nebo SQL_UPDATE a žádné řádky ani více než jeden řádek nebyly smazány ani aktualizovány. (Pro více informací o aktualizacích více než jednoho řádku viz popis atributu SQL_ATTR_SIMULATE_CURSOR v SQLSetStmtAttr.) (Funkce vrací SQL_SUCCESS_WITH_INFO.) Argument operace byl SQL_DELETE nebo SQL_UPDATE a operace selhala kvůli optimistické souběžnosti. (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
01004	Pravé ořezávání datových řetězců	Argument Operation byl SQL_REFRESH a řetězcová nebo binární data vrácená pro sloupec nebo sloupce s datovým typem SQL_C_CHAR nebo SQL_C_BINARY vedly k okrácení neprázdných znaků nebo ne-NULL binárních dat.
01S01	Chyba v řádku	Argument RowNumber byl 0 a při provádění operace specifikované argumentem Operation došlo k chybě v jednom nebo více řádcích. (SQL_SUCCESS_WITH_INFO se vrátí, pokud se chyba objeví na jednom nebo více, ale ne na všech řádcích víceřádkové operace, a SQL_ERROR se vrátí, pokud chyba nastane u jednořádkové operace.) (Tento SQLSTATE se vrací pouze tehdy, když je SQLSetPos volán po SQLExtendedFetch, pokud je ovladač ODBC 2.x a knihovna kurzoru není použita.)
01S07	Zlomkové zkrácení	Argument Operation byl SQL_REFRESH, typ dat aplikačního bufferu nebyl SQL_C_CHAR ani SQL_C_BINARY a data vrácená do aplikačních bufferů pro jeden nebo více sloupců 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	Hodnota dat sloupce ve výsledné sadě nemohla být převedena na datový typ specifikovaný TargetType při volání SQLBindCol.
07009	Index neplatných deskriptorů	Argument Operation byl SQL_REFRESH nebo SQL_UPDATE a sloupec byl vázán číslem sloupce větším než počet sloupců ve výsledné množině.
21S02	Stupeň odvozené tabulky neodpovídá seznamu sloupců	Argumentová operace byla SQL_UPDATE a žádné sloupce nebyly aktualizovatelné, protože všechny sloupce byly buď nevázané, pouze pro čtení, nebo hodnota v bufferu pro délku/indikátor byla SQL_COLUMN_IGNORE.
22001	Řetězcová data, zkrácení zprava	Argument Operation byl SQL_UPDATE a přiřazení znaku nebo binární hodnoty ke sloupci vedlo k okrácení neprázdných (pro znaky) nebo nenulových (pro binárních) znaků či bajtů.
22003	Číselná hodnota mimo rozsah	Argumentová operace byla SQL_UPDATE a přiřazení číselné hodnoty sloupci ve výsledné množině způsobilo zkrácení celé (na rozdíl od zlomkové) části čísla. Argument Operation byl SQL_REFRESH a vrácení číselné hodnoty pro jeden nebo více vázaných sloupců by způsobilo ztrátu významných číslic.
22007	Neplatný formát data a času	Argumentová operace byla SQL_UPDATE a přiřazení hodnoty data nebo časového razítka ke sloupci ve výsledné sadě způsobilo, že pole rok, měsíc nebo den bylo mimo rozsah. Argument Operace byl SQL_REFRESH a vrácení hodnoty data nebo časového razítka pro jeden nebo více vázaných sloupců by způsobilo, že pole rok, měsíc nebo den bylo mimo rozsah.
22008	Přetečení dat/čas pole	Argument operace byl SQL_UPDATE a provedení aritmetiky datového času na datech odeslaných do sloupce ve výsledné sadě vedlo k tomu, že pole data (rok, měsíc, den, hodina, minuta nebo druhé pole) výsledku bylo mimo povolený rozsah hodnot pro dané pole, nebo bylo neplatné podle přirozených pravidel gregoriánského kalendáře pro daty. Argument operace byl SQL_REFRESH a provedení aritmetiky datového času na datech získaných z výsledné sady vedlo k tomu, že pole datového času (rok, měsíc, den, hodina, minuta nebo druhé pole) výsledku bylo mimo povolený rozsah hodnot pro dané pole, nebo bylo neplatné podle přirozených pravidel gregoriánského kalendáře pro daty.
22015	Přetečení pole intervalu	Argument Operation byl SQL_UPDATE a přiřazení přesného číselného nebo intervalového typu C k intervalovému SQL datovému typu způsobilo ztrátu významných číslic. Argument Operace byl SQL_UPDATE; při přiřazení SQL typu interval nebyla v intervalovém SQL typu reprezentována hodnota typu C. Argument operace byl SQL_REFRESH a 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. Argument Operace byl SQL_ REFRESH; při přiřazení typu C intervalu nebyla v intervalu C uvedena hodnota SQL typu.
22018	Neplatná hodnota znaku pro specifikaci přetypování	Argument Operace byl SQL_REFRESH; typ C byl přesný nebo přibližný číselný typ, 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. Argumentem byla operace SQL_UPDATE; SQL typ byl přesná nebo přibližná číselná číslo, datový čas nebo intervalový datový typ; typ C byl SQL_C_CHAR; a hodnota ve sloupci nebyla platným literálem vázaného SQL typu.
23000	Porušení omezení integrity	Argument Operace byla SQL_DELETE nebo SQL_UPDATE a bylo porušeno omezení integrity.
24000	Neplatný stav kurzoru	CommandHandle byl ve stavu vykonání, ale žádná výsledná sada nebyla spojena s StatementHandle. (DM) Kurzor byl otevřený na StatementHandle, ale SQLFetch nebo SQLFetchScroll nebyly volány. Na StatementHandle byl otevřený kurzor a byly volány SQLFetch nebo SQLFetchScroll , ale kurzor byl umístěn před začátkem výsledné sady nebo za jejím koncem. Argumentová operace byla SQL_DELETE, SQL_REFRESH nebo SQL_UPDATE a kurzor byl umístěn před začátkem výsledné množiny nebo za koncem výsledné množiny.
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í se nezdařilo během provádění této funkce a stav transakce nelze určit.
42000	Chyba syntaxe nebo porušení přístupu	Ovladač nebyl schopen uzamknout řádek tak, jak bylo nutné pro provedení operace požadované v argumentu Operace. Řidič nebyl schopen uzamknout řadu, jak bylo požadováno v argumentaci LockType.
44000	PORUŠENÍ FUNKCE CHECK OPTION	Argument Operation byl SQL_UPDATE a aktualizace byla provedena na zobrazené tabulce nebo na tabulce odvozené z této tabulky, která byla vytvořena zadáním S MOŽNOSTÍ ZAŠKRTNOUT, takže jeden nebo více řádků ovlivněných aktualizací již nebude v zobrazené tabulce přítomno.
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 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 spouštěla, když byla volána funkce SQLSetPos. (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) Ovladač byl ODBC 2.x a SQLSetPos byl volán pro StatementHandle po vyvolání SQLFetch .
HY011	Atribut nelze nyní nastavit	(DM) Ovladač byl ODBC 2.x ; atribut SQL_ATTR_ROW_STATUS_PTR příkazu byl nastaven; poté byl volán SQLSetPos před voláním SQLFetch, SQLFetchScroll nebo SQLExtendedFetch .
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	Argument Operation byl SQL_UPDATE, hodnota dat byla nulový ukazatel a hodnota délky sloupce nebyla 0, SQL_DATA_AT_EXEC, SQL_COLUMN_IGNORE, SQL_NULL_DATA ani menší či rovna SQL_LEN_DATA_AT_EXEC_OFFSET. Argument Operace byl SQL_UPDATE; Hodnota dat nebyla nulovým ukazatelem; datový typ C byl SQL_C_BINARY nebo SQL_C_CHAR; a délka sloupce byla menší než 0, ale nebyla rovna SQL_DATA_AT_EXEC, SQL_COLUMN_IGNORE, SQL_NTS nebo SQL_NULL_DATA, ani menší či rovna SQL_LEN_DATA_AT_EXEC_OFFSET. Hodnota v bufferu délky/indikátoru byla SQL_DATA_AT_EXEC; SQL typ byl buď SQL_LONGVARCHAR, SQL_LONGVARBINARY, nebo dlouhý datový typ specifický pro datový zdroj; a SQL_NEED_LONG_DATA_LEN informační typ v SQLGetInfo byl "Y".
HY092	Neplatný identifikátor atributu	(DM) Hodnota uvedená pro argument Operace byla neplatná. (DM) Hodnota zadaná pro argument LockType byla neplatná. Argument Operation byl SQL_UPDATE nebo SQL_DELETE a atribut SQL_ATTR_CONCURRENCY příkazu byl SQL_ATTR_CONCUR_READ_ONLY.
HY107	Hodnota řádku mimo rozsah	Hodnota zadaná pro argument RowNumber byla větší než počet řádků v sadě řádků.
HY109	Neplatná pozice kurzoru	Kurzor spojený s StatementHandle byl definován pouze jako přesměrovaný, takže kurzor nemohl být umístěn uvnitř řádkové sady. Viz popis atributu SQL_ATTR_CURSOR_TYPE v SQLSetStmtAttr. Argument Operation byl SQL_UPDATE, SQL_DELETE nebo SQL_REFRESH a řádek identifikovaný argumentem RowNumber byl smazán nebo nebyl načten. (DM) Argument Řádkové číslo byl 0 a argument Operace byl SQL_POSITION. SQLSetPos byl volán po vyvolání SQLBulkOperations a před voláním SQLFetchScroll nebo SQLFetch .
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 operaci požadovanou v argumentu Operation ani LockType argumentu.
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í SQLSetStmtAttr s atributem 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

Caution

Pro informace o tom, že příkaz uvádí, že lze volat SQLSetPos a co je potřeba pro kompatibilitu s aplikacemi ODBC 2.x, viz Blokové kurzory, Posuvné kurzory a zpětná kompatibilita.

Argument Řádku

Argument RowNumber určuje počet řádků v sadě řádků, na kterých se provádí operace specifikovaná argumentem Operace . Pokud je argument RowNumber 0, operace se vztahuje na každý řádek v sadě řádků. Číslo řádku musí být hodnota od 0 do počtu řádků v sadě řádků.

Note

V jazyce C jsou pole založená na 0 a argument RowNumber je založen na 1. Například pro aktualizaci pátého řádku sady řádků aplikace upraví řádkové buffery na indexu pole 4, ale specifikuje Číslo řádku 5.

Všechny operace umisťují kurzor na řádek určený pomocí RowNumber. Následující operace vyžadují pozici kurzoru:

Pozice pro příkazy aktualizace a odstranění.
Volání na SQLGetData.
Volání do SQLSetPos s možnostmi SQL_DELETE, SQL_REFRESH a SQL_UPDATE.

Například pokud je RowNumber 2 pro volání SQLSetPos s operací SQL_DELETE, kurzor je umístěn na druhém řádku sady a ten řádek je smazán. Záznam v poli stavu implementačního řádku (označený atributem SQL_ATTR_ROW_STATUS_PTR příkazu) pro druhý řádek je změněn na SQL_ROW_DELETED.

Aplikace může při volání SQLSetPos specifikovat pozici kurzoru. Obecně volá SQLSetPos pomocí operace SQL_POSITION nebo SQL_REFRESH k umístění kurzoru před vykonáním příkazu pro aktualizaci nebo odstranění pozice nebo voláním SQLGetData.

Operace Argument

Argument operace podporuje následující operace. Pro určení, které možnosti jsou datovým zdrojem podporovány, aplikace volá SQLGetInfo s typem informací SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 nebo SQL_STATIC_CURSOR_ATTRIBUTES1 (v závislosti na typu kurzoru).

Operation argument	Operation
SQL_POSITION	Ovladač umístí kurzor na řádek určený pomocí RowNumber. Obsah pole stavů řádku, na které odkazuje atribut SQL_ATTR_ROW_OPERATION_PTR příkazu, je pro operaci SQL_POSITION ignorován.
SQL_REFRESH	Ovladač umístí kurzor na řádek určený pomocí RowNumber a obnoví data v bufferech řádků pro tento řádek. Pro více informací o tom, jak ovladač vrací data v bufferech řádků, viz popisy řádkových a sloupcových vazeb v SQLBindCol. SQLSetPos s operací SQL_REFRESH aktualizuje stav a obsah řádků v aktuálně načítané sadě řádků. To zahrnuje obnovení záložek. Protože data v bufferech jsou obnovována, ale nejsou znovu načítana, členství v sadě řádků je pevně dané. To se liší od obnovy prováděné voláním SQLFetchScroll s FetchOrientation SQL_FETCH_RELATIVE a RowNumber rovným 0, které načítá řádkovou sadu z výsledné sady, aby mohla zobrazit přidaná data a odstranit smazaná data, pokud jsou tyto operace podporovány ovladačem a kurzorem. Úspěšné obnovení pomocí SQLSetPos nezmění stav řádku SQL_ROW_DELETED. Smazané řádky v rámci sady budou nadále označeny jako smazané až do dalšího načítání. Řádky zmizí při dalším načítání, pokud kurzor podporuje balení (kdy následný SQLFetch nebo SQLFetchScroll nevrátí smazané řádky). Přidané řádky se neobjevují při obnově pomocí SQLSetPos . Toto chování se liší od SQLFetchScroll s FetchType SQL_FETCH_RELATIVE a RowNumber rovným 0, který také obnovuje aktuální řádkovou sadu, ale zobrazí přidané záznamy nebo smazané záznamy, pokud tyto operace kurzor podporuje. Úspěšné obnovení pomocí SQLSetPos změní stav řádku SQL_ROW_ADDED na SQL_ROW_SUCCESS (pokud pole stavů řádku existuje). Úspěšné obnovení pomocí SQLSetPos změní stav řádku SQL_ROW_UPDATED na nový stav řádku (pokud pole stavů řádku existuje). Pokud dojde k chybě v operaci SQLSetPos na řádku, stav řádku je nastaven na SQL_ROW_ERROR (pokud pole stavů řádku existuje). U kurzoru otevřeného s atributem SQL_ATTR_CONCURRENCY příkazu SQL_CONCUR_ROWVER nebo SQL_CONCUR_VALUES může obnovení pomocí SQLSetPos aktualizovat optimistické hodnoty souběžnosti používané datovým zdrojem, aby se zjistilo, že se řádek změnil. Pokud k tomu dojde, verze řádků nebo hodnoty používané k zajištění souběžnosti kurzoru se aktualizují při obnově řádkových bufferů ze serveru. To nastává pro každý obnovený řádek. Obsah pole stavů řádku, na které odkazuje atribut SQL_ATTR_ROW_OPERATION_PTR, je pro operaci SQL_REFRESH ignorován.
SQL_UPDATE	Ovladač umístí kurzor na řádek určený pomocí RowNumber a aktualizuje základní řádek dat hodnotami v bufferech řádků (argument TargetValuePtr v SQLBindCol). Získává délky dat z bufferů délky/indikátorů (argument StrLen_or_IndPtr v SQLBindCol). Pokud je délka libovolného sloupce SQL_COLUMN_IGNORE, sloupec se neaktualizuje. Po aktualizaci řádku ovladač změní odpovídající prvek pole stavů řádku na SQL_ROW_UPDATED nebo SQL_ROW_SUCCESS_WITH_INFO (pokud pole stavů řádku existuje). Je definováno ovladačem, jaké chování je, pokud je SQLSetPos s argumentem operace SQL_UPDATE vyvolán na kurzoru obsahujícím duplicitní sloupce. Ovladač může vracet SQLSTATE definovaný ovladačem, aktualizovat první sloupec, který se objeví ve výsledné sadě, nebo provádět jiné chování definované ovladačem. Pole řádkových operací, na které odkazuje atribut SQL_ATTR_ROW_OPERATION_PTR příkazu, může být použito k označení, že řádek v aktuální řádkové sadě by měl být během hromadné aktualizace ignorován. Pro více informací viz "Stavová a operační pole" později v této referenci funkce.
SQL_DELETE	Ovladač umístí kurzor na řádek určený pomocí RowNumber a smaže základní řádek dat. Změní odpovídající prvek řádkového stavového pole na SQL_ROW_DELETED. Po smazání řádku nejsou pro řádek platné následující příkazy: umístěné příkazy update a delete, volání SQLGetData a volání SQLSetPos s operací nastavenou na cokoli jiného než SQL_POSITION. U ovladačů, které podporují balení, je řádek z kurzoru odstraněn při načtení nových dat ze zdroje. Zda řádek zůstane viditelný, závisí na typu kurzoru. Například vymazané řádky jsou viditelné pro statické a klíčové kurzory, ale neviditelné pro dynamické kurzory. Pole řádkových operací, na které odkazuje atribut SQL_ATTR_ROW_OPERATION_PTR příkazu, může být použito k označení, že řádek v aktuální sadě řádků by měl být během hromadného mazání ignorován. Pro více informací viz "Stavová a operační pole" později v této referenci funkce.

Argument typu zámku

Argument LockType poskytuje způsob, jak aplikace mohou řídit souběžnost. Ve většině případů datové zdroje podporující úrovně souběžnosti a transakce podporují pouze SQL_LOCK_NO_CHANGE hodnotu argumentu LockType . Argument LockType se obecně používá pouze pro podporu založenou na souborech.

Argument LockType specifikuje stav zámku řádku po spuštění SQLSetPos . Pokud ovladač není schopen uzamknout řádek buď pro provedení požadované operace, nebo pro uspokojení argumentu LockType , vrátí SQL_ERROR a SQLSTATE 42000 (chyba syntaxe nebo porušení přístupu).

Ačkoliv je argument LockType specifikován pro jeden příkaz, zámek uděluje stejná oprávnění všem příkazům na spojení. Zejména zámek, který je získán jedním příkazem na spojení, může být odemčen jiným příkazem na stejném spojení.

Řádek uzamčený pomocí SQLSetPos zůstává zamčený, dokud aplikace nezavolá SQLSetPos pro řádek s nastavením LockType na SQL_LOCK_UNLOCK, nebo dokud aplikace nezavolá SQLFreeHandle pro příkaz nebo SQLFreeStmt s možností SQL_CLOSE. Pro ovladač podporující transakce se řádek uzamčený přes SQLSetPos odemkne, když aplikace zavolá SQLEndTran k potvrzení nebo vrácení transakce na spojení (pokud je kurzor uzavřen při potvrzení nebo vrácení transakce, jak je indikováno typy informací SQL_CURSOR_COMMIT_BEHAVIOR a SQL_CURSOR_ROLLBACK_BEHAVIOR vrácené SQLGetInfo).

Argument LockType podporuje následující typy zámků. Aby aplikace určila, které zámky jsou zdrojem dat podporovány, volá SQLGetInfo s typem informací SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 nebo SQL_STATIC_CURSOR_ATTRIBUTES1 (v závislosti na typu kurzoru).

Argument LockType	Typ zámku
SQL_LOCK_NO_CHANGE	Ovladač nebo zdroj dat zajišťuje, že řádek je ve stejném stavu zamčeného nebo odemčeného jako před vyvoláním SQLSetPos . Tato hodnota LockType umožňuje datovým zdrojům, které nepodporují explicitní uzamčení na úrovni řádku, používat jakékoli uzamčení požadované současnou souběžností a úrovní izolace transakcí.
SQL_LOCK_EXCLUSIVE	Ovladač nebo zdroj dat uzamkne řádek výhradně. Příkaz na jiném spojení nebo v jiné aplikaci nelze použít k získání zámků na řádku.
SQL_LOCK_UNLOCK	Ovladač nebo zdroj dat odemkne řádek.

Pokud ovladač podporuje SQL_LOCK_EXCLUSIVE, ale nepodporuje SQL_LOCK_UNLOCK, řádek, který je zamčený, zůstane zamčený, dokud nedojde k jednomu z volání funkcí popsaných v předchozím odstavci.

Pokud ovladač podporuje SQL_LOCK_EXCLUSIVE, ale nepodporuje SQL_LOCK_UNLOCK, řádek, který je zamčený, zůstane zamčený, dokud aplikace nezavolá příkaz SQLFreeHandle nebo SQLFreeStmt s volbou SQL_CLOSE. Pokud ovladač podporuje transakce a uzavře kurzor při potvrzení nebo vrácení transakce, aplikace volá SQLEndTran.

Pro operace aktualizace a mazání v SQLSetPos aplikace používá argument LockType následovně:

Aby byla zajištěna, že se řádek po načtení nezmění, aplikace volá SQLSetPos s operací nastavenou na SQL_REFRESH a LockType na SQL_LOCK_EXCLUSIVE.
Pokud aplikace nastaví LockType na SQL_LOCK_NO_CHANGE, ovladač zaručuje, že aktualizace nebo odstranění uspěje pouze tehdy, pokud aplikace specifikovala SQL_CONCUR_LOCK atributu SQL_ATTR_CONCURRENCY příkazu.
Pokud aplikace specifikuje SQL_CONCUR_ROWVER nebo SQL_CONCUR_VALUES pro atribut SQL_ATTR_CONCURRENCY, ovladač porovná verze řádků nebo hodnoty a operaci zamítne, pokud se řádek změnil od doby, kdy aplikace načetla řádek.
Pokud aplikace specifikuje SQL_CONCUR_READ_ONLY pro atribut SQL_ATTR_CONCURRENCY příkazu, ovladač jakoukoli aktualizaci nebo smazání zamítne.

Pro více informací o atributu SQL_ATTR_CONCURRENCY příkazu viz SQLSetStmtAttr.

Stavová a operační pole

Při volání SQLSetPos se používají následující stavová a operační pole:

Pole stavů řádků (jak ukazuje pole SQL_DESC_ARRAY_STATUS_PTR v IRD a atribut příkazu SQL_ATTR_ROW_STATUS_ARRAY) obsahuje stavové hodnoty pro každý řádek dat v sadě řádků. Ovladač nastavuje stavové hodnoty v tomto poli po volání do SQLFetch, SQLFetchScroll, SQLBulkOperations nebo SQLSetPos. Toto pole je označeno atributem SQL_ATTR_ROW_STATUS_PTR statement.
Pole řádkových operací (jak ukazuje pole SQL_DESC_ARRAY_STATUS_PTR v ARD a atribut SQL_ATTR_ROW_OPERATION_ARRAY příkazu) obsahuje hodnotu pro každý řádek v sadě řádků, která určuje, zda je volání SQLSetPos pro hromadnou operaci ignorováno nebo provedeno. Každý prvek v poli je nastaven buď na SQL_ROW_PROCEED (výchozí) nebo SQL_ROW_IGNORE. Toto pole je označeno atributem SQL_ATTR_ROW_OPERATION_PTR příkazu.

Počet prvků ve stavových a operačních poli musí být roven počtu řádků v sadě řádků (jak je definováno atributem SQL_ATTR_ROW_ARRAY_SIZE příkazu).

Pro informace o stavovém poli řádku viz SQLFetch. Informace o poli řádkových operací naleznete v článku "Ignorování řádku v hromadné operaci" později v této části.

Použití SQLSetPos

Než aplikace zavolá SQLSetPos, musí provést následující sekvenci kroků:

Pokud aplikace volá SQLSetPos s operací nastavenou na SQL_UPDATE, zavolejte SQLBindCol (nebo SQLSetDescRec) pro každý sloupec, abyste určili jeho datový typ a navázali buffery pro data a délku sloupce.
Pokud aplikace volá SQLSetPos s operací nastavenou na SQL_DELETE nebo SQL_UPDATE, zavolejte SQLColAtribut , abyste se ujistili, že sloupce, které mají být smazány nebo aktualizovány, jsou aktualizovatelné.
Zavolejte SQLExecDirect, SQLExecute nebo katalogovou funkci pro vytvoření výsledné množiny.
Pro získání dat zavolejte SQLFetch nebo SQLFetchScroll .

Pro více informací o používání SQLSetPos viz Aktualizace dat pomocí SQLSetPos.

Mazání dat pomocí SQLSetPos

Pro smazání dat pomocí SQLSetPos aplikace volá SQLSetPos s RowNumber nastaveným na číslo řádku pro mazání a operací nastavenou na SQL_DELETE.

Po smazání dat ovladač změní hodnotu v stavovém poli implementačních řádků pro příslušný řádek na SQL_ROW_DELETED (nebo SQL_ROW_ERROR).

Aktualizace dat pomocí SQLSetPos

Aplikace může předat hodnotu sloupce buď do vázaného datového bufferu, nebo jedním či více voláními do SQLPutData. Sloupce, jejichž data jsou předávána pomocí SQLPutData, se nazývají sloupcedatových při vykonání. Tyto se běžně používají k odesílání dat pro SQL_LONGVARBINARY a SQL_LONGVARCHAR sloupce a mohou být smíchány s jinými sloupci.

Pro aktualizaci dat pomocí SQLSetPos aplikace:

Umisťuje hodnoty do datových a délkových/indikátorových bufferů vázaných pomocí SQLBindCol:
- Pro normální sloupce aplikace umístí novou hodnotu sloupce do bufferu *TargetValuePtr a délku této hodnoty do bufferu *StrLen_or_IndPtr . Pokud by řádek neměl být aktualizován, aplikace umístí SQL_ROW_IGNORE do prvku tohoto řádku v poli operací řádku.
- Pro sloupce dat při vykonání aplikace umístí hodnotu definovanou aplikací, například číslo sloupce, do bufferu *TargetValuePtr . Hodnota může být později použita k identifikaci sloupce.
  
  Aplikace umístí výsledek makra SQL_LEN_DATA_AT_EXEC(délka) do bufferu *StrLen_or_IndPtr . Pokud je SQL datový typ sloupce SQL_LONGVARBINARY, SQL_LONGVARCHAR nebo dlouhý datový typ specifický pro zdroj dat a ovladač vrací "Y" pro SQL_NEED_LONG_DATA_LEN informační typ v SQLGetInfo, délka je počet bajtů dat, která mají být odeslána pro parametr; jinak musí být nezáporná hodnota a je ignorována.
Volá SQLSetPos s argumentem Operation nastaveným na SQL_UPDATE pro aktualizaci řádku dat.
- Pokud nejsou žádné sloupce dat při vykonání, proces je dokončen.
- Pokud jsou zde nějaké sloupce dat při vykonání, funkce vrátí SQL_NEED_DATA a pokračuje do kroku 3.
Volá SQLParamData pro získání adresy bufferu *TargetValuePtr pro první sloupec dat-at-exekuce, který má být zpracován. SQLParamData vrací SQL_NEED_DATA. Aplikace získává hodnotu definovanou aplikací z bufferu *TargetValuePtr .

Note

Ačkoli parametry dat při vykonání jsou podobné sloupcům dat-at-exekuci, hodnota vrácená SQLParamData je pro každý z nich jiná.

Note

Parametry Data při vykonání jsou parametry v SQL příkazu, pro které budou data odeslána spolu se SQLPutData , když je příkaz vykonán pomocí SQLExecDirect nebo SQLExecute. Jsou vázány pomocí SQLBindParameter nebo nastavením deskriptorů pomocí SQLSetDescRec. Hodnota vrácená SQLParamData je 32bitová hodnota předaná SQLBindParameter v argumentu ParameterValuePtr .

Note

Sloupce Data při vykonání jsou sloupce v sadě řádků, pro které budou data odeslána spolu se SQLPutData při aktualizaci řádku pomocí SQLSetPos. Jsou vázáni na SQLBindCol. Hodnota vrácená SQLParamData je adresa řádku v bufferu *TargetValuePtr , který je zpracováván.
Volá SQLPutData jednou nebo vícekrát, aby poslal data pro sloupec. Pokud nelze všechny datové hodnoty vrátit do bufferu *TargetValuePtr specifikovaného v SQLPutData, je potřeba více než jedno volání; více volání SQLPutData pro stejný sloupec je povoleno pouze při odesílání dat znaku C do sloupce s typem znaku, binárního souboru nebo datového zdroje specifického, nebo při odesílání binárních dat C do sloupce se znakem, binárním nebo datovým typem specifickým pro zdroj dat.
Znovu volá SQLParamData , aby signalizovala, že všechna data pro sloupec byla odeslána.
- Pokud je více sloupců dat-at-exekuci, SQLParamData vrátí SQL_NEED_DATA a adresu bufferu TargetValuePtr pro další sloupec dat-at-exekuce, který má být zpracován. Aplikace opakuje kroky 4 a 5.
- Pokud již nejsou žádné sloupce dat při vykonání, proces je dokončen. Pokud byl příkaz úspěšně vykonán, SQLParamData vrací SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO; pokud provedení selže, vrátí SQL_ERROR. V tomto bodě může SQLParamData vrátit jakýkoli SQLSTATE, který SQLSetPos může vrátit.

Pokud byla data aktualizována, ovladač změní hodnotu ve stavovém poli implementačních řádků pro příslušný řádek na SQL_ROW_UPDATED.

Pokud je operace zrušena nebo dojde k chybě v SQLParamData nebo SQLPutData, po vrácení SQL_NEED_DATA SQLSetPos a před odesláním dat pro všechny sloupce při vykonání dat může aplikace volat pouze SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData nebo SQLPutData pro příkaz nebo spojení spojené s tímto příkazem. Pokud zavolá jinou funkci pro příkaz nebo spojení spojené s tímto příkazem, funkce vrátí SQL_ERROR a SQLSTATE HY010 (chyba sekvence funkce).

Pokud aplikace volá SQLCancel, zatímco ovladač stále potřebuje data pro sloupce dat-at-exekuce, ovladač operaci zruší. Aplikace pak může znovu volat SQLSetPos ; Zrušení neovlivňuje stav kurzoru ani aktuální pozici kurzoru.

Když SELECT-list dotazovací specifikace spojené s kurzorem obsahuje více než jednu referenci na stejný sloupec, je definováno ovladačem, zda je vygenerována chyba nebo ovladač ignoruje duplicitní odkazy a provede požadované operace.

Provádění hromadných operací

Pokud je argument RowNumber 0, ovladač provede operaci specifikovanou v argumentu Operation pro každý řádek v sadě řádků, který má hodnotu SQL_ROW_PROCEED ve svém poli v poli řádkových operací, na které odkazuje atribut SQL_ATTR_ROW_OPERATION_PTR příkazu. Toto je platná hodnota argumentu RowNumber pro argument operace SQL_DELETE, SQL_REFRESH nebo SQL_UPDATE, ale ne SQL_POSITION. SQLSetPos s operací SQL_POSITION a Řádkovým číslem rovným 0 vrátí SQLSTATE HY109 (Neplatná pozice kurzoru).

Pokud dojde k chybě, která se týká celé sady řádků, například SQLSTATE HYT00 (vypršel časový limit), ovladač vrátí SQL_ERROR a odpovídající SQLSTATE. Obsah bufferů řádků je nedefinovaný a pozice kurzoru zůstává nezměněna.

Pokud dojde k chybě týkající se jednoho řádku, ovladač:

Nastaví prvek řádku v poli stavu, na který ukazuje atribut SQL_ATTR_ROW_STATUS_PTR příkazu, na SQL_ROW_ERROR.
Zveřejní jeden nebo více dalších SQLstavů pro chybu ve frontě chyb a nastaví pole SQL_DIAG_ROW_NUMBER v diagnostické datové struktuře.

Po zpracování chyby nebo varování, pokud ovladač dokončí operaci pro zbývající řádky v sadě řádků, vrátí SQL_SUCCESS_WITH_INFO. Takže pro každý řádek, který vrátil chybu, chybová fronta obsahuje nula nebo více dalších SQLstavů. Pokud ovladač operaci zastaví poté, co zpracoval chybu nebo varování, vrátí SQL_ERROR.

Pokud ovladač vrátí nějaká varování, například SQLSTATE 01004 (Data trunkována), vrátí varování, která se vztahují na celou sadu řádků nebo na neznámé řádky v sadě, než vrátí chybové informace platné pro konkrétní řádky. Vrací varování pro konkrétní řádky spolu s dalšími chybovými informacemi o těchto řádcích.

Pokud je RowNumber roven 0 a Operation je SQL_UPDATE, SQL_REFRESH nebo SQL_DELETE, počet řádků, na kterých SQLSetPos pracuje, je označen atributem SQL_ATTR_ROWS_FETCHED_PTR příkazu.

Pokud je Řádkové číslo rovno 0 a operace je SQL_DELETE, SQL_REFRESH nebo SQL_UPDATE, aktuální řádek po operaci je stejný jako aktuální řádek před operací.

Ignorování řádku při hromadné operaci

Pole řádkových operací lze použít k označení, že řádek v aktuální sadě řádků by měl být ignorován během hromadné operace pomocí SQLSetPos. Aby aplikace mohla ovladač nasměrovat ignorovat jeden nebo více řádků během hromadné operace, měla by provést následující kroky:

Zavolejte SQLSetStmtAttr a nastavte atribut SQL_ATTR_ROW_OPERATION_PTR příkazu tak, aby ukazoval na pole SQLUSMALLINT. Toto pole lze také nastavit voláním SQLSetDescField pro nastavení SQL_DESC_ARRAY_STATUS_PTR hlavičkového pole ARD, což vyžaduje, aby aplikace získala descriptor handle.
Nastavte každý prvek řádkového operačního pole na jednu ze dvou hodnot:
- SQL_ROW_IGNORE, aby bylo označeno, že řádek je vyloučen pro hromadnou operaci.
- SQL_ROW_PROCEED, aby označil, že řádek je zahrnut do hromadné operace. (Toto je výchozí hodnota.)
Pro provedení hromadné operace zavolejte SQLSetPos .

Na pole řádkových operací platí následující pravidla:

SQL_ROW_IGNORE a SQL_ROW_PROCEED ovlivňují pouze hromadné operace pomocí SQLSetPos s operací SQL_DELETE nebo SQL_UPDATE. Neovlivňují volání SQLSetPosoperací SQL_REFRESH nebo SQL_POSITION.
Ukazatel je ve výchozím nastavení nastaven na null.
Pokud je ukazatel null, všechny řádky se aktualizují, jako by všechny prvky byly nastaveny na SQL_ROW_PROCEED.
Nastavení prvku na SQL_ROW_PROCEED nezaručuje, že operace proběhne právě na daném řádku. Například pokud má určitý řádek v sadě řádků status SQL_ROW_ERROR, ovladač nemusí být schopen tento řádek aktualizovat, bez ohledu na to, zda aplikace specifikovala SQL_ROW_PROCEED. Aplikace musí vždy zkontrolovat pole stavů řádků, aby zjistila, zda byla operace úspěšná.
SQL_ROW_PROCEED je v hlavičkovém souboru definována jako 0. Aplikace může inicializovat pole řádkových operací na 0, aby zpracovala všechny řádky.
Pokud je prvek číslo "n" v řádkovém operačním poli nastaven na SQL_ROW_IGNORE a SQLSetPos je vyvolán k hromadné aktualizaci nebo mazání, n-tý řádek v řádku zůstává po volání SQLSetPos nezměněn.
Aplikace by měla automaticky nastavit sloupec pouze pro čtení na SQL_ROW_IGNORE.

Ignorování sloupce při hromadné operaci

Aby se předešlo zbytečným diagnostickým procesům generovaným pokusy o aktualizaci jednoho nebo více sloupců pouze pro čtení, může aplikace nastavit hodnotu v bufferu délky/indikátoru na SQL_COLUMN_IGNORE. Pro více informací viz SQLBindCol.

Příklad kódu

V následujícím příkladu aplikace umožňuje uživateli procházet tabulku ORDERS a aktualizovat stav objednávky. Kurzor je řízen klíčovou sadou s velikostí řádků 20 a používá optimistickou kontrolu souběžnosti při porovnání verzí řádků. Po načtení každé sady řádků ji aplikace vytiskne a umožní uživateli vybrat a aktualizovat stav objednávky. Aplikace používá SQLSetPos k umístění kurzoru na vybraný řádek a provádí jeho polohovanou aktualizaci. (Zpracování chyb je vynecháno pro přehlednost.)

#define ROWS 20  
#define STATUS_LEN 6  
  
SQLCHAR        szStatus[ROWS][STATUS_LEN], szReply[3];  
SQLINTEGER     cbStatus[ROWS], cbOrderID;  
SQLUSMALLINT   rgfRowStatus[ROWS];  
SQLUINTEGER    sOrderID, crow = ROWS, irow;  
SQLHSTMT       hstmtS, hstmtU;  
  
SQLSetStmtAttr(hstmtS, SQL_ATTR_CONCURRENCY, (SQLPOINTER) SQL_CONCUR_ROWVER, 0);  
SQLSetStmtAttr(hstmtS, SQL_ATTR_CURSOR_TYPE, (SQLPOINTER) SQL_CURSOR_KEYSET_DRIVEN, 0);  
SQLSetStmtAttr(hstmtS, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER) ROWS, 0);  
SQLSetStmtAttr(hstmtS, SQL_ATTR_ROW_STATUS_PTR, (SQLPOINTER) rgfRowStatus, 0);  
SQLSetCursorName(hstmtS, "C1", SQL_NTS);  
SQLExecDirect(hstmtS, "SELECT ORDERID, STATUS FROM ORDERS ", SQL_NTS);  
  
SQLBindCol(hstmtS, 1, SQL_C_ULONG, &sOrderID, 0, &cbOrderID);  
SQLBindCol(hstmtS, 2, SQL_C_CHAR, szStatus, STATUS_LEN, &cbStatus);  
  
while ((retcode == SQLFetchScroll(hstmtS, SQL_FETCH_NEXT, 0)) != SQL_ERROR) {  
   if (retcode == SQL_NO_DATA_FOUND)  
      break;  
   for (irow = 0; irow < crow; irow++) {  
      if (rgfRowStatus[irow] != SQL_ROW_DELETED)  
         printf("%2d %5d %*s\n", irow+1, sOrderID, NAME_LEN-1, szStatus[irow]);  
   }  
   while (TRUE) {  
      printf("\nRow number to update?");  
      gets_s(szReply, 3);  
      irow = atoi(szReply);  
      if (irow > 0 && irow <= crow) {  
         printf("\nNew status?");  
         gets_s(szStatus[irow-1], (ROWS * STATUS_LEN));  
         SQLSetPos(hstmtS, irow, SQL_POSITION, SQL_LOCK_NO_CHANGE);  
         SQLPrepare(hstmtU,  
          "UPDATE ORDERS SET STATUS=? WHERE CURRENT OF C1", SQL_NTS);  
         SQLBindParameter(hstmtU, 1, SQL_PARAM_INPUT,  
            SQL_C_CHAR, SQL_CHAR,  
            STATUS_LEN, 0, szStatus[irow], 0, NULL);  
         SQLExecute(hstmtU);  
      } else if (irow == 0) {  
         break;  
      }  
   }  
}

Pro více příkladů viz Positioned Update and Delete Statements a Updating Řá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í, které nesouvisejí s pozicí kurzoru bloku	SQLBulkOperations Function
Zrušení zpracování příkazů	SQLCancel – funkce
Načtení bloku dat nebo procházení sady výsledků	SQLFetchScroll – funkce
Získání jednoho pole deskriptoru	SQLGetDescField Function
Získání více polí deskriptoru	SQLGetDescRec Function
Nastavení jednoho pole deskriptoru	SQLSetDescField Function
Nastavení více polí deskriptoru	SQLSetDescRec Function
Nastavení atributu příkazu	FUNKCE SQLSetStmtAttr

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-08-24