Función JetEscrowUpdate

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetEscrowUpdate

La función JetEscrowUpdate realiza una operación de suma atómica en una columna. Esta función permite que varias sesiones actualicen el mismo registro simultáneamente sin conflictos.

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

Parámetros

sesid

La sesión que se va a usar para esta llamada.

tableid

Cursor que se va a usar para esta llamada.

columnid

Columnid de la columna que se va a actualizar.

Puntero a un búfer que contiene el addend para la columna.

cbMax

Tamaño del búfer que contiene el addend.

pvOld

Búfer de salida que recibirá el valor actual de la columna tal y como se almacena en la base de datos (se omite el control de versiones).

cbOldMax

Tamaño máximo del búfer de salida que recibirá el valor actual de la columna. Actualmente solo se admite JET_coltypLong, por lo que el búfer debe tener una longitud de 4 o 0 bytes. Si pvOld es NULL, cbOldMax debe ser 0.

pcbOldActual

Recibe la cantidad real de datos de valor sin procesar recibidos en el búfer de salida.

grbit

Un grupo de bits que especifica cero o más de las siguientes opciones.

Value	Significado
JET_bitEscrowNoRollback	Incluso si la sesión que realiza la actualización de custodia tiene su reversión de transacciones, esta actualización no se deshacerá. Tenga en cuenta que, dado que los registros de registro no se pueden vaciar en el disco, es posible que se pierdan las actualizaciones recientes de la custodia realizadas con esta marca si se produce un bloqueo.

Valor devuelto

Esta función devuelve el JET_ERR tipo de datos con uno de los siguientes códigos de retorno. Para obtener más información sobre los posibles errores de ESE, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código devuelto	Descripción
JET_errSuccess	La operación se ha completado correctamente.
JET_errAlreadyPrepared	El cursor tiene una actualización preparada con JetPrepareUpdate.
JET_errClientRequestToStopJetService	No es posible completar la operación porque toda la actividad de la instancia asociada a la sesión ha dejado de funcionar como resultado de una llamada a JetStopService.
JET_errInstanceUnavailable	No es posible completar la operación porque la instancia asociada a la sesión ha encontrado un error irrecuperable que requiere que se revoque el acceso a todos los datos para proteger la integridad de esos datos. Este error solo lo devolverá Windows XP y versiones posteriores.
JET_errInvalidBufferSize	Se ha pasado un tamaño de búfer no válido. Actualmente solo se admite JET_coltypLong, por lo que el búfer debe ser de 4 bytes.
JET_errInvalidOperation	Se ha especificado una columna no válida. La columna debe crearse con JET_bitColumnEscrowUpdate especificado. Solo se pueden especificar columnas fijas de JET_coltypLong como actualizables.
JET_errNoCurrentRecord	El cursor debe estar en un registro para actualizar una columna.
JET_errNotInTransaction	Las actualizaciones de custodia solo se pueden realizar mediante sesiones de una transacción.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errPermissionDenied	El cursor no puede ser de solo lectura y actualizar un registro.
JET_errRestoreInProgress	No es posible completar la operación porque una operación de restauración está en curso en la instancia asociada a la sesión.
JET_errSessionSharingViolation	No se puede usar la misma sesión desde más de un subproceso al mismo tiempo. Este error solo lo devolverá Windows XP y versiones posteriores.
JET_errTermInProgress	No es posible completar la operación porque la instancia asociada a la sesión se está cerrando.
JET_errTransReadOnly	La sesión debe tener permisos de escritura para actualizar un registro.
JET_errWriteConflict	Error devuelto cuando se solicita una actualización en conflicto.

Comentarios

Normalmente, si dos sesiones intentan actualizar un registro simultáneamente, la segunda sesión recibirá un error de JET_errWriteConflict a menos que las sesiones estén completamente serializadas. Para serializar dos sesiones que actualizan el mismo registro, la segunda sesión debe iniciar su transacción después de que la primera transacción confirme su transacción. Consulte JetBeginTransaction para obtener más información.

Se pueden actualizar varias columnas del mismo registro. Las actualizaciones no afectan entre sí.

Solo las operaciones JetEscrowUpdate son compatibles entre sí. Si dos sesiones diferentes intentan preparar actualizaciones o eliminar el mismo registro, se generará un conflicto de escritura.

		Sesión B JetEscrowUpdate	JetPrepareUpdate	JetDelete
	JetEscrowUpdate	JET_errSuccess	JET_errWriteConflict	JET_errWriteConflict
	JetUpdate	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict
Sesión A	JetDelete	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict

Las operaciones de custodia tienen versiones y se deshacen mediante JetRollback (a menos que se haya especificado JET_bitEscrowNoRollback). JetEscrowUpdate devuelve el valor sin procesar de la columna almacenada en la base de datos, ya que una aplicación puede querer realizar una acción especial cuando se alcanza un valor de Sentinel. JetRetrieveColumn devuelve la vista con versiones correcta de la columna, ignorando las actualizaciones realizadas por sesiones simultáneas.

Dadas dos sesiones que funcionan en la misma columna del mismo registro, podemos ver cómo funciona. Supongamos que la columna comienza con un valor de 0.

Sesión	Operación	Valor almacenado	Valor devuelto
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
N	JetRetrieveColumn		3
A	JetRetrieveColumn		-1
B	JetRollback	-1
A	JetRetrieveColumn		-1

No se recomienda reemplazar un registro en la misma transacción que realiza actualizaciones de custodia en un registro. En concreto, si se prepara una actualización de un registro con una JET_TABLEID y se usa un JET_TABLEID diferente para actualizar el registro, la custodia actualizada se perderá cuando se llame a JetUpdate . Esto sucede incluso si la columna de custodia no se estableció durante la actualización.

Cuando una columna actualizable de custodia tiene un valor de cero, se puede desencadenar un comportamiento especial. Este comportamiento solo se produce si una operación JetEscrowUpdate hace que la columna tenga un valor de cero. La acción no se produce inmediatamente, pero se produce algún tiempo después de la transacción que hizo que la columna tuviera un valor de cero confirmaciones. La columna todavía debe tener un valor de cero (es decir, si ninguna otra sesión ha modificado la columna). Si la columna se creó con JET_bitColumnDeleteOnZero, se eliminará el registro que contiene la columna. Si la columna se creó con JET_bitColumnFinalize, se emitirá una devolución de llamada. Un bloqueo puede hacer que estas acciones no se produzcan, pero el mantenimiento en línea (mediante la función JetDefragment ) rehacerá correctamente las acciones.

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista, Windows XP o Windows 2000 Professional.
Servidor	Requiere Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Encabezado	Declarado en Esent.h.
Library	Use ESENT.lib.
Archivo DLL	Requiere ESENT.dll.

Consulte también

JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction
JetDefragment
JetPrepareUpdate
JetRetrieveColumn
JetRollback
JetStopService
JetUpdate

Función JetEscrowUpdate