Fonction JetSetIndexRange

S’applique à : Windows | Windows Server

Fonction JetSetIndexRange

La fonction JetSetIndexRange limite temporairement l’ensemble des entrées d’index que le curseur peut parcourir à l’aide de JetMove à celles commençant par l’entrée d’index actuelle et se terminant à l’entrée d’index qui correspond aux critères de recherche spécifiés par la clé de recherche dans ce curseur et aux critères liés spécifiés. Une clé de recherche doit avoir été précédemment construite à l’aide de JetMakeKey.

    JET_ERR JET_API JetSetIndexRange(
      __in          JET_SESID sesid,
    __in          JET_TABLEID tableidSrc,
      __in          JET_GRBIT grbit
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableidSrc

Curseur à utiliser pour cet appel.

grbit

Groupe de bits qui contient les options à utiliser pour cet appel, qui incluent zéro ou plusieurs des éléments suivants :

Valeur	Signification
JET_bitRangeInclusive	Cette présence ou absence de cette option indique les critères de limite de la plage d’index. Lorsqu’elle est présente, cette option indique que la limite de la plage d’index est inclusive. En cas d’absence, cette option indique que la limite de la plage d’index est exclusive. Lorsque la limite de la plage d’index est incluse, toutes les entrées d’index correspondant exactement aux critères de recherche sont incluses dans la plage.
JET_bitRangeInstantDuration	Cette option demande que la plage d’index soit supprimée dès qu’elle a été établie. Tous les autres aspects de l’opération restent inchangés. Cela est utile pour tester l’existence d’entrées d’index qui correspondent aux critères de recherche.
JET_bitRangeRemove	Cette option demande qu’une plage d’index existante sur le curseur soit annulée. Une fois la plage d’index annulée, il est possible de dépasser la fin de la plage d’index à l’aide de JetMove. Si une plage d’index n’est pas déjà appliquée, JetSetIndexRange échoue avec JET_errInvalidOperation. Lorsque cette option est spécifiée, toutes les autres options sont ignorées.
JET_bitRangeUpperLimit	Si cette option est utilisée, la clé de recherche dans le curseur représente les critères de recherche pour l’entrée d’index la plus proche de la fin de l’index qui correspondra à la plage d’index. La plage d’index est établie entre la position actuelle du curseur et cette entrée d’index afin que toutes les correspondances puissent être trouvées en marchant vers l’avant sur l’index à l’aide de JetMove avec JET_MoveNext ou un décalage positif. Il n’est pas significatif d’utiliser cette option avec une clé de recherche qui a été construite à l’aide de JetMakeKey à l’aide d’une option générique destinée à rechercher les entrées d’index les plus proches du début de l’index. Si cette option est omise, la clé de recherche dans le curseur représente les critères de recherche pour l’entrée d’index la plus proche du début de l’index qui correspondra à la plage d’index. La plage d’index est établie entre la position actuelle du curseur et cette entrée d’index afin que toutes les correspondances puissent être trouvées en marchant vers l’arrière sur l’index à l’aide de JetMove avec JET_MovePrevious ou un décalage négatif. Il n’est pas significatif d’omettre cette option avec une clé de recherche qui a été construite à l’aide de JetMakeKey à l’aide d’une option générique destinée à rechercher les entrées d’index les plus proches de la fin de l’index.

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. Pour JetSetIndexRange, cela signifie qu’une plage d’index existante a été annulée ou qu’il existe au moins une entrée d’index à l’intérieur de la plage d’index.
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. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errInvalidOperation	Cette erreur est retournée par JetSetIndexRange lorsque JET_bitRangeRemove a été spécifié et qu’aucune plage d’index n’a été appliquée.
JET_errKeyNotMade	Il n’existe aucune clé de recherche actuelle pour le curseur. JetSetIndexRange nécessite que le curseur dispose d’une clé de recherche valide, car il l’utilisera pour les critères de recherche utilisés pour rechercher les entrées d’index.
JET_errNoCurrentIndex	Il n’existe aucun index actuel pour le curseur. Cela se produit pour JetSetIndexRange si le curseur se trouve sur l’index cluster d’une table et qu’aucun index principal n’a été défini. La définition d’une plage d’index sur un tel index n’est pas prise en charge.
JET_errNoCurrentRecord	Cette erreur sera retournée par JetSetIndexRange pour indiquer qu’il n’y a aucune entrée d’index à l’intérieur de la plage d’index.
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_bitRangeRemove est spécifié, la plage d’index actuellement en vigueur est annulée. Si JET_bitRangeRemove n’est pas spécifié et JET_bitRangeInstantDuration est spécifié, aucune plage d’index n’est appliquée. Si ni JET_bitRangeRemove ni JET_bitRangeInstantDuration n’est spécifié, une nouvelle plage d’index est appliquée. Cette plage d’index limite temporairement l’ensemble des entrées d’index que le curseur peut parcourir à l’aide de JetMove à celles commençant à partir de l’entrée d’index actuelle et se terminant à l’entrée d’index qui correspond aux critères de recherche. La position du curseur reste inchangée. Si une clé de recherche a été construite pour le curseur, cette clé de recherche est supprimée. Aucune modification de l’état de la base de données ne se produira.

En cas d’échec, si JET_errNoCurrentRecord n’est pas retourné, aucune plage d’index n’est appliquée. Si JET_errNoCurrentRecord est retourné, une nouvelle plage d’index est appliquée. Cette plage d’index limite temporairement l’ensemble des entrées d’index que le curseur peut parcourir à l’aide de JetMove à celles commençant à partir de l’entrée d’index actuelle et se terminant à l’entrée d’index qui correspond aux critères de recherche. La position du curseur reste inchangée. Si JET_errNoCurrentRecord a été retourné et qu’une clé de recherche a été construite pour le curseur, cette clé de recherche est supprimée. Aucune modification de l’état de la base de données ne se produira.

Notes

Une plage d’index est volatile et est automatiquement annulée si une navigation autre que JetMove est effectuée sur le curseur.

Les plages d’index ne fonctionnent que dans une direction. Si une limite supérieure est établie, seul le mouvement vers l’avant à l’aide de JetMove avec JET_MoveNext ou un décalage positif est empêché une fois la fin de la plage d’index atteinte. Dans ce cas, il est toujours possible de laisser la plage d’index à l’aide de JetMove avec JET_MovePrevious ou un décalage négatif. Une situation analogue se produit pour une limite inférieure.

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
JetMakeKey
JetMove
JetSetIndexRange
JetStopService