Fonction JetEnumerateColumns

S’applique à : Windows | Windows Server

Fonction JetEnumerateColumns

La fonction JetEnumerateColumns récupère efficacement un ensemble de colonnes et leurs valeurs à partir de l’enregistrement actif d’un curseur ou de la mémoire tampon de copie de ce curseur. Les colonnes et les valeurs récupérées peuvent être limitées par une liste d’ID de colonne, des nombres itagSequence et d’autres caractéristiques. Cette API de récupération de colonne est unique en ce qu’elle retourne des informations dans la mémoire allouée dynamiquement obtenue à l’aide d’un rappel compatible realloc fourni par l’utilisateur. Cette nouvelle flexibilité permet la récupération efficace des données de colonne avec des caractéristiques spécifiques (telles que la taille et la multiplicité) inconnues de l’appelant. Cela élimine la nécessité d’utiliser les modes de découverte de JetRetrieveColumn pour déterminer ces caractéristiques afin de configurer un appel final à JetRetrieveColumn qui récupérera correctement les données souhaitées.

Windows XP : JetEnumerateColumns est introduit dans Windows XP.

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

cEnumColumnId

Tableau d’ID de colonne, chacun avec un tableau facultatif de nombres itagSequence à énumérer.

Si cEnumColumnId a la valeur 0 (zéro), rgEnumColumnId est ignoré et toutes les valeurs de colonne sont énumérées et retournées à l’appelant. Si un élément du tableau d’ID de colonne fait référence à un ID de colonne de 0 (zéro), l’énumération de cette colonne est ignorée et un emplacement correspondant dans la sortie est généré avec une colonne status de JET_wrnColumnSkipped.

Si ctagSequence est égal à 0 (zéro) pour un élément donné du tableau d’ID de colonne, rgtagSequence est ignoré et toutes les valeurs de colonne pour cet ID de colonne sont énumérées et retournées à l’appelant. Si un élément d’un tableau de nombres itagSequence fait référence à un nombre itagSequence de 0 (zéro), l’énumération de ce nombre itagSequence est ignorée et un emplacement correspondant dans la sortie est généré avec une valeur de colonne status de JET_wrnColumnSkipped.

rgEnumColumnId

Consultez cEnumColumnId.

pcEnumColumn

Retourne le tableau énuméré de colonnes et leurs valeurs en mémoire allouées via le rappel compatible itagSequence fourni.

Si un tableau d’ID de colonne est demandé en entrée, l’ordre et la taille du tableau de sortie reflètent l’ordre et la taille du tableau d’entrée. De même, si un tableau de nombres itagSequence est demandé pour un ID de colonne particulier en entrée, l’ordre et la taille du tableau de sortie des valeurs de colonne pour cette colonne reflètent l’ordre et la taille du tableau d’entrée.

Les paramètres de sortie sont définis sur 0 (zéro) et NULL sur toute erreur, à l’exception des JET_errBadColumnId et des JET_errColumnNotFound. Lorsque ces erreurs sont retournées, les données de sortie sont valides et complètes pour tous les ID de colonne, sauf pour les ID de colonne affectés. Le code status pour chacun des ID de colonne affectés est défini sur l’une de ces erreurs afin que l’appelant puisse déterminer quels ID de colonne étaient incorrects et éventuellement prendre des mesures correctives.

prgEnumColumn

Consultez pcEnumColumn.

pfnRealloc

Identifie un rappel compatible realloc et un pointeur de contexte facultatif utilisé pour allouer de la mémoire pour le tableau de sortie de colonnes et leurs valeurs.

pvReallocContext

Voir pfnRealloc.

cbDataMost

Définit une limite sur la quantité de données à retourner à partir d’un texte long ou d’une colonne binaire longue.

Ce paramètre peut être utilisé pour empêcher l’énumération d’une valeur de colonne extrêmement grande. En règle générale, une telle énumération peut échouer l’appel d’API avec JET_errOutOfMemory. Si une grande valeur de colonne est tronquée de cette manière, la status de la valeur de colonne est JET_wrnColumnTruncated.

grbit

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

Valeur	Signification
JET_bitEnumerateCompressOutput	Lors de l’énumération de valeurs de colonne, toutes les colonnes pour lesquelles nous récupérons toutes les valeurs et qui n’ont qu’une seule valeur de colonne non NULL peuvent être retournées dans un format compressé. La status pour ces colonnes sera définie sur JET_wrnColumnSingleValue et la taille de la valeur de colonne et la mémoire contenant la valeur de colonne seront retournées directement dans la structure de JET_ENUMCOLUMN. Il n’est pas garanti que toutes les colonnes éligibles soient compressées de cette manière. Pour plus d’informations, consultez JET_ENUMCOLUMN .
JET_bitEnumerateCopy	Cette option indique que les valeurs de colonne modifiées de l’enregistrement doivent être énumérées plutôt que les valeurs de colonne d’origine. Si la valeur d’une colonne n’a pas été modifiée, la valeur de colonne d’origine est énumérée. Ainsi, une valeur de colonne qui n’a pas encore été insérée ou mise à jour peut être énumérée lors de l’insertion ou de la mise à jour d’un enregistrement. Cette option est identique à JET_bitRetrieveCopy lorsqu’elle est utilisée avec JetRetrieveColumn ou JetRetrieveColumns.
JET_bitEnumerateIgnoreDefault	Si une colonne donnée n’est pas présente dans l’enregistrement, aucune valeur de colonne n’est retournée. En règle générale, la valeur par défaut de la colonne, le cas échéant, est retournée dans ce cas. Il est garanti que si la colonne est définie sur une valeur différente de la valeur par défaut, cette valeur différente sera retournée (autrement dit, si une colonne avec une valeur par défaut est explicitement définie sur NULL , une valeur NULL sera retournée comme valeur pour cette colonne). Notez que, même si cette option est demandée, il est toujours possible de voir une valeur de colonne qui se trouve être égale à la valeur par défaut. Aucun effort n’est fait pour supprimer les valeurs de colonne qui correspondent à leurs valeurs par défaut. Il est important de noter que cette option affecte la sortie de JetEnumerateColumns lorsqu’elle est utilisée avec JET_bitEnumeratePresenceOnly ou JET_bitEnumerateTaggedOnly.
JET_bitEnumerateIgnoreUserDefinedDefault	Si une colonne donnée n’est pas présente dans l’enregistrement et qu’elle a une valeur par défaut définie par l’utilisateur, aucune valeur de colonne n’est retournée. Cette option empêche le rappel qui calcule la valeur par défaut définie par l’utilisateur pour la colonne d’être appelée lors de l’énumération des valeurs de cette colonne. Windows Server 2003 et versions antérieures : Pour Windows Server 2003 et versions antérieures, l’opération échoue avec JET_errCallbackFailed. Windows Server 2003 SP1 : Cette valeur possible est disponible uniquement pour les systèmes d’exploitation Windows Server 2003 SP1 et ultérieurs. Si cette valeur possible est spécifiée et que la table contient une colonne dont la valeur par défaut est définie par l’utilisateur, l’opération échoue avec JET_errCallbackFailed.
JET_bitEnumeratePresenceOnly	S’il existe une valeur non NULL pour la colonne ou la valeur de colonne demandée, les données associées ne sont pas retournées. Au lieu de cela, la status associée à cette valeur de colonne ou de colonne sera définie sur JET_wrnColumnPresent. Si la valeur de colonne ou de colonne est NULL , JET_wrnColumnNull sera retourné comme d’habitude.
JET_bitEnumerateTaggedOnly	Lors de l’énumération de toutes les valeurs de colonne dans l’enregistrement (par exemple, c’est-à-dire lorsque cEnumColumnId est égal à zéro), seules les valeurs de colonne étiquetées sont retournées. Cette option n’est pas autorisée lors de l’énumération d’un tableau spécifique d’ID de colonne.
JET_bitEnumerateInRecordOnly	Windows 7 : JET_bitEnumerateInRecordOnly est introduit dans Windows 7.

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_errBadColumnId	L’ID de colonne donné est en dehors des limites légales d’un ID de colonne. Cette erreur sera retournée par JetEnumerateColumns si des ID de colonne spécifiques ont été demandés, si l’un de ces ID de colonne n’était pas valide et que le premier ID de colonne non valide a échoué avec cette erreur pour sa colonne status code.
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_errColumnNotFound	La colonne décrite par l’ID de colonne donné n’existe pas dans la table. Cette erreur sera retournée par JetEnumerateColumns si des ID de colonne spécifiques ont été demandés, si l’un de ces ID de colonne n’était pas valide et que le premier ID de colonne non valide a échoué avec cette erreur pour son code status colonne.
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. Windows XP : Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errInvalidgrbit	L’une des options demandées n’était pas valide ou n’était pas implémentée. Cette erreur sera retournée par JetEnumerateColumns dans les cas suivants : JET_bitEnumerateLocal est spécifié. Un grbit illégal est spécifié.
JET_errInvalidParameter	L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas logique lorsqu’elle était combinée à la valeur d’un autre paramètre. Cette erreur sera retournée par JetEnumerateColumns dans les cas suivants : pcEnumColumn a la valeur NULL. prgEnumColumn a la valeur NULL. pfnRealloc a la valeur NULL.
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_errRecordDeleted	Le curseur est positionné sur un enregistrement qui a été supprimé. Cela peut se produire pour de nombreuses raisons différentes. La raison la plus courante est que la session ne se trouve pas dans une transaction, que le curseur a été positionné sur un enregistrement, que cet enregistrement a été supprimé, puis que le curseur a tenté de référencer cet enregistrement.
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. Windows XP : 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, les données demandées sont retournées dans les mémoires tampons de sortie. Il incombe à l’appelant de libérer toute mémoire allouée par ce rappel et retournée dans les mémoires tampons de sortie. Cette mémoire doit être libérée via le rappel compatible realloc fourni. Aucune modification de l’état de la base de données ne se produira.

En cas d’échec, aucune des données demandées n’est retournée. Toute mémoire allouée pendant l’appel est libérée automatiquement à l’aide du rappel compatible realloc fourni. Aucune modification de l’état de la base de données ne se produira.

Notes

Si vous énumérez toutes les valeurs de colonne dans l’enregistrement et que vous n’avez pas spécifié JET_bitEnumerateIgnoreDefaults vous ne pouvez pas supposer que vous ne verrez jamais une colonne ou une valeur de colonne avec un code status de JET_wrnColumnNull. Vous pouvez voir ce code status si une colonne a une valeur par défaut et a été explicitement définie sur NULL ou si la colonne est une colonne non éparse (par exemple, une colonne fixe ou variable).

Le paramètre cbDataMost ne s’applique pas à toutes les valeurs de colonne. Ce paramètre tronque uniquement les valeurs de texte long et de colonnes binaires longues qui sont si volumineuses qu’elles ont été stockées séparément de l’enregistrement.

Si JetEnumerateColumns retourne des données dans ses paramètres de sortie, l’appelant est responsable de libérer la mémoire dans le tableau ainsi que toute mémoire référencée par les pointeurs incorporés dans ce tableau.

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
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns