Fonction JetRetrieveColumns

S’applique à : Windows | Windows Serveurs

Fonction JetRetrieveColumns

La fonction JetRetrieveColumns Récupère plusieurs valeurs de colonne de l’enregistrement actuel en une seule opération. Un tableau de structures de JET_RETRIEVECOLUMN est utilisé pour décrire l’ensemble des valeurs de colonne à récupérer et pour décrire les mémoires tampons de sortie pour chaque valeur de colonne à récupérer.

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

Paramètres

sesid

Session à utiliser pour cet appel.

TableID

Curseur à utiliser pour cet appel.

pretrievecolumn

Pointeur vers un tableau d’une ou plusieurs structures de JET_RETRIEVECOLUMN . Chaque structure comprend des descriptions de la valeur de colonne à récupérer et de l’emplacement de stockage des données retournées.

cretrievecolumn

Nombre de structures de JET_RETRIEVECOLUMN dans le tableau donné par pretrievecolumn.

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

Une valeur de numéro de séquence de colonne à valeurs multiples non valide a été transmise dans pretinfo- > itagSequence. Les valeurs valides pour les numéros de séquence de valeur de colonne à valeurs multiples sont égales ou supérieures à 1. La valeur 0 (zéro) est valide pour cette fonction, mais n’est pas valide pour JetRetrieveColumn.

JET_errBadColumnId

L’ID de colonne indiqué est en dehors des limites autorisées d’un ID de colonne.

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_errColumnNotFound

La colonne décrite par le ColumnID donné n’existe pas dans la table.

JET_errIndexTuplesCannotRetrieveFromIndex

Les colonnes indexées en tant que sous-chaînes ne peuvent pas être récupérées à partir de l’index, car seule une petite partie de la colonne est généralement présente dans chaque entrée d’index.

JET_errInvalidBufferSize

Dans certains cas, la mémoire tampon donnée pour la colonne de récupération doit être suffisamment dimensionnée pour pouvoir retourner n’importe quel volume de la valeur de colonne. Par exemple, les colonnes pouvant être mises à jour par tiers de confiance sont ajustées pour être cohérentes pour le contexte transactionnel de la session appelante et cet ajustement requiert la mémoire tampon fournie par l’appelant. Si un espace de mémoire tampon insuffisant est fourni, JET_errInvalidBufferSize est retourné et aucune donnée de colonne n’est retournée.

JET_errInvalidgrbit

Les options fournies sont inconnues ou une combinaison non conforme de paramètres de bits connus.

JET_errInvalidParameter

Un ou plusieurs des paramètres spécifiés sont incorrects. Cela peut se produire si retinfo. cbStruct est plus petit que la taille de JET_RETINFO.

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.

Windows XP : cette erreur est renvoyée uniquement par Windows XP et les versions ultérieures.

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.

Windows XP : 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.

JET_wrnBufferTruncated

Impossible de récupérer la valeur de colonne entière, car la taille de la mémoire tampon donnée est inférieure à celle de la colonne.

En cas de réussite, les données de colonnes et la taille de colonne sont retournées dans les mémoires tampons fournies décrites dans tableau de structures de JET_RETRIEVECOLUMN . Si un itagSequence a été défini sur 0 (zéro) pour indiquer que le nombre d’instances d’un champ à valeurs multiples était souhaité à la place des données de colonne, le nombre d’instances d’une colonne à valeurs multiples est retourné dans le champ itagSequence lui-même. Chaque structure de JET_RETRIEVECOLUMN a un champ d’erreur qui contient des avertissements pour la colonne récupérée. Si la colonne a une valeur null , le code d’erreur est défini sur JET_wrnColumnNull.

En cas d’échec, l’emplacement du curseur reste inchangé et aucune donnée n’est copiée dans la mémoire tampon fournie.

Remarques

JetRetrieveColumns prend en charge une fonctionnalité que JetRetrieveColumn ne fait pas. Il s’agit de la possibilité de récupérer le nombre d’instances d’une colonne à valeurs multiples. L’objectif de cette fonctionnalité est de permettre à une application de récupérer toutes les valeurs d’une colonne. Pour ce faire, vous devez d’abord déterminer le nombre de valeurs d’une colonne. Ensuite, leur longueur peut être déterminée en appelant à nouveau JetRetrieveColumns avec une structure JET_RETRIEVECOLUMN allouée pour chaque valeur afin de déterminer la longueur des données de la colonne. Pour ce faire, vous pouvez passer des pointeurs PvData null avec cbMax de 0 (zéro) et récupérer la longueur de colonne dans cbActual. Le troisième et le dernier appel peuvent être effectués avec la mémoire allouée pour les données de valeur de colonne.

Si une colonne Récupérée est tronquée en raison d’une mémoire tampon de longueur insuffisante, l’API retourne JET_wrnBufferTruncated. Toutefois, d’autres erreurs, JET_wrnColumnNull sont retournées uniquement dans le champ d’erreur de JET_RETRIEVECOLUMN. Cela est dû au fait que les applications veulent souvent s’assurer que toutes les données ont été récupérées et que le retour de cette erreur à partir de JetRetrieveColumns facilite cette compréhension.

Configuration requise

Condition requise Valeur

Client

requiert Windows Vista, Windows XP ou Windows 2000 Professional.

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

Requiert ESENT.dll.

Voir aussi

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns