Função JetExternalRestore

Aplica-se a: Windows | Windows Server

Função JetExternalRestore

A função JetExternalRestore restaura um backup externo que foi feito com as APIs de backup externo e especifica um intervalo de números de arquivo de log a serem reproduzidos durante o processo de restauração. Isso é conhecido como recuperação rígida, que é semelhante, mas diferente da recuperação reversível, conforme executado pela função JetInit .

JET_ERR JET_API JetExternalRestore(
  __in          JET_PSTR szCheckpointFilePath,
  __in          JET_PSTR szLogPath,
  __in_opt      JET_RSTMAP* rgrstmap,
  __in          long crstfilemap,
  __in          JET_PSTR szBackupLogPath,
  __in          long genLow,
  __in          long genHigh,
  __in          JET_PFNSTATUS pfn
);

Parâmetros

szCheckpointFilePath

O caminho para o arquivo de ponto de verificação a ser usado durante a recuperação se szTargetInstanceCheckpointPath não for especificado ou já tiver uma instância ativa ou em execução.

szLogPath

O caminho ou diretório para os logs para a fase final (desfazer) da recuperação e, possivelmente, para os logs de roll forward. Esse caminho pode ser o mesmo que o szBackupLogPath.

rgrstmap

Essa é uma matriz de estruturas JET_RSTMAP . Este é um mapa de caminhos de banco de dados antigos e novos ou nomes de arquivo. Isso é usado porque os bancos de dados podem precisar ser recuperados em um local diferente do local do qual foram submetidos backup. No caso em que vários bancos de dados estão anexados a um único conjunto de logs, o mapa de restauração pode especificar um subconjunto de bancos de dados a serem restaurados.

crstfilemap

O número de entradas no parâmetro de matriz rgrstmap .

szBackupLogPath

O caminho para o diretório em que os arquivos de log são restaurados. Esses são os logs que foram lidos durante a sequência de backup externo. Esse caminho pode ser o mesmo que o szLogPath.

genLow

O menor número de arquivo de log que deve ser reproduzido de szBackupLogPath. A fidelidade total de um longo sem sinal deve ser preservada, mas nas versões atuais do mecanismo esse número é um número hexadecimal no intervalo de 0x00000 a 0xFFFFF. Isso pode mudar em versões futuras.

genHigh

O número de arquivo de log mais alto a ser reproduzido de szBackupLogPath. A fidelidade total de um longo sem sinal deve ser preservada, mas nas versões atuais do mecanismo esse número é um número hexadecimal no intervalo de 0x00000 a 0xFFFFF. Isso pode mudar em versões futuras.

pfn

O status retorno de chamada, para relatar o progresso da recuperaçã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_errOutOfMemory	A operação falhou porque não foi possível alocar memória suficiente para concluí-la.
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. Isso pode acontecer para JetExternalRestore e assim por diante quando o szTargetCheckpointPath e o szTargetInstanceLogPath não são especificados ou não são especificados. Ou seja, eles devem corresponder e ser especificados ou não especificados.
JET_errDatabaseCorrupted	Isso indica que o banco de dados foi corrompido ou um arquivo não reconhecido.
JET_errFileNotFound	A operação falhou porque não pôde abrir o arquivo solicitado porque ele não pôde ser encontrado no caminho especificado.
JET_errInvalidPath	A operação falhou porque o caminho especificado não pôde ser encontrado.
JET_errRestoreOfNonBackupDatabase	Esse erro será retornado se o arquivo de banco de dados especificado durante a restauração não for um banco de dados cujo backup foi feito com backup externo.
JET_errStartingRestoreLogTooHigh	Esse erro será retornado se um dos arquivos de log no szBackupLogPath tiver uma geração de log abaixo especificada pelo genLow ou pLogInfo.ulGenLow.
JET_errEndingRestoreLogTooLow	Esse erro será retornado se um dos arquivos de log no szBackupLogPath tiver uma geração de log acima especificada em genHigh ou pLogInfo.ulGenHigh.
JET_errBadRestoreTargetInstance	O szTargetInstanceLogPath especificado não pertence a uma instância inicializada. Esse erro só será retornado no Windows XP e posterior.
JET_errRunningInOneInstanceMode	O mecanismo de banco de dados não pode executar restauração externa ou recuperação rígida no modo de instância única. Esse erro só será retornado no Windows XP e posterior.

Em caso de êxito, todos os bancos de dados do rgrstmap são completamente recuperados e em um estado limpo ou consistente. Neste ponto, o banco de dados pode ser remontado a uma instância existente.

Em caso de falha, o mecanismo não pôde recuperar o banco de dados. O banco de dados está em um estado inválido e, para tentar novamente a recuperação rígida, todo o banco de dados deve ser restaurado novamente. Normalmente, a origem dessa situação é corrupção de disco ou log, ou alguma outra forma de má gestão de log ou um conjunto de logs não contínuo.

Comentários

Para entender como uma recuperação "difícil" funciona, você deve entender que há três fases de recuperação e que a segunda fase pode ter duas partes. Na Fase I, os logs são necessários para colocar um banco de dados de backup em consistência (ou um conjunto inicial de logs incrementais pode ser usado). Na Fase II, todos os logs adicionais de roll forward disponíveis são consumidos para tornar o banco de dados consistente. Também há uma reprodução dos logs de roll forward adicionais. A fase III é a fase desfazer da recuperação.

Fase I: a reprodução do conjunto de logs que deve ser restaurado para que o banco de dados seja levado a um estado consistente (ou um conjunto inicial de arquivos de log) é executada. Basicamente, essa é a reprodução do conjunto de arquivos de log que não são opcionais para os bancos de dados que estão sendo restaurados. Se houver logs ausentes desse intervalo de logs, a restauração falhará. Esses logs devem ser colocados no diretório especificado no parâmetro szBackupLogPath .

Fase II: opcionalmente, pode haver alguns conjuntos de arquivos de log que são arquivos de log roll forward provenientes de backups incrementais ou diferenciais e dos arquivos de log de uma instância ativa. No caso de arquivos de log de backups incrementais ou diferenciais, os arquivos de log podem ser colocados nos diretórios especificados nos parâmetros szBackupLogPath ou szTargetInstanceLogPath , sendo o primeiro o diretório recomendado. Os logs usados para a fase de roll forward (fase II) devem vir da mesma série de logs reproduzidos durante a Fase I e devem ter números de log incrementados continuamente sem lacunas dos logs da Fase I. Para reproduzir um banco de dados totalmente atualizado com os arquivos de log que estão sendo usados por uma instância ativa, os parâmetros szTargetInstanceLogPath e szTargetInstanceCheckpointPath devem ser especificados. Isso pode ser feito mesmo enquanto outros bancos de dados estão anexados a esse conjunto de logs.

Fase III: na fase final de recuperação, todas as transações não confirmadas são revertidas, o que requer a geração de novos arquivos de log e a atualização do arquivo de ponto de verificação. Às vezes, essa fase é chamada de "desfazer". O caminho do arquivo de ponto de verificação a ser usado durante essa fase é o caminho análogo ao local de log da fase III, ou seja, se szLogPath for usado para a Fase III, szCheckpointFilePath será usado, se szTargetInstanceLogPath for usado para a fase III da recuperação szTargetInstanceCheckpointPath será usado.

Para entender como os caminhos funcionam, use este fluxograma:

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.
Unicode	Implementado como JetExternalRestoreW (Unicode) e JetExternalRestoreA (ANSI).

Consulte Também

JET_ERR
JET_PFNSTATUS
JET_RSTMAP
JET_LOGINFO
JetBeginExternalBackup
JetInit