Fonction JetRetrieveColumns

S’applique à : Windows | Windows Server

Fonction JetRetrieveColumns

La fonction JetRetrieveColumns récupère plusieurs valeurs de colonne de l’enregistrement actif en une seule opération. Un tableau de structures JET_RETRIEVECOLUMN est utilisé pour décrire l’ensemble de 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 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 JET_RETRIEVECOLUMN dans le tableau donné par prétrievecolumn.

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é passée dans pretinfo-itagSequence>. Les valeurs valides pour les numéros de séquence de colonnes à valeurs multiples sont 1 ou plus. La valeur 0 (zéro) est valide pour cette fonction, mais n’est pas valide pour JetRetrieveColumn.
JET_errBadColumnId	L’ID de colonne donné est en dehors des limites légales d’un ID de colonne.
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 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 retourner n’importe quelle valeur de colonne. Par exemple, les colonnes pouvant être levées par dépôt sont ajustées pour être cohérentes pour le contexte transactionnel de la session appelante et cet ajustement nécessite la mémoire tampon fournie par l’appelant. Si l’espace tampon est insuffisant, 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 donnés sont incorrects. Cela peut se produire si le retinfo.cbStruct est plus petit que la taille de JET_RETINFO.
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_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. 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.
JET_wrnBufferTruncated	La valeur de colonne entière n’a pas pu être récupérée, car la mémoire tampon donnée est inférieure à la taille de la colonne.

En cas de réussite, les données des colonnes et la taille des colonnes sont retournées dans les mémoires tampons fournies décrites dans tableau de structures 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é au lieu 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 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.

Notes

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 pouvez d’abord déterminer le nombre de valeurs d’une colonne. Ensuite, leurs longueurs peuvent être déterminées en appelant à nouveau JetRetrieveColumns avec une structure JET_RETRIEVECOLUMN allouée pour chaque valeur afin de déterminer la longueur des données de colonne. Pour ce faire, transmettez des pointeurs pvData NULL avec cbMax de 0 (zéro) et récupérez la longueur de colonne dans cbActual. Le troisième et dernier appel peut être effectué 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, les autres erreurs, JET_wrnColumnNull sont retournées uniquement dans le champ d’erreur dans JET_RETRIEVECOLUMN. La raison en est que les applications veulent souvent s’assurer que toutes les données ont été récupérées et que le renvoi de cette erreur à partir de JetRetrieveColumns facilite cette compréhension.

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_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns