JetGetBookmark-Funktion

Gilt für: Windows | Windows Server

JetGetBookmark-Funktion

Die JetGetBookmark-Funktion ruft das Lesezeichen für den Datensatz ab, der dem Indexeintrag an der aktuellen Position eines Cursors zugeordnet ist. Dieses Lesezeichen kann dann verwendet werden, um den Cursor mithilfe von JetGoToBookmark wieder auf denselben Datensatz zu positionieren.

    JET_ERR JET_API JetGetBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

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 Ausgabepuffer, der das Lesezeichen empfängt.

cbMax

Die maximale Größe des Ausgabepuffers in Bytes.

pcbActual

Die tatsächliche Größe des Lesezeichens in Bytes.

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

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

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_errBufferTooSmall	Der Vorgang wurde erfolgreich abgeschlossen, aber der Ausgabepuffer war zu klein, um das gesamte Lesezeichen zu empfangen. Der Ausgabepuffer wurde mit so viel Textmarke gefüllt, wie es passen würde. Bei Bedarf wurde auch die tatsächliche Größe des Lesezeichens zurückgegeben.
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 instance, die der Sitzung zugeordnet ist, 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: Diese Rückgabewerte werden in Windows XP eingeführt.
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 nach dem letzten Datensatz im aktuellen Index positioniert ist.
JET_errNotInitialized	Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete instance noch nicht initialisiert wurde.
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 wird 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 das Lesezeichen für den Datensatz, der dem Indexeintrag an der aktuellen Position eines Cursors zugeordnet ist, im Ausgabepuffer zurückgegeben. Es wird keine Änderung des Datenbankzustands vorgenommen.

Wenn diese Funktion fehlschlägt, sind der Status des Ausgabepuffers und die tatsächliche Größe des Lesezeichens nicht definiert, es sei denn, es wurde JET_errBufferTooSmall zurückgegeben. Für den Fall, dass JET_errBufferTooSmall zurückgegeben wird, enthält der Ausgabepuffer so viel vom Lesezeichen, wie in den bereitgestellten Platz passt, und die tatsächliche Größe des Lesezeichens ist genau. Es wird keine Änderung des Datenbankzustands vorgenommen.

Bemerkungen

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

• Ein Lesezeichen identifiziert einen Datensatz in einer bestimmten Tabelle eindeutig.

• Das Lesezeichen eines Datensatzes ändert sich während der Lebensdauer dieses Datensatzes nicht.

• Das Lesezeichen eines Datensatzes ist identisch mit dem Schlüssel dieses Datensatzes im primären Index über der Tabelle, die diesen Datensatz enthält. Wenn kein primärer Index für diese Tabelle definiert ist, erstellt die Datenbank-Engine ein eigenes Lesezeichen für den Datensatz.

• Lesezeichen können mithilfe der memcmp-Funktion miteinander verglichen werden, um ihre relative Reihenfolge im primären Index über der Tabelle der Quelldatensätze festzulegen. Wenn kein primärer Index für diese Tabelle definiert ist, ist es nicht sinnvoll, die relative Reihenfolge der Lesezeichen aus dieser Tabelle zu verwenden.

• Es ist bedeutungslos, Lesezeichen von Datensätzen aus verschiedenen Tabellen miteinander zu vergleichen.

• Ein Lesezeichen ist vor Windows Vista immer kleiner oder gleich JET_cbBookmarkMost (256) Bytes.

Windows Vista: Unter Windows Vista und höheren Versionen können Lesezeichen größer als JET_cbBookmarkMost (256) Bytes sein. Die maximale Größe eines Lesezeichens entspricht dem aktuellen Wert von JET_paramKeyMost + 1.

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
JetGoToBookmark
JetStopService
memcmp