JetUpdate 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetUpdate 函式

JetUpdate函式會執行更新作業，包括將新資料列插入資料表或更新現有的資料列。刪除資料表資料列是藉由呼叫 JetDelete來執行。

JetUpdate 是執行插入或更新的最後一個步驟。更新是從呼叫 JetPrepareUpdate 開始，然後藉由呼叫 JetSetColumn 或 JetSetColumns 一或多次來設定記錄狀態。最後， 會呼叫 JetUpdate 來完成更新作業。索引只會由JetUpdate或JetUpdate2更新，而不會在JetSetColumn 或 JetSetColumns期間更新。

    JET_ERR JET_API JetUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbBookmark,
      __out_opt     unsigned long* pcbActual
    );

參數

sesid

要用於這個呼叫的會話。

tableid

要用於這個呼叫的資料指標。

pvBookmark

已插入資料列之傳回書簽的指標。

cbBookmark

pvBookmark指向的緩衝區大小。

sqlActual

pvBookmark中傳回之插入資料列之書簽的傳回大小。

傳回值

此函式會傳回具有下列其中一個傳回碼的 JET_ERR 資料類型。如需可能 ESE 錯誤的詳細資訊，請參閱可延伸儲存引擎錯誤和錯誤處理參數。

傳回碼	描述
JET_errSuccess	作業已成功完成。
JET_errBufferTooSmall	記錄書簽的指定緩衝區不夠大，無法儲存記錄書簽。
JET_errClientRequestToStopJetService	無法完成作業，因為與會話相關聯之實例上的所有活動因 JetStopService呼叫而停止。
JET_errColumnIllegalNull	與JET_errNullInvalid相同。
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_errTransReadOnly	在唯讀交易的範圍內嘗試更新不合法。唯讀交易是一項交易，其已使用對 JetBeginTransaction2 的呼叫搭配 JET_bitTransactionReadOnly 來啟動。 Windowsxp：此錯誤只會由 Windows XP 和更新版本傳回。
JET_errUpdateNotPrepared	JetPrepareUpdate 是以JET_prepCancel呼叫，但游標未處於備妥狀態。
JET_errVersionStoreOutOfMemory	作業失敗，因為記憶體不足，無法保留有關更新的交易資訊。
JET_errWriteConflict	另一個會話先前已鎖定記錄以進行更新。此會話嘗試的更新將會失敗。

成功時，資料指標上的開啟更新作業已完成。如果為數據表定義自動遞增資料行，則會針對插入的記錄設定此值。如果為數據表定義版本資料行，則會針對新插入的記錄初始化其值，或在每次取代記錄時遞增。所有索引，包括叢集和非叢集索引都會更新。

失敗時，不會對資料庫進行任何變更。在插入和取代回呼函式之前可能已經呼叫，但在插入和取代回呼之後，將不會呼叫，因為後者無法造成更新失敗。游標複製緩衝區會保留其備妥狀態，以便有機會以累加方式更正造成錯誤的問題，然後重試更新作業。

備註

回呼函式可以註冊為在插入之前或之後呼叫，以及在更新之前或之後呼叫。

JetSetColumn會強制執行記錄大小限制，而不是JetUpdate的一般限制。

請務必瞭解在單一交易內執行大量更新作業的影響。資料庫的每個更新都必須由版本存放區中的資料庫引擎追蹤。版本存放區會保存資料庫中每個記錄或索引項目目之所有不同版本的即時記錄，可供所有使用中的交易看到。這些版本可用來支援資料庫引擎所使用的多重版本並行控制，以支援使用快照集隔離的交易。一旦資料庫引擎耗盡用來儲存這些版本的資源，它就無法再接受進一步的變更，直到某些交易結束以允許回收這些資源為止。當引擎處於此狀態時，所有更新都會因為JET_errVersionStoreOutOfMemory而失敗。您可以使用 JetSetSystemParameter 搭配 JET_paramMaxVerPages 和 JET_paramGlobalMinVerPages來控制可供資料庫引擎儲存這些版本的資源。

規格需求

需求	值
用戶端	需要 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
JetDelete
JetPrepareUpdate
JetRegisterCallback
JetRetrieveColumn
JetRetrieveColumns
JetSetColumn
JetSetColumns
JetSetSystemParameter
系統參數

共用方式為

JetUpdate 函式