JetRetrieveKey-Funktion

Gilt für: Windows | Windows Server

JetRetrieveKey-Funktion

Die JetRetrikey-Funktion ruft den Schlüssel für den Indexeintrag an der aktuellen Position eines Cursors ab. Solche Schlüssel werden durch Aufrufe von JetMakeKey erstellt. Der abgerufene Schlüssel kann dann verwendet werden, um diesen Cursor durch einen Aufruf von JetSeek effizient an denselben Indexeintrag zurück zu geben.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __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.

pvData

Der Ausgabepuffer, der den Schlüssel erhält.

cbMax

Die maximale Größe des Ausgabepuffers in Bytes.

–actual

Empfängt die tatsächliche Größe des Schlüssels in Bytes.

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

Wenn der Ausgabepuffer zu klein ist, wird weiterhin die tatsächliche Größe des Schlüssels zurückgegeben. Das bedeutet, dass diese Zahl größer als die Größe des Ausgabepuffers ist.

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

Wenn angegeben, gibt die Engine den Suchschlüssel für den Cursor zurück. Der Suchschlüssel wird mit mindestens einem vorherigen Aufruf von JetMakeKey erstellt, um mit JetSeek nach diesem Schlüssel zu suchen oder einen Indexbereich mit JetSetIndexRange zu festlegen.

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_errClientRequestToStopJetService

Es ist nicht möglich, den Vorgang abschließen, da alle Aktivitäten auf der -Instanz, die der Sitzung zugeordnet ist, aufgrund eines Aufrufs von JetStopService beendet wurden.

JET_errInstanceUnavailable

Der Vorgang kann nicht abgeschlossen werden, da für die der Sitzung zugeordnete Instanz 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 xp Windows und späteren Versionen zurückgegeben.

JET_errKeyNotMade

Es gibt keinen aktuellen Suchschlüssel für den Cursor. Dies geschieht für JetRetrikey, wenn JET_bitRetrieveCopy angegeben ist und kein Suchschlüssel für diesen Cursor erstellt wurde, indem ein vorheriger Aufruf von JetMakeKey verwendet wird. Der Suchschlüssel wird durch einen vorherigen Aufruf einer Navigations-API auf dem Cursor gelöscht, die nicht JetMove ist.

JET_errNoCurrentRecord

Der Cursor ist 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

Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete Instanz noch nicht initialisiert wurde.

JET_errRestoreInProgress

Der Vorgang kann nicht abgeschlossen werden, da ein Wiederherstellungsvorgang für die -Instanz durchgeführt wird, die der Sitzung zugeordnet ist.

JET_errSessionSharingViolation

Dieselbe Sitzung kann nicht gleichzeitig für mehrere Threads verwendet werden. Dieser Fehler wird nur von xp Windows und späteren Versionen zurückgegeben.

JET_errTermInProgress

Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete Instanz heruntergefahren wird.

JET_wrnBufferTruncated

Der Vorgang wurde erfolgreich abgeschlossen, aber der Ausgabepuffer war zu klein, um den gesamten Schlüssel zu empfangen. Der Ausgabepuffer wurde mit einem so großen Teil des Schlüssels gefüllt, wie er passt. Bei Bedarf wurde auch die tatsächliche Größe des Schlüssels zurückgegeben.

Hinweis: Dieser Fehler wird nicht zurückgegeben, wenn JET_bitRetrieveCopy angegeben ist. Weitere Informationen finden Sie im Abschnitt "Hinweise".

Bei Erfolg wird der Schlüssel für den Indexeintrag an der aktuellen Position eines Cursors im Ausgabepuffer zurückgegeben. Wenn JET_wrnBufferTruncated zurückgegeben wird, enthält der Ausgabepuffer so viel des Schlüssels, wie in den bereitgestellten Speicherplatz passt, und die tatsächliche Größe des Schlüssels ist genau. Es erfolgt keine Änderung des Datenbankstatus.

Bei einem Fehler sind der Zustand des Ausgabepuffers und die tatsächliche Größe des Schlüssels nicht definiert. Es erfolgt keine Änderung des Datenbankstatus.

Hinweise

Schlüssel sollten in der Regel als nicht transparente Datenbrocken behandelt werden. Es sollte nicht versucht werden, die interne Struktur dieser Daten auszunutzen. Die folgenden Eigenschaften können jedoch für alle ESENT-Schlüssel bekannt sein:

  • Schlüssel können mithilfe der memcmp-Funktion miteinander verglichen werden, um ihre relative Reihenfolge im ursprünglichen Index über die Tabelle der Quellindexeinträge zu erstellen.

  • Es ist bedeutungslos, Schlüssel von Indexeinträgen aus verschiedenen Indizes miteinander zu vergleichen.

  • Ein Schlüssel ist vor der JET_cbKeyMost Vista immer kleiner oder gleich Windows JET_cbKeyMost (255) Bytes. In Windows Vista und höheren Versionen können Die Schlüssel größer sein. Die maximale Größe eines Schlüssels entspricht dem aktuellen Wert JET_paramKeyMost.

Zusätzlich zu den oben genannten Eigenschaften von ESENT-Schlüsseln im Allgemeinen ist es wichtig zu beachten, dass sich ein Suchschlüssel vom Schlüssel für einen Indexeintrag unterscheiden kann. Insbesondere kann ein Suchschlüssel länger als ein gewöhnlicher Schlüssel sein. Diese zusätzliche Länge tritt auf, wenn beim Erstellen des Suchschlüssels eine Platzhalteroption verwendet wird. Weitere Informationen finden Sie unter JetMakeKey.

Es gibt einen wichtigen Fehler in dieser API, der in allen Releases vorhanden ist. Wenn der Suchschlüssel mithilfe von JET_bitRetrieveCopy angefordert wird und der Ausgabepuffer zu klein ist, um den gesamten Schlüssel zu empfangen, wird JET_wrnBufferTruncated NICHT zurückgegeben. JET_errSuccess wird stattdessen zurückgegeben. Es ist wichtig zu überprüfen, ob die tatsächliche Größe des Schlüssels, wie er mithilfe von "actual" zurückgegeben wird, kleiner oder gleich der Größe des Ausgabepuffers ist. Wenn die tatsächliche Größe größer als die Größe des Ausgabepuffers ist, sollte der Aufrufer von JetRetrikey so reagieren, als ob JET_wrnBufferTruncated zurückgegeben würden.

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

Wird in Esent.h deklariert.

Bibliothek

Verwenden Sie ESENT.lib.

DLL

Erfordert ESENT.dll.

Weitere Informationen

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange