Fonction JetMove

S’applique à : Windows | Windows Server

Fonction JetMove

La fonction JetMove positionne un curseur au début ou à la fin d’un index et traverse les entrées de cet index vers l’avant ou vers l’arrière. Il est également possible de déplacer le curseur vers l’avant ou vers l’arrière sur l’index actuel en fonction d’un nombre spécifié d’entrées d’index. Une autre approche consiste à limiter artificiellement les entrées d’index qui peuvent être énumérées à l’aide de JetMove en configurant une plage d’index sur le curseur à l’aide de JetSetIndexRange.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

Crow

Décalage arbitraire qui indique le mouvement souhaité du curseur sur l’index actif.

En plus des décalages standard, ce paramètre peut également être défini avec l’une des options suivantes.

Valeur	Signification
JET_MoveFirst	Déplace le curseur vers la première entrée d’index de l’index (le cas échéant). Cela réinitialise toute plage d’index définie avec JetSetIndexRange. Note La valeur littérale -2147483648 est utilisée pour désigner cette option. N’utilisez pas cette valeur comme décalage ordinaire ou un comportement involontaire peut en résulter.
JET_MoveLast	Déplace le curseur vers la dernière entrée d’index de l’index (le cas échéant). Cela réinitialise toute plage d’index définie avec JetSetIndexRange. Note La valeur littérale de 2147483647 est utilisée pour désigner cette option. N’utilisez pas cette valeur comme décalage ordinaire ou un comportement involontaire peut en résulter.
JET_MoveNext	Déplace le curseur vers l’entrée d’index suivante dans l’index (le cas échéant). Cette valeur est exactement égale à un décalage ordinaire de +1. Il respecte les plages d’index définies avec JetSetIndexRange.
JET_MovePrevious	Déplace le curseur vers l’entrée d’index précédente dans l’index (le cas échéant). Il respecte les plages d’index définies avec JetSetIndexRange. Cette valeur est exactement égale à un décalage ordinaire de -1 ou 0 (Zéro). Le curseur reste à la position logique actuelle et l’existence de l’entrée d’index qui correspond à cette position logique sera testée.

grbit

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

Valeur

Signification

JET_bitMoveKeyNE

Déplace le curseur vers l’avant ou vers l’arrière en fonction du nombre d’entrées d’index requises pour ignorer le nombre demandé de valeurs de clé d’index rencontrées dans l’index. Cela a pour effet de réduire les entrées d’index avec des valeurs de clé dupliquées en une seule entrée d’index. En règle générale, un décalage déplace le curseur en fonction du nombre spécifié d’entrées d’index, quelles que soient leurs valeurs de clé.

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 JetMove, cela signifie qu’une entrée d’index a été trouvée à l’emplacement ou au décalage demandé sur l’index actuel.
JET_errClientRequestToStopJetService	L’opération ne peut pas se terminer, car toute l’activité sur le instance associée à la session a cessé à la suite d’un appel à JetStopService.
JET_errInstanceUnavailable	L’opération ne peut pas se terminer, car le instance associé à la session a rencontré une erreur irrécupérable qui exige 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_errNoCurrentRecord	Le curseur n’est actuellement pas positionné sur une entrée d’index. Pour JetMove, cela signifie qu’une entrée d’index n’a pas été trouvée à l’emplacement ou au décalage demandé sur l’index actuel.
JET_errNotInitialized	L’opération ne peut pas se terminer, car le instance associé à la session n’a pas encore été initialisé.
JET_errRecordDeleted	Le curseur est actuellement positionné logiquement sur une entrée d’index qui correspond à un enregistrement qui a été supprimé.
JET_errRestoreInProgress	L’opération ne peut pas se terminer, 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. Windows XP : Cette valeur de retour est introduite dans Windows XP.
JET_errTermInProgress	L’opération ne peut pas se terminer, car le instance associé à la session est en cours d’arrêt.

Si cette fonction réussit, le curseur sera positionné sur une entrée d’index qui correspond à l’emplacement ou au décalage demandé. Si un enregistrement a été préparé pour la mise à jour, cette mise à jour est annulée. Si une plage d’index est en vigueur et que JET_MoveFirst ou JET_MoveLast a été spécifié, cette plage d’index est annulée. Aucune modification de l’état de la base de données ne se produira.

