Compartir a través de


Función JetEscrowUpdate

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.

pv

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