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.
| 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 | Les données de chaîne ou binaire retournées pour une colonne ont entraîné la troncation d’un caractère non vide ou de données binaires non NULL. S’il s’agissait d’une valeur de chaîne, elle était tronquée à droite. |
| 01S01 | Erreur dans la ligne | Une erreur s’est produite lors de l’extraction d’une ou plusieurs lignes. (Si ce SQLSTATE est retourné lorsqu’une application ODBC 3*.x* fonctionne avec un pilote ODBC 2*.x*, elle peut être ignorée.) |
| 01S07 | Troncation fractionnelle | Les données retournées pour une colonne 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 qui contiennent 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 n’a pas pu être convertie en type de données spécifié par TargetType dans SQLBindCol. La colonne 0 a été liée à un type de données de SQL_C_BOOKMARK, et l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_VARIABLE. La colonne 0 était liée à un type de données de SQL_C_VARBOOKMARK, et l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS n’a pas été défini sur SQL_UB_VARIABLE. |
| 07009 | Index de descripteur non valide | Le pilote était un pilote ODBC 2*.x* qui ne prend pas en charge SQLExtendedFetch et un numéro de colonne spécifié dans la liaison pour une colonne était 0. La colonne 0 était liée et l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_OFF. |
| 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. |
| 22001 | Données de chaîne, tronquées à droite | Un signet de longueur variable retourné pour une colonne a été tronqué. |
| 22002 | Variable d’indicateur requise, mais non fournie | Les données NULL ont été extraites dans une colonne dont les StrLen_or_IndPtr définies par SQLBindCol (ou SQL_DESC_INDICATOR_PTR définies par SQLSetDescField ou SQLSetDescRec) étaient un pointeur Null. |
| 22003 | Valeur numérique hors plage | Le renvoi de la valeur numérique sous forme de numérique ou de chaîne pour une ou plusieurs colonnes liées aurait provoqué la troncation de l’ensemble (par opposition à la fraction) du nombre. Pour plus d’informations, consultez Conversion de données de SQL en types de données C dans l’annexe D : Types de données. |
| 22007 | Format datetime non valide | Une colonne de caractères dans le jeu de résultats était liée à une structure C de date, d’heure ou d’horodatage, et une valeur dans la colonne était, respectivement, une date, une heure ou un horodatage non valide. |
| 22012 | Division par zéro | Une valeur d’une expression arithmétique a été retournée, ce qui a entraîné la division par zéro. |
| 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. Lors de l’extraction de données dans un type C d’intervalle, il n’y avait aucune représentation de la valeur du type SQL dans l’intervalle C type. |
| 22018 | Valeur de caractère non valide pour la spécification de cast | Une colonne de caractères dans le jeu de résultats était lié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 | L’instruction StatementHandle était dans un état exécuté, mais aucun jeu de résultats n’a été associé à l’instruction StatementHandle. |
| 40001 | Échec de sérialisation | La transaction dans laquelle la récupération a été exécutée a été arrêtée pour empêcher l’interblocage. |
| 40003 | Saisie semi-automatique de l’instruction inconnue | La connexion associée a échoué pendant l’exécution de cette fonction et l’état de la transaction ne peut pas être déterminé. |
| 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. |
| HY008 | Opération annulée | Le traitement asynchrone a été activé pour StatementHandle. La fonction SQLFetch a été appelée et avant l’exécution terminée, SQLCancel ou SQLCancelHandle a été appelée sur StatementHandle. Ensuite, la fonction SQLFetch a été appelée à nouveau sur l’InstructionHandle. Ou bien, la fonction SQLFetch a été appelée et avant l’exécution terminée, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle à partir d’un autre thread dans une application multithread. |
| HY010 | Erreur de séquence de fonction | (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 SQLFetch a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle et retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu. (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 (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) SQLFetch a été appelé pour l’instructionHandle après l’appel de SQLExtendedFetch et avant que SQLFreeStmt avec l’option SQL_CLOSE ait été appelée. |
| 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 | L’attribut d’instruction SQL_ATTR_USE_BOOKMARK a été défini sur SQL_UB_VARIABLE, et la colonne 0 était liée à une mémoire tampon dont la longueur n’était pas égale à la longueur maximale du signet pour ce jeu de résultats. (Cette longueur est disponible dans le champ SQL_DESC_OCTET_LENGTH de l’IRD et peut être obtenue en appelant SQLDescribeCol, SQLColAttribute ou SQLGetDescField.) |
| HY107 | Valeur de ligne hors plage | La valeur spécifiée avec l’attribut d’instruction SQL_ATTR_CURSOR_TYPE était SQL_CURSOR_KEYSET_DRIVEN, mais la valeur spécifiée avec l’attribut d’instruction SQL_ATTR_KEYSET_SIZE était supérieure à 0 et inférieure à la valeur spécifiée avec l’attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE. |
| 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 la conversion spécifiée par la combinaison de TargetType dans SQLBindCol et du type de données SQL de la colonne correspondante. |
| HYT00 | Délai expiré | La période d’expiration de la requête a expiré avant que la source de données n’a retourné le jeu de résultats demandé. La période d’expiration est définie via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 associé à 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
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.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| Avant de commencer | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Après la fin |
| Après la fin | Après la fin |
[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.
| Notation | Signification |
|---|---|
| Avant de commencer | Le curseur de bloc est positionné avant le début du jeu de résultats. Si la première ligne du nouvel ensemble de lignes est avant le début du jeu de résultats, SQLFetch retourne SQL_NO_DATA. |
| Après la fin | Le curseur de bloc est positionné après la fin du jeu de résultats. Si la première ligne du nouvel ensemble de lignes se trouve après la fin du jeu de résultats, SQLFetch retourne SQL_NO_DATA. |
| CurrRowsetStart | Numéro de la première ligne de l’ensemble de lignes actuel. |
| LastResultRow | Numéro de la dernière ligne du jeu de résultats. |
| RowsetSize | Taille de l’ensemble de lignes. |
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.
| Ensemble de lignes actuel | Code de retour | Nouvel ensemble de lignes | Nombre de lignes extraites |
|---|---|---|---|
| Avant de commencer | SQL_SUCCESS | 1 à 5 | 5 |
| 1 à 5 | SQL_SUCCESS | 6 à 10 | 5 |
| 52 à 56 | SQL_SUCCESS | 57 à 61 | 5 |
| 91 à 95 | SQL_SUCCESS | 96 à 100 | 5 |
| 93 à 97 | SQL_SUCCESS | 98 à 100. Les lignes 4 et 5 du tableau d’état des lignes sont définies sur SQL_ROW_NOROW. | 3 |
| 96 à 100 | SQL_NO_DATA | Aucune. | 0 |
| 99 à 100 | SQL_NO_DATA | Aucune. | 0 |
| Après la fin | SQL_NO_DATA | Aucune. | 0 |
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 :
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.
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.
Convertit les données en type spécifié par TargetType dans SQLBindCol.
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.
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.
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.
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.
| Valeur du tableau d’état des lignes | Description |
|---|---|
| SQL_ROW_SUCCESS | La ligne a été récupérée avec succès et n’a pas changé depuis sa dernière extraction à partir de ce jeu de résultats. |
| SQL_ROW_SUCCESS_WITH_INFO | La ligne a été récupérée avec succès et n’a pas changé depuis sa dernière extraction à partir de ce jeu de résultats. Toutefois, un avertissement a été retourné à propos de la ligne. |
| SQL_ROW_ERROR | Une erreur s’est produite lors de l’extraction de la ligne. |
| SQL_ROW_UPDATED[1],[2] et [3] | La ligne a été récupérée avec succès et a changé depuis sa dernière extraction à partir de ce jeu de résultats. Si la ligne est récupérée à nouveau à partir de ce jeu de résultats ou est actualisée par SQLSetPos, l’état est remplacé par le nouvel état de la ligne. |
| SQL_ROW_DELETED[3] | La ligne a été supprimée depuis sa dernière extraction à partir de ce jeu de résultats. |
| SQL_ROW_ADDED[4] | La ligne a été insérée par SQLBulkOperations. Si la ligne est récupérée à nouveau à partir de ce jeu de résultats ou est actualisée par SQLSetPos, son état est SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | L’ensemble de lignes se chevauche à la fin du jeu de résultats et aucune ligne n’a été retournée qui correspond à cet élément du 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.
| Champ de descripteur | Desc. | Champ dans | Définir par le biais |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | en-tête | attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | en-tête | attribut d’instruction SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | ARD | en-tête | attribut d’instruction SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | ARD | en-tête | attribut d’instruction SQL_ATTR_ROW_BIND_TYPE |
| SQL_DESC_COUNT | ARD | en-tête | Argument ColumnNumber de SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | enregistrements | Argument TargetValuePtr de SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | enregistrements | argument StrLen_or_IndPtr dans SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | enregistrements | Argument BufferLength dans SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | enregistrements | argument StrLen_or_IndPtr dans SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | en-tête | attribut d’instruction SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | ARD | enregistrements | Argument TargetType dans SQLBindCol |
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
| Pour plus d’informations sur | Consultez |
|---|---|
| Liaison d’une mémoire tampon à une colonne dans un jeu de résultats | SQLBindCol, fonction |
| Annulation du traitement des instructions | SQLCancel, fonction |
| Retour d’informations sur une colonne dans un jeu de résultats | SQLDescribeCol, fonction |
| Exécution d’une instruction SQL | SQLExecDirect, fonction |
| Exécution d’une instruction SQL préparée | SQLExecute, fonction |
| Extraction d’un bloc de données ou défilement d’un jeu de résultats | SQLFetchScroll, fonction |
| Fermeture du curseur sur l’instruction | SQLFreeStmt, fonction |
| Extraction d’une partie ou de l’ensemble d’une colonne de données | SQLGetData, fonction |
| Renvoi du nombre de colonnes du jeu de résultats | SQLNumResultCols, fonction |
| Préparation d’une instruction pour l’exécution | SQLPrepare, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC