Partage via


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 :

  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.

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.

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