Initialement, l'API C de MySQL a été développée pour être très similaire à celle du serveur mSQL. A cause de cela, les programmes mSQL peuvent souvent être convertis facilement à utiliser MySQL, en changeant simplement les noms de l'API C.

L'utilitaire msql2mysql fait cette conversion, et transforme les appels C mSQL en leurs équivalents MYSQL.

msql2mysql convertit le fichier sur place : il est recommandé de faire une copie avant de lancer la conversion. Par exemple, utilisez msql2mysql comme ceci :

shell> cp client-prog.c client-prog.c.orig

shell> msql2mysql client-prog.c

client-prog.c converted

Puis, examinez le fichier client-prog.c et faites toutes les modifications post-conversion nécessaires.

msql2mysql utilise l'utilitaire replace pour faire les substitutions. See Section 8.13, « L'utilitaire de remplacement de chaînes replace ».

mysql_config vous indique des informations pratiques pour compiler votre client MySQL et le connecter au serveur.

mysql_config supporte les options suivantes :

Si vous exécutez mysql_config sans aucune option, il va afficher toutes les options qu'il supporte, ainsi que la valeur de toutes les options :

shell> mysql_config

Usage: /usr/local/mysql/bin/mysql_config [options]

Options:

  --cflags         [-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]

  --include        [-I/usr/local/mysql/include/mysql]

  --libs           [-L/usr/local/mysql/lib/mysql -lmysqlclient -lz

                    -lcrypt -lnsl -lm -L/usr/lib -lssl -lcrypto]

  --libs_r         [-L/usr/local/mysql/lib/mysql -lmysqlclient_r

                    -lpthread -lz -lcrypt -lnsl -lm -lpthread]

  --socket         [/tmp/mysql.sock]

  --port           [3306]

  --version        [4.0.16]

  --libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld -lpthread -lz

                    -lcrypt -lnsl -lm -lpthread -lrt]

Vous pouvez utiliser mysql_config dans une ligne de commande pour inclure la valeur qui sera affichée par une option. Par exemple, pour compiler un client MySQL, utilisez mysql_config comme ceci :

CFG=/usr/local/mysql/bin/mysql_config

sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`"

Lorsque vous utilisez mysql_config de cette manière, assurez vous de l'invoquer entre des guillemets obliques (‘`’). Cela indique que le Shell doit exécuter cette expression, et remplacer le résultat dans la commande.

La structure MYSQL_FIELD contient les membres listés ici :

Les fonctions disponibles dans l'API C sont listées ici et décrites en plus de détails dans la section suivante. See Section 24.2.3, « Description des fonctions de l'API C ».

Pour vous connecter au serveur, appelez mysql_init() pour initialiser un gestionnaire de connexion, puis appelez mysql_real_connect() avec ce gestionnaire (avec d'autres informations tel que l'hôte, l'utilisateur et le mot de passe). Lors de la connexion, mysql_real_connect() définit l'option reconnect (quit fait partie de la structure MYSQL) à 1. Cette option indique, dans le cas où une requête ne peut être exécutée à cause d'une perte de connexion, d'essayer de se reconnecter au serveur avant d'abandonner. Lorsque vous n'avez plus besoin de la connexion, appelez mysql_close() pour la clore.

Tant qu'une connexion est active, le client envoi des requêtes SQL au serveur à l'aide de mysql_query() ou mysql_real_query(). La différence entre les deux est que mysql_query() s'attend à ce que la requête soit spécifiée en tant que chaîne terminée par la chaîne nulle, tandis que mysql_real_query() attend une chaîne de longueur connue. Si la chaîne contient des données binaires (incluant l'octet nul), vous devez utiliser mysql_real_query().

Pour chaque requête non-sélective (par exemple, INSERT, UPDATE, DELETE), vous pouvez trouver combien de lignes ont été mises à jour (affectées) en appelant mysql_affected_rows().

Pour les requêtes SELECT, vous récupérez les lignes sélectionnées dans un jeu de résultat. (Notez que quelques commandes ont le même comportement que SELECT, dans le sens où elle renvoient des lignes. Cela inclut SHOW, DESCRIBE, et EXPLAIN. Elles doivent être traitées de la même fa¸on que les requêtes SELECT.)

Il y a deux fa¸ons pour un client de gérer les jeux de résultats. Une méthode consiste à récupérer le jeu de résultat en entier et en une seule fois en appelant mysql_store_result(). Cette fonction obtient toutes les lignes retournées par la requête et les stocke dans le client. La seconde méthode consiste à initialiser une récupération ligne par ligne du jeu de résultats en appelant mysql_use_result(). Cette fonction initie la récupération, mais ne récupère actuellement aucune ligne à partir du serveur.

Dans les deux cas, vous accédez aux ligne en appelant mysql_fetch_row(). Avec mysql_store_result(), mysql_fetch_row() accède aux lignes qui ont déjà été récupérées à partir du serveur. Avec mysql_use_result(), mysql_fetch_row() récupère actuellement la ligne à partir du serveur. Les informations à propos de la taille des données dans chaque ligne est disponible en appelant mysql_fetch_lengths().

Après avoir fini de traiter le jeu de résultats, appelez mysql_free_result() pour libérer la mémoire utilisée.

Les deux mécanismes de récupération sont complémentaires. Les programmes clients doivent utiliser l'approche qui leur convient le mieux. En pratique, les clients tendent plus à utiliser mysql_store_result().

Un avantage de mysql_store_result() est que puisque toutes les lignes ont été récupérées dans le client, vous ne pouvez pas que accéder aux lignes séquentiellement, vous pouvez revenir en arrière ou avancer dans le jeu de résultats en utilisant mysql_data_seek() ou mysql_row_seek() pour changer la position de la ligne courante dans le jeu de résultats. Vous pouvez aussi trouver le nombre total des lignes en appelant mysql_num_rows(). D'un autre côté, les besoins en mémoire de mysql_store_result() peuvent être très grands pour les grands jeux de résultats et vous aurez des chances d'obtenir un manque de mémoire.

Un avantage de mysql_use_result() est que le client a besoin de moins de mémoire pour le jeu de résultats car il utilise une ligne à la fois (et puisque il y a moins de pertes de mémoire, mysql_use_result() peut être plus rapide). Les inconvénients sont que vous devez récupérer chaque ligne rapidement pour éviter de bloquer le serveur, vous n'avez pas d'accès aléatoires aux lignes dans le jeu de résultats (vous ne pouvez accéder aux lignes que séquentiellement), et vous ne savez pas combien de lignes comporte le jeu de résultats tant que vous ne les avez pas toutes récupérées. De plus, vous devez récupérer toutes les lignes même si vous trouvez entre-temps l'informations que vous cherchiez.

L'API permet aux clients de gérer correctement les requêtes (récupérant les lignes seulement en cas de besoin) sans savoir si la requête était un SELECT ou non. Vous pouvez faire cela en appelant mysql_store_result() après chaque mysql_query() (ou mysql_real_query()). Si l'appel au jeu de résultats réussi, la requête était un SELECT et vous pouvez lire les lignes. Sinon, appelez mysql_field_count() pour vérifier si un résultat aurait du être retourné. Si mysql_field_count() retourne zéro, la requête n'a pas retourné de données (cela indique que c'était un INSERT, UPDATE, DELETE, etc.), et ne devait pas retourner de lignes. Si mysql_field_count() est non-nul, la requête aurait du retourner des lignes, mais ne l'a pas fait. Cela indique que la requête était un SELECT qui a échoué. Reportez vous à la description de mysql_field_count() pour un exemple d'utilisation.

mysql_store_result() et mysql_use_result() vous permettent d'obtenir des informations à propos des champs qui constituent le jeu de résultat (le nombre de champs, leurs noms et types, etc.). Vous pouvez accéder aux informations du champ séquentiellement dans une ligne en appelant plusieurs fois mysql_fetch_field(), ou avec le numéro du champ dans la ligne en appelant mysql_fetch_field_direct(). La position courante du pointeur de champ peut être changée en appelant mysql_field_seek(). Changer le pointeur de champ affecte les appels suivants à mysql_fetch_field(). Vous pouvez aussi obtenir en une seule fois les informations sur les champs en appelant mysql_fetch_fields().

Pour détecter les erreurs, MySQL fournit un accès aux informations des erreurs via les fonctions mysql_errno() et mysql_error(). Elles retournent le code de l'erreur et le message pour la dernière fonction invoquée qui aurait pu réussir ou échouer, vous permettant ainsi de déterminer les erreurs et leurs causes.

Dans les descriptions suivantes, un paramètre ou retour de fonction NULL correspond au NULL dans le sens C du terme, et non dans le sens de la valeur NULL de MySQL.

Les fonctions qui retournent une valeur retournent la plupart du temps un pointeur ou un entier. Sauf en cas d'indications contraires, les fonctions retournant un pointeur retournent une valeur non-NULL pour indiquer un succès ou une valeur NULL pour indiquer une erreur, les fonctions retournant un entier retournent zéro pour indiquer un succès et une valeur non-nulle en cas d'erreur. Notez que ``non-nulle'' ne signifie rien de plus que cela. Sauf si la description de la fonction le dit, ne testez pas avec une valeur différente de zéro :

if (result)                   /* correct */

    ... erreur ...



if (result < 0)               /* incorrect */

    ... erreur ...



if (result == -1)             /* incorrect */

    ... erreur ...

Lorsqu'une fonction retourne une erreur, la section Erreurs du