Fonction SQLGetData

Article
05/23/2023

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLGetData récupère les données d’une colonne unique dans le jeu de résultats ou pour un paramètre unique après que SQLParamData retourne SQL_PARAM_DATA_AVAILABLE. Il peut être appelé plusieurs fois pour récupérer des données de longueur variable en parties.

Syntaxe

  
SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);

Arguments

StatementHandle
[Entrée] Handle d’instruction.

Col_or_Param_Num
[Entrée] Pour récupérer des données de colonne, il s’agit du nombre de colonnes pour lesquelles retourner des données. Les colonnes du jeu de résultats sont numérotées dans l’ordre croissant des colonnes à partir de 1. La colonne signet est le numéro de colonne 0 ; cela ne peut être spécifié que si les signets sont activés.

Pour récupérer des données de paramètre, il s’agit de l’ordinal du paramètre, qui commence à 1.

TargetType
[Entrée] Identificateur de type du type de données C de la mémoire tampon *TargetValuePtr . Pour obtenir la liste des types de données C valides et des identificateurs de type, consultez la section Types de données C dans l’annexe D : Types de données.

Si TargetType est SQL_ARD_TYPE, le pilote utilise l’identificateur de type spécifié dans le champ SQL_DESC_CONCISE_TYPE de l’ARD. Si TargetType est SQL_APD_TYPE, SQLGetData utilise le même type de données C spécifié dans SQLBindParameter. Sinon, le type de données C spécifié dans SQLGetData remplace le type de données C spécifié dans SQLBindParameter. S’il est SQL_C_DEFAULT, le pilote sélectionne le type de données C par défaut en fonction du type de données SQL de la source.

Vous pouvez également spécifier un type de données C étendu. Pour plus d'informations, voir Types de données C dans ODBC.

TargetValuePtr
[Sortie] Pointeur vers la mémoire tampon dans laquelle retourner les données.

TargetValuePtr ne peut pas être NULL.

BufferLength
[Entrée] Longueur de la mémoire tampon *TargetValuePtr en octets.

Le pilote utilise BufferLength pour éviter d’écrire au-delà de la fin de la mémoire tampon *TargetValuePtr lors du retour de données de longueur variable, telles que des données caractère ou binaires. Notez que le pilote compte le caractère d’arrêt null lors du renvoi de données de caractères à *TargetValuePtr. *TargetValuePtr doit donc contenir de l’espace pour le caractère de terminaison Null, ou le pilote tronque les données.

Lorsque le pilote retourne des données de longueur fixe, telles qu’un entier ou une structure de date, le pilote ignore BufferLength et suppose que la mémoire tampon est suffisamment grande pour contenir les données. Il est donc important que l’application alloue une mémoire tampon suffisamment grande pour les données de longueur fixe ou que le pilote écrive au-delà de la fin de la mémoire tampon.

SQLGetData retourne SQLSTATE HY090 (chaîne ou longueur de mémoire tampon non valide) lorsque BufferLength est inférieur à 0, mais pas quand BufferLength est 0.

StrLen_or_IndPtr
[Sortie] Pointeur vers la mémoire tampon dans laquelle retourner la longueur ou la valeur de l’indicateur. S’il s’agit d’un pointeur Null, aucune longueur ou valeur d’indicateur n’est retournée. Cette opération renvoie une erreur lorsque les données extraites sont NULL.

SQLGetData peut retourner les valeurs suivantes dans la mémoire tampon longueur/indicateur :

Longueur des données disponibles pour retourner
SQL_NO_TOTAL
SQL_NULL_DATA

Pour plus d’informations, consultez Utilisation des valeurs longueur/indicateur et « Commentaires » dans cette rubrique.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLGetData retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLGetData et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

SQLSTATE	Erreur	Description
01000	Avertissement général	Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01004	Données de chaîne, tronquées à droite	Toutes les données de la colonne spécifiée, Col_or_Param_Num, ne peuvent pas être récupérées dans un seul appel à la fonction. SQL_NO_TOTAL ou la longueur des données restantes dans la colonne spécifiée avant l’appel actuel à SQLGetData est retournée dans *StrLen_or_IndPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.) Pour plus d’informations sur l’utilisation de plusieurs appels à SQLGetData pour une seule colonne, consultez « Commentaires ».
01S07	Troncation fractionnelle	Les données retournées pour une ou plusieurs colonnes ont été tronquées. Pour les types de données numériques, la partie fractionnaire du nombre a été tronquée. Pour les types de données time, timestamp et interval contenant un composant de temps, la partie fractionnaire de l’heure a été tronquée. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
07006	Violation d’attribut de type de données restreint	La valeur de données d’une colonne dans le jeu de résultats ne peut pas être convertie en type de données C spécifié par l’argument TargetType.
07009	Index de descripteur non valide	La valeur spécifiée pour l’argument Col_or_Param_Num a été 0 et l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_OFF. La valeur spécifiée pour l’argument Col_or_Param_Num était supérieure au nombre de colonnes dans le jeu de résultats. La valeur Col_or_Param_Num n’était pas égale à l’ordinal du paramètre disponible. (DM) La colonne spécifiée a été liée. Cette description ne s’applique pas aux pilotes qui retournent le masque de bits SQL_GD_BOUND pour l’option SQL_GETDATA_EXTENSIONS dans SQLGetInfo. (DM) Le nombre de la colonne spécifiée était inférieur ou égal au nombre de la colonne liée la plus élevée. Cette description ne s’applique pas aux pilotes qui retournent le masque de bits SQL_GD_ANY_COLUMN pour l’option de SQL_GETDATA_EXTENSIONS dans SQLGetInfo. (DM) L’application a déjà appelé SQLGetData pour la ligne active ; le numéro de la colonne spécifiée dans l’appel actuel était inférieur au nombre de la colonne spécifiée dans l’appel précédent ; et le pilote ne retourne pas le masque de bits SQL_GD_ANY_ORDER pour l’option de SQL_GETDATA_EXTENSIONS dans SQLGetInfo. (DM) L’argument TargetType était SQL_ARD_TYPE, et l’enregistrement de descripteur Col_or_Param_Num dans l’ARD a échoué la vérification de cohérence. (DM) L’argument TargetType était SQL_ARD_TYPE, et la valeur dans le champ SQL_DESC_COUNT de l’ARD était inférieure à l’argument Col_or_Param_Num .
08S01	Échec du lien de communication	Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant l’achèvement du traitement de la fonction.
22002	Variable d’indicateur requise, mais non fournie	StrLen_or_IndPtr était un pointeur Null et les données NULL ont été récupérées.
22003	Valeur numérique hors plage	Le renvoi de la valeur numérique (en tant que numérique ou chaîne) pour la colonne aurait provoqué la troncation de l’ensemble (par opposition à la fraction) du nombre. Pour plus d’informations, consultez l’annexe D : Types de données.
22007	Format datetime non valide	La colonne de caractères du jeu de résultats était liée à une structure de date, d’heure ou d’horodatage C, et la valeur de la colonne était une date, une heure ou un horodatage non valide, respectivement. Pour plus d’informations, consultez l’annexe D : Types de données.
22012	Division par zéro	Une valeur d’une expression arithmétique qui a entraîné la division par zéro a été retournée.
22015	Dépassement de champ d’intervalle	L’affectation d’un type SQL numérique ou d’intervalle exact à un type C d’intervalle a provoqué une perte de chiffres significatifs dans le champ de début. Lorsque vous retournez des données à un type C d’intervalle, il n’y a pas eu de représentation de la valeur du type SQL dans le type C d’intervalle.
22018	Valeur de caractère non valide pour la spécification de cast	Une colonne de caractères dans le jeu de résultats a été retournée à une mémoire tampon C de caractère, et la colonne contenait un caractère pour lequel il n’y avait aucune représentation dans le jeu de caractères de la mémoire tampon. Le type C était un type numérique exact ou approximatif, un datetime ou un type de données d’intervalle ; le type SQL de la colonne était un type de données caractère ; et la valeur de la colonne n’était pas un littéral valide du type C lié.
24 000	État de curseur non valide	(DM) La fonction a été appelée sans appeler SQLFetch ou SQLFetchScroll pour positionner le curseur sur la ligne de données requise. (DM) L’instructionHandle était dans un état exécuté, mais aucun jeu de résultats n’a été associé à l’instruction StatementHandle. Un curseur a été ouvert sur l’instruction StatementHandle et SQLFetchScroll ou SQLFetchScroll , mais le curseur a été positionné avant le début du jeu de résultats ou après la fin du jeu de résultats.
HY000	Erreur générale	Une erreur s’est produite pour laquelle il n’y avait aucun SQLSTATE spécifique et pour lequel aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans la mémoire tampon MessageText décrit l’erreur et sa cause.
HY001	Erreur d’allocation de mémoire	Le pilote n’a pas pu allouer de mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction.
HY003	Type de programme hors plage	(DM) L’argument TargetType n’était pas un type de données valide, SQL_C_DEFAULT, SQL_ARD_TYPE (en cas de récupération de données de colonne) ou SQL_APD_TYPE (en cas de récupération des données de paramètre). (DM) L’argument Col_or_Param_Num était 0 et l’argument TargetType n’était pas SQL_C_BOOKMARK pour un signet de longueur fixe ou SQL_C_VARBOOKMARK pour un signet de longueur variable.
HY008	Opération annulée	Le traitement asynchrone a été activé pour StatementHandle. La fonction a été appelée, et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle, puis la fonction a été appelée à nouveau sur l’InstructionHandle. La fonction a été appelée, et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle à partir d’un autre thread dans une application multithread, puis la fonction a été appelée à nouveau sur l’InstructionHandle.
HY009	Utilisation non valide du pointeur Null	(DM) L’argument TargetValuePtr était un pointeur Null.
HY010	Erreur de séquence de fonction	(DM) L’instruction StatementHandle spécifiée n’était pas dans un état exécuté. La fonction a été appelée sans appeler SQLExecDirect, SQLExecute ou une fonction de catalogue. (DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé à StatementHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLGetData a été appelée. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour l’instruction StatementHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’instructionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution. (DM) L’instructionHandle était dans un état exécuté, mais aucun jeu de résultats n’a été associé à l’instruction StatementHandle. Un appel à SQLExeceute, SQLExecDirect ou SQLMoreResults a retourné SQL_PARAM_DATA_AVAILABLE, mais SQLGetData a été appelé, au lieu de SQLParamData.
HY013	Erreur de gestion de la mémoire	L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, éventuellement en raison de conditions de mémoire insuffisantes.
HY090	Longueur de la chaîne ou de la mémoire tampon non valide	(DM) La valeur spécifiée pour l’argument BufferLength était inférieure à 0. La valeur spécifiée pour l’argument BufferLength était inférieure à 4, l’argument Col_or_Param_Num a été défini sur 0 et le pilote était un pilote ODBC 2.x.
HY109	Position du curseur non valide	Le curseur a été positionné (par SQLSetPos, SQLFetch, SQLFetchScroll ou SQLBulkOperations) sur une ligne qui avait été supprimée ou qui n’a pas pu être récupérée. Le curseur était un curseur vers l’avant uniquement et la taille de l’ensemble de lignes était supérieure à une.
HY117	La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées.	(DM) Pour plus d’informations sur l’état suspendu, consultez la fonction SQLEndTran.
HYC00	Fonctionnalité facultative non implémentée	Le pilote ou la source de données ne prend pas en charge l’utilisation de SQLGetData avec plusieurs lignes dans SQLFetchScroll. Cette description ne s’applique pas aux pilotes qui retournent le masque de bits SQL_GD_BLOCK pour l’option SQL_GETDATA_EXTENSIONS dans SQLGetInfo. Le pilote ou la source de données ne prend pas en charge la conversion spécifiée par la combinaison de l’argument TargetType et du type de données SQL de la colonne correspondante. Cette erreur s’applique uniquement lorsque le type de données SQL de la colonne a été mappé à un type de données SQL spécifique au pilote. Le pilote prend uniquement en charge ODBC 2.x, et l’argument TargetType a été l’un des éléments suivants : SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT et l’un des types de données C d’intervalle répertoriés dans les types de données C dans l’annexe D : Types de données. Le pilote prend uniquement en charge les versions ODBC antérieures à la version 3.50 et l’argument TargetType a été SQL_C_GUID.
HYT01	Délai d’attente de la connexion expiré	La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Le pilote ne prend pas en charge cette fonction	(DM) Le pilote correspondant à StatementHandle ne prend pas en charge la fonction.
IM017	L’interrogation est désactivée en mode de notification asynchrone	Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée.
IM018	SQLCompleteAsync n’a pas été appelé pour terminer l’opération asynchrone précédente sur ce handle.	Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer un post-traitement et terminer l’opération.

Commentaires

SQLGetData retourne les données dans une colonne spécifiée. SQLGetData ne peut être appelé qu’après une ou plusieurs lignes extraites du jeu de résultats par SQLFetch, SQLFetchScroll ou SQLExtendedFetch. Si les données de longueur variable sont trop volumineuses pour être retournées dans un seul appel à SQLGetData (en raison d’une limitation dans l’application), SQLGetData peut la récupérer en parties. Il est possible de lier certaines colonnes dans une ligne et d’appeler SQLGetData pour d’autres, bien que cela soit soumis à certaines restrictions. Pour plus d’informations, consultez Obtention de données longues.

Pour plus d’informations sur l’utilisation de SQLGetData avec des paramètres de sortie diffusés en continu, consultez Récupération des paramètres de sortie à l’aide de SQLGetData.

Utilisation de SQLGetData

Si le pilote ne prend pas en charge les extensions de SQLGetData, la fonction peut retourner des données uniquement pour les colonnes non liées avec un nombre supérieur à celui de la dernière colonne liée. En outre, dans une ligne de données, la valeur de l’argument Col_or_Param_Num dans chaque appel à SQLGetData doit être supérieure ou égale à la valeur de Col_or_Param_Num dans l’appel précédent ; autrement dit, les données doivent être récupérées dans l’ordre croissant des nombres de colonnes. Enfin, si aucune extension n’est prise en charge, SQLGetData ne peut pas être appelé si la taille de l’ensemble de lignes est supérieure à 1.

Les conducteurs peuvent assouplir l’une de ces restrictions. Pour déterminer les restrictions qu’un pilote assouplit, une application appelle SQLGetInfo avec l’une des options de SQL_GETDATA_EXTENSIONS suivantes :

SQL_GD_OUTPUT_PARAMS = SQLGetData peut être appelé pour retourner des valeurs de paramètre de sortie. Pour plus d'informations, voir Récupération des paramètres de sortie à l'aide de SQLGetData.
SQL_GD_ANY_COLUMN. Si cette option est retournée, SQLGetData peut être appelé pour n’importe quelle colonne non liée, y compris celles avant la dernière colonne liée.
SQL_GD_ANY_ORDER. Si cette option est retournée, SQLGetData peut être appelé pour les colonnes non liées dans n’importe quel ordre.
SQL_GD_BLOCK. Si cette option est retournée par SQLGetInfo pour l’SQL_GETDATA_EXTENSIONS InfoType, le pilote prend en charge les appels à SQLGetData lorsque la taille de l’ensemble de lignes est supérieure à 1 et que l’application peut appeler SQLSetPos avec l’option SQL_POSITION pour positionner le curseur sur la ligne correcte avant d’appeler SQLGetData.
SQL_GD_BOUND. Si cette option est retournée, SQLGetData peut être appelé pour les colonnes liées ainsi que pour les colonnes indépendantes.

Il existe deux exceptions à ces restrictions et la capacité d’un conducteur à les détendre. Tout d’abord, SQLGetData ne doit jamais être appelé pour un curseur avant uniquement lorsque la taille de l’ensemble de lignes est supérieure à 1. Ensuite, si un pilote prend en charge les signets, il doit toujours prendre en charge la possibilité d’appeler SQLGetData pour la colonne 0, même s’il n’autorise pas les applications à appeler SQLGetData pour d’autres colonnes avant la dernière colonne liée. (Lorsqu’une application fonctionne avec un pilote ODBC 2*.x*, SQLGetData retourne correctement un signet lorsqu’il est appelé avec Col_or_Param_Num égal à 0 après un appel à SQLFetch, car SQLFetch est mappé par le Gestionnaire de pilotes ODBC 3*.x* à SQLExtendedFetch avec une extraction d’SQL_FETCH_NEXT, et SQLGetData avec un Col_or_Param_Num de 0 est mappé par le Gestionnaire de pilotes ODBC 3*.x* à SQLGetStmtOption avec une option fOption de SQL_GET_BOOKMARK.)

SQLGetData ne peut pas être utilisé pour récupérer le signet d’une ligne simplement insérée en appelant SQLBulkOperations avec l’option SQL_ADD, car le curseur n’est pas positionné sur la ligne. Une application peut récupérer le signet pour une telle ligne en liant la colonne 0 avant d’appeler SQLBulkOperations avec SQL_ADD, auquel cas SQLBulkOperations retourne le signet dans la mémoire tampon liée. SQLFetchScroll peut ensuite être appelé avec SQL_FETCH_BOOKMARK pour repositionner le curseur sur cette ligne.

Si l’argument TargetType est un type de données d’intervalle, la précision de début d’intervalle par défaut (2) et l’intervalle par défaut seconde (6), comme défini dans les champs SQL_DESC_DATETIME_INTERVAL_PRECISION et SQL_DESC_PRECISION de l’ARD, respectivement, sont utilisés pour les données. Si l’argument TargetType est un type de données SQL_C_NUMERIC, la précision par défaut (définie par le pilote) et l’échelle par défaut (0), telles que définies dans les champs SQL_DESC_PRECISION et SQL_DESC_SCALE de l’ARD, sont utilisées pour les données. Si une précision ou une échelle par défaut n’est pas appropriée, l’application doit définir explicitement le champ descripteur approprié par un appel à SQLSetDescField ou SQLSetDescRec. Il peut définir le champ SQL_DESC_CONCISE_TYPE sur SQL_C_NUMERIC et appeler SQLGetData avec un argument TargetType de SQL_ARD_TYPE, ce qui entraîne l’utilisation des valeurs de précision et d’échelle dans les champs de descripteur.

Remarque

Dans ODBC 2*.x*, les applications définissent TargetType sur SQL_C_DATE, SQL_C_TIME ou SQL_C_TIMESTAMP pour indiquer que *TargetValuePtr est une structure de date, d’heure ou d’horodatage. Dans ODBC 3*.x*, les applications définissent TargetType sur SQL_C_TYPE_DATE, SQL_C_TYPE_TIME ou SQL_C_TYPE_TIMESTAMP. Le Gestionnaire de pilotes effectue les mappages appropriés si nécessaire, en fonction de la version de l’application et du pilote.

Récupération de données de longueur variable dans des parties

SQLGetData peut être utilisé pour récupérer des données d’une colonne qui contient des données de longueur variable en parties, autrement dit, lorsque l’identificateur du type de données SQL de la colonne est SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY ou un identificateur spécifique au pilote pour un type de longueur variable.

Pour récupérer des données d’une colonne en parties, l’application appelle SQLGetData plusieurs fois par succession pour la même colonne. À chaque appel, SQLGetData retourne la partie suivante des données. Il incombe à l’application de réassembler les parties, en prenant soin de supprimer le caractère d’arrêt null des parties intermédiaires des données de caractères. S’il y a plus de données à retourner ou pas assez de mémoire tampon a été allouée pour le caractère de fin, SQLGetData retourne SQL_SUCCESS_WITH_INFO et SQLSTATE 01004 (données tronquées). Lorsqu’il retourne la dernière partie des données, SQLGetData retourne SQL_SUCCESS. Ni SQL_NO_TOTAL ni zéro ne peuvent être retournés lors du dernier appel valide pour récupérer des données d’une colonne, car l’application n’aurait alors aucun moyen de savoir combien de données dans la mémoire tampon de l’application est valide. Si SQLGetData est appelé après cela, il retourne SQL_NO_DATA. Pour plus d’informations, consultez la section suivante , « Récupération de données avec SQLGetData ».

Les signets de longueur variable peuvent être retournés dans des parties par SQLGetData. Comme pour d’autres données, un appel à SQLGetData pour retourner des signets de longueur variable dans les parties retourne SQLSTATE 01004 (données de chaîne, tronquées à droite) et SQL_SUCCESS_WITH_INFO lorsqu’il y a plus de données à renvoyer. Cela est différent du cas où un signet de longueur variable est tronqué par un appel à SQLFetch ou SQLFetchScroll, qui retourne SQL_ERROR et SQLSTATE 22001 (données de chaîne, tronquées à droite).

SQLGetData ne peut pas être utilisé pour retourner des données de longueur fixe en parties. Si SQLGetData est appelé plusieurs fois dans une ligne pour une colonne contenant des données de longueur fixe, elle retourne SQL_NO_DATA pour tous les appels après le premier.

Récupération des paramètres de sortie diffusés en continu

Si un pilote prend en charge les paramètres de sortie diffusés en continu, une application peut appeler SQLGetData avec une petite mémoire tampon plusieurs fois pour récupérer une valeur de paramètre volumineuse. Pour plus d’informations sur le paramètre de sortie diffusé en continu, consultez Récupération des paramètres de sortie à l’aide de SQLGetData.

Récupération de données avec SQLGetData

Pour retourner des données pour la colonne spécifiée, SQLGetData effectue la séquence d’étapes suivante :

Retourne SQL_NO_DATA s’il a déjà retourné toutes les données de la colonne.
Définit *StrLen_or_IndPtr sur SQL_NULL_DATA si les données ont la valeur NULL. Si les données sont NULL et StrLen_or_IndPtr était un pointeur Null, SQLGetData retourne SQLSTATE 22002 (variable d’indicateur requise, mais non fournie).

Si les données de la colonne ne sont pas NULL, SQLGetData passe à l’étape 3.
Si l’attribut d’instruction SQL_ATTR_MAX_LENGTH est défini sur une valeur différente de zéro, si la colonne contient des données caractères ou binaires et si SQLGetData n’a pas été appelé précédemment pour la colonne, les données sont tronquées à SQL_ATTR_MAX_LENGTH octets.

Remarque

L’attribut d’instruction SQL_ATTR_MAX_LENGTH est destiné à réduire le trafic réseau. Elle est généralement implémentée par la source de données, qui tronque les données avant de les retourner sur le réseau. Les pilotes et les sources de données ne sont pas nécessaires pour le prendre en charge. Par conséquent, pour garantir que les données sont tronquées à une taille particulière, une application doit allouer une mémoire tampon de cette taille et spécifier la taille dans l’argument BufferLength .
Convertit les données en type spécifié dans TargetType. Les données reçoivent la précision et l’échelle par défaut pour ce type de données. Si TargetType est SQL_ARD_TYPE, le type de données dans le champ SQL_DESC_CONCISE_TYPE de l’ARD est utilisé. Si TargetType est SQL_ARD_TYPE, les données reçoivent la précision et l’échelle dans les SQL_DESC_DATETIME_INTERVAL_PRECISION, les SQL_DESC_PRECISION et les champs SQL_DESC_SCALE de l’ARD, selon le type de données dans le champ SQL_DESC_CONCISE_TYPE. Si une précision ou une échelle par défaut n’est pas appropriée, l’application doit définir explicitement le champ descripteur approprié par un appel à SQLSetDescField ou SQLSetDescRec.
Si les données ont été converties en un type de données de longueur variable, tel que caractère ou binaire, SQLGetData vérifie si la longueur des données dépasse BufferLength. Si la longueur des données de caractère (y compris le caractère de terminaison Null) dépasse BufferLength, SQLGetData tronque les données en BufferLength moins la longueur d’un caractère d’arrêt Null. Elle met ensuite fin à la valeur Null. Si la longueur des données binaires dépasse la longueur de la mémoire tampon de données, SQLGetData la tronque en octets BufferLength .

Si la mémoire tampon de données fournie est trop petite pour contenir le caractère de terminaison Null, SQLGetData retourne SQL_SUCCESS_WITH_INFO et SQLSTATE 01004.

SQLGetData ne tronque jamais les données converties en types de données de longueur fixe ; il suppose toujours que la longueur de *TargetValuePtr est la taille du type de données.
Place les données converties (et éventuellement tronquées) dans *TargetValuePtr. Notez que SQLGetData ne peut pas retourner les données hors ligne.
Place la longueur des données dans *StrLen_or_IndPtr. Si StrLen_or_IndPtr était un pointeur Null, SQLGetData ne retourne pas la longueur.
- Pour les données caractères ou binaires, il s’agit de la longueur des données après la conversion et avant la troncation en raison de BufferLength. Si le pilote ne peut pas déterminer la longueur des données après la conversion, comme c’est parfois le cas avec des données longues, elle retourne SQL_SUCCESS_WITH_INFO et définit la longueur sur SQL_NO_TOTAL. (Dernier appel à SQLGetData doit toujours retourner la longueur des données, pas zéro ni SQL_NO_TOTAL.) Si les données ont été tronquées en raison de l’attribut d’instruction SQL_ATTR_MAX_LENGTH, la valeur de cet attribut , par opposition à la longueur réelle, est placée dans *StrLen_or_IndPtr. Cela est dû au fait que cet attribut est conçu pour tronquer les données sur le serveur avant la conversion. Par conséquent, le pilote n’a aucun moyen de déterminer la longueur réelle. Lorsque SQLGetData est appelé plusieurs fois par succession pour la même colonne, il s’agit de la longueur des données disponibles au début de l’appel actuel ; autrement dit, la longueur diminue avec chaque appel suivant.
- Pour tous les autres types de données, il s’agit de la longueur des données après la conversion ; autrement dit, il s’agit de la taille du type vers lequel les données ont été converties.
Si les données sont tronquées sans perte de signification pendant la conversion (par exemple, le nombre réel 1,234 est tronqué lorsqu’elles sont converties en entier 1) ou parce que BufferLength est trop petite (par exemple, la chaîne « abcdef » est placée dans une mémoire tampon de 4 octets), SQLGetData retourne SQLSTATE 01004 (tronqué de données) et SQL_SUCCESS_WITH_INFO. Si les données sont tronquées sans perte de signification en raison de l’attribut d’instruction SQL_ATTR_MAX_LENGTH, SQLGetData retourne SQL_SUCCESS et ne retourne pas SQLSTATE 01004 (données tronquées).

Le contenu de la mémoire tampon de données liée (si SQLGetData est appelé sur une colonne liée) et la mémoire tampon de longueur/indicateur ne sont pas définies si SQLGetData ne retourne pas SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.

Les appels successifs à SQLGetData récupèrent les données de la dernière colonne demandée ; les décalages antérieurs ne sont plus valides. Par exemple, lorsque la séquence suivante est effectuée :

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)

le deuxième appel à SQLGetData(icol=n) récupère les données à partir du début de la colonne n. Tout décalage dans les données en raison d’appels antérieurs à SQLGetData pour la colonne n’est plus valide.

Descripteurs et SQLGetData

SQLGetData n’interagit pas directement avec les champs de descripteur.

Si TargetType est SQL_ARD_TYPE, le type de données dans le champ SQL_DESC_CONCISE_TYPE de l’ARD est utilisé. Si TargetType est SQL_ARD_TYPE ou SQL_C_DEFAULT, les données reçoivent la précision et l’échelle dans le SQL_DESC_DATETIME_INTERVAL_PRECISION, les SQL_DESC_PRECISION et les champs SQL_DESC_SCALE de l’ARD, en fonction du type de données dans le champ SQL_DESC_CONCISE_TYPE.

Exemple de code

Dans l’exemple suivant, une application exécute une instruction SELECT pour retourner un jeu de résultats des ID, noms et numéros de téléphone clients triés par nom, ID et numéro de téléphone. Pour chaque ligne de données, elle appelle SQLFetch pour positionner le curseur vers la ligne suivante. Il appelle SQLGetData pour récupérer les données extraites ; les mémoires tampons pour les données et le nombre retourné d’octets sont spécifiés dans l’appel à SQLGetData. Enfin, il imprime le nom, l’ID et le numéro de téléphone de chaque employé.

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}

