Función JetPrepareUpdate

Se aplica a: Windows | Windows Server

Función JetPrepareUpdate

La función JetPrepareUpdate es la primera operación en realizar una actualización, con el fin de insertar un nuevo registro o reemplazar un registro existente por nuevos valores. Novedades se realizan llamando a JetPrepareUpdate y, a continuación, llamando a JetSetColumn o JetSetColumns cero o más veces y finalmente llamando a JetUpdate para completar la operación. JetPrepareUpdate y JetUpdate establecen los límites de una operación de actualización y son importantes al tener solo el estado de actualización final de un registro especificado en los índices. Esto es más eficaz, pero también es necesario en los casos en los que los datos deben coincidir con un estado válido a través de más que en la operación de establecer columna.

Hay algunas opciones diferentes para insertar o reemplazar registros y se describen con más detalle a continuación.

    JET_ERR JET_API JetPrepareUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long prep
    );

Parámetros

sesid

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

tableid

Cursor que se va a usar para esta llamada.

Preparación

Las opciones que se pueden usar para prepararse para una actualización, que incluyen lo siguiente.

Valor	Significado
JET_prepCancel	Esta marca hace que JetPrepareUpdate cancele la actualización de este cursor.
JET_prepInsert	Esta marca hace que el cursor se prepare para una inserción de un nuevo registro. Todos los datos se inicializan en el estado predeterminado del registro. Si la tabla tiene una columna de incremento automático, se asigna un nuevo valor a este registro, independientemente de si la actualización se realiza correctamente, produce un error o se cancela.
JET_prepInsertCopy	Esta marca hace que el cursor se prepare para una inserción de una copia del registro existente. Debe haber un registro actual si se usa esta opción. El estado inicial del nuevo registro se copia del registro actual. Los valores largos que se almacenan fuera del registro se copian virtualmente.
JET_prepInsertCopyDeleteOriginal	Esta marca hace que el cursor se prepare para una inserción del mismo registro y una eliminación o el registro original. Se usa en los casos en los que ha cambiado la clave principal.
JET_prepReplace	Esta marca hace que el cursor se prepare para un reemplazo del registro actual. Si la tabla tiene una columna de versión, la columna de versión se establece en el siguiente valor de su secuencia. Si esta actualización no se completa, el valor de versión del registro no se verá afectado. Se toma un bloqueo de actualización en el registro para evitar que otras sesiones actualicen este registro antes de que se complete esta sesión.
JET_prepReplaceNoLock	Esta marca es similar a JET_prepReplace, pero no se toma ningún bloqueo para evitar que otras sesiones actualicen este registro. En su lugar, esta sesión puede recibir JET_errWriteConflict cuando llama a JetUpdate para completar la actualización.

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_errAlreadyPrepared	Se llamó a JetPrepareUpdate con una marca válida para la preparación, pero no JET_prepCancel y el cursor ya estaba en estado preparado.
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. Windows XP solo devolverá este error y versiones posteriores.
JET_errInvalidParameter	La marca de preparación especificada no es una marca válida.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errNotInTransaction	Se llamó a JetPrepareUpdate para reemplazar un registro que tenía columnas SLV. Columnas SLV. Tenga en cuenta que las columnas SLV son una característica que no está pensada para el uso general. Esta característica se usa para admitir la infraestructura de Microsoft Exchange y no está pensada para usarse en la aplicación.
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_errRollbackError	Se llamó a JetPrepareUpdate con JET_prepCancel pero no pudo revertir todos los cambios realizados en columnas de tipo JET_coltypLongText o columnas de tipo JET_coltypLongBinary.
JET_errSessionSharingViolation	Esta marca no se puede usar con la misma sesión de más de un subproceso al mismo tiempo. 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_errUpdateNotPrepared	Se llamó a JetPrepareUpdate con JET_prepCancel pero el cursor no estaba en estado preparado.

Si se ejecuta correctamente, el cursor se cambia al estado preparado con el fin de la actualización deseada, o en el caso de JET_prepCancel, el cursor se revierte al estado no preparado y se descartan los cambios.

En caso de error, el estado del cursor se deja sin cambios. Si el error se JET_errRollbackError, el estado del cursor se cambia al estado no preparado, pero no se han revertido todos los cambios.

Comentarios

Insertar una copia de un registro es una optimización importante cuando los registros comparten datos de tipo JET_coltypLongText o JET_coltypLongBinary. Estos datos se almacenan fuera de registro cuando son grandes y es posible que varios registros compartan la misma representación física de los datos. En este caso, los datos se pueden actualizar desde cualquier registro, pero si lo hace, los datos se expandirán de forma que cada registro tenga su propia copia. No es posible cambiar los datos de un registro mediante una modificación de otro registro. Además, no es posible bloquear una actualización de un registro mediante una actualización de otro registro. Se trata de una característica central para ESE y se conoce como bloqueo de nivel de registro.

Las operaciones jetUpdate que producen un error dejan el cursor en el estado preparado de actualización. Esto permite corregir algunos errores, como un valor de columna incorrecto, sin necesidad de volver a crear el estado de actualización. Esto significa que, en todos los casos en los que un cursor abandona una actualización, debe llamar explícitamente a JetPrepareUpdate con JET_prepCancel.

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
JetRetrieveColumn
JetSetColumn
JetUpdate