JetRetrieveColumn-Funktion

Artikel
06/12/2023

Gilt für: Windows | Windows Server

JetRetrieveColumn-Funktion

Die JetRetrieveColumn-Funktion ruft einen einzelnen Spaltenwert aus dem aktuellen Datensatz ab. Der Datensatz ist der Datensatz, der dem Indexeintrag an der aktuellen Position des Cursors zugeordnet ist. Alternativ kann diese Funktion eine Spalte aus einem Datensatz abrufen, der im Cursorkopierpuffer erstellt wird. Diese Funktion kann auch Spaltendaten aus einem Indexeintrag abrufen, der auf den aktuellen Datensatz verweist. Zusätzlich zum Abrufen des tatsächlichen Spaltenwerts kann JetRetrieveColumn auch verwendet werden, um die Größe einer Spalte abzurufen, bevor die Spaltendaten selbst abgerufen werden, damit die Anwendungspuffer entsprechend dimensioniert werden können.

    JET_ERR JET_API JetRetrieveColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __out_opt     void* pvData,
      __in          unsigned long cbData,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit,
      __in_out_opt  JET_RETINFO* pretinfo
    );

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.

Es kann ein columnid-Wert von 0 (null) angegeben werden, der sich selbst nicht auf eine einzelne Spalte bezieht. Wenn columnid 0 (null) angegeben wird, werden alle markierten Spalten, Sparsespalten und mehrwertigen Spalten als eine einzelne Spalte behandelt. Dies erleichtert das Abrufen aller Sparsespalten, die in einem Datensatz vorhanden sind.

pvData

Der Ausgabepuffer, der den Spaltenwert empfängt.

cbData

Die maximale Größe des Ausgabepuffers in Bytes.

pcbActual

Empfängt die tatsächliche Größe des Spaltenwerts in Bytes.

Wenn dieser Parameter NULL ist, wird die tatsächliche Größe des Spaltenwerts nicht zurückgegeben.

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_bitRetrieveCopy	Dieses Flag bewirkt, dass die Abrufspalte den geänderten Wert anstelle des ursprünglichen Werts abruft. Wenn der Wert nicht geändert wurde, wird der ursprüngliche Wert abgerufen. Auf diese Weise kann ein Wert, der noch nicht eingefügt oder aktualisiert wurde, während des Vorgangs zum Einfügen oder Aktualisieren eines Datensatzes abgerufen werden.
JET_bitRetrieveFromIndex	Diese Option wird verwendet, um Spaltenwerte aus dem Index abzurufen, wenn möglich, ohne auf den Datensatz zuzugreifen. Auf diese Weise kann unnötiges Laden von Datensätzen vermieden werden, wenn benötigte Daten aus Indexeinträgen selbst verfügbar sind. In Fällen, in denen der ursprüngliche Spaltenwert aufgrund von irreversiblen Transformationen oder Datenkürzungen nicht aus dem Index abgerufen werden kann, wird auf den Datensatz zugegriffen und die Daten wie gewohnt abgerufen. Dies ist eine Leistungsoption, die nur angegeben werden sollte, wenn der Spaltenwert wahrscheinlich aus dem Index abgerufen werden kann. Diese Option sollte nicht angegeben werden, wenn der aktuelle Index der gruppierte Index ist, da die Indexeinträge für den gruppierten oder primären Index die Datensätze selbst sind. Dieses Bit kann nicht festgelegt werden, wenn auch JET_bitRetrieveFromPrimaryBookmark festgelegt ist.
JET_bitRetrieveFromPrimaryBookmark	Diese Option wird verwendet, um Spaltenwerte aus dem Indexlesezeichen abzurufen. Sie kann sich vom Indexwert unterscheiden, wenn eine Spalte sowohl im primären Index als auch im aktuellen Index angezeigt wird. Diese Option sollte nicht angegeben werden, wenn der aktuelle Index der gruppierte oder primäre Index ist. Dieses Bit kann nicht festgelegt werden, wenn JET_bitRetrieveFromIndex ebenfalls festgelegt ist.
JET_bitRetrieveTag	Diese Option wird verwendet, um die Sequenznummer eines mehrwertigen Spaltenwerts in pretinfo-itagSequence> abzurufen. Das Feld itagSequence ist in der Regel eine Eingabe zum Abrufen von mehrwertigen Spaltenwerten aus einem Datensatz. Beim Abrufen von Werten aus einem Index ist es jedoch auch möglich, den Indexeintrag einer bestimmten Sequenznummer zuzuordnen und auch diese Sequenznummer abzurufen. Das Abrufen der Sequenznummer kann ein kostspieliger Vorgang sein und sollte nur bei Bedarf durchgeführt werden.
JET_bitRetrieveNull	Diese Option wird verwendet, um NULL-Werte für mehrwertige Spalten abzurufen. Wenn diese Option nicht angegeben ist, werden null-Werte für mehrwertige Spalten automatisch übersprungen.
JET_bitRetrieveIgnoreDefault	Diese Option wirkt sich nur auf mehrwertige Spalten aus und bewirkt, dass ein NULL-Wert zurückgegeben wird, wenn die angeforderte Sequenznummer 1 ist und keine festgelegten Werte für die Spalte im Datensatz vorhanden sind.
JET_bitRetrieveLongId	Dieses Flag dient nur zur internen Verwendung und ist nicht für die Verwendung in Ihrer Anwendung vorgesehen.
JET_bitRetrieveLongValueRefCount	Dieses Flag dient nur zur internen Verwendung und ist nicht für die Verwendung in Ihrer Anwendung vorgesehen.
JET_bitRetrieveTuple	Dieses Flag ermöglicht den Abruf eines Tupelsegments des Indexes. Dieses Bit muss mit JET_bitRetrieveFromIndex angegeben werden.

Pretinfo

Wenn pretinfo 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 Spaltenabruf den ersten Wert einer mehrwertigen Spalte und lange Daten mit Offset 0 (Null) abruft.

Dieser Parameter wird verwendet, um einen oder mehrere der folgenden Punkte bereitzustellen:

Wert	Bedeutung
ibLongValue	Gibt einen binären Offset in einen langen Spaltenwert, wenn ein Teil eines Spaltenwerts abgerufen wird.
itagSequence	Gibt die Sequenznummer des gewünschten mehrwertigen Spaltenwerts an. Beachten Sie, dass dieses Feld nur festgelegt wird, wenn die JET_bitRetrieveTag angegeben ist. Andernfalls ist sie unverändert.
columnidNextTagged	Gibt die Spalten-ID des zurückgegebenen Spaltenwerts zurück, wenn alle markierten, sparse und mehrwertigen Spalten abgerufen werden, wobei columnid 0 (null) übergeben wird.

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_errBadItagSequence	In pretinfo-itagSequence> wurde ein ungültiger Wert für eine mehrwertige Spaltensequenznummer übergeben. Gültige Werte für die Sequenznummern der mehrwertigen Spalte sind 1 oder höher. Der Wert 0 (null) ist für diese Funktion ungültig.
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_errIndexTuplesCannotRetrieveFromIndex	Spalten, die als Teilzeichenfolgen indiziert sind, können nicht aus dem Index abgerufen werden, da in jedem Indexeintrag normalerweise nur ein kleiner Teil der Spalte vorhanden ist.
JET_errInstanceUnavailable	Es ist nicht möglich, den Vorgang abzuschließen, da für die instance, 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. Dieser Fehler wird nur von Windows XP und späteren Versionen zurückgegeben.
JET_errInvalidBufferSize	In einigen Fällen muss der für die Abrufspalte angegebene Puffer ausreichend groß sein, um eine beliebige Menge des Spaltenwerts zurückzugeben. Beispielsweise werden aktualisierbare Escrow-Spalten so angepasst, dass sie für den Transaktionskontext der aufrufenden Sitzung konsistent sind, und diese Anpassung erfordert den vom Aufrufer bereitgestellten Puffer. Wenn nicht genügend Pufferspeicher bereitgestellt wird, wird JET_errInvalidBufferSize zurückgegeben, und es werden keine Spaltendaten zurückgegeben.
JET_errInvalidParameter	Mindestens einer der angegebenen Parameter ist falsch. Dies kann passieren, wenn die retinfo.cbStruct kleiner ist als die Größe von JET_RETINFO.
JET_errInvalidgrbit	Die angegebenen Optionen sind unbekannt oder eine unzulässige Kombination bekannter Biteinstellungen.
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_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_wrnBufferTruncated	Der gesamte Spaltenwert konnte nicht abgerufen werden, da der angegebene Puffer kleiner als die Größe der Spalte ist.
JET_wrnColumnNull	Der abgerufene Spaltenwert ist NULL.

Bei Erfolg wird der Spaltenwert für die angegebene Spalte in den angegebenen Puffer kopiert. Kleiner als der gesamte Spaltenwert wird mit der Warnung kopiert JET_wrnBufferTruncated zurückgegeben wird. Wenn der pcbActual angegeben wurde, wird die tatsächliche Größe des Spaltenwerts zurückgegeben. Beachten Sie, dass NULL-Werte die Länge 0 (null) haben und daher die zurückgegebene Größe auf 0 (null) festlegen. Wenn die abgerufene Spalte eine mehrwertige Spalte war und pretinfo angegeben wurde und JET_bitReturnTag als Option festgelegt wurde, wird die Sequenznummer des Spaltenwerts in pretinfo-itagSequence> zurückgegeben.

Bei einem Fehler bleibt die Cursorposition unverändert, und es werden keine Daten in den bereitgestellten Puffer kopiert.

Bemerkungen

Dieser Aufruf wird nur einmal verwendet, um Daten von fester oder bekannter Größe für Spalten mit nicht mehreren Werten abzurufen. Wenn Spaltendaten jedoch eine unbekannte Größe aufweisen, wird dieser Aufruf in der Regel zweimal verwendet. Es wird zuerst aufgerufen, um die Größe der Daten zu bestimmen, damit sie den erforderlichen Speicherplatz zuordnen kann. Anschließend wird derselbe Aufruf erneut ausgeführt, um die Spaltendaten abzurufen. Wenn die tatsächliche Anzahl von Werten unbekannt ist, da eine Spalte mehrwertige Werte aufweist, wird der Aufruf in der Regel dreimal verwendet. Zuerst, um die Anzahl der Werte abzurufen, und dann zweimal mehr, um Speicher zuzuweisen und die tatsächlichen Daten abzurufen.

Das Abrufen aller Werte für eine mehrwertige Spalte kann durch wiederholtes Aufrufen dieser Funktion mit einem pretinfo-itagSequence-Wert> ab 1 erfolgen und bei jedem nachfolgenden Aufruf erhöht werden. Der letzte Spaltenwert wird bekannt, wenn ein JET_wrnColumnNull von der Funktion zurückgegeben wird. Beachten Sie, dass diese Methode nicht durchgeführt werden kann, wenn die mehrwertige Spalte explizite NULL-Werte in ihrer Wertsequenz festgelegt hat, da diese Werte übersprungen würden. Wenn eine Anwendung alle mehrwertigen Spaltenwerte abrufen möchte, einschließlich der werte, die explizit auf NULL festgelegt sind, muss JetRetrieveColumns anstelle von JetRetrieveColumns verwendet werden. Beachten Sie, dass diese Funktion die Anzahl der Werte für eine mehrwertige Funktion nicht zurückgibt, wenn ein itagSequence-Wert von 0 (null) angegeben wird. Nur JetRetrieveColumns gibt die Anzahl der Werte eines Spaltenwerts zurück, wenn ein itagSequence-Wert von 0 (null) übergeben wird.

Wenn diese Funktion beispielsweise auf Transaktionsebene 0 (null) aufgerufen wird, ist die aufrufende Sitzung nicht selbst in einer Transaktion, dann wird eine Transaktion innerhalb der Funktion geöffnet und geschlossen. Der Zweck besteht darin, konsistente Ergebnisse für den Fall zurückzugeben, dass sich ein langer Wert über Datenbankseiten erstreckt. Beachten Sie, dass die Transaktion zwischen Funktionsaufrufen und einer Reihe von Aufrufen dieser Funktion freigegeben wird, wenn sich die Sitzung nicht in einer Transaktion befindet, möglicherweise Daten zurückgibt, die nach dem ersten Aufruf dieser Funktion aktualisiert wurden.

Der Standardspaltenwert wird abgerufen, wenn die Spalte nicht explizit auf einen anderen Wert festgelegt wurde, es sei denn, die Option JET_bitRetrieveIgnoreDefault ist festgelegt.

Das Abrufen des Autoinkrementspaltenwerts aus dem Kopierpuffer vor dem Einfügen ist ein gängiges Mittel, um einen Datensatz eindeutig für die Verknüpfung zu identifizieren, wenn normalisierte Daten in mehrere Tabellen eingefügt werden. Der Autoinkrementwert wird zugewiesen, wenn der Einfügevorgang beginnt und kann jederzeit aus dem Kopierpuffer abgerufen werden, bis die Aktualisierung abgeschlossen ist.

Beim Abrufen aller markierten, mehrwertigen Und Sparsespalten durch Festlegen von columnid auf 0 (null) werden Spalten in columnid-Reihenfolge von der niedrigsten Columnid bis zur höchsten Columnid abgerufen. Jedes Mal, wenn Spaltenwerte abgerufen werden, wird die gleiche Reihenfolge der Spaltenwerte zurückgegeben. Die Reihenfolge ist deterministisch.

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_RETINFO
JetSetColumn
JetRetrieveColumns

JetRetrieveColumn-Funktion