JetRetrieveKey-Funktion

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.

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.

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

Weitere Informationen

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange