Função JetUpdate

  • Artigo

Aplica-se a: Windows | Windows Server

Função JetUpdate

A função JetUpdate executa uma operação de atualização, incluindo a inserção de uma nova linha em uma tabela ou a atualização de uma linha existente. A exclusão de uma linha de tabela é executada chamando JetDelete.

JetUpdate é a etapa final na execução de uma inserção ou uma atualização. A atualização é iniciada chamando JetPrepareUpdate e, em seguida, chamando JetSetColumn ou JetSetColumns uma ou mais vezes para definir o estado do registro. Por fim, JetUpdate é chamado para concluir a operação de atualização. Os índices são atualizados apenas por JetUpdate ou JetUpdate2, e não durante JetSetColumn ou 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

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

pvBookmark

Ponteiro para um indicador retornado para uma linha inserida.

cbBookmark

Tamanho do buffer apontado por pvBookmark.

pcbActual

O tamanho retornado do indicador para a linha inserida retornada em pvBookmark.

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_errBufferTooSmall

O buffer fornecido para o indicador de registro não é suficientemente grande o suficiente para armazenar o indicador de registro.

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_errColumnIllegalNull

O mesmo que JET_errNullInvalid.

JET_errDiskFull

A operação de atualização requer o crescimento do arquivo de banco de dados ou a alocação de arquivos de log, mas a unidade de disco em que reside o arquivo de banco de dados ou a série de logs está cheia. Como alternativa, o arquivo de banco de dados está em um volume formatado em FAT32 e o arquivo de banco de dados já é 4GBytes, o limite por arquivo para FAT32.

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.

Windows XP: Esse erro só será retornado pelo Windows XP e versões posteriores.

JET_errInvalidParameter

O parâmetro de preparação especificado na função JetPrepareUpdate não é um sinalizador válido.

JET_errKeyDuplicate

Uma chave de índice para esse registro é uma duplicata de outra chave de índice para outro registro que já está na tabela e o índice não permite duplicatas.

JET_errKeyTruncated

O registro inserido ou atualizado tem um ou mais índices para os quais a chave gerada teria excedido o tamanho máximo permitido. Como resultado, a operação falhou ao impedir o truncamento de chave.

JET_errMultiValuedIndexViolation

O registro inserido ou atualizado tem uma coluna de vários valores indexada com dois ou mais valores idênticos dentro do tamanho máximo da chave definido para o índice. Como resultado, o registro tem duas entradas idênticas no índice, o que é inválido.

JET_errNotInitialized

Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.

JET_errNullInvalid

Uma ou mais colunas no registro a ser inserido ou no estado atualizado de um registro que está sendo substituído é NULL , o que viola a restrição definida para essas colunas.

JET_errNullKeyDisallowed

Um ou mais índices são definidos para não permitir uma chave NULL e o estado inserido ou atualizado de um registro que está sendo substituído viola essa restrição definida.

JET_errRecordPrimaryChanged

Uma operação de substituição de registro atualizou a chave primária. Atualizações para colunas de chave primária devem ser feitas por meio da exclusão do registro existente e da inserção de um novo registro com os dados desejados.

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 para mais de um thread ao mesmo tempo.

Windows XP: 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

É inválido tentar uma atualização quando estiver dentro do escopo de uma transação somente leitura. Uma transação somente leitura é uma transação que foi iniciada usando uma chamada para JetBeginTransaction2 com JET_bitTransactionReadOnly.

Windows XP: Esse erro só será retornado pelo Windows XP e versões posteriores.

JET_errUpdateNotPrepared

JetPrepareUpdate foi chamado com JET_prepCancel mas o cursor não estava no estado preparado.

JET_errVersionStoreOutOfMemory

A operação falhou porque não há memória suficiente para reter informações transacionais sobre a atualização.

JET_errWriteConflict

Outra sessão bloqueou anteriormente o registro para atualização. A atualização tentada por esta sessão falhará.

Em caso de êxito, a operação de atualização aberta no cursor é concluída. Se uma coluna de incremento automático for definida para a tabela, esse valor será definido para registros inseridos. Se uma coluna de versão for definida para a tabela, seu valor será inicializado para registros recém-inseridos ou incrementado sempre que um registro for substituído. Todos os índices, incluindo índices clusterizados e não clusterizados, são atualizados.

Em caso de falha, nenhuma alteração de qualquer tipo é feita no banco de dados. Antes de inserir e antes de substituir, as funções de retorno de chamada podem ter sido chamadas, mas após inserir e depois de substituir, os retornos de chamada não serão chamados, pois este último não pode causar uma falha na atualização. O buffer de cópia do cursor é deixado em seu estado preparado, de modo que exista a oportunidade de corrigir incrementalmente os problemas que causaram erros e repetir a operação de atualização.

Comentários

As funções de retorno de chamada podem ser registradas para serem chamadas antes ou depois da inserção e antes ou depois da atualização.

As limitações de tamanho do registro são impostas por JetSetColumn e não em geral pelo JetUpdate.

É importante entender o impacto de executar um grande número de operações de atualização dentro de uma única transação. Cada atualização para o banco de dados deve ser controlada pelo mecanismo de banco de dados no repositório de versão. O repositório de versão contém um registro ao vivo de todas as diferentes versões de cada registro ou entrada de índice no banco de dados que podem ser vistas por todas as transações ativas. Essas versões são usadas para dar suporte ao controle de simultaneidade de várias versões em uso pelo mecanismo de banco de dados para dar suporte a transações usando instantâneo isolamento. Depois que o mecanismo de banco de dados tiver esgotado os recursos usados para armazenar essas versões, ele não poderá mais aceitar mais alterações até que algumas transações tenham sido concluídas para permitir que esses recursos sejam recuperados. Quando o mecanismo estiver nesse estado, todas as atualizações falharão com JET_errVersionStoreOutOfMemory. Os recursos disponíveis para o mecanismo de banco de dados para armazenar essas versões podem ser controlados usando JetSetSystemParameter com JET_paramMaxVerPages e JET_paramGlobalMinVerPages.

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
JetDelete
JetPrepareUpdate
JetRegisterCallback
JetRetrieveColumn
JetRetrieveColumns
JetSetColumn
JetSetColumns
JetSetSystemParameter
Parâmetros do sistema