Fonction JetOpenTempTable

  • Article

S’applique à : Windows | Windows Server

Fonction JetOpenTempTable

La fonction JetOpenTempTable crée une table temporaire avec un seul index. Une table temporaire stocke et récupère les enregistrements comme une table ordinaire créée à l’aide de JetCreateTableColumnIndex. Toutefois, les tables temporaires sont beaucoup plus rapides que les tables ordinaires en raison de leur nature volatile. Ils peuvent également être utilisés pour trier et effectuer très rapidement la suppression des doublons sur les jeux d’enregistrements lorsqu’ils sont accessibles de manière purement séquentielle.

    JET_ERR JET_API JetOpenTempTable(
      __in          JET_SESID sesid,
      __in          const JET_COLUMNDEF* prgcolumndef,
      __in          unsigned long ccolumn,
      __in          JET_GRBIT grbit,
      __out         JET_TABLEID* ptableid,
      __out         JET_COLUMNID* prgcolumnid
    );

Paramètres

sesid

Session à utiliser.

prgcolumndef

Définitions de colonnes pour les colonnes créées dans la table temporaire.

Il existe des limitations importantes pour les options de définition de colonne utilisées avec une table temporaire. Pour plus d'informations, consultez la section Notes.

En plus des options de définition de colonne habituelles, zéro ou plusieurs des options suivantes peuvent également être spécifiées qui ne sont pertinentes que dans le contexte d’une table temporaire.

Valeur

Signification

JET_bitColumnTTDescending

L’ordre de tri de la colonne clé de la table temporaire doit être décroissant plutôt que croissant. Si cette option est spécifiée sans JET_bitColumnTTKey cette option est ignorée.

JET_bitColumnTTKey

La colonne sera une colonne clé pour la table temporaire.

L’ordre des définitions de colonne avec cette option spécifiée dans le tableau d’entrée détermine la priorité de chaque colonne clé pour la table temporaire. La première définition de colonne dans le tableau qui a ce jeu d’options sera la colonne clé la plus significative, et ainsi de suite. Si plus de colonnes clés sont demandées que le moteur de base de données ne peut le prendre en charge, cette option est ignorée pour les colonnes clés non prises en charge.

ccolumn

Consultez prgcolumndef.

grbit

Groupe de bits spécifiant zéro ou plusieurs des options suivantes.

Valeur

Signification

JET_bitTTErrorOnDuplicateInsertion

Toute tentative d’insertion d’un enregistrement avec la même clé d’index qu’un enregistrement précédemment inséré échouera immédiatement avec JET_errKeyDuplicate. Si cette option n’est pas demandée, un doublon est détecté immédiatement et échoue, ou est supprimé en mode silencieux ultérieurement, en fonction de la stratégie choisie par le moteur de base de données pour implémenter la table temporaire, en fonction des fonctionnalités demandées.

Si cette fonctionnalité n’est pas requise, il est préférable de ne pas la demander. Si cette fonctionnalité n’est pas demandée, le gestionnaire de tables temporaire peut être en mesure de choisir une stratégie de gestion de la table temporaire qui se traduira par une amélioration des performances.

JET_bitTTForceMaterialization

Force le gestionnaire de tables temporaires à abandonner la recherche de la meilleure stratégie pour utiliser la gestion de la table temporaire qui entraînera une amélioration des performances.

JET_bitTTForwardOnly

La table temporaire est créée uniquement si le gestionnaire de tables temporaire peut utiliser l’implémentation optimisée pour les résultats de requête intermédiaires. Si une caractéristique de la table temporaire empêche l’utilisation de cette optimisation, l’opération échoue avec JET_errCannotMaterializeForwardOnlySort.

Un effet secondaire de cette option est d’autoriser la table temporaire à contenir des enregistrements avec des clés d’index en double. Pour plus d’informations, consultez JET_bitTTUnique.

Cette option est disponible uniquement sur Windows Server 2003 et versions ultérieures.

JET_bitTTIndexed

Cette option demande que la table temporaire soit suffisamment flexible pour permettre l’utilisation de JetSeek pour rechercher des enregistrements par clé d’index.

Si cette fonctionnalité n’est pas requise, il est préférable de ne pas la demander. Si cette fonctionnalité n’est pas demandée, le gestionnaire de tables temporaire peut être en mesure de choisir une stratégie de gestion de la table temporaire qui se traduira par une amélioration des performances.

JET_bitTTUnique

Demande que les enregistrements avec des clés d’index en double soient supprimés du jeu d’enregistrements final de la table temporaire.

