JetEnumerateColumns-Funktion
Gilt für: Windows | Windows Server
JetEnumerateColumns-Funktion
Die JetEnumerateColumns-Funktion ruft effizient einen Satz von Spalten und deren Werte aus dem aktuellen Datensatz eines Cursors oder dem Kopierpuffer dieses Cursors ab. Die abgerufenen Spalten und Werte können durch eine Liste von Spalten-IDs, itagSequence-Nummern und anderen Merkmalen eingeschränkt werden. Diese Spaltenabruf-API ist insofern einzigartig, als sie Informationen im dynamisch zugeordneten Arbeitsspeicher zurückgibt, die mithilfe eines vom Benutzer bereitgestellten, mit realloc kompatiblen Rückrufs abgerufen werden. Diese neue Flexibilität ermöglicht das effiziente Abrufen von Spaltendaten mit spezifischen Merkmalen (z. B. Größe und Multiplizität), die dem Aufrufer unbekannt sind. Dadurch entfällt die Notwendigkeit, die Ermittlungsmodi von JetRetrieveColumn zu verwenden, um diese Merkmale zu bestimmen, um einen endgültigen Aufruf von JetRetrieveColumn einzurichten, der die gewünschten Daten erfolgreich abruft.
Windows XP: JetEnumerateColumns wird in Windows XP eingeführt.
JET_ERR JET_API JetEnumerateColumns(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in unsigned long cEnumColumnId,
__in_opt JET_ENUMCOLUMNID* rgEnumColumnId,
__out unsigned long* pcEnumColumn,
__out JET_ENUMCOLUMN** prgEnumColumn,
__in JET_PFNREALLOC pfnRealloc,
__in void* pvReallocContext,
__in unsigned long cbDataMost,
__in JET_GRBIT grbit
);
Parameter
sesid
Die Sitzung, die für diesen Aufruf verwendet werden soll.
tableid
Der Cursor, der für diesen Aufruf verwendet werden soll.
cEnumColumnId
Ein Array von Spalten-IDs, die jeweils ein optionales Array von itagSequence-Zahlen aufweisen, die aufgelistet werden sollen.
Wenn cEnumColumnId 0 (null) ist, wird rgEnumColumnId ignoriert, und alle Spaltenwerte werden aufgelistet und an den Aufrufer zurückgegeben. Wenn ein Element des Spalten-ID-Arrays auf eine Spalten-ID von 0 (null) verweist, wird die Enumeration dieser Spalte übersprungen, und ein entsprechender Slot in der Ausgabe wird mit einer Spalte status von JET_wrnColumnSkipped generiert.
Wenn ctagSequence für ein bestimmtes Element des Spalten-ID-Arrays 0 (Null) ist, wird rgtagSequence ignoriert, und alle Spaltenwerte für diese Spalten-ID werden aufgelistet und an den Aufrufer zurückgegeben. Wenn ein Element eines itagSequence-Zahlenarrays auf eine itagSequence-Zahl von 0 (null) verweist, wird die Enumeration dieser itagSequence-Nummer übersprungen, und ein entsprechender Slot in der Ausgabe wird mit einem Spaltenwert status von JET_wrnColumnSkipped generiert.
rgEnumColumnId
Siehe cEnumColumnId.
pcEnumColumn
Gibt das aufgezählte Array von Spalten und deren Werte im Arbeitsspeicher zurück, die über den bereitgestellten itagSequence-kompatiblen Rückruf zugewiesen wurden.
Wenn bei der Eingabe ein Array von Spalten-IDs angefordert wird, spiegeln die Reihenfolge und Größe des Ausgabearrays die Reihenfolge und Größe des Eingabearrays wider. Wenn ein Array von itagSequence-Zahlen für eine bestimmte Spalten-ID bei der Eingabe angefordert wird, spiegeln die Reihenfolge und Größe des Ausgabearrays der Spaltenwerte für diese Spalte die Reihenfolge und Größe des Eingabearrays wider.
Die Ausgabeparameter sind auf 0 (null) und NULL für jeden Fehler festgelegt, mit Ausnahme von JET_errBadColumnId und JET_errColumnNotFound. Wenn diese Fehler zurückgegeben werden, sind die Ausgabedaten gültig und vollständig für alle spalten-IDs außer den betroffenen Spalten-IDs. Der status Code für jede der betroffenen Spalten-IDs ist auf einen dieser Fehler festgelegt, sodass der Aufrufer ermitteln kann, welche Spalten-IDs schlecht waren und möglicherweise Korrekturmaßnahmen ergreifen kann.
prgEnumColumn
Siehe pcEnumColumn.
pfnRealloc
Identifiziert einen reloc-kompatiblen Rückruf und einen optionalen Kontextzeiger, der zum Zuweisen von Arbeitsspeicher für das Ausgabearray der Spalten und deren Werte verwendet wird.
pvReallocContext
Siehe pfnRealloc.
cbDataMost
Legt eine Obergrenze für die Datenmenge fest, die aus einem langen Text oder einer langen binären Spalte zurückgegeben werden soll.
Dieser Parameter kann verwendet werden, um die Enumeration eines extrem großen Spaltenwerts zu verhindern. Normalerweise schlägt eine solche Enumeration beim API-Aufruf mit JET_errOutOfMemory fehl. Wenn ein großer Spaltenwert auf diese Weise abgeschnitten wird, wird der status des Spaltenwerts JET_wrnColumnTruncated.
grbit
Eine Gruppe von Bits, die null oder mehr der folgenden Optionen angibt.
Wert |
Bedeutung |
|---|---|
JET_bitEnumerateCompressOutput |
Beim Aufzählen von Spaltenwerten können alle Spalten, für die wir alle Werte abrufen und die nur einen Spaltenwert ungleich NULL aufweisen, in einem komprimierten Format zurückgegeben werden. Die status für diese Spalten wird auf JET_wrnColumnSingleValue festgelegt, und die Größe des Spaltenwerts und des Arbeitsspeichers, der den Spaltenwert enthält, wird direkt in der JET_ENUMCOLUMN-Struktur zurückgegeben. Es ist nicht garantiert, dass alle berechtigten Spalten auf diese Weise komprimiert werden. Weitere Informationen finden Sie unter JET_ENUMCOLUMN . |
JET_bitEnumerateCopy |
Diese Option gibt an, dass die geänderten Spaltenwerte des Datensatzes anstelle der ursprünglichen Spaltenwerte aufgelistet werden sollen. Wenn ein Spaltenwert nicht geändert wurde, wird der ursprüngliche Spaltenwert aufgelistet. Auf diese Weise kann ein Spaltenwert, der noch nicht eingefügt oder aktualisiert wurde, beim Einfügen oder Aktualisieren eines Datensatzes aufgelistet werden. Diese Option ist identisch mit JET_bitRetrieveCopy, wenn sie mit JetRetrieveColumn oder JetRetrieveColumns verwendet wird. |
JET_bitEnumerateIgnoreDefault |
Wenn eine bestimmte Spalte nicht im Datensatz vorhanden ist, wird kein Spaltenwert zurückgegeben. Normalerweise wird in diesem Fall der Standardwert für die Spalte zurückgegeben, sofern vorhanden. Es ist garantiert, dass, wenn die Spalte auf einen anderen Wert als den Standardwert festgelegt ist, dieser andere Wert zurückgegeben wird (das heißt, wenn eine Spalte mit einem Standardwert explizit auf NULL festgelegt ist, wird ein NULL-Wert als Wert für diese Spalte zurückgegeben). Beachten Sie, dass selbst wenn diese Option angefordert wird, es immer noch möglich ist, einen Spaltenwert anzuzeigen, der dem Standardwert entspricht. Es werden keine Anstrengungen unternommen, Spaltenwerte zu entfernen, die ihren Standardwerten entsprechen. Es ist wichtig zu beachten, dass sich diese Option auf die Ausgabe von JetEnumerateColumns auswirkt, wenn sie mit JET_bitEnumeratePresenceOnly oder JET_bitEnumerateTaggedOnly verwendet wird. |
JET_bitEnumerateIgnoreUserDefinedDefault |
Wenn eine bestimmte Spalte nicht im Datensatz vorhanden ist und über einen benutzerdefinierten Standardwert verfügt, wird kein Spaltenwert zurückgegeben. Diese Option verhindert, dass der Rückruf, der den benutzerdefinierten Standardwert für die Spalte berechnet, aufgerufen wird, wenn die Werte für diese Spalte aufgezählt werden. Windows Server 2003 und früher: Bei Windows Server 2003 und früheren Versionen schlägt der Vorgang mit JET_errCallbackFailed fehl. Windows Server 2003 SP1: Dieser mögliche Wert ist nur für Windows Server 2003 SP1 und höhere Betriebssysteme verfügbar. Wenn dieser mögliche Wert angegeben ist und die Tabelle eine Spalte mit einem benutzerdefinierten Standardwert enthält, schlägt der Vorgang mit JET_errCallbackFailed fehl. |
JET_bitEnumeratePresenceOnly |
Wenn für die angeforderte Spalte oder den angeforderten Spaltenwert ein Nicht-NULL-Wert vorhanden ist, werden die zugeordneten Daten nicht zurückgegeben. Stattdessen wird der zugeordnete status für diesen Spaltenwert auf JET_wrnColumnPresent festgelegt. Wenn der Spaltenwert NULL ist, wird JET_wrnColumnNull wie gewohnt zurückgegeben. |
JET_bitEnumerateTaggedOnly |
Beim Auflisten aller Spaltenwerte im Datensatz (z. B. wenn cEnumColumnId null ist) werden nur markierte Spaltenwerte zurückgegeben. Diese Option ist beim Auflisten eines bestimmten Arrays von Spalten-IDs nicht zulässig. |
JET_bitEnumerateInRecordOnly |
Windows 7: JET_bitEnumerateInRecordOnly wird in Windows 7 eingeführt. |
Rückgabewert
Diese Funktion gibt den JET_ERR-Datentyp 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 Grenzwerte einer Spalten-ID. Dieser Fehler wird von JetEnumerateColumns zurückgegeben, wenn bestimmte Spalten-IDs angefordert wurden, eine dieser Spalten-IDs ungültig war und die erste ungültige Spalten-ID mit diesem Fehler für die Spalte status Code fehlgeschlagen ist. |
JET_errClientRequestToStopJetService |
Es ist nicht möglich, den Vorgang abzuschließen, da alle Aktivitäten auf dem instance, die der Sitzung zugeordnet sind, aufgrund eines Aufrufs von JetStopService beendet wurden. |
JET_errColumnNotFound |
Die durch die angegebene Spalten-ID beschriebene Spalte ist in der Tabelle nicht vorhanden. Dieser Fehler wird von JetEnumerateColumns zurückgegeben, wenn bestimmte Spalten-IDs angefordert wurden, eine dieser Spalten-IDs ungültig war und die erste ungültige Spalten-ID mit diesem Fehler für die Spalte status Code fehlgeschlagen ist. |
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_errInvalidgrbit |
Eine der angeforderten Optionen war ungültig oder nicht implementiert. Dieser Fehler wird von JetEnumerateColumns zurückgegeben, wenn:
|
JET_errInvalidParameter |
Einer der bereitgestellten Parameter enthielt einen unerwarteten Wert oder einen Wert, der in Kombination mit dem Wert eines anderen Parameters nicht sinnvoll war. Dieser Fehler wird von JetEnumerateColumns zurückgegeben, wenn:
|
JET_errNoCurrentRecord |
Der Cursor wird nicht auf einem Datensatz positioniert. Dafür sind viele verschiedene Gründe möglich. Dies geschieht beispielsweise, wenn der Cursor derzeit nach dem letzten Datensatz im aktuellen Index positioniert ist. |
JET_errNotInitialized |
Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete instance noch nicht initialisiert wurde. |
JET_errRecordDeleted |
Der Cursor wird auf einem gelöschten Datensatz positioniert. Dafür sind viele verschiedene Gründe möglich. Der häufigste Grund ist, dass sich die Sitzung nicht in einer Transaktion befindet, der Cursor auf einem Datensatz positioniert wurde, dass dieser Datensatz gelöscht wurde und der Cursor dann versucht hat, auf diesen Datensatz zu verweisen. |
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. |
Bei Erfolg werden die angeforderten Daten in den Ausgabepuffern zurückgegeben. Es liegt in der Verantwortung des Aufrufers, den speicher freizugeben, der durch diesen Rückruf zugewiesen und in den Ausgabepuffern zurückgegeben wird. Dieser Arbeitsspeicher sollte über den bereitgestellten reloc-kompatiblen Rückruf freigegeben werden. Es wird keine Änderung des Datenbankstatus vorgenommen.
Bei einem Fehler wird keine der angeforderten Daten zurückgegeben. Der während des Anrufs zugewiesene Arbeitsspeicher wird mithilfe des bereitgestellten reloc-kompatiblen Rückrufs automatisch freigegeben. Es wird keine Änderung des Datenbankstatus vorgenommen.
Bemerkungen
Wenn Sie alle Spaltenwerte im Datensatz aufzählen und nicht JET_bitEnumerateIgnoreDefaults angegeben haben, können Sie nicht davon ausgehen, dass nie ein Spalten- oder Spaltenwert mit einem status Code von JET_wrnColumnNull angezeigt wird. Dieser status Code wird angezeigt, wenn eine Spalte über einen Standardwert verfügt und explizit auf NULL festgelegt wurde oder wenn es sich bei der Spalte um eine Spalte ohne Sparse handelt (z. B. eine feste oder variable Spalte).
Der cbDataMost-Parameter gilt nicht für alle Spaltenwerte. Mit diesem Parameter werden nur werte für langen Text und lange binäre Spalten abgeschnitten, die so groß sind, dass sie getrennt vom Datensatz gespeichert wurden.
Wenn JetEnumerateColumns Daten in seinen Ausgabeparametern zurückgibt, ist der Aufrufer für die Freigabe des Arbeitsspeichers im Array sowie für den Speicher verantwortlich, auf den durch in dieses Array eingebettete Zeiger verwiesen wird.
Anforderungen
| Anforderung | Wert |
|---|---|
Client |
Erfordert Windows Vista oder Windows XP. |
Server |
Erfordert Windows Server 2008 oder Windows Server 2003. |
Kopfzeile |
Deklariert in Esent.h. |
Bibliothek |
Verwenden Sie ESENT.lib. |
DLL |
Erfordert ESENT.dll. |
Weitere Informationen
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für