JetRetrieveColumn-Funktion

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. Neben dem 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 Größe der Anwendungspuffer entsprechend angepasst werden kann.

    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 abzurufende Spalte.

Ein columnid-Wert von 0 (null) kann angegeben werden, der selbst nicht auf eine einzelne Spalte verweist. 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

Der Ausgabepuffer, der den Spaltenwert empfängt.

cbData

Die maximale Größe des Ausgabepuffers in Bytes.

actual

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 für diesen Aufruf zu verwendenden Optionen enthalten, die null oder mehr der folgenden Elemente enthalten:

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 Nach Möglichkeit Spaltenwerte aus dem Index abzurufen, 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 nicht rückgängig machenden Transformationen oder Datenkürzungen nicht aus dem Index abgerufen werden kann, wird auf den Datensatz zugegriffen, und die Daten werden normal abgerufen. Dies ist eine Leistungsoption und sollte nur angegeben werden, wenn es wahrscheinlich ist, dass der Spaltenwert 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 zum Abrufen von Spaltenwerten aus dem Indexlesezeichen verwendet und 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 auch JET_bitRetrieveFromIndex festgelegt ist.

JET_bitRetrieveTag

Diese Option wird verwendet, um die Sequenznummer eines mehrwertigen Spaltenwerts in pretinfo- > itagSequence abzurufen. Das ItagSequence-Feld ist häufig 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 ausgeführt werden.

JET_bitRetrieveNull

Diese Option wird verwendet, um mehrwertige SPALTEN-NULL-Werte abzurufen. Wenn diese Option nicht angegeben ist, werden null-Werte für mehrwertige Spalten automatisch übersprungen.

JET_bitRetrieveIgnoreDefault

Diese Option betrifft nur mehrwertige Spalten 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 das Abrufen 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 worden wären. Dies bewirkt, dass der Spaltenabruf den ersten Wert einer mehrwertigen Spalte abruft und lange Daten bei Offset 0 (null) abruft.

Dieser Parameter wird verwendet, um eine oder mehrere der folgenden Angaben bereitzustellen:

Wert

Bedeutung

ibLongValue

Gibt beim Abrufen eines Teils eines Spaltenwerts einen binären Offset in einen long-Spaltenwert an.

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, indem columnid von 0 (null) übergeben wird.

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 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_errBadItagSequence

Ein ungültiger mehrwertiger Spaltensequenznummerwert wurde in pretinfo- > itagSequence übergeben. Gültige Werte für die Sequenznummern für mehrwertige Spaltenwerte 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 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_errIndexTuplesCannotRetrieveFromIndex

Spalten, die als Teilzeichenfolgen indiziert sind, können nicht aus dem Index abgerufen werden, da in der Regel nur ein kleiner Teil der Spalte in jedem Indexeintrag vorhanden ist.

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. 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 Spalten für die Aktualisierung so angepasst, dass sie für den Transaktionskontext der aufrufenden Sitzung konsistent sind. Für diese Anpassung ist der vom Aufrufer bereitgestellte Puffer erforderlich. 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 vorkommen, wenn retinfo.cbStruct kleiner als die Größe von JET_RETINFOist.

JET_errInvalidgrbit

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

JET_errNoCurrentRecord

Der Cursor wird nicht in 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 Instanz noch nicht initialisiert wurde.

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_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. Weniger als der gesamte Spaltenwert wird mit der Warnung kopiert, JET_wrnBufferTruncated zurückgegeben wird. Wenn das "actual" 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 mit fester oder bekannter Größe für nicht mehrwertige Spalten abzurufen. Wenn Spaltendaten jedoch eine unbekannte Größe aufweisen, wird dieser Aufruf in der Regel zweimal verwendet. Sie wird zuerst aufgerufen, um die Größe der Daten zu bestimmen, damit sie den erforderlichen Speicherplatz zuordnen können. Anschließend wird derselbe Aufruf erneut durchgeführt, um die Spaltendaten abzurufen. Wenn die tatsächliche Anzahl von Werten unbekannt ist, da eine Spalte mehrwertige Werte enthält, wird der Aufruf in der Regel dreimal verwendet. Zuerst, um die Anzahl der Werte abzurufen, und dann zweimal mehr, um Speicher zuzuordnen und die tatsächlichen Daten abzurufen.

Das Abrufen aller Werte für eine mehrwertige Spalte kann erfolgen, indem diese Funktion wiederholt mit einem pretinfo- > itagSequence-Wert aufgerufen wird, der bei 1 beginnt und bei jedem nachfolgenden Aufruf erhöht wird. Es ist bekannt, dass der letzte Spaltenwert abgerufen wird, wenn ein JET_wrnColumnNull von der Funktion zurückgegeben wird. Beachten Sie, dass diese Methode nicht ausgeführt werden kann, wenn in der Wertsequenz der Mehrwertspalte explizite NULL-Werte festgelegt sind, 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 JetRetrieveColumn verwendet werden. Beachten Sie, dass diese Funktion nicht die Anzahl der Werte für eine mehrwertige Funktion 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 auf Transaktionsebene 0 (null) aufgerufen wird, z. B. ist die aufrufende Sitzung nicht selbst in einer Transaktion, wird eine Transaktion innerhalb der Funktion geöffnet und geschlossen. Der Zweck besteht darin, konsistente Ergebnisse zurückzugeben, falls 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 und nach dem ersten Aufruf dieser Funktion aktualisierte Daten zurückgeben kann.

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 Spaltenwerts für die automatische Inkrementierung 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 Wert für die automatische Inkrementierung wird zugeordnet, wenn der Einfügevorgang beginnt, und kann jederzeit aus dem Kopierpuffer abgerufen werden, bis das Update 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 zur höchsten columnid abgerufen. Jedes Mal, wenn Spaltenwerte abgerufen werden, wird die gleiche Reihenfolge von Spaltenwerten zurückgegeben. Die Reihenfolge ist deterministisch.

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