Avant Windows Server 2003, le moteur de base de données supposait toujours que cette option était en vigueur, car tous les index cluster devaient également être une clé primaire et, par conséquent, être uniques. Depuis Windows Server 2003, il est désormais possible de créer une table temporaire qui ne supprime pas les doublons lorsque l’option JET_bitTTForwardOnly est également spécifiée.

Il n’est pas possible de savoir quel doublon réussira et quels doublons seront ignorés, en général. Toutefois, lorsque l’option JET_bitTTErrorOnDuplicateInsertion est demandée, le premier enregistrement avec une clé d’index donnée à insérer dans la table temporaire réussit toujours.

JET_bitTTUpdatable

Demande que la table temporaire soit suffisamment flexible pour permettre aux enregistrements précédemment insérés d’être modifiés par la suite. Si cette fonctionnalité n’est pas requise, il est préférable de ne pas la demander.

Si cette fonctionnalité n’est pas demandée, le gestionnaire de tables temporaire peut être en mesure de choisir une stratégie de gestion de la table temporaire qui se traduira par une amélioration des performances.

JET_bitTTScrollable

Demande que la table temporaire soit suffisamment flexible pour permettre l’analyse des enregistrements dans un ordre et une direction arbitraires à l’aide de JetMove.

Si cette fonctionnalité n’est pas requise, il est préférable de ne pas la demander. Si cette fonctionnalité n’est pas demandée, le gestionnaire de tables temporaire peut être en mesure de choisir une stratégie de gestion de la table temporaire qui se traduira par une amélioration des performances.

JET_bitTTSortNullsHigh

Demande que les valeurs de colonne clé NULL trient plus près de la fin de l’index que les valeurs de colonne de clé non NULL.

JET_bitTTIntrinsicLVsOnly

Demande d’autoriser uniquement les valeurs longues intrinsèques.

Windows 7 : JET_bitTTIntrinsicLVsOnly est introduit dans Windows 7.

ptableid

Mémoire tampon de sortie qui reçoit le nouveau curseur ouvert sur la table temporaire nouvellement créée.

prgcolumnid

Mémoire tampon de sortie qui reçoit le tableau des ID de colonne générés lors de la création de la table temporaire.

Les ID de colonne dans ce tableau correspondent exactement au tableau d’entrée des définitions de colonne. Par conséquent, la taille de cette mémoire tampon doit correspondre à la taille du tableau d’entrée.

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_errCannotMaterializeForwardOnlySort

Échec de JetOpenTempTable , car JET_bitTTForwardOnly a été spécifié et la table temporaire spécifiée n’a pas pu être créée à l’aide de l’optimisation avant uniquement. Cette erreur ne sera retournée que par Windows Server 2003 et versions ultérieures.

JET_errClientRequestToStopJetService

Il n’est pas possible d’effectuer l’opération, car toutes les activités sur le instance associée à la session ont cessé à la suite d’un appel à JetStopService.

JET_errIndexInvalidDef

Impossible de créer l’index, car une définition d’index non valide a été spécifiée.

JetOpenTempTable retourne cette erreur dans les cas suivants :

  • Les paramètres régionaux non linguistiques sont spécifiés.

  • Un ensemble d’indicateurs de normalisation non valides est spécifié.

Cette erreur ne sera retournée que par Windows 2000.

JET_errInstanceUnavailable

Il n’est pas possible d’effectuer l’opération, car le instance associé à la session a rencontré une erreur irrécupérable qui nécessite que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.

JET_errInvalidCodePage

Le champ cp du JET_COLUMNDEF n’a pas été défini sur une page de codes valide. Les seules valeurs valides pour les colonnes de texte sont Anglais (1252) et Unicode (1200). La valeur 0 signifie que la valeur par défaut sera utilisée (anglais, 1252).

JET_errInvalidColumnType

Le champ coltyp du JET_COLUMNDEF n’a pas été défini sur un type de colonne valide.

JET_errInvalidLanguageId

Impossible de créer l’index, car une tentative d’utilisation d’un ID de paramètres régionaux non valide a été effectuée. L’ID de paramètres régionaux peut être complètement non valide ou le module linguistique associé peut ne pas être installé.

JET_errInvalidLCMapStringFlags

L’index n’a pas pu être créé, car une tentative d’utilisation d’un ensemble d’indicateurs de normalisation non valides a été effectuée. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures. Sur Windows 2000, les indicateurs de normalisation non valides entraînent des JET_errIndexInvalidDef à la place.

