Função JetRestoreInstance

Aplica-se a: Windows | Windows Server

Função JetRestoreInstance

A função JetRestoreInstance restaura e recupera um backup de streaming de uma instância, incluindo todos os bancos de dados anexados. Ele foi projetado para funcionar com um backup criado com a função JetBackupInstance . Essa é a função de restauração mais simples e encapsulada.

O Windows XP:JetRestoreInstance é introduzido no Windows XP.

    JET_ERR JET_API JetRestoreInstance(
      __in          JET_INSTANCE instance,
      __in          JET_PCSTR sz,
      __in_opt      JET_PCSTR szDest,
      __in          JET_PFNSTATUS pfn
    );

Parâmetros

instance

Especifica a instância a ser usada para essa chamada.

Para o Windows XP e versões posteriores, o uso desse parâmetro depende do modo operacional do mecanismo. Se o mecanismo estiver operando no modo herdado (modo de compatibilidade do Windows 2000) em que apenas uma instância tem suporte, esse parâmetro pode ser NULL ou pode ser definido como um buffer de saída válido contendo NULL ou JET_instanceNil que retornará o identificador de instância global criado como um efeito colateral da inicialização. Esse identificador de instância pode ser passado para qualquer outra API que usa uma instância. Se o mecanismo estiver operando no modo de várias instâncias, esse parâmetro deverá ser definido como um buffer de entrada válido que contenha o identificador de instância retornado por JetCreateInstance que está sendo inicializado.

sz

A pasta em que o backup está localizado. O backup deveria ter sido gerado usando as APIs do JetBackup .

szDest

Nome da pasta em que os arquivos de banco de dados do conjunto de backup serão copiados e recuperados. Se isso for definido como NULL (que é o caso do JetRestore herdado), os arquivos de banco de dados serão copiados e recuperados para o local original.

pfn

O ponteiro opcional para a função que será chamada como informações de notificação sobre o progresso da operação de restauraçã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 do 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_errAlreadyInitialized	A operação falhou porque o mecanismo já está inicializado para essa instância.
JET_errInvalidLogSequence	O conjunto de arquivos de log do conjunto de backup e do caminho de log atual não corresponde.
JET_errInvalidParameter	Um dos parâmetros fornecidos continha um valor inesperado ou continha um valor que não fazia sentido quando combinado com o valor de outro parâmetro. Esse erro será retornado por JetRestoreInstance quando o mecanismo estiver no modo de várias instâncias e pinstance se referir a uma instância inválida do Windows XP e versões posteriores.
JET_errInvalidPath	A operação falhou porque alguns dos caminhos fornecidos são inválidos (o caminho de backup, o caminho de destino, o log ou o caminho do sistema para a instância).
JET_errPageSizeMismatch	A operação falhou porque o mecanismo está configurado para usar um tamanho de página de banco de dados (usando JetSetSystemParameter para JET_paramDatabasePageSize) que não corresponde ao tamanho da página do banco de dados usado para criar os arquivos de log de transações ou os bancos de dados associados aos arquivos de log de transações.
JET_errRunningInMultiInstanceMode	A operação falhou porque os parâmetros implicavam o modo de instância única (modo de compatibilidade do Windows 2000) e o mecanismo já está no modo de várias instâncias.

Com êxito, os arquivos de banco de dados do conjunto de backup serão restaurados para o local e a recuperação será executada de modo que os bancos de dados estejam em um estado de consistência transacional limpo. A recuperação reproduzirá os arquivos de log do conjunto de backup e os arquivos de log do caminho de log se esses arquivos existirem. Essa recuperação resultará em alterações no arquivo de ponto de verificação, nos arquivos de log de transações e nos bancos de dados referenciados por esses arquivos de log de transações.

Em caso de falha, a instância permanece em um estado não inicializado. O estado dos arquivos de log de transações e todos os bancos de dados referenciados por esses arquivos de log de transações provavelmente foram alterados na tentativa de inicializar a restauração e recuperar os bancos de dados.

Comentários

O processo de recuperação reconstruirá os bancos de dados anexados à instância durante o backup e salvará as alterações nos arquivos de banco de dados. O resultado serão bancos de dados consistentes com a transação. Se possível, ele também salvará no banco de dados as alterações feitas desde que o backup foi feito até a alteração mais recente encontrada nos logs de transações. Isso seria possível se os logs de transação gerados desde que o backup foi feito ainda estejam presentes no diretório de log de transações. Observe que, se o log circular tiver sido habilitado para a instância, os logs de transação gerados serão reutilizados de modo que a recuperação possa salvar as alterações que ocorreram até o momento do backup. De qualquer forma, é possível que esse processo leve algum tempo se o número de arquivos de log de transações a serem reproduzidos nos bancos de dados for grande.

JetRestoreInstance deve ser chamado em uma instância que já foi criada usando JetCreateInstance.

Como durante a recuperação um número significativo de páginas de banco de dados e logs de transações serão usados, há uma série inteira de erros que podem ser retornados por essas funções. Esses erros podem ser de falhas temporárias de alocação de recursos, como Jet_errOutOfMemory, a erros que representam corrupção física, como JET_errReadVerifyFailure, JET_errLogFileCorrupt ou JET_errBadPageLink. Esses erros são quase sempre causados por problemas de hardware e, portanto, não podem ser evitados. A má gestão de arquivos se manifestará com mais frequência como JET_errMissingLogFile ou JET_errAttachedDatabaseMismatch ou JET_errDatabaseSharingViolation ou JET_errInvalidLogSequence. Esses erros são evitáveis pelo aplicativo. O aplicativo deve ter cuidado para proteger o repositório desses arquivos contra manipulação por forças externas, como o usuário ou outros aplicativos. Se o aplicativo quiser destruir totalmente uma instância, todos os arquivos associados à instância deverão ser excluídos. Eles incluem o arquivo de ponto de verificação, os arquivos de log de transações e todos os arquivos de banco de dados anexados à instância.

As diferentes etapas da recuperação terão entradas do Log de Eventos geradas, incluindo o progresso da reprodução do log de transações e o resultado final da restauração.

Requisitos

Requisito	Valor
Cliente	Requer o Windows Vista ou o Windows XP.
Servidor	Requer o Windows Server 2008 ou o Windows Server 2003.
Cabeçalho	Declarado em Esent.h.
Biblioteca	Use ESENT.lib.
DLL	Requer ESENT.dll.
Unicode	Implementado como JetRestoreInstanceW (Unicode) e JetRestoreInstanceA (ANSI).

Consulte Também

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter