Função JetPrepareUpdate

Artigo
06/12/2023

Aplica-se a: Windows | Windows Server

Função JetPrepareUpdate

A função JetPrepareUpdate é a primeira operação na execução de uma atualização, para fins de inserção de um novo registro ou substituição de um registro existente por novos valores. Atualizações são feitas chamando JetPrepareUpdate, chamando JetSetColumn ou JetSetColumns zero ou mais vezes e, por fim, chamando JetUpdate para concluir a operação. JetPrepareUpdate e JetUpdate definem os limites para uma operação de atualização e são importantes para ter apenas o estado de atualização final de um registro inserido em índices. Isso é mais eficiente, mas também necessário nos casos em que os dados devem corresponder a um estado válido por meio de mais do que na operação de coluna definida.

Há algumas opções diferentes para inserir ou substituir registros e eles são descritos em mais detalhes abaixo.

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

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

Preparar

As opções que podem ser usadas para se preparar para uma atualização, que incluem o seguinte.

Valor	Significado
JET_prepCancel	Esse sinalizador faz com que JetPrepareUpdate cancele a atualização desse cursor.
JET_prepInsert	Esse sinalizador faz com que o cursor se prepare para uma inserção de um novo registro. Todos os dados são inicializados para o estado padrão do registro. Se a tabela tiver uma coluna de incremento automático, um novo valor será atribuído a esse registro, independentemente de a atualização ser bem-sucedida, falhar ou ser cancelada.
JET_prepInsertCopy	Esse sinalizador faz com que o cursor se prepare para uma inserção de uma cópia do registro existente. Deve haver um registro atual se essa opção for usada. O estado inicial do novo registro é copiado do registro atual. Valores longos armazenados fora do registro são virtualmente copiados.
JET_prepInsertCopyDeleteOriginal	Esse sinalizador faz com que o cursor se prepare para uma inserção do mesmo registro e uma exclusão ou o registro original. Ele é usado nos casos em que a chave primária foi alterada.
JET_prepReplace	Esse sinalizador faz com que o cursor se prepare para uma substituição do registro atual. Se a tabela tiver uma coluna de versão, a coluna de versão será definida como o próximo valor em sua sequência. Se essa atualização não for concluída, o valor da versão no registro não será afetado. Um bloqueio de atualização é feito no registro para impedir que outras sessões atualizem esse registro antes da conclusão desta sessão.
JET_prepReplaceNoLock	Esse sinalizador é semelhante a JET_prepReplace, mas nenhum bloqueio é feito para impedir que outras sessões atualizem esse registro. Em vez disso, essa sessão pode receber JET_errWriteConflict quando chama JetUpdate para concluir a atualização.

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	JetPrepareUpdate foi chamado com um sinalizador válido para preparação, mas não JET_prepCancel e o cursor já estava no estado preparado.
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_errInvalidParameter	O sinalizador de preparação especificado não é um sinalizador válido.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errNotInTransaction	JetPrepareUpdate foi chamado para substituir um registro que tinha colunas SLV. Colunas SLV. Observe que as colunas SLV são um recurso não destinado ao uso geral. Esse recurso é usado para dar suporte à infraestrutura do Microsoft Exchange e não se destina a ser usado em seu aplicativo.
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_errRollbackError	JetPrepareUpdate foi chamado com JET_prepCancel, mas não pôde reverter todas as alterações feitas em colunas do tipo JET_coltypLongText e/ou colunas do tipo JET_coltypLongBinary.
JET_errSessionSharingViolation	Esse sinalizador não pode ser usado com a mesma sessão 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_errUpdateNotPrepared	JetPrepareUpdate foi chamado com JET_prepCancel mas o cursor não estava no estado preparado.

Em caso de êxito, o cursor é alterado para o estado preparado para a finalidade da atualização desejada ou, no caso de JET_prepCancel, o cursor é revertido para o estado não preparado e todas as alterações são descartadas.

Em caso de falha, o estado do cursor permanece inalterado. Se a falha tiver sido JET_errRollbackError o estado do cursor será alterado para o estado não preparado, mas nem todas as alterações foram revertidas.

Comentários

Inserir uma cópia de um registro é uma otimização importante quando os registros compartilham dados do tipo JET_coltypLongText e/ou JET_coltypLongBinary. Esses dados são armazenados fora do registro quando grandes e é possível que vários registros compartilhem a mesma representação física dos dados. Nesse caso, os dados podem ser atualizados de qualquer registro, mas isso fará com que os dados sejam estourados de modo que cada registro tenha sua própria cópia. Não é possível alterar dados em um registro por uma modificação de outro registro. Além disso, não é possível bloquear uma atualização de um registro por uma atualização de outro registro. Esse é um recurso central do ESE e é conhecido como Bloqueio de Nível de Registro.

As operações JetUpdate que falham deixam o cursor no estado preparado de atualização. Isso é para permitir a correção de alguns erros, como um valor de coluna incorreto, sem exigir que o estado de atualização seja recriado. Isso significa que, em todos os casos em que um cursor abandona uma atualização, ele deve chamar explicitamente JetPrepareUpdate com JET_prepCancel.

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_ERR
JET_SESID
JET_TABLEID
JetRetrieveColumn
JetSetColumn
JetUpdate

Função JetPrepareUpdate