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