JetReadFileInstance 函数

项目
06/13/2023

适用于： Windows |Windows Server

JetReadFileInstance 函数

JetReadFileInstance 函数检索使用 JetOpenFileInstance 函数打开的文件的内容。

Windows XP： JetReadFileInstance 在 Windows XP 中引入。

    JET_ERR JET_API JetReadFileInstance(
      __in          JET_INSTANCE instance,
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcb
    );

parameters

instance

要用于特定 API 调用的实例。

请注意，对于 Windows 2000，接受此参数的 API 变体不可用，因为仅支持一个实例。在本例中隐含使用此全局实例。

对于 Windows XP 及更高版本，可以调用仅当引擎处于旧模式 (Windows 2000 兼容模式) 仅支持一个实例时，才接受此参数的 API 变体。否则，操作将失败并返回JET_errRunningInMultiInstanceMode错误。

hfFile

要读取的文件的句柄。

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

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

Pcb

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

返回值

此函数有助于返回在 Extensible Storage Engine ( ESE) API 中定义的任何JET_ERR数据类型。有关 JET 错误的详细信息，请参阅可扩展存储引擎错误和错误处理参数。

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

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

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

备注

使用已返回基础文件中的所有数据的句柄对 JetReadFileInstance 函数进行的任何调用 (例如，如果上一次调用返回的字节数少于输出缓冲区) 的大小将始终成功，但将返回零字节的数据。

应使用较大的输出缓冲区来最大化备份性能。对于特定情况，可能需要进行试验，以找出资源消耗和吞吐量之间的最佳权衡。在任何情况下，输出缓冲区都应不小于 64 KB。传递给 JetReadFileInstance 的指针必须与内存页边界对齐， (4 KB 或 8 KB) 。可以通过调用 VirtualAlloc 函数来执行此操作。

不支持使用同一文件句柄对 JetReadFileInstance 进行多个并发调用。这意味着不可能将多个缓冲区排队，以便针对同一文件进行并发读取，以实现较高的顺序吞吐量。应改用单个大型缓冲区。

如果已配置特定实例，以便启用数据库页面清理， (在系统参数) 中查看JET_paramCircularLog参数，则删除的数据将从数据库中删除，这是针对数据库文件调用 JetReadFileInstance 的副作用。

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

此外，请务必了解，在流式备份期间，通常会首先检测到数据损坏情况。这是因为流式备份是唯一定期扫描数据库文件的每一页的过程。由于备份检索到的数据量和检索数据的速度，流式备份可能是检测间歇性数据损坏错误所表现出的硬件故障早期迹象的第一个过程。

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

要求

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

另请参阅

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
系统参数

JetReadFileInstance 函数