JetSetColumn, functie

van toepassing op: Windows | Windows Server

JetSetColumn, functie

De functie JetSetColumn wijzigt één kolomwaarde in een gewijzigde record die moet worden ingevoegd of om de huidige record bij te werken. Het kan een bestaande waarde overschrijven, een nieuwe waarde toevoegen aan een reeks waarden in een kolom met meerdere waarden, een waarde verwijderen uit een reeks waarden in een kolom met meerdere waarden of een geheel of gedeeltelijk bijwerken van een lange waarde, een kolom van het type JET_coltypLongText of 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
    );

Parameterwaarden

sesid

De sessie die moet worden gebruikt voor deze aanroep.

tableid

De cursor die moet worden gebruikt voor deze aanroep.

columnid

De JET_COLUMNID van de kolom die moet worden opgehaald. U kunt ook een kolom-id-waarde van 0 (nul) opgeven. Wanneer columnid 0 (nul) wordt gegeven, worden alle gelabelde kolommen, parserings- en multiwaardekolommen behandeld als één kolom. Dit vereenvoudigt het ophalen van alle parserende kolommen die aanwezig zijn in een record.

pvData-

Invoerbuffer met gegevens die moeten worden gebruikt voor kolomwaarde.

cbData

Grootte in bytes van de invoerbuffer.

grbit-

Een groep bits met de opties die moeten worden gebruikt voor deze aanroep, waaronder nul of meer van de volgende opties:

Waarde	Betekenis
JET_bitSetAppendLV	Deze optie wordt gebruikt om gegevens toe te voegen aan een kolom van het type JET_coltypLongText of JET_coltypLongBinary. Hetzelfde gedrag kan worden bereikt door de grootte van de bestaande lange waarde te bepalen en ibLongValue in psetinfo op te geven. Het is echter eenvoudiger om deze grbit te gebruiken, omdat de grootte van de bestaande kolomwaarde niet nodig is.
JET_bitSetOverwriteLV	Deze optie wordt gebruikt om de bestaande lange waarde te vervangen door de zojuist verstrekte gegevens. Wanneer deze optie wordt gebruikt, is dit alsof de bestaande lange waarde is ingesteld op 0 (nul) voordat u de nieuwe gegevens instelt.
JET_bitSetRevertToDefaultValue	Deze optie is alleen van toepassing op gelabelde, geparseerde of kolommen met meerdere waarden. Dit zorgt ervoor dat de kolom de standaardkolomwaarde retourneert bij volgende ophaalt kolombewerkingen. Alle bestaande kolomwaarden worden verwijderd.
JET_bitSetSeparateLV	Deze optie wordt gebruikt om een lange waarde, kolommen van het type JET_coltypLongText of JET_coltypLongBinary, afzonderlijk van de rest van recordgegevens op te slaan. Dit gebeurt normaal wanneer de grootte van de lange waarde voorkomt dat deze wordt opgeslagen met resterende recordgegevens. Deze optie kan echter worden gebruikt om de lange waarde afzonderlijk op te slaan. Houd er rekening mee dat lange waarden vier bytes kleiner niet kunnen worden gescheiden. In dergelijke gevallen wordt de optie genegeerd.
JET_bitSetSizeLV	Deze optie wordt gebruikt om de invoerbuffer te interpreteren als een geheel getal van bytes dat moet worden ingesteld als de lengte van de lange waarde die wordt beschreven door de opgegeven columnid en indien opgegeven, het volgnummer in psetinfo-itagSequence>. Als de opgegeven grootte groter is dan de bestaande kolomwaarde, wordt de kolom uitgebreid met 0s. Als de grootte kleiner is dan de bestaande kolomwaarde, wordt de waarde afgekapt.
JET_bitSetUniqueMultiValues	Deze optie wordt gebruikt om af te dwingen dat alle waarden in een kolom met meerdere waarden verschillend zijn. Met deze optie worden de bronkolomgegevens, zonder transformaties, vergeleken met andere bestaande kolomwaarden en wordt een fout geretourneerd als er een duplicaat wordt gevonden. Als deze optie is opgegeven, kunnen JET_bitSetAppendLV JET_bitSetOverwriteLV en JET_bitSetSizeLV niet ook worden gegeven.
JET_bitSetUniqueNormalizedMultiValues	Deze optie wordt gebruikt om af te dwingen dat alle waarden in een kolom met meerdere waarden verschillend zijn. Met deze optie wordt de genormaliseerde sleuteltransformatie van kolomgegevens vergeleken met andere vergelijkbare getransformeerde bestaande kolomwaarden en wordt een fout geretourneerd als er een duplicaat wordt gevonden. Als deze optie is opgegeven, kunnen JET_bitSetAppendLV JET_bitSetOverwriteLV en JET_bitSetSizeLV niet ook worden gegeven.
JET_bitSetZeroLength	Deze optie wordt gebruikt om een waarde in te stellen op nullengte. Normaal gesproken wordt een kolomwaarde ingesteld op NULL door een cbMax van 0 (nul) door te geven. Voor sommige typen, zoals JET_coltypText, kan een kolomwaarde echter 0 (nul) zijn in plaats van NULL en wordt deze optie gebruikt om onderscheid te maken tussen NULL en 0 (nul). Notitie Als de kolom een kolom met een vaste lengte is, wordt deze bit genegeerd en wordt de kolom ingesteld op NULL. Als de kolom echter een kolom met een vaste lengte is, wordt de kolomlengte ingesteld op 0. Wanneer de kolom met vaste lengte is ingesteld op 0, wordt geprobeerd de kolom op te halen met JetRetrieveColumn of JetRetrieveColumns , maar de werkelijke lengte die wordt geretourneerd in de cbActual-parameter is 0.
JET_bitSetIntrinsicLV	Deze optie wordt gebruikt om de hele lange waarde in de record op te slaan.
JET_bitSetCompressed	Deze optie wordt gebruikt om gegevenscompressie uit te proberen bij het opslaan van de gegevens. Windows 7: JET_bitSetCompressed wordt geïntroduceerd in Windows 7.
JET_bitSetUncompressed	Deze optie wordt niet gebruikt om compressie uit te proberen bij het opslaan van de gegevens. Windows 7: JET_bitSetUnCompressed wordt geïntroduceerd in Windows 7.

psetinfo

Aanwijzer naar optionele invoerparameters die voor deze functie kunnen worden ingesteld met behulp van de JET_SETINFO structuur.

Als psetinfo wordt gegeven als NULL , gedraagt de functie zich alsof een itagSequence van 1 en een ibLongValue van 0 (nul) zijn gegeven. Dit zorgt ervoor dat de kolomset de eerste waarde van een kolom met meerdere waarden instelt en lange gegevens instelt die beginnen bij verschuiving 0 (nul).

De volgende opties kunnen worden ingesteld voor deze parameter:

Waarde	Betekenis
ibLongValue	Binaire verschuiving in een lange kolomwaarde waar setgegevens moeten beginnen.
itagSequence	Volgnummer van de gewenste kolomwaarde met meerdere waarden die u wilt instellen. Als itagSequence is ingesteld op 0 (nul), moet de opgegeven waarde worden toegevoegd aan het einde van de reeks waarden met meerdere waarden. Als het opgegeven reeksnummer groter is dan de laatste bestaande waarde met meerdere waarden, wordt opnieuw de opgegeven waarde toegevoegd aan het einde van de reeks waarden. Als het volgnummer overeenkomt met een bestaande waarde, wordt die waarde vervangen door de opgegeven waarde.

Retourwaarde

Met deze functie wordt het JET_ERR gegevenstype geretourneerd met een van de volgende retourcodes. Zie Extensible Storage Engine Errors and Error Handling Parameters (Extensible Storage Engine Errors and Error Handling Parameters) (Extensible Storage Engine Errors and Error Handling Parameters) voor meer informatie over de mogelijke ESE-fouten.

