JetGotoBookmark-Funktion

Gilt für: Windows | Windows Server

JetGotoBookmark-Funktion

Die JetGotoBookmark-Funktion positioniert einen Cursor an einen Indexeintrag für den Datensatz, der dem angegebenen Lesezeichen zugeordnet ist. Das Lesezeichen kann mit jedem Index verwendet werden, der für eine Tabelle definiert ist. Das Lesezeichen für einen Datensatz kann mithilfe von JetGetBookmark abgerufen werden.

    JET_ERR JET_API JetGotoBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          void* pvBookmark,
      __in          unsigned long cbBookmark
    );

Parameter

sesid

Die Sitzung, die für diesen Aufruf verwendet werden soll.

tableid

Der Cursor, der für diesen Aufruf verwendet werden soll.

pvBookmark

Der Puffer, der das Lesezeichen enthält, das zum Positionieren des Cursors verwendet werden soll.

cbBookmark

Die Größe des Lesezeichens im Puffer.

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	Der Vorgang kann nicht abgeschlossen werden, da alle Aktivitäten auf der instance, 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 instance ein schwerwiegender Fehler aufgetreten ist, der erfordert, dass der Zugriff auf alle Daten widerrufen werden muss, um die Integrität dieser Daten zu schützen. Windows XP: Dieser Rückgabewert wurde in Windows XP eingeführt.
JET_errInvalidBookmark	Das bereitgestellte Lesezeichen ist ungültig. Dies ist möglicherweise aufgetreten, weil die Größe des Lesezeichens null oder der Lesezeichenpufferzeiger NULL ist.
JET_errNoCurrentRecord	Der Cursor befindet sich auf einem sekundären Index, und für den Datensatz, der dem Lesezeichen zugeordnet ist, konnte kein Indexeintrag gefunden werden.
JET_errNotInitialized	Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete instance noch nicht initialisiert wurde.
JET_errRecordDeleted	Der Datensatz, der dem Lesezeichen zugeordnet ist, konnte nicht gefunden werden.
JET_errRestoreInProgress	Der Vorgang kann nicht abgeschlossen werden, 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. Windows XP: Dieser Rückgabewert wurde in Windows XP eingeführt.
JET_errTermInProgress	Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete instance heruntergefahren wird.

Wenn diese Funktion erfolgreich ist, wird der Cursor an einem Indexeintrag für den Datensatz positioniert, der dem angegebenen Lesezeichen zugeordnet ist. Wenn ein Datensatz für das Update vorbereitet wurde, wird dieses Update abgebrochen. Wenn ein Indexbereich aktiv ist, wird dieser Indexbereich abgebrochen. Wenn ein Suchschlüssel für den Cursor erstellt wurde, wird dieser Suchschlüssel gelöscht. Es wird keine Änderung des Datenbankzustands vorgenommen.

Wenn diese Funktion fehlschlägt, bleibt die Position des Cursors unverändert. Wenn ein Datensatz für das Update vorbereitet wurde, wird dieses Update abgebrochen. Wenn ein Indexbereich aktiv ist, wird dieser Indexbereich abgebrochen. Wenn ein Suchschlüssel für den Cursor erstellt wurde, wird dieser Suchschlüssel gelöscht. Es wird keine Änderung des Datenbankzustands vorgenommen.

Bemerkungen

Es gibt zwei Möglichkeiten, ein Lesezeichen zu verwenden, um einen Cursor auf einem Index zu positionieren. Die erste besteht darin, das Lesezeichen zu verwenden, um direkt auf dem Datensatz zu positionieren. Dies tritt auf, wenn der aktuelle Index des Cursors der primäre Index ist. Dieses Verfahren funktioniert, da ein ESENT-Lesezeichen mit dem Primärschlüssel des zugeordneten Datensatzes identisch ist.

Die zweite Möglichkeit, ein Lesezeichen zu verwenden, besteht darin, es auf einem Eintrag in einem sekundären Index zu positionieren, der dem Datensatz entspricht, der diesem Lesezeichen zugeordnet ist. Während dieses Vorgangs sucht die Engine den tatsächlichen Datensatz mithilfe des Lesezeichens im primären Index. Anschließend werden die Datensatzdaten und die Definition des sekundären Indexes verwendet, um einen Schlüssel in den sekundären Index zu berechnen, der auf den Datensatz verweist. Anschließend wird der Cursor auf den Indexeintrag für diesen Schlüssel positioniert. Wenn sich der Cursor derzeit auf einem sekundären Index über einer oder mehreren mehrwertigen Schlüsselspalten befindet, wird der Cursor auf dem Indexeintrag positioniert, der dem ersten Multiwert jeder dieser Schlüsselspalten entspricht.

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_SESID
JET_TABLEID
JetGetBookmark