JetPrepareUpdate 函式

發行項
06/12/2023

適用于： 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 錯誤的詳細資訊，請參閱可延伸儲存引擎錯誤和錯誤處理參數。

傳回碼	Description
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	JetPrepareUpdate 是以JET_prepCancel呼叫，但游標未處於備妥狀態。

成功時，資料指標會變更為備妥狀態以供所需更新之用，或在JET_prepCancel的情況下，資料指標會還原為非備妥狀態，並捨棄任何變更。

失敗時，資料指標狀態會保持不變。如果失敗JET_errRollbackError則資料指標狀態會變更為非備妥狀態，但尚未還原所有變更。

備註

當記錄共用類型為 JET_coltypLongText 和/或 JET_coltypLongBinary 類型的資料時，插入記錄複本是重要的優化。當資料很大時，此資料會儲存在異地，而且多個記錄可以共用資料的相同實體標記法。在此情況下，可以從任一筆記錄更新資料，但這麼做會導致資料暴增，讓每個記錄都有自己的複本。您無法藉由從另一筆記錄修改來變更某筆記錄中的資料。此外，您無法透過另一筆記錄的更新來封鎖一筆記錄的更新。這是 ESE 的核心功能，稱為「記錄層級鎖定」。

JetUpdate 作業會讓資料指標保持更新備妥狀態。這是為了允許更正某些錯誤，例如錯誤的資料行值，而不需要重新建立更新狀態。這表示在所有資料指標放棄更新的情況下，都必須使用 JET_prepCancel 明確呼叫 JetPrepareUpdate 。

規格需求

需求	值
用戶端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
Server	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。

另請參閱

JET_ERR
JET_SESID
JET_TABLEID
JetRetrieveColumn
JetSetColumn
JetUpdate

共用方式為

JetPrepareUpdate 函式