JET_errInvalidSesid

Le handle de session n’est pas valide ou fait référence à une session fermée.

Note Cette erreur n’est pas retournée dans toutes les circonstances. Les handles sont validés uniquement sur la base du meilleur effort.

JET_errNotInitialized

Il n’est pas possible d’effectuer l’opération, car le instance associé à la session n’a pas encore été initialisé.

JET_errOutOfCursors

L’opération a échoué, car le moteur ne peut pas allouer les ressources nécessaires pour ouvrir un nouveau curseur. Les ressources de curseur sont configurées à l’aide de JetSetSystemParameter avec JET_paramMaxCursors.

JET_errOutOfMemory

L’opération a échoué, car il n’est pas possible d’allouer suffisamment de mémoire pour la terminer.

JetOpenTempTable peut retourner JET_errOutOfMemory si l’espace d’adressage du processus hôte devient trop fragmenté. Le gestionnaire de tables temporaire allouera toujours un segment d’espace d’adressage de 1 Mo pour chaque table temporaire créée, quelle que soit la quantité de données à stocker.

JET_errRestoreInProgress

Il n’est pas possible d’effectuer l’opération, car une opération de restauration est en cours sur le instance associé à la session.

JET_errSessionSharingViolation

La même session ne peut pas être utilisée pour plusieurs threads en même temps.

Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.

JET_errTermInProgress

Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt.

JET_errTooManyColumns

Une tentative d’ajout de trop de colonnes à la table a été effectuée. Une table ne peut pas avoir plus de JET_ccolFixedMost colonnes fixes, pas plus de JET_ccolVarMost colonnes de longueur variable et pas plus de JET_ccolTaggedMost colonnes étiquetées.

JET_errTooManyOpenIndexes

L’opération a échoué, car le moteur ne peut pas allouer les ressources nécessaires pour mettre en cache les index de la table. Le nombre d’index dont le schéma peut être mis en cache est configuré à l’aide de JetSetSystemParameter avec JET_paramMaxOpenTables.

JET_errTooManyOpenTables

L’opération a échoué, car le moteur ne peut pas allouer les ressources nécessaires pour mettre en cache le schéma de la table. Le nombre de tables dont le schéma peut être mis en cache est configuré à l’aide de JetSetSystemParameter avec JET_paramMaxOpenTables.

JET_errTooManySorts

L’opération a échoué, car le moteur ne peut pas allouer les ressources nécessaires à la création d’une table temporaire. Les ressources de table temporaires sont configurées à l’aide de JetSetSystemParameter avec JET_paramMaxTemporaryTables.

En cas de réussite, un curseur ouvert sur la table temporaire nouvellement créée est retourné. L’état de la base de données temporaire sera préparé pour contenir la nouvelle table temporaire. L’état des bases de données ordinaires utilisées par le moteur de base de données reste inchangé.

En cas d’échec, la table temporaire n’est pas créée et aucun curseur n’est retourné. L’état de la base de données temporaire peut être modifié. L’état des bases de données ordinaires utilisées par le moteur de base de données reste inchangé.

Notes

Les tables temporaires ne prennent pas en charge le complément complet des options de définition de colonne qui sont normalement prises en charge par le moteur de base de données. En fait, seuls les JET_bitColumnFixed et les JET_bitColumnTagged sont pris en charge. Cela signifie qu’il n’est pas possible de créer un incrément automatique, une version ou une colonne à valeurs multiples dans une table temporaire. Enfin, les colonnes de mise à jour d’entiercement ne sont pas prises en charge, car elles ne sont pas utiles dans une table temporaire, car elles ne peuvent être utilisées que par une session à la fois. Si l’une de ces options est demandée, elle sera ignorée.

Les tables temporaires ne prennent pas en charge les valeurs par défaut. Si une définition de colonne contenant une spécification de valeur par défaut est fournie, cette spécification sera ignorée.

Les tables temporaires sont retournées à l’appelant à la suite de nombreuses fonctions ESE différentes. Par exemple, JetGetIndexInfo avec l’option JET_IdxInfo définie dans le paramètre InfoLevel retourne une table temporaire contenant une liste de toutes les colonnes clés d’un index donné. Les tables temporaires suivent les mêmes règles de cycle de vie que les tables temporaires ordinaires, comme décrit ici.

Les tables temporaires sont également utilisées en interne par le moteur de base de données pour de nombreuses tâches. La plus importante de ces tâches est la création d’un index sur une table existante. Une table temporaire sera utilisée pour trier les clés d’index utilisées pour construire cet index.

Toutes les tables temporaires sont stockées dans la base de données temporaire. La base de données temporaire est un fichier de base de données spécial qui est conservé pendant la durée de vie d’un instance ESE et qui est supprimé lorsque cette instance est arrêtée ou redémarrée. L’emplacement de la base de données temporaire peut être configuré à l’aide de JetSetSystemParameter avec JET_paramTempPath. Le placement de la base de données temporaire sur le disque par rapport à vos fichiers journaux des transactions et fichiers de base de données peut être important si votre application utilise intensivement des tables temporaires ou crée fréquemment des index.

Le cycle de vie d’une table temporaire est lié aux curseurs qui la référencent. Si tous les curseurs qui font référence à une table temporaire sont fermés, implicitement ou explicitement, la table temporaire est supprimée. Si une table temporaire est créée à l’intérieur d’une transaction et que cette transaction est restaurée par la suite, la table temporaire est supprimée, car tous les curseurs qui l’ont référencée à ce stade seront implicitement fermés. Les nouveaux curseurs peuvent référencer une table temporaire uniquement via l’utilisation de JetDupCursor. Dans ce cas, les nouveaux curseurs seront positionnés sur la première entrée d’index de la table temporaire. JetDupCursor fonctionne uniquement pendant certaines phases d’utilisation de la table temporaire. Pour plus d’informations, consultez les remarques relatives aux fonctionnalités de curseur de table temporaires. Il n’est pas possible de référencer une table temporaire à partir de plusieurs sessions à la fois.

JetDupCursor présente un problème important qui affecte les tables temporaires. Si une tentative est effectuée pour dupliquer une table temporaire en mode avant uniquement, le curseur résultant n’est pas créé correctement et dysfonctionnement. Il est toujours sûr de dupliquer un curseur sur une table temporaire matérialisée.

Le gestionnaire de tables temporaire peut choisir d’implémenter une table temporaire de trois manières. La première méthode consiste à gérer une table en mémoire. Cette stratégie est la plus rapide, mais ne peut être utilisée que pour de petites tables temporaires simples. La deuxième méthode consiste à créer un tri sur disque qui peut être piloté à l’aide d’un itérateur avant uniquement. Cette stratégie ne peut être utilisée que dans certaines circonstances et constitue le moyen le plus rapide de trier et de supprimer les doublons d’un jeu de données très volumineux. La troisième méthode consiste à créer une arborescence B+ dans la base de données temporaire pour contenir la table temporaire. Cette stratégie est la plus lente, mais la plus polyvalente, et est appelée table temporaire matérialisée. Ces stratégies peuvent être utilisées conjointement pour obtenir les fonctionnalités demandées de la table temporaire.

Lorsque la table temporaire n’est pas matérialisée, elle est utilisée principalement dans deux phases majeures. La première phase est la phase d’insertion où la table est remplie avec son jeu de données initial. Pendant cette phase, seule l’insertion de données est autorisée. Cette phase se termine lorsqu’une tentative de déplacement du curseur est effectuée à l’aide de JetMove ou JetSeek. La deuxième phase est la phase d’extraction de données. Au cours de cette phase, les données stockées dans la table temporaire peuvent être extraites en fonction des fonctionnalités demandées lors de la création de la table temporaire.

Fonctionnalités de curseur de table temporaire

Lorsque la table temporaire est matérialisée, le curseur dispose des fonctionnalités suivantes, mais peut être davantage limité par les options demandées :

Lorsque la table temporaire n’est pas matérialisée et est en phase d’insertion, le curseur a les fonctionnalités suivantes, mais peut être davantage limité par les options demandées :

Lorsque la table temporaire n’est pas matérialisée et est en phase d’extraction, le curseur a les fonctionnalités suivantes, mais peut être davantage limité par les options demandées :

Spécifications

Condition requise Valeur

Client

Nécessite Windows Vista, Windows XP ou Windows 2000 Professionnel.

Serveur

Nécessite Windows Server 2008, Windows Server 2003 ou Windows 2000 Server.

En-tête

Déclaré dans Esent.h.

Bibliothèque

Utilisez ESENT.lib.

DLL

Nécessite ESENT.dll.

Voir aussi

JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_UNICODEINDEX
JetCloseTable
JetCreateTableColumnIndex
JetDupCursor
JetMove
JetRollback
JetSeek
JetSetSystemParameter
Paramètres de base de données temporaires