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