Retourcode	Beschrijving
JET_errSuccess	De bewerking is voltooid.
JET_errBadColumnId	De opgegeven kolom-id valt buiten de wettelijke limieten van een kolom-id.
JET_errClientRequestToStopJetService	Het is niet mogelijk om de bewerking te voltooien omdat alle activiteit op het exemplaar dat aan de sessie is gekoppeld, is beëindigd als gevolg van een aanroep naar JetStopService.
JET_errColumnNotFound	De kolom die wordt beschreven door de opgegeven columnid , bestaat niet in de tabel.
JET_errColumnNotUpdatable	Er is een ongeldige poging gedaan om een lange waarde bij te werken tijdens een invoegbewerking voor het verwijderen van de oorspronkelijke update.
JET_errColumnTooBig	De opgegeven kolomwaardegegevens die in de invoerbuffer worden opgegeven, overschrijden de maximale grootte voor een kolom met vaste lengte of zijn geconfigureerd voor tekst of binaire kolommen met vaste lengte. Deze fout wordt ook geretourneerd bij het doorgeven van meer dan 1024 bytes aan gegevens voor een lange kolom en het instellen van de vlag JET_bitSetIntrinsicLV.
JET_errInstanceUnavailable	Het is niet mogelijk om de bewerking te voltooien omdat het exemplaar dat is gekoppeld aan de sessie een fatale fout heeft opgetreden die vereist dat toegang tot alle gegevens wordt ingetrokken om de integriteit van die gegevens te beschermen. Windows XP: Deze fout wordt alleen geretourneerd door Windows XP en latere versies.
JET_errInvalidBufferSize	De gegevensgrootte van de opgegeven kolomwaarde komt niet overeen met wat natuurlijk is voor het gegevenstype vaste lengte.
JET_errInvalidColumnType	Er is een ongeldige poging gedaan om een kolom voor automatisch verhogen bij te werken tijdens een invoeg- of bijwerkbewerking, of om een versiekolom bij te werken tijdens een vervangingsbewerking.
JET_errInvalidgrbit	De opgegeven opties zijn onbekend of een ongeldige combinatie van bekende bitinstellingen.
JET_errInvalidParameter	De opgegeven psetinfo-cbStruct> is geen geldige grootte voor de JET_SETINFO structuur.
JET_errMultiValuedDuplicate	De ingestelde kolombewerking heeft geprobeerd een dubbele waarde te maken en JET_bitSetUniqueMultiValues of JET_bitSetUniqueNormalizedMultiValues opgegeven.
JET_errNotInitialized	Het is niet mogelijk om de bewerking te voltooien omdat het exemplaar dat is gekoppeld aan de sessie nog niet is geïnitialiseerd.
JET_errNotInTransaction	Er is een ongeldige poging gedaan om een lange kolomwaarde bij te werken wanneer de aanroepende sessie zich niet in een transactie bevond.
JET_errNullInvalid	Er is een ongeldige poging gedaan om een niet-NULL-kolom in te stellen op NULL.
JET_errColumnIllegalNull	Hetzelfde als JET_errNullInvalid.
JET_errRecordTooBig	De kolomwaarde kan niet worden ingesteld op de waarde in de invoerbuffer, omdat de record de limiet voor de paginagrootte van de record heeft overschreden. Kolommen van het type JET_coltypLongText of JET_coltypLongBinary kunnen afzonderlijk van de resterende recordgegevens worden opgeslagen. Andere kolommen moeten echter worden opgeslagen met de record en kunnen ertoe leiden dat de beperking van de recordgrootte wordt overschreden. Zelfs lange kolommen vereisen 5 bytes ruimte in de record als een koppeling en dit kan ook leiden tot JET_errRecordTooBig worden geretourneerd.
JET_errRestoreInProgress	Het is niet mogelijk om de bewerking te voltooien omdat er een herstelbewerking wordt uitgevoerd op het exemplaar dat aan de sessie is gekoppeld.
JET_errSessionSharingViolation	Dezelfde sessie kan niet tegelijkertijd worden gebruikt voor meer dan één thread. Windows XP: Deze fout wordt alleen geretourneerd door Windows XP en latere versies.
JET_errTermInProgress	Het is niet mogelijk om de bewerking te voltooien omdat het exemplaar dat is gekoppeld aan de sessie wordt afgesloten.
JET_errUpdateNotPrepared	De cursor is momenteel niet bezig met het invoegen van een nieuwe record of het bijwerken van een bestaande record.
JET_errVersionStoreOutOfMemory	Deze fout treedt op wanneer de geconfigureerde grootte van het versiearchief onvoldoende is om alle openstaande updates te bewaren.
JET_wrnColumnMaxTruncated	De kolomwaarde in de invoerbuffer heeft de maximaal geconfigureerde lengte voor een kolom met variabele lengte overschreden en is afgekapt.

Bij succes wordt het gewenste gedeelte van een kolomwaarde voor de opgegeven kolom ingesteld met gegevens die zijn gekopieerd uit de invoerbuffer. De gegevensset is mogelijk afgekapt als deze de maximale lengte heeft overschreden die is opgegeven voor een kolom met variabele lengte.

Bij een fout blijft de cursorlocatie ongewijzigd en worden er geen kolomwaardegegevens bijgewerkt in de kopieerbuffer.

Opmerkingen

Het instellen van lange waarden, waarden voor kolommen JET_coltypLongBinary van het type JET_coltypLongText of JET_coltypLongBinary, moet alleen worden uitgevoerd wanneer de aanroepende sessie zich in een transactie bevindt. Als de aanroepende sessie zich niet in een transactie bevindt, kunnen wijzigingen in lange waarden die afzonderlijk worden opgeslagen, volledig worden doorgevoerd, zelfs wanneer de updatebewerking later wordt geannuleerd. Als de aanroepende sessie zich in een transactie bevindt, kunnen de gevolgen van de update volledig worden teruggedraaid door de update te annuleren en de sessietransactie terug te draaien.

Indexupdates worden niet uitgevoerd als gevolg van JetSetColumn-bewerkingen . In plaats daarvan worden indexen pas bijgewerkt nadat alle kolomwijzigingen zijn voltooid en JetUpdate wordt aangeroepen. Dit maakt het efficiëntst bijwerken van indexen mogelijk wanneer indexen betrekking hebben op meer dan één kolom die wordt gewijzigd.

Een record is beperkt in grootte op basis van het paginaformaat van de database. Eventuele lange waarden in de record die groter zijn dan vijf bytes, worden gescheiden van de record opgeslagen als de gegevens in de record de limiet overschrijden als gevolg van een JetSetColumn-bewerking . De fout JET_errRecordTooBig wordt alleen geretourneerd nadat alle kolomgegevens van afzonderlijke records afzonderlijk van de record zijn opgeslagen en de record nog steeds de limiet voor de recordgrootte overschrijdt.

Behoeften

Voorwaarde	Waarde
Klant	Vereist Windows Vista, Windows XP of Windows 2000 Professional.
Server	Vereist Windows Server 2008, Windows Server 2003 of Windows 2000 Server.
Koptekst	Gedeclareerd in Esent.h.
Bibliotheek	Gebruik ESENT.lib.
DLL	Vereist ESENT.dll.

Zie ook

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn-
JetSetColumns-