Last modified: January 09, 2012
Applies to: Windows | Windows Server
The JetEscrowUpdate function performs an atomic addition operation on one column. This function allows multiple sessions to update the same record concurrently without conflicts.
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 );
The session to use for this call.
The cursor to use for this call.
The columnid of the column to be updated.
A pointer to a buffer containing the addend for the column.
The size of the buffer containing the addend.
The output buffer that will receive the current value of the column as stored in the database (versioning is ignored).
The maximum size of the output buffer that will receive the current value of the column. Currently only JET_coltypLong is supported, so the buffer must either be 4 bytes or 0 bytes in length. If pvOld is NULL then cbOldMax should be 0.
Receives the actual amount of raw value data received in the output buffer.
A group of bits specifying zero or more of the following options.
Even if the session performing the escrow update has its transaction rollback this update will not be undone. Note that as the log records may not be flushed to disk, recent escrow updates done with this flag may be lost if there is a crash.
This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.
The operation completed successfully.
The cursor has an update prepared with JetPrepareUpdate.
It is not possible to complete the operation because all activity on the instance associated with the session has ceased as a result of a call to JetStopService.
It is not possible to complete the operation because the instance associated with the session has encountered a fatal error that requires that access to all data be revoked to protect the integrity of that data. This error will only be returned by Windows XP and later releases.
An invalid buffer size has been passed in. Currently only JET_coltypLong is supported, so the buffer must be 4 bytes.
An invalid column has been specified. The column must be created with JET_bitColumnEscrowUpdate specified. Only fixed columns of JET_coltypLong can be specified as escrow updateable.
Cursor must be on a record in order to update a column.
Escrow updates can only be performed by sessions in a transaction.
It is not possible to complete the operation because the instance associated with the session has not been initialized yet.
Cursor cannot be read only and update a record.
It is not possible to complete the operation because a restore operation is in progress on the instance associated with the session.
The same session cannot be used from more than one thread at the same time. This error will only be returned by Windows XP and later releases.
It is not possible to complete the operation because the instance associated with the session is being shut down.
Session must have write permissions to update a record.
The error returned when a conflicting update is requested.
Normally, if two sessions attempt to update a record simultaneously, the second session will receive a JET_errWriteConflict error unless the sessions are completely serialized. To serialize two sessions that update the same record, the second session must start its transaction after the first transaction commits its transaction. See JetBeginTransaction for more information.
Multiple columns in the same record can be escrow updated. The updates do not affect each other.
Only JetEscrowUpdate operations are compatible with each other. If two different sessions try to prepare updates or delete the same record, a write conflict will be generated.
Escrow operations are versioned and are undone using JetRollback (unless JET_bitEscrowNoRollback was specified). JetEscrowUpdate returns the raw value of the column stored in the database, because an application may want to perform a special action when a sentinel value is hit. JetRetrieveColumn returns the correctly versioned view of the column, ignoring updates made by concurrent sessions.
Given two sessions operating on the same column of the same record, we can see how this works. Assume the column starts with a value of 0.
Replacing a record in the same transaction that performs escrow updates to a record is not recommended. In particular, if an update on a record is prepared with one JET_TABLEID and a different JET_TABLEID is used to escrow update the record then the escrow updated will be lost when JetUpdate is called. This happens even if the escrow column was not set during the update.
When an escrow updateable column has a value of zero, special behavior can be triggered. This behavior only happens if a JetEscrowUpdate operation causes the column to have a value of zero. The action does not happen immediately, but occurs sometime after the transaction which caused the column to have a value of zero commits. The column must still have a value of zero (that is, if no other sessions have modified the column). If the column was created with JET_bitColumnDeleteOnZero, the record containing the column will be deleted. If the column was created with JET_bitColumnFinalize then a callback will be issued. A crash may cause these actions not to happen, but online maintenance (using the JetDefragment function) will correctly redo the actions.
Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Declared in Esent.h.