Função JetReadFile

Aplica-se a: Windows | Windows Server

Função JetReadFile

A função JetReadFile recupera o conteúdo de um arquivo aberto com JetOpenFile.

    JET_ERR JET_API JetReadFile(
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcbActual
    );

Parâmetros

hfFile

O identificador do arquivo a ser lido.

pv

Buffer de saída que receberá os dados do arquivo.

cb

O tamanho máximo em bytes do buffer de saída.

pcbActual

Recebe a quantidade real de dados de arquivo recuperados.

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_errBackupAbortByServer	A operação falhou porque o backup externo atual foi anulado por uma chamada para JetStopService. Esse erro só será retornado pelo Windows XP e versões posteriores.
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	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 JetReadFile quando: O identificador de instância especificado é inválido. Windows XP e versões posteriores. O tamanho do buffer de saída não é um múltiplo do tamanho da página do banco de dados (JET_paramDatabasePageSize). Windows XP e versões posteriores. O tamanho do buffer de saída é menor que três páginas de banco de dados (JET_paramDatabasePageSize) e essa é a primeira chamada para JetReadFile para o identificador especificado. Windows XP e versões posteriores.
JET_errNoBackup	A operação falhou porque nenhum backup externo está em andamento.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errReadVerifyFailure	A operação falhou porque dados não recuperáveis corrompidos foram detectados durante a leitura de uma página de banco de dados de um arquivo de banco de dados ou arquivo de patch de banco de dados.
JET_errLogReadVerifyFailure	A operação falhou porque dados não recuperáveis corrompidos foram detectados durante a leitura de um arquivo de log de transações. Esse erro só será retornado pelo Windows XP e versões posteriores.
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_errRunningInMultiInstanceMode	A operação falhou porque foi feita uma tentativa de usar o mecanismo no modo herdado (modo de compatibilidade do Windows 2000) em que apenas uma instância tem suporte quando, na verdade, várias instâncias já existem.
JET_errTermInProgress	Não é possível concluir a operação porque a instância associada à sessão está sendo desligada.

Em caso de êxito, a próxima parte dos dados do arquivo será lida no buffer de saída. O número real de bytes recuperados também será retornado. O deslocamento de arquivo no qual a próxima leitura ocorrerá será avançado por esse valor.

Em caso de falha, o estado do buffer de saída é indefinido. A falha resultará no cancelamento de todo o processo de backup para a instância. No Windows XP e versões posteriores, o backup não será cancelado se ocorrer um erro ao ler um arquivo de banco de dados. No entanto, o backup desse arquivo de banco de dados ainda será cancelado e o identificador correspondente será fechado automaticamente.

Comentários

Qualquer chamada para JetReadFile usando um identificador que já retornou todos os dados no arquivo subjacente (como uma chamada anterior retornada menos bytes do que o tamanho do buffer de saída) sempre terá êxito, mas retornará zero bytes de dados.

Um buffer de saída grande deve ser usado para maximizar o desempenho do backup. Algumas experimentações podem ser necessárias para encontrar a compensação certa entre o consumo de recursos e a taxa de transferência para uma determinada situação. O buffer de saída não deve ser menor que 64 KB em qualquer caso.

Não há suporte para várias chamadas simultâneas para JetReadFile usando o mesmo identificador de arquivo. Isso significa que não é possível enfileirar vários buffers para leitura simultânea no mesmo arquivo para obter alta taxa de transferência sequencial. Em vez disso, um único buffer grande deve ser usado.

Se a instância estiver configurada de modo que a depuração de página de banco de dados esteja habilitada (consulte JET_paramZeroDatabaseDuringBackup em Parâmetros do Sistema), os dados excluídos serão removidos do banco de dados como um efeito colateral de uma chamada para JetReadFile no arquivo de banco de dados.

É muito importante entender como o backup e a corrupção de dados interagem. Se o mecanismo de banco de dados detectar dados corrompidos durante um backup, ele falhará no backup do banco de dados afetado ou de toda a instância. Essa é uma decisão de design consciente destinada a proteger contra perda de dados. Se o mecanismo de banco de dados permitiu que um backup tivesse êxito quando os dados corrompidos estavam presentes, é possível que um backup mais antigo e não corrompido possa ser descartado como resultado. Isso seria lamentável porque seria possível corrigir os dados corrompidos na instância dinâmica restaurando esse backup e reproduzindo todos os arquivos de log de transações nesse banco de dados. Esse cenário de perda de dados zero pressupõe que o log circular não está habilitado (consulte JET_paramCircularLog em Parâmetros do Sistema).

Também é importante entender que quando dados corrompidos estiverem presentes, o backup de streaming será o lugar mais provável em que ele será detectado pela primeira vez. Esse é o caso porque o backup de streaming é o único processo que examina rotineiramente cada página do arquivo de banco de dados. Também é provável que o backup de streaming seja o primeiro processo a detectar os primeiros sinais de falha de hardware, conforme manifestado por erros intermitentes de corrupção de dados. Isso ocorre devido à quantidade de dados recuperados pelo backup, bem como à velocidade em que são recuperados.

Dados corrompidos são detectados pelo mecanismo de banco de dados por meio do uso de somas de verificação de bloco. Essas somas de verificação são definidas pouco antes de uma gravação de página de banco de dados e são verificadas em uma página de banco de dados lida. Esse esquema permite que o mecanismo de banco de dados determine que os dados foram corrompidos em algum momento, mas não permite que o mecanismo de banco de dados determine a origem dessa corrupção. Historicamente, a causa predominante dessa corrupção tem sido encontrada a partir de fontes diferentes do próprio mecanismo de banco de dados.

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_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
Parâmetros do sistema