Extraction d’une ligne de données

Pour extraire une ligne de données, une application appelle SQLFetch. SQLFetch peut être appelé avec n’importe quel type de curseur, mais il déplace uniquement le curseur de l’ensemble de lignes dans une direction vers l’avant uniquement. SQLFetch avance le curseur vers la ligne suivante et retourne les données de toutes les colonnes liées avec des appels à SQLBindCol. Lorsque le curseur atteint la fin du jeu de résultats, SQLFetch retourne SQL_NO_DATA. Pour obtenir des exemples d’appel de SQLFetch, consultez Utilisation de SQLBindCol.

Exactement la façon dont SQLFetch est implémenté est spécifique au pilote, mais le modèle général est pour le pilote de récupérer les données pour toutes les colonnes liées de la source de données, de les convertir en fonction des types des variables liées et de placer les données converties dans ces variables. Si le pilote ne peut pas convertir de données, SQLFetch retourne une erreur. L’application peut continuer à extraire des lignes, mais les données de la ligne actuelle sont perdues. Ce qui arrive aux données des colonnes non liées dépend du pilote, mais la plupart des pilotes récupèrent et dés carte elles ou ne la récupèrent jamais du tout.

Le pilote définit également les valeurs de toutes les mémoires tampons de longueur/indicateur qui ont été liées. Si la valeur de données d’une colonne est NULL, le pilote définit la mémoire tampon de longueur/indicateur correspondante sur SQL_NULL_DATA. Si la valeur de données n’est pas NULL, le pilote définit la longueur/la mémoire tampon de l’indicateur sur la longueur d’octet des données après la conversion. Si cette longueur ne peut pas être déterminée, comme c’est parfois le cas avec des données longues récupérées par plusieurs appels de fonction, le pilote définit la mémoire tampon longueur/indicateur sur SQL_NO_TOTAL. Pour les types de données de longueur fixe, tels que les entiers et les structures de date, la longueur d’octet est la taille du type de données.

Pour les données de longueur variable, telles que les données caractère et binaires, le pilote case activée la longueur d’octet des données converties par rapport à la longueur d’octet de la mémoire tampon liée à la colonne ; la longueur de la mémoire tampon est spécifiée dans l’argument BufferLength dans SQLBindCol. Si la longueur d’octets des données converties est supérieure à la longueur d’octet de la mémoire tampon, le pilote tronque les données pour s’adapter à la mémoire tampon, retourne la longueur nontruncée dans la mémoire tampon de longueur/indicateur, retourne SQL_SUCCESS_WITH_INFO et place SQLSTATE 01004 (Données tronquées) dans les diagnostics. La seule exception à ceci est si un signet de longueur variable est tronqué lorsqu’il est retourné par SQLFetch, qui retourne SQLSTATE 22001 (données de chaîne, tronquées à droite).

Les données de longueur fixe ne sont jamais tronquées, car le pilote suppose que la taille de la mémoire tampon liée est la taille du type de données. La troncation des données a tendance à être rare, car l’application lie généralement une mémoire tampon suffisamment grande pour contenir la valeur de données entière ; elle détermine la taille nécessaire à partir des métadonnées. Toutefois, l’application peut lier explicitement une mémoire tampon qu’elle sait être trop petite. Par exemple, il peut récupérer et afficher les 20 premiers caractères d’une description de partie ou les 100 premiers caractères d’une colonne de texte longue.

Les données de caractères doivent être arrêtées par null par le pilote avant qu’elles ne soient retournées à l’application, même si elles ont été tronquées. Le caractère de terminaison Null n’est pas inclus dans la longueur d’octet retournée, mais nécessite de l’espace dans la mémoire tampon liée. Par exemple, supposons qu’une application utilise des chaînes composées de données de caractères dans le jeu de caractères ASCII, qu’un pilote a 50 caractères de données à retourner et que la mémoire tampon de l’application est de 25 octets. Dans la mémoire tampon de l’application, le pilote retourne les 24 premiers caractères suivis d’un caractère d’arrêt null. Dans la mémoire tampon longueur/indicateur, elle retourne une longueur d’octet de 50.

L’application peut restreindre le nombre de lignes dans le jeu de résultats en définissant l’attribut d’instruction SQL_ATTR_MAX_ROWS avant d’exécuter l’instruction qui crée le jeu de résultats. Par exemple, le mode d’aperçu dans une application utilisée pour mettre en forme des rapports ne nécessite que suffisamment de données pour afficher la première page du rapport. En limitant la taille du jeu de résultats, une telle fonctionnalité s’exécuterait plus rapidement. Cet attribut d’instruction est destiné à réduire le trafic réseau et peut ne pas être pris en charge par tous les pilotes.