SQLFetchScroll, fonction

Article
05/23/2023

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.

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.)
01S06	Tentative d’extraction avant que le jeu de résultats ne retourne le premier ensemble de lignes	L’ensemble de lignes demandé se chevauche au début du jeu de résultats lorsque FetchOrientation a été SQL_FETCH_PRIOR, la position actuelle était au-delà de la première ligne et le nombre de la ligne actuelle est inférieur ou égal à la taille de l’ensemble de lignes. L’ensemble de lignes demandé se chevauche au début du jeu de résultats lorsque FetchOrientation a été SQL_FETCH_PRIOR, la position actuelle était au-delà de la fin du jeu de résultats et la taille de l’ensemble de lignes était supérieure à la taille du jeu de résultats. L’ensemble de lignes demandé se chevauche au début du jeu de résultats lorsque FetchOrientation a été SQL_FETCH_RELATIVE, FetchOffset a été négatif et la valeur absolue de FetchOffset était inférieure ou égale à la taille de l’ensemble de lignes. L’ensemble de lignes demandé se chevauche au début du jeu de résultats lorsque FetchOrientation a été SQL_FETCH_ABSOLUTE, FetchOffset était négatif et la valeur absolue de FetchOffset était supérieure à la taille du jeu de résultats, mais inférieure ou égale à la taille de l’ensemble de lignes. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
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 contenant 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 numérique ou 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é.
24000	É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 a été appelée et avant l’exécution terminée, SQLCancel ou SQLCancelHandle a été appelée sur StatementHandle. Ensuite, la fonction a été appelée à nouveau sur l’instructionHandle. La fonction a été appelée et avant qu’elle ait terminé l’exécution, 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 SQLFetchScroll 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.)
HY106	Type d’extraction hors plage	DM) La valeur spécifiée pour l’argument FetchOrientation n’était pas valide. (DM) L’argument FetchOrientation a été SQL_FETCH_BOOKMARK et l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_OFF. La valeur de l’attribut d’instruction SQL_ATTR_CURSOR_TYPE était SQL_CURSOR_FORWARD_ONLY et la valeur de l’argument FetchOrientation n’était pas SQL_FETCH_NEXT. La valeur de l’attribut d’instruction SQL_ATTR_CURSOR_SCROLLABLE était SQL_NONSCROLLABLE et la valeur de l’argument FetchOrientation n’était pas SQL_FETCH_NEXT.
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.
HY111	Valeur de signet non valide	L’argument FetchOrientation a été SQL_FETCH_BOOKMARK, et le signet pointé par la valeur de l’attribut d’instruction SQL_ATTR_FETCH_BOOKMARK_PTR n’était pas valide ou était un pointeur Null.
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

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.

FetchOrientation	Signification
SQL_FETCH_NEXT	Retournez l’ensemble de lignes suivant. Cela équivaut à appeler SQLFetch. SQLFetchScroll ignore la valeur de FetchOffset.
SQL_FETCH_PRIOR	Retournez l’ensemble de lignes précédent. SQLFetchScroll ignore la valeur de FetchOffset.
SQL_FETCH_RELATIVE	Retourne l’ensemble de lignes FetchOffset à partir du début de l’ensemble de lignes actuel.
SQL_FETCH_ABSOLUTE	Retourne l’ensemble de lignes à partir de la ligne FetchOffset.
SQL_FETCH_FIRST	Retourne le premier ensemble de lignes dans le jeu de résultats. SQLFetchScroll ignore la valeur de FetchOffset.
SQL_FETCH_LAST	Retourne le dernier ensemble de lignes complet dans le jeu de résultats. SQLFetchScroll ignore la valeur de FetchOffset.
SQL_FETCH_BOOKMARK	Retournez les lignes FetchOffset de l’ensemble de lignes à partir du signet spécifié par l’attribut d’instruction SQL_ATTR_FETCH_BOOKMARK_PTR.

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.

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, SQLFetchScroll 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, SQLFetchScroll 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.
FetchOffset	Valeur de l’argument FetchOffset .
BookmarkRow	Ligne correspondant au signet spécifié par l’attribut d’instruction SQL_ATTR_FETCH_BOOKMARK_PTR.