JetSetColumn – funkce

platí pro: Windows | Windows Server

JetSetColumn – funkce

Funkce JetSetColumn upraví hodnotu jednoho sloupce v upraveném záznamu, která se má vložit nebo aktualizovat aktuální záznam. Může přepsat existující hodnotu, přidat novou hodnotu do posloupnosti hodnot ve sloupci s více hodnotami, odebrat hodnotu z posloupnosti hodnot ve sloupci s více hodnotami nebo aktualizovat všechny nebo části dlouhé hodnoty, sloupec typu JET_coltypLongText nebo JET_coltypLongBinary.

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

Parametry

sesid

Relace, která se má použít pro toto volání.

tableid

Kurzor, který se má použít pro toto volání.

columnid

JET_COLUMNID sloupce, který se má načíst. Případně můžete zadat hodnotu columnid 0 (nula). Při zadání columnidu 0 (nula) se všechny označené sloupce, řídké a vícehodnotové sloupce považují za jeden sloupec. To usnadňuje načtení všech řídkých sloupců, které jsou přítomné v záznamu.

pvData

Vstupní vyrovnávací paměť obsahující data, která se mají použít pro hodnotu sloupce.

cbData

Velikost v bajtech vstupní vyrovnávací paměti.

grbitů

Skupina bitů, které obsahují možnosti, které se mají použít pro toto volání, které zahrnují nula nebo více z následujících:

Hodnota	Význam
JET_bitSetAppendLV	Tato možnost slouží k připojení dat ke sloupci typu JET_coltypLongText nebo JET_coltypLongBinary. Stejného chování lze dosáhnout určením velikosti existující dlouhé hodnoty a zadáním ibLongValue v psetinfo. Tento grbit je ale jednodušší použít, protože znalost velikosti existující hodnoty sloupce není nutná.
JET_bitSetOverwriteLV	Tato možnost slouží k nahrazení stávající dlouhé hodnoty nově poskytnutými daty. Pokud se tato možnost použije, je to, jako by byla stávající dlouhá hodnota před nastavením nových dat nastavená na 0 (nula).
JET_bitSetRevertToDefaultValue	Tato možnost se vztahuje pouze na označené, řídké nebo vícehodnotové sloupce. Způsobí, že sloupec vrátí výchozí hodnotu sloupce při následných operacích načtení sloupce. Odeberou se všechny existující hodnoty sloupců.
JET_bitSetSeparateLV	Tato možnost slouží k vynucení dlouhé hodnoty, sloupců typu JET_coltypLongText nebo JET_coltypLongBinary, aby se ukládaly odděleně od zbytku dat záznamů. K tomu obvykle dochází, když velikost dlouhé hodnoty brání jejímu uložení se zbývajícími daty záznamu. Tuto možnost ale můžete použít k vynucení samostatného uložení dlouhé hodnoty. Všimněte si, že dlouhé hodnoty čtyři bajty ve velikosti menších nesmí být nuceny oddělit. V takových případech se možnost ignoruje.
JET_bitSetSizeLV	Tato možnost slouží k interpretaci vstupní vyrovnávací paměti jako celočíselného počtu bajtů, které se nastaví jako délka dlouhé hodnoty popsané daným id sloupce a pokud je k dispozici, pořadové číslo v psetinfo-itagSequence>. Pokud je zadaná velikost větší než hodnota existujícího sloupce, sloupec se rozšíří o 0s. Pokud je velikost menší než hodnota existujícího sloupce, bude tato hodnota zkrácena.
JET_bitSetUniqueMultiValues	Tato možnost slouží k vynucení, že všechny hodnoty ve sloupci s více hodnotami jsou odlišné. Tato možnost porovnává zdrojová data sloupců bez jakýchkoli transformací s jinými existujícími hodnotami sloupců a pokud se najde duplicitní hodnota, vrátí se chyba. Pokud je tato možnost uvedena, nelze také zadat JET_bitSetAppendLV, JET_bitSetOverwriteLV a JET_bitSetSizeLV.
JET_bitSetUniqueNormalizedMultiValues	Tato možnost slouží k vynucení, že všechny hodnoty ve sloupci s více hodnotami jsou odlišné. Tato možnost porovnává normalizovanou transformaci dat sloupců s jinými podobnými transformovanými existujícími hodnotami sloupců a pokud se najde duplicitní hodnota, vrátí se chyba. Pokud je tato možnost uvedena, nelze také zadat JET_bitSetAppendLV, JET_bitSetOverwriteLV a JET_bitSetSizeLV.
JET_bitSetZeroLength	Tato možnost slouží k nastavení hodnoty na nulovou délku. Za normálních okolností je hodnota sloupce nastavena na HODNOTU NULL předáním cbMax 0 (nula). U některých typů, například JET_coltypText, ale hodnota sloupce může být 0 (nula) délka místo hodnoty NULL a tato možnost se používá k rozlišení hodnoty NULL a 0 (nula). Poznámka Obecně platí, že pokud je sloupec s pevnou délkou, bude tento bit ignorován a sloupec je nastaven na hodnotu NULL. Pokud je ale sloupec označený pevnou délkou, je délka sloupce nastavená na hodnotu 0. Pokud je označený sloupec s pevnou délkou nastaven na 0, pokusí se načíst sloupec s JetRetrieveColumn nebo JetRetrieveColumns bude úspěšný, ale skutečná délka vrácená v parametru cbActual je 0.
JET_bitSetIntrinsicLV	Tato možnost slouží k uložení celé dlouhé hodnoty v záznamu.
JET_bitSetCompressed	Tato možnost slouží k pokusu o kompresi dat při ukládání dat. Windows 7: JET_bitSetCompressed je zaveden ve Windows 7.
JET_bitSetUncompressed	Tato možnost se při ukládání dat nepokoušá o kompresi. Windows 7: JET_bitSetUnCompressed je zaveden ve Windows 7.

psetinfo

Ukazatel na volitelné vstupní parametry, které lze pro tuto funkci nastavit pomocí struktury JET_SETINFO .

Pokud je psetinfo zadán jako NULL , funkce se chová, jako by byla zadána itagSequence 1 a ibLongValue 0 (nula). To způsobí, že sloupec nastaví první hodnotu sloupce s více hodnotami a nastaví dlouhá data začínající posunem 0 (nula).

Pro tento parametr lze nastavit následující možnosti:

Hodnota	Význam
ibLongValue	Binární posun na dlouhou hodnotu sloupce, kde mají začínat nastavená data.
itagSequence	Pořadové číslo požadované hodnoty sloupce s více hodnotami, která se má nastavit. Pokud je itagSequence nastavena na hodnotu 0 (nula), měla by být zadaná hodnota připojena k poté konci posloupnosti hodnot s více hodnotami. Pokud zadané pořadové číslo je větší než poslední existující hodnota s více hodnotami, připojí se znovu daná hodnota na konec posloupnosti hodnot. Pokud pořadové číslo odpovídá existující hodnotě, nahradí se daná hodnota danou hodnotou.

Návratová hodnota

Tato funkce vrátí datový typ JET_ERR s jedním z následujících návratových kódů. Další informace o možných chybách ESE naleznete v tématu Rozšiřitelné chyby modulu úložiště a parametry zpracování chyb.

Návratový kód	Popis
JET_errSuccess	Operace byla úspěšně dokončena.
JET_errBadColumnId	Zadané ID sloupce je mimo právní omezení ID sloupce.
JET_errClientRequestToStopJetService	Operaci není možné dokončit, protože veškerá aktivita instance přidružené k relaci přestala v důsledku volání JetStopService.
JET_errColumnNotFound	Sloupec popsaný daným id sloupce v tabulce neexistuje.
JET_errColumnNotUpdatable	Při pokusu o aktualizaci dlouhé hodnoty během operace odstranění původní aktualizace pro vložení kopírování došlo k neplatnému pokusu.
JET_errColumnTooBig	Data dané hodnoty sloupce zadaná ve vstupní vyrovnávací paměti překračují omezení velikosti pro sloupec s pevnou délkou nebo nakonfigurované pro text s pevnou délkou nebo binární sloupce. Tato chyba se také vrátí při předávání více než 1024 bajtů dat pro dlouhý sloupec a nastavení příznaku JET_bitSetIntrinsicLV.
JET_errInstanceUnavailable	Operaci není možné dokončit, protože instance přidružená k relaci zjistila závažnou chybu, která vyžaduje odvolání přístupu ke všem datům kvůli ochraně integrity těchto dat. Windows XP: Tato chyba bude vrácena pouze systémem Windows XP a novějšími verzemi.
JET_errInvalidBufferSize	Velikost dat dané hodnoty sloupce neodpovídá tomu, co je přirozené pro datový typ s pevnou délkou.
JET_errInvalidColumnType	Během operace vložení nebo aktualizace došlo k neplatnému pokusu o aktualizaci sloupce automatického přírůstku nebo aktualizace sloupce verze během operace nahrazení.
JET_errInvalidgrbit	Zadané možnosti jsou neznámé nebo neplatná kombinace známých nastavení bitů.
JET_errInvalidParameter	Daná psetinfo-cbStruct> není platná velikost pro JET_SETINFO strukturu.
JET_errMultiValuedDuplicate	Operace nastavení sloupce se pokusila vytvořit duplicitní hodnotu a zadala JET_bitSetUniqueMultiValues nebo JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	Operaci není možné dokončit, protože instance přidružená k relaci ještě nebyla inicializována.
JET_errNotInTransaction	Byl proveden neplatný pokus o aktualizaci dlouhé hodnoty sloupce, když volání relace nebyla v transakci.
JET_errNullInvalid	Byl proveden neplatný pokus o nastavení sloupce bez hodnoty NULL na hodnotu NULL.
JET_errColumnIllegalNull	Stejné jako JET_errNullInvalid.
JET_errRecordTooBig	Hodnotu sloupce nelze nastavit na hodnotu ve vstupní vyrovnávací paměti, protože by způsobila, že záznam překročil omezení velikosti související s velikostí stránky. Sloupce typu JET_coltypLongText nebo JET_coltypLongBinary lze ukládat odděleně od zbývajících dat záznamů. Jiné sloupce však musí být uloženy se záznamem a mohou způsobit překročení omezení velikosti záznamu. Dokonce i dlouhé sloupce vyžadují 5 bajtů místa v záznamu jako propojení a to může také vést k JET_errRecordTooBig vrácení.
JET_errRestoreInProgress	Operaci není možné dokončit, protože probíhá operace obnovení u instance přidružené k relaci.
JET_errSessionSharingViolation	Stejnou relaci nelze použít pro více než jedno vlákno současně. Windows XP: Tato chyba bude vrácena pouze systémem Windows XP a novějšími verzemi.
JET_errTermInProgress	Operaci není možné dokončit, protože instance přidružená k relaci se vypíná.
JET_errUpdateNotPrepared	Kurzor v současné době není v procesu vložení nového záznamu nebo aktualizace existujícího záznamu.
JET_errVersionStoreOutOfMemory	K této chybě dojde v případě, že nakonfigurovaná velikost úložiště verzí není dostatečná k uložení všech nevyřízených aktualizací.
JET_wrnColumnMaxTruncated	Hodnota sloupce ve vstupní vyrovnávací paměti překročila maximální nakonfigurovanou délku pro sloupec s proměnlivou délkou a byla zkrácena.

Při úspěchu je požadovaná část hodnoty sloupce pro daný sloupec nastavena s daty zkopírovanými ze vstupní vyrovnávací paměti. Sada dat byla pravděpodobně zkrácena, pokud překročila maximální délku zadanou pro sloupec s proměnlivou délkou.

Při selhání zůstane umístění kurzoru beze změny a v vyrovnávací paměti kopírování se neaktualizují žádná data hodnoty sloupce.

Poznámky

Nastavení dlouhých hodnot, hodnoty pro sloupce JET_coltypLongBinary typu JET_coltypLongText nebo JET_coltypLongBinary, by se měly provádět pouze v případě, že je volající relace v transakci. Pokud volání relace není v transakci, úpravy dlouhých hodnot, které jsou uloženy samostatně, mohou být potvrzeny plně i v případě, že je operace aktualizace později zrušena. Pokud je volající relace v transakci, pak účinky aktualizace lze plně vrátit zpět zrušením aktualizace a vrácením zpět transakce relace.

Aktualizace indexu se neprovádí v důsledku operací JetSetColumn . Místo toho se indexy aktualizují až po dokončení všech úprav sloupců a zavolá se JetUpdate . To umožňuje nejúčinnější aktualizaci indexů, když indexy zahrnují více než jeden sloupec, který se upravuje.

Záznam je omezený na základě velikosti stránky databáze. Jakékoli dlouhé hodnoty v záznamu větší než pět bajtů budou uloženy odděleně od záznamu, pokud data v záznamu překročí limit v důsledku operace JetSetColumn . Chyba JET_errRecordTooBig bude vrácena pouze po uložení všech oddělitelných dat sloupců záznamů odděleně od záznamu a záznam stále překračuje limit velikosti záznamu.

Požadavky

Požadavek	Hodnota
Klient	Vyžaduje systém Windows Vista, Windows XP nebo Windows 2000 Professional.
Server	Vyžaduje Systém Windows Server 2008, Windows Server 2003 nebo Windows 2000 Server.
záhlaví	Deklarováno v esent.h.
Knihovna	Použijte ESENT.lib.
DLL knihovny	Vyžaduje ESENT.dll.

Viz také

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns