Fonction JetMakeKey

  • Article

S’applique à : Windows | Windows Server

Fonction JetMakeKey

La fonction JetMakeKey construit des clés de recherche qui peuvent ensuite être utilisées pour rechercher un ensemble d’entrées dans un index selon des critères de recherche simples sur leurs valeurs de colonne clé. Une clé de recherche est également l’une des propriétés intrinsèques d’un curseur et est utilisée par les opérations JetSeek et JetSetIndexRange pour localiser les entrées d’index correspondant à ces critères de recherche sur l’index actuel de ce curseur. Une clé de recherche complète est générée dans une série d’appels JetMakeKey où chaque appel est utilisé pour charger la valeur de colonne pour la colonne clé suivante de l’index actuel d’un curseur. Il est également possible de charger une clé de recherche précédemment construite qui a été récupérée à partir du curseur à l’aide de JetRetrieveKey.

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

pvData

Mémoire tampon d’entrée contenant les données de colonne pour la colonne clé actuelle de l’index actuel du curseur pour lequel la clé de recherche est en cours de construction.

Le type de données des données de colonne dans la mémoire tampon d’entrée doit correspondre exactement au type de données et aux autres propriétés de la définition de colonne de la colonne actuelle. Aucune contrainte de type n’est effectuée sur les données de colonne.

Si JET_bitNormalizedKey est spécifié dans le paramètre grbit , la mémoire tampon d’entrée doit contenir une clé de recherche précédemment construite. Ces clés sont obtenues à l’aide d’un appel à JetRetrieveKey.

cbData

Taille en octets des données de colonne fournies dans la mémoire tampon d’entrée.

Si JET_bitNormalizedKey est spécifié dans le paramètre grbit , il s’agit de la taille de la clé de recherche fournie dans la mémoire tampon d’entrée.

Si la taille des données de colonne est égale à zéro, le contenu de la mémoire tampon d’entrée est ignoré. Si JET_bitKeyDataZeroLength est spécifié dans le paramètre grbit et que la colonne clé actuelle de l’index actuel du curseur est une colonne de longueur variable, les données de colonne d’entrée sont supposées être une valeur de longueur nulle. Sinon, les données de colonne d’entrée sont supposées être une valeur NULL.

grbit

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

Valeur

Signification

JET_bitFullColumnEndLimit

La clé de recherche doit être construite de telle sorte que toutes les colonnes clés qui viennent après la colonne clé actuelle soient considérées comme des caractères génériques. Cela signifie que la clé de recherche construite peut être utilisée pour faire correspondre les entrées d’index qui ont les éléments suivants :

  • Valeurs de colonne exactes fournies pour cette colonne clé et toutes les colonnes clés précédentes.

  • Toutes les valeurs de colonne nécessaires pour les colonnes clés suivantes.

Cette option doit être utilisée lors de la création de clés de recherche génériques à utiliser pour rechercher les entrées d’index les plus proches de la fin d’un index. La fin de l’index est l’entrée d’index trouvée lors du passage au dernier enregistrement de cet index. La fin de l’index n’est pas la même que l’extrémité supérieure de l’index, ce qui peut changer en fonction de l’ordre de tri des colonnes clés dans l’index.

Cette option n’est disponible que sur Windows XP et versions ultérieures.

JETbitFullColumnStartLimit

La clé de recherche doit être construite de telle sorte que toutes les colonnes clés qui viennent après la colonne de clé actuelle soient considérées comme des caractères génériques. Cela signifie que la clé de recherche construite peut être utilisée pour faire correspondre les entrées d’index qui ont les éléments suivants :

  • Valeurs de colonne exactes fournies pour cette colonne clé et toutes les colonnes clés précédentes.

  • Toutes les valeurs de colonne nécessaires pour les colonnes clés suivantes.

Cette option doit être utilisée lors de la création de clés de recherche génériques à utiliser pour rechercher les entrées d’index les plus proches du début d’un index. Le début de l’index est l’entrée d’index trouvée lors du déplacement vers le premier enregistrement de cet index. Le début de l’index n’est pas identique à l’extrémité inférieure de l’index, qui peut changer en fonction de l’ordre de tri des colonnes clés dans l’index.

Cette option n’est disponible que sur Windows XP et versions ultérieures.

JET_bitKeyDataZeroLength

Si la taille de la mémoire tampon d’entrée est égale à zéro et que la colonne clé actuelle est une colonne de longueur variable, cette option indique que la mémoire tampon d’entrée contient une valeur de longueur nulle. Sinon, une taille de mémoire tampon d’entrée égale à zéro indique une valeur NULL.

JET_bitNewKey

Une nouvelle clé de recherche doit être construite. Toute clé de recherche existante est ignorée.

