JetSetCurrentIndex4 関数

[アーティクル]
06/13/2023

適用対象: Windows |Windows Server

JetSetCurrentIndex4 関数

JetSetCurrentIndex4 関数は、カーソルの現在のインデックスを設定するために使用されます。カーソルの現在のインデックスは、テーブル内のどのレコードをそのカーソルに表示するかを定義し、それらのレコードを公開するために使用するインデックスエントリのセットを選択して表示順序を定義します。

    JET_ERR JET_API JetSetCurrentIndex4(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in_opt      JET_INDEXID* pindexid,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

パラメーター

sesid

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

tableid

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

szIndexName

カーソルに対して選択するインデックスの名前。このパラメーターが NULL または空の文字列の場合は、クラスター化インデックスが選択されます。テーブルに対してプライマリインデックスが定義されている場合、クラスター化インデックスと同じであるため、そのインデックスが選択されます。テーブルにプライマリインデックスが定義されていない場合は、シーケンシャルインデックスが選択されます。シーケンシャルインデックスにはインデックス定義がありません。詳細については、「 JetCreateIndex 」を参照してください。

pindexid が NULL でない場合、インデックス名は無視され、インデックス ID によってインデックスが選択されます。

pindexid

カーソルに対して選択するインデックスの ID。

インデックス ID は、揮発性で不透明なハンドルであり、インデックスをすばやく選択するために使用できます。この ID は、JET_IdxInfoIndexId オプションを使用して JetGetIndexInfo または JetGetTableIndexInfo を使用して取得できます。

pindexid が NULL の場合、インデックスはインデックス名で選択され、インデックス ID は無視されます。

このパラメーターが存在しない場合、その値は NULL と見なされます。

grbit

この呼び出しに使用するオプションを含むビットのグループ。これには、次の 0 個以上が含まれます。

値	説明
JET_bitMoveFirst	このオプションは、指定したインデックスの最初のエントリにカーソルを置く必要があることを示します。クラスター化インデックス (プライマリインデックスまたはシーケンシャルインデックス) が選択されていて、現在のインデックスがセカンダリインデックスである場合は、JET_bitMoveFirstが想定されます。現在のインデックスが選択されている場合、このオプションは無視され、カーソル位置は変更されません。
JET_bitNoMove	このオプションは、古いインデックス上のカーソルの現在位置にあるインデックスエントリに関連付けられているレコードに対応する新しいインデックスのインデックスエントリにカーソルを置く必要があることを示します。新しいインデックスの定義に少なくとも 1 つの複数値キー列が含まれている場合、変換先のインデックスエントリはあいまいです。この場合、指定した itagSequence を使用して、カーソルを配置するために最も重要な複数値キー列の複数値を選択します。複数の複数値キー列の場合でも、1 つの itagSequence を渡す必要があるのは、エンジンが最も重要な複数値のキー列のすべての値のみを展開するためです。詳細については、「 JetCreateIndex 」を参照してください。 JET_bitMoveFirstが指定されている場合、このオプションは無視されます。現在のインデックスが選択されている場合、このオプションは無視され、カーソル位置は変更されません。このパラメーターが存在しない場合、その値はJET_bitMoveFirstと見なされます。

値

説明

JET_bitMoveFirst

このオプションは、指定したインデックスの最初のエントリにカーソルを置く必要があることを示します。クラスター化インデックス (プライマリインデックスまたはシーケンシャルインデックス) が選択されていて、現在のインデックスがセカンダリインデックスである場合は、JET_bitMoveFirstが想定されます。現在のインデックスが選択されている場合、このオプションは無視され、カーソル位置は変更されません。

JET_bitNoMove

このオプションは、古いインデックス上のカーソルの現在位置にあるインデックスエントリに関連付けられているレコードに対応する新しいインデックスのインデックスエントリにカーソルを置く必要があることを示します。

新しいインデックスの定義に少なくとも 1 つの複数値キー列が含まれている場合、変換先のインデックスエントリはあいまいです。この場合、指定した itagSequence を使用して、カーソルを配置するために最も重要な複数値キー列の複数値を選択します。複数の複数値キー列の場合でも、1 つの itagSequence を渡す必要があるのは、エンジンが最も重要な複数値のキー列のすべての値のみを展開するためです。詳細については、「 JetCreateIndex 」を参照してください。

JET_bitMoveFirstが指定されている場合、このオプションは無視されます。

現在のインデックスが選択されている場合、このオプションは無視され、カーソル位置は変更されません。このパラメーターが存在しない場合、その値はJET_bitMoveFirstと見なされます。

itagSequence

新しいインデックスにカーソルを置くために使用される複数値の列値のシーケンス番号。

このパラメーターは、JET_bitNoMoveと組み合わせてのみ使用されます。詳細については、このオプションの説明を参照してください。

このパラメーターが存在しない場合、または 0 に設定されている場合、その値は 1 と見なされます。

戻り値

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

リターンコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errBadItagSequence	JET_bitNoMove オプションを使用してセカンダリインデックスが選択されており、指定したシーケンス番号に対応する新しいインデックスの定義内の最初の複数値キー列の値はありません。
JET_errClientRequestToStopJetService	JetStopService の呼び出しの結果、セッションに関連付けられたインスタンス上のすべてのアクティビティが停止したため、操作を完了することはできません。
JET_errInstanceUnavailable	セッションに関連付けられているインスタンスで致命的なエラーが発生したため、操作を完了できません。このエラーでは、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要があります。このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errInvalidIndexId	インデックス ID の内容が無効であるか、有効期限が切れているので、更新する必要があります。これは、次の場合に JetSetCurrentIndex4 で発生する可能性があります。 pindexid-cbStruct> は、予想されるサイズではありません (Windows Server 2003 以降のリリース)。インデックス ID がフェッチされてから、エンジンはシャットダウンされています。インデックス ID に対応するインデックスを含むテーブルを参照しているすべてのカーソルが閉じられ、エンジンによってそのインデックスの定義がスキーマキャッシュから削除されました。インデックス ID は、間違ったテーブルでカーソルを開いた状態で使用されています。インデックスが削除されたか、セッションにまだ表示されていません。
JET_errInvalidName	指定されたオブジェクト名の 1 つが無効です。すべてのオブジェクト名は、同じ規則セットに準拠している必要があります。これらのルールを以下に示します。オブジェクト名は ASCII 文字で構成する必要があります。オブジェクト名の長さは少なくとも 1 文字にする必要があります。オブジェクト名の長さはJET_cbNameMost (64) 文字を超えることはできません。オブジェクト名はスペースで始まる場合があります。オブジェクト名には、ASCII 制御文字 (0x00 ~ 0x1F) を含めないようにしてください。オブジェクト名に感嘆符 (!)、ピリオド (.)、左角かっこ ([)、または右角かっこ (]) 文字を含めないようにしてください。検証が完了すると、最初のスペース (存在する場合) までの文字列の部分のみがオブジェクト名に使用されます。つまり、オブジェクト名にスペースも含まれていない可能性があります。
JET_errInvalidParameter	指定されたパラメーターの 1 つに、予期しない値が含まれていたか、別のパラメーターの値と組み合わせると意味のない値が含まれていました。これは、pindexid が NULL ではなく、pindexid-cbStruct> が予想されるサイズ (Windows XP 以前のリリース) ではない場合に、JetSetCurrentIndex4 で発生する可能性があります。
JET_errNoCurrentRecord	JET_bitNoMove オプションを使用してセカンダリインデックスが選択されており、新しいインデックスには、古いインデックス上のカーソルの現在位置にあるインデックスエントリに関連付けられているレコードに対応するインデックスエントリがありません。
JET_errNotInitialized	セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errOutOfCursors	エンジンは、カーソルを開くために使用されるリソースのプールを使い果たしました。一度に開くことができるカーソルの最大数は、 JET_paramMaxCursorsを使用して制御されます。詳細については、「JetSetSystemParameter 」を参照してください。これは、セカンダリインデックスが選択されていて、エンジンが内部カーソルを開いてそのインデックスを使用できない場合に、JetSetCurrentIndex4 で発生する可能性があります。
JET_errRestoreInProgress	セッションに関連付けられているインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errSessionSharingViolation	同じセッションを複数のスレッドに同時に使用することはできません。このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。

成功すると、カーソルの現在のインデックスが要求されたインデックスに設定されます。要求されたインデックスのインデックス定義に従って、JetSeek を使用してインデックスエントリを検索できるようになりました。インデックスエントリは、そのインデックス定義で指定された順序で JetMove を使用して列挙することもできます。カーソルの現在位置は、インデックスの最初のインデックスエントリ (JET_bitMoveFirst) または古いインデックス上のカーソルの現在位置 (JET_bitNoMove) に関連する特定のインデックスエントリに設定されます。データベースの状態に対する変更は行われません。

失敗した場合、カーソルの現在のインデックスと現在の位置は未定義の状態になります。データベースの状態に対する変更は行われません。

解説

インデックス ID ヒントが古い場合、API は単に失敗します。この場合、インデックスのテキスト名にフォールバックはありません。このフォールバックは、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が必要です。
Unicode	JetSetCurrentIndex4W (Unicode) および JetSetCurrentIndex4A (ANSI) として実装されます。

参照

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetSystemParameter

次の方法で共有

JetSetCurrentIndex4 関数