JetUpdate2 函数

项目
06/13/2023

适用于： Windows |Windows Server

JetUpdate2 函数

JetUpdate2 函数执行更新操作，包括将新行插入表中或更新现有行。此函数包含可在执行更新时设置的 grbit 选项列表。删除表行是通过调用 JetDelete 来执行的。

Windows Server 2003：JetUpdate2 在 Windows Server 2003 中引入。

JetUpdate2 是执行插入或更新的最后一步。通过调用 JetPrepareUpdate 开始更新，然后调用 JetSetColumn 或 JetSetColumns 一次或多次设置记录状态。最后，调用 JetUpdate2 以完成更新操作。索引仅由 JetUpdate 或 JetUpdate2 更新，而不是在 JetSetColumn 或 JetSetColumns 期间更新。

    JET_ERR JET_API JetUpdate2(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbBookmark,
      __out_opt     unsigned long* pcbActual,
      __in            const JET_GRBIT grbit
    );

parameters

sesid

用于此调用的会话。

tableid

用于此调用的游标。

pvBookmark

指向插入行的返回书签的指针。

cbBookmark

pvBookmark 指向的缓冲区的大小。

印刷品

pvBookmark 中返回的插入行的书签的返回大小。

grbit

包含用于此调用的选项的一组位，其中包括以下零个或多个内容。

值	含义
JET_bitUpdateCheckESE97Compatibility	如果 Windows 2000 版本的 ESE 中无法进行更新，则此标志会导致更新返回错误，该更新在每条记录中强制实施的最大多值列实例数比更高版本的 ESE 少。这一点仅对于希望在 Windows 2000 上托管的应用程序与 Windows Server 2003 上托管的应用程序或更高版本的 ESE 之间复制数据的应用程序非常重要。对于大多数应用程序来说，它不应该是必需的。

值

含义

JET_bitUpdateCheckESE97Compatibility

如果 Windows 2000 版本的 ESE 中无法进行更新，则此标志会导致更新返回错误，该更新在每条记录中强制实施的最大多值列实例数比更高版本的 ESE 少。这一点仅对于希望在 Windows 2000 上托管的应用程序与 Windows Server 2003 上托管的应用程序或更高版本的 ESE 之间复制数据的应用程序非常重要。对于大多数应用程序来说，它不应该是必需的。

返回值

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

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBufferTooSmall	记录书签的给定缓冲区不够大，无法存储记录书签。
JET_errClientRequestToStopJetService	无法完成操作，因为由于调用 JetStopService，与会话关联的实例上的所有活动都已停止。
JET_errDiskFull	更新操作需要数据库文件增长或日志文件分配，但数据库文件或日志系列所在的磁盘驱动器已满。或者，数据库文件位于 FAT32 格式的卷上，并且数据库文件已经是 4GBytes（FAT32 的每个文件限制）。
JET_errInstanceUnavailable	无法完成该操作，因为与会话关联的实例遇到一个致命错误，该错误要求撤销对所有数据的访问以保护该数据的完整性。 Windowsxp：此错误仅由 Windows XP 和更高版本返回。
JET_errInvalidParameter	JetPrepareUpdate 函数中的给定 prep 参数不是有效的标志。
JET_errKeyDuplicate	此记录的索引键是表中已有的另一条记录的另一个索引键的副本，索引不允许重复。
JET_errKeyTruncated	插入或更新的记录具有一个或多个索引，生成的键将超过允许的最大大小。因此，操作无法阻止密钥截断。
JET_errMultiValuedIndexViolation	插入或更新的记录具有索引多值列，其中两个或更多值在为索引设置的最大长度键大小内相同。因此，该记录在索引中具有两个无效的相同条目。
JET_errNotInitialized	无法完成操作，因为尚未初始化与会话关联的实例。
JET_errNullInvalid	要插入的记录中的一个或多个列或处于正在替换的记录的更新状态的列为 NULL ，这违反了这些列的定义约束。
JET_errNullKeyDisallowed	定义一个或多个索引以不允许 NULL 键，替换的记录的插入或更新状态违反此定义的约束。
JET_errRecordPrimaryChanged	记录替换操作已更新主键。必须通过删除现有记录并插入具有所需数据的新记录来完成对主键列的汇报。
JET_errRestoreInProgress	无法完成操作，因为正在与会话关联的实例上执行还原操作。
JET_errSessionSharingViolation	同一会话不能同时用于多个线程。 Windowsxp：此错误仅由 Windows XP 和更高版本返回。
JET_errTermInProgress	无法完成操作，因为与会话关联的实例正在关闭。
JET_errUpdateNotPrepared	使用 JET_prepCancel调用 JetPrepareUpdate，但光标未处于准备状态。
JET_errWriteConflict	尚未为其分配写入锁的记录替换操作在更新时可能会遇到写入冲突。

成功后，将完成游标上的打开更新操作。如果为表定义了自动递增列，则为插入的记录设置此值。如果为表定义了版本列，则会为新插入的记录初始化其值，或在每次替换记录时递增。所有索引（包括聚集索引和非聚集索引）都会更新。

发生故障时，不会对数据库进行任何更改。插入前和替换前的回调函数可能已调用，但插入后和替换后回调不会调用，因为后者不会导致更新失败。游标复制缓冲区将保持其准备状态，以便有机会以增量方式更正导致错误的问题并重试更新操作。

备注

记录大小限制由 JetSetColumn 强制执行，通常由 JetUpdate 强制执行。唯一的例外是使用JET_bitUpdateCheckESE97Compatibility兼容性标志。在这种情况下，将检查整个记录，因为超出限制的单个 JetSetColumn 操作可以通过后续调用 JetSetColumn 进行补偿。

有关详细信息，请参阅 JetUpdate 中的“备注”部分。

要求

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

另请参阅

JET_ERR
JET_SESID
JET_TABLEID
JetDelete
JetPrepareUpdate
JetRegisterCallback
JetRetrieveColumn
JetRetrieveColumns
JetSetColumn
JetSetColumns

JetUpdate2 函数