SQLRowCount (fonction)

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

Résumé
SQLRowCount retourne le nombre de lignes affectées par une instruction UPDATE, INSERT ou DELETE ; une opération SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK dans SQLBulkOperations ; ou une opération SQL_UPDATE ou SQL_DELETE dans SQLSetPos.

Syntaxe

  
SQLRETURN SQLRowCount(  
      SQLHSTMT   StatementHandle,  
      SQLLEN *   RowCountPtr);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

RowCountPtr
[Sortie] Pointe vers une mémoire tampon dans laquelle retourner un nombre de lignes. Pour les instructions UPDATE, INSERT et DELETE , pour les opérations SQL_ADD, SQL_UPDATE_BY_BOOKMARK et SQL_DELETE_BY_BOOKMARK dans SQLBulkOperations, et pour les opérations SQL_UPDATE ou SQL_DELETE dans SQLSetPos, la valeur renvoyée dans *RowCountPtr est le nombre de lignes affectées par la requête ou -1 si le nombre de lignes affectées n’est pas disponible.

Lorsque SQLExecute, SQLExecDirect, SQLBulkOperations, SQLSetPos ou SQLMoreResults est appelé, le champ SQL_DIAG_ROW_COUNT de la structure de données de diagnostic est défini sur le nombre de lignes et le nombre de lignes est mis en cache de manière dépendante de l’implémentation. SQLRowCount retourne la valeur du nombre de lignes mises en cache. La valeur du nombre de lignes mises en cache est valide jusqu’à ce que le handle d’instruction soit rétabli à l’état préparé ou alloué, que l’instruction soit réexécutée ou que SQLCloseCursor soit appelé. Notez que si une fonction a été appelée depuis que le champ SQL_DIAG_ROW_COUNT a été défini, la valeur retournée par SQLRowCount peut être différente de la valeur dans le champ SQL_DIAG_ROW_COUNT, car le champ SQL_DIAG_ROW_COUNT est réinitialisé à 0 par n’importe quel appel de fonction.

Pour d’autres instructions et fonctions, le pilote peut définir la valeur retournée dans *RowCountPtr. Par exemple, certaines sources de données peuvent être en mesure de retourner le nombre de lignes retournées par une instruction SELECT ou une fonction de catalogue avant d’extraire les lignes.

Notes

De nombreuses sources de données ne peuvent pas retourner le nombre de lignes d’un jeu de résultats avant de les extraire ; pour une interopérabilité maximale, les applications ne doivent pas s’appuyer sur ce comportement.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLRowCount 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 SQLRowCount 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.)
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.
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 SQLRowCount 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) La fonction a été appelée avant d’appeler SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos pour l’InstructionHandle. (DM) Une fonction d’exécution asynchrone a été appelée pour l’InstructionHandle 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 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.

Commentaires

Si la dernière instruction SQL exécutée sur le handle d’instruction n’était pas une instruction UPDATE, INSERT ou DELETE , ou si l’argument Operation de l’appel précédent à SQLBulkOperations n’était pas SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK, ou si l’argument Operation dans l’appel précédent à SQLSetPos n’était pas SQL_UPDATE ou SQL_DELETE, la valeur de *RowCountPtr est définie par le pilote. Pour plus d’informations, consultez Détermination du nombre de lignes affectées.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Exécution d’une instruction SQL	SQLExecDirect, fonction
Exécution d’une instruction SQL préparée	SQLExecute, fonction

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC