Fonction JetIntersectIndexes
S’applique à : Windows | Windows Server
Fonction JetIntersectIndexes
La fonction JetIntersectIndexes calcule l’intersection entre plusieurs jeux d’entrées d’index de différents index secondaires sur la même table. Cette opération est utile pour rechercher le jeu d’enregistrements dans une table qui correspondent à deux critères ou plus qui peuvent être exprimés à l’aide de plages d’index.
JET_ERR JET_API JetIntersectIndexes(
__in JET_SESID sesid,
__in JET_INDEXRANGE* rgindexrange,
__in unsigned long cindexrange,
__in_out JET_RECORDLIST* precordlist,
__in JET_GRBIT grbit
);
Paramètres
sesid
Session à utiliser pour cet appel.
rgindexrange
Pointeur vers un tableau de structures JET_IndexRange . Chaque structure comprend une JET_TABLEID qui a été configurée pour contenir l’une des plages d’index à croiser. Pour plus d’informations, consultez JET_IndexRange.
cindexrange
Nombre de structures JET_IndexRange dans le tableau contenu dans le paramètre rgindexrange .
précordlist
Pointeur vers une structure JET_RECORDLIST . Cette structure sera remplie avec suffisamment d’informations pour parcourir la table temporaire avec les résultats de JetIntersectIndexes.
Mémoire tampon de sortie qui reçoit une structure JET_RECORDLIST . La structure contient une description du jeu de résultats de l’intersection.
grbit
Réservé pour un usage futur.
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, 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_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. Windows XP : Cette valeur de retour est introduite dans Windows XP. |
JET_errInvalidgrbit |
L’une des options demandées n’était pas valide, utilisée incorrectement ou n’était pas implémentée. Cette erreur est retournée par JetIntersectIndexes dans les cas suivants : Le grbit contenu dans la structure JET_IndexRange pointée par un élément du tableau rgindexrange n’est pas égal à JET_bitRecordInIndex. |
JET_errInvalidParameter |
L’un des paramètres fournis contient une valeur inattendue ou une valeur incohérente lorsqu’elle est combinée avec la valeur d’un autre paramètre. Cette erreur est retournée par JetIntersectIndexes pour les raisons suivantes :
|
JET_errInvalidSesid |
Le handle de session n’est pas valide ou fait référence à une session fermée. Cette erreur n’est pas retournée dans toutes les circonstances. Les descripteurs sont validés sur la base du meilleur effort uniquement. |
JET_errNotInitialized |
Il n’est pas possible d’effectuer l’opération, car le instance associé à la session n’a pas été initialisé. |
JET_errOutOfCursors |
L’opération a échoué, car le moteur n’a pas pu allouer les ressources nécessaires pour ouvrir un nouveau curseur. Les ressources de curseur sont configurées en appelant JetSetSystemParameter avec JET_paramMaxCursors spécifiées dans le paramètre paramid . |
JET_errOutOfMemory |
L’opération a échoué, car la mémoire n’a pas pu être allouée pour la terminer. JetIntersectIndexes peut retourner JET_errOutOfMemory si l’espace d’adressage du processus hôte devient trop fragmenté. Le gestionnaire de tables temporaires alloue toujours un bloc d’espace d’adressage de 1 Mo pour chaque table temporaire créée, quelle que soit la quantité de données à stocker. JetIntersectIndexes crée une table temporaire pour chaque JET_IndexRange spécifiée dans le paramètre rgindexrange et une table temporaire pour la sortie dans JET_RECORDLIST. |
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 |
Il n’est pas autorisé d’utiliser la même session à partir de plusieurs threads en même temps. Windows XP : Cette valeur de retour est introduite dans Windows XP. |
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_errTooManyOpenIndexes |
L’opération a échoué, car le moteur n’a pas pu 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 spécifié dans le paramètre paramid . |
JET_errTooManyOpenTables |
L’opération a échoué, car le moteur n’a pas pu 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 spécifié dans le paramètre paramid . |
JET_errTooManySorts |
L’opération a échoué, car le moteur n’a pas pu 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 spécifiées dans le paramètre paramid . |
En cas de réussite, une nouvelle table temporaire est retournée qui contient les signets des enregistrements qui correspondent aux critères représentés par chacune des descriptions de plage d’index d’entrée.
En cas d’échec, la table temporaire contenant les résultats n’est pas créée. 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é. La position actuelle des JET_TABLEIDfournies à cette fonction peut être modifiée.
Notes
JetIntersectIndexes peut être utilisé pour filtrer efficacement les enregistrements d’une table selon plusieurs critères si ces critères peuvent être exprimés en termes d’index secondaires sur cette table. Par exemple, considérez que vous avez une très grande table contenant des personnes. La table peut contenir des colonnes pour son ID d’utilisateur, prénom, nom, etc. Supposons que chacune de ces colonnes soit indexée séparément et que l’index principal de la table soit sur l’ID utilisateur. Si vous souhaitez trouver toutes les personnes dont le prénom commence par un A et dont le nom commence par G, vous devez effectuer les étapes suivantes :
Ouvrez un nouveau curseur sur la table et définissez ce curseur de manière à utiliser l’index sur la colonne « prénom ». Ensuite, configurez une plage d’index pour toutes les personnes dont le « prénom » a commencé par « A », puis créez un struct JET_IndexRange qui contient ce curseur.
Répétez l’étape 1 avec un nouveau curseur sur l’index « nom » pour toutes les personnes dont le « nom » a commencé par « G ».
Transmettez ces critères à JetIntersectIndexes pour calculer le résultat dans une table temporaire.
Parcourez la table temporaire et récupérez chacun des enregistrements qui réussissent les critères par signet.
La table temporaire contenant le jeu de résultats est une table simple avec une colonne qui contient le signet de chaque enregistrement qui a passé tous les critères utilisés pour calculer l’intersection. Le jeu de résultats est trié dans le même ordre que l’index principal et ne contient aucune entrée en double. L’application peut énumérer les résultats de l’intersection en énumérant les lignes dans la table temporaire, en récupérant le signet pour chaque résultat à l’aide de JetRetrieveColumn, puis en visitant l’enregistrement dans la base de données en appelant JetGotoBookmark avec ce signet sur un curseur positionné sur l’index principal.
La table temporaire retournée par JetIntersectIndexes ne peut être analysée que dans une direction vers l’avant. Il doit également être fermé via JetCloseTable une fois l’analyse terminée. Pour plus d’informations sur les tables temporaires et leur fonctionnement, consultez JetOpenTemporaryTable.
JetIntersectIndexes est généralement un moyen efficace et pratique de filtrer les enregistrements en fonction de plusieurs critères indexés. Toutefois, il existe quelques conseils importants à suivre pour optimiser l’utilité de cette fonctionnalité. Si vous savez que l’un des critères est si restrictif que la plage d’index résultante a très peu d’enregistrements, il est probablement préférable de simplement parcourir cette plage d’index et de filtrer les enregistrements au niveau de l’application. De plus, si vous savez que vous avez des critères beaucoup moins restrictifs que d’autres critères dans votre intersection, vous pouvez envisager de supprimer ces critères beaucoup moins restrictifs de l’intersection. Enfin, si vous savez que l’un des critères n’est pas du tout restrictif, de sorte que la plage d’index résultante est presque aussi grande que l’index principal, il est peu probable que l’intersection avec cette plage d’index bénéficie (réduit la taille de) le jeu de résultats. Dans tous les cas, vous devez sélectionner des critères de manière à prendre le moins d’entrées d’index possibles en entrée et à générer l’ensemble de signets le plus spécifique sur la sortie pour des performances maximales.
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
JET_IndexRange
JET_RECORDLIST
JetGotoBookmark
JetRetrieveColumn
JetSetIndexRange