大网数据广告活动
磁盘与文件系统

JetDefragment Function

· 52CE 我爱测

Learn more about: JetDefragment Function

Applies to: Windows | Windows Server

JetDefragment Function

The JetDefragment function starts and stops database defragmentation tasks that improves data organization within a database. This is done to limit database growth by using existing disk allocation more efficiently within the database. It can also reduce working set by ensuring that data is more closely packed. Lastly, it can improve application performance by speeding common operations through better data organization.

Database defragmentation is an online operation and does not interrupt regular database activity, such as query operations or data updates. JetDefragment also does not make a copy of all existing data. Instead, it defragments a database in place. Lastly, JetDefragment recovers internal database space for re-use but does not release excess space to the operating system file system.

The resulting format of the data can be much more efficient but is not generally optimal. Defragmentation is limited to releasing database pages for re-use which contain data that has already been logically deleted. Defragmentation also makes database pages available for re-use in some cases by combining data from two pages when it can fit on a single page.

This operation is different from JetCompact which makes a copy of a read-only database into a highly optimal form.

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

Parameters

sesid

The session to use for this call.

dbid

The database that will be defragmented.

szTableName

Unused parameter. Defragmentation is performed for the entire database described by the given database ID.

pcPasses

When starting an online defragmentation task, this input parameter sets the maximum number of defragmentation passes. When stopping an online defragmentation task, this output buffer is set to the number of passes performed.

When this parameter is set to NULL, the number of online defragmentation passes is unlimited.

pcSeconds

When starting an online defragmentation task, this input parameter sets the maximum time for defragmentation. When stopping an online defragmentation task, this output buffer is set to the length of time used for defragmentation.

When this parameter is set to NULL or if pcSeconds points to a negative value, the maximum time for defragmentation is unlimited.

grbit

A group of bits specifying zero or more of the following options.

Value Meaning
JET_bitDefragmentAvailSpaceTreesOnly Defragments the available space portion of ESE database space allocation. Database space is divided into two types, owned space and available space. Owned space is allocated to a table or index while available space is ready for use within the table or index, respectively. Available space is much more dynamic in behavior and requires on-line defragmentation more so than owned space or table or index data.
JET_bitDefragmentBatchStart Starts a new defragmentation task.
JET_bitDefragmentBatchStop Stops a defragmentation task.

Return Value

This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.

Return code Description
JET_errSuccess The operation completed successfully.
JET_errClientRequestToStopJetService It is not possible to complete the operation because all activity on the instance associated with the session has ceased as a result of a call to <a href="gg269240(v=exchg.10).md">JetStopService</a>.
JET_errDatabaseFileReadOnly The database chosen for defragmentation is read only and cannot be updated in any way, including defragmentation.
JET_errDistributedTransactionAlreadyPreparedToCommit The given session is in the prepared to commit state, and cannot begin new updates until the current transaction is committed or rolled back.
JET_errInstanceUnavailable It is not possible to complete the operation because the instance associated with the session has encountered a fatal error that requires that access to all data be revoked to protect the integrity of that data. This error will only be returned by Windows XP and later releases.
JET_errInvalidDatabaseId The given database ID does not match a known database in the instance.
JET_errNotInitialized It is not possible to complete the operation because the instance associated with the session has not been initialized yet.
JET_errRestoreInProgress It is not possible to complete the operation because a restore operation is in progress on the instance associated with the session.
JET_errSessionSharingViolation The same session cannot be used for more than one thread at the same time. This error will only be returned by Windows XP and later releases.
JET_errTermInProgress It is not possible to complete the operation because the instance associated with the session is being shut down.
JET_errTransReadOnly The given session has read-only privileges only and cannot start a task that may perform an update, including defragmentation.
JET_errVersionStoreOutOfMemory This error will occur when the configured size of the version store is insufficient to hold all outstanding updates.
JET_wrnDefragAlreadyRunning The JET_bitDefragmentBatchStart option has been passed but a defragmentation task is already running defragmentation on the given database.
JET_wrnDefragNotRunning The JET_bitDefragmentBatchStop option has been passed, but no defragmentation task is currently running.

On success, the requested action of either starting a defragmentation task for a given data with given options is performed, or the action of stopping an existing defragmentation task is performed.

On failure, the requested action of either starting or stopping an online defragmentation job is not done. No other side effects occur.

Remarks

Online defragmentation is controlled both by a parameter setting, as well as by this API. The default system parameter value is JET_OnlineDefragAll, which means defragmentation is enabled for all supported data structures. However, using JetSetSystemParameter, it is possible to disable online defragmentation, or to selectively enable it for database space trees only, databases only, streaming files only or any combination of these options. If the system setting for online defragmentation is set to an obsolete setting, JetDefragment will treat the setting as JET_OnlineDefragAll.

There can at most be one task running for each database. The task runs as a thread in the process hosting ESE.

The session used to start the online defragmentation task can be subsequently used for database operations while the defragmentation task continues, because the defragmentation task allocates its own session. The given session is only used to check the permissions associated with the task starting session and is not actually used for the defragmentation operations themselves.

Requirements
Requirement Value
Client Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Server Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Header Declared in Esent.h.
Library Use ESENT.lib.
DLL Requires ESENT.dll.
Unicode Implemented as JetDefragmentW (Unicode) and JetDefragmentA (ANSI).
See Also

JET_ERR
JET_SESID
JetCompact
JetDefragment2
JetSetSystemParameter
JetStopService

Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.

资料来源与适用范围

资料来源
Microsoft Learn / Windows Win32 documentation
适用范围
Windows Win32 API · Source date 04/11/2016
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0 (documentation), MIT (code samples)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。