Last modified: January 09, 2012
Applies to: Windows | Windows Server
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 );
The session to use for this call.
The database that will be defragmented.
Unused parameter. Defragmentation is performed for the entire database described by the given database ID.
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.
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.
A group of bits specifying zero or more of the following options.
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.
Starts a new defragmentation task.
Stops a defragmentation task.
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.
The operation completed successfully.
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 JetStopService.
The database chosen for defragmentation is read only and cannot be updated in any way, including defragmentation.
The given session is in the prepared to commit state, and cannot begin new updates until the current transaction is committed or rolled back.
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.
The given database ID does not match a known database in the instance.
It is not possible to complete the operation because the instance associated with the session has not been initialized yet.
It is not possible to complete the operation because a restore operation is in progress on the instance associated with the session.
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.
It is not possible to complete the operation because the instance associated with the session is being shut down.
The given session has read-only privileges only and cannot start a task that may perform an update, including defragmentation.
This error will occur when the configured size of the version store is insufficient to hold all outstanding updates.
The JET_bitDefragmentBatchStart option has been passed but a defragmentation task is already running defragmentation on the given database.
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.
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.
Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Declared in Esent.h.
Implemented as JetDefragmentW (Unicode) and JetDefragmentA (ANSI).