JetSetColumn-Funktion

Gilt für: Windows | Windows Server

JetSetColumn-Funktion

Die JetSetColumn-Funktion ändert einen einzelnen Spaltenwert in einem geänderten Datensatz, der eingefügt oder aktualisiert werden soll. Sie kann einen vorhandenen Wert überschreiben, einer Sequenz von Werten in einer mehrwertigen Spalte einen neuen Wert hinzufügen, einen Wert aus einer Sequenz von Werten in einer mehrwertigen Spalte entfernen oder einen langen Wert ganz oder teilweise aktualisieren, eine Spalte vom Typ JET_coltypLongText oder 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
    );

Parameter

sesid

Die Sitzung, die für diesen Aufruf verwendet werden soll.

tableid

Der Cursor, der für diesen Aufruf verwendet werden soll.

Columnid

Die JET_COLUMNID der abzurufenden Spalte. Alternativ kann ein columnid-Wert von 0 (null) angegeben werden. Wenn columnid 0 (null) angegeben wird, werden alle markierten Spalten, Sparsespalten und mehrwertigen Spalten, als einzelne Spalte behandelt. Dies erleichtert das Abrufen aller Sparsespalten, die in einem Datensatz vorhanden sind.

pvData

Eingabepuffer mit Daten, die für den Spaltenwert verwendet werden sollen.

cbData

Größe des Eingabepuffers in Bytes.

grbit

Eine Gruppe von Bits, die die für diesen Aufruf zu verwendenden Optionen enthalten, die null oder mehr der folgenden Elemente enthalten:

Wert

Bedeutung

JET_bitSetAppendLV

Diese Option wird verwendet, um Daten an eine Spalte vom Typ JET_coltypLongText oder JET_coltypLongBinaryanzufügen. Das gleiche Verhalten kann erreicht werden, indem die Größe des vorhandenen long-Werts bestimmt und ibLongValue in psetinfoangegeben wird. Es ist jedoch einfacher, dieses Grbit zu verwenden, da es nicht erforderlich ist, die Größe des vorhandenen Spaltenwerts zu kennen.

JET_bitSetOverwriteLV

Diese Option wird verwendet, um den vorhandenen long-Wert durch die neu bereitgestellten Daten zu ersetzen. Wenn diese Option verwendet wird, sieht es so aus, als ob der vorhandene long-Wert vor dem Festlegen der neuen Daten auf 0 (null) länge festgelegt wurde.

JET_bitSetRevertToDefaultValue

Diese Option gilt nur für markierte, sparse- oder mehrwertige Spalten. Dies bewirkt, dass die Spalte bei nachfolgenden Abrufspaltenvorgängen den Standardspaltenwert zurückgibt. Alle vorhandenen Spaltenwerte werden entfernt.

JET_bitSetSeparateLV

Diese Option wird verwendet, um zu erzwingen, dass ein long-Wert( Spalten vom Typ JET_coltypLongText oder JET_coltypLongBinary )getrennt von den restlichen Datensatzdaten gespeichert wird. Dies tritt normalerweise auf, wenn die Größe des long-Werts verhindert, dass er mit den verbleibenden Datensatzdaten gespeichert wird. Diese Option kann jedoch verwendet werden, um zu erzwingen, dass der long-Wert separat gespeichert wird. Beachten Sie, dass lange Werte, die vier Bytes kleiner sind, nicht erzwungen werden können, getrennt zu sein. In solchen Fällen wird die Option ignoriert.

JET_bitSetSizeLV

Diese Option wird verwendet, um den Eingabepuffer als eine ganzzahlige Anzahl von Bytes zu interpretieren, die als Länge des long-Werts festgelegt werden soll, der von der angegebenen columnid beschrieben wird, und, falls angegeben, die Sequenznummer in psetinfo- > itagSequence. Wenn die angegebene Größe größer als der vorhandene Spaltenwert ist, wird die Spalte um 0 (0) erweitert. Wenn die Größe kleiner als der vorhandene Spaltenwert ist, wird der Wert abgeschnitten.

JET_bitSetUniqueMultiValues

