Partager via

Fonction JetSetCurrentIndex4

  • Article

S’applique à : Windows | Windows Server

Fonction JetSetCurrentIndex4

La fonction JetSetCurrentIndex4 est utilisée pour définir l’index actuel d’un curseur. L’index actuel d’un curseur définit les enregistrements d’une table qui sont visibles par ce curseur et l’ordre dans lequel ils apparaissent en sélectionnant le jeu d’entrées d’index à utiliser pour exposer ces enregistrements.

    JET_ERR JET_API JetSetCurrentIndex4(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in_opt      JET_INDEXID* pindexid,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

szIndexName

Nom de l’index à sélectionner pour le curseur. Si ce paramètre a la valeur NULL ou une chaîne vide, l’index cluster est sélectionné. Si un index principal est défini pour la table, cet index est sélectionné, car il est identique à l’index cluster. Si aucun index principal n’est défini pour la table, l’index séquentiel est sélectionné. L’index séquentiel n’a pas de définition d’index. Pour plus d’informations, consultez JetCreateIndex .

Si pindexid n’est pas NULL, le nom de l’index est ignoré et l’index est sélectionné par son ID d’index.

pindexid

ID de l’index à sélectionner pour le curseur.

L’ID d’index est un handle volatile et opaque qui peut être utilisé pour sélectionner rapidement un index. Cet ID peut être récupéré à l’aide de JetGetIndexInfo ou JetGetTableIndexInfo à l’aide de l’option JET_IdxInfoIndexId.

Si pindexid a la valeur NULL, l’index est sélectionné par son nom d’index et l’ID d’index est ignoré.

Lorsque ce paramètre n’est pas présent, sa valeur est supposée être NULL.

grbit

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

Valeur

Signification

JET_bitMoveFirst

Cette option indique que le curseur doit être positionné sur la première entrée de l’index spécifié. Si l’index cluster est sélectionné (index principal ou index séquentiel) et que l’index actuel est un index secondaire, JET_bitMoveFirst est supposé. Si l’index actuel est sélectionné, cette option est ignorée et aucune modification de la position du curseur n’est effectuée.

JET_bitNoMove

Cette option indique que le curseur doit être positionné sur l’entrée d’index du nouvel index qui correspond à l’enregistrement associé à l’entrée d’index à la position actuelle du curseur sur l’ancien index.

Si la définition du nouvel index contient au moins une colonne clé à valeurs multiples, l’entrée d’index de destination est ambiguë. Dans ce cas, l’itagSequence spécifiée est utilisée pour sélectionner la valeur multiple de la colonne clé à valeurs multiples la plus significative qui est utilisée pour positionner le curseur. Il est nécessaire de passer une seule itagSequence même dans le cas de plusieurs colonnes clés à valeurs multiples, car le moteur développe uniquement toutes les valeurs de la colonne clé à valeurs multiples la plus significative. Pour plus d’informations, consultez JetCreateIndex .

Si JET_bitMoveFirst est spécifié, cette option est ignorée.

Si l’index actuel est sélectionné, cette option est ignorée et aucune modification de la position du curseur n’est effectuée. Lorsque ce paramètre n’est pas présent, sa valeur est supposée être JET_bitMoveFirst.

itagSequence

Numéro séquentiel de la valeur de colonne à valeurs multiples qui sera utilisée pour positionner le curseur sur le nouvel index.

Ce paramètre est utilisé uniquement conjointement avec JET_bitNoMove. Pour plus d’informations, consultez la description de cette option.

Lorsque ce paramètre n’est pas présent ou est défini sur zéro, sa valeur est supposée être 1.

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_errBadItagSequence

Un index secondaire est sélectionné avec l’option JET_bitNoMove et il n’existe aucune valeur pour la première colonne clé à valeurs multiples dans la définition du nouvel index qui correspond au numéro de séquence spécifié.

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_errInvalidIndexId

Le contenu de l’ID d’index n’était pas valide ou a expiré et doit être actualisé. Cela peut se produire pour JetSetCurrentIndex4 dans les cas suivants :

  • pindexid-cbStruct> n’a pas la taille attendue (Windows Server 2003 et versions ultérieures).

  • Le moteur a été arrêté depuis que l’ID d’index a été extrait.

  • Tous les curseurs référençant la table contenant l’index correspondant à l’ID d’index ont été fermés et le moteur a supprimé la définition de cet index du cache de schéma.

  • L’ID d’index est utilisé avec un curseur ouvert sur la table incorrecte.

  • L’index a été supprimé ou n’est pas encore visible par la session.

JET_errInvalidName

L’un des noms d’objets spécifiés n’était pas valide. Tous les noms d’objets doivent être conformes au même ensemble de règles. Ces règles sont les suivantes :

  • Les noms d’objets doivent être composés de caractères ASCII.

  • Les noms d’objets doivent comporter au moins un caractère.

  • Les noms d’objets ne peuvent pas dépasser JET_cbNameMost (64) caractères.

  • Les noms d’objets ne peuvent pas commencer par un espace.

  • Les noms d’objets ne peuvent pas contenir de caractères de contrôle ASCII (0x00 à 0x1F).

  • Les noms d’objets ne peuvent pas contenir de point d’exclamation (!), de point (.), de crochet gauche ([) ou de crochet droit (]).

  • Une fois validé, seule la partie de la chaîne jusqu’au premier espace (le cas échéant) est utilisée pour le nom de l’objet. Cela signifie en fait que les noms d’objets ne peuvent pas non plus contenir d’espace.

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 JetSetCurrentIndex4 lorsque pindexid n’a pas la valeur NULL et que pindexid-cbStruct> n’a pas la taille attendue (Windows XP et versions antérieures).

JET_errNoCurrentRecord

Un index secondaire est sélectionné avec l’option JET_bitNoMove et il n’existe aucune entrée d’index dans le nouvel index correspondant à l’enregistrement associé à l’entrée d’index à la position actuelle du curseur sur l’ancien 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_errOutOfCursors

Le moteur a épuisé son pool de ressources utilisées pour ouvrir les curseurs. Le nombre maximal de curseurs pouvant être ouverts à tout moment est contrôlé à l’aide de JET_paramMaxCursors. Pour plus d’informations, consultez JetSetSystemParameter . Cela peut se produire pour JetSetCurrentIndex4 lorsqu’un index secondaire a été sélectionné et que le moteur ne peut pas ouvrir un curseur interne pour utiliser cet index.

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, l’index actuel du curseur est défini sur l’index demandé. Les entrées d’index peuvent maintenant être recherchées à l’aide de JetSeek en fonction de la définition d’index de l’index demandé. Les entrées d’index peuvent également être énumérées à l’aide de JetMove dans l’ordre spécifié par cette définition d’index. La position actuelle du curseur est définie sur la première entrée d’index de l’index (JET_bitMoveFirst) ou sur une entrée d’index spécifique liée à la position actuelle du curseur sur l’ancien index (JET_bitNoMove). Aucune modification de l’état de la base de données ne se produira.

En cas d’échec, l’index actuel et la position actuelle du curseur sont dans un état non défini. Aucune modification de l’état de la base de données ne se produira.

Notes

Si l’indicateur d’ID d’index est obsolète, l’API échoue tout simplement. Il n’y a pas de secours au nom de texte de l’index dans ce cas, comme on peut s’y attendre. Ce secours doit être effectué manuellement par l’appelant de l’API.

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.

Unicode

Implémenté en tant que JetSetCurrentIndex4W (Unicode) et JetSetCurrentIndex4A (ANSI).

Voir aussi

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetSystemParameter