SQLFetch, fonction

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

Résumé
SQLFetch récupère l’ensemble de lignes suivant des données du jeu de résultats et retourne des données pour toutes les colonnes liées.

Syntaxe

  
SQLRETURN SQLFetch(  
     SQLHSTMT     StatementHandle);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

Retours

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

Diagnostics

Lorsque SQLFetch retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant la fonction SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un handle d’instructionHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLFetch 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. Si une erreur se produit sur une seule colonne, SQLGetDiagField peut être appelé avec un DiagIdentifier de SQL_DIAG_COLUMN_NUMBER pour déterminer la colonne sur laquelle l’erreur s’est produite ; et SQLGetDiagField peut être appelé avec un DiagIdentifier de SQL_DIAG_ROW_NUMBER pour déterminer la ligne qui contient cette colonne.

Pour tous les SQLSTATEs qui peuvent retourner SQL_SUCCESS_WITH_INFO ou SQL_ERROR (sauf 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO est retourné si une erreur se produit sur une ou plusieurs lignes, mais pas toutes, les lignes d’une opération multirow et SQL_ERROR est retournée si une erreur se produit sur une opération à une seule ligne.

Commentaires

SQLFetch retourne l’ensemble de lignes suivant dans le jeu de résultats. Il peut être appelé uniquement lorsqu’un jeu de résultats existe : autrement dit, après un appel qui crée un jeu de résultats et avant que le curseur sur ce jeu de résultats soit fermé. Si des colonnes sont liées, elle retourne les données de ces colonnes. Si l’application a spécifié un pointeur vers un tableau d’état de ligne ou une mémoire tampon dans laquelle retourner le nombre de lignes extraites, SQLFetch retourne également ces informations. Les appels à SQLFetch peuvent être mélangés avec des appels à SQLFetchScroll , mais ils ne peuvent pas être mélangés avec des appels à SQLExtendedFetch. Pour plus d’informations, consultez Extraction d’une ligne de données.

Si une application ODBC 3*.x* fonctionne avec un pilote ODBC 2*.x*, le Gestionnaire de pilotes mappe les appels SQLFetch à SQLExtendedFetch pour un pilote ODBC 2*.x* qui prend en charge SQLExtendedFetch. Si le pilote ODBC 2*.x* ne prend pas en charge SQLExtendedFetch, le Gestionnaire de pilotes mappe les appels SQLFetch à SQLFetch dans le pilote ODBC 2*.x*, qui ne peut extraire qu’une seule ligne.

Pour plus d’informations, consultez Bloquer les curseurs de bloc, les curseurs à défilement et la compatibilité descendante dans l’annexe G : Instructions relatives à la compatibilité descendante.

Positionnement du curseur

Lorsque le jeu de résultats est créé, le curseur est positionné avant le début du jeu de résultats. SQLFetch récupère l’ensemble de lignes suivant. Il équivaut à appeler SQLFetchScroll avec FetchOrientation défini sur SQL_FETCH_NEXT. Pour plus d’informations sur les curseurs, consultez Curseurs et curseurs de bloc.

L’attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE spécifie le nombre de lignes dans l’ensemble de lignes. Si l’ensemble de lignes récupéré par SQLFetch chevauche la fin du jeu de résultats, SQLFetch retourne un ensemble de lignes partiel. Autrement dit, si S + R - 1 est supérieur à L, où S est la ligne de départ de l’ensemble de lignes récupéré, R est la taille de l’ensemble de lignes et L est la dernière ligne du jeu de résultats, puis seulement les premières lignes L - S + 1 de l’ensemble de lignes sont valides. Les lignes restantes sont vides et ont un état de SQL_ROW_NOROW.

Une fois que SQLFetch est retourné, la ligne actuelle est la première ligne de l’ensemble de lignes.

Les règles répertoriées dans le tableau suivant décrivent le positionnement du curseur après un appel à SQLFetch, en fonction des conditions répertoriées dans le deuxième tableau de cette section.

[1] Si la taille de l’ensemble de lignes est modifiée entre les extractions, il s’agit de la taille de l’ensemble de lignes utilisée avec la récupération précédente.

[2] Si la taille de l’ensemble de lignes est modifiée entre les extractions, il s’agit de la taille de l’ensemble de lignes utilisée avec la nouvelle extraction.

Par exemple, supposons qu’un jeu de résultats comporte 100 lignes et que la taille de l’ensemble de lignes est 5. Le tableau suivant montre l’ensemble de lignes et le code de retour retourné par SQLFetch pour différentes positions de départ.

Retour de données dans des colonnes liées

À mesure que SQLFetch retourne chaque ligne, elle place les données de chaque colonne liée dans la mémoire tampon liée à cette colonne. Si aucune colonne n’est liée, SQLFetch ne retourne aucune donnée, mais déplace le curseur de bloc vers l’avant. Les données peuvent toujours être récupérées à l’aide de SQLGetData. Si le curseur est un curseur multirow (autrement dit, la SQL_ATTR_ROW_ARRAY_SIZE est supérieure à 1), SQLGetData peut être appelé uniquement si SQL_GD_BLOCK est retourné lorsque SQLGetInfo est appelé avec un InfoType de SQL_GETDATA_EXTENSIONS. (Pour plus d’informations, consultez SQLGetData.)

Pour chaque colonne liée d’une ligne, SQLFetch effectue les opérations suivantes :

1. Définit la mémoire tampon de longueur/indicateur sur SQL_NULL_DATA et passe à la colonne suivante si les données sont NULL. Si les données sont NULL et qu’aucune mémoire tampon de longueur/indicateur n’a été liée, SQLFetch retourne SQLSTATE 22002 (variable d’indicateur requise, mais non fournie) pour la ligne et passe à la ligne suivante. Pour plus d’informations sur la façon de déterminer l’adresse de la mémoire tampon de longueur/indicateur, consultez « Adresses de mémoire tampon » dans SQLBindCol.

   Si les données de la colonne ne sont pas NULL, SQLFetch passe à l’étape 2.

2. Si l’attribut d’instruction SQL_ATTR_MAX_LENGTH est défini sur une valeur différente de zéro et que la colonne contient des données caractères ou binaires, les données sont tronquées en octets SQL_ATTR_MAX_LENGTH.

   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 cbValueMax dans SQLBindCol.

3. Convertit les données en type spécifié par TargetType dans SQLBindCol.

4. Si les données ont été converties en type de données de longueur variable, comme le caractère ou le binaire, SQLFetch vérifie si la longueur des données dépasse la longueur de la mémoire tampon de données. Si la longueur des données caractère (y compris le caractère de terminaison Null) dépasse la longueur de la mémoire tampon de données, SQLFetch tronque les données à la longueur de la mémoire tampon de données moins la longueur d’un caractère de terminaison 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, SQLFetch la tronque à la longueur de la mémoire tampon de données. La longueur de la mémoire tampon de données est spécifiée avec BufferLength dans SQLBindCol.

   SQLFetch ne tronque jamais les données converties en types de données de longueur fixe ; il suppose toujours que la longueur de la mémoire tampon de données est la taille du type de données.

5. Place les données converties (et éventuellement tronquées) dans la mémoire tampon de données. Pour plus d’informations sur la façon de déterminer l’adresse de la mémoire tampon de données, consultez « Adresses de mémoire tampon » dans SQLBindCol.

6. Place la longueur des données dans la mémoire tampon longueur/indicateur. Si le pointeur d’indicateur et le pointeur de longueur ont tous deux été définis sur la même mémoire tampon (comme un appel à SQLBindCol le fait), la longueur est écrite dans la mémoire tampon pour les données valides et SQL_NULL_DATA est écrite dans la mémoire tampon pour les données NULL. Si aucune mémoire tampon de longueur/indicateur n’a été liée, SQLFetch 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 la mémoire tampon de données trop petite. 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, il définit la longueur sur 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 est placée dans la mémoire tampon longueur/indicateur au lieu de la longueur réelle. Cela est dû au fait que cet attribut est conçu pour tronquer les données sur le serveur avant la conversion, afin que le pilote n’ait aucun moyen de déterminer la longueur réelle.

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

   Pour plus d’informations sur la façon de déterminer l’adresse de la mémoire tampon de longueur/indicateur, consultez « Adresses de mémoire tampon » dans SQLBindCol.

7. Si les données sont tronquées pendant la conversion sans perte de chiffres significatifs (par exemple, le nombre réel 1,234 est tronqué en entier 1 lors de la conversion), SQLFetch retourne SQLSTATE 01S07 (troncation fractionnelle) et SQL_SUCCESS_WITH_INFO. Si les données sont tronquées, car la longueur de la mémoire tampon de données est trop petite (par exemple, la chaîne « abcdef » est placée dans une mémoire tampon de 4 octets), SQLFetch retourne SQLSTATE 01004 (données tronquées) et SQL_SUCCESS_WITH_INFO. Si les données sont tronquées en raison de l’attribut d’instruction SQL_ATTR_MAX_LENGTH, SQLFetch retourne SQL_SUCCESS et ne retourne pas SQLSTATE 01S07 (troncation fractionnaire) ou SQLSTATE 01004 (tronqué de données). Si les données sont tronquées pendant la conversion avec une perte de chiffres significatifs (par exemple, si une valeur SQL_INTEGER supérieure à 100 000 ont été converties en SQL_C_TINYINT), SQLFetch retourne SQLSTATE 22003 (valeur numérique hors plage) et SQL_ERROR (si la taille de l’ensemble de lignes est 1) ou SQL_SUCCESS_WITH_INFO (si la taille de l’ensemble de lignes est supérieure à 1).

Le contenu de la mémoire tampon de données liée et la mémoire tampon longueur/indicateur ne sont pas définis si SQLFetch ou SQLFetchScroll ne retourne pas SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.

Tableau d’état des lignes

Le tableau d’état de ligne est utilisé pour retourner l’état de chaque ligne dans l’ensemble de lignes. L’adresse de ce tableau est spécifiée avec l’attribut d’instruction SQL_ATTR_ROW_STATUS_PTR. Le tableau est alloué par l’application et doit avoir autant d’éléments que spécifiés par l’attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE. Ses valeurs sont définies par SQLFetch, SQLFetchScroll et SQLBulkOperations ou SQLSetPos (sauf lorsqu’elles ont été appelées après que le curseur a été positionné par SQLExtendedFetch). Si la valeur de l’attribut d’instruction SQL_ATTR_ROW_STATUS_PTR est un pointeur Null, ces fonctions ne retournent pas l’état de ligne.

Le contenu de la mémoire tampon du tableau d’état de ligne n’est pas défini si SQLFetch ou SQLFetchScroll ne retourne pas SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.

Les valeurs suivantes sont retournées dans le tableau d’état de ligne.

[1] Pour les jeux de clés, les curseurs mixtes et dynamiques, si une valeur de clé est mise à jour, la ligne de données est considérée comme ayant été supprimée et une nouvelle ligne ajoutée.

[2] Certains pilotes ne peuvent pas détecter les mises à jour des données et ne peuvent donc pas retourner cette valeur. Pour déterminer si un pilote peut détecter les mises à jour des lignes refétées, une application appelle SQLGetInfo avec l’option SQL_ROW_UPDATES.

[3] SQLFetch peut retourner cette valeur uniquement lorsqu’elle est mélangée avec des appels à SQLFetchScroll. Cela est dû au fait que SQLFetch avance vers l’avant dans le jeu de résultats et lorsqu’il est utilisé exclusivement, ne refetche aucune ligne. Étant donné qu’aucune ligne n’est reféchée, SQLFetch ne détecte pas les modifications apportées aux lignes extraites précédemment. Toutefois, si SQLFetchScroll positionne le curseur avant les lignes extraites précédemment et QUE SQLFetch est utilisé pour extraire ces lignes, SQLFetch peut détecter les modifications apportées à ces lignes.

[4] Retourné par SQLBulkOperations uniquement. Non défini par SQLFetch ou SQLFetchScroll.

Mémoire tampon extraite des lignes

La mémoire tampon extraite des lignes est utilisée pour renvoyer le nombre de lignes extraites, y compris les lignes pour lesquelles aucune donnée n’a été retournée, car une erreur s’est produite lors de leur extraction. En d’autres termes, il s’agit du nombre de lignes pour lesquelles la valeur du tableau d’état de ligne n’est pas SQL_ROW_NOROW. L’adresse de cette mémoire tampon est spécifiée avec l’attribut d’instruction SQL_ATTR_ROWS_FETCHED_PTR. La mémoire tampon est allouée par l’application. Il est défini par SQLFetch et SQLFetchScroll. Si la valeur de l’attribut d’instruction SQL_ATTR_ROWS_FETCHED_PTR est un pointeur Null, ces fonctions ne retournent pas le nombre de lignes extraites. Pour déterminer le nombre de lignes actuelles dans le jeu de résultats, une application peut appeler SQLGetStmtAttr avec l’attribut SQL_ATTR_ROW_NUMBER.

Le contenu de la mémoire tampon extraite des lignes n’est pas défini si SQLFetch ou SQLFetchScroll ne retourne pas SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, sauf si SQL_NO_DATA est retourné, auquel cas la valeur de la mémoire tampon extraite est définie sur 0.

Gestion des erreurs

Les erreurs et avertissements peuvent s’appliquer à des lignes individuelles ou à l’ensemble de la fonction. Pour plus d’informations sur les enregistrements de diagnostic, consultez Diagnostics et SQLGetDiagField.

Erreurs et avertissements sur l’ensemble de la fonction

Si une erreur s’applique à l’ensemble de la fonction, telle que SQLSTATE HYT00 (Expiration du délai d’expiration) ou SQLSTATE 24000 (état du curseur non valide), SQLFetch retourne SQL_ERROR et SQLSTATE applicable. Le contenu des mémoires tampons d’ensemble de lignes n’est pas défini et la position du curseur n’est pas modifiée.

Si un avertissement s’applique à l’ensemble de la fonction, SQLFetch retourne SQL_SUCCESS_WITH_INFO et sqlSTATE applicable. Les enregistrements d’état des avertissements qui s’appliquent à la fonction entière sont retournés avant les enregistrements d’état qui s’appliquent à des lignes individuelles.

Erreurs et avertissements dans des lignes individuelles

Si une erreur (par exemple, SQLSTATE 22012 (division par zéro)) ou un avertissement (par exemple, SQLSTATE 01004 (données tronquées)) s’applique à une seule ligne, SQLFetcheffectue les opérations suivantes :

• Définit l’élément correspondant du tableau d’état de ligne sur SQL_ROW_ERROR pour les erreurs ou les SQL_ROW_SUCCESS_WITH_INFO pour les avertissements.

• Ajoute zéro ou plusieurs enregistrements d’état qui contiennent des SQLSTATEs pour l’erreur ou l’avertissement.

• Définit les champs de numéro de ligne et de colonne dans les enregistrements d’état. Si SQLFetch ne peut pas déterminer un numéro de ligne ou de colonne, il définit ce nombre sur SQL_ROW_NUMBER_UNKNOWN ou SQL_COLUMN_NUMBER_UNKNOWN, respectivement. Si l’enregistrement d’état ne s’applique pas à une colonne particulière, SQLFetch définit le numéro de colonne sur SQL_NO_COLUMN_NUMBER.

SQLFetch continue à extraire des lignes jusqu’à ce qu’elle ait extrait toutes les lignes de l’ensemble de lignes. Elle retourne SQL_SUCCESS_WITH_INFO sauf si une erreur se produit dans chaque ligne de l’ensemble de lignes (sans inclure les lignes avec l’état SQL_ROW_NOROW), auquel cas elle retourne SQL_ERROR. En particulier, si la taille de l’ensemble de lignes est 1 et qu’une erreur se produit dans cette ligne, SQLFetch retourne SQL_ERROR.

SQLFetch retourne les enregistrements d’état dans l’ordre des numéros de ligne. Autrement dit, elle retourne tous les enregistrements d’état pour les lignes inconnues (le cas échéant) ; ensuite, il retourne tous les enregistrements d’état pour la première ligne (le cas échéant), puis retourne tous les enregistrements d’état pour la deuxième ligne (le cas échéant), et ainsi de suite. Les enregistrements d’état pour chaque ligne sont classés en fonction des règles normales de classement des enregistrements d’état ; Pour plus d’informations, consultez « Séquence d’enregistrements d’état » dans SQLGetDiagField.

Descripteurs et SQLFetch

Les sections suivantes décrivent comment SQLFetch interagit avec les descripteurs.

Mappages d’arguments

Le pilote ne définit aucun champ descripteur basé sur les arguments de SQLFetch.

Autres champs de descripteur

Les champs de descripteur suivants sont utilisés par SQLFetch.

Tous les champs de descripteur peuvent également être définis via SQLSetDescField.

Longueur et mémoires tampons d’indicateur distinctes

Les applications peuvent lier une seule mémoire tampon ou deux mémoires tampons distinctes qui peuvent être utilisées pour contenir des valeurs de longueur et d’indicateur. Lorsqu’une application appelle SQLBindCol, le pilote définit les champs SQL_DESC_OCTET_LENGTH_PTR et SQL_DESC_INDICATOR_PTR de l’ARD sur la même adresse, qui est passée dans l’argument StrLen_or_IndPtr . Lorsqu’une application appelle SQLSetDescField ou SQLSetDescRec, elle peut définir ces deux champs sur des adresses différentes.

SQLFetch détermine si l’application a spécifié des mémoires tampons de longueur et d’indicateur distinctes. Dans ce cas, lorsque les données ne sont pas NULL, SQLFetch définit la mémoire tampon d’indicateur sur 0 et retourne la longueur dans la mémoire tampon de longueur. Lorsque les données sont NULL, SQLFetch définit la mémoire tampon d’indicateur sur SQL_NULL_DATA et ne modifie pas la mémoire tampon de longueur.

Exemple de code

Consultez SQLBindCol, SQLColumns, SQLGetData et SQLProcedures.

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC