Fonction JetCreateInstance2

S’applique à : Windows | Windows Server

Fonction JetCreateInstance2

La fonction JetCreateInstance2 est utilisée pour allouer une nouvelle instance du moteur de base de données à utiliser dans un processus unique, avec un nom d’affichage spécifié.

Windows XP:JetCreateInstance2 est introduit dans 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
    );

Paramètres

Pinstance

Mémoire tampon de sortie qui recevra le instance nouvellement créé.

szInstanceName

Spécifie un identificateur de chaîne unique pour le instance à créer. Cette chaîne doit être unique au sein d’un processus donné hébergeant le moteur de base de données.

Note Une valeur NULL est traitée comme un identificateur de chaîne valide pour un instance. Un seul instance peut avoir un identificateur de chaîne NULL.

szDisplayName

Nom d’affichage du instance à créer. Lorsque ce paramètre n’est pas présent, sa valeur est présumée null.

grbit

Réservé pour un usage futur. Lorsque ce paramètre n’est pas présent, sa valeur est supposée être égale à zéro.

Valeur renvoyée

Cette fonction retourne le type de données JET_ERR avec l’un des codes de retour suivants. Pour plus d’informations sur les erreurs ESE possibles, consultez Erreurs du moteur de stockage extensible et Paramètres de gestion des erreurs.

Code de retour	Description
JET_errSuccess	L’opération s’est terminée avec succès.
JET_errInstanceNameInUse	Le nom de instance spécifié est déjà utilisé pour ce processus.
JET_errInvalidParameter	L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas logique lorsqu’elle était combinée à la valeur d’un autre paramètre. Cela peut se produire pour JetCreateInstance lorsque pinstance a la valeur NULL.
JET_errRunningInOneInstanceMode	L’opération a échoué, car elle ne peut pas être utilisée lorsque le moteur de base de données fonctionne en mode instance unique (mode de compatibilité Windows 2000).
JET_errTooManyInstances	Impossible de créer une nouvelle instance, car le nombre maximal d’instances a été atteint. Le nombre maximal d’instances prises en charge est configuré à l’aide de JetSetSystemParameter à l’aide de JET_paramMaxInstances.

En cas de réussite, une nouvelle instance sera allouée et son identificateur sera retourné. À ce stade, tous les paramètres système du instance auront les valeurs des paramètres système par défaut globaux. Une fois qu’une instance est allouée, elle doit être arrêtée et/ou libérée ultérieurement.

En cas d’échec, une erreur représentant la cause de l’échec est retournée et aucune instance n’est allouée.

Notes

Un instance doit être initialisé avec un appel à JetInit avant de pouvoir être utilisé par autre chose que JetSetSystemParameter.

Un instance est détruit par un appel à la fonction JetTerm, même si cette instance n’a jamais été initialisée à l’aide de JetInit. Le nombre maximal d’instances qui peuvent être créées à un moment donné est contrôlé par JET_paramMaxInstances, qui peut être configuré par un appel à JetSetSystemParameter. Une instance est l’unité de récupération du moteur de base de données. Il contrôle le cycle de vie de tous les fichiers utilisés pour protéger l’intégrité des données dans un ensemble de fichiers de base de données. Ces fichiers incluent le fichier de point de contrôle et les fichiers journaux des transactions.

Si la fonction réussit, le moteur de base de données passe automatiquement au mode multi-instance comme effet secondaire de cet appel. Si l’application souhaite autoriser une seule instance dans le processus, JetInit doit être utilisé pour démarrer le moteur de base de données en mode de compatibilité Windows 2000.

S’il est présent, le paramètre szDisplayName sera utilisé pour identifier les instance à des endroits tels que le journal des événements ou vers d’autres appelants comme les applications de sauvegarde (par le biais de fonctions telles que JetGetInstanceInfo ou JetOSSnapshotFreeze). Si le nom d’affichage n’est pas fourni, le paramètre unique szInstanceName est utilisé à la place, s’il est présent, sinon une chaîne vide est retournée. Si le mode d’exécution du moteur n’a pas été défini, après cet appel, il sera défini sur le mode multi-instance.

La séquence de démarrage classique pour un processus qui exécute potentiellement plusieurs instances Jet est la suivante :

• Appel à JetCreateInstance2 qui alloue et nomme le instance.

• Plusieurs appels à JetSetSystemParameter pour ce instance afin de définir différents paramètres système. Notez que certains paramètres système doivent être uniques pour chaque instance (par exemple, JET_paramSystemPath ou JET_paramLogFilePath).

• Démarrez le instance à l’aide de JetInit ou JetInit2. Pour mettre fin et/ou libérer une instance, utilisez JetTerm ou JetTerm2.

S’il s’agit de la première instance à démarrer, il existe un certain nombre d’étapes supplémentaires qui seront exécutées pendant cet appel afin d’effectuer l’initialisation et la configuration système de base. Un certain nombre de ces étapes peuvent entraîner des erreurs spécifiques, en commençant par JET_errOutOfMemory mais aussi d’autres (voir Valeurs de retour pour plus d’informations).

Spécifications

Condition requise	Valeur
Client	Nécessite Windows Vista ou Windows XP.
Serveur	Nécessite Windows Server 2008 ou Windows Server 2003.
En-tête	Déclaré dans Esent.h.
Bibliothèque	Utilisez ESENT.lib.
DLL	Nécessite ESENT.dll.
Unicode	Implémenté en tant que JetCreateInstance2W (Unicode) et JetCreateInstance2A (ANSI).

Voir aussi

JET_ERR
JET_INSTANCE
JetCreateInstance
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2