JET_bitNormalizedKey

Lorsque cette option est spécifiée, toutes les autres options sont ignorées, toute clé de recherche existante est ignorée et le contenu de la mémoire tampon d’entrée est chargé en tant que nouvelle clé de recherche.

JET_bitPartialColumnEndLimit

La clé de recherche doit être construite de telle sorte que la colonne clé actuelle soit considérée comme un caractère générique de préfixe et que toutes les colonnes clés qui viennent après la colonne clé actuelle soient considérées comme des caractères génériques. Cela signifie que la clé de recherche construite peut être utilisée pour faire correspondre les entrées d’index qui ont les éléments suivants :

  • Valeurs de colonne exactes fournies pour cette colonne clé et toutes les colonnes clés précédentes.

  • Toutes les valeurs de colonne nécessaires pour les colonnes clés suivantes.

Cette option doit être utilisée lors de la création de clés de recherche génériques à utiliser pour rechercher les entrées d’index les plus proches de la fin d’un index. La fin de l’index est l’entrée d’index trouvée lors du passage au dernier enregistrement de cet index. La fin de l’index n’est pas la même que l’extrémité supérieure de l’index, ce qui peut changer en fonction de l’ordre de tri des colonnes clés dans l’index.

Cette option ne peut pas être utilisée lorsque la colonne clé actuelle n’est pas une colonne de texte ou une colonne binaire variable. L’opération échoue avec JET_errInvalidgrbit si cette opération est tentée.

Cette option n’est disponible que sur Windows XP et versions ultérieures.

JET_bitPartialColumnStartLimit

Cette option indique que la clé de recherche doit être construite de telle sorte que la colonne clé actuelle soit considérée comme un caractère générique de préfixe et que toutes les colonnes clés qui viennent après la colonne clé actuelle soient considérées comme des caractères génériques. Cela signifie que la clé de recherche construite peut être utilisée pour faire correspondre les entrées d’index qui ont les éléments suivants :

  • Valeurs de colonne exactes fournies pour cette colonne clé et toutes les colonnes clés précédentes.

  • Toutes les valeurs de colonne nécessaires pour les colonnes clés suivantes.

Cette option doit être utilisée lors de la création de clés de recherche génériques à utiliser pour rechercher les entrées d’index les plus proches du début d’un index. Le début de l’index est l’entrée d’index trouvée lors du déplacement vers le premier enregistrement de cet index. Le début de l’index n’est pas identique à l’extrémité inférieure de l’index, qui peut changer en fonction de l’ordre de tri des colonnes clés dans l’index.

Cette option ne peut pas être utilisée lorsque la colonne clé actuelle n’est pas une colonne de texte ou une colonne binaire variable. L’opération échoue avec JET_errInvalidgrbit si cette opération est tentée.

Cette option n’est disponible que sur Windows XP et versions ultérieures.

JET_bitStrLimit

Cette option indique que la clé de recherche doit être construite de telle sorte que toutes les colonnes clés qui viennent après la colonne clé actuelle soient considérées comme des caractères génériques. Cela signifie que la clé de recherche construite peut être utilisée pour faire correspondre les entrées d’index qui ont les éléments suivants :

  • Valeurs de colonne exactes fournies pour cette colonne clé et toutes les colonnes clés précédentes.

  • Toutes les valeurs de colonne nécessaires pour les colonnes clés suivantes.

Cette option doit être utilisée lors de la création de clés de recherche génériques à utiliser pour rechercher les entrées d’index les plus proches de la fin d’un index. La fin de l’index est l’entrée d’index trouvée lors du passage au dernier enregistrement de cet index. La fin de l’index n’est pas la même que l’extrémité supérieure de l’index, ce qui peut changer en fonction de l’ordre de tri des colonnes clés dans l’index.

Lorsque cette option est spécifiée en combinaison avec JET_bitSubStrLimit et que la colonne clé actuelle est une colonne de texte, cette option est ignorée. Ce comportement est destiné à permettre d’inférer le type de la colonne de clé active lors de la génération de la clé de recherche.

Si vous souhaitez créer une clé de recherche similaire pour le début d’un index, un appel similaire à JetMakeKey doit être effectué pour la dernière colonne de clé qui n’est pas un caractère générique, mais sans aucune option générique spécifiée. La clé de recherche est alors dans un état approprié à utiliser pour une telle recherche. Cela est analogue à l’utilisation de JET_bitFullColumnStartLimit, sauf que la clé de recherche n’est pas correctement terminée, car elle est après l’utilisation d’une option générique.

