Función JetUpdate

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetUpdate

La función JetUpdate realiza una operación de actualización, incluida la inserción de una nueva fila en una tabla o la actualización de una fila existente. La eliminación de una fila de tabla se realiza mediante una llamada a JetDelete.

JetUpdate es el último paso para realizar una inserción o una actualización. La actualización se inicia llamando a JetPrepareUpdate y, a continuación, llamando a JetSetColumn o JetSetColumns una o varias veces para establecer el estado del registro. Por último, se llama a JetUpdate para completar la operación de actualización. Los índices solo se actualizan mediante JetUpdate o JetUpdate2, y no durante JetSetColumn o JetSetColumns.

    JET_ERR JET_API JetUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbBookmark,
      __out_opt     unsigned long* pcbActual
    );

Parámetros

sesid

Sesión que se va a usar para esta llamada.

tableid

Cursor que se va a usar para esta llamada.

pvBookmark

Puntero a un marcador devuelto para una fila insertada.

cbBookmark

Tamaño del búfer al que apunta pvBookmark.

pcbActual

Tamaño devuelto del marcador para la fila insertada devuelta en pvBookmark.

Valor devuelto

Esta función devuelve el tipo de datos JET_ERR 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_errBufferTooSmall	El búfer especificado para el marcador de registro no es lo suficientemente grande como para almacenar el marcador de registro.
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_errColumnIllegalNull	Igual que JET_errNullInvalid.
JET_errDiskFull	La operación de actualización requiere crecimiento de archivos de base de datos o asignación de archivos de registro, pero la unidad de disco donde reside el archivo de base de datos o la serie de registros está llena. Como alternativa, el archivo de base de datos está en un volumen con formato FAT32 y el archivo de base de datos ya es 4GBytes, el límite por archivo para FAT32.
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. Windows XP: Windows XP solo devolverá este error y versiones posteriores.
JET_errInvalidParameter	El parámetro de preparación especificado en la función JetPrepareUpdate no es una marca válida.
JET_errKeyDuplicate	Una clave de índice para este registro es un duplicado de otra clave de índice para otro registro ya en la tabla y el índice no permite duplicados.
JET_errKeyTruncated	El registro insertado o actualizado tiene uno o varios índices para los que la clave generada habría superado el tamaño máximo permitido. Como resultado, la operación no pudo evitar el truncamiento de claves.
JET_errMultiValuedIndexViolation	El registro insertado o actualizado tiene una columna de varios valores indizada con dos o más valores idénticos dentro del tamaño máximo de clave establecido para el índice. Como resultado, el registro tiene dos entradas idénticas en el índice que no son válidas.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errNullInvalid	Una o varias columnas del registro que se van a insertar o en el estado actualizado de un registro que se va a reemplazar es NULL , lo que infringe la restricción definida para esas columnas.
JET_errNullKeyDisallowed	Uno o varios índices se definen para no permitir una clave NULL y el estado insertado o actualizado de un registro que se va a reemplazar infringe esta restricción definida.
JET_errRecordPrimaryChanged	Una operación de reemplazo de registros ha actualizado la clave principal. Novedades a las columnas de clave principal deben realizarse mediante la eliminación del registro existente y la inserción de un nuevo registro con los datos deseados.
JET_errRestoreInProgress	No es posible completar la operación porque hay una operación de restauración en curso en la instancia asociada a la sesión.
JET_errSessionSharingViolation	No se puede usar la misma sesión para más de un subproceso al mismo tiempo. Windows XP: Windows XP solo devolverá este error y versiones posteriores.
JET_errTermInProgress	No es posible completar la operación porque se está cerrando la instancia asociada a la sesión.
JET_errTransReadOnly	No es válido intentar una actualización cuando se encuentra dentro del ámbito de una transacción de solo lectura. Una transacción de solo lectura es una transacción que se ha iniciado mediante una llamada a JetBeginTransaction2 con JET_bitTransactionReadOnly. Windows XP: Windows XP solo devolverá este error y versiones posteriores.
JET_errUpdateNotPrepared	Se llamó a JetPrepareUpdate con JET_prepCancel pero el cursor no estaba en estado preparado.
JET_errVersionStoreOutOfMemory	Error en la operación porque no hay suficiente memoria para conservar la información transaccional sobre la actualización.
JET_errWriteConflict	Otra sesión ha bloqueado previamente el registro para la actualización. Se producirá un error en la actualización que intentó esta sesión.

Si se ejecuta correctamente, se completa la operación de actualización abierta en el cursor. Si se define una columna de incremento automático para la tabla, este valor se establece para los registros insertados. Si se define una columna de versión para la tabla, su valor se inicializa para los registros recién insertados o se incrementa cada vez que se reemplaza un registro. Todos los índices, incluidos los índices agrupados y no agrupados, se actualizan.

En caso de error, no se realizan cambios de ningún tipo en la base de datos. Antes de que se haya llamado a las funciones de devolución de llamada insert y antes de reemplazar, pero después de la inserción y después de las devoluciones de llamada de reemplazo no se habrá llamado, ya que no se puede producir un error en la actualización. El búfer de copia del cursor se deja en su estado preparado, por lo que existe la oportunidad de corregir incrementalmente los problemas que provocaron errores y reintentar la operación de actualización.

Comentarios

Las funciones de devolución de llamada se pueden registrar para que se llamen antes o después de la inserción y antes o después de la actualización.

JetSetColumn aplica limitaciones de tamaño de registro y no en general jetUpdate.

Es importante comprender el impacto de realizar un gran número de operaciones de actualización dentro de una sola transacción. El motor de base de datos debe realizar un seguimiento de cada actualización de la base de datos en el almacén de versiones. El almacén de versiones contiene un registro activo de todas las distintas versiones de cada registro o entrada de índice en la base de datos que todas las transacciones activas pueden ver. Estas versiones se usan para admitir el control de simultaneidad con varias versiones en uso por el motor de base de datos para admitir transacciones mediante el aislamiento de instantáneas. Una vez que el motor de base de datos ha agotado los recursos usados para almacenar estas versiones, ya no puede aceptar más cambios hasta que se hayan concluido algunas transacciones para permitir que estos recursos se recuperen. Cuando el motor se encuentra en este estado, se producirá un error en todas las actualizaciones con JET_errVersionStoreOutOfMemory. Los recursos disponibles para el motor de base de datos para almacenar estas versiones se pueden controlar mediante JetSetSystemParameter con JET_paramMaxVerPages y JET_paramGlobalMinVerPages.

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_ERR
JET_SESID
JET_TABLEID
JetDelete
JetPrepareUpdate
JetRegisterCallback
JetRetrieveColumn
JetRetrieveColumns
JetSetColumn
JetSetColumns
JetSetSystemParameter
Parámetros del sistema

Función JetUpdate