Diese Option wird verwendet, um zu erzwingen, dass alle Werte in einer mehrwertigen Spalte unterschiedlich sind. Diese Option vergleicht die Quellspaltendaten ohne Transformationen mit anderen vorhandenen Spaltenwerten, und ein Fehler wird zurückgegeben, wenn ein Duplikat gefunden wird. Wenn diese Option angegeben ist, können JET_bitSetAppendLV, JET_bitSetOverwriteLV und JET_bitSetSizeLV nicht ebenfalls angegeben werden.

JET_bitSetUniqueNormalizedMultiValues

Diese Option wird verwendet, um zu erzwingen, dass alle Werte in einer mehrwertigen Spalte unterschiedlich sind. Diese Option vergleicht die schlüsselnormierte Transformation von Spaltendaten mit anderen ähnlich transformierten vorhandenen Spaltenwerten, und es wird ein Fehler zurückgegeben, wenn ein Duplikat gefunden wird. Wenn diese Option angegeben ist, können JET_bitSetAppendLV, JET_bitSetOverwriteLV und JET_bitSetSizeLV nicht ebenfalls angegeben werden.

JET_bitSetZeroLength

Diese Option wird verwendet, um einen Wert auf die Länge 0 festzulegen. Normalerweise wird ein Spaltenwert auf NULL festgelegt, indem ein cbMax von 0 (null) übergeben wird. Für einige Typen, z. B. JET_coltypText, kann ein Spaltenwert jedoch 0 (null) anstatt NULLlang sein, und diese Option wird verwendet, um zwischen NULL und 0 (null) Länge zu unterscheiden.

Hinweis Wenn es sich bei der Spalte um eine Spalte mit fester Länge handelt, wird dieses Bit im Allgemeinen ignoriert, und die Spalte wird auf NULLfestgelegt. Wenn es sich bei der Spalte jedoch um eine spalte mit fester Länge handelt, wird die Spaltenlänge auf 0 festgelegt. Wenn die markierte Spalte mit fester Länge auf die Länge 0 festgelegt ist, wird versucht, die Spalte mit JetRetrieveColumn oder JetRetrieveColumns abzurufen, aber die tatsächliche Länge, die im cbActual-Parameter zurückgegeben wird, ist 0.

JET_bitSetIntrinsicLV

Diese Option wird verwendet, um den gesamten long-Wert im Datensatz zu speichern.

JET_bitSetCompressed

Diese Option wird verwendet, um beim Speichern der Daten eine Datenkomprimierung zu versuchen.

Windows 7: JET_bitSetCompressed wird in Windows 7 eingeführt.

JET_bitSetUncompressed

Diese Option wird beim Speichern der Daten nicht zum Komprimieren verwendet.

Windows 7: JET_bitSetUnCompressed wird in Windows 7 eingeführt.

psetinfo

Zeiger auf optionale Eingabeparameter, die für diese Funktion mithilfe der JET_SETINFO-Struktur festgelegt werden können.

Wenn psetinfo als NULL angegeben wird, verhält sich die Funktion so, als ob eine ItagSequence von 1 und ein ibLongValue von 0 (null) angegeben worden wären. Dadurch wird der erste Wert einer mehrwertigen Spalte festgelegt, und lange Daten werden beginnend bei Offset 0 (null) festgelegt.

Für diesen Parameter können die folgenden Optionen festgelegt werden:

Wert

Bedeutung

ibLongValue

Binärer Offset in einen long-Spaltenwert, bei dem festgelegte Daten beginnen sollen.

itagSequence

Sequenznummer des gewünschten mehrwertigen Spaltenwerts, der festgelegt werden soll. Wenn itagSequence auf 0 (null) festgelegt ist, sollte der angegebene Wert an das Ende der Sequenz von mehrwertigen Werten angefügt werden. Wenn die angegebene Sequenznummer größer als der letzte vorhandene mehrwertige Wert ist, wird der angegebene Wert erneut an das Ende der Sequenz von Werten angefügt. Wenn die Sequenznummer einem vorhandenen Wert entspricht, wird dieser Wert durch den angegebenen Wert ersetzt.

Rückgabewert

Diese Funktion gibt den JET_ERR Datentyp mit einem der folgenden Rückgabecodes zurück. Weitere Informationen zu den möglichen ESE-Fehlern finden Sie unter Extensible Storage Engine Errors and Error Handling Parameters.

Rückgabecode

Beschreibung

JET_errSuccess

Der Vorgang wurde erfolgreich abgeschlossen.

JET_errBadColumnId

Die angegebene Spalten-ID liegt außerhalb der rechtlichen Grenzen einer Spalten-ID.

JET_errClientRequestToStopJetService

Es ist nicht möglich, den Vorgang abzuschließen, da alle Aktivitäten auf der Instanz, die der Sitzung zugeordnet ist, als Ergebnis eines Aufrufs von JetStopServiceaufgetreten sind.

JET_errColumnNotFound

Die von der angegebenen columnid beschriebene Spalte ist in der Tabelle nicht vorhanden.

JET_errColumnNotUpdatable

Es wurde ein unzulässiger Versuch unternommen, einen long-Wert während eines ursprünglichen Aktualisierungsvorgangs zum Löschen von Einfügekopien zu aktualisieren.

JET_errColumnTooBig

Die angegebenen Spaltenwertdaten, die im Eingabepuffer angegeben werden, überschreiten die Größenbeschränkung , entweder natürlich für eine Spalte fester Länge oder konfiguriert für Text mit fester Länge oder binäre Spalten. Dieser Fehler wird auch zurückgegeben, wenn für eine lange Spalte mehr als 1.024 Byte an Daten übergeben und das flag JET_bitSetIntrinsicLV festgelegt wird.

JET_errInstanceUnavailable

Es ist nicht möglich, den Vorgang abzuschließen, da für die instanz, die der Sitzung zugeordnet ist, ein schwerwiegender Fehler aufgetreten ist, der erfordert, dass der Zugriff auf alle Daten widerrufen wird, um die Integrität dieser Daten zu schützen.

Windows XP: Dieser Fehler wird nur von Windows XP und späteren Versionen zurückgegeben.

JET_errInvalidBufferSize

Die datengröße des angegebenen Spaltenwerts stimmt nicht mit der natürlichen Größe für den Datentyp fester Länge überein.

JET_errInvalidColumnType

Es wurde ein unzulässiger Versuch unternommen, eine Spalte mit automatischem Inkrement während eines Einfüge- oder Aktualisierungsvorgangs zu aktualisieren oder eine Versionsspalte während eines Ersetzungsvorgangs zu aktualisieren.

JET_errInvalidgrbit

Die bereitgestellten Optionen sind unbekannt oder eine unzulässige Kombination bekannter Biteinstellungen.

JET_errInvalidParameter

Die angegebene psetinfo- > cbStruct ist keine gültige Größe für die JET_SETINFO-Struktur.

JET_errMultiValuedDuplicate

Der Vorgang set column hat versucht, einen doppelten Wert zu erstellen, und entweder JET_bitSetUniqueMultiValues oder JET_bitSetUniqueNormalizedMultiValues angegeben.

JET_errNotInitialized

Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete Instanz noch nicht initialisiert wurde.

JET_errNotInTransaction

Es wurde ein unzulässiger Versuch unternommen, einen long-Spaltenwert zu aktualisieren, wenn sich die aufrufende Sitzung nicht in einer Transaktion befand.

JET_errNullInvalid

Es wurde ein unzulässiger Versuch unternommen, eine Spalte ungleichNULL auf NULLfestzulegen.

JET_errColumnIllegalNull

Entspricht JET_errNullInvalid.

JET_errRecordTooBig

Der Spaltenwert konnte nicht auf den Wert im Eingabepuffer festgelegt werden, da er dazu geführt hätte, dass der Datensatz seine Größenbeschränkung im Zusammenhang mit der Seitengröße überschritten hätte. Spalten vom Typ JET_coltypLongText oder JET_coltypLongBinary können getrennt von den verbleibenden Datensatzdaten gespeichert werden. Andere Spalten müssen jedoch mit dem Datensatz gespeichert werden und können dazu führen, dass die Größenbeschränkung des Datensatzes überschritten wird. Selbst lange Spalten benötigen 5 Bytes Speicherplatz innerhalb des Datensatzes als Verknüpfung. Dies kann auch dazu führen, dass JET_errRecordTooBig zurückgegeben wird.

