JetSetIndexRange 函式

發行項
06/12/2023

適用于： Windows |Windows Server

JetSetIndexRange 函式

JetSetIndexRange函式會暫時限制資料指標可以使用JetMove從目前索引項目目開始的索引項目目，並結束于符合該資料指標中搜尋索引鍵所指定之搜尋準則的索引項目目集，以及指定的系結準則。先前必須使用 JetMakeKey建構搜尋金鑰。

    JET_ERR JET_API JetSetIndexRange(
      __in          JET_SESID sesid,
    __in          JET_TABLEID tableidSrc,
      __in          JET_GRBIT grbit
    );

參數

sesid

要用於這個呼叫的會話。

tableidSrc

要用於這個呼叫的資料指標。

grbit

一組位，其中包含要用於此呼叫的選項，其中包含下列零個或多個內容：

值	意義
JET_bitRangeInclusive	這個選項的存在或不存在表示索引範圍的界限準則。出現時，此選項表示索引範圍的限制是包含的。如果不存在，此選項表示索引範圍的限制是獨佔的。當索引範圍的限制包含時，任何完全符合搜尋準則的索引項目目就會包含在範圍中。
JET_bitRangeInstantDuration	此選項會要求在建立索引範圍後立即移除。作業的所有其他層面都會保持不變。這適用于測試符合搜尋準則的索引項目目是否存在。
JET_bitRangeRemove	此選項會要求取消資料指標上的現有索引範圍。取消索引範圍之後，就可以使用 JetMove超出索引範圍的結尾。如果索引範圍尚未生效， JetSetIndexRange 將會失敗並JET_errInvalidOperation。指定此選項時，會忽略所有其他選項。
JET_bitRangeUpperLimit	如果使用此選項，則資料指標中的搜尋索引鍵代表索引項目最接近索引範圍結尾之索引項目目的搜尋準則。索引範圍會在游標的目前位置與這個索引項目目之間建立，以便透過使用 JetMove 與JET_MoveNext或正位移的 JetMove ，在索引上向前查看所有相符專案。搭配使用 JetMakeKey 所建構的搜尋索引鍵，使用萬用字元選項尋找最接近索引開頭的索引項目目並不有意義。如果省略此選項，則資料指標中的搜尋索引鍵代表最接近索引範圍的索引項目目開頭的搜尋準則。索引範圍會在游標的目前位置與此索引項目目之間建立，以便透過使用 JetMove 與JET_MovePrevious或負位移的 JetMove 往回查看索引，找到所有相符專案。使用 JetMakeKey 使用萬用字元選項來尋找最接近索引結尾的索引項目目，以使用 JetMakeKey 建構的搜尋索引鍵並無意義。

傳回值

此函式會傳回具有下列其中一個傳回碼的JET_ERR 資料類型。如需可能 ESE 錯誤的詳細資訊，請參閱可延伸的儲存引擎錯誤和錯誤處理參數。

傳回碼	Description
JET_errSuccess	作業已成功完成。對於 JetSetIndexRange，這表示現有的索引範圍已取消，或索引範圍內至少有一個索引項目目。
JET_errClientRequestToStopJetService	因為與會話相關聯的實例上的所有活動因為對 JetStopService的呼叫而停止，所以無法完成作業。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，要求撤銷所有資料的存取權以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidOperation	指定JET_bitRangeRemove且沒有作用中的索引範圍時， JetSetIndexRange 會傳回此錯誤。
JET_errKeyNotMade	資料指標目前沒有搜尋索引鍵。 JetSetIndexRange 要求游標具有有效的搜尋索引鍵，因為它會針對用來尋找索引項目目的搜尋準則使用該索引鍵。
JET_errNoCurrentIndex	資料指標目前沒有索引。如果資料指標位於資料表的叢集索引上，則 JetSetIndexRange 會發生這種情況，但尚未定義主要索引。不支援在這類索引上設定索引範圍。
JET_errNoCurrentRecord	JetSetIndexRange會傳回此錯誤，指出索引範圍內沒有索引項目目。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errRestoreInProgress	因為與會話相關聯的實例上正在進行還原作業，所以無法完成作業。
JET_errSessionSharingViolation	同一個會話不能同時用於多個執行緒。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	因為與會話相關聯的實例正在關閉，所以無法完成作業。

成功時，如果指定JET_bitRangeRemove，則會取消目前生效的索引範圍。如果未指定JET_bitRangeRemove且指定JET_bitRangeInstantDuration，則不會有任何索引範圍生效。如果未指定JET_bitRangeRemove或JET_bitRangeInstantDuration，則新的索引範圍會生效。此索引範圍會暫時限制資料指標可以使用 JetMove 從目前索引項目目開始的索引項目目集，並結束于符合搜尋準則的索引項目目。游標的位置會保持不變。如果已針對游標建構搜尋索引鍵，則會刪除該搜尋索引鍵。不會變更資料庫狀態。

失敗時，如果未傳回JET_errNoCurrentRecord，則不會有任何索引範圍生效。如果傳回JET_errNoCurrentRecord，則新的索引範圍會生效。此索引範圍會暫時限制資料指標可以使用 JetMove 從目前索引項目目開始的索引項目目集，並結束于符合搜尋準則的索引項目目。游標的位置會保持不變。如果傳回JET_errNoCurrentRecord，而且已針對游標建構搜尋索引鍵，則會刪除該搜尋索引鍵。不會變更資料庫狀態。

備註

索引範圍是變動性的，而且如果在游標上執行 JetMove 以外的任何導覽，則會自動取消。

索引範圍只能以一個方向運作。如果已建立上限，則只有使用 JetMove 搭配JET_MoveNext或正位移的向前動作，一旦到達索引範圍的結尾，就會防止正位移。在此情況下，仍然可以使用 JetMove 搭配JET_MovePrevious或負位移來保留索引範圍。下限會發生類似的情況。

規格需求

需求	值
用戶端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
Server	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。

另請參閱

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetMove
JetSetIndexRange
JetStopService

共用方式為

JetSetIndexRange 函式