Structure JET_INDEXCREATE

Article
06/13/2023

S’applique à : Windows | Windows Server

La structure JET_INDEXCREATE contient les informations nécessaires pour créer un index sur des données dans une base de données ESE (Extensible Storage Engine). La structure est utilisée par des fonctions telles que JetCreateIndex2 et dans des structures telles que JET_TABLECREATE et JET_TABLECREATE2.

typedef struct tagJET_INDEXCREATE {
  unsigned long cbStruct;
  tchar* szIndexName;
  tchar* szKey;
  unsigned long cbKey;
  JET_GRBIT grbit;
  unsigned long ulDensity;
  union {
    unsigned long lcid;
    JET_UNICODEINDEX* pidxunicode;
  };
  union {
    unsigned long cbVarSegMac;
    JET_TUPLELIMITS* ptuplelimits;
  };
  JET_CONDITIONALCOLUMN* rgconditionalcolumn;
  unsigned long cConditionalColumn;
  JET_ERR err;
  unsigned long cbKeyMost;
} JET_INDEXCREATE;

Membres

cbStruct

Taille, en octets, de cette structure. Définissez ce membre sur sizeof( JET_INDEXCREATE ).

szIndexName

Nom de l’index à créer.

Le nom de l’index doit remplir les conditions suivantes :

Elle doit être inférieure à JET_cbNameMost, sans compter la valeur null de fin.
Elle doit se composer des caractères suivants : 0 (zéro) à 9, A à Z, a à z, et toutes les autres signes de ponctuation à l’exception de « ! » (point d’exclamation), « , » (virgule), « [ » (crochet ouvrant) et « ] » (crochet fermant) : c’est-à-dire, les caractères ASCII 0x20, 0x22 par 0x2d, 0x2f par 0x5a, 0x5c 0x5d par 0x7f.
Il ne doit pas commencer par un espace.
Il doit se composer d’au moins un caractère non-espace.

szKey

Pointeur vers une chaîne de jetons délimités par des valeurs Null à double terminaison null.

Chaque jeton se présente sous la forme «< nom-colonne-spécificateur><de> direction », où direction-specification est « + » ou « - ». Par exemple, une szKey de « +abc\0-def\0+ghi\0 » s’indexe sur les trois colonnes « abc » (dans l’ordre croissant), « def » (dans l’ordre décroissant) et « ghi » (dans l’ordre croissant). Dans le langage C, les littéraux de chaîne ont un terminateur NULL implicite ; par conséquent, la chaîne ci-dessus se termine par une valeur double NULL.

Le nombre de colonnes spécifiées dans szKey ne peut pas dépasser la valeur de JET_ccolKeyMost (constante dépendante de la version).

Au moins une colonne doit être nommée dans szKey.

Comportement obsolète : après la marque de fin double NULL, il est possible de spécifier un ID de langue (un MOT qui est passé dans MAKELCID( langid, SORT_DEFAULT ) pour spécifier le LCID pour l’index. Il n’est pas autorisé à spécifier un ID de langue dans szKey et un LCID dans JET_UNICODEINDEX (en définissant JET_bitIndexUnicode dans grbit).

Déconseillé : après l’ID de langue, il est possible de passer cbVarSegMac en tant que USHORT. Le comportement n’est pas défini si l’USHORT est défini à la fois dans szKey et si cbVarSegMac est défini dans la structure.

cbKey

Longueur, en octets, de szKey , y compris les deux valeurs null de fin.

grbit

Groupe de bits qui inclut zéro ou plus des valeurs répertoriées dans le tableau suivant.

Valeur	Signification
JET_bitIndexUnique	Les entrées d’index en double (clés) ne sont pas autorisées. Cela s’applique lorsque JetUpdate est appelé, et non lorsque JetSetColumn est appelé.
JET_bitIndexPrimary	L’index est un index principal (cluster). Chaque table doit avoir exactement un index principal. Si aucun index principal n’est explicitement défini sur une table, le moteur de base de données crée son propre index principal.
JET_bitIndexDisallowNull	Aucune des colonnes sur lesquelles l’index est créé ne peut contenir de valeur NULL .
JET_bitIndexIgnoreNull	N’ajoutez pas d’entrée d’index pour une ligne si toutes les colonnes indexées sont NULL.
JET_bitIndexIgnoreAnyNull	N’ajoutez pas d’entrée d’index pour une ligne si l’une des colonnes indexées est NULL.
JET_bitIndexIgnoreFirstNull	N’ajoutez pas d’entrée d’index pour une ligne si la première colonne indexée est NULL.
JET_bitIndexLazyFlush	Les opérations d’index sont consignées par voie différée. JET_bitIndexLazyFlush n’affecte pas la paresse des mises à jour des données. Si l’opération d’indexation est interrompue par l’arrêt du processus, la récupération réversible peut toujours obtenir un état cohérent de la base de données, mais l’index peut ne pas être présent.
JET_bitIndexEmpty	N’essayez pas de générer l’index, car toutes les entrées sont évaluées à NULL. grbit doit également spécifier JET_bitIgnoreAnyNull lorsque JET_bitIndexEmpty est passé. Il s’agit d’une amélioration des performances. Par exemple, si une nouvelle colonne est ajoutée à une table, un index est créé sur cette colonne nouvellement ajoutée et tous les enregistrements de la table sont analysés même s’ils ne sont pas ajoutés à l’index. La spécification JET_bitIndexEmpty ignore l’analyse de la table, ce qui peut prendre du temps.
JET_bitIndexUnversioned	Rend la création d’index visible par d’autres transactions. En règle générale, une session d’une transaction ne peut pas voir une opération de création d’index dans une autre session. Cet indicateur peut être utile si une autre transaction est susceptible de créer le même index. La deuxième création d’index échoue au lieu de provoquer potentiellement de nombreuses opérations de base de données inutiles. La deuxième transaction peut ne pas être en mesure d’utiliser l’index immédiatement. L’opération de création d’index doit se terminer avant qu’elle ne soit utilisable. La session ne doit pas se trouver dans une transaction pour créer un index sans informations de version.
JET_bitIndexSortNullsHigh	La spécification de cet indicateur entraîne le tri des valeurs NULL après les données de toutes les colonnes de l’index.
JET_bitIndexUnicode	La spécification de cet indicateur affecte l’interprétation du champ union lcid/pidxunicde dans la structure. La définition du bit signifie que le champ pidxunicode pointe réellement vers une structure JET_UNICODEINDEX . JET_bitIndexUnicode n’est pas nécessaire pour indexer des données Unicode. Il est utilisé uniquement pour personnaliser la normalisation des données Unicode.
JET_bitIndexTuples	Spécifie que l’index est un index de tuple. Consultez JET_TUPLELIMITS pour obtenir une description d’un index de tuple. JET_bitIndexTuples a été introduit dans le système d’exploitation Windows XP.
JET_bitIndexTupleLimits	La spécification de cet indicateur affecte l’interprétation du champ d’union cbVarSegMac/ptuplelimits dans la structure. La définition de ce bit signifie que le champ ptuplelimits pointe réellement vers une structure JET_TUPLELIMITS pour autoriser des limites d’index de tuple personnalisées (implique JET_bitIndexTuples). JET_bitIndexTupleLimits a été introduit dans le système d’exploitation Windows Server 2003.
JET_bitIndexCrossProduct 0x00004000	La spécification de cet indicateur pour un index qui a plusieurs colonnes clés qui est une colonne à valeurs multiples entraîne la création d’une entrée d’index pour chaque résultat d’un produit croisé de toutes les valeurs de ces colonnes clés. Sinon, l’index n’aurait qu’une seule entrée pour chaque valeur multiple dans la colonne clé la plus significative qui est une colonne à valeurs multiples et chacune de ces entrées d’index utiliserait la première valeur multiple de toutes les autres colonnes clés qui sont des colonnes à valeurs multiples. Par exemple, si vous avez spécifié cet indicateur pour un index sur la colonne A qui a les valeurs « red » et « blue » et sur la colonne B qui a les valeurs « 1 » et « 2 », les entrées d’index suivantes sont créées : « red », « 1 » ; « red », « 2 »; « blue », « 1 »; « blue », « 2 ». Sinon, les entrées d’index suivantes sont créées : « red », « 1 » ; « blue », « 1 ». JET_bitIndexCrossProduct a été introduit dans le système d’exploitation Windows Vista.
JET_bitIndexKeyMost 0x00008000	Si vous spécifiez cet indicateur, l’index utilise la taille de clé maximale spécifiée dans le champ cbKeyMost de la structure. Sinon, l’index utilise JET_cbKeyMost (255) comme taille de clé maximale. JET_bitIndexKeyMost a été introduit dans Windows Vista.
JET_bitIndexDisallowTruncation 0x00010000	La spécification de cet indicateur entraîne l’échec de toute mise à jour de l’index qui entraînerait l’échec d’une clé tronquée avec JET_errKeyTruncated. Sinon, les touches seront tronquées en mode silencieux. Pour plus d’informations sur la troncation de clé, consultez la fonction JetMakeKey . Windows Vista : JET_bitIndexDisallowTruncation est introduit dans Windows Vista.
JET_bitIndexNestedTable 0x00020000	La spécification de cet indicateur entraîne la mise à jour de l’index sur plusieurs colonnes à valeurs multiples, mais uniquement avec des valeurs de même itagSequence. JET_bitIndexNestedTable a été introduit dans Windows Vista.

ulDensity

Densité en pourcentage de l’arborescence d’index B+ initiale. La spécification d’un nombre inférieur à 100 utilise plus d’espace pour créer l’index initialement, mais permet de mettre en place une croissance future de l’index, évitant ainsi la fragmentation interne.

lcid

Identificateur de paramètres régionaux (LCID) à utiliser lors de la normalisation des données lorsque la valeur JET_bitIndexUnicode n’est pas spécifiée dans le paramètre grbit . Le LCID affecte la normalisation si l’index se trouve sur des colonnes Unicode.

pidxunicode

Pointeur vers une structure JET_UNICODEINDEX si la valeur JET_bitIndexUnicode est spécifiée dans le paramètre grbit . Cela permet à l’utilisateur de spécifier des indicateurs personnalisés qui sont passés à la fonction LCMapString pendant la normalisation Unicode.

cbVarSegMac

Longueur maximale, en octets, de chaque colonne à stocker dans l’index lorsque la valeur JET_bitIndexTupleLimits n’est pas spécifiée dans le paramètre grbit .

La spécification d’une valeur de 0 (zéro) pour ce champ équivaut à :

Spécification de JET_cbPrimaryKeyMost pour un index principal.
Spécification de JET_cbSecondaryKeyMost pour un index secondaire.

ptuplelimits

Pointeur vers une structure JET_TUPLELIMITS si la valeur JET_bitIndexTupleLimits est spécifiée dans le paramètre grbit .

ptuplelimits a été introduit dans Windows Server 2003.

rgconditionalcolumn

Paramètre facultatif pour un tableau de structures JET_CONDITIONALCOLUMN , qui sont utilisées pour spécifier les colonnes conditionnelles dans l’index.

cConditionalColumn

Nombre de structures dans le tableau rgconditionalcolumn .

err

Contient le code de retour pour la création de cet index.

cbKeyMost

Spécifie la taille maximale autorisée, en octets, pour les clés de l’index. Ce paramètre est ignoré si la valeur JET_bitIndexKeyMost n’est pas spécifiée dans le paramètre grbit . Si ce paramètre a la valeur zéro et que JET_bitIndexKeyMost est spécifié dans le paramètre grbit , la fonction appelante échoue avec JET_err_InvalidDef.

La taille maximale de clé minimale prise en charge est JET_cbKeyMostMin (255), qui est la taille maximale de clé héritée.

La taille maximale de la clé dépend de la taille de la page de base de données (JET_paramDatabasePageSize), comme suit :

Si JET_paramDatabasePageSize = 2048, JET_cbKeyMostMin (255) <= cbKeyMost<= JET_cbKeyMost2KBytePage (500)
Si JET_paramDatabasePageSize = 4096, JET_cbKeyMostMin (255) <= cbKeyMost<= JET_cbKeyMost4KBytePage (1000)
Si JET_paramDatabasePageSize = 8192, JET_cbKeyMostMin (255) <= cbKeyMost<= JET_cbKeyMost8KBytePage (2000)

La taille maximale de clé prise en charge pour le instance peut également être lue à partir du paramètre système JET_paramKeyMost.

cbKeyMost a été introduit dans Windows Vista.

Notes

ESE prend en charge l’indexation sur des colonnes clés contenant plusieurs valeurs. Pour utiliser cette fonctionnalité, la colonne doit être un type de colonne étiqueté (JET_bitColumnTagged), et elle doit être marquée pour que ses valeurs multiples soient indexées avec JET_bitColumnMultiValued. Dans les versions de Windows antérieures à Windows Vista, seule la première colonne de clé à valeurs multiples de l’index aura ses valeurs développées dans l’index. Toutes les autres colonnes à valeurs multiples et étiquetées ont uniquement leurs premières valeurs développées dans l’index.

En supposant que les lignes suivantes existent dans une table (la colonne Alpha n’est pas à valeurs multiples, tandis que les colonnes Bêta, Gamma et Delta sont à valeurs multiples), et qu’un index est créé sous la forme « +Alpha\0+Beta\0+Gamma\0+Delta\0\0 » :

Alpha	Bêta	Gamma	Delta
1	ABC GHI JKL	MNO PQR STU	VWX YZ
2	LLA	PLUIE ESPAGNE	IN TOMBE

Les tuples d’index qui tombent sont stockés :

{1,ABC,MNO,VWX}
{1,GHI,MNO,VWX}
{1,JKL,MNO,VWX}
{2,THE,RAIN,IN}

Notez que {2,THE,SPAIN,IN} n’est pas stocké, même si la colonne Alpha de la deuxième ligne a une seule valeur multivaleur.

Dans les versions de Windows à partir de Windows Vista, toutes les colonnes à valeurs multiples peuvent être développées dans l’index en spécifiant JET_bitIndexCrossProduct.

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.
Unicode	Implémenté en tant que JET_ INDEXCREATE_W (Unicode) et JET_ INDEXCREATE_A (ANSI).

Voir aussi

JET_COLTYP
JET_CONDITIONALCOLUMN
JET_ERR
JET_GRBIT
JET_TABLECREATE
JET_TABLECREATE2
JET_TUPLELIMITS
JET_UNICODEINDEX
JetCreateIndex2
JetSetColumn
JetUpdate