Fonction JetCreateInstance

  • Article

S’applique à : Windows | Windows Server

Fonction JetCreateInstance

La fonction JetCreateInstance alloue une nouvelle instance du moteur de base de données pour une utilisation dans un processus unique.

Windows XP : JetCreateInstance est introduit dans Windows XP.

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

Paramètres

Pinstance

Mémoire tampon de sortie qui reçoit le instance nouvellement créé.

szInstanceName

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.

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 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, l’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 :

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 commençant par JET_errOutOfMemory mais d’autres (voir les erreurs ci-dessus).

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

Voir aussi

Fichiers du moteur de stockage extensibles
JET_ERR
JET_INSTANCE
JetCreateInstance2
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2