Types de données de l'API C
<<<		 C API Prepared Statement Function Overview Descriptions des fonctions C pour les requêtes préparées
>>>
21.2 API MySQL C
21 API MySQL
 Manuel de Référence MySQL 4.1 : Version Française
. Types de données de l'API C
. Vue d'ensemble des fonctions de l'API C
. Description des fonctions de l'API C
. Fonctions C de commandes préparées
. Types de données de l'API C
->C API Prepared Statement Function Overview
. Descriptions des fonctions C pour les requêtes préparées
. C API Handling of Multiple Query Execution
. C API Handling of Date and Time Values
. Description des fonctions threadées de C
. Description des fonctions C du serveur embarqué
. Questions courantes sur la librairie C
. Compiler les clients
. Comment faire un client MySQL threadé
. libmysqld, la librairie du serveur embarqué MySQL

21.2.6 C API Prepared Statement Function Overview

Voici les fonctions disponibles pour les commandes préparées. Elles sont listées ici et détailles plus loin. Description des fonctions C de commandes préparées .

Fonction Description
mysql_bind_param() Associe un buffer avec une variable de requêtes, dans une commande préparée.
mysql_bind_result() Lie les buffers de l'application avec les colonnes d'un résultat.
mysql_execute() Exécute une commande préparée.
mysql_fetch() Lit la prochaine ligne de données dans le résultat, et retourne toutes les données des colonnes liées.
mysql_fetch_column() Lit les données d'une seule colonne, dans le résultat.
mysql_get_metadata() Retourne les méta-données de la commande préparée, sous forme d'un jeu de résultat.
mysql_param_count() Retourne le nombre de paramètres d'une commande préparée.
mysql_param_result() Retourne les meta-données des paramètres, sous forme d'un jeu de résultat.
mysql_prepare() Prépare une chaîne SQL pour l'exécution.
mysql_send_long_data() Envoie de grandes données par parties.
mysql_stmt_affected_rows() Retourne le nombre de lignes modifiées, effacées ou insérée dans la dernière requête UPDATE, DELETE ou INSERT.
mysql_stmt_close() Libère une commande préparée de la mémoire.
mysql_stmt_data_seek() Se place à une numéro de ligne arbitraire dans un jeu de résultat.
mysql_stmt_errno() Retourne le numéro d'erreur de la dernière requête.
mysql_stmt_error() Retourne le méssage d'erreur de la dernière requête.
mysql_stmt_free_result() Libère les ressources allouées pour la commande.
mysql_stmt_num_rows() Retourne le nombre total de lignees dans un jeu de résultat bufferisé.
mysql_stmt_reset() Remet à zéro les buffers de la commande, sur le serveur.
mysql_stmt_row_seek() Se place à un numéro de ligne, dans un résultat de commande, en utilisant la valeure retournée par mysql_stmt_row_tell() .
mysql_stmt_row_tell() Retourne la position du curseur de ligne de la commande.
mysql_stmt_sqlstate() Retourne le code d'erreur SQLSTATE de la dernière opération.
mysql_stmt_store_result() Lit tout le résultat dans le client.
Appelez mysql_prepare() pour préparer et initialiser la commande, puis appelez mysql_bind_param() pour fournir les données des paramètres, enfin appelez mysql_execute() pour exécuter la requête. Vous pouvez répépter mysql_execute() en modificant les valeurs des paramètres des buffers respectifs via mysql_bind_param() .

Dans le cas où la requête est une commande SELECT, ou toute autre commande qui retourne un résultat, alors mysql_prepare() va aussi retourner les méta données de résultat sous la forme d'une structure MYSQL_RES avec mysql_prepare_result() .

Vous pouvez fournir les buffers de résultat avec mysql_bind_result() , pour que mysql_fetch() lise automatiquement les résultats dans les buffers. Cela est fait ligne par ligne.

Vous pouvez aussi envoyer le texte ou les données binaires par parties, au serveur, avec mysql_send_long_data() , en spécifiant l'option is_long_data=1 ou length=MYSQL_LONG_DATA ou -2 dans la structure MYSQL_BIND fournie avec mysql_bind_param() .

Une fois que l'exécution de la commande est terimée, elle doit être supprimée avec mysql_stmt_close pour que toute les ressources allouées soient détruites.

Etapes d'exécution :

Pour préparer et exécuter une commande, l'application :
  • appelle mysql_prepare() et passe une chaîne contenant la commande SQL. Si la préparation réussi, mysql_prepare() retourne un pointeur de commande valide.
  • Si la requête a un résultat, alors mysql_prepare_result retourne les méta informations de résultat.
  • spécifie les valeurs de tous les paramètres de mysql_bind_param . Tous les paramètres doivent être fournis, sinon, cela générera une erreur, ou engendrera des résultats inattendus.
  • appelle mysql_execute() pour exécuter la requête.
  • Répète les étapes 2 et 3 autant que nécessaire, en modifiant les valeurs des paramètres, et en ré-exécutant la commande.
  • Lie les buffers de données aux lignes de résultat, si la commande génère un résultat, en utilisant mysql_bind_result() .
  • Lit les données dans les buffers, ligne par ligne, en appelant mysql_fetch() jusqu'à ce qu'il n'y ait plus de lignes.
Lorsque mysql_prepare() est appelé, dans le protocole client/serveur MySQL :
  • Le serveur analyse la requête et envoie le statut OK au client en lui assignant un identifiant de commande. Il renvoie aussi le nombre total de paramètres, le nombre de colonnes et des métas informations si un résultat est attendu. La syntaxe et la sémantique de la requête sont vérifiés durant cet appel.
  • Le client utilise cet identifiant de commande pour les exécutions ultérieures, pour que le serveur identifie la commande dans le pool de commandes. Désormais, le client alloue un pointeur de commande avec cet identifiant, et le retourne à l'application.
Lorsque mysql_execute() est appelé, avec le protocole client/serveur MySQL :
  • Le client utilise le pointeur de comande et envoie les paramètres au serveur.
  • Le serveur identifie la commane en utilisant l'identifiant, et remplace les marqueurs de paramètres par leur valeur, puis il exécute la requête. Si cela conduit à un résultat, il est retourné au client, ou bien un statut OK, indiquant le nombre total de ligne affecté est retourné.
Lorsque mysql_fetch() est appelé, dans le protocole client/serveur MySQL :
  • Le client lit les données dans le paquet, ligne par ligne, et les place dans les buffers de données, avec les conversions nécessaires. Si le type de buffer de l'application est le même que le type de champs, alors les conversions sont immédiates.

Vous pouvez lire les codes et messages d'erreurs, ansi que les codes d'erreur SQLSTATE avec les fonctions mysql_stmt_errno() , mysql_stmt_error() et mysql_stmt_sqlstate() , respectivement.

<< C API Prepared Statement Function Overview >>
Types de données de l'API C API MySQL C Descriptions des fonctions C pour les requêtes préparées