Skip navigation links
MySQL 5.0 Reference Manual :: 24 API MySQL :: 24.2 API MySQL C :: 24.2.6 Présentation des fonctions de l'interface C
24.2.7 Description des fonctions C pour les requêtes préparées »
Section Navigation      [Toggle]

24.2.6. Présentation des fonctions de l'interface C

Note : les fonctions pour les commandes préparées est toujours en cours de développement. Les informations de cette section sont destinées aux premiers utilisateurs mais il faut être conscient que l'API peut changer. Certains changements sont incompatibles avec MySQL 4.1.2. Voyez Section 24.2.7, « Description des fonctions C pour les requêtes préparées » pour plus de détails.

Voici les fonctions disponibles pour les commandes préparées. Elles sont listées ici et détailles plus loin. See Section 24.2.7, « Description des fonctions C pour les requêtes préparées ».

Fonction Description
mysql_stmt_init() Alloue la mémoire pour une structure MYSQL_STMT et l'initialise.
mysql_stmt_bind_param() Associe un buffer avec une variable de requêtes, dans une commande préparée.
mysql_stmt_bind_result() Lie les buffers de l'application avec les colonnes d'un résultat.
mysql_stmt_execute() Exécute une commande préparée.
mysql_stmt_fetch() Lit la prochaine ligne de données dans le résultat, et retourne toutes les données des colonnes liées.
mysql_stmt_fetch_column() Lit les données d'une seule colonne, dans le résultat.
mysql_stmt_result_metadata() Retourne les meta-données de la commande préparée, sous forme d'un jeu de résultat.
mysql_stmt_param_count() Retourne le nombre de paramètres d'une commande préparée.
mysql_stmt_param_metadata() Retourne les meta-données des paramètres, sous forme d'un jeu de résultat.
mysql_stmt_prepare() Prépare une chaîne SQL pour l'exécution.
mysql_stmt_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_insert_id() Retourne l'identifiant généré par la colonne AUTO_INCREMENT de la dernière commande préparée.
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 message 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 lignes 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 valeur 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.
mysql_stmt_attr_set() Modifie un attribut d'une commande préparée.
mysql_stmt_attr_get() Lit la valeur d'un attribut d'une commande préparée.

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éter mysql_execute() en modifiant 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 au serveur en utilisant la fonction mysql_stmt_send_long_data(). See Section 24.2.7.25, « mysql_stmt_send_long_data() ».

Une fois que l'exécution de la commande est terminé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 :

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

  2. Si la requête a un résultat, alors mysql_prepare_result retourne les méta informations de résultat.

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

  4. appelle mysql_execute() pour exécuter la requête.

  5. Répète les étapes 2 et 3 autant que nécessaire, en modifiant les valeurs des paramètres, et en exécutant à nouveau la commande.

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

  7. 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 meta-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 commande et envoie les paramètres au serveur.

  • Le serveur identifie la commande 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'erreur, ansi que les codes d'erreur SQLSTATE avec les fonctions mysql_stmt_errno(), mysql_stmt_error() et mysql_stmt_sqlstate(), respectivement.

This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.