Função JetReadFileInstance

Artigo
06/13/2023

Aplica-se a: Windows | Windows Server

Função JetReadFileInstance

A função JetReadFileInstance recupera o conteúdo de um arquivo aberto com a função JetOpenFileInstance .

Windows XP: JetReadFileInstance é introduzido no Windows XP.

    JET_ERR JET_API JetReadFileInstance(
      __in          JET_INSTANCE instance,
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcb
    );

Parâmetros

instance

A instância a ser usada para uma chamada à API específica.

Observe que, para o Windows 2000, a variante de API que aceita esse parâmetro não está disponível porque há suporte apenas para uma instância. O uso dessa instância global está implícito nesse caso.

Para o Windows XP e versões posteriores, você pode chamar a variante de API que não aceita esse parâmetro somente quando o mecanismo está no modo herdado (modo de compatibilidade do Windows 2000) nos casos em que há suporte apenas para uma instância. Caso contrário, a operação falhará e retornará o erro JET_errRunningInMultiInstanceMode.

hfFile

O identificador do arquivo a ser lido.

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

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

Pcb

A quantidade real de dados de arquivo recuperados.

Valor Retornado

Essa função facilita o retorno de qualquer JET_ERR tipos de dados definidos na API do Mecanismo de Armazenamento Extensível (ESE). Para obter mais informações sobre erros jet, consulte Erros extensíveis do mecanismo de armazenamento e parâmetros de tratamento de erros.

Código de retorno	Significado
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 a função JetStopService . Esse erro será retornado somente pelo Windows XP e versões posteriores do Windows.
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 a função 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 será retornado somente pelo Windows XP e versões posteriores do Windows.
JET_errInvalidParameter	Um dos parâmetros especificados continha um valor inesperado ou um valor que não fazia sentido quando combinado com o valor de outro parâmetro. Isso pode acontecer para a função JetReadFileInstance quando qualquer um dos seguintes ocorre: O identificador de instância especificado é inválido. Windows XP e versões posteriores do Windows. 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 do Windows. 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 a função JetReadFileInstance para o identificador especificado. Windows XP e versões posteriores do Windows.
JET_errLogReadVerifyFailure	A operação falhou porque dados corrompidos irrecuperáveis foram detectados durante a leitura de um arquivo de log de transações. Esse erro será retornado somente pelo Windows XP e versões posteriores do Windows.
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 a esta sessão ainda não foi inicializada.
JET_errReadVerifyFailure	A operação falhou porque dados corrompidos irrecuperáveis 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_errRestoreInProgress	Não é possível concluir a operação porque uma operação de restauração está em andamento na instância associada a esta 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 um caso em que apenas uma instância tem suporte, mas já existem várias instâncias.
JET_errTermInProgress	Não é possível concluir a operação porque a instância associada a esta 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 atual. No Windows XP e versões posteriores do Windows, 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 a função JetReadFileInstance feita usando um identificador que já retornou todos os dados no arquivo subjacente (como se uma chamada anterior retornasse menos bytes do que o tamanho do buffer de saída) sempre terá êxito, mas retornará zero bytes de dados.

Você deve usar um buffer de saída grande para maximizar o desempenho do backup. Talvez seja necessário experimentar para encontrar a compensação ideal entre o consumo de recursos e a taxa de transferência para uma situação específica. De qualquer forma, o buffer de saída não deve ser menor que 64 KB. O ponteiro que você passa para JetReadFileInstance deve ser alinhado com um limite de página de memória (4 KB ou 8 KB). Você pode fazer isso chamando a função VirtualAlloc .

Não há suporte para várias chamadas simultâneas para JetReadFileInstance feitas 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, você deve usar um único buffer grande.

Se você tiver configurado uma instância específica de modo que a depuração de página do banco de dados esteja habilitada (consulte o parâmetro JET_paramCircularLog em Parâmetros do Sistema), os dados excluídos serão removidos do banco de dados como um efeito colateral de uma chamada para JetReadFileInstance 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 havia dados corrompidos, é possível que um backup mais antigo e não corrompido possa ser descartado como resultado. Isso seria lamentável porque, em seguida, 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 presume que o log circular não está habilitado (consulte JET_paramCircularLog em Parâmetros do Sistema).

Também é importante entender que os casos de corrupção de dados geralmente são detectados pela primeira vez durante o backup de streaming. Isso ocorre 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 para detectar os primeiros sinais de falha de hardware, conforme manifestado por erros intermitentes de corrupção de dados, devido à quantidade de dados recuperados pelo backup e à velocidade com que esses dados 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, as instâncias desses dados corrompidos se originaram de fontes diferentes do próprio mecanismo de banco de dados.

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	Usa ESENT.lib.
DLL	Requer ESENT.dll.

Consulte Também

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Parâmetros do sistema

Compartilhar via

Função JetReadFileInstance