JET_errRestoreInProgress

Es ist nicht möglich, den Vorgang abzuschließen, da ein Wiederherstellungsvorgang für die Instanz ausgeführt wird, die der Sitzung zugeordnet ist.

JET_errSessionSharingViolation

Dieselbe Sitzung kann nicht für mehrere Threads gleichzeitig verwendet werden.

Windows XP: Dieser Fehler wird nur von Windows XP und späteren Versionen zurückgegeben.

JET_errTermInProgress

Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete Instanz heruntergefahren wird.

JET_errUpdateNotPrepared

Der Cursor ist derzeit nicht dabei, entweder einen neuen Datensatz einzufügen oder einen vorhandenen Datensatz zu aktualisieren.

JET_errVersionStoreOutOfMemory

Dieser Fehler tritt auf, wenn die konfigurierte Größe des Versionsspeichers nicht ausreicht, um alle ausstehenden Updates zu speichern.

JET_wrnColumnMaxTruncated

Der Spaltenwert im Eingabepuffer hat die maximal konfigurierte Länge für eine Spalte variabler Länge überschritten und wurde abgeschnitten.

Bei Erfolg wird der gewünschte Teil eines Spaltenwerts für die angegebene Spalte mit Daten festgelegt, die aus dem Eingabepuffer kopiert werden. Das Dataset wurde möglicherweise abgeschnitten, wenn es die maximale Länge überschritten hat, die für eine Spalte variabler Länge angegeben wurde.

Bei einem Fehler bleibt die Cursorposition unverändert, und im Kopierpuffer werden keine Spaltenwertdaten aktualisiert.

Bemerkungen

Lange Werte, Werte für Spalten JET_coltypLongBinary vom Typ JET_coltypLongText oder JET_coltypLongBinary, sollten nur festgelegt werden, wenn sich die aufrufende Sitzung in einer Transaktion befindet. Wenn sich die aufrufende Sitzung nicht in einer Transaktion befindet, wird für Änderungen an langen Werten, die separat gespeichert werden, möglicherweise auch dann ein vollständiger Commit ausgeführt, wenn der Updatevorgang später abgebrochen wird. Wenn sich die aufrufende Sitzung in einer Transaktion befindet, können die Auswirkungen des Updates vollständig zurückgesetzt werden, indem das Update abgebrochen und ein Rollback für die Sitzungstransaktion ausgeführt wird.

Indexaktualisierungen werden nicht als Ergebnis von JetSetColumn-Vorgängen ausgeführt. Stattdessen werden Indizes erst aktualisiert, nachdem alle Spaltenänderungen abgeschlossen sind und JetUpdate aufgerufen wird. Dies ermöglicht die effizienteste Aktualisierung von Indizes, wenn Indizes mehr als eine Spalte betreffen, die geändert wird.

Ein Datensatz ist abhängig von der Größe der Datenbankseite begrenzt. Alle long-Werte im Datensatz, die größer als fünf Bytes sind, werden getrennt vom Datensatz gespeichert, wenn die Daten im Datensatz den Grenzwert aufgrund eines JetSetColumn-Vorgangs überschreiten. Der Fehler JET_errRecordTooBig wird nur zurückgegeben, nachdem alle Daten der Spalte mit getrennten Datensätzen getrennt vom Datensatz gespeichert wurden und der Datensatz weiterhin das Größenlimit des Datensatzes überschreitet.

Requirements (Anforderungen)

Anforderung Wert

Client

Erfordert Windows Vista, Windows XP oder Windows 2000 Professional.

Server

Erfordert Windows Server 2008, Windows Server 2003 oder Windows 2000 Server.

Header

Deklariert in Esent.h.

Bibliothek

Verwenden Sie ESENT.lib.

DLL

Erfordert ESENT.dll.

Weitere Informationen

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns