Structure JET_INDEXCREATE2

S’applique à : Windows | Windows Server

La structure JET_INDEXCREATE2 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.

La structure JET_INDEXCREATE2 a été introduite dans le système d’exploitation Windows 7.

typedef struct tagJET_INDEXCREATE2 {
  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_SPACEHINTS* pSpacehints;
} JET_INDEXCREATE;

Membres

cbStruct

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

szIndexName

Nom de l’index à créer.

Le nom doit remplir les conditions suivantes :

• Elle doit être inférieure à JET_cbNameMost, sans inclure la valeur null de fin.

• Il doit se composer de l’ensemble de caractères suivant : 0 (zéro) à 9, A à Z, a à z, et toutes les autres ponctuations à l’exception de « ! » (point d’exclamation), « , » (virgule), « [ » (crochet ouvrant) et « ] » (crochet fermant), c’est-à-dire, caractères ASCII 0x20, 0x22 via 0x2d, 0x2f via 0x5a, 0x5c et 0x5d via 0x7f.

• Il ne doit pas commencer par un espace.

• Il doit contenir au moins un caractère autre que l’espace.

szKey

Pointeur vers une chaîne de jetons délimités par une double valeur null.

Chaque jeton est de la forme «< nom-colonne du spécificateur><de> direction », où la spécification de direction 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 est terminée par une valeur NULL double.

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

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

Comportement obsolète : après la terminaison double NULL, il est possible de spécifier un ID de langue (un MOT passé dans MAKELCID( langid, SORT_DEFAULT ) afin de spécifier le LCID pour l’index. Il n’est pas autorisé à spécifier à la fois 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 type de données 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 contiennent zéro ou plus des options de valeur 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 est appliqué 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	Spécifie que les opérations d’index seront consignées de manière paresseuse. 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 sera toujours en mesure d’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 ont la valeur 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 et qu’un index est créé sur cette colonne nouvellement ajoutée, tous les enregistrements de la table sont analysés même s’ils ne sont pas ajoutés à l’index. La spécification de JET_bitIndexEmpty ignore l’analyse de la table, ce qui peut prendre beaucoup de temps.
JET_bitIndexUnversioned	JET_bitIndexUnversioned rend la création d’index visible par d’autres transactions. En règle générale, une session dans 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 simplement au lieu de provoquer 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 pour qu’elle soit utilisable. La session ne doit pas se trouver actuellement 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 d’union lcid/pidxunicde dans la structure. La définition du bit signifie que le champ pidxunicode pointe en fait vers une structure JET_UNICODEINDEX . JET_bitIndexUnicode n’est pas nécessaire pour indexer les données Unicode. Il est uniquement nécessaire pour personnaliser la normalisation des données Unicode.
JET_bitIndexTuples	Spécifie que l’index est un index tuple. Consultez JET_TUPLELIMITS pour obtenir une description d’un index tuple. La valeur JET_bitIndexTuples a été introduite 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 en fait vers une structure JET_TUPLELIMITS pour autoriser les limites d’index tuple personnalisées (implique JET_bitIndexTuples). La valeur JET_bitIndexTupleLimits a été introduite 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 colonne à valeurs multiples 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 multivaleur 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 ». La valeur JET_bitIndexCrossProduct a été introduite dans 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. La valeur JET_bitIndexKeyMost a été introduite 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 le code de réponse JET_errKeyTruncated. Sinon, les clés seront tronquées en mode silencieux. Pour plus d’informations sur la troncation de clé, consultez JetMakeKey. La valeur JET_bitIndexDisallowTruncation a été introduite 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 à ce qui suit :

• 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 JET_bitIndexKeyMost n’est pas spécifié dans le paramètre grbit . Si ce paramètre est défini sur zéro et que JET_bitIndexKeyMost est spécifié dans le membre 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.

pSpacehints

Pointeur vers une structure JET_SPACEHINTS .

pSpacehints a été introduit dans Windows 7.

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 index-tuples suivants seront 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_ INDEXCREATE2_W (Unicode) et JET_ INDEXCREATE2_A (ANSI).

Voir aussi

JET_COLTYP
JET_CONDITIONALCOLUMN
JET_ERR
JET_GRBIT
JET_TABLECREATE
JET_TABLECREATE2
JET_TUPLELIMITS
JET_UNICODEINDEX
JetCreateIndex2
JetSetColumn
JetUpdate