SQLExtendedFetch, fonction
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : déconseillée
Résumé
SQLExtendedFetch 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.
Notes
Dans ODBC 3*.x*, SQLExtendedFetch a été remplacé par SQLFetchScroll. Les applications ODBC 3*.x* ne doivent pas appeler SQLExtendedFetch ; au lieu de cela, ils 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 les applications ODBC 2*.x* qui l’appellent. Pour plus d’informations, consultez « Commentaires » et Bloquer les curseurs, les curseurs à défilement et la compatibilité descendante dans l’annexe G : Instructions de pilote pour 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] Numéro de la ligne à 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 la mémoire tampon 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. Il n’est pas utilisé par SQLFetch ou SQLFetchScroll, et il n’est pas utilisé par SQLBulkOperations ou SQLSetPos lorsqu’ils sont appelés après SQLFetch ou SQLFetchScroll. Il n’est pas non plus utilisé quand SQLBulkOperations avec une opération de SQL_ADD est appelé avant l’appel d’une fonction de récupération. En d’autres termes, il est utilisé uniquement dans l’état d’instruction S7. Il n’est pas utilisé dans les états d’instruction S5 ou S6. Pour plus d’informations, consultez Transitions d’instructions dans l’Annexe B : Tables de transition d’état ODBC.
Les applications doivent fournir un pointeur valide dans l’argument RowStatusArray ; si ce n’est pas le cas, 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 | 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 était tronquée à droite. S’il s’agissait d’une valeur numérique, la partie fractionnaire du nombre était 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 de 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 chevauché le début du jeu de résultats lorsque la position actuelle se trouvait au-delà de la première ligne et que 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 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 restreinte | Une valeur de données n’a pas pu être convertie en type de données C spécifié par TargetType dans SQLBindCol. |
07009 | Index de descripteur non valide | La colonne 0 était liée à SQLBindCol et l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_OFF. |
08S01 | Échec de la liaison de communication | La liaison de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant que la fonction n’ait terminé le traitement. |
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 é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 entraîné la tronquation de la partie entière (plutôt que fractionnaire) du nombre. (La fonction retourne SQL_SUCCESS_WITH_INFO.) Pour plus d’informations, consultez Recommandations pour les types de données interval et numériques 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 de date, d’heure ou d’horodatage C, et une valeur de 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é une 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 entraîné une perte de chiffres significatifs dans le champ de début. Lors de l’extraction de données vers un type d’intervalle C, il n’y avait aucune représentation de la valeur du type SQL dans le type d’intervalle C. (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 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é. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
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. |
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 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 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ée sur l’InstructionHandle, puis 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 SQLExtendedFetch 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) SQLExtendedFetch a été appelé pour l’instruction StatementHandle après l’appel de SQLFetch ou SQLFetchScroll et avant l’appel de SQLFreeStmt avec l’option SQL_CLOSE. (DM) SQLBulkOperations a été appelé pour une instruction avant l’appel de SQLFetch, SQLFetchScroll ou SQLExtendedFetch , puis SQLExtendedFetch avant que SQLFreeStmt ne soit 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 consultés, peut-être en raison de conditions de mémoire insuffisantes. |
HY106 | Type d’extraction hors de la 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 était 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 a été 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 FONCTION SQLEndTran. |
HYC00 | Fonctionnalité facultative non implémentée | Le pilote ou la source de données ne prend pas en charge le type de récupération spécifié. 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. 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é | Le délai d’expiration de la requête a expiré avant que la source de données ne retourne le jeu de résultats. Le délai d’expiration est défini via SQLSetStmtOption, SQL_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. |
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 ni l’extraction des 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 celle 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 de récupération, 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 d’instruction S7. Pour plus d’informations, consultez Transitions d’instructions 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 « Pilotes SQLFetchScroll et ODBC 2*.x* » dans SQLFetchScroll.
Dans ODBC 2*.x*, SQLExtendedFetch a été appelé pour extraire plusieurs lignes et SQLFetch a été appelé pour extraire une seule ligne. En revanche, dans ODBC 3*.x*, SQLFetch peut être appelé pour extraire plusieurs lignes.
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 |
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