JetMove-Funktion

Gilt für: Windows | Windows Server

JetMove-Funktion

Die JetMove-Funktion positioniert einen Cursor am Anfang oder Ende eines Indexes und durchläuft die Einträge in diesem Index entweder vorwärts oder rückwärts. Es ist auch möglich, den Cursor auf dem aktuellen Index durch eine angegebene Anzahl von Indexeinträgen vorwärts oder rückwärts zu bewegen. Ein weiterer Ansatz besteht darin, die Indexeinträge, die mithilfe von JetMove aufgezählt werden können, künstlich einzuschränken, indem mithilfe von JetSetIndexRange ein Indexbereich auf dem Cursor eingerichtet wird.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __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.

Krähe

Ein beliebiger Offset, der die gewünschte Bewegung des Cursors auf dem aktuellen Index angibt.

Zusätzlich zu den Standardoffsets kann dieser Parameter auch mit einer der folgenden Optionen festgelegt werden.

Wert	Bedeutung
JET_MoveFirst	Verschiebt den Cursor zum ersten Indexeintrag im Index (sofern vorhanden). Dadurch werden alle Indexbereiche zurückgesetzt, die mit JetSetIndexRange festgelegt wurden. Hinweis Der Literalwert -2147483648 wird verwendet, um diese Option zu kennzeichnen. Verwenden Sie diesen Wert nicht als gewöhnlichen Offset, oder es kann zu unbeabsichtigtem Verhalten führen.
JET_MoveLast	Verschiebt den Cursor zum letzten Indexeintrag im Index (sofern vorhanden). Dadurch werden alle Indexbereiche zurückgesetzt, die mit JetSetIndexRange festgelegt wurden. Hinweis Der Literalwert von 2147483647 wird verwendet, um diese Option anzugeben. Verwenden Sie diesen Wert nicht als gewöhnlichen Offset, oder es kann zu unbeabsichtigtem Verhalten führen.
JET_MoveNext	Verschiebt den Cursor zum nächsten Indexeintrag im Index (sofern vorhanden). Dieser Wert ist genau gleich einem normalen Offset von +1. Es berücksichtigt Indexbereiche, die mit JetSetIndexRange festgelegt wurden.
JET_MovePrevious	Verschiebt den Cursor zum vorherigen Indexeintrag im Index (sofern vorhanden). Es berücksichtigt Indexbereiche, die mit JetSetIndexRange festgelegt wurden. Dieser Wert ist genau gleich einem normalen Offset von -1 oder 0 (Null). Der Cursor verbleibt an der aktuellen logischen Position, und das Vorhandensein des Indexeintrags, der dieser logischen Position entspricht, wird getestet.

grbit

Eine Gruppe von Bits, die null oder mehr der folgenden Optionen angeben.

Wert

Bedeutung

JET_bitMoveKeyNE

Verschiebt den Cursor um die Anzahl der Indexeinträge, die erforderlich sind, um die angeforderte Anzahl von Indexschlüsselwerten im Index zu überspringen. Dies hat den Effekt, dass Indexeinträge mit doppelten Schlüsselwerten in einen einzelnen Indexeintrag reduziert werden. Normalerweise bewegt ein Offset den Cursor um die angegebene Anzahl von Indexeinträgen, unabhängig von ihren Schlüsselwerten.

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. Für JetMove bedeutet dies, dass ein Indexeintrag am angeforderten Speicherort oder Offset für den aktuellen Index gefunden wurde.
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: Dieser Rückgabewert wird in Windows XP eingeführt.
JET_errNoCurrentRecord	Der Cursor ist derzeit nicht in einem Indexeintrag positioniert. Für JetMove bedeutet dies, dass kein Indexeintrag am angeforderten Speicherort oder Offset für den aktuellen Index gefunden wurde.
JET_errNotInitialized	Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete instance noch nicht initialisiert wurde.
JET_errRecordDeleted	Der Cursor ist derzeit logisch auf einem Indexeintrag positioniert, der einem gelöschten Datensatz entspricht.
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 der Cursor an einem Indexeintrag positioniert, der der angeforderten Position oder dem angeforderten Offset entspricht. Wenn ein Datensatz für das Update vorbereitet wurde, wird dieses Update abgebrochen. Wenn ein Indexbereich aktiv ist und JET_MoveFirst oder JET_MoveLast angegeben wurde, wird dieser Indexbereich abgebrochen. Es wird keine Änderung des Datenbankzustands vorgenommen.

Wenn diese Funktion fehlschlägt, bleibt die Position des Cursors unverändert, es sei denn, es wurde JET_errNoCurrentRecord zurückgegeben. In diesem Fall wird der Cursor an der Stelle positioniert, an der sich der Indexeintrag befindet, der der angeforderten Position oder dem angeforderten Offset entspricht. Der Cursor kann relativ zu dieser Position verschoben werden, befindet sich aber immer noch nicht in einem gültigen Indexeintrag. Wenn ein Datensatz für das Update vorbereitet wurde, wird dieses Update abgebrochen. Wenn ein Indexbereich aktiv ist und JET_MoveFirst oder JET_MoveLast angegeben wurde, wird dieser Indexbereich abgebrochen. Es wird keine Änderung des Datenbankzustands vorgenommen.

Bemerkungen

Ein Cursor kann mithilfe von JetMove an zwei spezielle Positionen verschoben werden: Before First und After Last. Wenn sich der Cursor auf dem ersten Indexeintrag in der Tabelle befindet und JetMove mit JET_MovePrevious aufgerufen wird, schlägt der Aufruf mit JET_errNoCurrentRecord fehl, und der Cursor wird logisch vor dem ersten Eintrag im Index positioniert. Diese logische Position wird auch dann beibehalten, wenn vor dem ersten Eintrag im Index ein anderer Indexeintrag eingefügt wird. Eine analoge Situation tritt für After Last relativ zum Ende des Indexes auf. Before First und After Last sind am nützlichsten beim Einrichten eines Bereichs von Indexeinträgen, der mit JetMove durchlaufen werden soll, wobei ein Iteratormodell verwendet wird, das vor der Verwendung dieses Elements immer zum nächsten (oder vorherigen) Element wechselt.

Der Satz von Indexeinträgen, die von JetMove aufgerufen werden können, kann durch Einrichten eines Indexbereichs auf dem Cursor eingeschränkt werden. Dies ist nützlich für Anwendungen, die eine Reihe von Indexeinträgen auflisten, die einfachen Kriterien entsprechen, die durch ein für diesen Index erstelltes Suchschlüsselpaar ausgedrückt werden können. Weitere Informationen finden Sie unter JetSetIndexRange.

Bei Releases vor Windows Server 2003 SP1 gibt es ein Problem in JetMove , das in bestimmten Fällen auftritt, das sich auf die korrekte Erzwingung eines Indexbereichs auswirkt, wie er von der JetSetIndexRange-Funktion eingerichtet wurde. Wenn sich der Cursor derzeit vor dem ersten Indexeintrag befindet und ein Indexbereich mit einer Obergrenze festgelegt ist, die kleiner als der erste Indexeintrag ist, wird der nächste JetMove-Aufruf fälschlicherweise an diesen Indexeintrag weiter ausgeführt, anstatt wie erwartet mit JET_errNoCurrentRecord fehlzuschlagen. Der gleiche Fehler tritt für die analoge Situation ab dem Ende des Indexes auf. Diese Situation kann in einer Anwendung auftreten, die einen Indexbereich einrichtet und mit einem Iterator navigiert, der erwartet, dass er vor dem ersten Indexeintrag beginnt, der ein Mitglied der Gruppe von Einträgen ist, die aufgelistet werden sollen, anstatt mit dem ersten Indexeintrag dieser Gruppe zu beginnen. Diese Situation tritt auch im analogen Fall ab dem Ende des Indexes auf. Die Problemumgehung besteht darin, dass die Anwendung manuell überprüft, ob sich der abgerufene Indexeintrag innerhalb des Indexbereichs befindet, indem der Schlüssel für den aktuellen Indexeintrag (abgerufen mit JetRetrieveKey) mit dem Schlüssel verglichen wird, der das Ende des aktuellen Indexbereichs darstellt (abgerufen mit JetRetrieveKey mithilfe von JET_bitRetrieveCopy).

Es ist wichtig, vorsichtig zu sein, wenn berechnete Offsets an JetMove übergeben werden. Wenn der berechnete Offset kleiner oder gleich JET_MoveFirst ist, muss dieser Offset in mehrere Teile aufgeteilt werden, die jeweils separat, aber innerhalb einer einzelnen Transaktion an JetMove übergeben werden, um den gewünschten Effekt zu erzielen. Dasselbe gilt für Offsets, die größer oder gleich JET_MoveNext. Es ist unwahrscheinlich, dass eine Anwendung dies in der realen Welt durchmachen würde, aber es ist gut, angesichts der sehr unterschiedlichen Semantik von JET_MoveFirst und JET_MoveLast von einem gewöhnlichen Offset eine Verteidigung gegen diesen Fall zu haben.

Wenn JetMove mit einem sehr großen Offset aufgerufen wird, z. B. wenn der cRow-Parameter auf 1000 festgelegt ist, durchläuft JetMove alle 1000 Indexeinträge, um die endgültige Position zu erreichen. Derzeit bietet die ESE-API keine effiziente Möglichkeit, direkt zu einem bestimmten Indexeintrag per Offset zu wechseln, ohne jeden Indexeintrag zu durchlaufen.

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_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange