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
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

pvBookmark

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

cbBookmark

pvBookmark所指向的緩衝區大小。

azureActual

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函式中的指定準備參數不是有效的旗標。
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	JetPrepareUpdate 是以JET_prepCancel呼叫，但游標未處於備妥狀態。
JET_errWriteConflict	尚未配置寫入鎖定的記錄取代作業，在更新時可能會遇到寫入衝突。

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

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

備註

JetSetColumn會強制執行記錄大小限制，而不是JetUpdate的一般限制。唯一的例外狀況是使用JET_bitUpdateCheckESE97Compatibility相容性旗標時。在此情況下，會檢查整個記錄，因為超過限制的個別 JetSetColumn 作業可能會由後續呼叫 JetSetColumn來補償。

如需詳細資訊，請參閱 JetUpdate 中的一節。

規格需求

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

另請參閱

JET_ERR
JET_SESID
JET_TABLEID
JetDelete
JetPrepareUpdate
JetRegisterCallback
JetRetrieveColumn
JetRetrieveColumns
JetSetColumn
JetSetColumns

共用方式為

JetUpdate2 函式