SQLFetch, fonction
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92
Résumé
SQLFetch extrait l’ensemble de lignes suivant de données à partir du jeu de résultats et retourne les données de 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 handled’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 de 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 des SQL_SUCCESS_WITH_INFO ou des SQL_ERROR (à l’exception de 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO est retourné si une erreur se produit sur une ou plusieurs lignes, mais pas toutes, d’une opération multirow, et SQL_ERROR est retourné si une erreur se produit sur une opération à une seule ligne.
| SQLSTATE | Error | 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 binaires retournées pour une colonne ont entraîné la troncation de caractères non vides 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 de plusieurs lignes. (Si cette valeur SQLSTATE est retournée lorsqu’une application ODBC 3*.x* fonctionne avec un pilote ODBC 2*.x*, elle peut être ignorée.) |
| 01S07 | Troncation fractionnaire | 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 restreinte | La valeur de données d’une colonne du 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 a été 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 de la liaison de communication | La liaison de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant que la fonction n’ait terminé le traitement. |
| 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 le StrLen_or_IndPtr défini par SQLBindCol (ou SQL_DESC_INDICATOR_PTR défini par SQLSetDescField ou SQLSetDescRec) était un pointeur null. |
| 22003 | Valeur numérique hors plage | Le renvoi de la valeur numérique sous forme numérique ou chaîne pour une ou plusieurs colonnes liées aurait entraîné la tronquation de la partie entière (et non fractionnaire) 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 de date, d’heure ou d’horodatage C, et une valeur de 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é une 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 entraîné une perte de chiffres significatifs dans le champ de début. Lors de l’extraction de données vers un type d’intervalle C, il n’y avait aucune représentation de la valeur du type SQL dans le type d’intervalle C. |
| 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 de données 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’InstructionHandle était dans un état exécuté, mais aucun jeu de résultats n’a été associé à l’InstructionHandle. |
| 40001 | Échec de sérialisation | La transaction dans laquelle la récupération a été exécutée a été arrêtée pour éviter l’interblocage. |
| 40003 | Saisie semi-automatique d’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 pas de SQLSTATE spécifique et pour laquelle 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 la 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 l’instruction StatementHandle. La fonction SQLFetch a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle. Ensuite, la fonction SQLFetch a été appelée à nouveau sur l’InstructionHandle. Ou bien, la fonction SQLFetch a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un thread différent dans une application multithread. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction en exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. 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’InstructionHandle et a 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’InstructionHandle spécifiée n’était pas dans un état exécuté. La fonction a été appelée sans avoir d’abord appelé 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’InstructionHandle 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 a retourné SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de l’exécution. (DM) SQLFetch a été appelé pour l’instructionHandle après l’appel de SQLExtendedFetch et avant l’appel de SQLFreeStmt avec l’option SQL_CLOSE. |
| 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, peut-être en raison de conditions de mémoire insuffisantes. |
| HY090 | Chaîne ou longueur de 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 a été 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 a été SQL_CURSOR_KEYSET_DRIVEN, mais la valeur spécifiée avec l’attribut d’instruction SQL_ATTR_KEYSET_SIZE est 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 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 du TargetType dans SQLBindCol et du type de données SQL de la colonne correspondante. |
| HYT00 | Délai expiré | Le délai d’expiration de la requête a expiré avant que la source de données renvoie le jeu de résultats demandé. Le délai d’expiration est défini via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Délai d’attente de la connexion expiré | Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à l’InstructionHandle 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 effectuer 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 le 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 , c’est-à-dire après un appel qui crée un jeu de résultats et avant la fermeture du curseur sur ce jeu de résultats. 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 renvoie également ces informations. Les appels à SQLFetch peuvent être mélangés avec des appels à SQLFetchScroll , mais pas 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 Curseurs de bloc, Curseurs avec défilement et Compatibilité descendante dans l’Annexe G : Instructions de pilote pour 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. Cela revient à 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 extrait 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 extrait, R est la taille de l’ensemble de lignes et L est la dernière ligne du jeu de résultats, seules les premières lignes L - S + 1 de l’ensemble de lignes sont valides. Les lignes restantes sont vides et ont l’état 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 le début | 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 qui a été utilisée avec l’extraction 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 qui a été utilisée avec la nouvelle extraction.
| Notation | Signification |
|---|---|
| Avant le début | 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 se trouve 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 de 5. Le tableau suivant montre l’ensemble de lignes et le code de retour retournés 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 le début | 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 | Aucun. | 0 |
| 99 à 100 | SQL_NO_DATA | Aucun. | 0 |
| Après la fin | SQL_NO_DATA | Aucun. | 0 |
Retour de données dans des colonnes liées
Comme SQLFetch retourne chaque ligne, il 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 multiligne (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/d’indicateur sur SQL_NULL_DATA et passe à la colonne suivante si les données ont la valeur NULL. Si les données ont la valeur NULL et qu’aucune mémoire tampon de longueur/d’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 a 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 à SQL_ATTR_MAX_LENGTH octets.
Notes
L’attribut d’instruction SQL_ATTR_MAX_LENGTH est destiné à réduire le trafic réseau. Il est généralement implémenté 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 un type de données de longueur variable, tel que caractère ou 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 de caractères (y compris le caractère d’arrêt 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. Il termine ensuite les données avec 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 correspond à 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 de longueur/d’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 le fait un appel à SQLBindCol ), 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/d’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, car la mémoire tampon de données est 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 les 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 de longueur/d’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, de sorte que le pilote n’a 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 fractionnaire) 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 renvoie pas SQLSTATE 01S07 (troncation fractionnaire) ou SQLSTATE 01004 (données tronquées). Si les données sont tronquées pendant la conversion avec une perte de chiffres significatifs (par exemple, si une valeur de SQL_INTEGER supérieure à 100 000 a été convertie en SQL_C_TINYINT), SQLFetch renvoie 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 de longueur/d’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 de 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é par l’attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE. Ses valeurs sont définies par SQLFetch, SQLFetchScroll et SQLBulkOperations ou SQLSetPos (sauf quand 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 la 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 des lignes.
| Valeur du tableau d’état de ligne | 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 si elle 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 extraite à nouveau de ce jeu de résultats ou si elle est actualisée par SQLSetPos, son état est SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | L’ensemble de lignes chevauche la fin du jeu de résultats et aucune ligne correspondant à cet élément du tableau d’état de ligne n’a été retournée. |
[1] Pour les curseurs de jeu de clés, 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étisées, une application appelle SQLGetInfo avec l’option SQL_ROW_UPDATES.
[3] SQLFetch ne peut retourner cette valeur que lorsqu’elle est mélangée avec des appels à SQLFetchScroll. Cela est dû au fait que SQLFetch avance dans le jeu de résultats et, lorsqu’il est utilisé exclusivement, ne refetch aucune ligne. Étant donné qu’aucune ligne n’est refétée, SQLFetch ne détecte pas les modifications apportées aux lignes précédemment extraites. Toutefois, si SQLFetchScroll place le curseur avant les lignes précédemment extraites 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 retourner 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 pendant 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. Elle est définie 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 numéro de la ligne actuelle 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 quand SQL_NO_DATA est retourné, auquel cas la valeur dans la mémoire tampon extraite des lignes est définie sur 0.
Gestion des erreurs
Les erreurs et les 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 (délai d’expiration expiré) ou SQLSTATE 24000 (état de curseur non valide), SQLFetch retourne SQL_ERROR et le SQLSTATE applicable. Le contenu des mémoires tampons d’ensemble de lignes n’est pas défini et la position du curseur est inchangée.
Si un avertissement s’applique à l’ensemble de la fonction, SQLFetch retourne SQL_SUCCESS_WITH_INFO et l’état SQLSTATE applicable. Les enregistrements d’état des avertissements qui s’appliquent à l’ensemble de la fonction sont retournés avant les enregistrements d’état qui s’appliquent aux lignes individuelles.
Erreurs et avertissements dans les lignes individuelles
Si une erreur (telle que SQLSTATE 22012 (Division par zéro)) ou un avertissement (tel que 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 SQL_ROW_SUCCESS_WITH_INFO pour les avertissements.
Ajoute zéro ou plusieurs enregistrements d’état qui contiennent 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 d’extraire les lignes jusqu’à ce qu’il 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 les lignes dont l’état est 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 du numéro de ligne. Autrement dit, il 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 il 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 selon les 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 de 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 via |
|---|---|---|---|
| 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.
Séparer les mémoires tampons de longueur et d’indicateur
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 de l’indicateur sur 0 et retourne la longueur dans la mémoire tampon de longueur. Lorsque les données ont la valeur NULL, SQLFetch définit la mémoire tampon de l’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 obtenir des informations sur | Consultez |
|---|---|
| Liaison d’une mémoire tampon à une colonne dans un jeu de résultats | Fonction SQLBindCol |
| Annulation du traitement des instructions | SQLCancel, fonction |
| Retour d’informations sur une colonne dans un jeu de résultats | Fonction SQLDescribeCol |
| 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 | Fonction SQLFetchScroll |
| Fermeture du curseur sur l’instruction | Fonction SQLFreeStmt |
| Extraction d’une partie ou de la totalité d’une colonne de données | Fonction SQLGetData |
| Retour du nombre de colonnes de jeu de résultats | Fonction SQLNumResultCols |
| Préparation d’une instruction pour l’exécution | Fonction SQLPrepare |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour