Функция JetEscrowUpdate

Применимо к: 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 обновляемого столбца.

Pv

Указатель на буфер, содержащий надстройку для столбца.

cbMax

Размер буфера, содержащего надстройку.

pvOld

Выходной буфер, который получит текущее значение столбца, хранящегося в базе данных (управление версиями игнорируется).

cbOldMax

Максимальный размер выходного буфера, который получит текущее значение столбца. В настоящее время поддерживается только JET_coltypLong, поэтому длина буфера должна составлять 4 байта или 0 байт. Если pvOld имеет значение NULL, то cbOldMax должно иметь значение 0.

pcbOldActual

Получает фактический объем необработанных данных о значении, полученных в выходном буфере.

grbit

Группа битов, задающая ноль или несколько следующих параметров.

Значение	Значение
JET_bitEscrowNoRollback	Даже если сеанс, выполняющий обновление депонирования, имеет откат транзакций, это обновление не будет отменено. Обратите внимание, что, так как записи журнала могут не быть сброшены на диск, последние обновления, выполненные с помощью этого флага, могут быть потеряны в случае сбоя.

Возвращаемое значение

Эта функция возвращает тип данных JET_ERR с одним из следующих кодов возврата. Дополнительные сведения о возможных ошибках ESE см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.

Код возврата	Описание
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

Операции escrow определяются версиями и отменяются с помощью JetRollback (если не указан JET_bitEscrowNoRollback). 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.
Сервер	Требуется 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