Cette option a été déconseillée pour Windows XP et les versions ultérieures afin de résoudre cette sémantique gênante. JET_bitFullColumnStartLimit et JET_bitFullColumnEndLimit doivent être utilisés à la place dans la mesure du possible.

JET_bitSubStrLimit

Cette option indique que la clé de recherche doit être construite de telle sorte que la colonne clé actuelle soit considérée comme un caractère générique de préfixe et que toutes les colonnes clés qui viennent après la colonne clé actuelle soient considérées comme des caractères génériques. Cela signifie que la clé de recherche construite peut être utilisée pour faire correspondre les entrées d’index qui ont les éléments suivants :

  • Valeurs de colonne exactes fournies pour toutes les colonnes clés précédentes.

  • Données de colonne spécifiées en tant que préfixe de leur valeur de colonne pour la colonne clé active.

  • Toutes les valeurs de colonne pour les colonnes clés suivantes.

Cette option doit être utilisée lors de la création de clés de recherche génériques à utiliser pour rechercher les entrées d’index les plus proches de la fin d’un index. La fin de l’index est l’entrée d’index trouvée lors du déplacement vers le dernier enregistrement de cet index. La fin de l’index n’est pas la même que l’extrémité supérieure de l’index, qui peut changer en fonction de l’ordre de tri des colonnes clés dans l’index.

Lorsque cette option est spécifiée en combinaison avec JET_bitStrLimit et que la colonne clé actuelle est une colonne de texte, cette option est prioritaire. Cette option est ignorée lorsque la colonne clé actuelle n’est pas une colonne de texte. Ce comportement est destiné à permettre d’inférer le type de la colonne clé actuelle lors de la création de la clé de recherche.

Si vous souhaitez créer une clé de recherche similaire pour le début d’un index, un appel similaire à JetMakeKey doit être effectué pour la colonne clé qui doit être le caractère générique de préfixe, mais sans aucune option générique spécifiée. La clé de recherche est alors dans un état approprié à utiliser pour une telle recherche. Cela est analogue à l’utilisation de JET_bitPartialColumnStartLimit, à ceci près que la clé de recherche n’est pas correctement terminée, car elle l’est après l’utilisation d’une option générique.

Cette option a été déconseillée pour Windows XP et les versions ultérieures afin de résoudre cette sémantique maladroite. JET_bitPartialColumnStartLimit et JET_bitPartialColumnEndLimit doivent être utilisés à la place, lorsque cela est possible.

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_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_errIndexTuplesKeyTooSmall

Les données de colonne fournies étaient trop petites pour générer une clé valide pour l’index actuel, car cet index est un index de tuple et la taille de tuple minimale était supérieure aux données de colonne fournies. Pour plus d’informations sur les index de tuple, consultez JetCreateIndex . Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.

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_errInvalidBufferSize

Les données de colonne fournies ne correspondent pas à la taille requise par la définition de colonne. Cela peut se produire si le type de données de la colonne a intrinsèquement une certaine taille. Cela peut également se produire si le type de données de la colonne n’a pas intrinsèquement une certaine taille, mais que la définition de la colonne déclare qu’il est de longueur fixe. Une exception à cela est que cette erreur ne se produit pas lorsque trop peu de données sont fournies pour une colonne de texte de longueur fixe, car toutes les données manquantes sont automatiquement remplies avec des espaces. Une deuxième exception est que cette erreur ne se produit pas lorsque trop peu de données sont fournies pour une colonne binaire de longueur fixe, car toutes les données manquantes sont automatiquement remplies avec des zéros.

JET_errInvalidgrbit

L’une des options demandées n’était pas valide, utilisée de manière illégale ou non implémentée. Cela peut se produire pour JetMakeKey dans les cas suivants :

  • JET_bitPartialColumnStartLimit ou JET_bitPartialColumnEndLimit sont spécifiés et la colonne clé correspondante n’est pas une colonne de texte et n’est pas une colonne binaire de longueur variable. Ce cas se produit uniquement sur Windows XP et versions ultérieures.

  • Une tentative est effectuée pour utiliser plusieurs des options suivantes : JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit et JET_bitFullColumnEndLimit. Ce cas se produit uniquement sur Windows XP et versions ultérieures.

  • Une tentative est effectuée pour utiliser JET_bitStrLimit ou JET_bitSubStrLimit lorsque l’une des options suivantes est utilisée : JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit et JET_bitFullColumnEndLimit. Ce cas se produit uniquement sur Windows XP et versions ultérieures.

JET_errInvalidParameter

L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas pertinente lorsqu’elle était combinée avec la valeur d’un autre paramètre.

Cela peut se produire pour JetMakeKey lorsque JET_bitNormalizedKey a été spécifié et que la valeur fournie dans la mémoire tampon d’entrée était trop grande pour être une clé de recherche valide.

JET_errKeyIsMade

Les données de colonne fournies à JetMakeKey ont été rejetées, car les données de colonne ont déjà été fournies pour toutes les colonnes clés de l’index actuel. Cela peut se produire de trois façons. La première méthode consiste à fournir des données de colonne pour chaque colonne clé de l’index actuel. La deuxième méthode consiste à savoir si des données de colonne ont été fournies pour au moins une colonne clé et si une option générique a été choisie pour le dernier appel. La troisième méthode consiste à fournir une clé de recherche précédemment construite à l’aide de JET_bitNormalizedKey, qui couvre toutes les colonnes clés.

JET_errKeyNotMade

Il n’existe aucune clé de recherche actuelle pour le curseur. Cela se produit pour JetMakeKey si JET_bitNewKey n’est pas spécifié et qu’aucune clé de recherche n’a été construite pour ce curseur à l’aide d’un appel antérieur à JetMakeKey. La clé de recherche sera supprimée par un appel antérieur à toute API de navigation sur le curseur autre que JetMove.

JET_errNoCurrentIndex

Il n’existe aucun index actuel pour le curseur. Cela se produit pour JetMakeKey si le curseur se trouve sur l’index cluster d’une table, si aucun index principal n’a été défini et JET_bitNormalizedKey n’a pas été spécifié. Il n’est pas possible de construire une clé de recherche si le curseur se trouve sur un index qui n’a pas de colonnes clés, sauf si une clé de recherche précédemment construite est fournie.

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_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.

En cas de réussite, si JET_bitNormalizedKey et JET_bitNewKey n’ont pas été spécifiés, la clé de recherche a été générée par les critères de recherche d’une colonne clé supplémentaire dans l’index actuel. Si JET_bitNormalizedKey n’a pas été spécifié et JET_bitNewKey a été spécifié, toute clé de recherche existante a été ignorée et une nouvelle clé a été créée selon les critères de recherche pour la première colonne clé de l’index actuel. Si JET_bitNormalizedKey a été spécifié, toute clé de recherche existante a été ignorée et une nouvelle clé chargée à partir de la mémoire tampon d’entrée. Dans tous les cas, aucune modification de l’état de la base de données ne se produira.

En cas d’échec, si JET_bitNormalizedKey ou JET_bitNewKey a été spécifié, l’état de la clé de recherche n’est pas défini. Si ni JET_bitNormalizedKey ni JET_bitNewKey n’ont été spécifiés, aucune modification de l’état de la clé de recherche ne se produit. Dans tous les cas, aucune modification de l’état de la base de données ne se produira.

Notes

Les clés doivent être traitées comme des blocs opaques de données. Aucune tentative ne doit être effectuée pour exploiter la structure interne de ces données. Toutefois, les éléments suivants sont connus sur toutes les clés ESENT :

  • Les clés peuvent être comparées entre elles à l’aide de memcmp pour établir leur ordre relatif dans l’index d’origine sur la table des entrées d’index source.

  • Il est inutile de comparer les clés des entrées d’index de différents index les unes aux autres.

  • Une clé est toujours inférieure ou égale à JET_cbKeyMost (255) octets avant Windows Vista. Sur Windows Vista et les versions ultérieures, les clés peuvent être plus volumineuses. La taille maximale d’une clé est égale à la valeur actuelle de JET_paramKeyMost.

Les clés de recherche peuvent être d’un octet plus long si une option générique a été utilisée. Dans ce cas, la clé de recherche sera jusqu’à JET_cbLimitKeyMost (256) octets pour les versions antérieures à Windows Vista et JET_paramKeyMost + 1 octets pour Windows Vista et versions ultérieures.

Il y a une conséquence très importante à cette taille maximale de clé. Chaque fois qu’une entrée d’index a des valeurs de colonne suffisamment grandes pour générer une clé pour cet index qui serait autrement supérieure à cette taille maximale, cette clé est tronquée silencieusement à cette taille maximale. Cela entraîne deux effets :

  • Pour les entrées d’un index unique, les entrées qui seraient autrement uniques sont déclarées en tant que doublons.

  • Pour les entrées de tous les index, la troncation de clé entraîne la déclaration des entrées d’index qui ne correspondraient pas aux critères de recherche d’une clé de recherche donnée.

Les applications doivent anticiper cette troncation et l’éviter ou compenser ses effets. Dans Windows Vista, un nouvel indicateur d’index, JET_bitIndexDisallowTruncation, a été ajouté pour permettre aux applications d’empêcher plus facilement les troncations de clé. Pour plus d’informations sur cette option d’indexation, consultez la structure JET_INDEXCREATE .

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_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange