Compartilhar via

Função JetCreateInstance2

  • Artigo

Aplica-se a: Windows | Windows Server

Função JetCreateInstance2

A função JetCreateInstance2 é usada para alocar uma nova instância do mecanismo de banco de dados para uso em um único processo, com um nome de exibição especificado.

O Windows XP:JetCreateInstance2 é introduzido no Windows XP.

    JET_ERR JET_API JetCreateInstance2(
      __out         JET_INSTANCE* pinstance,
      __in_opt      const tchar* szInstanceName,
      __in_opt      const tchar* szDisplayName,
      __in          JET_GRBIT grbit
    );

Parâmetros

pinstance

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

szInstanceName

Especifica 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.

Nota Um valor NULL é 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 NULL.

Szdisplayname

Um nome de exibição para a instância a ser criada. Quando esse parâmetro não está presente, presume-se que seu valor seja NULL.

grbit

Reservado para uso futuro. Quando esse parâmetro não está presente, presume-se que seu valor seja zero.

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_errInstanceNameInUse

O nome da instância especificada já está em uso para esse 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 acontecer para JetCreateInstance quando pinstance é NULL.

JET_errRunningInOneInstanceMode

A operação falhou porque não pode ser usada quando o mecanismo de banco de dados está operando no 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 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 de sistema padrão globais. Depois que uma instância for alocada, ela precisará ser encerrada e/ou liberada posteriormente.

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 de poder ser usada por qualquer outra coisa que não seja 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 dados. Esses arquivos incluem o arquivo de ponto de verificação e os arquivos de log de transações.

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

Se presente, o parâmetro szDisplayName será usado para identificar a instância em locais como 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 parâmetro szInstanceName exclusivo será usado, se 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:

  • Uma chamada para JetCreateInstance2 que alocará e nomeará a instância.

  • Várias chamadas para JetSetSystemParameter para essa instância para definir parâmetros de sistema diferentes. Observe que alguns parâmetros do sistema precisam ser exclusivos para cada instância (como JET_paramSystemPath ou JET_paramLogFilePath), portanto, provavelmente, cada um deles precisará ser definido.

  • Inicie a instância usando JetInit ou JetInit2. Para encerrar e/ou liberar uma instância, use JetTerm ou JetTerm2.

Se essa 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ásicas do sistema. Várias dessas etapas podem resultar em erros específicos começando com JET_errOutOfMemory mas outros também (consulte Valores retornados para obter mais informações).

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 JetCreateInstance2W (Unicode) e JetCreateInstance2A (ANSI).

Consulte Também

JET_ERR
JET_INSTANCE
JetCreateInstance
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2