JetSetColumn-Funktion

Artikel
06/12/2023

Gilt für: Windows | Windows Server

JetSetColumn-Funktion

Die JetSetColumn-Funktion ändert einen einzelnen Spaltenwert in einem geänderten Datensatz, der eingefügt oder der aktuelle Datensatz aktualisiert werden soll. Es 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 ganzen oder einen Teil eines langen Werts, einer Spalte vom Typ JET_coltypLongText oder JET_coltypLongBinary aktualisieren.

    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, Sparse- und Mehrwertspalten, als einzelne Spalte behandelt. Dies erleichtert das Abrufen aller Sparsespalten, die in einem Datensatz vorhanden sind.

pvData

Eingabepuffer, der Daten enthält, die für den Spaltenwert verwendet werden sollen.

cbData

Größe des Eingabepuffers in Byte.

grbit

Eine Gruppe von Bits, die die Optionen enthalten, die für diesen Aufruf verwendet werden sollen, einschließlich 0 oder mehr der folgenden Optionen:

Wert	Bedeutung
JET_bitSetAppendLV	Diese Option wird verwendet, um Daten an eine Spalte vom Typ JET_coltypLongText oder JET_coltypLongBinary anzufügen. Das gleiche Verhalten kann erreicht werden, indem die Größe des vorhandenen long-Werts bestimmt und ibLongValue in psetinfo angegeben 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, ist es so, als ob der vorhandene long-Wert vor dem Festlegen der neuen Daten auf die Länge 0 (Null) 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 vom rest der 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 Byte kleiner sind, nicht getrennt sein können. In solchen Fällen wird die Option ignoriert.
JET_bitSetSizeLV	Diese Option wird verwendet, um den Eingabepuffer als ganzzahlige Anzahl von Bytes zu interpretieren, die als Länge des langen Werts festgelegt werden soll, der von der angegebenen columnid beschrieben wird, und falls angegeben, der Sequenznummer in psetinfo-itagSequence>. Wenn die angegebene Größe größer als der vorhandene Spaltenwert ist, wird die Spalte um 0s 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. Mit dieser Option werden die Quellspaltendaten ohne Transformationen mit anderen vorhandenen Spaltenwerten verglichen, 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 auch gegeben werden.
JET_bitSetUniqueNormalizedMultiValues	Diese Option wird verwendet, um zu erzwingen, dass alle Werte in einer mehrwertigen Spalte unterschiedlich sind. Diese Option vergleicht die schlüsselnormalisierte 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 auch gegeben werden.
JET_bitSetZeroLength	Diese Option wird verwendet, um einen Wert auf die Länge null festzulegen. Normalerweise wird ein Spaltenwert auf NULL festgelegt, indem eine cbMax von 0 (null) übergeben wird. Für einige Typen, z . B. JET_coltypText, kann ein Spaltenwert jedoch 0 (null) anstelle von NULL 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 NULL festgelegt. Wenn die Spalte jedoch eine Spalte mit Tags fester Länge ist, wird die Spaltenlänge auf 0 festgelegt. Wenn die Spalte mit Tags fester Länge auf 0 länge 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 die Datenkomprimierung zu versuchen. Windows 7: JET_bitSetCompressed wird in Windows 7 eingeführt.
JET_bitSetUncompressed	Diese Option wird beim Speichern der Daten nicht versucht, zu komprimieren. 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 wurden. Dies führt dazu, dass der Spaltensatz den ersten Wert einer mehrwertigen Spalte und lange Daten ab Offset 0 (Null) festgelegt.

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

Wert	Bedeutung
ibLongValue	Binärer Offset in einen langen Spaltenwert, an dem die Setdaten 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 der mehrwertigen Werte angefügt werden. Wenn die angegebene Sequenznummer größer als der letzte vorhandene mehrwertige Wert ist, wird der angegebene Wert erneut am Ende der Wertesequenz angefügt. Wenn die Sequenznummer einem vorhandenen Wert entspricht, wird dieser Wert durch den angegebenen Wert ersetzt.

Wert

Bedeutung

ibLongValue

Binärer Offset in einen langen Spaltenwert, an dem die Setdaten 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 der mehrwertigen Werte angefügt werden. Wenn die angegebene Sequenznummer größer als der letzte vorhandene mehrwertige Wert ist, wird der angegebene Wert erneut am Ende der Wertesequenz angefügt. Wenn die Sequenznummer einem vorhandenen Wert entspricht, wird dieser Wert durch den angegebenen Wert ersetzt.

Rückgabewert

Diese Funktion gibt den Datentyp JET_ERR mit einem der folgenden Rückgabecodes zurück. Weitere Informationen zu möglichen ESE-Fehlern finden Sie unter Erweiterbare Speichermodulfehler und Fehlerbehandlungsparameter.

Rückgabecode	Beschreibung
JET_errSuccess	Der Vorgang wurde erfolgreich abgeschlossen.
JET_errBadColumnId	Die angegebene Spalten-ID liegt außerhalb der gesetzlichen Grenzen einer Spalten-ID.
JET_errClientRequestToStopJetService	Es ist nicht möglich, den Vorgang abzuschließen, da alle Aktivitäten auf der instance, die der Sitzung zugeordnet sind, aufgrund eines Aufrufs von JetStopService beendet wurden.
JET_errColumnNotFound	Die von der angegebenen Columnid beschriebene Spalte ist in der Tabelle nicht vorhanden.
JET_errColumnNotUpdatable	Es wurde ein illegaler Versuch unternommen, einen langen Wert während eines Kopierlöschvorgangs zu aktualisieren.
JET_errColumnTooBig	Die angegebenen Spaltenwertdaten, die im Eingabepuffer angegeben werden, überschreiten die Größenbeschränkung entweder natürlich für eine Spalte mit fester Länge oder konfiguriert für Text mit fester Länge oder binäre Spalten. Dieser Fehler wird auch zurückgegeben, wenn mehr als 1024 Bytes Daten für eine lange Spalte übergeben und das JET_bitSetIntrinsicLV-Flag festgelegt wird.
JET_errInstanceUnavailable	Es ist nicht möglich, den Vorgang abzuschließen, da beim instance, der 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 höheren Versionen zurückgegeben.
JET_errInvalidBufferSize	Die angegebene Spaltenwert-Datengröße stimmt nicht mit der natürlichen Größe des Datentyps mit fester Länge überein.
JET_errInvalidColumnType	Es wurde ein illegaler Versuch unternommen, eine Automatische Inkrementspalte entweder während eines Einfüge- oder Updatevorgangs zu aktualisieren oder eine Versionsspalte während eines Ersetzungsvorgangs zu aktualisieren.
JET_errInvalidgrbit	Die angegebenen 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 der Setspalte hat versucht, einen doppelten Wert zu erstellen, und hat entweder JET_bitSetUniqueMultiValues oder JET_bitSetUniqueNormalizedMultiValues angegeben.
JET_errNotInitialized	Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete instance noch nicht initialisiert wurde.
JET_errNotInTransaction	Es wurde ein illegaler Versuch unternommen, einen langen Spaltenwert zu aktualisieren, wenn sich die aufrufende Sitzung nicht in einer Transaktion befand.
JET_errNullInvalid	Es wurde ein illegaler Versuch unternommen, eine Spalte ohne NULL auf NULL festzulegen.
JET_errColumnIllegalNull	Identisch mit 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 für die Seitengröße überschritten hätte. Spalten vom Typ JET_coltypLongText oder JET_coltypLongBinary können getrennt von den übrigen Datensatzdaten gespeichert werden. Allerdings müssen andere Spalten mit dem Datensatz gespeichert werden und können dazu führen, dass die Datensatzgrößenbeschränkung überschritten wird. Selbst lange Spalten benötigen 5 Bytes Speicherplatz innerhalb des Datensatzes als Verknüpfung, und auch dies kann dazu führen, dass JET_errRecordTooBig zurückgegeben werden.
JET_errRestoreInProgress	Es ist nicht möglich, den Vorgang abzuschließen, da auf dem der Sitzung zugeordneten instance ein Wiederherstellungsvorgang ausgeführt wird.
JET_errSessionSharingViolation	Dieselbe Sitzung kann nicht für mehrere Threads gleichzeitig verwendet werden. Windows XP: Dieser Fehler wird nur von Windows XP und höheren Versionen zurückgegeben.
JET_errTermInProgress	Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete instance heruntergefahren wird.
JET_errUpdateNotPrepared	Der Cursor ist derzeit weder dabei, einen neuen Datensatz einzufügen noch einen vorhandenen Datensatz zu aktualisieren.
JET_errVersionStoreOutOfMemory	Dieser Fehler tritt auf, wenn die konfigurierte Größe des Versionsspeichers nicht ausreicht, um alle ausstehenden Updates aufzunehmen.
JET_wrnColumnMaxTruncated	Der Spaltenwert im Eingabepuffer überschreitet die maximale konfigurierte Länge für eine Spalte mit variabler Länge 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 wurden. Das Dataset wurde möglicherweise abgeschnitten, wenn es die maximale Länge überschritten hat, die für eine Spalte mit variabler Länge angegeben wurde.

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

Bemerkungen

Das Festlegen von langen Werten und Werten für Spalten JET_coltypLongBinary vom Typ JET_coltypLongText oder JET_coltypLongBinary sollte nur erfolgen, wenn sich die aufrufende Sitzung in einer Transaktion befindet. Wenn sich die aufrufende Sitzung nicht in einer Transaktion befindet, können Änderungen an langen Werten, die separat gespeichert werden, auch dann vollständig committet werden, wenn der Aktualisierungsvorgang 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 die Sitzungstransaktion zurückgesetzt wird.

Indexupdates 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 ändern.

Die Größe eines Datensatzes ist basierend auf der Seitengröße der Datenbank begrenzt. Alle langen Werte im Datensatz, die größer als fünf Bytes sind, werden getrennt vom Datensatz gespeichert, wenn die Daten im Datensatz aufgrund eines JetSetColumn-Vorgangs den Grenzwert überschreiten. Der Fehler JET_errRecordTooBig wird erst zurückgegeben, nachdem alle trennbaren Datensatzspaltendaten getrennt vom Datensatz gespeichert wurden und der Datensatz weiterhin das Grenzwert für die Datensatzgröße überschreitet.

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.
Kopfzeile	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

Freigeben über

JetSetColumn-Funktion