Présentation des fonctions de l'interface C

Présentation des fonctions de l'interface C

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
->Présentation des fonctions de l'interface C
. Descriptions des fonctions C pour les requêtes préparées
. Gestion des commandes multiples avec l'interface C
. Gestion des dates et horaires avec l'interface C
. Description des fonctions threadées de C
. Description des fonctions C du serveur embarqué
. Questions courantes sur la bibliothèque C
. Compiler les clients
. Comment faire un client MySQL threadé
. libmysqld , la bibliothèque du serveur embarqué MySQL

21.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 Description des fonctions C de commandes 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. Description des fonctions C de commandes 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() . 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 :

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 exécutant à nouveau 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 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.

<<	Présentation des fonctions de l'interface C	>>
Types de données de l'API C	API MySQL C	Descriptions des fonctions C pour les requêtes préparées