JetDefragment2 函数

适用于:Windows |Windows服务器

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

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

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

返回代码

说明

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。

Server

需要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