Si cette fonction échoue, la position du curseur reste inchangée, sauf si JET_errNoCurrentRecord a été retourné. Dans ce cas, le curseur est positionné à l’emplacement de l’entrée d’index correspondant à l’emplacement ou au décalage demandé. Le curseur peut être déplacé par rapport à cette position, mais il n’est toujours pas sur une entrée d’index valide. Si un enregistrement a été préparé pour la mise à jour, cette mise à jour est annulée. Si une plage d’index est en vigueur et que JET_MoveFirst ou JET_MoveLast a été spécifié, cette plage d’index est annulée. Aucune modification de l’état de la base de données ne se produira.

Notes

Un curseur peut être déplacé vers deux positions spéciales à l’aide de JetMove, Before First et After Last. Si le curseur se trouve sur la première entrée d’index de la table et que JetMove est appelé avec JET_MovePrevious, l’appel échoue avec JET_errNoCurrentRecord et le curseur est positionné logiquement avant la première entrée de l’index. Cette position logique est conservée même si une autre entrée d’index est insérée avant la première entrée de l’index. Une situation analogue se produit pour After Last par rapport à la fin de l’index. Before First et After Last sont plus utiles lors de la configuration d’une plage d’entrées d’index à itérer à l’aide de JetMove, à l’aide d’un modèle d’itérateur qui s’attend à toujours passer à l’élément suivant (ou précédent) avant d’utiliser cet élément.

L’ensemble d’entrées d’index qui peuvent être visitées par JetMove peut être limité en configurant une plage d’index sur le curseur. Cela est utile pour les applications qui énumèrent un ensemble d’entrées d’index qui correspondent à des critères simples qui peuvent être exprimés par le biais d’une paire de clés de recherche créées pour cet index. Pour plus d’informations, consultez JetSetIndexRange.

Sur les versions antérieures à Windows Server 2003 SP1, il existe un problème dans JetMove qui se produit dans certains cas spécifiques, qui affecte l’application correcte d’une plage d’index telle que configurée par la fonction JetSetIndexRange . Si le curseur se trouve actuellement avant la première entrée d’index et qu’une plage d’index est définie avec une limite supérieure inférieure à la première entrée d’index, l’appel suivant à JetMove va à tort à cette entrée d’index au lieu d’échouer avec JET_errNoCurrentRecord, comme prévu. La même erreur se produit pour la situation analogue à partir de la fin de l’index. Cette situation peut se produire dans une application qui configure une plage d’index et la navigue à l’aide d’un itérateur qui s’attend à démarrer avant la première entrée d’index qui est membre du jeu d’entrées à énumérer, plutôt que de commencer sur la première entrée d’index de cet ensemble. Cette situation se produit également sur le cas analogue à partir de la fin de l’index. La solution de contournement consiste pour l’application à vérifier manuellement que l’entrée d’index acquise se trouve à l’intérieur de la plage d’index en comparant la clé de l’entrée d’index actuelle (récupérée à l’aide de JetRetrieveKey) avec la clé représentant la fin de la plage d’index actuelle (récupérée à l’aide de JetRetrieveKey à l’aide de JET_bitRetrieveCopy).

Il est important d’être prudent lors du passage de décalages calculés à JetMove. Si le décalage calculé est inférieur ou égal à JET_MoveFirst, ce décalage doit être fractionné en plusieurs éléments, chacun d’entre eux étant transmis à JetMove séparément, mais au sein d’une transaction unique pour obtenir l’effet souhaité. Il en va de même pour les décalages supérieurs ou égaux à JET_MoveNext. Il est peu probable qu’une application subisse cela dans le monde réel, mais il est bon d’avoir une défense contre ce cas étant donné la sémantique très différente de JET_MoveFirst et JET_MoveLast d’un décalage ordinaire.

Lorsque JetMove est appelé avec un décalage très important, par exemple lorsque le paramètre cRow est défini sur 1000, JetMove traverse les 1 000 entrées d’index pour atteindre la position finale. Actuellement, l’API ESE ne fournit pas de moyen efficace de passer directement à une entrée d’index donnée par décalage sans traverser chaque entrée d’index.

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
JetRetrieveKey
JetSetIndexRange