JetSetColumn-funktion

2025-06-10

gäller för: Windows | Windows Server

JetSetColumn-funktion

Funktionen JetSetColumn ändrar ett kolumnvärde i en modifierad post som ska infogas eller uppdatera den aktuella posten. Det kan skriva över ett befintligt värde, lägga till ett nytt värde i en sekvens med värden i en kolumn med flera värden, ta bort ett värde från en sekvens med värden i en kolumn med flera värden eller uppdatera hela eller delar av ett långt värde, en kolumn av typen JET_coltypLongText eller 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
    );

Parameterar

sesid

Sessionen som ska användas för det här anropet.

tableid

Markören som ska användas för det här anropet.

columnid

Den JET_COLUMNID för kolumnen som ska hämtas. Alternativt kan ett columnid-värde på 0 (noll) anges. När columnid 0 (noll) anges behandlas alla taggade kolumner, glesa och flervärdeskolumner som en enda kolumn. Detta underlättar hämtning av alla glesa kolumner som finns i en post.

pvData

Indatabuffert som innehåller data som ska användas för kolumnvärde.

cbData

Storlek i byte för indatabufferten.

grbit

En grupp bitar som innehåller de alternativ som ska användas för det här anropet, som innehåller noll eller fler av följande:

Värde	Innebörd
JET_bitSetAppendLV	Det här alternativet används för att lägga till data i en kolumn av typen JET_coltypLongText eller JET_coltypLongBinary. Samma beteende kan uppnås genom att bestämma storleken på det befintliga långa värdet och ange ibLongValue i psetinfo. Det är dock enklare att använda den här grbiten eftersom det inte är nödvändigt att veta storleken på det befintliga kolumnvärdet.
JET_bitSetOverwriteLV	Det här alternativet används för att ersätta det befintliga långa värdet med de nyligen angivna data. När det här alternativet används är det som om det befintliga långa värdet har angetts till 0 (noll) längd innan du anger nya data.
JET_bitSetRevertToDefaultValue	Det här alternativet gäller endast för taggade, glesa eller flervärdeskolumner. Det gör att kolumnen returnerar standardkolumnvärdet för efterföljande hämtningskolumnåtgärder. Alla befintliga kolumnvärden tas bort.
JET_bitSetSeparateLV	Det här alternativet används för att tvinga fram ett långt värde, kolumner av typen JET_coltypLongText eller JET_coltypLongBinary, som ska lagras separat från resten av postdata. Detta inträffar normalt när storleken på det långa värdet förhindrar att det lagras med återstående postdata. Det här alternativet kan dock användas för att tvinga det långa värdet att lagras separat. Observera att långa värden fyra byte i storlek mindre inte kan tvingas att vara separata. I sådana fall ignoreras alternativet.
JET_bitSetSizeLV	Det här alternativet används för att tolka indatabufferten som ett heltalsantal byte som ska anges som längden på det långa värde som beskrivs av det angivna columnid och om det tillhandahålls sekvensnumret i psetinfo-itagSequence>. Om den angivna storleken är större än det befintliga kolumnvärdet utökas kolumnen med 0s. Om storleken är mindre än det befintliga kolumnvärdet trunkeras värdet.
JET_bitSetUniqueMultiValues	Det här alternativet används för att framtvinga att alla värden i en kolumn med flera värden är distinkta. Det här alternativet jämför källkolumndata, utan transformeringar, med andra befintliga kolumnvärden och ett fel returneras om en dubblett hittas. Om det här alternativet anges kan JET_bitSetAppendLV, JET_bitSetOverwriteLV och JET_bitSetSizeLV inte heller ges.
JET_bitSetUniqueNormalizedMultiValues	Det här alternativet används för att framtvinga att alla värden i en kolumn med flera värden är distinkta. Det här alternativet jämför den viktiga normaliserade omvandlingen av kolumndata med andra liknande transformerade befintliga kolumnvärden och ett fel returneras om en dubblett hittas. Om det här alternativet anges kan JET_bitSetAppendLV, JET_bitSetOverwriteLV och JET_bitSetSizeLV inte heller ges.
JET_bitSetZeroLength	Det här alternativet används för att ange ett värde till nolllängd. Normalt är ett kolumnvärde inställt på NULL genom att skicka ett cbMax på 0 (noll). Men för vissa typer, till exempel JET_coltypText, kan ett kolumnvärde vara 0 (noll) längd i stället för NULL, och det här alternativet används för att skilja mellan NULL och 0 (noll) längd. Not Om kolumnen i allmänhet är en kolumn med fast längd ignoreras den här biten och kolumnen är inställd på NULL. Men om kolumnen är en taggad kolumn med fast längd anges kolumnlängden till 0. När den taggade kolumnen med fast längd är inställd på 0 längd kommer försök att hämta kolumnen med JetRetrieveColumn eller JetRetrieveColumns att lyckas, men den faktiska längden som returneras i parametern cbActual är 0.
JET_bitSetIntrinsicLV	Det här alternativet används för att lagra hela det långa värdet i posten.
JET_bitSetCompressed	Det här alternativet används för att försöka komprimera data när data lagras. Windows 7: JET_bitSetCompressed introduceras i Windows 7.
JET_bitSetUncompressed	Det här alternativet används inte för komprimering vid lagring av data. Windows 7: JET_bitSetUnCompressed introduceras i Windows 7.

psetinfo

Pekare till valfria indataparametrar som kan anges för den här funktionen med hjälp av JET_SETINFO struktur.

Om psetinfo ges som NULL beter sig funktionen som om en itagSequence på 1 och en ibLongValue på 0 (noll) angavs. Detta gör att kolumnuppsättningen anger det första värdet för en kolumn med flera värden och anger långa data med början vid förskjutning 0 (noll).

Följande alternativ kan anges för den här parametern:

Värde	Innebörd
ibLongValue	Binär förskjutning till ett långt kolumnvärde där angivna data ska börja.
itagSequence	Sekvensnummer för önskat flervärdeskolumnvärde som ska anges. Om itagSequence är inställt på 0 (noll) ska det angivna värdet läggas till i slutet av sekvensen med flervärdesvärden. Om det angivna sekvensnumret är större än det senaste befintliga flervärdesvärdet läggs det angivna värdet till i slutet av sekvensen med värden. Om sekvensnumret motsvarar ett befintligt värde ersätts det värdet med det angivna värdet.

Värde

Innebörd

ibLongValue

Binär förskjutning till ett långt kolumnvärde där angivna data ska börja.

itagSequence

Sekvensnummer för önskat flervärdeskolumnvärde som ska anges. Om itagSequence är inställt på 0 (noll) ska det angivna värdet läggas till i slutet av sekvensen med flervärdesvärden. Om det angivna sekvensnumret är större än det senaste befintliga flervärdesvärdet läggs det angivna värdet till i slutet av sekvensen med värden. Om sekvensnumret motsvarar ett befintligt värde ersätts det värdet med det angivna värdet.

Returvärde

Den här funktionen returnerar JET_ERR-datatypen med någon av följande returkoder. Mer information om möjliga ESE-fel finns i Extensible Storage Engine Errors and Error Handling Parameters (Utökningsbara lagringsmotorfel och felhanteringsparametrar).

Returkod	Beskrivning
JET_errSuccess	Åtgärden har slutförts.
JET_errBadColumnId	Det angivna kolumn-ID:t ligger utanför de juridiska gränserna för ett kolumn-ID.
JET_errClientRequestToStopJetService	Det går inte att slutföra åtgärden eftersom all aktivitet på den instans som är associerad med sessionen har upphört till följd av ett anrop till JetStopService.
JET_errColumnNotFound	Kolumnen som beskrivs av det angivna columnid finns inte i tabellen.
JET_errColumnNotUpdatable	Ett ogiltigt försök gjordes att uppdatera ett långt värde under en ursprunglig uppdateringsåtgärd för att ta bort en infogningskopia.
JET_errColumnTooBig	Angivna kolumnvärdedata som anges i indatabufferten överskrider storleksbegränsningen, antingen naturlig för en kolumn med fast längd eller konfigurerad för text med fast längd eller binära kolumner. Det här felet returneras också när du skickar mer än 1 024 byte data för en lång kolumn och anger flaggan JET_bitSetIntrinsicLV.
JET_errInstanceUnavailable	Det går inte att slutföra åtgärden eftersom den instans som är associerad med sessionen har påträffat ett allvarligt fel som kräver att åtkomsten till alla data återkallas för att skydda dataintegriteten. Windows XP: Det här felet returneras endast av Windows XP och senare versioner.
JET_errInvalidBufferSize	Datastorleken för det angivna kolumnvärdet matchar inte det som är naturligt för datatypen fast längd.
JET_errInvalidColumnType	Ett olagligt försök gjordes att uppdatera en automatisk inkrementell kolumn under en infognings- eller uppdateringsåtgärd, eller att uppdatera en versionskolumn under en ersättningsåtgärd.
JET_errInvalidgrbit	De angivna alternativen är okända eller en otillåten kombination av kända bitinställningar.
JET_errInvalidParameter	Angiven psetinfo-cbStruct> är inte en giltig storlek för JET_SETINFO struktur.
JET_errMultiValuedDuplicate	Åtgärden set column försökte skapa ett duplicerat värde och angav antingen JET_bitSetUniqueMultiValues eller JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	Det går inte att slutföra åtgärden eftersom den instans som är associerad med sessionen inte har initierats ännu.
JET_errNotInTransaction	Ett olagligt försök gjordes att uppdatera ett långt kolumnvärde när den anropande sessionen inte fanns i en transaktion.
JET_errNullInvalid	Ett olagligt försök gjordes att ange en icke-NULL-kolumn till NULL.
JET_errColumnIllegalNull	Samma som JET_errNullInvalid.
JET_errRecordTooBig	Kolumnvärdet kunde inte anges till värdet i indatabufferten eftersom det skulle ha gjort att posten överskrider sin storleksbegränsning för sidan. Kolumner av typen JET_coltypLongText eller JET_coltypLongBinary kan lagras separat från återstående postdata. Andra kolumner måste dock lagras med posten och kan orsaka att poststorleksbegränsningen överskrids. Även långa kolumner kräver 5 byte utrymme i posten som en länkning och även detta kan leda till att JET_errRecordTooBig returneras.
JET_errRestoreInProgress	Det går inte att slutföra åtgärden eftersom en återställningsåtgärd pågår på den instans som är associerad med sessionen.
JET_errSessionSharingViolation	Samma session kan inte användas för fler än en tråd samtidigt. Windows XP: Det här felet returneras endast av Windows XP och senare versioner.
JET_errTermInProgress	Det går inte att slutföra åtgärden eftersom den instans som är associerad med sessionen stängs av.
JET_errUpdateNotPrepared	Markören håller för närvarande inte på att antingen infoga en ny post eller uppdatera en befintlig post.
JET_errVersionStoreOutOfMemory	Det här felet uppstår när den konfigurerade storleken på versionsarkivet inte räcker för att lagra alla utestående uppdateringar.
JET_wrnColumnMaxTruncated	Kolumnvärdet i indatabufferten överskred den maximala konfigurerade längden för en kolumn med variabel längd och trunkerades.

När det lyckas anges den önskade delen av ett kolumnvärde för den angivna kolumnen med data kopierade från indatabufferten. Datauppsättningen kan ha trunkerats om den överskred den maximala längd som angetts för en kolumn med variabel längd.

Vid fel lämnas markörens plats oförändrad och inga kolumnvärdedata uppdateras i kopieringsbufferten.

Anmärkningar

Ange långa värden, värden för kolumner JET_coltypLongBinary av typen JET_coltypLongText eller JET_coltypLongBinary, bör endast göras när den anropande sessionen är i en transaktion. Om den anropande sessionen inte ingår i en transaktion kan ändringar av långa värden som lagras separat utföras helt även när uppdateringsåtgärden senare avbryts. Om den anropande sessionen är i en transaktion kan effekterna av uppdateringen återställas helt genom att avbryta uppdateringen och återställa sessionstransaktionen.

Indexuppdateringar utförs inte som ett resultat av JetSetColumn-åtgärder . Index uppdateras i stället först när alla kolumnändringar har slutförts och JetUpdate anropas . Detta tillåter den mest effektiva uppdateringen av index när index innebär att mer än en kolumn ändras.

En post är begränsad i storlek baserat på databasens sidstorlek. Alla långa värden i posten som är större än fem byte lagras separat från posten om data i posten överskrider sin gräns till följd av en JetSetColumn-åtgärd . Felet JET_errRecordTooBig returneras endast efter att alla data för separat postkolumn har lagrats separat från posten och posten fortfarande överskrider poststorleksgränsen.

Kravspecifikation

Krav	Värde
Klient	Kräver Windows Vista, Windows XP eller Windows 2000 Professional.
Server	Kräver Windows Server 2008, Windows Server 2003 eller Windows 2000 Server.
Rubrik	Deklarerad i Esent.h.
Bibliotek	Använd ESENT.lib.
DLL	Kräver ESENT.dll.

Se även

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns

Feedback

Var den här sidan till hjälp?

Dela via

JetSetColumn-funktion