Fonction SQLMoreResults

  • Article

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ODBC

Résumé
SQLMoreResults détermine si d’autres résultats sont disponibles sur une instruction contenant des instructions SELECT, UPDATE, INSERT ou DELETE et, le cas échéant, initialise le traitement pour ces résultats.

Syntaxe

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);

Arguments

StatementHandle
[Entrée] Handle d’instruction.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE, OR SQL_PARAM_DATA_AVAILABLE.

Diagnostics

Lorsque SQLMoreResults 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 SQLMoreResults 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.

SQLSTATE Error Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01S02 La valeur de l’option a changé La valeur d’un attribut d’instruction a changé au fur et à mesure que le lot était en cours de traitement. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
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.
40001 Échec de sérialisation La transaction a été annulée en raison d’un blocage de ressources avec une autre transaction.
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 SQLMoreResults a été appelée et, avant la fin de l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle. Ensuite, la fonction SQLMoreResults a été appelée à nouveau sur l’InstructionHandle.

La fonction SQLMoreResults a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un thread différent 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 SQLMoreResults a été appelée.

(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.
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.
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.
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

Les instructions SELECT retournent des jeux de résultats. Les instructions UPDATE, INSERT et DELETE retournent un nombre de lignes affectées. Si l’une de ces instructions est batchée, envoyée avec des tableaux de paramètres (numérotés dans l’ordre croissant des paramètres, dans l’ordre dans lequel elles apparaissent dans le lot), ou dans des procédures, elles peuvent retourner plusieurs jeux de résultats ou nombre de lignes. Pour plus d’informations sur les lots d’instructions et les tableaux de paramètres, consultez Batches of SQL Statements et Arrays of Parameter Values.

Après avoir exécuté le lot, l’application est positionnée sur le premier jeu de résultats. L’application peut appeler SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos et toutes les fonctions de métadonnées, sur le premier jeu de résultats ou tout autre jeu de résultats suivant, comme elle le ferait s’il n’y avait qu’un seul jeu de résultats. Une fois le premier jeu de résultats terminé, l’application appelle SQLMoreResults pour passer au jeu de résultats suivant. Si un autre jeu de résultats ou un autre nombre est disponible, SQLMoreResults retourne SQL_SUCCESS et initialise le jeu de résultats ou le nombre pour un traitement supplémentaire. Si des instructions de génération de nombre de lignes apparaissent entre les instructions de génération de jeu de résultats, elles peuvent être exécutées en appelant SQLMoreResults. Après avoir appelé SQLMoreResults pour les instructions UPDATE, INSERT ou DELETE , une application peut appeler SQLRowCount.

S’il existait un jeu de résultats actuel avec des lignes non affectées, SQLMoreResults ignore ce jeu de résultats et rend le jeu de résultats ou le nombre suivant disponible. Si tous les résultats ont été traités, SQLMoreResults retourne SQL_NO_DATA. Pour certains pilotes, les paramètres de sortie et les valeurs de retour ne sont pas disponibles tant que tous les jeux de résultats et le nombre de lignes n’ont pas été traités. Pour ces pilotes, les paramètres de sortie et les valeurs de retour deviennent disponibles lorsque SQLMoreResults retourne SQL_NO_DATA.

Toutes les liaisons qui ont été établies pour le jeu de résultats précédent restent valides. Si les structures de colonne sont différentes pour ce jeu de résultats, l’appel de SQLFetch ou SQLFetchScroll peut entraîner une erreur ou une troncation. Pour éviter cela, l’application doit appeler SQLBindCol pour qu’il soit explicitement rebiné le cas échéant (ou pour cela, en définissant des champs de descripteur). L’application peut également appeler SQLFreeStmt avec une option de SQL_UNBIND pour dissocier toutes les mémoires tampons de colonne.

Les valeurs des attributs d’instruction, telles que le type de curseur, la concurrence du curseur, la taille du jeu de clés ou la longueur maximale, peuvent changer à mesure que l’application navigue dans le lot en appelant SQLMoreResults. Si cela se produit, SQLMoreResults retourne SQL_SUCCESS_WITH_INFO et SQLSTATE 01S02 (la valeur de l’option a changé).

L’appel de SQLCloseCursor ou SQLFreeStmt avec une option de SQL_CLOSE ignore tous les jeux de résultats et le nombre de lignes disponibles à la suite de l’exécution du lot. Le handle d’instruction retourne à l’état alloué ou préparé. L’appel de SQLCancel pour annuler une fonction en cours d’exécution asynchrone lorsqu’un lot a été exécuté et que le handle d’instruction est à l’état exécuté, positionné sur le curseur ou asynchrone entraîne l’abandon de tous les jeux de résultats et le nombre de lignes générés par le lot si l’appel d’annulation a réussi. L’instruction retourne ensuite à l’état préparé ou alloué.

Si un lot d’instructions ou une procédure combine d’autres instructions SQL avec des instructions SELECT, UPDATE, INSERT et DELETE , ces autres instructions n’affectent pas SQLMoreResults.

Pour plus d’informations, consultez Résultats multiples.

Si une instruction de mise à jour, d’insertion ou de suppression recherchée dans un lot d’instructions n’affecte aucune ligne au niveau de la source de données, SQLMoreResults retourne SQL_SUCCESS. Cela diffère du cas d’une instruction de mise à jour, d’insertion ou de suppression recherchée exécutée via SQLExecDirect, SQLExecute ou SQLParamData, qui retourne SQL_NO_DATA si elle n’affecte aucune ligne au niveau de la source de données. Si une application appelle SQLRowCount pour récupérer le nombre de lignes après qu’un appel à SQLMoreResults n’a affecté aucune ligne, SQLRowCount retourne SQL_NO_DATA.

Pour plus d’informations sur le séquencement valide des fonctions de traitement des résultats, consultez Annexe B : Tables de transition d’état ODBC.

Pour plus d’informations sur SQL_PARAM_DATA_AVAILABLE et les paramètres de sortie diffusés en continu, consultez Récupération des paramètres de sortie à l’aide de SQLGetData.

Disponibilité du nombre de lignes

Lorsqu’un lot contient plusieurs instructions de génération de nombre de lignes consécutives, il est possible que ces nombres de lignes soient regroupés en un seul nombre de lignes. Par exemple, si un lot comporte cinq instructions insert, certaines sources de données sont capables de retourner cinq nombres de lignes individuelles. Certaines autres sources de données retournent un seul nombre de lignes qui représente la somme des cinq nombres de lignes individuelles.

Lorsqu’un lot contient une combinaison d’instructions de génération de jeu de résultats et de génération de nombre de lignes, le nombre de lignes peut ou non être disponible du tout. Le comportement du pilote par rapport à la disponibilité du nombre de lignes est énuméré dans le type d’informations SQL_BATCH_ROW_COUNT disponible via un appel à SQLGetInfo. Par exemple, supposons que le lot contienne un SELECT, suivi de deux INSERTet d’un autre SELECT. Les cas suivants sont alors possibles :

  • Le nombre de lignes correspondant aux deux instructions INSERT n’est pas disponible du tout. Le premier appel à SQLMoreResults vous positionne sur le jeu de résultats de la deuxième instruction SELECT .

  • Les nombres de lignes correspondant aux deux instructions INSERT sont disponibles individuellement. (Un appel à SQLGetInfo ne retourne pas le bit SQL_BRC_ROLLED_UP pour le type d’informations SQL_BATCH_ROW_COUNT.) Le premier appel à SQLMoreResults vous positionne sur le nombre de lignes du premier insert, et le deuxième appel vous positionne sur le nombre de lignes du deuxième insert. Le troisième appel à SQLMoreResults vous positionne sur le jeu de résultats de la deuxième instruction SELECT .

  • Les nombres de lignes correspondant aux deux INSERT sont regroupés en un seul nombre de lignes disponible. (Un appel à SQLGetInfo retourne le bit SQL_BRC_ROLLED_UP pour le type d’informations SQL_BATCH_ROW_COUNT.) Le premier appel à SQLMoreResults vous positionne sur le nombre de lignes regroupées, et le deuxième appel à SQLMoreResults vous positionne sur le jeu de résultats du deuxième SELECT.

Certains pilotes rendent le nombre de lignes disponible uniquement pour les lots explicites et non pour les procédures stockées.

Pour obtenir des informations sur Consultez
Annulation du traitement des instructions SQLCancel, fonction
Extraction d’un bloc de données ou défilement d’un jeu de résultats Fonction SQLFetchScroll
Extraction d’une seule ligne ou d’un bloc de données dans une direction avant uniquement SQLFetch, fonction
Extraction d’une partie ou de la totalité d’une colonne de données Fonction SQLGetData

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Récupération des paramètres de sortie à l’aide de SQLGetData