JetReadFile 函数

项目
06/13/2023

适用于： Windows |Windows Server

JetReadFile 函数

JetReadFile 函数检索使用 JetOpenFile 打开的文件的内容。

    JET_ERR JET_API JetReadFile(
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcbActual
    );

parameters

hfFile

要读取的文件的句柄。

将接收文件数据的输出缓冲区。

输出缓冲区的最大大小（以字节为单位）。

印刷品

接收检索到的文件数据的实际量。

返回值

此函数返回具有以下返回代码之一的JET_ERR 数据类型。有关可能的 ESE 错误的详细信息，请参阅可扩展存储引擎错误和错误处理参数。

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBackupAbortByServer	操作失败，因为调用 JetStopService 中止了当前外部备份。此错误仅由 Windows XP 和更高版本返回。
JET_errClientRequestToStopJetService	无法完成操作，因为由于调用 JetStopService，与会话关联的实例上的所有活动都已停止。
JET_errInstanceUnavailable	无法完成该操作，因为与会话关联的实例遇到一个致命错误，该错误要求撤销对所有数据的访问以保护该数据的完整性。此错误仅由 Windows XP 和更高版本返回。
JET_errInvalidParameter	提供的其中一个参数包含意外值或包含一个值，当与另一个参数的值组合时，该值没有意义。在以下情况下，JetReadFile 可能会发生这种情况：指定的实例句柄无效。 Windows XP 和更高版本。输出缓冲区大小不是数据库页大小 (JET_paramDatabasePageSize) 的倍数。 Windows XP 和更高版本。输出缓冲区大小小于三个数据库页 (JET_paramDatabasePageSize) ，这是对指定句柄的第一次 JetReadFile 调用。 Windows XP 和更高版本。
JET_errNoBackup	操作失败，因为没有外部备份正在进行。
JET_errNotInitialized	无法完成操作，因为尚未初始化与会话关联的实例。
JET_errReadVerifyFailure	操作失败，因为从数据库文件或数据库修补程序文件读取数据库页时检测到不可恢复的数据损坏。
JET_errLogReadVerifyFailure	操作失败，因为在读取事务日志文件时检测到不可恢复的数据损坏。此错误仅由 Windows XP 和更高版本返回。
JET_errRestoreInProgress	无法完成操作，因为正在与会话关联的实例上执行还原操作。
JET_errRunningInMultiInstanceMode	操作失败，因为尝试在旧模式下使用引擎， (Windows 2000 兼容模式) 其中仅支持一个实例，但实际上已存在多个实例。
JET_errTermInProgress	无法完成操作，因为与会话关联的实例正在关闭。

成功后，文件中的下一个数据区块将被读入输出缓冲区。还将返回实际检索到的字节数。下一次读取时的文件偏移量将按此量提前。

失败时，输出缓冲区的状态未定义。失败将导致取消实例的整个备份过程。在 Windows XP 及更高版本中，如果在读取数据库文件时出错，则不会取消备份。但是，该数据库文件的备份仍将取消，相应的句柄将自动关闭。

备注

使用已返回基础文件 (（例如上一次调用）的句柄对 JetReadFile 的任何调用返回的字节数小于输出缓冲区大小) 将始终成功，但返回零字节的数据。

应使用大型输出缓冲区来最大程度地提高备份性能。对于给定的情况，可能需要进行一些试验才能在资源消耗量和吞吐量之间找到适当的权衡。在任何情况下，输出缓冲区都应不小于 64KB。

不支持使用同一文件句柄对 JetReadFile 进行多次并发调用。这意味着无法针对同一文件对多个缓冲区进行并发读取，以实现高顺序吞吐量。应改用单个大型缓冲区。

如果实例配置为启用数据库页清理， (在系统参数) 看到JET_paramZeroDatabaseDuringBackup，则删除的数据将从数据库中删除，因为对数据库文件调用 JetReadFile 会产生副作用。

了解备份和数据损坏的交互方式非常重要。如果数据库引擎在备份期间检测到数据损坏，则会使受影响数据库或整个实例的备份失败。这是一个有意识的设计决策，旨在防止数据丢失。如果数据库引擎在存在数据损坏的情况下允许备份成功，则可能会放弃较旧的未损坏备份。这很不幸，因为可以通过还原该备份并针对该数据库重播所有事务日志文件来修复实时实例上的数据损坏。此零数据丢失方案假定未启用循环日志记录， (系统参数 ) 中看到JET_paramCircularLog。

同样重要的是，当数据损坏存在时，流式备份将是最可能首先检测到它的位置。之所以如此，是因为流式备份是唯一定期扫描数据库文件的每一页的过程。流式备份也可能是检测硬件故障的早期迹象的第一个过程，例如间歇性数据损坏错误。这是因为备份检索到的数据量以及检索数据的速度。

数据库引擎通过使用块校验和检测到数据损坏。这些校验和是在写入数据库页之前设置的，并在读取数据库页时进行验证。此方案使数据库引擎能够确定数据在某个时间点已损坏，但不允许数据库引擎确定该损坏的来源。从历史上看，此类损坏的主要原因一直来自数据库引擎本身以外的其他来源。

要求

要求	值
客户端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
服务器	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。

另请参阅

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
系统参数

JetReadFile 函数