Pour plus d’informations sur	Consultez
Affectation de stockage pour une colonne dans un jeu de résultats	SQLBindCol
Exécution d’opérations en bloc qui ne sont pas liées à la position du curseur de bloc	SQLBulkOperations
Annulation du traitement des instructions	SQLCancel
Exécution d’une instruction SQL	SQLExecDirect
Exécution d’une instruction SQL préparée	SQLExecute
Extraction d’un bloc de données ou défilement d’un jeu de résultats	SQLFetchScroll
Extraction d’une seule ligne de données ou d’un bloc de données dans une direction vers l’avant uniquement	SQLFetch
Envoi de données de paramètre au moment de l’exécution	SQLPutData
Positionnement du curseur, actualisation des données dans l’ensemble de lignes ou mise à jour ou suppression de données dans l’ensemble de lignes	SQLSetPos

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Récupération des paramètres de sortie à l’aide de SQLGetData

Partage via

Fonction SQLGetData

Syntaxe

Arguments

Retours

Diagnostics

Commentaires

Utilisation de SQLGetData

Récupération de données de longueur variable dans des parties

Récupération des paramètres de sortie diffusés en continu

Récupération de données avec SQLGetData

Descripteurs et SQLGetData

Exemple de code

Voir aussi

Commentaires

Ressources supplémentaires

Partage via

Fonction SQLGetData

Syntaxe

Arguments

Retours

Diagnostics

Commentaires

Utilisation de SQLGetData

Récupération de données de longueur variable dans des parties

Récupération des paramètres de sortie diffusés en continu

Récupération de données avec SQLGetData

Descripteurs et SQLGetData

Exemple de code

Fonctions connexes

Voir aussi

Commentaires

Ressources supplémentaires