Fonction JetIntersectIndexes
S’applique à : Windows | Windows Serveurs
Fonction JetIntersectIndexes
La fonction JetIntersectIndexes calcule l’intersection entre plusieurs jeux d’entrées d’index à partir d’index secondaires différents sur la même table. Cette opération est utile pour Rechercher l’ensemble des enregistrements d’une table qui correspondent à plusieurs critères 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 inclut 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 de JET_IndexRange dans le tableau contenues dans le paramètre rgindexrange .
precordlist
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 de terminer l’opération, car toute activité sur l’instance associée à la session a été interrompue suite à un appel à JetStopService. |
JET_errInstanceUnavailable |
Il n’est pas possible de terminer l’opération, car l’instance associée à la session a rencontré une erreur irrécupérable qui requiert 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’est pas valide, a été utilisée de manière incorrecte ou n’a pas été implémentée. Cette erreur est retournée par JetIntersectIndexes quand : Le Grbit contenu dans la structure JET_IndexRange pointée par n’importe quel élément dans le tableau rgindexrange n’est pas égal à JET_bitRecordInIndex. |
JET_errInvalidParameter |
L’un des paramètres fournis contient une valeur inattendue ou une valeur qui n’est pas cohérente lorsqu’elle est associée à la valeur d’un autre paramètre. Cette erreur est retournée par JetIntersectIndexes pour les raisons suivantes :
|
JET_errInvalidSesid |
Le descripteur 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 handles ne sont validés qu’à titre d’effort optimal. |
JET_errNotInitialized |
Impossible de terminer l’opération, car l’instance associée à la session n’a pas été initialisée. |
JET_errOutOfCursors |
L’opération a échoué, car le moteur n’a pas pu allouer les ressources nécessaires à l’ouverture d’un nouveau curseur. Les ressources de curseur sont configurées en appelant JetSetSystemParameter avec JET_paramMaxCursors spécifié dans le paramètre paramid . |
JET_errOutOfMemory |
L’opération a échoué, car la mémoire peut être allouée pour être terminée. JetIntersectIndexes peut retourner JET_errOutOfMemory si l’espace d’adressage du processus hôte est 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. 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 de terminer l’opération, car une opération de restauration est en cours sur l’instance associée à la session. |
JET_errSessionSharingViolation |
Il n’est pas conforme 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 de terminer l’opération, car l’instance associée à 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 requises pour créer une table temporaire. Les ressources de table temporaire sont configurées à l’aide de JetSetSystemParameter avec JET_paramMaxTemporaryTables spécifié 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 la plage d’index d’entrée.
En cas d’échec, la table temporaire contenant les résultats ne sera pas créée. L’état de la base de données temporaire peut être modifié. L’état de toutes les bases de données ordinaires utilisées par le moteur de base de données reste inchangé. La position actuelle du JET_TABLEIDfourni à 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 disposez d’une table très volumineuse contenant des personnes. La table peut comporter des colonnes pour son ID utilisateur, son prénom, son nom, etc. Supposons que chacune de ces colonnes soit indexée séparément et que l’index primaire de la table soit sur l’ID d’utilisateur. Si vous souhaitez trouver tous les utilisateurs dont le prénom commence par un 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 pour utiliser l’index sur la colonne « First Name ». Configurez ensuite une plage d’index pour toutes les personnes dont le « prénom » a démarré avec « A », puis générez un JET_IndexRange struct contenant ce curseur.
Répétez l’étape 1 avec un nouveau curseur sur l’index « Last Name » pour toutes les personnes dont le « Last Name » a démarré avec « 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 passent 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 ayant 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 primaire et ne contient pas d’entrées en double. L’application peut énumérer les résultats de l’intersection en énumérant les lignes de la table temporaire, en extrayant 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 primaire.
La table temporaire retournée par JetIntersectIndexes peut uniquement être analysée vers l’avant. Elle doit également être fermée via JetCloseTable lorsque l’analyse est 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 des conseils importants qui doivent être suivis pour optimiser l’utilité de cette fonctionnalité. Si vous savez que l’un des critères est tellement restrictif que la plage d’index résultante a très peu d’enregistrements, il est probablement préférable de simplement parcourir la plage d’index et de filtrer les enregistrements au niveau de l’application. En outre, si vous savez que vous avez des critères qui sont bien moins restrictifs que d’autres critères de votre intersection, vous pouvez envisager de supprimer ces critères de plus en moins restrictifs de l’intersection. Enfin, si vous savez que l’un des critères n’est pas tout à fait restrictif, de sorte que la plage d’index résultante est presque aussi importante que l’index primaire, il est peu probable que l’intersection avec cette plage d’index soit avantageuse (réduisez la taille de) l’ensemble de résultats. Dans tous les cas, vous devez sélectionner des critères de manière à ce qu’ils prennent le moins d’entrées d’index possible en entrée et génèrent le jeu de signets le plus spécifique sur la sortie pour des performances maximales.
Spécifications
| Condition requise | Valeur |
|---|---|
Client |
requiert Windows Vista, Windows XP ou Windows 2000 Professional. |
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 |
Requiert ESENT.dll. |
Voir aussi
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_IndexRange
JET_RECORDLIST
JetGotoBookmark
JetRetrieveColumn
JetSetIndexRange