JetDefragment2 函数

项目
06/13/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
);

parameters

sesid

用于此调用的会话。

dbid

要进行碎片整理的数据库。

szTableName

有时需要 szTableName ，有时是禁止的：

grbit	szTableName
`JET_bitDefragmentBTreeBatch`	必须是 `NULL`。
`JET_bitDefragmentBTree`	指定要进行碎片整理的表/BTree 的名称。
其他	必须是 `NULL`。

对给定数据库 ID 描述的整个数据库执行碎片整理。

pcPasses

启动联机碎片整理任务时，此可选输入参数设置碎片整理传递的最大次数。停止联机碎片整理任务时，此可选输出缓冲区设置为执行的传递数。

当此参数设置为 NULL 时，联机碎片整理过程的数量不受限制。

pcSeconds

启动联机碎片整理任务时，此可选输入参数设置重整的最长时间。停止联机碎片整理任务时，此可选输出缓冲区设置为用于碎片整理的时间长度。

如果此参数设置为 NULL，或者 如果 pcSeconds 指向负值，则重整的最长时间不受限制。

回调 (callback)

碎片整理定期调用以报告进度的回调函数。

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 错误的详细信息，请参阅可扩展存储引擎错误和错误处理参数。

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errClientRequestToStopJetService	无法完成操作，因为与会话关联的实例上的所有活动都因调用 JetStopService 而停止。
JET_errDatabaseFileReadOnly	为碎片整理选择的数据库是只读的，不能以任何方式更新，包括碎片整理。
JET_errDistributedTransactionAlreadyPreparedToCommit	给定会话处于准备提交状态，在提交或回滚当前事务之前无法开始新的更新。
JET_errInstanceUnavailable	无法完成操作，因为与会话关联的实例遇到严重错误，要求撤销对所有数据的访问权限以保护该数据的完整性。此错误仅由 Windows XP 及更高版本返回。
JET_errInvalidDatabaseId	给定的数据库 ID 与实例中的已知数据库不匹配。
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。
服务器	需要 Windows Server 2008 或 Windows Server 2003。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。
Unicode	实现为 JetDefragment2W (Unicode) 和 JetDefragment2A (ANSI) 。

另请参阅

JET_ERR
JET_SESID
JetCompact
JetDefragment
JetSetSystemParameter
JetStopService

JetDefragment2 函数