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

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

カラス

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

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

grbit

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

戻り値

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

この関数が成功すると、カーソルは、要求された場所またはオフセットと一致するインデックス エントリに配置されます。 レコードが更新用に準備されている場合、その更新は取り消されます。 インデックス範囲が有効で、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 では、各インデックス エントリを走査せずにオフセットによって特定のインデックス エントリに直接移動する効率的な方法は提供されていません。

必要条件

参照

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange