JetSetCurrentIndex 関数

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

適用対象: Windows |Windows Server

JetSetCurrentIndex 関数

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

    JET_ERR JET_API JetSetCurrentIndex(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const tchar* szIndexName
    );

パラメーター

sesid

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

tableid

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

szIndexName

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

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

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

戻り値

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

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

参照

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

次の方法で共有

JetSetCurrentIndex 関数