JetSetCurrentIndex3 函式

發行項
06/12/2023

適用于： Windows |Windows Server

JetSetCurrentIndex3 函式

JetSetCurrentIndex3函式可用來設定資料指標的目前索引。資料指標的目前索引會定義該資料指標可以看到哪些記錄，以及要用來公開這些記錄的索引項目目集來顯示它們的順序。

    JET_ERR JET_API JetSetCurrentIndex3(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

szIndexName

要為數據指標選取的索引名稱。

如果此參數為 Null 或空字串，則會選取叢集索引。如果為數據表定義主索引，則會選取該索引，因為它與叢集索引相同。如果未定義資料表的主要索引，則會選取循序索引。循序索引沒有索引定義。如需詳細資訊，請參閱 JetCreateIndex 。

如果 pindexid 不是 Null，則會忽略索引名稱，並依索引識別碼選取索引。

grbit

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

值	意義
JET_bitMoveFirst	此選項表示游標應該放在指定索引的第一個專案上。如果要選取叢集索引， (主要索引或循序索引) ，而且目前的索引是次要索引，則會假設JET_bitMoveFirst。如果選取目前的索引，則會忽略此選項，而且不會變更游標位置。
JET_bitNoMove	此選項表示游標應該放在新索引的索引項目目上，該索引項目目對應至與舊索引上資料指標目前位置之索引項目相關聯的記錄。如果新索引的定義至少包含一個多重值索引鍵資料行，則目的地索引項目目模棱兩可。在此情況下，會使用指定的 itagSequence 來選取哪一個最重要多重值索引鍵資料行的多重值用來定位資料指標。只有在多個多重值索引鍵資料行的情況下，才需要傳遞單一 itagSequence ，因為引擎只會針對最重要的多重值索引鍵資料行展開所有值。如需詳細資訊，請參閱 JetCreateIndex 。如果指定JET_bitMoveFirst，則會忽略此選項。如果選取目前的索引，則會忽略此選項，而且不會變更游標位置。當此參數不存在時，其值會假設為JET_bitMoveFirst。

值

意義

JET_bitMoveFirst

此選項表示游標應該放在指定索引的第一個專案上。如果要選取叢集索引， (主要索引或循序索引) ，而且目前的索引是次要索引，則會假設JET_bitMoveFirst。如果選取目前的索引，則會忽略此選項，而且不會變更游標位置。

JET_bitNoMove

此選項表示游標應該放在新索引的索引項目目上，該索引項目目對應至與舊索引上資料指標目前位置之索引項目相關聯的記錄。

如果新索引的定義至少包含一個多重值索引鍵資料行，則目的地索引項目目模棱兩可。在此情況下，會使用指定的 itagSequence 來選取哪一個最重要多重值索引鍵資料行的多重值用來定位資料指標。只有在多個多重值索引鍵資料行的情況下，才需要傳遞單一 itagSequence ，因為引擎只會針對最重要的多重值索引鍵資料行展開所有值。如需詳細資訊，請參閱 JetCreateIndex 。

如果指定JET_bitMoveFirst，則會忽略此選項。

如果選取目前的索引，則會忽略此選項，而且不會變更游標位置。當此參數不存在時，其值會假設為JET_bitMoveFirst。

itagSequence

多重值資料行值的序號，用來將游標放在新索引上。

此參數只能與JET_bitNoMove搭配使用。如需詳細資訊，請參閱此選項的描述。

當此參數不存在或設定為零時，其值會假設為 1。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errBadItagSequence	系統會使用 [JET_bitNoMove] 選項選取次要索引，而且新索引定義中第一個多重值索引鍵資料行的值與指定的序號相對應。
JET_errClientRequestToStopJetService	無法完成作業，因為與會話相關聯之實例上的所有活動因 JetStopService呼叫而停止。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，需要撤銷所有資料的存取權，以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidIndexId	索引識別碼的內容無效或已過期，必須重新整理。當下列情況時，JetSetCurrentIndex3 可能會發生此問題： pindexid-cbStruct > 不是 Windows Server 2003 和更新版本) 的預期 (大小。自擷取索引識別碼之後，引擎已經關閉。參考包含對應索引識別碼之索引的所有資料指標都已經關閉，而且引擎已從架構快取收回該索引的定義。索引識別碼正與在錯誤資料表上開啟的資料指標搭配使用。索引已卸載，或尚未對會話顯示。
JET_errInvalidName	其中一個指定的物件名稱無效。所有物件名稱都必須符合相同的規則集。這些規則如下：物件名稱必須由 ASCII 字元組成。物件名稱長度必須至少為一個字元。物件名稱長度不能超過 JET_cbNameMost (64) 個字元。物件名稱開頭不一定是空格。物件名稱不能包含透過 0x1F) (0x00 ASCII 控制字元。物件名稱不能包含驚嘆號 (！) 、句號 (.) 、左括弧 ([) ]或右括弧 (]) 字元。一旦驗證之後，只有在物件名稱使用任何) 時，字串的第一個空格才會 (部分。這實際上表示物件名稱不能包含空格。
JET_errInvalidParameter	提供的其中一個參數包含非預期的值，或包含與另一個參數的值結合時沒有意義的值。當pindexid不是 Null，而 pindexid-cbStruct > 不是 Windows XP 和舊版) 的預期大小 (時，JetSetCurrentIndex3就會發生此情況。
JET_errNoCurrentRecord	系統會使用 [JET_bitNoMove] 選項選取次要索引，而且新索引中沒有索引項目對應至舊索引上資料指標目前位置上與索引項目相關聯的記錄。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errOutOfCursors	引擎已耗盡其用來開啟資料指標的資源集區。您可以使用 JET_paramMaxCursors控制隨時可開啟的資料指標數目上限。如需詳細資訊，請參閱 JetSetSystemParameter 。當已選取次要索引，且引擎無法開啟內部資料指標以使用該索引時， JetSetCurrentIndex3 可能會發生這種情況。
JET_errRestoreInProgress	無法完成作業，因為與會話相關聯的實例上正在進行還原作業。
JET_errSessionSharingViolation	同一個會話不能同時用於一個以上的執行緒。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	無法完成作業，因為與會話相關聯的實例正在關閉。

成功時，資料指標的目前索引會設定為要求的索引。根據要求之索引的索引定義，現在可以使用 JetSeek 來尋找索引項目目。您也可以依照該索引定義所指定的順序，使用 JetMove 列舉索引項目目。游標的目前位置會設定為索引 (JET_bitMoveFirst) 上的第一個索引項目目，或設定為與舊索引 (JET_bitNoMove) 上資料指標目前位置相關的特定索引項目目。不會變更資料庫狀態。

失敗時，資料指標的目前索引和目前位置處於未定義狀態。不會變更資料庫狀態。

備註

如果索引識別碼提示過時，API 只會失敗。在此情況下，索引的文字名稱沒有後援，如同預期一樣。此後援必須由 API 的呼叫端手動完成。

規格需求

需求	值
用戶端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
Server	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。
Unicode	實作為 JetSetCurrentIndex3W (Unicode) 和 JetSetCurrentIndex3A (ANSI) 。

另請參閱

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

共用方式為

JetSetCurrentIndex3 函式