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