JetRetrieveKey-Funktion

Artikel
06/13/2023

Gilt für: Windows | Windows Server

JetRetrieveKey-Funktion

Die JetRetrieveKey-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 den gleichen Indexeintrag zurückzugeben.

    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 empfängt.

cbMax

Die maximale Größe des Ausgabepuffers in Byte.

pcbActual

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

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 Optionen enthalten, die für diesen Aufruf verwendet werden sollen, einschließlich 0 oder mehr der folgenden Optionen.

Wert	Bedeutung
JET_bitRetrieveCopy	Bei Angabe gibt die Engine den Suchschlüssel für den Cursor zurück. Der Suchschlüssel wird mithilfe eines oder mehrerer vorheriger Aufrufe von JetMakeKey erstellt, um mithilfe von JetSeek nach diesem Schlüssel zu suchen oder mithilfe von JetSetIndexRange einen Indexbereich festzulegen.

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_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_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_errKeyNotMade	Es gibt keinen aktuellen Suchschlüssel für den Cursor. Dies geschieht für JetRetrieveKey , wenn JET_bitRetrieveCopy angegeben ist und kein Suchschlüssel für diesen Cursor mithilfe eines vorherigen Aufrufs von JetMakeKey erstellt wurde. Der Suchschlüssel wird durch einen vorherigen Aufruf einer anderen Navigations-API auf dem Cursor als JetMove gelöscht.
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	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 ein Wiederherstellungsvorgang für die instance ausgeführt wird, die der Sitzung zugeordnet ist.
JET_errSessionSharingViolation	Dieselbe Sitzung kann nicht für mehrere Threads gleichzeitig verwendet werden. 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 instance 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 dem erforderlichen Schlüssel gefüllt. 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 Schlüssel, wie in den bereitgestellten Platz passt, und die tatsächliche Größe des Schlüssels ist genau. Es wird keine Änderung des Datenbankzustands vorgenommen.

Bei einem Fehler sind der Status des Ausgabepuffers und die tatsächliche Größe des Schlüssels nicht definiert. Es wird keine Änderung des Datenbankzustands vorgenommen.

Bemerkungen

Schlüssel sollten im Allgemeinen als undurchsichtige Datenblöcke behandelt werden. Es sollte kein Versuch unternommen werden, die interne Struktur dieser Daten auszunutzen. Die folgenden Eigenschaften sind jedoch für alle ESENT-Schlüssel bekannt:

Schlüssel können mithilfe der memcmp-Funktion miteinander verglichen werden, um ihre relative Reihenfolge im Ursprungsindex über der Tabelle der Quellindexeinträge festzulegen.
Es ist bedeutungslos, Schlüssel von Indexeinträgen aus verschiedenen Indizes miteinander zu vergleichen.
Ein Schlüssel ist vor Windows Vista immer kleiner oder gleich JET_cbKeyMost (255) Bytes. Unter Windows Vista und späteren Versionen können die Tasten größer sein. Die maximale Größe eines Schlüssels entspricht dem aktuellen Wert von 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 unterscheidet. Insbesondere kann ein Suchschlüssel länger sein als ein gewöhnlicher Schlüssel. Diese zusätzliche Länge tritt auf, wenn beim Erstellen des Suchschlüssels eine Wildcard-Option 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. stattdessen wird JET_errSuccess zurückgegeben. Es ist wichtig zu überprüfen, ob die tatsächliche Größe des Schlüssels, wie er mithilfe von pcbActual 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 JetRetrieveKey so reagieren, als ob stattdessen 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.
Kopfzeile	Deklariert in Esent.h.
Bibliothek	Verwenden Sie ESENT.lib.
DLL	Erfordert ESENT.dll.

Weitere Informationen

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange

JetRetrieveKey-Funktion