Função JetEscrowUpdate

Artigo
06/13/2023

Aplica-se a: Windows | Windows Server

Função JetEscrowUpdate

A função JetEscrowUpdate executa uma operação de adição atômica em uma coluna. Essa função permite que várias sessões atualizem o mesmo registro simultaneamente sem conflitos.

    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

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

Columnid

A columnid da coluna a ser atualizada.

Um ponteiro para um buffer que contém o complemento para a coluna.

cbMax

O tamanho do buffer que contém o complemento.

pvOld

O buffer de saída que receberá o valor atual da coluna, conforme armazenado no banco de dados (o controle de versão é ignorado).

cbOldMax

O tamanho máximo do buffer de saída que receberá o valor atual da coluna. Atualmente, há suporte apenas para JET_coltypLong, portanto, o buffer deve ter 4 bytes ou 0 bytes de comprimento. Se pvOld for NULL, cbOldMax deverá ser 0.

pcbOldActual

Recebe a quantidade real de dados de valor bruto recebidos no buffer de saída.

grbit

Um grupo de bits que especifica zero ou mais das opções a seguir.

Valor	Significado
JET_bitEscrowNoRollback	Mesmo que a sessão que executa a atualização de caução tenha sua reversão de transação, essa atualização não será desfeita. Observe que, como os registros de log podem não ser liberados para o disco, as atualizações de caução recentes feitas com esse sinalizador podem ser perdidas se houver uma falha.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos seguintes códigos de retorno. Para obter mais informações sobre os possíveis erros de ESE, consulte Erros extensíveis do mecanismo de armazenamento e parâmetros de tratamento de erros.

Código de retorno	Descrição
JET_errSuccess	A operação foi concluída com sucesso.
JET_errAlreadyPrepared	O cursor tem uma atualização preparada com JetPrepareUpdate.
JET_errClientRequestToStopJetService	Não é possível concluir a operação porque todas as atividades na instância associada à sessão cessaram como resultado de uma chamada para JetStopService.
JET_errInstanceUnavailable	Não é possível concluir a operação porque a instância associada à sessão encontrou um erro fatal que exige que o acesso a todos os dados seja revogado para proteger a integridade desses dados. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errInvalidBufferSize	Um tamanho de buffer inválido foi passado. Atualmente, há suporte apenas para JET_coltypLong, portanto, o buffer deve ser de 4 bytes.
JET_errInvalidOperation	Uma coluna inválida foi especificada. A coluna deve ser criada com JET_bitColumnEscrowUpdate especificado. Somente colunas fixas de JET_coltypLong podem ser especificadas como atualizáveis.
JET_errNoCurrentRecord	O cursor deve estar em um registro para atualizar uma coluna.
JET_errNotInTransaction	As atualizações de caução só podem ser executadas por sessões em uma transação.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errPermissionDenied	O cursor não pode ser somente leitura e atualizar um registro.
JET_errRestoreInProgress	Não é possível concluir a operação porque uma operação de restauração está em andamento na instância associada à sessão.
JET_errSessionSharingViolation	A mesma sessão não pode ser usada de mais de um thread ao mesmo tempo. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errTermInProgress	Não é possível concluir a operação porque a instância associada à sessão está sendo desligada.
JET_errTransReadOnly	A sessão deve ter permissões de gravação para atualizar um registro.
JET_errWriteConflict	O erro retornado quando uma atualização conflitante é solicitada.

Comentários

Normalmente, se duas sessões tentarem atualizar um registro simultaneamente, a segunda sessão receberá um erro JET_errWriteConflict, a menos que as sessões sejam completamente serializadas. Para serializar duas sessões que atualizam o mesmo registro, a segunda sessão deve iniciar sua transação após a primeira transação confirmar sua transação. Confira JetBeginTransaction para obter mais informações.

Várias colunas no mesmo registro podem ser atualizadas. As atualizações não afetam umas às outras.

Somente as operações JetEscrowUpdate são compatíveis entre si. Se duas sessões diferentes tentarem preparar atualizações ou excluir o mesmo registro, um conflito de gravação será gerado.

		Sessão B JetEscrowUpdate	JetPrepareUpdate	JetDelete
	JetEscrowUpdate	JET_errSuccess	JET_errWriteConflict	JET_errWriteConflict
	JetUpdate	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict
Sessão A	JetDelete	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict

As operações de caução têm controle de versão e são desfeitas usando JetRollback (a menos que JET_bitEscrowNoRollback tenha sido especificado). JetEscrowUpdate retorna o valor bruto da coluna armazenada no banco de dados, pois um aplicativo pode querer executar uma ação especial quando um valor sentinela é atingido. JetRetrieveColumn retorna a exibição com controle de versão correta da coluna, ignorando as atualizações feitas por sessões simultâneas.

Considerando duas sessões operando na mesma coluna do mesmo registro, podemos ver como isso funciona. Suponha que a coluna comece com um valor de 0.

Session	Operação	Valor armazenado	Valor retornado
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

Não é recomendável substituir um registro na mesma transação que executa atualizações de caução em um registro. Em particular, se uma atualização em um registro for preparada com um JET_TABLEID e um JET_TABLEID diferente for usado para escrow atualizar o registro, o caução atualizado será perdido quando JetUpdate for chamado. Isso acontece mesmo que a coluna de caução não tenha sido definida durante a atualização.

Quando uma coluna atualizável de caução tem um valor igual a zero, um comportamento especial pode ser disparado. Esse comportamento só ocorrerá se uma operação JetEscrowUpdate fizer com que a coluna tenha um valor igual a zero. A ação não acontece imediatamente, mas ocorre em algum momento após a transação, o que fez com que a coluna tivesse um valor de zero commits. A coluna ainda deverá ter um valor igual a zero (ou seja, se nenhuma outra sessão tiver modificado a coluna). Se a coluna tiver sido criada com JET_bitColumnDeleteOnZero, o registro que contém a coluna será excluído. Se a coluna tiver sido criada com JET_bitColumnFinalize, um retorno de chamada será emitido. Uma falha pode fazer com que essas ações não ocorram, mas a manutenção online (usando a função JetDefragment ) refazerá corretamente as ações.

Requisitos

Requisito	Valor
Cliente	Requer Windows Vista, Windows XP ou Windows 2000 Professional.
Servidor	Requer o Windows Server 2008, o Windows Server 2003 ou o Windows 2000 Server.
Cabeçalho	Declarado em Esent.h.
Biblioteca	Use ESENT.lib.
DLL	Requer ESENT.dll.

Consulte Também

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

Função JetEscrowUpdate