Funzione JetCreateInstance

Si applica a: Windows | Windows Server

Funzione JetCreateInstance

La funzione JetCreateInstance alloca una nuova istanza del motore di database da usare in un singolo processo.

Windows XP: JetCreateInstance viene introdotto in Windows XP.

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

Parametri

pinstance

Buffer di output che riceve l'istanza appena creata.

szInstanceName

Identificatore di stringa univoco per la creazione dell'istanza. Questa stringa deve essere univoca all'interno di un determinato processo che ospita il motore di database.

Nota Un valore NULL viene considerato come identificatore di stringa valido per un'istanza. Una sola istanza può avere un identificatore di stringa NULL.

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sugli errori ESE possibili, vedere Errori del motore di archiviazione estendibili e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errInstanceNameInUse	Il nome dell'istanza specificato è già in uso per questo processo.
JET_errInvalidParameter	Uno dei parametri forniti contiene un valore imprevisto o contiene un valore che non ha senso quando si combina con il valore di un altro parametro. Ciò può verificarsi per JetCreateInstance quando pinstance è NULL.
JET_errRunningInOneInstanceMode	L'operazione non è riuscita perché non può essere usata quando il motore di database è operativo in modalità singola istanza (modalità di compatibilità di Windows 2000).
JET_errTooManyInstances	Impossibile creare una nuova istanza perché è stato raggiunto il numero massimo di istanze. Il numero massimo di istanze supportate viene configurato usando JetSetSystemParameter usando JET_paramMaxInstances.

In caso di esito positivo, verrà allocata una nuova istanza e verrà restituito l'identificatore. A questo punto, tutti i parametri di sistema per l'istanza avranno i valori dei parametri di sistema predefiniti globali. Una volta allocata un'istanza, deve essere terminata e/o liberata in un secondo momento.

In caso di errore, verrà restituito un errore che rappresenta la causa dell'errore e non verrà allocata alcuna istanza.

Commenti

Un'istanza deve essere inizializzata con una chiamata a JetInit prima che possa essere usata da qualsiasi cosa diversa da JetSetSystemParameter.

Un'istanza viene eliminata da una chiamata alla funzione JetTerm , anche se tale istanza non è mai stata inizializzata usando JetInit. Il numero massimo di istanze che possono essere create in qualsiasi momento è controllato da JET_paramMaxInstances, che può essere configurato da una chiamata a JetSetSystemParameter. Un'istanza è l'unità di ripristinabilità per il motore di database. Controlla il ciclo di vita di tutti i file usati per proteggere l'integrità dei dati in un set di file di database. Questi file includono il file di checkpoint e i file di log delle transazioni.

Se la funzione ha esito positivo, il motore di database verrà modificato automaticamente in modalità multiistanza come effetto collaterale di questa chiamata. Se l'applicazione desidera consentire solo un'istanza nel processo, JetInit deve essere usata per avviare il motore di database in modalità di compatibilità di Windows 2000.

Se presente, szDisplayName verrà usato per identificare l'istanza in posizioni come Registro eventi o verso altri chiamanti come applicazioni di backup (tramite funzioni come JetGetInstanceInfo o JetOSnapshotFreeze). Se il nome visualizzato non viene specificato, verrà usato szInstanceName univoco se presente, altrimenti verrà restituita una stringa vuota. Se il motore non ha impostato la modalità di esecuzione, dopo questa chiamata, verrà impostato su modalità multiistanza.

La tipica sequenza di avvio per un processo potenzialmente in esecuzione di più istanze jet sarebbe:

• Chiamata a JetCreateInstance2 che alloca e denomina l'istanza.

• Più chiamate a JetSetSystemParameter per tale istanza per impostare parametri di sistema diversi. Si noti che alcuni parametri di sistema devono essere univoci per istanza (ad esempio JET_paramSystemPath o JET_paramLogFilePath) in modo più probabile che sia necessario impostare ognuno di questi elementi.

• Avviare l'istanza usando JetInit o JetInit2. Per terminare e/o liberare un'istanza, JetTerm, JetTerm2 deve essere usata.

Se si tratta della prima istanza da avviare, esistono diversi passaggi aggiuntivi che verranno eseguiti durante questa chiamata per eseguire l'inizializzazione e la configurazione di base del sistema. Alcuni di questi passaggi potrebbero causare errori specifici a partire da JET_errOutOfMemory ma anche altri (vedere gli errori precedenti).

Requisiti

Requisito	Valore
Client	Richiede Windows Vista o Windows XP.
Server	Richiede Windows Server 2008 o Windows Server 2003.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.
Unicode	Implementato come JetCreateInstanceW (Unicode) e JetCreateInstanceA (ANSI).

Vedere anche

File del motore di archiviazione estendibili
JET_ERR
JET_INSTANCE
JetCreateInstance2
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2