Função JetDefragment2

Aplica-se a: Windows | Windows Server

Função JetDefragment2

A função JetDefragment2 inicia e interrompe tarefas de desfragmentação de banco de dados que melhoram a organização de dados em um banco de dados, com um parâmetro de retorno de chamada disponível para relatar o progresso da desfragmentação. Isso é feito para limitar o crescimento do banco de dados usando a alocação de disco existente de forma mais eficiente no banco de dados. Ele também pode reduzir o conjunto de trabalho garantindo que os dados sejam mais bem empacotados. Por fim, ele pode melhorar o desempenho do aplicativo acelerando as operações comuns por meio de uma melhor organização de dados.

O Windows XP:JetDefragment2 é introduzido no Windows XP.

JetDefragment2 também contém um parâmetro de função de retorno de chamada usado para relatar o progresso do processo de desfragmentação.

A desfragmentação de banco de dados é uma operação online e não interrompe a atividade regular do banco de dados, como operações de consulta ou atualizações de dados. JetDefragment2 também não faz uma cópia de todos os dados existentes. Em vez disso, ele desfragmenta um banco de dados em vigor. Por fim, JetDefragment2 recupera o espaço interno do banco de dados para reutilização, mas não libera espaço em excesso para o sistema de arquivos do sistema operacional.

O formato resultante dos dados pode ser muito mais eficiente, mas geralmente não é ideal. A desfragmentação é limitada à liberação de páginas de banco de dados para reutilização que contêm dados que já foram excluídos logicamente. A desfragmentação também disponibiliza páginas de banco de dados para reutilização em alguns casos combinando dados de duas páginas quando elas podem caber em uma única página.

Essa operação é diferente de JetCompact , que faz uma cópia de um banco de dados somente leitura em uma forma altamente ideal.

JET_ERR JET_API JetDefragment2(
  __in          JET_SESID sesid,
  __in          JET_DBID dbid,
  __in          JET_PCSTR szTableName,
  __out_opt     unsigned long* pcPasses,
  __out_opt     unsigned long* pcSeconds,
  __in          JET_CALLBACK callback,
  __in          JET_GRBIT grbit
);

Parâmetros

sesid

A sessão a ser usada para essa chamada.

dbid

O banco de dados a ser desfragmentador.

szTableName

Às vezes , szTableName é necessário e, às vezes, é proibido:

grbit	szTableName
JET_bitDefragmentBTreeBatch	Deve ser NULL.
JET_bitDefragmentBTree	Especifica o nome da tabela/BTree para desfragmentar.
other	Deve ser NULL.

A desfragmentação é executada para todo o banco de dados descrito pela ID de banco de dados fornecida.

pcPasses

Ao iniciar uma tarefa de desfragmentação online, esse parâmetro de entrada opcional define o número máximo de aprovações de desfragmentação. Ao interromper uma tarefa de desfragmentação online, esse buffer de saída opcional é definido como o número de passes executados.

Quando esse parâmetro é definido como NULL, o número de aprovações de desfragmentação online é ilimitado.

pcSeconds

Ao iniciar uma tarefa de desfragmentação online, esse parâmetro de entrada opcional define o tempo máximo para desfragmentação. Ao interromper uma tarefa de desfragmentação online, esse buffer de saída opcional é definido como o período de tempo usado para desfragmentação.

Quando esse parâmetro é definido como NULL ou se pcSeconds aponta para um valor negativo, o tempo máximo para desfragmentação é ilimitado.

callback

Função de retorno de chamada que a desfragmentação chama regularmente para relatar o progresso.

grbit	szTableName
JET_bitDefragmentBTreeBatch	Deve ser NULL.
JET_bitDefragmentBTree	Deve ser NULL.
other	Opcional.

grbit

Um grupo de bits que especifica zero ou mais das opções a seguir.

Valor	Significado
JET_bitDefragmentAvailSpaceTreesOnly	Essa opção é usada para desfragmentar a parte de espaço disponível da alocação de espaço de banco de dados do ESE. O espaço do banco de dados é dividido em dois tipos, espaço de propriedade e espaço disponível. O espaço de propriedade é alocado para uma tabela ou índice enquanto o espaço disponível está pronto para uso dentro da tabela ou índice, respectivamente. O espaço disponível é muito mais dinâmico no comportamento e requer desfragmentação online mais do que o espaço de propriedade, tabela ou dados de índice.
JET_bitDefragmentBatchStart	Essa opção é usada para iniciar uma nova tarefa de desfragmentação.
JET_bitDefragmentBatchStop	Essa opção é usada para interromper uma tarefa de desfragmentação iniciada existente.
JET_bitDefragmentBTree	Essa opção é usada para desfragmentar uma Árvore B, especificada por szTableName.
JET_bitDefragmentBTreeBatch	Essa opção é usada para chamar OLD2 em todo o banco de dados.

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_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_errDatabaseFileReadOnly	O banco de dados escolhido para desfragmentação é somente leitura e não pode ser atualizado de forma alguma, incluindo desfragmentação.
JET_errDistributedTransactionAlreadyPreparedToCommit	A sessão fornecida está preparada para confirmar o estado e não pode iniciar novas atualizações até que a transação atual seja confirmada ou revertida.
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_errInvalidDatabaseId	A ID de banco de dados fornecida não corresponde a um banco de dados conhecido na instância.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
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. 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	A sessão fornecida tem privilégios somente leitura e não pode iniciar uma tarefa que pode executar uma atualização, incluindo desfragmentação.
JET_errVersionStoreOutOfMemory	Esse erro ocorrerá quando o tamanho configurado do repositório de versão for insuficiente para manter todas as atualizações pendentes.
JET_wrnDefragAlreadyRunning	A opção JET_bitDefragmentBatchStart foi passada, mas uma tarefa de desfragmentação já está executando a desfragmentação no banco de dados especificado.
JET_wrnDefragNotRunning	A opção JET_bitDefragmentBatchStop foi passada, mas nenhuma tarefa de desfragmentação está em execução no momento.

Em caso de êxito, a ação solicitada de iniciar uma tarefa de desfragmentação para determinados dados com determinadas opções é executada ou a ação de interromper uma tarefa de desfragmentação existente é executada.

Em caso de falha, a ação solicitada de iniciar ou parar um trabalho de desfragmentação online não é feita. Nenhum outro efeito colateral ocorre.

Comentários

A desfragmentação online é controlada por uma configuração de parâmetro, bem como por essa API. O valor padrão do parâmetro do sistema é JET_OnlineDefragAll, o que significa que a desfragmentação está habilitada para todas as estruturas de dados com suporte. No entanto, usando JetSetSystemParameter, é possível desabilitar a desfragmentação online ou habilitá-la seletivamente somente para árvores de espaço de banco de dados, somente bancos de dados, somente arquivos de streaming ou qualquer combinação dessas opções. Se a configuração do sistema para desfragmentação on-line for para uma configuração obsoleta, JetDefragment2 tratará a configuração como JET_OnlineDefragAll.

No máximo, pode haver uma tarefa em execução para cada banco de dados. A tarefa é executada como um thread no processo que hospeda o ESE.

A sessão usada para iniciar a tarefa de desfragmentação online pode ser usada posteriormente para operações de banco de dados enquanto a tarefa de desfragmentação continua, porque a tarefa de desfragmentação aloca sua própria sessão. A sessão fornecida é usada apenas para marcar as permissões associadas à sessão inicial da tarefa e não é realmente usada para as próprias operações de desfragmentaçã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 JetDefragment2W (Unicode) e JetDefragment2A (ANSI).

Consulte Também

JET_ERR
JET_SESID
JetCompact
JetDefragment
JetSetSystemParameter
JetStopService