Fonction SQLFetchScroll
Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92
Résumé
SQLFetchScroll extrait l’ensemble de lignes spécifié de données 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 Mappage des fonctions de remplacement 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 d’extraction :
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]
Numéro de la ligne à 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 de 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 peuvent être appelés 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 (à l’exception de 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO est retourné si une erreur se produit sur une ou plusieurs lignes d’une opération multiligne, mais pas sur la totalité, et SQL_ERROR est retournée 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 a été tronquée à droite. |
| 01S01 | Erreur dans la ligne | Une erreur s’est produite lors de l’extraction d’une ou de plusieurs lignes. (Si ce SQLSTATE est retourné lorsqu’une application ODBC 3*.x* fonctionne avec un pilote ODBC 2*.x*, il peut être ignoré.) |
| 01S06 | Tentative d’extraction avant que le jeu de résultats ne retourne le premier ensemble de lignes | L’ensemble de lignes demandé a chevauché le début du jeu de résultats lorsque FetchOrientation a été SQL_FETCH_PRIOR, que la position actuelle était au-delà de la première ligne et que le nombre de la ligne actuelle est inférieur ou égal à la taille de l’ensemble de lignes. L’ensemble de lignes demandé chevauche le 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é chevauche le début du jeu de résultats lorsque FetchOrientation a été SQL_FETCH_RELATIVE, FetchOffset était négatif et que la valeur absolue de FetchOffset était inférieure ou égale à la taille de l’ensemble de lignes. L’ensemble de lignes demandé chevauche le début du jeu de résultats lorsque FetchOrientation a été SQL_FETCH_ABSOLUTE, FetchOffset était négatif et que 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 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 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 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 | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant la fin 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 StrLen_or_IndPtr définie par SQLBindCol (ou SQL_DESC_INDICATOR_PTR définie par SQLSetDescField ou SQLSetDescRec) était un pointeur Null. |
| 22003 | Valeur numérique hors plage | Le renvoi de la valeur numérique (numérique ou chaîne) pour une ou plusieurs colonnes liées aurait entraîné la troncation de la partie entière (par opposition à une fraction) du nombre. Pour plus d’informations, consultez Conversion de données de types de données 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é 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 C d’intervalle, il n’y avait aucune représentation de la valeur du type SQL dans le type interval 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 a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle. Ensuite, la fonction a été appelée à nouveau sur l’InstructionHandle. La fonction a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un autre thread dans une application multithread. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction d’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 SQLFetchScroll a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle 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. (DM) L’InstructionHandle spécifiée n’était pas dans un état exécuté. La fonction a été appelée sans appeler d’abord SQLExecDirect, SQLExecute ou une fonction de catalogue. (DM) Une fonction d’exécution asynchrone (et non celle-ci) a été appelée pour l’InstructionHandle et s’exécutait toujours lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a renvoyé 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’instruction StatementHandle 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 consultés, 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 é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 de la 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 était 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 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 réponde à la demande. La période de délai d’expiration de la connexion est définie 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 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 la fermeture du curseur sur ce jeu de résultats. Si des colonnes sont liées, elles retournent 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 pas avec des appels à SQLExtendedFetch.
Pour plus d’informations, consultez Utilisation de curseurs de bloc et Utilisation de curseurs scrollables.
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 indiquées dans la section suivante.
| FetchOrientation | Signification |
|---|---|
| SQL_FETCH_NEXT | Retourne l’ensemble de lignes suivant. Cela équivaut à appeler SQLFetch. SQLFetchScroll ignore la valeur de FetchOffset. |
| SQL_FETCH_PRIOR | Retourne 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 en commençant à 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 | Retourne 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 tenus de prendre en charge toutes les orientations de récupération ; une application appelle SQLGetInfo avec un type d’informations SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 ou 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 SQL_CA1_NEXT, les SQL_CA1_RELATIVE, les SQL_CA1_ABSOLUTE et les WQL_CA1_BOOKMARK dans ces types d’informations. En outre, si le curseur est vers l’avant uniquement et que 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 extrait 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 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 SQLFetchScroll est retourné, 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 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, 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. |
SQL_FETCH_NEXT
Les règles suivantes s’appliquent.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| Avant le début | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | Après la fin |
| Après la fin | Après la fin |
[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 de l’ensemble de lignes qui a été utilisée avec l’appel précédent.
SQL_FETCH_PRIOR
Les règles suivantes s’appliquent.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| Avant le début | Avant le début |
| CurrRowsetStart = 1 | Avant le début |
| 1 < CurrRowsetStart <= RowsetSize[2] | 1[1] |
| CurrRowsetStart > RowsetSize[2] | CurrRowsetStart - RowsetSize[2] |
| Après la fin ET LastResultRow < RowsetSize[2] | 1[1] |
| After end AND LastResultRow >= RowsetSize[2] | LastResultRow - RowsetSize + 1[2] |
[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.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| (Avant le début ET FetchOffset > 0) OR (Après la fin ET FetchOffset < 0) | --[1] |
| BeforeStart AND FetchOffset <= 0 | Avant le début |
| CurrRowsetStart = 1 AND FetchOffset < 0 | Avant le début |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize[3] | Avant le début |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize[3] | 1[2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | Après la fin |
| Après la fin et FetchOffset >= 0 | Après la fin |
[1] SQLFetchScroll retourne le même ensemble de lignes que s’il était 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 n’a retourné 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.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| FetchOffset < 0 AND | FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize[2] | Avant le début |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize[2] | 1[1] |
| FetchOffset = 0 | Avant le début |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | Après la fin |
[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 sont indéterminées. Une telle opération équivaut à une extraction d’abord suivie d’un rapport d’extraction ; il ne s’agit pas d’une opération atomique, tout comme une extraction absolue sur un curseur statique.
SQL_FETCH_FIRST
Les règles suivantes s’appliquent.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| Aucune | 1 |
SQL_FETCH_LAST
Les règles suivantes s’appliquent.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| RowsetSize[1]<= LastResultRow | LastResultRow - RowsetSize + 1[1] |
| RowsetSize[1]> LastResultRow | 1 |
[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.
| Condition | Première ligne du nouvel ensemble de lignes |
|---|---|
| BookmarkRow + FetchOffset < 1 | Avant le début |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | Après la fin |
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 un jeu 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 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 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 refetcher le même ensemble de lignes, mais n’inclut pas le cas quand SQLSetPos est appelé avec fOption défini sur SQL_REFRESH. Dans ce dernier cas, les données dans les mémoires tampons de l’ensemble de lignes sont actualisées, mais pas réétifiées, et les lignes supprimées ne sont pas supprimées du jeu de résultats. Ainsi, 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’il extrait un ensemble de lignes qui incluait précédemment la ligne supprimée ou inclut maintenant 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 actif 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 peut détecter, même si elles 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 actif, un ensemble de lignes partiel est considéré comme se terminant à 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 soit 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éfini sur SQL_FETCH_NEXT, SQLFetchScroll retourne l’ensemble de lignes en commençant par la première ligne nouvellement ajoutée.
Par exemple, supposons que l’ensemble de lignes actuel comprend les lignes 21 à 30, que la taille de l’ensemble de lignes est de 10, que le curseur supprime les lignes supprimées du jeu de résultats et que 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.
| Modifier | Type d’extraction | FetchOffset | Nouvel ensemble de lignes[1] |
|---|---|---|---|
| Supprimer la ligne 21 | NEXT | 0 | 31 à 40 |
| Supprimer la ligne 31 | NEXT | 0 | 32 à 41 |
| Insérer une ligne entre les lignes 21 et 22 | NEXT | 0 | 31 à 40 |
| Insérer une ligne entre les lignes 30 et 31 | NEXT | 0 | Ligne insérée, 31 à 39 |
| Supprimer la ligne 21 | PRIOR | 0 | 11 à 20 |
| Supprimer la ligne 20 | PRIOR | 0 | 10 à 19 |
| Insérer une ligne entre les lignes 21 et 22 | PRIOR | 0 | 11 à 20 |
| Insérer une ligne entre les lignes 20 et 21 | PRIOR | 0 | 12 à 20, ligne insérée |
| Supprimer la ligne 21 | RELATIVE | 0 | 22 à 31[2] |
| Supprimer la ligne 21 | RELATIVE | 1 | 22 à 31 |
| Insérer une ligne entre les lignes 21 et 22 | RELATIVE | 0 | 21, ligne insérée, 22 à 29 |
| Insérer une ligne entre les lignes 21 et 22 | RELATIVE | 1 | 22 à 31 |
| Supprimer la ligne 21 | ABSOLUTE | 21 | 22 à 31[2] |
| Supprimer la ligne 22 | ABSOLUTE | 21 | 21, 23 à 31 |
| Insérer une ligne entre les lignes 21 et 22 | ABSOLUTE | 22 | Ligne insérée, 22 à 29 |
[1] Cette colonne utilise les numéros de ligne avant l’insertion ou la suppression des lignes.
[2] Dans ce cas, le curseur tente de renvoyer des lignes à partir de la ligne 21. Étant donné que la ligne 21 a été supprimée, la première ligne qu’elle retourne est la ligne 22.
Les lignes d’erreur (c’est-à-dire 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 renvoie l’ensemble de lignes à partir de la ligne 16, comme il le ferait 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 manière que SQLFetch. Pour plus d’informations, consultez « Retour de données dans des colonnes liées » dans 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. La possibilité de récupérer des données à partir de colonnes non liées 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 mémoires tampons de données et de longueur/d’indicateur que SQLFetch. Pour plus d’informations, consultez « Adresses tampons » dans la fonction SQLBindCol.
Tableau d’état des lignes
SQLFetchScroll définit les valeurs dans le tableau d’état des lignes de la même manière que SQLFetch. Pour plus d’informations, consultez « Tableau d’état de ligne » dans FONCTION SQLFetch.
Mémoire tampon extraite des lignes
SQLFetchScroll retourne le nombre de lignes extraites dans la mémoire tampon extraite des lignes de la même manière que SQLFetch. Pour plus d’informations, consultez « Mémoire tampon extraite des lignes » dans SQLFetch Function.
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 d’une 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 les erreurs et les avertissements de la même manière que SQLFetch ; Pour plus d’informations, consultez « Gestion des erreurs » dans SQLFetch. SQLExtendedFetch retourne les erreurs de la même manière que SQLFetch, avec les exceptions suivantes :
Lorsqu’un avertissement s’applique à une ligne particulière de l’ensemble de lignes, SQLExtendedFetch définit l’entrée correspondante dans le tableau d’état des lignes 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 renvoyer d’autres SQLSTATEs, il doit toujours renvoyer ce SQLSTATE.
SQLFetchScroll et accès concurrentiel 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 optimistes utilisées par la source de données pour détecter si une ligne a changé. Cela se produit chaque fois que SQLFetchScroll extrait un nouvel ensemble de lignes, y compris lorsqu’il reféète l’ensemble de lignes actif. (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.
| Argument SQLExtendedFetch | Valeur |
|---|---|
| StatementHandle | StatementHandle dans SQLFetchScroll. |
| FetchOrientation | FetchOrientation dans SQLFetchScroll. |
| FetchOffset | Si FetchOrientation n’est pas SQL_FETCH_BOOKMARK, la valeur de l’argument FetchOffset dans SQLFetchScroll est utilisée. Si FetchOrientation est SQL_FETCH_BOOKMARK, la valeur stockée à l’adresse spécifiée par l’attribut d’instruction SQL_ATTR_FETCH_BOOKMARK_PTR est utilisée. |
| RowCountPtr | Adresse spécifiée par l’attribut d’instruction SQL_ATTR_ROWS_FETCHED_PTR. |
| RowStatusArray | Adresse spécifiée par l’attribut d’instruction SQL_ATTR_ROW_STATUS_PTR. |
Pour plus d’informations, consultez Bloquer les curseurs, Curseurs à défilement et Compatibilité descendante à l’Annexe G : Instructions de pilote pour la compatibilité descendante.
Descripteurs et SQLFetchScroll
SQLFetchScroll interagit avec les descripteurs de la même manière que SQLFetch. Pour plus d’informations, consultez la section « Descriptors and SQLFetchScroll » dans SQLFetch Function.
Exemple de code
Consultez Liaison par colonne, Liaison au niveau des lignes, Instructions de mise à jour et de suppression positionnées et Mise à jour des lignes dans l’ensemble de lignes avec SQLSetPos.
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| Liaison d’une mémoire tampon à une colonne dans un jeu de résultats | Fonction SQLBindCol |
| Exécution d’opérations d’insertion, de mise à jour ou de suppression en bloc | SQLBulkOperations, fonction |
| 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’une seule ligne ou d’un bloc de données dans une direction vers l’avant uniquement | SQLFetch, fonction |
| Fermeture du curseur sur l’instruction | Fonction SQLFreeStmt |
| Retour du nombre de colonnes de jeu de résultats | Fonction SQLNumResultCols |
| Positionnement du curseur, actualisation des données dans l’ensemble de lignes ou mise à jour ou suppression de données dans le jeu de résultats | SQLSetPos, fonction |
| Définition d’un attribut d’instruction | Fonction SQLSetStmtAttr |
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