Fonction SQLMoreResults

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);  

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

Diagnostiques

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 des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

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 par lot, envoyée avec des tableaux de paramètres (numérotées dans l’ordre croissant des paramètres, dans l’ordre qu’elles apparaissent dans le lot) ou dans les procédures, elles peuvent retourner plusieurs jeux de résultats ou nombres de lignes. Pour plus d’informations sur les lots d’instructions et de tableaux de paramètres, consultez Batches of SQL Statements and 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 ou tout jeu de résultats ultérieur, comme il le ferait s’il n’y avait qu’un seul jeu de résultats. Une fois le 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 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 pas à pas en appelant SQLMoreResults. Après avoir appelé SQLMoreResults pour les instructions UPDATE, INSERT ou DELETE , une application peut appeler SQLRowCount.

S’il existe un jeu de résultats actuel avec des lignes non bloquées, SQLMoreResults ignore ce jeu de résultats et rend le jeu de résultats ou le nombre de résultats 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 tous les nombres 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 é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 se connecter explicitement selon les besoins (ou le faire 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, tels 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. Dans ce cas, 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 tous les nombres de lignes disponibles suite à 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 se trouve dans l’état exécuté, positionné par le curseur ou dans l’état asynchrone entraîne l’abandon de tous les jeux de résultats et des nombres de lignes générés par le lot en cours d’abandon 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 Plusieurs résultats.

Si une instruction de mise à jour, d’insertion ou de suppression recherchée dans un lot d’instructions n’affecte aucune ligne à 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 s’il n’affecte aucune ligne à la source de données. Si une application appelle SQLRowCount pour récupérer le nombre de lignes après un appel à SQLMoreResults n’a pas affecté de lignes, SQLRowCount retourne SQL_NO_DATA.

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

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

Disponibilité des nombres 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 d’insertion, certaines sources de données peuvent retourner cinq nombres de lignes individuels. Certaines autres sources de données ne retournent qu’un seul nombre de lignes qui représente la somme des cinq nombres de lignes individuels.

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 en ce qui concerne 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 contient un SELECT, suivi de deux instructions INSERT et d’un autre SELECT. Les cas suivants sont ensuite 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 inscrits, et le deuxième appel à SQLMoreResults vous positionne sur le jeu de résultats du deuxième SELECT.

Certains pilotes rendent les nombres de lignes disponibles uniquement pour les lots explicites et non pour les procédures stockées.

Fonctions associées

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