Função JetCreateInstance

Aplica-se a: Windows | Windows Server

Função JetCreateInstance

A função JetCreateInstance aloca uma nova instância do mecanismo de banco de dados para uso em um único processo.

Windows XP: o JetCreateInstance é introduzido no Windows XP.

    JET_ERR JET_API JetCreateInstance(
      __out         JET_INSTANCE* pinstance,
      __in_opt      const tchar* szInstanceName
    );

Parâmetros

pinstance

O buffer de saída que recebe a instância recém-criada.

szInstanceName

Um identificador de cadeia de caracteres exclusivo para a instância a ser criada. Essa cadeia de caracteres deve ser exclusiva em um determinado processo que hospeda o mecanismo de banco de dados.

Observação Um valor nulo é tratado como um identificador de cadeia de caracteres válido para uma instância. Somente uma instância pode ter um identificador de cadeia de caracteres nulo.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos códigos de retorno a seguir. Para obter mais informações sobre os possíveis erros do ESE, consulte erros do mecanismo de armazenamento extensível e parâmetros de tratamento de erros.

Código de retorno

Descrição

JET_errSuccess

A operação foi concluída com sucesso.

JET_errInstanceNameInUse

O nome de instância especificado já está em uso para este processo.

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 ocorrer para JetCreateInstance quando pinstance é nulo.

JET_errRunningInOneInstanceMode

A operação falhou porque não pode ser usada quando o mecanismo de banco de dados está operando em modo de instância única (modo de compatibilidade do Windows 2000).

JET_errTooManyInstances

Não foi possível criar uma nova instância porque o número máximo de instâncias foi atingido. O número máximo de instâncias com suporte é configurado usando o JetSetSystemParameter usando JET_paramMaxInstances.

Em caso de êxito, uma nova instância será alocada e o identificador para ela será retornado. Neste ponto, todos os parâmetros do sistema para a instância terão os valores dos parâmetros do sistema padrão global. Depois que uma instância for alocada, ela precisará ser terminada e/ou liberada mais tarde.

Em caso de falha, um erro que representa a causa da falha será retornado e nenhuma instância será alocada.

Comentários

Uma instância deve ser inicializada com uma chamada para JetInit antes que possa ser usada por algo diferente de JetSetSystemParameter.

Uma instância é destruída por uma chamada para a função JetTerm , mesmo que essa instância nunca tenha sido inicializada usando JetInit. O número máximo de instâncias que podem ser criadas a qualquer momento é controlado por JET_paramMaxInstances, que pode ser configurado por uma chamada para JetSetSystemParameter. Uma instância é a unidade de capacidade de recuperação para o mecanismo de banco de dados. Ele controla o ciclo de vida de todos os arquivos usados para proteger a integridade dos dados em um conjunto de arquivos de banco de dado. Esses arquivos incluem o arquivo de ponto de verificação e os arquivos de log de transações.

Se a função for bem sucedido, o mecanismo de banco de dados será automaticamente alterado para o modo de várias instâncias como um efeito colateral dessa chamada. Se o aplicativo desejar permitir apenas uma instância no processo, JetInit deverá ser usado para iniciar o mecanismo de banco de dados no modo de compatibilidade do Windows 2000.

Se houver, o szDisplayName será usado para identificar a instância em locais como o log de eventos ou para outros chamadores, como aplicativos de backup (por meio de funções como JetGetInstanceInfo ou JetOSSnapshotFreeze). Se o nome de exibição não for fornecido, o szInstanceName exclusivo será usado, em vez disso, se estiver presente, caso contrário, uma cadeia de caracteres vazia será retornada. Se o mecanismo não tiver o modo de execução definido, após essa chamada, ele será definido como modo de várias instâncias.

A sequência de inicialização típica para um processo que potencialmente executa várias instâncias do Jet seria:

Se esta for a primeira instância a ser iniciada, haverá várias etapas adicionais que serão executadas durante essa chamada para fazer a inicialização e a configuração básica do sistema. Várias etapas podem resultar em erros específicos, começando com JET_errOutOfMemory, mas outros também (consulte os erros acima).

Requisitos

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 JetCreateInstanceW (Unicode) e JetCreateInstanceA (ANSI).

Consulte Também

Arquivos do mecanismo de armazenamento extensível
JET_ERR
JET_INSTANCE
JetCreateInstance2
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2