SQLFetchScroll (bibliothèque de curseurs)
Important
Cette fonctionnalité sera supprimée dans une version future de Windows. Évitez d’utiliser cette fonctionnalité dans les nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité. Microsoft recommande d’utiliser la fonctionnalité de curseur du pilote.
Cette rubrique décrit l’utilisation de la fonction SQLFetchScroll dans la bibliothèque de curseurs. Pour plus d’informations générales sur SQLFetchScroll, consultez FONCTION SQLFetchScroll.
La bibliothèque de curseurs implémente SQLFetchScroll en appelant à plusieurs reprises SQLFetch dans le pilote. Il transfère les données qu’il récupère du pilote vers les mémoires tampons d’ensemble de lignes fournies par l’application. Il met également en cache les données dans les fichiers de mémoire et de disque. Lorsqu’une application demande un nouvel ensemble de lignes, la bibliothèque de curseurs le récupère si nécessaire à partir du pilote (s’il n’a pas été extrait précédemment) ou du cache (s’il a été extrait précédemment). Enfin, la bibliothèque de curseurs conserve l’état des données mises en cache et retourne ces informations à l’application dans le tableau d’état des lignes.
Lorsque la bibliothèque de curseurs est utilisée, les appels à SQLFetchScroll ne peuvent pas être mélangés avec des appels à SQLFetch ou à SQLExtendedFetch.
Lorsque la bibliothèque de curseurs est utilisée, les appels à SQLFetchScroll sont pris en charge à la fois pour ODBC 2. x et pour ODBC 3. x pilotes.
Mémoires tampons d’ensemble de lignes
La bibliothèque de curseurs optimise le transfert des données du pilote vers la mémoire tampon d’ensemble de lignes fournie par l’application si :
L’application utilise une liaison basée sur les lignes.
Il n’y a pas d’octets inutilisés entre les champs dans la structure que l’application déclare pour contenir une ligne de données.
Les champs dans lesquels SQLFetch ou SQLFetchScroll retourne la longueur/l’indicateur d’une colonne suivent la mémoire tampon de cette colonne et précèdent la mémoire tampon pour la colonne suivante. Ces champs sont facultatifs.
Lorsque l’application demande un nouvel ensemble de lignes, la bibliothèque de curseurs récupère les données de son cache et du pilote si nécessaire. Si les nouveaux et les anciens ensembles de lignes se chevauchent, la bibliothèque de curseurs peut optimiser ses performances en réutilisant les données des sections qui se chevauchent des mémoires tampons de l’ensemble de lignes. Par conséquent, les modifications non enregistrées dans les mémoires tampons de l’ensemble de lignes sont perdues, sauf si les nouveaux et les anciens ensembles de lignes se chevauchent et que les modifications se trouvent dans les sections qui se chevauchent des mémoires tampons d’ensemble de lignes. Pour enregistrer les modifications, une application envoie une instruction de mise à jour positionnée.
Notez que la bibliothèque de curseurs actualise toujours les mémoires tampons de l’ensemble de lignes avec les données du cache lorsqu’une application appelle SQLFetchScroll avec l’argument FetchOrientation défini sur SQL_FETCH_RELATIVE et l’argument FetchOffset défini sur 0.
La bibliothèque de curseurs prend en charge l’appel de SQLSetStmtAttr avec un attribut de SQL_ATTR_ROW_ARRAY_SIZE pour modifier la taille de l’ensemble de lignes lorsqu’un curseur est ouvert. La nouvelle taille de l’ensemble de lignes prendra effet la prochaine fois que SQLFetchScroll sera appelé.
Appartenance au jeu de résultats
La bibliothèque de curseurs ne récupère les données du pilote que lorsque l’application les demande. Selon la source de données et le paramètre de l’attribut d’instruction SQL_CONCURRENCY, cela a les conséquences suivantes :
Les données récupérées par la bibliothèque de curseurs peuvent différer des données disponibles au moment de l’exécution de l’instruction. Par exemple, après l’ouverture du curseur, les lignes insérées à un point au-delà de la position actuelle du curseur peuvent être récupérées par certains pilotes.
Les données du jeu de résultats peuvent être verrouillées par la source de données de la bibliothèque de curseurs et ne sont donc pas disponibles pour d’autres utilisateurs.
Une fois que la bibliothèque de curseurs a mis en cache une ligne de données, elle ne peut pas détecter les modifications apportées à cette ligne dans la source de données sous-jacente (à l’exception des mises à jour positionnées et des suppressions qui fonctionnent sur le cache du même curseur). Cela se produit parce que, pour les appels à SQLFetchScroll, la bibliothèque de curseurs ne reféque jamais les données de la source de données. Au lieu de cela, il reféète les données de son cache.
Défilement
La bibliothèque de curseurs prend en charge les types de récupération suivants dans SQLFetchScroll.
| Type de curseur | Types d’extraction |
|---|---|
| Curseur avant uniquement | SQL_FETCH_NEXT |
| statique | SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_RELATIVE SQL_FETCH_ABSOLUTE SQL_FETCH_BOOKMARK |
Erreurs
Lorsque SQLFetchScroll est appelé et que l’un des appels à SQLFetch retourne SQL_ERROR, la bibliothèque de curseurs se poursuit comme suit. Une fois ces étapes terminées, la bibliothèque de curseurs continue son traitement.
Appelle SQLGetDiagRec pour obtenir des informations d’erreur à partir du pilote et les publie sous forme d’enregistrement de diagnostic dans le Gestionnaire de pilotes.
Définit la valeur appropriée pour le champ SQL_DIAG_ROW_NUMBER dans l’enregistrement de diagnostic.
Définit le champ SQL_DIAG_COLUMN_NUMBER dans l’enregistrement de diagnostic sur la valeur appropriée, le cas échéant ; sinon, il le définit sur 0.
Définit la valeur de la ligne en erreur dans le tableau d’état des lignes sur SQL_ROW_ERROR.
Une fois que la bibliothèque de curseurs a appelé SQLFetch plusieurs fois dans son implémentation de SQLFetchScroll, toute erreur ou avertissement retourné par l’un des appels à SQLFetch se trouve dans un enregistrement de diagnostic et peut être récupéré par un appel à SQLGetDiagRec. Si les données ont été tronquées lors de leur extraction, les données tronquées résident désormais dans le cache de la bibliothèque de curseurs. Les appels suivants à SQLFetchScroll pour faire défiler jusqu’à une ligne avec des données tronquées retournent les données tronquées, et aucun avertissement ne sera déclenché, car les données sont extraites du cache de la bibliothèque de curseurs. Pour suivre la longueur des données retournées afin de déterminer si les données retournées dans une mémoire tampon ont été tronquées, une application doit lier la mémoire tampon de longueur/indicateur.
Opérations de signet
La bibliothèque de curseurs prend en charge l’appel de SQLFetchScroll avec un FetchOrientation de SQL_FETCH_BOOKMARK. Il prend également en charge la spécification d’un décalage dans l’argument FetchOffset qui peut être utilisé dans l’opération de signet. Il s’agit de la seule opération de signet prise en charge par la bibliothèque de curseurs. La bibliothèque de curseurs ne prend pas en charge l’appel de SQLBulkOperations.
Si l’application a défini l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS et est liée à la colonne signet, la bibliothèque de curseurs génère un signet de longueur fixe et le retourne à l’application. La bibliothèque de curseurs crée et gère les signets qu’elle utilise ; il n’utilise pas de signets conservés au niveau de la source de données. Lorsque SQLFetchScroll est appelé pour récupérer un bloc de données qui a déjà été extrait à partir de la source de données, il récupère les données du cache de la bibliothèque de curseurs. Par conséquent, le signet utilisé dans un appel à SQLFetchScroll avec une FetchOrientation de SQL_FETCH_BOOKMARK doit être créé et géré par la bibliothèque de curseurs.
Interaction avec d’autres fonctions
Une application doit appeler SQLFetch ou SQLFetchScroll avant de préparer ou d’exécuter des instructions de mise à jour ou de suppression positionnées.