Partager via

Fonction JetGetSecondaryIndexBookmark

  • Article

S’applique à : Windows | Windows Server

Fonction JetGetSecondaryIndexBookmark

La fonction JetGetSecondaryIndexBookmark récupère un signet spécial pour l’entrée d’index secondaire à la position actuelle d’un curseur. Ce signet peut ensuite être utilisé pour repositionner efficacement ce curseur vers la même entrée d’index à l’aide de JetGotoSecondaryIndexBookmark. Cela est particulièrement utile lors du repositionnement sur un index secondaire qui contient des clés en double ou qui contient plusieurs entrées d’index pour le même enregistrement.

Windows XP : JetGetSecondaryIndexBookmark est introduit dans Windows XP.

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const JET_GRBIT grbit
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

pvSecondaryKey

Mémoire tampon de sortie qui reçoit la clé secondaire.

cbSecondaryKeyMax

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

pcbSecondaryKeyActual

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

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

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

pvPrimaryBookmark

Mémoire tampon de sortie qui reçoit le signet de clé primaire.

cbPrimaryBookmarkMax

Taille maximale, en octets, de la mémoire tampon de sortie du signet de clé primaire.

pcbPrimaryKeyActual

Reçoit la taille réelle, en octets, du signet de clé primaire.

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

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

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 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_errBufferTooSmall

L’opération s’est terminée correctement, mais l’une des mémoires tampons de sortie était trop petite pour recevoir les données demandées.

La mémoire tampon de sortie a été remplie avec autant de signets qu’il le faudrait. La taille réelle du signet a également été retournée, si demandé.

JET_errClientRequestToStopJetService

Il n’est pas possible d’effectuer l’opération, car toutes les activités sur le instance associées à 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 exige 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_errNoCurrentIndex

Le curseur ne se trouve actuellement pas sur un index secondaire.

Il n’est pas utile de récupérer un signet d’index secondaire lorsque le curseur n’utilise pas d’index secondaire. JetGetBookmark doit être utilisé lorsque le curseur ne se trouve pas sur un index secondaire.

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.

En cas de réussite, le signet d’index secondaire de l’entrée d’index à la position actuelle d’un curseur est retourné dans les mémoires tampons de sortie. Aucune modification de l’état de la base de données ne se produira.

En cas d’échec, l’état des mémoires tampons de sortie et la taille réelle du signet d’index secondaire ne sont pas définis, sauf si JET_errBufferTooSmall a été retourné. Dans le cas où JET_errBufferTooSmall est retourné, les mémoires tampons de sortie contiennent autant de signet d’index secondaire qu’il convient dans l’espace fourni et la taille réelle du signet d’index secondaire sera exacte. Dans tous les cas, aucune modification de l’état de la base de données ne se produit.

Notes

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

  • Un signet identifie de manière unique un enregistrement dans une table donnée.

  • Le signet d’un enregistrement ne change pas pendant la durée de vie de cet enregistrement.

  • Le signet d’un enregistrement est identique à la clé de cet enregistrement sur l’index principal sur la table contenant cet enregistrement. Si aucun index principal n’est défini sur cette table, le moteur de base de données crée son propre signet pour l’enregistrement.

  • Les signets peuvent être comparés les uns aux autres à l’aide de memcmp pour établir leur classement relatif dans l’index principal sur la table des enregistrements sources. Si aucun index principal n’est défini sur cette table, l’ordre relatif des signets de cette table n’est pas significatif.

  • Il est inutile de comparer les signets d’enregistrements de différentes tables les uns aux autres.

  • Un signet est toujours inférieur ou égal à JET_cbBookmarkMost (256) octets avant Windows Vista. Sur Windows Vista et les versions ultérieures, les signets peuvent être plus volumineux. La taille maximale d’un signet est égale à la valeur actuelle de JET_paramKeyMost + 1.

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

  • Les clés peuvent être comparées les unes aux autres à l’aide de 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 d’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.

Spécifications

Condition requise Valeur

Client

Nécessite Windows Vista ou Windows XP.

Serveur

Nécessite Windows Server 2008 ou Windows Server 2003.

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
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp