JetEscrowUpdate 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetEscrowUpdate 函式

JetEscrowUpdate函式會在一個資料行上執行不可部分完成的加法運算。此函式允許多個會話同時更新相同的記錄，而不會發生衝突。

    JET_ERR JET_API JetEscrowUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in          void* pv,
      __in          unsigned long cbMax,
      __out_opt     void* pvOld,
      __in          unsigned long cbOldMax,
      __out_opt     unsigned long* pcbOldActual,
      __in          JET_GRBIT grbit
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

columnid

要更新之資料行的 columnid 。

光伏

緩衝區的指標，其中包含資料行的附加元件。

cbMax

包含附加元件的緩衝區大小。

pvOld

) 會忽略儲存在資料庫 (版本設定中所儲存資料行目前值的輸出緩衝區。

cbOldMax

將接收資料行目前值的輸出緩衝區大小上限。目前僅支援JET_coltypLong，因此緩衝區長度必須為 4 個位元組或 0 個位元組。如果 pvOld 為 Null， 則 cbOldMax 應為 0。

sqlOldActual

接收輸出緩衝區中所接收之原始值資料的實際數量。

grbit

指定下列選項之零或多個位群組。

值	意義
JET_bitEscrowNoRollback	即使執行委付更新的會話具有其交易復原，此更新也不會復原。請注意，由於記錄檔記錄可能不會排清到磁片，因此如果當機，使用這個旗標完成的最新委付更新可能會遺失。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errAlreadyPrepared	資料指標具有使用 JetPrepareUpdate 準備的更新。
JET_errClientRequestToStopJetService	無法完成作業，因為與會話相關聯之實例上的所有活動因 JetStopService呼叫而停止。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，需要撤銷所有資料的存取權，以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidBufferSize	已傳入不正確緩衝區大小。目前僅支援JET_coltypLong，因此緩衝區必須是 4 個位元組。
JET_errInvalidOperation	已指定不正確資料行。必須以指定的JET_bitColumnEscrowUpdate建立資料行。只有固定JET_coltypLong資料行可以指定為可委付更新。
JET_errNoCurrentRecord	資料指標必須位於記錄上，才能更新資料行。
JET_errNotInTransaction	委付更新只能由交易中的會話執行。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errPermissionDenied	資料指標不可為唯讀，並更新記錄。
JET_errRestoreInProgress	無法完成作業，因為與會話相關聯的實例上正在進行還原作業。
JET_errSessionSharingViolation	同一個會話不能同時從一個以上的執行緒使用。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	無法完成作業，因為與會話相關聯的實例正在關閉。
JET_errTransReadOnly	會話必須具有可更新記錄的寫入權限。
JET_errWriteConflict	要求衝突更新時傳回的錯誤。

備註

一般而言，如果兩個會話嘗試同時更新記錄，除非會話已完全序列化，否則第二個會話會收到JET_errWriteConflict錯誤。若要序列化更新相同記錄的兩個會話，第二個會話必須在第一筆交易認可交易之後啟動其交易。如需詳細資訊，請參閱 JetBeginTransaction 。

同一筆記錄中的多個資料行可以委付更新。更新不會影響彼此。

只有 JetEscrowUpdate 作業彼此相容。如果兩個不同的會話嘗試準備更新或刪除相同的記錄，將會產生寫入衝突。

		會話 B JetEscrowUpdate	JetPrepareUpdate	JetDelete
	JetEscrowUpdate	JET_errSuccess	JET_errWriteConflict	JET_errWriteConflict
	JetUpdate	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict
會話 A	JetDelete	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict

除非) 指定了JET_bitEscrowNoRollback，否則會使用 JetRollback (來復原委付作業。 JetEscrowUpdate 會傳回儲存在資料庫中之資料行的原始值，因為當到達 sentinel 值時，應用程式可能會想要執行特殊動作。 JetRetrieveColumn 會傳回資料行正確設定版本的檢視，忽略並行會話所做的更新。

假設在相同記錄的相同資料行上操作兩個會話，我們可以看到其運作方式。假設資料行開頭為 0。

工作階段	作業	預存值	傳回值
A	JetBeginTransation
A	JetBeginTransation		0
A	JetEscrowUpdate (4)	4	0
A	JetRetrieveColumn		4
B	JetBeginTransaction
B	JetRetrieveColumn		0
B	JetEscrowUpdate (3)	7	4
B	JetRetrieveColumn		3
A	JetEscrowUpdate (2)	9	7
A	JetEscrowUpdate (-7)	2	9
B	JetRetrieveColumn		3
A	JetRetrieveColumn		-1
B	JetRollback	-1
A	JetRetrieveColumn		-1

不建議在對記錄執行委付更新的相同交易中取代記錄。特別是，如果記錄上的更新已備妥一個JET_TABLEID ，而使用不同的 JET_TABLEID 來委付更新記錄，則會在呼叫 JetUpdate 時遺失更新的委付。即使更新期間未設定委付資料行，也會發生這種情況。

當可委付可更新的資料行值為零時，可以觸發特殊行為。只有當 JetEscrowUpdate 作業造成資料行值為零時，才會發生此行為。動作不會立即發生，但在導致資料行具有零個認可值的交易之後發生。如果沒有任何其他會話修改資料行) ，資料行仍必須具有零 (值。如果使用 JET_bitColumnDeleteOnZero 建立資料行，將會刪除包含該資料行的記錄。如果使用 JET_bitColumnFinalize 建立資料行，則會發出回呼。當機可能會導致這些動作不發生，但使用 JetDefragment 函式的線上維護 (，) 會正確地重做動作。

規格需求

需求	值
用戶端	需要 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_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction
JetDefragment
JetPrepareUpdate
JetRetrieveColumn
JetRollback
JetStopService
JetUpdate

共用方式為

JetEscrowUpdate 函式