JetPrepareUpdate 函数

适用于： Windows |Windows Server

JetPrepareUpdate 函数

JetPrepareUpdate 函数是执行更新的第一个操作，用于插入新记录或将现有记录替换为新值。 汇报方法是调用 JetPrepareUpdate，然后调用 JetSetColumn 或 JetSetColumns 零次或多次，最后调用 JetUpdate 以完成操作。 JetPrepareUpdate 和 JetUpdate 为更新操作设置边界，对于仅将记录的最终更新状态输入索引非常重要。 这既是更高效的，但当数据必须匹配有效状态时，这比设置列操作还要高。

有几种不同的选项用于插入或替换记录，下面将更详细地介绍这些选项。

    JET_ERR JET_API JetPrepareUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long prep
    );

参数

sesid

用于此调用的会话。

tableid

用于此调用的游标。

准备

可用于准备更新的选项，包括以下内容。

值	含义
JET_prepCancel	此标志会导致 JetPrepareUpdate 取消此游标的更新。
JET_prepInsert	此标志使游标准备插入新记录。 所有数据都初始化为记录的默认状态。 如果表具有自动递增列，则无论更新最终是成功、失败还是取消，都会为此记录分配新值。
JET_prepInsertCopy	此标志使游标准备插入现有记录的副本。 如果使用此选项，则必须有当前记录。 从当前记录复制新记录的初始状态。 以虚拟形式复制存储在记录之外的长值。
JET_prepInsertCopyDeleteOriginal	此标志使游标准备插入同一记录以及删除或原始记录。 它在主键已更改的情况下使用。
JET_prepReplace	此标志使游标准备替换当前记录。 如果表具有版本列，则版本列将设置为其序列中的下一个值。 如果此更新未完成，则记录中的版本值将不受影响。 对记录执行更新锁，以防止其他会话在此会话完成之前更新此记录。
JET_prepReplaceNoLock	此标志类似于JET_prepReplace，但不会采取任何锁定来阻止其他会话更新此记录。 相反，当此会话调用 JetUpdate 以完成更新时，可能会收到JET_errWriteConflict。

返回值

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

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errAlreadyPrepared	JetPrepareUpdate 是使用用于准备的有效标志调用的，但未JET_prepCancel并且游标已处于准备状态。
JET_errClientRequestToStopJetService	无法完成操作，因为由于调用 JetStopService，与会话关联的实例上的所有活动都已停止。
JET_errInstanceUnavailable	无法完成该操作，因为与会话关联的实例遇到一个致命错误，该错误要求撤销对所有数据的访问以保护该数据的完整性。 此错误仅由 Windows XP 和更高版本返回。
JET_errInvalidParameter	给定的准备标志不是有效的标志。
JET_errNotInitialized	无法完成操作，因为尚未初始化与会话关联的实例。
JET_errNotInTransaction	调用 JetPrepareUpdate 以替换包含 SLV 列的记录。 SLV 列。 请注意，SLV 列是一项不用于常规用途的功能。 此功能用于支持 Microsoft Exchange 基础结构，不打算在应用程序中使用。
JET_errRestoreInProgress	无法完成操作，因为正在与会话关联的实例上执行还原操作。
JET_errRollbackError	JetPrepareUpdate 是使用 JET_prepCancel 调用的，但无法回滚对类型JET_coltypLongText和/或类型JET_coltypLongBinary列所做的所有更改。
JET_errSessionSharingViolation	此标志不能与来自多个线程的同一会话同时使用。 此错误仅由 Windows XP 和更高版本返回。
JET_errTermInProgress	无法完成操作，因为与会话关联的实例正在关闭。
JET_errUpdateNotPrepared	使用 JET_prepCancel调用 JetPrepareUpdate，但光标未处于准备状态。

成功后，游标将更改为准备状态以进行所需更新，或者在JET_prepCancel的情况下，游标将还原到未准备的状态，并放弃任何更改。

失败时，游标状态保持不变。 如果失败JET_errRollbackError则游标状态将更改为非准备状态，但并非所有更改都已还原。

备注

当记录共享JET_coltypLongText和/或JET_coltypLongBinary类型的数据时，插入记录的副本是一项重要的优化。 此数据在较大时存储在记录外，并且多个记录可以共享数据的相同物理表示形式。 在这种情况下，可以从任一记录更新数据，但这样做会导致数据突发，使每个记录都有其自己的副本。 无法通过修改另一条记录来更改一条记录中的数据。 此外，无法通过更新另一条记录来阻止一个记录的更新。 这是 ESE 的核心功能，称为记录级别锁定。

失败的 JetUpdate 操作会使游标处于更新准备状态。 这是为了允许更正某些错误（如错误的列值），而无需重新创建更新状态。 这意味着，在游标放弃更新的所有情况下，它都必须使用 JET_prepCancel 显式调用 JetPrepareUpdate 。

要求

要求	值
客户端	需要 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_SESID
JET_TABLEID
JetRetrieveColumn
JetSetColumn
JetUpdate