SQLFetchScroll, fonction

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

Résumé
SQLFetchScroll récupère l’ensemble de lignes spécifié de données à partir du jeu de résultats et retourne des données pour toutes les colonnes liées. Les ensembles de lignes peuvent être spécifiés à une position absolue ou relative ou par signet.

Lorsque vous utilisez un pilote ODBC 2.x, le Gestionnaire de pilotes mappe cette fonction à SQLExtendedFetch. Pour plus d’informations, consultez Fonctions de remplacement de mappage pour la compatibilité descendante des applications.

Syntaxe

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

FetchOrientation
[Entrée]

Type de récupération :

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

Pour plus d’informations, consultez « Positionnement du curseur » dans la section « Commentaires ».

FetchOffset
[Entrée]

Nombre de lignes à extraire. L’interprétation de cet argument dépend de la valeur de l’argument FetchOrientation . Pour plus d’informations, consultez « Positionnement du curseur » dans la section « Commentaires ».

Retours

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

Diagnostics

Lorsque SQLFetchScroll retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLFetchScroll 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 contenant cette colonne.

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

Commentaires

SQLFetchScroll retourne un ensemble de lignes spécifié à partir du jeu de résultats. Les ensembles de lignes peuvent être spécifiés par position absolue ou relative ou par signet. SQLFetchScroll 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 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, SQLFetchScroll retourne également ces informations. Les appels à SQLFetchScroll peuvent être mélangés avec des appels à SQLFetch , mais ne peuvent pas être mélangés avec des appels à SQLExtendedFetch.

Pour plus d’informations, consultez Utilisation des curseurs de bloc et utilisation de curseurs à défilement.

Positionnement du curseur

Lorsque le jeu de résultats est créé, le curseur est positionné avant le début du jeu de résultats. SQLFetchScroll positionne le curseur de bloc en fonction des valeurs des arguments FetchOrientation et FetchOffset , comme indiqué dans le tableau suivant. Les règles exactes pour déterminer le début du nouvel ensemble de lignes sont affichées dans la section suivante.

Les pilotes ne sont pas nécessaires pour prendre en charge toutes les orientations de récupération ; une application appelle SQLGetInfo avec un type d’informations de SQL_DYNAMIC_CURSOR_ATTRIBUTES1, de SQL_KEYSET_CURSOR_ATTRIBUTES1 ou de SQL_STATIC_CURSOR_ATTRIBUTES1 (selon le type du curseur) pour déterminer les orientations d’extraction prises en charge par le pilote. L’application doit examiner les masques de bits SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE et WQL_CA1_BOOKMARK dans ces types d’informations. En outre, si le curseur est en avant uniquement et fetchOrientation n’est pas SQL_FETCH_NEXT, SQLFetchScroll retourne SQLSTATE HY106 (type d’extraction hors plage).

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 SQLFetchScroll chevauche la fin du jeu de résultats, SQLFetchScroll 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 SQLFetchScroll retourne, la ligne actuelle est la première ligne de l’ensemble de lignes.

Règles de positionnement des curseurs

Les sections suivantes décrivent les règles exactes pour chaque valeur de FetchOrientation. Ces règles utilisent la notation suivante.

SQL_FETCH_NEXT

Les règles suivantes s’appliquent.

[1] Si la taille de l’ensemble de lignes a été modifiée depuis l’appel précédent pour extraire des lignes, il s’agit de la taille d’ensemble de lignes utilisée avec l’appel précédent.

SQL_FETCH_PRIOR

Les règles suivantes s’appliquent.

[1] SQLFetchScroll retourne SQLSTATE 01S06 (tentative d’extraction avant que le jeu de résultats ne renvoie le premier ensemble de lignes) et SQL_SUCCESS_WITH_INFO.

[2] Si la taille de l’ensemble de lignes a été modifiée depuis l’appel précédent pour extraire des lignes, il s’agit de la nouvelle taille d’ensemble de lignes.

SQL_FETCH_RELATIVE

Les règles suivantes s’appliquent.

[1] SQLFetchScroll retourne le même ensemble de lignes que s’il a été appelé avec FetchOrientation défini sur SQL_FETCH_ABSOLUTE. Pour plus d’informations, consultez la section « SQL_FETCH_ABSOLUTE ».

[2] SQLFetchScroll retourne SQLSTATE 01S06 (tentative d’extraction avant que le jeu de résultats ne renvoie le premier ensemble de lignes) et SQL_SUCCESS_WITH_INFO.

[3] Si la taille de l’ensemble de lignes a été modifiée depuis l’appel précédent pour extraire des lignes, il s’agit de la nouvelle taille d’ensemble de lignes.

SQL_FETCH_ABSOLUTE

Les règles suivantes s’appliquent.

[1] SQLFetchScroll retourne SQLSTATE 01S06 (tentative d’extraction avant que le jeu de résultats ne renvoie le premier ensemble de lignes) et SQL_SUCCESS_WITH_INFO.

[2] Si la taille de l’ensemble de lignes a été modifiée depuis l’appel précédent pour extraire des lignes, il s’agit de la nouvelle taille d’ensemble de lignes.

Une extraction absolue effectuée sur un curseur dynamique ne peut pas fournir le résultat requis, car les positions de ligne dans un curseur dynamique ne sont pas déterminée. Une telle opération équivaut d’abord à une extraction suivie d’un relatif d’extraction ; il ne s’agit pas d’une opération atomique, car il s’agit d’une extraction absolue sur un curseur statique.

SQL_FETCH_FIRST

Les règles suivantes s’appliquent.

SQL_FETCH_LAST

Les règles suivantes s’appliquent.

[1] Si la taille de l’ensemble de lignes a été modifiée depuis l’appel précédent pour extraire des lignes, il s’agit de la nouvelle taille d’ensemble de lignes.

SQL_FETCH_BOOKMARK

Les règles suivantes s’appliquent.

Pour plus d’informations sur les signets, consultez Signets (ODBC).

Effet des lignes supprimées, ajoutées et d’erreur sur le déplacement du curseur

Les curseurs statiques et pilotés par les jeux de clés détectent parfois les lignes ajoutées au jeu de résultats et suppriment les lignes supprimées du jeu de résultats. En appelant SQLGetInfo avec les options SQL_STATIC_CURSOR_ATTRIBUTES2 et SQL_KEYSET_CURSOR_ATTRIBUTES2 et en examinant les SQL_CA2_SENSITIVITY_ADDITIONS, les SQL_CA2_SENSITIVITY_DELETIONS et les masques de bits SQL_CA2_SENSITIVITY_UPDATES, une application détermine si les curseurs implémentés par un pilote particulier le font. Pour les pilotes qui peuvent détecter les lignes supprimées et les supprimer, les paragraphes suivants décrivent les effets de ce comportement. Pour les pilotes qui peuvent détecter les lignes supprimées, mais qui ne peuvent pas les supprimer, les suppressions n’ont aucun effet sur les mouvements de curseur et les paragraphes suivants ne s’appliquent pas.

Si le curseur détecte les lignes ajoutées au jeu de résultats ou supprime les lignes supprimées du jeu de résultats, il apparaît comme s’il détecte ces modifications uniquement lorsqu’il extrait des données. Cela inclut le cas où SQLFetchScroll est appelé avec FetchOrientation défini sur SQL_FETCH_RELATIVE et FetchOffset défini sur 0 pour refetch le même ensemble de lignes, mais n’inclut pas le cas où SQLSetPos est appelé avec fOption défini sur SQL_REFRESH. Dans ce dernier cas, les données des mémoires tampons de l’ensemble de lignes sont actualisées, mais pas refétées, et les lignes supprimées ne sont pas supprimées du jeu de résultats. Par conséquent, lorsqu’une ligne est supprimée ou insérée dans l’ensemble de lignes actuel, le curseur ne modifie pas les mémoires tampons de l’ensemble de lignes. Au lieu de cela, il détecte la modification lorsqu’elle extrait tout ensemble de lignes qui incluait précédemment la ligne supprimée ou inclut désormais la ligne insérée.

Par exemple :

// Fetch the next rowset.  
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);  
// Delete third row of the rowset. Does not modify the rowset buffers.  
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);  
// The third row has a status of SQL_ROW_DELETED after this call.  
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);  
// Refetch the same rowset. The third row is removed, replaced by what  
// was previously the fourth row.  
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);  

Lorsque SQLFetchScroll retourne un nouvel ensemble de lignes qui a une position par rapport à l’ensemble de lignes actuel ( autrement dit, FetchOrientation est SQL_FETCH_NEXT, SQL_FETCH_PRIOR ou SQL_FETCH_RELATIVE ), il n’inclut pas les modifications apportées à l’ensemble de lignes actuel lors du calcul de la position de départ du nouvel ensemble de lignes. Toutefois, il inclut des modifications en dehors de l’ensemble de lignes actuel s’il est capable de les détecter. En outre, lorsque SQLFetchScroll retourne un nouvel ensemble de lignes qui a une position indépendante de l’ensemble de lignes actuel , autrement dit, FetchOrientation est SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE ou SQL_FETCH_BOOKMARK - il inclut toutes les modifications qu’il est capable de détecter, même s’ils se trouvent dans l’ensemble de lignes actuel.

Lorsque vous déterminez si les lignes nouvellement ajoutées se trouvent à l’intérieur ou à l’extérieur de l’ensemble de lignes actuel, un ensemble de lignes partiel est considéré comme se mettant fin à la dernière ligne valide ; c’est-à-dire la dernière ligne pour laquelle l’état de la ligne n’est pas SQL_ROW_NOROW. Par exemple, supposons que le curseur soit capable de détecter les lignes nouvellement ajoutées, que l’ensemble de lignes actuel est un ensemble de lignes partiel, que l’application ajoute de nouvelles lignes et que le curseur ajoute ces lignes à la fin du jeu de résultats. Si l’application appelle SQLFetchScroll avec FetchOrientation définie sur SQL_FETCH_NEXT, SQLFetchScroll retourne l’ensemble de lignes commençant par la première ligne nouvellement ajoutée.

Par exemple, supposons que l’ensemble de lignes actuel comprend les lignes 21 à 30, la taille de l’ensemble de lignes est 10, le curseur supprime les lignes supprimées du jeu de résultats et le curseur détecte les lignes ajoutées au jeu de résultats. Le tableau suivant montre les lignes retournées par SQLFetchScroll dans différentes situations.

[1] Cette colonne utilise les numéros de ligne avant que toutes les lignes aient été insérées ou supprimées.

[2] Dans ce cas, le curseur tente de retourner des lignes à partir de la ligne 21. Étant donné que la ligne 21 a été supprimée, la première ligne retournée est la ligne 22.

Les lignes d’erreur (autrement dit, les lignes dont l’état est SQL_ROW_ERROR) n’affectent pas le déplacement du curseur. Par exemple, si l’ensemble de lignes actuel commence par la ligne 11 et que l’état de la ligne 11 est SQL_ROW_ERROR, l’appel de SQLFetchScroll avec FetchOrientation défini sur SQL_FETCH_RELATIVE et FetchOffset défini sur 5 retourne l’ensemble de lignes commençant par la ligne 16, comme si l’état de la ligne 11 était SQL_SUCCESS.

Retour de données dans des colonnes liées

SQLFetchScroll retourne des données dans des colonnes liées de la même façon que SQLFetch. Pour plus d’informations, consultez « Retour de données dans des colonnes liées » dans la fonction SQLFetch.

Si aucune colonne n’est liée, SQLFetchScroll ne retourne pas de données, mais déplace le curseur de bloc vers la position spécifiée. Si les données peuvent être récupérées à partir de colonnes indépendantes d’un curseur de bloc avec SQLGetData dépend du pilote. Cette fonctionnalité est prise en charge si un appel à SQLGetInfo retourne le bit SQL_GD_BLOCK pour le type d’informations SQL_GETDATA_EXTENSIONS.

Adresses de mémoire tampon

SQLFetchScroll utilise la même formule pour déterminer l’adresse des données et des mémoires tampons de longueur/indicateur que SQLFetch. Pour plus d’informations, consultez « Adresses de mémoire tampon » dans la fonction SQLBindCol.

Tableau d’état des lignes

SQLFetchScroll définit des valeurs dans le tableau d’état de ligne de la même manière que SQLFetch. Pour plus d’informations, consultez « Tableau d’état des lignes » dans la fonction SQLFetch.

Mémoire tampon extraite des lignes

SQLFetchScroll retourne le nombre de lignes extraites dans la mémoire tampon extraite de la même manière que SQLFetch. Pour plus d’informations, consultez « Mémoire tampon extraite des lignes » dans la fonction SQLFetch.

Gestion des erreurs

Lorsqu’une application appelle SQLFetchScroll dans un pilote ODBC 3.x, le Gestionnaire de pilotes appelle SQLFetchScroll dans le pilote. Lorsqu’une application appelle SQLFetchScroll dans un pilote ODBC 2.x, le Gestionnaire de pilotes appelle SQLExtendedFetch dans le pilote. Étant donné que SQLFetchScroll et SQLExtendedFetch gèrent les erreurs de manière légèrement différente, l’application voit un comportement d’erreur légèrement différent lorsqu’elle appelle SQLFetchScroll dans les pilotes ODBC 2.x et ODBC 3.x.

SQLFetchScroll retourne des erreurs et des avertissements de la même manière que SQLFetch. Pour plus d’informations, consultez « Gestion des erreurs » dans SQLFetch. SQLExtendedFetch retourne des erreurs de la même manière que SQLFetch, avec les exceptions suivantes :

Lorsqu’un avertissement se produit qui s’applique à une ligne particulière dans l’ensemble de lignes, SQLExtendedFetch définit l’entrée correspondante dans le tableau d’état de ligne sur SQL_ROW_SUCCESS, et non SQL_ROW_SUCCESS_WITH_INFO.

Si des erreurs se produisent dans chaque ligne de l’ensemble de lignes, SQLExtendedFetch retourne SQL_SUCCESS_WITH_INFO, et non SQL_ERROR.

Dans chaque groupe d’enregistrements d’état qui s’applique à une ligne individuelle, le premier enregistrement d’état retourné par SQLExtendedFetch doit contenir SQLSTATE 01S01 (Erreur dans la ligne) ; SQLFetchScroll ne retourne pas ce SQLSTATE. Si SQLExtendedFetch ne peut pas retourner d’autres SQLSTATEs, il doit toujours renvoyer ce SQLSTATE.

Accès concurrentiel SQLFetchScroll et optimiste

Si un curseur utilise l’accès concurrentiel optimiste , autrement dit, l’attribut d’instruction SQL_ATTR_CONCURRENCY a une valeur de SQL_CONCUR_VALUES ou de SQL_CONCUR_ROWVER - SQLFetchScroll met à jour les valeurs d’accès concurrentiel optimiste utilisées par la source de données pour détecter si une ligne a changé. Cela se produit chaque fois que SQLFetchScroll récupère un nouvel ensemble de lignes, y compris lorsqu’il refétise l’ensemble de lignes actuel. (Il est appelé avec FetchOrientation défini sur SQL_FETCH_RELATIVE et FetchOffset défini sur 0.)

Pilotes SQLFetchScroll et ODBC 2.x

Lorsqu’une application appelle SQLFetchScroll dans un pilote ODBC 2.x, le Gestionnaire de pilotes mappe cet appel à SQLExtendedFetch. Il transmet les valeurs suivantes pour les arguments de SQLExtendedFetch.

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.

Descriptors et SQLFetchScroll

SQLFetchScroll interagit avec des descripteurs de la même manière que SQLFetch. Pour plus d’informations, consultez la section « Descriptors et SQLFetchScroll » dans la fonction SQLFetch.

Exemple de code

Consultez la liaison à l’aide des colonnes, de la liaison ligne, des instructions de mise à jour et de suppression positionnées et de mise à jour des lignes dans l’ensemble de lignes avec SQLSetPos.

Fonctions connexes

Voir aussi

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