Fonction JetRetrieveKey

Article
06/13/2023

S’applique à : Windows | Windows Server

Fonction JetRetrieveKey

La fonction JetRetrieveKey récupère la clé de l’entrée d’index à la position actuelle d’un curseur. Ces clés sont construites par les appels à JetMakeKey. La clé récupérée peut ensuite être utilisée pour renvoyer efficacement ce curseur à la même entrée d’index par un appel à JetSeek.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

pvData

Mémoire tampon de sortie qui recevra la clé.

cbMax

Taille maximale en octets de la mémoire tampon de sortie.

pcbActual

Reçoit la taille réelle en octets de la clé.

Si ce paramètre a la valeur NULL, la taille réelle de la clé n’est pas retournée.

Si la mémoire tampon de sortie est trop petite, la taille réelle de la clé est toujours retournée. Cela signifie que ce nombre sera supérieur à la taille de la mémoire tampon de sortie.

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_bitRetrieveCopy	Lorsque cette option est spécifiée, le moteur retourne la touche de recherche pour le curseur. La clé de recherche est générée à l’aide d’un ou plusieurs appels antérieurs à JetMakeKey afin de rechercher cette clé à l’aide de JetSeek ou de définir une plage d’index à l’aide de JetSetIndexRange.

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_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_errKeyNotMade	Il n’existe aucune clé de recherche actuelle pour le curseur. Cela se produit pour JetRetrieveKey si JET_bitRetrieveCopy est spécifié et qu’aucune clé de recherche n’a été construite pour ce curseur à l’aide d’un appel antérieur à JetMakeKey. La clé de recherche sera supprimée par un appel antérieur à toute API de navigation sur le curseur autre que JetMove.
JET_errNoCurrentRecord	Le curseur n’est pas positionné sur un enregistrement. Cela peut se produire pour de nombreuses raisons différentes. Par exemple, cela se produit si le curseur est actuellement positionné après le dernier enregistrement de l’index actuel.
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.
JET_wrnBufferTruncated	L’opération s’est terminée correctement, mais la mémoire tampon de sortie était trop petite pour recevoir la clé entière. La mémoire tampon de sortie a été remplie avec autant de clé que possible. La taille réelle de la clé a également été retournée, si demandé. Note Cette erreur ne sera pas retournée si JET_bitRetrieveCopy est spécifié. Pour plus d’informations, consultez la section Remarques.

En cas de réussite, la clé de l’entrée d’index à la position actuelle d’un curseur est retournée dans la mémoire tampon de sortie. Si JET_wrnBufferTruncated est retourné, la mémoire tampon de sortie contiendra autant de la clé que l’espace fourni et la taille réelle de la clé sera précise. Aucune modification de l’état de la base de données ne se produira.

En cas d’échec, l’état de la mémoire tampon de sortie et la taille réelle de la clé ne sont pas définis. Aucune modification de l’état de la base de données ne se produira.

Notes

Les clés doivent généralement être traitées comme des blocs opaques de données. Aucune tentative ne doit être effectuée pour exploiter la structure interne de ces données. Toutefois, les propriétés suivantes peuvent être connues sur toutes les clés ESENT :

Les clés peuvent être comparées les unes aux autres à l’aide de la fonction memcmp pour établir leur ordre relatif dans l’index d’origine sur la table des entrées d’index source.
Il est inutile de comparer les clés des entrées d’index de différents index les unes aux autres.
Une clé est toujours inférieure ou égale à JET_cbKeyMost (255) octets avant Windows Vista. Sur Windows Vista et les versions ultérieures, les clés peuvent être plus volumineuses. La taille maximale d’une clé est égale à la valeur actuelle de JET_paramKeyMost.

En plus des propriétés ci-dessus des clés ESENT en général, il est important de noter qu’une clé de recherche est différente de la clé d’une entrée d’index. Plus précisément, une clé de recherche peut être plus longue qu’une clé ordinaire. Cette longueur supplémentaire se produit lorsqu’une option générique est utilisée lors de la construction de la clé de recherche. Pour plus d’informations, consultez JetMakeKey .

Il existe un bogue important dans cette API qui est présent dans toutes les versions. Si la clé de recherche est demandée à l’aide de JET_bitRetrieveCopy et que la mémoire tampon de sortie est trop petite pour recevoir la clé entière, JET_wrnBufferTruncated ne sera PAS retourné. JET_errSuccess seront retournés à la place. Il est important de vérifier que la taille réelle de la clé retournée à l’aide de pcbActual est inférieure ou égale à la taille de la mémoire tampon de sortie. Si la taille réelle est supérieure à la taille de la mémoire tampon de sortie, l’appelant de JetRetrieveKey doit réagir comme si JET_wrnBufferTruncated étaient retournés à la place.

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

Fonction JetRetrieveKey