JetGetSecondaryIndexBookmark fonction)

S’applique à : Windows | Windows Serveurs

JetGetSecondaryIndexBookmark fonction)

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 sur 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 dupliquées 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 pour 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 pour le 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 sera 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 la plus grande partie du signet. La taille réelle du signet a également été retournée, si nécessaire.

JET_errClientRequestToStopJetService

Il n’est pas possible de terminer l’opération, car toute activité sur l’instance associée à la session a été interrompue suite à un appel à JetStopService.

JET_errInstanceUnavailable

Il n’est pas possible de terminer l’opération, car l’instance associée à la session a rencontré une erreur irrécupérable qui requiert que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. cette erreur est renvoyée uniquement par Windows XP et les versions ultérieures.

JET_errNoCurrentIndex

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

Il n’est pas utile de récupérer un signet d’index secondaire lorsque le curseur n’utilise pas actuellement un 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

Impossible de terminer l’opération, car l’instance associée à la session n’a pas encore été initialisée.

JET_errRestoreInProgress

Il n’est pas possible de terminer l’opération, car une opération de restauration est en cours sur l’instance associée à la session.

JET_errSessionSharingViolation

La même session ne peut pas être utilisée simultanément pour plusieurs threads. cette erreur est renvoyée uniquement par Windows XP et les versions ultérieures.

JET_errTermInProgress

Il n’est pas possible de terminer l’opération, car l’instance associée à 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 tampons de sortie. Aucune modification de l’état de la base de données ne se produit.

En cas d’échec, l’état des tampons de sortie et la taille réelle du signet de l’index secondaire ne sont pas définis, sauf si JET_errBufferTooSmall a été retourné. Dans le cas où JET_errBufferTooSmall est retourné, les tampons de sortie contiendront la plus grande partie du signet d’index secondaire, comme 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.

Remarques

Les signets doivent généralement être traités comme des blocs de données opaques. Aucune tentative n’est faite pour exploiter la structure interne de ces données. Toutefois, les propriétés suivantes peuvent être connues en ce qui concerne tous les signets ESENT :

  • Un signet identifie de façon unique un enregistrement dans une table donnée.

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

  • Le signet d’un enregistrement est le même que la clé de cet enregistrement sur l’index primaire sur la table contenant cet enregistrement. Si aucun index primaire 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 ordre relatif dans l’index primaire sur la table des enregistrements sources. Si aucun index primaire 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 des enregistrements de différentes tables entre eux.

  • un signet est toujours inférieur ou égal à JET_cbBookmarkMost (256) octets de longueur 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 n’est faite pour exploiter la structure interne de ces données. Toutefois, les propriétés suivantes peuvent être connues en ce qui concerne 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 des entrées d’index de différents index.

  • la longueur d’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.

Configuration requise

Condition requise Valeur

Client

requiert Windows Vista ou Windows XP.

Serveur

requiert Windows server 2008 ou Windows server 2003.

En-tête

Déclaré dans esent. h.

Bibliothèque

Utilisez ESENT. lib.

DLL

Requiert ESENT.dll.

Voir aussi

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp