JetDefragment2 函式

發行項
06/12/2023

適用于： Windows |Windows Server

JetDefragment2 函式

JetDefragment2函式會啟動和停止資料庫重組工作，以改善資料庫內的資料組織，並提供回呼參數來報告重組的進度。這可藉由在資料庫內更有效率地使用現有的磁片配置來限制資料庫成長。它也可以藉由確保資料更緊密地封裝來減少工作集。最後，它可藉由透過更好的資料組織加速常見作業，以改善應用程式效能。

Windows XP：JetDefragment2 是在 Windows XP 中引進。

JetDefragment2 也包含回呼函式參數，用來報告重組程式的進度。

資料庫重組是線上作業，不會中斷一般資料庫活動，例如查詢作業或資料更新。 JetDefragment2 也不會複製所有現有的資料。相反地，它會就地重組資料庫。最後， JetDefragment2 會復原內部資料庫空間以供重複使用，但不會釋出過多空間給作業系統檔案系統。

產生的資料格式可能會更有效率，但通常不是最佳格式。重組僅限於釋放資料庫頁面以供重複使用，其中包含已以邏輯方式刪除的資料。重組也可讓資料庫頁面在某些情況下重複使用，方法是合併兩個頁面的資料，使其可以容納在單一頁面上。

這項作業與 JetCompact 不同，它會將唯讀資料庫的複本變成高度最佳形式。

JET_ERR JET_API JetDefragment2(
  __in          JET_SESID sesid,
  __in          JET_DBID dbid,
  __in          JET_PCSTR szTableName,
  __out_opt     unsigned long* pcPasses,
  __out_opt     unsigned long* pcSeconds,
  __in          JET_CALLBACK callback,
  __in          JET_GRBIT grbit
);

參數

sesid

要用於這個呼叫的會話。

dbid

要重組的資料庫。

szTableName

有時候需要 szTableName ，有時會禁止：

grbit	szTableName
`JET_bitDefragmentBTreeBatch`	必須是 `NULL`。
`JET_bitDefragmentBTree`	指定要重組的資料表/BTree 名稱。
其他	必須是 `NULL`。

系統會針對指定資料庫識別碼所描述的整個資料庫執行重組。

pcPasses

啟動線上重組工作時，這個選擇性輸入參數會設定重組傳遞的最大數目。停止線上重組工作時，這個選擇性輸出緩衝區會設定為執行的傳遞數目。

當此參數設定為 Null 時，線上重組傳遞的數目不受限制。

pcSeconds

啟動線上重組工作時，這個選擇性的輸入參數會設定重組的最大時間。停止線上重組工作時，這個選擇性輸出緩衝區會設定為用於重組的時間長度。

當此參數設定為 Null 或 pcSeconds 指向負值時，重組的時間上限為無限制。

回檔

重組會定期呼叫的回呼函式，以報告進度。

grbit	szTableName
`JET_bitDefragmentBTreeBatch`	必須是 `NULL`。
`JET_bitDefragmentBTree`	必須是 `NULL`。
其他	選擇性。

grbit

指定下列零個或多個選項的位群組。

值	意義
JET_bitDefragmentAvailSpaceTreesOnly	此選項可用來重組 ESE 資料庫空間配置的可用空間部分。資料庫空間分成兩種類型：擁有的空間和可用空間。擁有的空間會分別配置給資料表或索引，而可用空間已準備好用於資料表或索引。可用空間在行為上更為動態，而且需要線上重組比擁有的空間或資料表或索引資料還要多。
JET_bitDefragmentBatchStart	此選項可用來啟動新的重組工作。
JET_bitDefragmentBatchStop	此選項可用來停止現有的已啟動重組工作。
JET_bitDefragmentBTree	此選項是用來重組 szTableName 所指定的 B 型樹狀結構。
JET_bitDefragmentBTreeBatch	此選項是用來在整個資料庫上呼叫 OLD2。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errClientRequestToStopJetService	因為與會話相關聯的實例上的所有活動因為對 JetStopService的呼叫而停止，所以無法完成作業。
JET_errDatabaseFileReadOnly	選擇進行重組的資料庫是唯讀的，而且無法以任何方式更新，包括重組。
JET_errDistributedTransactionAlreadyPreparedToCommit	指定的會話處於準備好認可狀態，而且在認可或回復目前交易之前，無法開始新的更新。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，要求撤銷所有資料的存取權以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidDatabaseId	指定的資料庫識別碼與實例中的已知資料庫不符。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errRestoreInProgress	因為與會話相關聯的實例上正在進行還原作業，所以無法完成作業。
JET_errSessionSharingViolation	同一個會話不能同時用於多個執行緒。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	因為與會話相關聯的實例正在關閉，所以無法完成作業。
JET_errTransReadOnly	指定的會話只有唯讀許可權，而且無法啟動可執行更新的工作，包括重組。
JET_errVersionStoreOutOfMemory	當版本存放區設定的大小不足，無法保存所有未完成的更新時，就會發生此錯誤。
JET_wrnDefragAlreadyRunning	已傳遞JET_bitDefragmentBatchStart選項，但重組工作已在指定資料庫上執行重組。
JET_wrnDefragNotRunning	已傳遞JET_bitDefragmentBatchStop選項，但目前未執行重組工作。

成功時，會針對具有指定選項的指定資料啟動重組工作的要求動作，或執行停止現有重組工作的動作。

失敗時，不會完成啟動或停止線上重組作業的要求動作。不會發生其他副作用。

備註

線上重組是由參數設定和此 API 控制。預設系統參數值為 JET_OnlineDefragAll，這表示已針對所有支援的資料結構啟用重組。不過，使用 JetSetSystemParameter，可以停用線上重組，或選擇性地只針對資料庫空間樹狀結構、僅限資料庫、僅串流檔案或任何這些選項的組合加以啟用。如果線上重組的系統設定是過時的設定， JetDefragment2 會將設定視為JET_OnlineDefragAll。

每個資料庫最多隻能執行一項工作。工作會在裝載 ESE 的進程中以執行緒的形式執行。

用來啟動線上重組工作的會話可以在重組工作繼續時用於資料庫作業，因為重組工作會配置自己的會話。指定的會話只會用來檢查與工作啟動會話相關聯的許可權，而且實際上不會用於重組作業本身。

規格需求

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

另請參閱

JET_ERR
JET_SESID
JetCompact
JetDefragment
JetSetSystemParameter
JetStopService

JetDefragment2 函式