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