次の方法で共有

JetMove 関数

  • [アーティクル]

適用対象: Windows |Windows Server

JetMove 関数

JetMove 関数は、インデックスの先頭または末尾にカーソルを置き、そのインデックス内のエントリを前方または後方に移動します。 また、指定した数のインデックス エントリによって、現在のインデックス上でカーソルを前方または後方に移動することもできます。 もう 1 つの方法は、JetSetIndexRange を使用してカーソルにインデックス範囲を設定することで、JetMove を使用して列挙できるインデックス エントリを人為的に制限することです。

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

パラメーター

sesid

この呼び出しに使用するセッション。

tableid

この呼び出しに使用するカーソル。

カラス

現在のインデックス上でのカーソルの目的の移動を示す任意のオフセット。

標準オフセットに加えて、このパラメーターは次のいずれかのオプションで設定することもできます。

値

説明

JET_MoveFirst

インデックス内の最初のインデックス エントリ (存在する場合) にカーソルを移動します。 これにより、 JetSetIndexRange で設定されたインデックス範囲がリセットされます。

メモ このオプションを示すために、-2147483648 のリテラル値が使用されます。 通常のオフセットまたは意図しない動作が発生する可能性があるため、この値を使用しないでください。

JET_MoveLast

インデックス内の最後のインデックス エントリ (存在する場合) にカーソルを移動します。 これにより、 JetSetIndexRange で設定されたインデックス範囲がリセットされます。

メモ 2147483647のリテラル値は、このオプションを示すために使用されます。 通常のオフセットまたは意図しない動作が発生する可能性があるため、この値を使用しないでください。

JET_MoveNext

インデックス内の次のインデックス エントリ (存在する場合) にカーソルを移動します。 この値は、+1 の通常のオフセットと正確に等しくなります。 JetSetIndexRange で設定されたインデックス範囲が考慮されます。

JET_MovePrevious

インデックス内の前のインデックス エントリ (存在する場合) にカーソルを移動します。 JetSetIndexRange で設定されたインデックス範囲が考慮されます。

この値は、-1 または 0 (ゼロ) の通常のオフセットと正確に等しくなります。

カーソルは現在の論理位置に残り、その論理位置に対応するインデックス エントリの存在がテストされます。

grbit

次のオプションの 0 個以上を指定するビットのグループ。

値

説明

JET_bitMoveKeyNE

インデックスで検出されたインデックス キー値の要求された数をスキップするために必要なインデックス エントリの数だけ、カーソルを前方または後方に移動します。 これは、重複するキー値を持つインデックス エントリを 1 つのインデックス エントリに折りたたむ効果があります。 通常、オフセットは、キー値に関係なく、指定した数のインデックス エントリだけカーソルを移動します。

戻り値

この関数は、次のいずれかのリターン コードを使用して 、JET_ERR データ型を返します。 考えられる ESE エラーの詳細については、「 拡張可能ストレージ エンジン エラー 」および「 エラー処理パラメーター」を参照してください。

リターン コード

説明

JET_errSuccess

操作は正常に完了しました。 JetMove の場合、これは、現在のインデックスの要求された場所またはオフセットでインデックス エントリが見つかったことを意味します。

JET_errClientRequestToStopJetService

JetStopService の呼び出しの結果、セッションに関連付けられているインスタンス上のすべてのアクティビティが停止したため、操作を完了できません。

JET_errInstanceUnavailable

セッションに関連付けられているインスタンスで致命的なエラーが発生したため、操作を完了できません。このエラーでは、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要があります。

Windows XP: この戻り値は Windows XP で導入されています。

JET_errNoCurrentRecord

現在、カーソルはインデックス エントリに配置されていません。 JetMove の場合、これは、現在のインデックスの要求された場所またはオフセットでインデックス エントリが見つからなかったことを意味します。

JET_errNotInitialized

セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。

JET_errRecordDeleted

カーソルは現在、削除されたレコードに対応するインデックス エントリに論理的に配置されています。

JET_errRestoreInProgress

セッションに関連付けられているインスタンスで復元操作が進行中のため、操作を完了できません。

JET_errSessionSharingViolation

同じセッションを複数のスレッドに同時に使用することはできません。

Windows XP: この戻り値は Windows XP で導入されています。

JET_errTermInProgress

セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。

この関数が成功すると、カーソルは、要求された場所またはオフセットと一致するインデックス エントリに配置されます。 レコードが更新用に準備されている場合、その更新は取り消されます。 インデックス範囲が有効で、JET_MoveFirstまたはJET_MoveLastが指定されている場合、そのインデックス範囲は取り消されます。 データベースの状態は変更されません。

この関数が失敗した場合、JET_errNoCurrentRecordが返されない限り、カーソルの位置は変更されません。 その場合、カーソルは、要求された場所またはオフセットと一致するインデックス エントリが配置された場所に配置されます。 カーソルは、その位置を基準にして移動できますが、有効なインデックス エントリ上にありません。 レコードが更新用に準備されている場合、その更新は取り消されます。 インデックス範囲が有効で、JET_MoveFirstまたはJET_MoveLastが指定されている場合、そのインデックス範囲は取り消されます。 データベースの状態は変更されません。

解説

JetMove の Before First と After Last を使用して、カーソルを 2 つの特殊な位置に移動できます。 カーソルがテーブルの最初のインデックス エントリにあり、 JetMove が JET_MovePrevious で呼び出された場合、呼び出しはJET_errNoCurrentRecordで失敗し、カーソルはインデックス内の最初のエントリの前に論理的に配置されます。 この論理位置は、インデックスの最初のエントリの前に別のインデックス エントリが挿入された場合でも維持されます。 同様の状況は、インデックスの末尾を基準にした After Last に対して発生します。 Before First and After Last は、 JetMove を使用して反復処理するインデックス エントリの範囲を設定する場合に最も便利です。その要素を使用する前に常に次の (または前の) 要素に移動することを想定する反復子モデルを使用します。

JetMove がアクセスできるインデックス エントリのセットは、カーソルにインデックス範囲を設定することによって制限できます。 これは、そのインデックス用に構築された検索キーのペアで表すことができる単純な条件に一致するインデックス エントリのセットを列挙するアプリケーションに役立ちます。 詳細については、「 JetSetIndexRange」を参照してください。

Windows Server 2003 SP1 より前のリリースでは、JetSetIndexRange 関数によって設定されたインデックス範囲の正しい適用に影響する、特定のケースで発生する JetMove に問題があります。 カーソルが現在最初のインデックス エントリの前にあり、インデックス範囲が最初のインデックス エントリより小さい上限で設定されている場合、 JetMove の次の呼び出しでは、予期したJET_errNoCurrentRecordで失敗するのではなく、誤ってそのインデックス エントリに移動します。 インデックスの末尾から始まる類似した状況でも、同じエラーが発生します。 この状況は、インデックス範囲を設定し、そのセットの最初のインデックス エントリではなく、列挙するエントリのセットのメンバーである最初のインデックス エントリの前に開始することを想定する反復子を使用して移動するアプリケーションで発生する可能性があります。 この状況は、インデックスの末尾から始まる類似のケースでも発生します。 回避策は、現在のインデックス エントリのキー ( JetRetrieveKey を使用して取得) と現在のインデックス範囲の末尾を表すキー (JET_bitRetrieveCopy を使用して JetRetrieveKey を使用して取得) を比較することで、取得したインデックス エントリがインデックス範囲内にあることを手動で確認することです。

計算されたオフセットを JetMove に渡す場合は注意が必要です。 計算されたオフセットがJET_MoveFirst以下の場合、そのオフセットは複数の部分に分割する必要があります。それぞれのオフセットは JetMove に個別に渡されますが、目的の効果を得るには 1 つのトランザクション内で渡されます。 JET_MoveNext以上のオフセットについても同様です。 アプリケーションが実際にこれを受ける可能性は低いですが、通常のオフセットからJET_MoveFirstとJET_MoveLastのセマンティクスが非常に異なることを考えると、このケースに対する防御を持つことは良い方法です。

cRow パラメーターが 1000 に設定されている場合など、 JetMove が非常に大きなオフセットで呼び出されると、 JetMove は 1000 個のインデックス エントリをすべて走査して最終的な位置に到達します。 現在、ESE API では、各インデックス エントリを走査せずにオフセットによって特定のインデックス エントリに直接移動する効率的な方法は提供されていません。

必要条件

要件 値

Client

Windows Vista、Windows XP、または Windows 2000 Professional が必要です。

[サーバー]

Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。

Header

Esent.h で宣言されています。

Library

ESENT.lib を使用します。

[DLL]

ESENT.dllが必要です。

参照

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange