SQLExtendedFetch, fonction
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : déconseillée
Résumé
SQLExtendedFetch 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.
Remarque
Dans ODBC 3*.x*, SQLExtendedFetch a été remplacé par SQLFetchScroll. Les applications ODBC 3*.x* ne doivent pas appeler SQLExtendedFetch ; au lieu de cela, elles doivent appeler SQLFetchScroll. Le Gestionnaire de pilotes mappe SQLFetchScroll à SQLExtendedFetch lors de l’utilisation d’un pilote ODBC 2*.x*. Les pilotes ODBC 3*.x* doivent prendre en charge SQLExtendedFetch s’ils souhaitent utiliser des applications ODBC 2*.x* qui l’appellent. Pour plus d’informations, consultez « Commentaires » et Curseurs de bloc, Curseurs défilants et compatibilité descendante dans l’annexe G : Recommandations relatives à la compatibilité descendante.
Syntaxe
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Arguments
StatementHandle
[Entrée] Handle d’instruction.
FetchOrientation
[Entrée] Type de récupération. Il s’agit de la même chose que FetchOrientation dans SQLFetchScroll.
FetchOffset
[Entrée] Nombre de lignes à extraire. Il s’agit de la même chose que FetchOffset dans SQLFetchScroll, à une exception près. Lorsque FetchOrientation est SQL_FETCH_BOOKMARK, FetchOffset est un signet de longueur fixe, et non un décalage d’un signet. En d’autres termes, SQLExtendedFetch récupère le signet à partir de cet argument, et non l’attribut d’instruction SQL_ATTR_FETCH_BOOKMARK_PTR. Il ne prend pas en charge les signets de longueur variable et ne prend pas en charge l’extraction d’un ensemble de lignes à un décalage (autre que 0) à partir d’un signet.
RowCountPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre de lignes réellement extraites. Cette mémoire tampon est utilisée de la même manière que celle spécifiée par l’attribut d’instruction SQL_ATTR_ROWS_FETCHED_PTR. Cette mémoire tampon est utilisée uniquement par SQLExtendedFetch. Il n’est pas utilisé par SQLFetch ou SQLFetchScroll.
RowStatusArray
[Sortie] Pointeur vers un tableau dans lequel retourner l’état de chaque ligne. Ce tableau est utilisé de la même manière que le tableau spécifié par l’attribut d’instruction SQL_ATTR_ROW_STATUS_PTR.
Toutefois, l’adresse de ce tableau n’est pas stockée dans le champ SQL_DESC_STATUS_ARRAY_PTR dans l’IRD. En outre, ce tableau est utilisé uniquement par SQLExtendedFetch et par SQLBulkOperations avec une opération de SQL_ADD ou SQLSetPos lorsqu’il est appelé après SQLExtendedFetch. Elle n’est pas utilisée par SQLFetch ou SQLFetchScroll, et elle n’est pas utilisée par SQLBulkOperations ou SQLSetPos lorsqu’elles sont appelées après SQLFetch ou SQLFetchScroll. Il n’est pas également utilisé lorsque SQLBulkOperations avec une opération de SQL_ADD est appelée avant l’appel d’une fonction fetch. En d’autres termes, il est utilisé uniquement dans l’état de l’instruction S7. Il n’est pas utilisé dans les états d’instruction S5 ou S6. Pour plus d’informations, consultez Transitions d’instruction dans l’annexe B : Tables de transition d’état ODBC.
Les applications doivent fournir un pointeur valide dans l’argument RowStatusArray ; sinon, le comportement de SQLExtendedFetch et le comportement des appels à SQLBulkOperations ou SQLSetPos après qu’un curseur a été positionné par SQLExtendedFetch ne sont pas définis.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLExtendedFetch retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLError. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLExtendedFetch 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.
| 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. S’il s’agissait d’une valeur numérique, la partie fractionnaire du nombre a été tronquée. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S01 | Erreur dans la ligne | Une erreur s’est produite lors de l’extraction d’une ou plusieurs lignes. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S06 | Tentative d’extraction avant que le jeu de résultats ne retourne le premier ensemble de lignes | L’ensemble de lignes demandé a superposé le début du jeu de résultats lorsque la position actuelle était au-delà de la première ligne, et FetchOrientation était SQL_PRIOR ou FetchOrientation était SQL_RELATIVE avec un FetchOffset négatif dont la valeur absolue était inférieure ou égale à la SQL_ROWSET_SIZE actuelle. (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 | Impossible de convertir une valeur de données en type de données C spécifié par TargetType dans SQLBindCol. |
| 07009 | Index de descripteur non valide | La colonne 0 a été liée à SQLBindCol 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. |
| 22002 | Variable d’indicateur requise, mais non fournie | Les données NULL ont été extraites dans une colonne dont la StrLen_or_IndPtr définie par SQLBindCol était un pointeur Null. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 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 aurait provoqué la troncation de la partie entière (par opposition à la fraction) du nombre. (La fonction retourne SQL_SUCCESS_WITH_INFO.) Pour plus d’informations, consultez Instructions pour les types de données interval et numeric 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. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 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. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 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. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 22018 | Valeur de caractère non valide pour la spécification de cast | 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é. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 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. |
| 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 SQLError 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 qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle, puis 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 SQLExtendedFetch 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) SQLExtendedFetch a été appelé pour l’instructionHandle après que SQLFetch ou SQLFetchScroll ait été appelé et avant que SQLFreeStmt ait été appelé avec l’option SQL_CLOSE. (DM) SQLBulkOperations a été appelé pour une instruction avant SQLFetch, SQLFetchScroll ou SQLExtendedFetch a été appelée, puis SQLExtendedFetch a été appelée avant que SQLFreeStmt ait été appelé 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 accessibles, éventuellement en raison de conditions de mémoire insuffisantes. |
| HY106 | Type d’extraction hors plage | (DM) La valeur spécifiée pour l’argument FetchOrientation n’était pas valide. (Voir « Commentaires »). 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’option d’instruction SQL_CURSOR_TYPE était SQL_CURSOR_FORWARD_ONLY et la valeur de l’argument FetchOrientation n’était pas SQL_FETCH_NEXT. L’argument FetchOrientation a été SQL_FETCH_RESUME. |
| HY107 | Valeur de ligne hors plage | La valeur spécifiée avec l’option d’instruction SQL_CURSOR_TYPE était SQL_CURSOR_KEYSET_DRIVEN, mais la valeur spécifiée avec l’attribut d’instruction SQL_KEYSET_SIZE était supérieure à 0 et inférieure à la valeur spécifiée avec l’attribut d’instruction SQL_ROWSET_SIZE. |
| HY111 | Valeur de signet non valide | L’argument FetchOrientation était SQL_FETCH_BOOKMARK, et le signet spécifié dans l’argument FetchOffset n’était pas valide. |
| 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 le type d’extraction spécifié. 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. Cette erreur s’applique uniquement lorsque le type de données SQL de la colonne a été mappé à un type de données SQL spécifique au pilote. |
| HYT00 | Délai expiré | La période d’expiration de la requête a expiré avant que la source de données ne retourne le jeu de résultats. La période d’expiration est définie via SQLSetStmtOption, SQL_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. |
Commentaires
Le comportement de SQLExtendedFetch est identique à celui de SQLFetchScroll, avec les exceptions suivantes :
SQLExtendedFetch et SQLFetchScroll utilisent différentes méthodes pour retourner le nombre de lignes extraites. SQLExtendedFetch retourne le nombre de lignes extraites dans *RowCountPtr ; SQLFetchScroll retourne le nombre de lignes extraites directement dans la mémoire tampon pointée par SQL_ATTR_ROWS_FETCHED_PTR. Pour plus d’informations, consultez l’argument RowCountPtr .
SQLExtendedFetch et SQLFetchScroll retournent l’état de chaque ligne dans différents tableaux. Pour plus d’informations, consultez l’argument RowStatusArray .
SQLExtendedFetch et SQLFetchScroll utilisent différentes méthodes pour récupérer le signet lorsque FetchOrientation est SQL_FETCH_BOOKMARK. SQLExtendedFetch ne prend pas en charge les signets de longueur variable ou l’extraction d’ensembles de lignes à un décalage autre que 0 à partir d’un signet. Pour plus d’informations, consultez l’argument FetchOffset .
SQLExtendedFetch et SQLFetchScroll utilisent différentes tailles d’ensemble de lignes. SQLExtendedFetch utilise la valeur de l’attribut d’instruction SQL_ROWSET_SIZE, et SQLFetchScroll utilise la valeur de l’attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE.
SQLExtendedFetch a une sémantique de gestion des erreurs légèrement différente de SQLFetchScroll. Pour plus d’informations, consultez « Gestion des erreurs » dans la section « Commentaires » de SQLFetchScroll.
SQLExtendedFetch ne prend pas en charge les décalages de liaison (attribut d’instruction SQL_ATTR_ROW_BIND_OFFSET_PTR).
Les appels à SQLExtendedFetch ne peuvent pas être mélangés avec des appels à SQLFetch ou SQLFetchScroll, et si SQLBulkOperations est appelé avant l’appel d’une fonction fetch, SQLExtendedFetch ne peut pas être appelé tant que le curseur n’est pas fermé et rouvert. Autrement dit, SQLExtendedFetch peut être appelé uniquement dans l’état de l’instruction S7. Pour plus d’informations, consultez Transitions d’instruction dans l’annexe B : Tables de transition d’état ODBC.
Lorsqu’une application appelle SQLFetchScroll lors de l’utilisation d’un pilote ODBC 2*.x*, le Gestionnaire de pilotes mappe cet appel à SQLExtendedFetch. Pour plus d’informations, consultez « SQLFetchScroll et ODBC 2*.x* Drivers » dans SQLFetchScroll.
Dans ODBC 2*.x*, SQLExtendedFetch a été appelé pour extraire plusieurs lignes et SQLFetch a été appelé pour extraire une seule ligne. Dans ODBC 3*.x*, par contre, SQLFetch peut être appelé pour extraire plusieurs lignes.
Fonctions connexes
| Pour plus d’informations sur | Consultez |
|---|---|
| Liaison d’une mémoire tampon à une colonne dans un jeu de résultats | SQLBindCol, fonction |
| 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 | SQLDescribeCol, fonction |
| Exécution d’une instruction SQL | SQLExecDirect, fonction |
| Exécution d’une instruction SQL préparée | SQLExecute, fonction |
| Renvoi du nombre de colonnes du jeu de résultats | SQLNumResultCols, fonction |
| 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 | SQLSetStmtAttr, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC