Share via

SQLExtendedFetch, fonction

  • Article

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.

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