JetGetSecondaryIndexBookmark-Funktion

Artikel
06/13/2023

Gilt für: Windows | Windows Server

JetGetSecondaryIndexBookmark-Funktion

Die JetGetSecondaryIndexBookmark-Funktion ruft ein spezielles Lesezeichen für den sekundären Indexeintrag an der aktuellen Position eines Cursors ab. Dieses Lesezeichen kann dann verwendet werden, um den Cursor mithilfe von JetGotoSecondaryIndexBookmark effizient auf denselben Indexeintrag zurück zu positionieren. Dies ist am nützlichsten, wenn sie in einem sekundären Index neu positioniert werden, der doppelte Schlüssel enthält oder mehrere Indexeinträge für denselben Datensatz enthält.

Windows XP: JetGetSecondaryIndexBookmark wird in Windows XP eingeführt.

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const 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.

pvSecondaryKey

Der Ausgabepuffer, der den sekundären Schlüssel empfängt.

cbSecondaryKeyMax

Die maximale Größe des Ausgabepuffers für den sekundären Schlüssel in Bytes.

pcbSecondaryKeyActual

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

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

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

pvPrimaryBookmark

Der Ausgabepuffer, der das Lesezeichen des Primärschlüssels empfängt.

cbPrimaryBookmarkMax

Die maximale Größe des Ausgabepuffers für das Primärschlüssel-Lesezeichen in Bytes.

pcbPrimaryKeyActual

Empfängt die tatsächliche Größe des Primärschlüssel-Lesezeichens in Bytes.

Wenn dieser Parameter NULL ist, wird die tatsächliche Größe des Primärschlüssel-Lesezeichens nicht zurückgegeben.

Wenn der Ausgabepuffer zu klein ist, wird die tatsächliche Größe des Primärschlüssel-Lesezeichens trotzdem zurückgegeben. Das bedeutet, dass diese Zahl größer als die Größe des Ausgabepuffers ist.

grbit

Für die zukünftige Verwendung reserviert.

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 Erweiterbare Speichermodulfehler und Fehlerbehandlungsparameter.

Rückgabecode	Beschreibung
JET_errSuccess	Der Vorgang wurde erfolgreich abgeschlossen.
JET_errBufferTooSmall	Der Vorgang wurde erfolgreich abgeschlossen, aber einer der Ausgabepuffer war zu klein, um die angeforderten Daten zu empfangen. Der Ausgabepuffer wurde mit der menge des Lesezeichens gefüllt, wie es passen würde. Bei Bedarf wurde auch die tatsächliche Größe des Lesezeichens zurückgegeben.
JET_errClientRequestToStopJetService	Es ist nicht möglich, den Vorgang abzuschließen, da alle Aktivitäten auf dem 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 beim instance, der 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 höheren Versionen zurückgegeben.
JET_errNoCurrentIndex	Der Cursor befindet sich derzeit nicht auf einem sekundären Index. Es ist nicht sinnvoll, ein sekundäres Index-Lesezeichen abzurufen, wenn der Cursor derzeit keinen sekundären Index verwendet. JetGetBookmark sollte verwendet werden, wenn sich der Cursor nicht auf einem sekundären Index befindet.
JET_errNoCurrentRecord	Der Cursor wird 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 auf dem der Sitzung zugeordneten instance ein Wiederherstellungsvorgang ausgeführt wird.
JET_errSessionSharingViolation	Dieselbe Sitzung kann nicht für mehrere Threads gleichzeitig verwendet werden. Dieser Fehler wird nur von Windows XP und höheren Versionen zurückgegeben.
JET_errTermInProgress	Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete instance heruntergefahren wird.

Bei Erfolg wird das Lesezeichen des sekundären Indexes für den Indexeintrag an der aktuellen Position eines Cursors in den Ausgabepuffern zurückgegeben. Es wird keine Änderung des Datenbankstatus vorgenommen.

Bei Einem Fehler sind der Zustand der Ausgabepuffer und die tatsächliche Größe des sekundären Index-Lesezeichens nicht definiert, es sei denn, JET_errBufferTooSmall wurde zurückgegeben. Für den Fall, dass JET_errBufferTooSmall zurückgegeben wird, enthalten die Ausgabepuffer so viel des sekundären Index-Lesezeichens, wie in den bereitgestellten Speicherplatz passt, und die tatsächliche Größe des Lesezeichens für den sekundären Index ist genau. In jedem Fall wird keine Änderung des Datenbankzustands vorgenommen.

Bemerkungen

Lesezeichen sollten im Allgemeinen als undurchsichtige Datenblöcke behandelt werden. Es sollte nicht versucht werden, die interne Struktur dieser Daten zu nutzen. Die folgenden Eigenschaften sind jedoch für alle ESENT-Lesezeichen bekannt:

Ein Lesezeichen identifiziert einen Datensatz in einer bestimmten Tabelle eindeutig.
Das Lesezeichen eines Datensatzes ändert sich für die Lebensdauer dieses Datensatzes nicht.
Das Lesezeichen eines Datensatzes ist identisch mit dem Schlüssel dieses Datensatzes im primären Index für die Tabelle, die diesen Datensatz enthält. Wenn für diese Tabelle kein primärer Index definiert ist, erstellt die Datenbank-Engine ein eigenes Lesezeichen für den Datensatz.
Lesezeichen können mithilfe von memcmp miteinander verglichen werden, um ihre relative Reihenfolge im primären Index gegenüber der Tabelle der Quelldatensätze festzulegen. Wenn für diese Tabelle kein primärer Index definiert ist, ist die relative Reihenfolge der Lesezeichen aus dieser Tabelle nicht sinnvoll.
Es ist sinnlos, Lesezeichen von Datensätzen aus verschiedenen Tabellen miteinander zu vergleichen.
Ein Lesezeichen ist immer kleiner oder gleich JET_cbBookmarkMost (256) Bytes länge vor Windows Vista. Unter Windows Vista und höheren Versionen können Lesezeichen größer sein. Die maximale Größe eines Lesezeichens entspricht dem aktuellen Wert von JET_paramKeyMost + 1.

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

Schlüssel können unter Verwendung von memcmp miteinander verglichen werden, um ihre relative Reihenfolge im Ursprungsindex gegenüber der Tabelle der Quellindexeinträge festzulegen.
Es ist sinnlos, Schlüssel von Indexeinträgen aus verschiedenen Indizes miteinander zu vergleichen.
Ein Schlüssel ist immer kleiner oder gleich JET_cbKeyMost (255) Bytes länge vor Windows Vista. Unter 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 von JET_paramKeyMost.

Anforderungen

Anforderung	Wert
Client	Erfordert Windows Vista oder Windows XP.
Server	Erfordert Windows Server 2008 oder Windows Server 2003.
Kopfzeile	Deklariert in Esent.h.
Bibliothek	Verwenden Sie ESENT.lib.
DLL	Erfordert ESENT.dll.

Weitere Informationen

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp

JetGetSecondaryIndexBookmark-Funktion