Função JetCreateDatabase

Artigo
06/13/2023

Aplica-se a: Windows | Windows Server

Função JetCreateDatabase

A função JetCreateDatabase cria e anexa um arquivo de banco de dados a ser usado com o mecanismo de banco de dados ESE. Chamar JetCreateDatabase2 com cpgDatabaseSizeMax definido como zero é idêntico a chamar JetCreateDatabase com szConnect definido como NULL. Atualmente, até sete bancos de dados podem ser criados por instância.

    JET_ERR JET_API JetCreateDatabase(
      __in          JET_SESID sesid,
      __in          JET_PCSTR szFilename,
      __in_opt      JET_PCSTR szConnect,
      __out         JET_DBID* pdbid,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

O contexto de sessão de banco de dados a ser usado para a chamada à API.

szFilename

O nome do banco de dados a ser criado.

szConnect

Reservado para uso futuro. Definido como NULL.

pdbid

Ponteiro para um buffer que, em uma chamada bem-sucedida, contém o identificador do banco de dados. Em caso de falha, o valor é indefinido.

grbit

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

Valor	Significado
JET_bitDbOverwriteExisting	Por padrão, se JetCreateDatabase for chamado e o banco de dados já existir, a chamada à API falhará e o banco de dados original não será substituído. JET_bitDbOverwriteExisting altera esse comportamento e o banco de dados antigo será substituído por um novo. Windows XP e posterior.
JET_bitDbRecoveryOff	JET_bitDbRecoveryOff desativa o registro em log. Definir esse bit perde a capacidade de reproduzir arquivos de log e recuperar o banco de dados para um estado utilizável consistente após um evento catastrófico.
JET_bitDbShadowingOff	Definir JET_bitDbShadowingOff desabilitará a duplicação de algumas estruturas de banco de dados internas (sombreamento). A duplicação dessas estruturas é feita para resiliência, portanto, a configuração JET_bitDbShadowingOff removerá essa resiliência.

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_errDatabaseDuplicate	O banco de dados nomeado em szFilename já existe. Quando esse erro é retornado, o banco de dados não é anexado.
JET_errDatabaseInUse	Pode ser retornado se o acesso exclusivo tiver sido solicitado, mas não puder ser concedido ou se outra sessão já tiver aberto o banco de dados exclusivamente.
JET_errDatabaseInvalidPages	Retornado quando cpgDatabaseSizeMax é maior que o número máximo de páginas permitidas em um banco de dados. O máximo atual é 2147483646 (0x7ffffffe).
JET_errDatabaseInvalidPath	Um caminho inválido foi fornecido em szFilename. szFilename deve ser não NULL. Por padrão, szFilename deve apontar para um diretório existente. O caminho será criado se JET_paramCreatePathIfNotExist estiver definido (consulte JetSetSystemParameter).
JET_errDatabaseLocked	Indica que outra sessão já abriu o banco de dados exclusivamente (usando JET_bitDbExclusive).
JET_errDatabaseNotFound	O banco de dados não foi anexado anteriormente (consulte JetAttachDatabase).
JET_errDatabaseSharingViolation	O arquivo de banco de dados já foi anexado por uma sessão diferente.
JET_errInTransaction	Foi feita uma tentativa de criar um banco de dados durante uma transação.
JET_errInvalidDatabase	Foi feita uma tentativa de abrir um arquivo que não é um arquivo de banco de dados válido.
JET_errOneDatabasePerSession	Foi feita uma tentativa de abrir mais de um banco de dados e JET_paramOneDatabasePerSession foi definido. Consulte Parâmetros de banco de dados.
JET_errOutOfMemory	A operação falhou porque a memória não pôde ser alocada.
JET_errTooManyAttachedDatabases	Somente um número finito de banco de dados pode ser anexado por instância. Atualmente, o limite é de sete bancos de dados por instância.
JET_wrnDatabaseAttached	Um aviso não fatal que indica que o arquivo de banco de dados já foi anexado por esta sessão.
JET_wrnFileOpenReadOnly	JET_wrnFileOpenReadOnly indica que o arquivo foi anexado somente leitura, mas JetCreateDatabase não passou JET_bitDbReadOnly. O banco de dados ainda é aberto com acesso somente leitura.

Comentários

Se o banco de dados especificado em szFilename existir e JET_bitDbOverwriteExisting não tiver sido passado, a chamada à API falhará. Se JET_bitDbOverwriteExisting tiver sido passado, o arquivo de banco de dados antigo será excluído primeiro.

Se a API criar um arquivo de banco de dados e, em seguida, atingir outro erro, ela limpo e excluirá o arquivo.

JetCreateDatabase abrirá implicitamente o banco de dados. Não é necessariamente chamar JetOpenDatabase posteriormente.

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.
Unicode	Implementado como JetCreateDatabaseW (Unicode) e JetCreateDatabaseA (ANSI).

Consulte Também

Arquivos extensíveis do mecanismo de armazenamento
JET_ERR
JET_DBID
JET_GRBIT
JET_SESID
JetAttachDatabase
JetCloseDatabase
JetCreateDatabase2
JetOpenDatabase
JetSetSystemParameter
Parâmetros do sistema

Função JetCreateDatabase