Fonction SQLGetData

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.

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.

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 :

1. Retourne SQL_NO_DATA s’il a déjà retourné toutes les données de la colonne.

2. 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.

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 .

4. 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.

5. 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.

6. Place les données converties (et éventuellement tronquées) dans *TargetValuePtr. Notez que SQLGetData ne peut pas retourner les données hors ligne.

7. 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.

8. 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;  
      }  
   }  
}  

Fonctions connexes

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