IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)

Manuel de référence MySQL 5.0


précédentsommairesuivant

24. API MySQL

Ce chapitre décrit les interfaces disponibles pour MySQL, où les trouver, et comment les utiliser. L'API C est celle qui est couverte le plus en détail, puisqu'elle est développée par l'équipe MySQL, et sert de base à toutes les autres API.

24-A. Utilitaires de développement des programmes MySQL

Cette section décrit certains utilitaires que vous pouvez trouver utiles, lors du développement de programmes MySQL.

  • msql2mysql
    Un script Shell qui convertit un programme mSQL en MySQL. Il ne gère pas toutes les situations, mais c'est un bon début.
  • mysql_config
    Un script Shell qui produit les options nécessaires lors de la compilation de programmes MySQL.

24-A-1. msql2mysql, convertit des programmes mSQL vers MySQL

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

L'utilitaire msql2mysql fait cette conversion, et transforme les appels C mSQL en leur équivalent 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 :

 
Sélectionnez
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 postconversions nécessaires.

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

24-A-2. mysql_config lit les options de compilations du client MySQL

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

mysql_config supporte les options suivantes :

  • --cflags
    Options de compilation utilisées pour trouver les fichiers inclus.
  • --include
    Options du compilateur pour trouver les fichiers d'inclusion MySQL. (Normalement, il faut utiliser --cflags au lieu de cette commande.)
  • --libs
    Les bibliothèques et options requises pour compiler avec la bibliothèque client MySQL.
  • --libs_r
    Les bibliothèques et options requises pour la compilation avec la sécurité thread de la bibliothèque client MySQL.
  • --socket
    Le nom par défaut de la socket, défini lors de la configuration de MySQL.
  • --port
    Le numéro de port par défaut, défini lors de la configuration de MySQL.
  • --version
    Le numéro de version et la version de la distribution MySQL.
  • --libmysqld-libs
    Les bibliothèques et options requises pour compiler avec la bibliothèque intégrée MySQL.

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 :

 
Sélectionnez
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 :

 
Sélectionnez
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.

24-B. API MySQL C

L'interface C est distribuée avec MySQL. Elle est incluse dans la bibliothèque mysqlclient et permet aux programmes écrits en C d'accéder à la base de données.

De nombreux clients de la distribution source de MySQL sont écrits en C. Si vous recherchez des exemples d'illustration de l'utilisation de l'interface C, étudiez donc ces clients. Vous pouvez les trouver dans le dossier clients de la distribution source MySQL.

La plupart des autres interfaces clientes (sauf Connector/J) utilisent la bibliothèque mysqlclient pour communiquer avec le serveur MySQL. Cela signifie que, par exemple, vous pouvez exploiter adroitement de nombreuses autres variables qui sont utilisées par les autres programmes clients, car elles sont utilisées dans la bibliothèque. Voyez Chapitre 8, MySQL Scripts clients et utilitairesChapitre 8. MySQL Scripts clients et utilitaires, pour une liste de ces variables.

Le client a une taille maximale de buffer de communication. La taille du buffer qui est allouée au lancement 16 ko bytes, est automatiquement augmentée jusqu'à la taille maximum de 16 Mo. Comme la taille du buffer croît à la demande, vous ne consommerez pas de ressources supplémentaires en augmentant la limite maximum par défaut. Cette limite sert surtout à s'assurer de bien identifier des problèmes de requêtes erronées ou des paquets de communication.

Le buffer de communication doit être assez grand pour contenir une commande SQL complète (dans le sens du trafic allant vers le serveur), et une ligne complète (dans le sens du trafic allant vers le client). Chaque buffer de threads est dynamiquement agrandi pour gérer les requêtes jusqu'à la taille limite. Par exemple, si vous avez des valeurs de type BLOB qui contient jusqu'à 16 Mo de données, vous devez avoir un buffer de communication dont la limite doit être au minimum de 16 Mo, aussi bien sur le serveur que sur le client. La limite par défaut sur le client est de 16 Mo, mais elle est de 1 Mo sur le serveur. Vous pouvez augmenter cette valeur en modifiant le paramètre max_allowed_packet lorsque le serveur est lancé. Voir Section 7.5.2, « Réglage des paramètres du serveur »7.5.2. Réglage des paramètres du serveur.

Le serveur MySQL réduit la taille des buffers de communication à net_buffer_length octets après chaque requête. Pour les clients, le buffer est associé à une connexion, et les ressources ne seront libérées que lorsque cette dernière sera refermée.

Pour la programmation avec les threads, voyez la section Section 24.2.15, « Comment faire un client MySQL threadé »24.2.15. Comment faire un client MySQL threadé. Pour la création d'applications qui incluent le serveur et le client dans le même programme, et ne communiquent avec aucun serveur externe, voyez Section 24.2.16, « libmysqld, la bibliothèque du serveur embarqué MySQL »24.2.16. libmysqld, la bibliothèque du serveur embarqué MySQL.

24-B-1. Types de données de l'API C

  • MYSQL
    Cette structure représente un gestionnaire de connexions à la base de données. Elle est utilisée dans la plupart des fonctions MySQL.
  • MYSQL_RES
    Cette structure représente le résultat d'une requête qui retourne des lignes (SELECT, SHOW, DESCRIBE, EXPLAIN). L'information retournée par une requête est appelée jeu de résultats dans le reste de cette section.
  • MYSQL_ROW
    C'est une représentation sûre pour les types d'une ligne de données. Elle est actuellement implémentée en tant que tableau de chaînes à octets comptés. (Vous ne pouvez la traiter en tant que chaîne terminée par une valeur nulle, si les valeurs du champ peuvent contenir des données binaires, car de telles valeurs peuvent contenir elles-mêmes des octets nuls.) Les lignes sont obtenues en appelant mysql_fetch_row().
  • MYSQL_FIELD
    Cette structure contient des informations à propos du champ, telles que son nom, son type, et sa taille. Ses membres sont décrits en plus de détail ici. Vous pouvez obtenir une structure MYSQL_FIELD pour chaque champ en appelant plusieurs fois mysql_fetch_field(). Les valeurs des champs ne font pas partie de la structure, elles sont contenues dans une structure MYSQL_ROW.
  • MYSQL_FIELD_OFFSET
    C'est une représentation sûre des types pour les index dans une liste de champs MySQL. (Utilisés par mysql_field_seek().) Les index sont des numéros de champs, dans une ligne, commençant à zéro.
  • my_ulonglong
    Le type utilisé pour le nombre de lignes et pour mysql_affected_rows(), mysql_num_rows(), et mysql_insert_id(). Ce type fournit une échelle allant de 0 à 1.84e19.
    Sur quelques systèmes, essayer d'écrire la valeur d'un type my_ulonglong ne fonctionnera pas. Pour écrire une telle valeur, convertissez-la en unsigned long et utilisez un format d'impression %lu. Exemple :
 
Sélectionnez
printf ("Nombre de lignes : %lu\n", (unsigned long) mysql_num_rows(result));

La structure MYSQL_FIELD contient les membres listés ici :

  • char * name
    Le nom du champ, une chaîne terminée par une valeur nulle.
  • char * table
    Le nom de la table contenant ce champ, s'il n'est pas calculé. Pour les champs calculés, la valeur de table est une chaîne vide.
  • char * def
    La valeur par défaut de ce champ, en tant que chaîne terminée par une valeur nulle. Ce n'est défini que si vous utilisez mysql_list_fields().
  • enum enum_field_types type
    Le type du champ. La valeur de type peut être l'une des suivantes :

    Valeur de type

    Description du type

    FIELD_TYPE_TINY

    Champ TINYINT

    FIELD_TYPE_SHORT

    Champ SMALLINT

    FIELD_TYPE_LONG

    Champ INTEGER

    FIELD_TYPE_INT24

    Champ MEDIUMINT

    FIELD_TYPE_LONGLONG

    Champ BIGINT

    FIELD_TYPE_DECIMAL

    Champ DECIMAL ou NUMERIC

    FIELD_TYPE_FLOAT

    Champ FLOAT

    FIELD_TYPE_DOUBLE

    Champ DOUBLE ou REAL

    FIELD_TYPE_TIMESTAMP

    Champ TIMESTAMP

    FIELD_TYPE_DATE

    Champ DATE

    FIELD_TYPE_TIME

    Champ TIME

    FIELD_TYPE_DATETIME

    Champ DATETIME

    FIELD_TYPE_YEAR

    Champ YEAR

    FIELD_TYPE_STRING

    Champ chaîne de caractères (CHAR ou VARCHAR)

    FIELD_TYPE_VAR_STRING

    Champ VARCHAR

    FIELD_TYPE_BLOB

    Champ BLOB ou TEXT (utilisez max_length pour déterminer la taille maximale)

    FIELD_TYPE_SET

    Champ SET

    FIELD_TYPE_ENUM

    Champ ENUM

    FIELD_TYPE_NULL

    Champ de type NULL

    FIELD_TYPE_CHAR

    Désapprouvé, utilisez FIELD_TYPE_TINY à la place

    Vous pouvez utiliser la macro IS_NUM() pour tester si un champ est de type numérique ou non. Passez la valeur de type à IS_NUM() et elle sera évaluée à TRUE si le champ est numérique :

     
    Sélectionnez
    if (IS_NUM(field->type))
        printf("Le champ est numérique\n");
  • unsigned int length
    La taille du champ, comme spécifié dans la définition de la table.

  • unsigned int max_length
    La longueur maximale du champ pour le jeu de résultats (la taille de la plus longue valeur de champ actuellement dans le jeu de résultat). Si vous utilisez mysql_store_result() ou mysql_list_fields(), cela contient la longueur maximale pour le champ. Si vous utilisez mysql_use_result(), la valeur de cette variable est zéro.

  • unsigned int flags
    Les différents attributs sous forme de bits pour le champ. La valeur de flags peut avoir zéro ou plusieurs de ces bits suivants activés :

    Valeur d'attribut

    Description d'attribut

    NOT_NULL_FLAG

    Le champ ne peut être NULL

    PRI_KEY_FLAG

    Le champ fait partie d'une clef primaire

    UNIQUE_KEY_FLAG

    Le champ fait partie d'une clef unique

    MULTIPLE_KEY_FLAG

    Le champ fait partie d'une clef non unique

    UNSIGNED_FLAG

    Le champ possède l'attribut UNSIGNED

    ZEROFILL_FLAG

    Le champ possède l'attribut ZEROFILL

    BINARY_FLAG

    Le champ possède l'attribut BINARY

    AUTO_INCREMENT_FLAG

    Le champ possède l'attribut AUTO_INCREMENT

    ENUM_FLAG

    Le champ est un ENUM (désapprouvé)

    SET_FLAG

    Le champ est un SET (désapprouvé)

    BLOB_FLAG

    Le champ est un BLOB ou TEXT (désapprouvé)

    TIMESTAMP_FLAG

    Le champ est un TIMESTAMP (désapprouvé)

    L'utilisation des attributs BLOB_FLAG, ENUM_FLAG, SET_FLAG, et TIMESTAMP_FLAG est désapprouvé, car ils indiquent un type de champ plutôt qu'un attribut de type de champ. Il est préférable de tester field->type avec FIELD_TYPE_BLOB, FIELD_TYPE_ENUM, FIELD_TYPE_SET, ou FIELD_TYPE_TIMESTAMP à la place.

    L'exemple suivant illustre une utilisation typique de la valeur de flags :

     
    Sélectionnez
    if (field->flags & NOT_NULL_FLAG)
        printf("Le champ ne peut être nul\n");

    Vous pouvez utiliser les différentes macros ci-dessous pour déterminer le statut booléen de la valeur de l'attribut :

    Statut de l'attribut

    Description

    IS_NOT_NULL(flags)

    Vrai si le champ est défini en tant que NOT NULL

    IS_PRI_KEY(flags)

    Vrai si le champ est une clef primaire

    IS_BLOB(flags)

    Vrai si le champ est un BLOB ou TEXT (désapprouvé, testez plutôt field->type)

  • unsigned int decimals
    Le nombre de décimales pour les champs numériques.

24-B-2. Vue d'ensemble des fonctions de l'API C

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

Fonction

Description

mysql_affected_rows()

Retourne le nombre de lignes changées/effacées/insérées par le dernier UPDATE, DELETE, ou INSERT.

mysql_change_user()

Change l'utilisateur et la base de données pour une connexion ouverte.

mysql_character_set_name()

Retourne le nom du jeu de caractères de la connexion.

mysql_close()

Ferme une connexion au serveur.

mysql_connect()

Connecte à un serveur MySQL. Cette fonction est désapprouvée, utilisez mysql_real_connect() à la place.

mysql_create_db()

Crée une base de données. Cette fonction est désapprouvée, utilisez plutôt la commande SQL CREATE DATABASE.

mysql_data_seek()

Déplace le pointeur vers une ligne arbitraire dans le jeu de résultats de la requête.

mysql_debug()

Effectue un DBUG_PUSH avec la chaîne donnée.

mysql_drop_db()

Supprime une base de données. Cette fonction est désapprouvée, utilisez plutôt la commande SQL DROP DATABASE.

mysql_dump_debug_info()

Demande au serveur d'écrire les informations de débogage dans un fichier de log.

mysql_eof()

Détermine si la dernière ligne du jeu de résultats a été lue ou non. Cette fonction est désapprouvée, vous pouvez utiliser mysql_errno() ou mysql_error() à la place.

mysql_errno()

Retourne le numéro de l'erreur de la fonction appelée en dernier.

mysql_error()

Retourne le message d'erreur de la dernière fonction MySQL appelée.

mysql_escape_string()

Protège une chaîne en échappant les caractères spéciaux.

mysql_fetch_field()

Retourne le type du champ suivant dans la table.

mysql_fetch_field_direct()

Retourne le type d'une colonne, étant donné un numéro de champ.

mysql_fetch_fields()

Retourne un tableau avec toutes les structures de champs.

mysql_fetch_lengths()

Retourne la longueur de toutes les colonnes dans la ligne suivante.

mysql_fetch_row()

Récupère la ligne suivante dans le jeu de résultats.

mysql_field_seek()

Place le curseur de colonne sur une colonne précise.

mysql_field_count()

Retourne le nombre de colonnes dans le résultat pour la requête la plus récente.

mysql_field_tell()

Retourne la position du curseur de champs utilisé pour le dernier appel à mysql_fetch_field().

mysql_free_result()

Libère la mémoire utilisée par un jeu de résultats.

mysql_get_client_info()

Retourne la version du client sous forme de chaîne.

mysql_get_client_version()

Retourne la version du client sous forme d'entier.

mysql_get_host_info()

Retourne une chaîne décrivant la connexion.

mysql_get_server_version()

Retourne le numéro de version du serveur sous forme d'entier (nouveau en 4.1).

mysql_get_proto_info()

Retourne la version du protocole utilisé par la connexion.

mysql_get_server_info()

Retourne la version du serveur.

mysql_info()

Retourne des informations à propos de la requête la plus récente.

mysql_init()

Récupère ou initialise une structure MYSQL.

mysql_insert_id()

Retourne l'identifié généré pour une colonne AUTO_INCREMENT par la dernière requête.

mysql_kill()

Termine un processus donné.

mysql_list_dbs()

Retourne les noms des bases de données répondant à une expression régulière simple.

mysql_list_fields()

Retourne les noms des champs répondant à une expression régulière simple.

mysql_list_processes()

Retourne une liste des processus courants du serveur.

mysql_list_tables()

Retourne les noms des tables répondant à une expression régulière simple.

mysql_num_fields()

Retourne le nombre de colonnes dans un jeu de résultats.

mysql_num_rows()

Retourne le nombre de lignes dans le jeu de résultats.

mysql_options()

Configure les options de connexion pour mysql_connect().

mysql_ping()

Vérifie si la connexion au serveur a toujours lieu. Reconnecte si besoin.

mysql_query()

Exécute une requête SQL spécifiée en tant que chaîne terminée par un caractère nul.

mysql_real_connect()

Connecte à un serveur MySQL.

mysql_real_escape_string()

Protège les caractères spéciaux dans une chaîne utilisable dans une requête SQL, en prenant en compte le jeu de caractères courant de la connexion.

mysql_real_query()

Exécute une requête SQL spécifiée en tant que chaîne comptée.

mysql_reload()

Demande au serveur de recharger la table des droits.

mysql_row_seek()

Déplace le pointeur vers une ligne dans le jeu de résultats, en utilisant une valeur retournée par mysql_row_tell().

mysql_row_tell()

Retourne la position du curseur de lignes.

mysql_select_db()

Sélectionne une base de données.

mysql_set_server_option()

Spécifie la valeur d'une option pour la connexion (comme multi-statements).

mysql_sqlstate()

Retourne l'erreur SQLSTATE de la dernière erreur.

mysql_shutdown()

Termine le serveur de base de données.

mysql_stat()

Retourne le statut du serveur dans une chaîne.

mysql_store_result()

Récupère le jeu de résultats complet dans le client.

mysql_thread_id()

Retourne l'identifiant du thread courant.

mysql_thread_safe()

Retourne 1 si le client est compilé avec la sécurité thread.

mysql_use_result()

Initialise une récupération ligne par ligne des résultats.

mysql_warning_count()

Retourne le nombre d'alertes générées par la dernière commande SQL.

mysql_commit()

Valide une transaction (nouveau en 4.1).

mysql_rollback()

Annule une transaction (nouveau en 4.1).

mysql_autocommit()

Active et désactive le mode d'autovalidation (nouveau en 4.1).

mysql_more_results()

Vérifie s'il n'y a plus de résultats (nouveau en 4.1).

mysql_next_result()

Retourne/initie le prochain résultat dans une commande multirequête (nouveau en 4.1).

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 telles 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 envoie 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ù elles 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ésultats 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 lignes 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 sont disponibles 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 puisqu'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'information 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éussit, 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 dû ê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 dû 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, leur nom et type, 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.

24-B-3. Description des fonctions de l'API C

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 :

 
Sélectionnez
if (result)                   /* correct */
    ... erreur ...

if (result < 0)               /* incorrect */
    ... erreur ...

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

Lorsqu'une fonction retourne une erreur, la section Erreurs du descriptif de la fonction liste les types d'erreurs possibles. Vous pouvez trouver celle qui est arrivée en appelant mysql_errno(). Une chaîne de caractères représentant l'erreur peut être obtenue en appelant mysql_error().

24-B-3-a. mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

Description

Retourne le nombre de lignes modifiées par la dernière commande UPDATE, supprimées par la dernière commande DELETE ou insérées par la dernière commande INSERT. Peut être appelée immédiatement après mysql_query() pour les commandes UPDATE, DELETE, ou INSERT. Pour la commande SELECT, mysql_affected_rows() fonctionne comme mysql_num_rows().

Valeur de retour

Un entier supérieur à zéro indique le nombre de lignes affectées ou sélectionnées. Zéro indique qu'aucun enregistrement n'a été mis à jour pour une requête UPDATE, qu'aucune ligne n'a correspondu à la clause WHERE dans la requête ou que celle-ci n'a pas encore été exécutée. -1 indique que la requête a renvoyé une erreur ou que, pour une requête SELECT, mysql_affected_rows() a été appelée avant mysql_store_result(). Comme mysql_affected_rows() retourne une valeur non signée, vous pouvez comparer avec -1 en comparant la valeur retournée par (my_ulonglong)-1 (ou par (my_ulonglong)~0, ce qui est la même chose).

Erreurs

Aucune.

Exemple

 
Sélectionnez
mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%ld produits mis à jour",(long) mysql_affected_rows(&mysql));

Si on spécifie l'option CLIENT_FOUND_ROWS en se connectant à mysqld, mysql_affected_rows() retournera le nombre d'enregistrements correspondant à la clause WHERE pour une requête UPDATE.

Notez que quand on utilise une commande REPLACE, mysql_affected_rows() retournera 2 si le nouvel enregistrement en a remplacé un ancien. 2 en retour, car dans ce cas, l'ancienne ligne a été supprimée puis la nouvelle insérée.

24-B-3-b. mysql_change_user()

my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

Description

Change l'utilisateur et définit la base de données spécifiée par db en tant que base de données par défaut (courante) dans la connexion spécifiée par mysql. Pour les requêtes suivantes, cette base de données sera celle utilisée pour les références aux tables ne spécifiant pas explicitement une base de données.

Cette fonction a été introduite à la version 3.23.3 de MySQL.

mysql_change_user() échoue si l'utilisateur ne peut être authentifié ou s'il n'a pas le droit d'utiliser cette base de données. Dans ce cas, l'utilisateur et la base de données ne sont pas changés.

Le paramètre db peut être mis à NULL si vous ne voulez pas avoir de base de données par défaut.

Valeur de retour

Zéro en cas de succès. Différent de zéro si une erreur se produit.

Erreurs

Les mêmes que vous pouvez obtenir avec mysql_real_connect().

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
  • ER_UNKNOWN_COM_ERROR
    Le serveur MySQL n'implémente pas cette commande (probablement un ancien serveur)
  • ER_ACCESS_DENIED_ERROR
    L'utilisateur ou le mot de passe étaient erronés.
  • ER_BAD_DB_ERROR
    La base de données n'existe pas.
  • ER_DBACCESS_DENIED_ERROR
    L'utilisateur n'a pas le droit d'accéder à la base de données.
  • ER_WRONG_DB_NAME
    Le nom de la base de données était trop long.

Exemple

 
Sélectionnez
if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
   fprintf(stderr, "Impossible de changer d'utilisateur.  Erreur : %s\n",
           mysql_error(&mysql));
}
24-B-3-c. mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

Description

Retourne le jeu de caractères par défaut de la connexion courante.

Valeur de retour

Le jeu de caractères par défaut

Erreurs

Aucune.

24-B-3-d. mysql_close()

void mysql_close(MYSQL *mysql)

Description

Ferme la connexion ouverte précédemment. mysql_close() libère aussi le pointeur de connexion mysql, si celui-ci avait été alloué dynamiquement par mysql_init() ou mysql_connect().

Valeur de retour

Aucune.

Erreurs

Aucune.

24-B-3-e. mysql_connect()

MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

Description

Cette fonction est désapprouvée. Il est préférable d'utiliser mysql_real_connect() à la place.

mysql_connect() essaye d'établir une connexion à un serveur MySQL lancé sur host. mysql_connect() doit s'achever avec succès avant que vous ne puissiez exécuter l'une des autres fonctions de l'API, à l'exception de mysql_get_client_info().

La signification des paramètres est la même que pour ceux de la fonction mysql_real_connect() à la différence que le paramètre de connexion peut être NULL. Dans ce cas, l'API C alloue automatiquement une mémoire pour la structure de connexion et la libère quand vous appelez mysql_close(). Le désavantage de cette approche est que vous ne pouvez pas récupérer les messages d'erreur si la connexion échoue. (Pour obtenir des informations sur les erreurs à partir de mysql_errno() ou mysql_error(), vous devez fournir un pointeur MYSQL valide.)

Valeur de retour

La même que pour mysql_real_connect().

Erreurs

Les mêmes que pour mysql_real_connect().

24-B-3-f. mysql_create_db()

int mysql_create_db(MYSQL *mysql, const char *db)

Description

Crée la base de données nommée avec le paramètre db.

Cette fonction est désapprouvée. Il est préférable d'utiliser mysql_query() pour générer une requête SQL CREATE DATABASE à la place.

Valeur de retour

Zéro si la base a été créée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.

Exemple

 
Sélectionnez
if(mysql_create_db(&mysql, "ma_base"))
{
   fprintf(stderr, "Impossible de créer une nouvelle base de données. Erreur : %s\n",
           mysql_error(&mysql));
}
24-B-3-g. mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

Description

Se déplace vers une ligne arbitraire d'un jeu de résultats de requête. Cela nécessite que la structure du jeu de résultats contienne la totalité du résultat de la requête, de ce fait mysql_data_seek() peut être utilisée en conjonction avec mysql_store_result(), mais pas avec mysql_use_result().

L'index de la ligne doit être compris entre 0 et mysql_num_rows(result)-1.

Valeur de retour

Aucune.

Erreurs

Aucune.

24-B-3-h. mysql_debug()

void mysql_debug(const char *debug)

Description

Provoque un DBUG_PUSH avec la chaîne donnée. mysql_debug() utilise la bibliothèque de débogage Fred Fish. Pour utiliser cette fonction vous devez compiler la bibliothèque client avec le support débogage. Voir Section D.1, « Déboguer un serveur MySQL »D.1. Déboguer un serveur MySQL. Voir Section D.2, « Débogage un client MySQL »D.2. Débogage un client MySQL.

Valeur de retour

Aucune.

Erreurs

Aucune.

Exemple

L'appel montré ici fait générer à la bibliothèque du client un fichier de trace dans /tmp/client.trace sur la machine du client :

 
Sélectionnez
mysql_debug("d:t:O,/tmp/client.trace");
24-B-3-i. mysql_drop_db()

int mysql_drop_db(MYSQL *mysql, const char *db)

Description

Supprime la base de données nommée avec le paramètre db.

Cette fonction est désapprouvée. Il est préférable d'utiliser mysql_query() pour générer une requête SQL DROP DATABASE à la place.

Valeur de retour

Zéro si la base a été effacée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.

Exemple

 
Sélectionnez
if(mysql_drop_db(&mysql, "ma_base"))
  fprintf(stderr, "Impossible de supprimer la base de données. Erreur : %s\n",
          mysql_error(&mysql));
24-B-3-j. mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

Description

Demande au serveur d'écrire quelques informations de débogage dans le log. Pour que cela fonctionne, il faut que l'utilisateur ait le droit SUPER.

Valeur de retour

Zéro si la commande a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-k. mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

Description

Cette fonction est désapprouvée. Vous pouvez utiliser mysql_errno() ou mysql_error() à la place.

mysql_eof() détermine si la dernière ligne d'un jeu de résultats a été lue.

Si vous obtenez un jeu de résultats suite à un appel à mysql_store_result(), le client reçoit le jeu entier en une seule opération. Dans ce cas, un retour NULL de la fonction mysql_fetch_row() signifie toujours que la fin du jeu de résultats a été atteinte et il n'est donc pas nécessaire d'appeler mysql_eof(). Lors d'une utilisation avec mysql_store_result(), mysql_eof() retournera toujours true.

D'un autre côté, si vous utilisez mysql_use_result() pour initialiser la récupération d'un jeu de résultats, les lignes sont obtenues du serveur une par une lors des appels successifs de mysql_fetch_row(). Puisqu'une erreur peut survenir à la connexion durant ce processus, une valeur de retour NULL de la part de mysql_fetch_row() ne signifie pas nécessairement que la fin du jeu de résultats a été atteinte normalement. Dans ce cas, vous pouvez utiliser mysql_eof() pour déterminer ce qui est arrivé. mysql_eof() retourne une valeur non nulle si la fin du jeu de résultats a été atteinte et zéro en cas d'erreur.

Historiquement, mysql_eof() a vu le jour avant les fonctions d'erreurs standards de MySQL mysql_errno() et mysql_error(). Puisque ces fonctions fournissent les mêmes informations, leur utilisation est préférée à mysql_eof(), qui est maintenant désapprouvée. (En fait, elles fournissent plus d'informations, car mysql_eof() ne retourne que des valeurs booléennes alors que les fonctions d'erreurs indiquent les raisons des erreurs lorsqu'elles surviennent.)

Valeur de retour

Zéro si aucune erreur n'est survenue. Autre chose dans le cas contraire.

Erreurs

Aucune.

Exemple

L'exemple suivant vous montre comment vous devez utiliser mysql_eof():

 
Sélectionnez
mysql_query(&mysql,"SELECT * FROM une_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
    // traite les données
}
if(!mysql_eof(result))  // mysql_fetch_row() failed due to an error
{
    fprintf(stderr, "Erreur : %s\n", mysql_error(&mysql));
}

Vous pouvez reproduire la même chose avec les fonctions d'erreurs de MySQL :

 
Sélectionnez
mysql_query(&mysql,"SELECT * FROM une_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
    // traite les données
}
if(mysql_errno(&mysql))  // mysql_fetch_row() ne marche pas à cause d'une erreur
{
    fprintf(stderr, "Erreur : %s\n", mysql_error(&mysql));
}
24-B-3-l. mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

Description

Pour la connexion spécifiée par mysql, mysql_errno() retourne le code de l'erreur pour l'appel le plus récent à une fonction de l'API qui peut réussir ou échouer. Un zéro en valeur de retour signifie qu'aucune erreur ne s'est produite. Les codes erreur du client sont listés dans le fichier d'entête MySQL (errmsg.h). Les codes erreur du serveur sont listés dans le fichier mysqld_error.h. Dans les sources de la distribution MySQL vous pouvez trouver la liste complète des messages d'erreur et le code qui leur est associé dans le fichier Docs/mysqld_error.txt. Les codes d'erreur serveur sont listés dans Chapitre 26, Gestion des erreurs avec MySQLChapitre 26. Gestion des erreurs avec MySQL.

Notez que certaines fonctions comme mysql_fetch_row() ne donnent pas de valeur à mysql_errno() si elles réussissent.

En général, les fonctions qui doivent interroger le serveur pour obtenir des informations vont remettre à zéro mysql_errno() si elles réussissent.

Valeur de retour

Un code d'erreur. Zéro si aucune erreur n'est survenue.

Erreurs

Aucune.

24-B-3-m. mysql_error()

char *mysql_error(MYSQL *mysql)

Description

Pour la connexion spécifiée par mysql, mysql_error() retourne le message d'erreur pour l'appel le plus récent à une fonction de l'API qui peut réussir ou échouer. Une chaîne vide ("") est retournée si aucune erreur n'est survenue. Cela signifie que les deux tests suivants sont équivalents :

 
Sélectionnez
if(mysql_errno(&mysql))
{
    // une erreur est survenue
}

if(mysql_error(&mysql)[0] != '\0')
{
    // une erreur est survenue
}

La langue des messages d'erreurs peut être changée en recompilant la bibliothèque du client MySQL. Actuellement, vous pouvez choisir les messages d'erreur parmi une liste de plusieurs langues. Voir Section 5.8.2, « Langue des messages d'erreurs »5.8.2. Langue des messages d'erreurs.

Valeur de retour

Une chaîne de caractères qui décrit l'erreur. Une chaîne vide si aucune erreur n'est survenue.

Erreurs

Aucune.

24-B-3-n. mysql_escape_string()

Vous devez utiliser la fonction mysql_real_escape_string() à la place de celle-ci !

Cette fonction est identique à mysql_real_escape_string() exception faite que mysql_real_escape_string() prend deux identifiants de connexion comme premiers arguments et échappe la chaîne en se basant sur le jeu de caractères courant. mysql_escape_string() ne prend pas d'identifiant de connexion et ne respecte pas le jeu de caractères courant.

24-B-3-o. mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Description

Retourne la définition d'une colonne d'un jeu de résultats en tant que structure MYSQL_FIELD. Appelez cette fonction plusieurs fois pour obtenir des informations à propos de toutes les colonnes dans le jeu de résultats. mysql_fetch_field() retourne NULL quand il ne reste plus de champ.

mysql_fetch_field() est mis à zéro pour retourner des informations à propos du premier champ à chaque fois que vous exécutez une nouvelle requête SELECT. Le champ retourné par mysql_fetch_field() est aussi affecté par les appels à mysql_field_seek().

Si vous avez appelé mysql_query() pour exécuter un SELECT sur une table mais n'avez pas appelé mysql_store_result(), MySQL retourne la longueur par défaut du BLOB (8 ko octets) si vous avez appelé mysql_fetch_field() pour obtenir la longueur d'un champ BLOB. (La taille 8 K est choisie, car MySQL ne connaît pas la longueur maximale du BLOB. Cela devrait être un jour paramétrable.) Une fois que vous avez récupéré le jeu de résultats, field->max_length contient la longueur de la plus grande valeur de cette colonne dans la requête spécifiée.

Valeur de retour

La structure MYSQL_FIELD de la colonne courante. NULL s'il ne reste plus de colonne.

Erreurs

Aucune.

Exemple

 
Sélectionnez
MYSQL_FIELD *field;

while((field = mysql_fetch_field(result)))
{
    printf("nom du champ : %s\n", field->name);
}
24-B-3-p. mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

Description

Retourne un tableau de toutes les structures MYSQL_FIELD dans un jeu de résultats. Chaque structure fournit la définition de champ d'une colonne dans le jeu de résultats.

Valeur de retour

Un tableau de structures MYSQL_FIELD pour toutes les colonnes dans le jeu de résultats.

Erreurs

Aucune.

Exemple

 
Sélectionnez
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;

num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i < num_fields; i++)
{
   printf("Le champ %u est %s\n", i, fields[i].name);
}
24-B-3-q. mysql_fetch_field_direct()

MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

Description

Étant donné un numéro de champ fieldnr pour une colonne dans un jeu de résultats, cette fonction retourne la définition de ce champ en tant que structure MYSQL_FIELD. Vous pouvez utiliser cette fonction pour obtenir la définition d'une colonne choisie arbitrairement. La valeur de fieldnr doit varier entre 0 et mysql_num_fields(result)-1.

Valeur de retour

La structure MYSQL_FIELD pour la colonne spécifiée.

Erreurs

Aucune.

Exemple

 
Sélectionnez
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;

num_fields = mysql_num_fields(result);
for(i = 0; i < num_fields; i++)
{
    field = mysql_fetch_field_direct(result, i);
    printf("La champ %u est %s\n", i, field->name);
}
24-B-3-r. mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

Description

Retourne les longueurs des colonnes de la ligne courante dans le jeu de résultats. Si vous voulez copier les valeurs des champs, cette information sur la longueur est très utile pour l'optimisation, car vous pouvez éviter les appels à strlen(). De plus, si le jeu de résultats contient des données binaires, vous devez utiliser cette fonction pour déterminer la longueur des données, car strlen() retourne des résultats incorrects pour les champs contenant des caractères nuls.

La longueur des colonnes vides et des colonnes contenant la valeur NULL est zéro. Pour savoir comment distinguer ces cas, voyez la description de mysql_fetch_row().

Valeur de retour

Un tableau d'entiers longs non signés représentant la taille de chaque colonne (n'incluant pas le caractère nul de terminaison). NULL si une erreur se produit.

Erreurs

mysql_fetch_lengths() n'est valide que pour la ligne courante du jeu de résultats. Cette fonction retourne NULL si vous l'appelez avant d'appeler mysql_fetch_row() ou après avoir récupéré toutes les lignes du résultat.

Exemple

 
Sélectionnez
MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;

row = mysql_fetch_row(result);
if (row)
{
    num_fields = mysql_num_fields(result);
    lengths = mysql_fetch_lengths(result);
    for(i = 0; i < num_fields; i++)
    {
         printf("La colonne %u a %l octets de longueur.\n", i, lengths[i]);
    }
}
24-B-3-s. mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

Description

Récupère la ligne suivante d'un jeu de résultats. Lorsqu'elle est utilisée après mysql_store_result(), mysql_fetch_row() retourne NULL quand il n'y a plus de ligne à récupérer. Lorsqu'elle est utilisée après mysql_use_result(), mysql_fetch_row() retourne NULL quand il n'y a plus de ligne à récupérer ou qu'une erreur est rencontrée.

Le nombre de valeurs dans la ligne est donné par mysql_num_fields(result). Si row contient la valeur de retour d'un appel à mysql_fetch_row(), les pointeurs sur les valeurs sont accédées de row[0] à row[mysql_num_fields(result)-1]. Les valeurs NULL de la ligne sont indiquées par des pointeurs NULL.

La longueur de la valeur du champ dans la ligne peut être obtenue en appelant mysql_fetch_lengths(). Les champs vides et les champs contenant NULL ont tous deux une longueur égale à zéro; vous pouvez les distinguer en vérifiant le pointeur sur la valeur du champ. Si le pointeur est NULL, le champ est NULL; sinon, le champ est vide.

Valeur de retour

Une structure MYSQL_ROW pour la prochaine ligne. NULL s'il n'y a plus de ligne à récupérer ou qu'une erreur survient.

Erreurs

  • CR_SERVER_LOST
    La connexion au serveur a été perdue durant la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

Exemple

 
Sélectionnez
MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
   unsigned long *lengths;
   lengths = mysql_fetch_lengths(result);
   for(i = 0; i < num_fields; i++)
   {
       printf("[%.*s] ", (int) lengths[i], row[i] ? row[i] : "NULL");
   }
   printf("\n");
}
24-B-3-t. mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

Si vous utilisez une version de MySQL plus ancienne que la 3.22.24, vous devez utiliser unsigned int mysql_num_fields(MYSQL *mysql).

Description

Retourne le nombre de colonnes pour la requête la plus récente de la connexion.

L'utilisation normale de cette fonction est lorsque mysql_store_result() a retourné NULL (et que vous n'avez donc pas de pointeur sur jeu de résultats). Dans ce cas, vous pouvez appeler mysql_field_count() pour déterminer si mysql_store_result() aurait dû produire un résultat non vide. Cela permet au programme client d'entreprendre les bonnes actions sans savoir si la requête était un SELECT (ou équivalent). L'exemple suivant illustre comment cela peut être fait.

Voir Section 24.2.13.1, « Pourquoi est-ce que mysql_store_result() retourne parfois NULL après que mysql_query() ait réussi »24.2.13.1. Pourquoi est-ce que mysql_store_result() retourne parfois NULL après que mysql_query() ait réussi.

Valeur de retour

Un entier non signé représentant le nombre de champs dans un jeu de résultats.

Erreurs

Aucune.

Exemple

 
Sélectionnez
MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&mysql,query_string))
{
    // erreur
}
else // requête bonne, traitons les données qu'elle renvoie
{
    result = mysql_store_result(&mysql);
    if (result)  // il y a des lignes
    {
        num_fields = mysql_num_fields(result);
        // récupère les lignes, puis appelle mysql_free_result(result)
    }
    else  // mysql_store_result() n'a rien retourné; est-ce normal ?
    {
        if(mysql_field_count(&mysql) == 0)
        {
            // la requête ne retourne aucune donnée
            // (ce n'était pas un SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
        else // mysql_store_result() aurait dû retourner des données
        {
            fprintf(stderr, "Erreur : %s\n", mysql_error(&mysql));
        }
    }
}

Une autre voie est de remplacer l'appel à mysql_field_count(&mysql) par mysql_errno(&mysql). Dans ce cas, vous vérifiez directement les erreurs à partir de mysql_store_result() plutôt qu'à partir de mysql_field_count() si la requête était un SELECT.

24-B-3-u. mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Description

Place le pointeur de champs à la position donnée. Le prochain appel à mysql_fetch_field() récupérera la définition du champ de la colonne associée à cet index.

Pour vous placer au début d'une ligne, passez 0 comme valeur d'offset.

Valeur de retour

La dernière valeur de l'index de champ.

Erreurs

Aucune.

24-B-3-v. mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

Description

Retourne la position du curseur de champs utilisé pour le dernier appel à mysql_fetch_field(). Cette valeur peut être utilisée en argument de mysql_field_seek().

Valeur de retour

L'indice courant du curseur de champs.

Erreurs

Aucune.

24-B-3-w. mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

Description

Libère la mémoire allouée à un résultat avec mysql_store_result(), mysql_use_result(), mysql_list_dbs(), etc. Quand vous n'avez plus besoin d'un jeu de résultats, vous devez libérer la mémoire qu'il occupe en appelant mysql_free_result().

Valeur de retour

Aucune.

Erreurs

Aucune.

24-B-3-x. mysql_get_client_info()

char *mysql_get_client_info(void)

Description

Retourne une chaîne représentant la version de la bibliothèque du client.

Valeur de retour

Une chaîne de caractères représentant la version de la bibliothèque du client.

Erreurs

Aucune.

24-B-3-y. mysql_get_client_version()

unsigned long mysql_get_client_version(void)

Description

Retourne un entier qui représente la version de la bibliothèque cliente. Cette valeur est au format XYYZZX est la version majeure, YY est la version publiée, et ZZ est le numéro de version de la version publiée. Par exemple, la valeur 40102 représente la version 4.1.2.

Valeur retournée

Un entier qui représente la version de la bibliothèque cliente MySQL.

Erreurs

Aucune.

24-B-3-z. mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

Description

Retourne une chaîne de caractères décrivant le type de connexion actuellement utilisé, incluant le nom du serveur.

Valeur de retour

Une chaîne de caractères représentant le nom du serveur et le type de connexion.

Erreurs

Aucune.

24-B-3-aa. mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

Description

Retourne la version du protocole utilisé par la connexion courante.

Valeur de retour

Un entier non signé représentant la version du protocole utilisé par la connexion courante.

Erreurs

Aucune.

24-B-3-ab. mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

Description

Retourne une chaîne représentant le numéro de version du serveur.

Valeur de retour

Une chaîne de caractères représentant le numéro de version du serveur.

Erreurs

Aucune.

24-B-3-ac. mysql_get_server_version()

unsigned long mysql_get_server_version(MYSQL *mysql)

Description

Retourne le numéro de version du serveur, sous la forme d'un entier (nouveau en 4.1).

Valeurs retournées

Un nombre, qui représente le numéro de version du serveur MySQL, au format suivant :

 
Sélectionnez
major_version*10000 + minor_version *100 + sub_version

Par exemple, 4.1.0 est retournée comme ceci : 40100.

Ceci est pratique pour déterminer rapidement le numéro de version d'un serveur, dans un client, et connaître ainsi ses fonctionnalités.

Erreurs

Aucune.

24-B-3-ad. mysql_hex_string()

unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)

Description

Cette fonction sert à créer une chaîne SQL valide que vous pouvez utiliser dans une requête SQL. Voir Section 9.1.1, « Chaînes »9.1.1. Chaînes.

La chaîne de l'argument from est encodée au format hexadécimal, et chaque caractère prend alors deux chiffres hexadécimaux. Le résultat est placé dans le paramètre to et un caractère nul termine la chaîne.

La chaîne pointée par from doit faire length octets de long. Vous devez allouer le buffer to à au moins longueur * 2 + 1 de long. Lorsque mysql_hex_string() se termine, le contenu de to est une chaîne terminée par un caractère nul. La valeur de retour est la taille de la chaîne encodée, sans compter le caractère nul.

La valeur retournée peut être placée dans une commande SQL en utilisant le format 0xvalue ou X'value'. Cependant, la valeur de retour n'inclut pas les éléments de syntaxe 0x ou X'...'. Le code appelant doit fournir les éléments dont il a besoin.

mysql_hex_string() a été ajouté en MySQL 4.0.23 et 4.1.8.

Exemple

 
Sélectionnez
char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
end = strmov(end,"0x");
end += mysql_hex_string(end,"What's this",11);
end = strmov(end,",0x");
end += mysql_hex_string(end,"binary data: \0\r\n",16);
*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}

La fonction strmov() utilisée dans l'exemple est incluse dans la bibliothèque cliente mysqlclient et fonctionne comme strcpy() mais retourne un pointeur sur le caractère nul final du premier paramètre.

Valeur retournée

La taille de la valeur placée dans to, hormis le caractère nul final.

Erreurs

Aucune.

24-B-3-ae. mysql_info()

char *mysql_info(MYSQL *mysql)

Description

Récupère une chaîne de caractères fournissant des informations à propos de la requête exécutée le plus récemment, mais seulement pour celles listées ici. Pour les autres requêtes, mysql_info() retournera NULL.

Le format de la chaîne varie selon le type de requête, comme décrit ici. Les nombres présentés sont des exemples, la chaîne retournée contiendra les informations correspondant à vos requêtes.

  • INSERT INTO ... SELECT ...
    Chaîne retournée : Records: 100 Duplicates: 0 Warnings: 0
  • INSERT INTO ... VALUES (...),(...),(...)...
    Chaîne retournée : Records: 3 Duplicates: 0 Warnings: 0
  • LOAD DATA INFILE ...
    Chaîne retournée : Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
  • ALTER TABLE
    Chaîne retournée : Records: 3 Duplicates: 0 Warnings: 0
  • UPDATE
    Chaîne retournée : Rows matched: 40 Changed: 40 Warnings: 0

Notez que mysql_info() retourne une valeur non nulle (NULL) pour les requêtes INSERT ... VALUES seulement si une liste de valeurs multiples est fournie à la requête.

Valeur de retour

Une chaîne de caractères représentant des informations additionnelles à propos de la dernière requête exécutée. NULL si aucune information n'est disponible pour la requête.

Erreurs

Aucune.

24-B-3-af. mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

Description

Alloue ou initialise un objet MYSQL convenable pour mysql_real_connect(). Si mysql est un pointeur NULL, la fonction alloue, initialise et retourne un nouvel objet. Sinon, l'objet est initialisé et son adresse est retournée. Si mysql_init() alloue un nouvel objet, il sera libéré quand mysql_close() sera appelée pour clore la connexion.

Valeur de retour

Un gestionnaire MYSQL* initialisé. NULL s'il n'y avait pas assez de mémoire pour allouer le nouvel objet.

Erreurs

Si la mémoire est insuffisante, NULL est retourné.

24-B-3-ag. mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

Description

Retourne l'identifiant généré pour une colonne AUTO_INCREMENT par la dernière requête. Utilisez cette commande après avoir exécuté une requête INSERT sur une table qui contient un champ AUTO_INCREMENT.

Plus précisément, mysql_insert_id() est mis à jour dans ces conditions :

  • Les commandes INSERT qui stockent une valeur dans une colonne de type AUTO_INCREMENT. C'est vrai si la valeur est automatiquement générée suivant le stockage de NULL ou 0 dans la colonne, ou une valeur explicite non spéciale.
  • Dans le cas des INSERT multiples, mysql_insert_id() retourne la première valeur AUTO_INCREMENT automatiquement générée : si aucune valeur n'est générée, elle retourne la dernière valeur explicitement insérée dans la colonne AUTO_INCREMENT.
  • Les commandes INSERT qui génèrent une valeur AUTO_INCREMENT en insérant l'expression LAST_INSERT_ID(expr) dans une colonne.
  • Les commandes INSERT qui génèrent une valeur AUTO_INCREMENT qui donne la valeur de LAST_INSERT_ID(expr) à une colonne.
  • La valeur de mysql_insert_id() n'est pas affectée par les commandes telles que les commandes SELECT qui ne retournent pas de résultat.
  • Si la commande précédente a retourné une erreur, la valeur de mysql_insert_id() est indéfinie.

Notez que mysql_insert_id() retourne 0 si la dernière requête n'a pas généré de valeur AUTO_INCREMENT. Si vous voulez garder cette valeur pour plus tard, assurez-vous d'appeler mysql_insert_id() immédiatement après la requête ayant généré cette valeur.

mysql_insert_id() est mis à jour après l'exécution de requêtes INSERT et UPDATE qui génèrent une valeur AUTO_INCREMENT ou qui définissent la valeur d'une colonne à LAST_INSERT_ID(expr). Voir Section 12.8.4, « Fonctions diverses »12.8.4. Fonctions diverses.

Notez aussi que la valeur de retour de la fonction SQL LAST_INSERT_ID() contient toujours la valeur d'AUTO_INCREMENT la plus à jour. Cette valeur n'est pas remise à zéro lors de l'exécution d'autres requêtes, car elle est maintenue pour le serveur.

Valeur de retour

La valeur de la colonne AUTO_INCREMENT qui a été mise à jour par la dernière requête. Retourne zéro si aucune requête n'avait eu lieu durant la connexion, ou si la dernière requête n'a pas mis à jour la valeur de la colonne AUTO_INCREMENT.

Erreurs

Aucune.

24-B-3-ah. mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

Description

Demande au serveur de terminer le thread spécifié par pid.

Valeur de retour

Zéro si la commande a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-ai. mysql_library_end()

int mysql_library_init(int argc, char **argv, char **groups)

Description

Ceci est un synonyme de la fonction mysql_server_init(). Il a été ajouté en MySQL 4.1.10 et 5.0.3.

Voyez Section 24.2.2, « Vue d'ensemble des fonctions de l'API C »24.2.2. Vue d'ensemble des fonctions de l'API C pour connaître son utilisation.

24-B-3-aj. mysql_library_end()

void mysql_library_end(void)

Description

Ceci est un synonyme de la fonction mysql_server_end(). Il a été ajouté en MySQL 4.1.10 et 5.0.3.

Voyez Section 24.2.2, « Vue d'ensemble des fonctions de l'API C »24.2.2. Vue d'ensemble des fonctions de l'API C pour connaître son utilisation.

24-B-3-ak. mysql_list_dbs()

MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

Description

Retourne un jeu de résultats se composant des noms des bases de données localisées sur le serveur qui correspondent à l'expression régulière spécifiée par le paramètre wild. wild peut contenir les caractères spéciaux '%' ou '_', ou peut être un pointeur NULL pour obtenir la liste de toutes les bases de données. Utiliser mysql_list_dbs() revient à exécuter la requête SHOW databases [LIKE wild].

Vous devez libérer le résultat avec mysql_free_result().

Valeur de retour

Un jeu de résultats MYSQL_RES en cas de succès. NULL si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-al. mysql_list_fields()

MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)

Description

Retourne un jeu de résultats comportant des noms de champs dans une table qui correspondent l'expression régulière simple spécifiée par la paramètre wild. wild peut contenir les caractères spéciaux '%' ou '_', ou peut être un pointeur NULL pour correspondre à tous les champs. Utiliser mysql_list_fields() revient à exécuter la requête SHOW COLUMNS FROM nom_de_table [LIKE wild].

Notez qu'il est recommandé d'utiliser SHOW COLUMNS FROM nom_de_table au lieu de /mysql_list_fields().

Vous devez libérer le résultat avec mysql_free_result().

Valeur de retour

Un jeu de résultats MYSQL_RES en cas de succès. NULL sinon.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-am. mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

Description

Retourne un jeu de résultats décrivant les threads courants du serveur. C'est le même genre d'informations renvoyé par mysqladmin processlist ou une requête SHOW PROCESSLIST.

Vous devez libérer le jeu de résultats avec mysql_free_result().

Valeur de retour

Un jeu de résultats MYSQL_RES en cas de succès. NULL si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-an. mysql_list_tables()

MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

Description

Retourne un jeu de résultats comportant des noms de tables dans la base de données courante qui concordent avec l'expression régulière spécifiée par le paramètre wild. wild peut contenir les caractères spéciaux '%' ou '_', ou peut être un pointeur NULL pour obtenir toutes les tables. Faire appel à mysql_list_tables() revient à exécuter la requête SHOW tables [LIKE wild].

Vous devez libérer le jeu de résultats avec mysql_free_result().

Valeur de retour

Un jeu d'enregistrements MYSQL_RES en cas de succès. NULL en cas d'erreur.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-ao. mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

ou

unsigned int mysql_num_fields(MYSQL *mysql)

La seconde forme ne fonctionne plus à partir de la version 3.22.24 de MySQL. Pour passer un argument MYSQL*, vous devez utiliser la fonction unsigned int mysql_field_count(MYSQL *mysql) à la place.

Description

Retourne le nombre de colonnes dans un jeu de résultats.

Notez que vous pouvez obtenir le nombre de colonnes soit à partir d'un pointeur sur résultat, soit d'un pointeur de connexion. Vous utiliserez le pointeur de connexion si mysql_store_result() ou mysql_use_result() ont retournés NULL (et que donc, vous n'avez pas de pointeur sur résultat). Dans ce cas, vous pouvez appeler mysql_field_count() pour déterminer si mysql_store_result() aurait dû retourner un résultat non vide. Cela permet au client d'effectuer les bonnes actions sans savoir si la requête était un SELECT (ou équivalent). L'exemple ci-dessous montre comment cela doit être utilisé.

Voir Section 24.2.13.1, « Pourquoi est-ce que mysql_store_result() retourne parfois NULL après que mysql_query() a réussi »24.2.13.1. Pourquoi est-ce que mysql_store_result() retourne parfois NULL après que mysql_query() ait réussi.

Valeur de retour

Un entier non signé représentant le nombre de champs dans un jeu de résultats.

Erreurs

Aucune.

Exemple

 
Sélectionnez
MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&mysql,query_string))
{
    // erreur
}
else // la requête fonctionne, on s'occupe des données
{
    result = mysql_store_result(&mysql);
    if (result)  // il y a des lignes
    {
        num_fields = mysql_num_fields(result);
        // recupérer les lignes, puis appeler mysql_free_result(result)
    }
    else  // mysql_store_result() n'a rien retourné ! pourquoi ?
    {
        if (mysql_errno(&mysql))
    {
           fprintf(stderr, "Erreur : %s\n", mysql_error(&mysql));
    }
        else if (mysql_field_count(&mysql) == 0)
        {
            // la requête ne retourne pas de données
            // (ce n'était pas un SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
    }
}

Une autre voie (si vous savez que votre requête aurait dû retourner des résultats) est de remplacer l'appel à mysql_errno(&mysql) par un test sur la nullité de mysql_field_count(&mysql). Cela n'arrive que si un problème a été rencontré.

24-B-3-ap. mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

Description

Retourne le nombre de lignes présentes dans le résultat.

L'utilisation de mysql_num_rows() dépend de si vous utilisez mysql_store_result() ou mysql_use_result() pour retourner le jeu de résultats. Si vous utilisez mysql_store_result(), mysql_num_rows() peut être appelé immédiatement. Si vous utilisez mysql_use_result(), mysql_num_rows() ne retournera pas la valeur correcte tant que toutes les lignes du résultat n'auront pas été récupérées.

Valeur de retour

Le nombre de lignes dans le résultat.

Erreurs

Aucune.

24-B-3-aq. mysql_options()

int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

Description

Cette fonction peut être utilisée pour spécifier des options de connexion et modifier le comportement de la session courante. Cette fonction peut être appelée plusieurs fois pour définir plusieurs options.

mysql_options() doit être appelée après mysql_init() et avant mysql_connect() ou mysql_real_connect().

L'argument option est l'option que vous voulez configurer, l'argument arg est la valeur pour cette option. Si l'option est un entier, arg doit pointer sur la valeur d'un entier.

Les valeurs possibles pour les options sont :

Option

Type de l'argument

Fonction

MYSQL_OPT_CONNECT_TIMEOUT

unsigned int *

Délai d'inactivité maximal permis.

MYSQL_OPT_READ_TIMEOUT

unsigned int *

Délai d'expiration pour les lectures depuis le serveur (fonctionne uniquement sur Windows sur les connexions TCP/IP)

MYSQL_OPT_WRITE_TIMEOUT

unsigned int *

Délai pour les écritures sur le serveur (fonctionne uniquement sur Windows sur les connexions TCP/IP)

MYSQL_OPT_COMPRESS

Non utilisé

Utiliser le protocole compressé client/serveur.

MYSQL_OPT_LOCAL_INFILE

pointeur optionnel sur uint

Si aucun pointeur n'est donné, ou que celui-ci pointe sur un unsigned int != 0 la commande LOAD LOCAL INFILE est activée.

MYSQL_OPT_NAMED_PIPE

Non utilisé

Utiliser les pipes nommés pour se connecter au serveur MySQL sur NT.

MYSQL_INIT_COMMAND

char *

Commande à exécuter lors de la connexion au serveur MySQL. Sera automatiquement réexécutée lors des reconnexions.

MYSQL_READ_DEFAULT_FILE

char *

Lit les options à partir du fichier d'options nommé plutôt que de my.cnf.

MYSQL_READ_DEFAULT_GROUP

char *

Lit les options à partir du groupe spécifié dans le fichier d'options my.cnfou le fichier spécifié par MYSQL_READ_DEFAULT_FILE.

MYSQL_OPT_PROTOCOL

unsigned int *

Type de protocole à utiliser. Doit être une des valeurs de mysql_protocol_type définies dans mysql.h.

MYSQL_SHARED_MEMORY_BASE_NAME

char*

Nom d'un objet de mémoire partagée pour communiquer avec le serveur. Doit être le même que l'option -shared-memory-base-name utilisé pour le serveur mysqld auquel vous voulez vous connecter.

Notez que le groupe client est toujours lu si vous utilisez MYSQL_READ_DEFAULT_FILE ou MYSQL_READ_DEFAULT_GROUP.

Le groupe spécifié dans le fichier des options peut contenir les options suivantes :

Option

Description

connect-timeout

Délai d'inactivité maximal permis en secondes. Sous Linux, ce délai est aussi utilisé lors de l'attente de la première réponse du serveur.

compress

Utiliser le protocole compressé client/serveur.

database

Se connecter à cette base de données si aucune base n'a été sélectionnée à la connexion.

debug

Options de débogage.

disable-local-infile

Interdit l'utilisation de LOAD DATA LOCAL.

host

Nom d'hôte par défaut.

init-command

Commande lors de la connexion au serveur MySQL. Sera automatiquement réexécutée lors des reconnexions.

interactive-timeout

Revient à spécifier CLIENT_INTERACTIVE à mysql_real_connect(). Voir Section 24.2.3.46, « mysql_real_connect() »24.2.3.46. mysql_real_connect().

local-infile[=(0|1)]

Si aucun argument, ou argument != 0, on permet alors l'utilisation de LOAD DATA LOCAL.

max_allowed_packet

Taille maximale de paquet que le client peut lire du serveur.

password

Mot de passe par défaut.

pipe

Utiliser les tunnels nommés pour se connecter à MySQL sur NT.

protocol=(TCP | SOCKET | PIPE | MEMORY)

Le protocole utilisé lors de la connexion au serveur (nouveau en version 4.1).

port

Port par défaut.

return-found-rows

Demande à mysql_info() de retourner les lignes trouvées au lieu des lignes mises à jour lors de l'utilisation de UPDATE.

shared-memory-base-name=name

Nom de l'objet en mémoire partagée à utiliser pour se connecter au serveur (par défaut, c'est "MySQL"). Nouveau en MySQL 4.1.

socket

Numéro de socket par défaut.

user

Utilisateur par défaut.

Notez que timeout a été remplacé par connect-timeout, mais que timeout fonctionne encore pour le moment.

Pour plus d'informations sur les fichiers d'options, reportez-vous à Section 4.3.2, « Fichier d'options my.cnf »4.3.2. Fichier d'options my.cnf.

Valeur de retour

Zéro si la commande a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Exemple

 
Sélectionnez
MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Impossible de se connecter à la base de données. Erreur : %s\n",
          mysql_error(&mysql));
}

Ce qui précède demande au client d'utiliser le protocole compressé client/serveur et lit les options optionnelles de la section odbc dans le fichier my.cnf.

24-B-3-ar. mysql_ping()

int mysql_ping(MYSQL *mysql)

Description

Vérifie si la connexion au serveur est encore assurée. Si ce n'est pas le cas, une reconnexion automatique est tentée.

Cette fonction peut être utilisée par les clients qui restent inactifs longtemps, pour vérifier que le serveur n'a pas fermé la connexion et se reconnecter si nécessaire.

Valeur de retour

Zéro si le serveur répond. Autre que zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-as. mysql_query()

int mysql_query(MYSQL *mysql, const char *query)

Description

Exécute la requête SQL pointée par la chaîne terminée par null query. La requête doit se composer d'une seule opération. Vous ne devez pas ajouter de caractère de terminaison (';') ou \g à la fin de la requête.

mysql_query() ne peut être utilisée pour les requêtes contenant des données binaires, vous devez utiliser mysql_real_query() à la place. (Les données binaires peuvent contenir le caractère '\0', qui est interprété comme la fin de la chaîne requête.)

Si vous voulez savoir si la requête doit retourner un jeu de résultats ou non, vous pouvez utiliser mysql_field_count() pour vérifier. Voir Section 24.2.3.20, « mysql_field_count() »24.2.3.20. mysql_field_count().

Valeur de retour

Zéro si la requête a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-at. mysql_real_connect()

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)

Description

mysql_real_connect() essaye de se connecter à une base de données MySQL tournant sur l'hôte. mysql_real_connect() doit se terminer correctement avant que vous ne puissiez aucune autre fonction de l'API, à l'exception de mysql_get_client_info().

Les paramètres sont spécifiés comme suit.

  • Le premier paramètre doit être l'adresse d'une structure MYSQL existante. Avant d'appeler mysql_real_connect() vous devez appeler mysql_init() pour initialiser la structure MYSQL. Vous pouvez changer un tas d'options de connexion en appelant mysql_options(). Voir Section 24.2.3.43, « mysql_options() »24.2.3.43. mysql_options().
  • La valeur de host peut être un nom de domaine ou une adresse IP. Si host est NULL ou égal à la chaîne "localhost", une connexion à la machine locale est essayée. Si le système supporte les sockets (Unix) ou les tunnels nommés (Windows), elles sont utilisées au lieu de TCP/IP pour se connecter au serveur.
  • La paramètre user contient l'identifiant MySQL de l'utilisateur. Si user est NULL, l'utilisateur courant est sous-entendu. Avec Unix c'est l'utilisateur courant. Avec Windows ODBC, le nom de l'utilisateur courant doit être spécifié explicitement. Voir Section 25.1.9.2, « Configuration du DSN MyODBC sur Windows »25.1.9.2. Configuration du DSN MyODBC sur Windows.
  • Le paramètre passwd contient le mot de passe de user. Si passwd est NULL, seules les entrées de la table user pour l'utilisateur ayant un champ vide seront testées. Cela permet à l'administrateur de mettre en place le système de privilèges MySQL de façon à ce que les utilisateurs aient divers privilèges selon qu'ils ont spécifié ou pas de mot de passe.
    Note : N'essayez pas d'encrypter le mot de passe avant l'appel à mysql_real_connect(), l'encryptage du mot de passe est géré automatiquement par l'API du client.
  • db est le nom de la base de données. Si db n'est pas NULL, la connexion changera la base par défaut en cette valeur.
  • Si port est différent de 0, sa valeur sera utilisée comme port de connexion TCP/IP. Notez que le paramètre host détermine le type de la connexion.
  • Si unix_socket n'est pas NULL, la chaîne spécifie la socket ou le tunnel nommé à utiliser. Notez que le paramètre host détermine le type de la connexion.
  • La valeur de client_flag est habituellement 0, mais peut être la combinaison des options suivantes dans des circonstances très spéciales :

Nom de l'option

Description

CLIENT_COMPRESS

Utilise le protocole compressé.

CLIENT_FOUND_ROWS

Retourne le nombre de lignes trouvées, et non de lignes affectées.

CLIENT_IGNORE_SPACE

Autorise les espaces après les noms de fonctions. Rend tous les noms de fonctions des mots réservés.

CLIENT_INTERACTIVE

Autorise interactive_timeout secondes (au lieu de wait_timeout secondes) d'inactivité avant de fermer la connexion.

CLIENT_LOCAL_FILES

Active le support de LOAD DATA LOCAL.

CLIENT_MULTI_STATEMENTS

Indique au serveur que le client peut envoyer des requêtes multiples (séparées par des ';'). Si cette option n'est pas configurée, les commandes multiples sont désactivées. Nouveau en 4.1.

CLIENT_MULTI_RESULTS

Indique au serveur que le client peut gérer des jeux de résultats multiples, issus de commandes multiples, ou de procédures stockées. C'est automatique si l'option CLIENT_MULTI_STATEMENTS est active. Nouveau en 4.1.

CLIENT_NO_SCHEMA

N'autorise pas la syntaxe db_name.tbl_name.col_name. Cela est fait pour ODBC. Il fait générer une erreur à l'analyseur si vous utilisez cette syntaxe, ce qui peut se révéler fort utile pour la chasse aux bogues dans les programmes ODBC.

CLIENT_ODBC

Le client est un client ODBC. Cela rend mysqld plus accueillant vis-à-vis de ODBC.

CLIENT_SSL

Utilise SSL (protocole encrypté).

Valeur de retour

Un gestionnaire de connexions MYSQL* si la connexion a réussi, NULL si elle a échoué. Pour une connexion à succès, la valeur de retour est la même que la valeur du premier paramètre.

Erreurs

  • CR_CONN_HOST_ERROR
    Impossible de se connecter au serveur MySQL.
  • CR_CONNECTION_ERROR
    Impossible de se connecter au serveur MySQL local.
  • CR_IPSOCK_ERROR
    Impossible de créer une socket IP.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SOCKET_CREATE_ERROR
    Impossible de créer une socket UNIX.
  • CR_UNKNOWN_HOST
    Impossible de trouver l'adresse IP de l'hôte.
  • CR_VERSION_ERROR
    Une disparité de protocole a résulté de la tentative de connexion à un serveur avec une bibliothèque de client qui utilise une version différente du protocole. Cela peut arriver si vous utilisez une très vieille bibliothèque cliente pour vous connecter à un serveur qui n'a pas été démarré avec l'option --old-protocol.
  • CR_NAMEDPIPEOPEN_ERROR
    Impossible de créer un tunnel nommé sur Windows.
  • CR_NAMEDPIPEWAIT_ERROR
    Impossible d'attendre un tunnel nommé sur Windows.
  • CR_NAMEDPIPESETSTATE_ERROR
    Impossible d'obtenir un gestionnaire de tunnels sur Windows.
  • CR_SERVER_LOST
    Si connect_timeout > 0 et qu'il a fallu plus de connect_timeout secondes pour se connecter au serveur, ou que celui-ci n'a plus répondu durant l'exécution de init-command.

Exemple

 
Sélectionnez
MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Impossible de se connecter à la base de données, erreur : %s\n",
          mysql_error(&mysql));
}

En utilisant mysql_options() la bibliothèque MySQL lira les sections [client] et [your_prog_name] dans le fichier my.cnf ce qui assurera le bon fonctionnement de votre programme, même si quelqu'un a configuré MySQL d'une façon non standard.

Notez que pendant la connexion, mysql_real_connect() configure l'option reconnect (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 déconnexion, d'essayer de se reconnecter au serveur avant d'abandonner.

24-B-3-au. mysql_real_escape_string()

unsigned long mysql_real_escape_string(MYSQL *mysql, char *en, const char *de, unsigned long longueur)

Description

Cette fonction est utilisée pour créer une requête SQL légale que vous pouvez utiliser dans une commande SQL. Voir Section 9.1.1, « Chaînes »9.1.1. Chaînes.

La string dans de est encodée en chaîne échappé SQL, prenant en compte le jeu de caractères de la connexion. Le résultat est placé dans en et un octet nul de terminaison est ajouté à la fin de celui-ci. Les caractères encodés sont NUL (ASCII 0), '\n', '\r', '\', ''', '"', et Ctrl-Z ( Voir Section 9.1, « Littéraux : comment écrire les chaînes et les nombres »9.1. Littéraux : comment écrire les chaînes et les nombres). (En fait, MySQL a seulement besoin que l'antislash et le guillemet utilisé pour entourer la chaîne soient échappés. Cette fonction échappe les autres caractères pour les rendre plus faciles à lire dans les fichiers de log.)

La chaîne pointée par de doit avoir une taille de longueur octets. Vous devez allouer à l'espace de en au moins longueur*2+1 octets. (Dans le pire des cas, chaque caractère devra être encodé en utilisant deux octets, et vous avez besoin de place pour l'octet nul de terminaison.) Lorsque mysql_escape_string() retourne un résultat, le contenu de en sera une chaîne terminée par un caractère nul. La valeur de retour est la longueur de la chaîne encodée, n'incluant pas le caractère nul de terminaison.

Exemple

 
Sélectionnez
char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"C'est quoi ça",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"donnée binaire : \0\r\n",16);
*end++ = '\'';
*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Impossible d'insérer la ligne, erreur : %s\n",
           mysql_error(&mysql));
}

La fonction strmov() utilisée dans cet exemple est incluse dans la bibliothèque mysqlclient et fonctionne comme strcpy() mais retourne un pointeur sur le nul de fin du premier paramètre.

Valeur de retour

La longueur de la valeur passée dans to, n'incluant pas le caractère nul de fin de chaîne.

Erreurs

Aucune.

24-B-3-av. mysql_real_query()

int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)

Description

Exécute la requête SQL pointée par query, qui doit être une chaîne de caractères de length octets de longueur. La requête ne doit contenir qu'une seule commande. Vous ne devez pas ajouter de point-virgule (';') ou \g à la fin de la requête.

Vous devez utiliser mysql_real_query() au lieu de mysql_query() pour les requêtes qui contiennent des données binaires, car celles-ci peuvent contenir le caractère'\0'. De plus, mysql_real_query() est plus rapide que mysql_query() car elle n'invoque pas strlen() sur la chaîne contenant la requête.

Si vous voulez savoir si la requête est censée retourner un jeu de résultats ou non, vous pouvez utiliser mysql_field_count() pour vérifier cela. Voir Section 24.2.3.20, « mysql_field_count() »24.2.3.20. mysql_field_count().

Valeur de retour

Zéro si la requête a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-aw. mysql_reload()

int mysql_reload(MYSQL *mysql)

Description

Demande au serveur MySQL de recharger les tables de droits. L'utilisateur doit avoir les droits RELOAD.

Cette fonction est déconseillée. Il est préférable d'utiliser mysql_query() pour exécuter une requête FLUSH PRIVILEGES à la place.

Valeur retournée

Zéro si la commande a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-ax. mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

Description

Déplace le curseur de ligne vers une ligne arbitraire dans un jeu de résultats de requête. Cela nécessite que le jeu de résultats contienne la totalité des lignes retournées par la requête, et donc, mysql_row_seek() ne peut être utilisée qu'en conjonction avec mysql_store_result(), et non avec mysql_use_result().

La position doit être une valeur retournée par un appel à mysql_row_tell() ou à mysql_row_seek(). Cette valeur n'est pas un simple numéro de ligne, si vous voulez vous déplacer dans un jeu de résultats en utilisant le numéro d'une ligne, utilisez mysql_data_seek().

Valeur de retour

La position précédente du curseur de ligne. Cette valeur peut être passée à mysql_row_seek().

Erreurs

Aucune.

24-B-3-ay. mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

Description

Retourne la position courante du pointeur de lignes pour le dernier appel à mysql_fetch_row(). Cette valeur peut être utilisée comme argument de mysql_row_seek().

Vous ne devez utiliser mysql_row_tell() qu'après mysql_store_result(), et non après mysql_use_result().

Valeur de retour

La position courante du pointeur de ligne.

Erreurs

Aucune.

24-B-3-az. mysql_select_db()

int mysql_select_db(MYSQL *mysql, const char *db)

Description

Rend la base de données spécifiée par db la base par défaut (courante) pour la connexion spécifiée par mysql. Pour les requêtes suivantes, cette base de données sera utilisée comme référence pour les tables dont la base de données n'a pas été spécifiée explicitement.

mysql_select_db() échoue si l'utilisateur ne peut être reconnu ayant droit d'accès à la base de données.

Valeur de retour

Zéro si la commande a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-ba. mysql_set_server_option()

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

Description

Active ou désactive une option de connexion. Le paramètre option peut prendre l'une des valeurs suivantes :

MYSQL_OPTION_MULTI_STATEMENTS_ON

Active le support des commandes multiples.

MYSQL_OPTION_MULTI_STATEMENTS_OFF

Désactive le support des commandes multiples.

Valeur retournée

Zéro en cas de succès. Non nul si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été exécutées dans un ordre invalide.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • ER_UNKNOWN_COM_ERROR
    Le serveur ne supporte pas mysql_set_server_option() (ce qui peut être le cas d'un serveur antérieur à la version 4.1.1) ou le serveur ne supporte pas l'option qui a été utilisée.
24-B-3-bb. mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

Description

Demande au serveur de base de données de se terminer. L'utilisateur connecté doit avoir le droit SHUTDOWN.

Valeur de retour

Zéro si la commande a été effectuée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-bc. mysql_sqlstate()

const char *mysql_sqlstate(MYSQL *mysql)

Description

Retourne une chaîne terminée par null, contenant le code d'erreur SQLSTATE de la dernière erreur. Le code d'erreur est constitué de 5 caractères. '00000' signifie « pas d'erreur ». Les valeurs sont spécifiées par les normes ANSI SQL et ODBC. Pour une liste des valeurs possibles, voyez Chapitre 26, Gestion des erreurs avec MySQLChapitre 26. Gestion des erreurs avec MySQL.

Notez que les erreurs MySQL ne sont pas toutes associées à une erreur SQLSTATE. La valeur 'HY000' (erreur générale) est utilisée pour ces erreurs.

Cette fonction a été ajoutée en MySQL 4.1.1.

Valeur retournée

Une chaîne terminée par null, qui contient le code d'erreur SQLSTATE.

Voir aussi

Voir Section 24.2.3.12, « mysql_errno() »24.2.3.12. mysql_errno(). Voir Section 24.2.3.13, « mysql_error() »24.2.3.13. mysql_error(). Voir Section 24.2.7.26, « mysql_stmt_sqlstate() »24.2.7.26. mysql_stmt_sqlstate().

24-B-3-bd. mysql_ssl_set()

int mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)

Description

mysql_ssl_set() sert à établir des connexions sécurisées par SSL. Elle doit être appelée avec mysql_real_connect().

mysql_ssl_set() ne fait rien à moins que le support OpenSSL soit activé dans la bibliothèque cliente.

mysql est un gestionnaire de connexions, retourné par mysql_init(). Les autres paramètres sont les suivants.

  • key est le chemin jusqu'au fichier de clé.
  • cert est le chemin jusqu'au fichier de certificat.
  • ca est le chemin jusqu'au fichier d'autorité de certification.
  • capath est le chemin jusqu'au dossier qui contient les autorités de certification SSL reconnues, au format PEM.
  • cipher est une liste de chiffrements autorisés avec SSL.

Tous les paramètres SSL inutilisés doivent être fournis avec la valeur NULL.

Valeur retournée

Cette fonction retourne toujours 0. Si la configuration SSL est incorrecte, mysql_real_connect() va retourner une erreur lors de la tentative de connexion.

24-B-3-be. mysql_stat()

char *mysql_stat(MYSQL *mysql)

Description

Retourne une chaîne de caractères contenant des informations similaires à celles fournies par la commande mysqladmin status. Cela inclut le temps de fonctionnement en secondes et le nombre de threads en cours d'exécution, questions, rechargement, et tables ouvertes.

Valeur de retour

Une chaîne de caractères décrivant l'état du serveur. NULL si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-bf. mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

Description

Vous devez appeler mysql_store_result() ou mysql_use_result() pour chaque requête qui récupère des données avec succès (SELECT, SHOW, DESCRIBE, EXPLAIN).

Vous n'avez pas à appeler mysql_store_result() ou mysql_use_result() pour d'autres requêtes, mais cela ne posera pas de problèmes ou ne ralentira pas vos scripts si vous appelez mysql_store_result() en tout cas. Vous pouvez savoir si la requête n'a pas renvoyé de résultat en vérifiant si mysql_store_result() retourne 0 (nous verrons cela plus tard).

Si vous voulez savoir si la requête devrait renvoyer un jeu de résultats ou non, vous pouvez utiliser mysql_field_count() pour vérifier. Voir Section 24.2.3.20, « mysql_field_count() »24.2.3.20. mysql_field_count().

mysql_store_result() lit le résultat en entier et le stocke dans le client, alloue une structure MYSQL_RES, et place le résultat dans cette structure.

mysql_store_result() retourne un pointeur nul si la requête n'a pas retourné un jeu de résultats (si la requête était, par exemple, un INSERT).

mysql_store_result() retourne aussi un pointeur nul si la lecture à partir du jeu de résultats échoue. Vous pouvez vérifier la présence d'erreurs en regardant si mysql_error() ne retourne pas de pointeur nul, si mysql_errno() retourne <> 0, ou si mysql_field_count() retourne <> 0.

Un jeu de résultat vide est retourné si aucune ligne n'est retournée. (Un jeu de résultats vide diffère d'un pointeur nul en tant que valeur de retour.)

Une fois que vous avez appelé mysql_store_result() et obtenu un résultat qui n'est pas un pointeur nul, vous devez appeler mysql_num_rows() pour trouver combien de lignes contient le jeu de résultats.

Vous pouvez appeler mysql_fetch_row() pour récupérer des lignes à partir du jeu de résultats, ou mysql_row_seek() et mysql_row_tell() pour obtenir ou changer la ligne courante dans le jeu de résultats.

Vous devez appeler mysql_free_result() une fois que vous n'avez plus besoin du résultat.

Voir Section 24.2.13.1, « Pourquoi est-ce que mysql_store_result() retourne parfois NULL après que mysql_query() ait réussi »24.2.13.1. Pourquoi est-ce que mysql_store_result() retourne parfois NULL après que mysql_query() ait réussi.

Valeur de retour

Une structure de résultat MYSQL_RES. NULL si une erreur survient.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-bg. mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

Description

Retourne l'identifiant du thread de la connexion courante. Cette valeur peut être utilisée comme argument de mysql_kill() pour terminer ce thread.

Si la connexion est perdue et que vous vous reconnectez via mysql_ping(), l'identifiant du thread changera. Cela signifie que cela ne sert à rien de récupérer l'identifiant du thread et de le sauvegarder pour l'utiliser plus tard. Vous devez le récupérer quand vous en avez besoin.

Valeur de retour

L'identifiant du thread de la connexion courante.

Erreurs

Aucune.

24-B-3-bh. mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

Description

Vous devez appeler mysql_store_result() ou mysql_use_result() pour chaque requête qui récupère des données avec succès (SELECT, SHOW, DESCRIBE, EXPLAIN).

mysql_use_result() initialise un jeu de résultats, mais ne l'enregistre pas dans le client comme le fait mysql_store_result(). À la place, chaque ligne doit être récupérée manuellement à l'aide de la commande mysql_fetch_row(). Cela lit le résultat directement à partir du serveur sans l'enregistrer dans une table temporaire ou un tampon local, ce qui est plus rapide et utilise moins de mémoire que mysql_store_result(). Le client n'allouera de la mémoire que pour la ligne courante et un tampon de communication qui peut aller jusqu'à max_allowed_packet octets.

D'une autre côté, vous ne devez pas utiliser mysql_use_result() si vous faites beaucoup de traitements pour chaque ligne côté client, ou que le résultat est envoyé à un écran où l'utilisateur peut entrer ^S (arrêt défilement). Cela bloquera le serveur et empêchera les autres threads de mettre à jour n'importe quelle table à partir de laquelle les données sont lues.

Lors de l'utilisation de mysql_use_result(), vous devez exécuter mysql_fetch_row() jusqu'à ce que NULL soit retourné, sinon, les lignes non retournées seront incluses dans le jeu de résultats de votre prochaine requête. L'API C donnera l'erreur Commands out of sync; you can't run this command now si vous oubliez de le faire !

Vous ne devez pas utiliser mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_rows(), ou mysql_affected_rows() avec un résultat retourné par mysql_use_result(), de même, vous ne devez pas exécuter d'autres requêtes tant que la commande mysql_use_result() n'est pas terminée. (Toutefois, après avoir récupéré toutes les lignes, mysql_num_rows() retournera correctement le nombre de lignes récupérées.)

Vous devez appeler mysql_free_result() lorsque vous n'avez plus besoin du jeu de résultats.

Valeur de retour

Une structure de résultat MYSQL_RES. NULL si une erreur survient.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes n'ont pas été exécutées dans le bon ordre.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL ne répond pas.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue au cours la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue s'est produite.
24-B-3-bi. mysql_warning_count()

unsigned int mysql_warning_count(MYSQL *mysql)

Description

Retourne le nombre d'alertes générées durant l'exécution de la dernière commande SQL. Disponible depuis MySQL 4.1.

Valeur retournée

Le nombre d'alertes.

Erreurs

Aucune.

24-B-3-bj. mysql_commit()

my_bool mysql_commit(MYSQL *mysql)

Description

Valide la transaction courante. Disponible depuis MySQL 4.1

Valeurs retournées

Zéro si la fonction réussit, non nul si une erreur survient.

Erreurs

Aucune

24-B-3-bk. mysql_rollback()

my_bool mysql_rollback(MYSQL *mysql)

Description

Annule la transaction courante. Disponible avec MySQL 4.1

Valeurs retournées

Zéro si l'annulation a réussi, et non nul si une erreur est survenue.

Erreurs

Aucune.

24-B-3-bl. mysql_autocommit()

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

Description

Active ou désactive le mode d'autovalidation (autocommit). Si le paramètre mode vaut 1, l'autovalidation est activée. Dans le cas où il vaut 0, l'autovalidation est désactivée. Disponible depuis MySQL 4.1

Valeurs retournées

Zéro si la fonction réussit. Non nul si une erreur survient.

Erreurs

Aucune.

24-B-3-bm. mysql_more_results()

my_bool mysql_more_results(MYSQL *mysql)

Description

Retourne TRUE s'il y a d'autres résultats disponibles pour la requête courante, et si l'application doit appeler mysql_next_result() pour lire ces résultats. Disponible en MySQL 4.1

Valeurs retournées

TRUE si d'autres résultats existent. FALSE s'il n'y a plus d'autres résultats disponibles.

Notez que dans la plupart des cas, vous pouvez appeler mysql_next_result() pour voir s'il existe plus d'un résultat, et initier le prochain jeu de résultats si c'est le cas.

Voir Section 24.2.9, « Gestion des commandes multiples avec l'interface C »24.2.9. Gestion des commandes multiples avec l'interface C. Voir Section 24.2.3.66, « mysql_next_result() »24.2.3.66. mysql_next_result().

Erreurs

Aucune.

24-B-3-bn. mysql_next_result()

int mysql_next_result(MYSQL *mysql)

Description

S'il existe des résultats disponibles, mysql_next_result() va lire la prochaine ligne, et retourne son statut à l'application. Disponible depuis MySQL 4.1

Notez que vous devez appeler mysql_free_result() pour la précédente requête, si elle retournait un jeu de résultats.

Après avoir appelé mysql_next_result() l'état de la connexion est le même que si vous aviez appelé mysql_real_query() pour la requête suivante. Cela signifie que vous pouvez maintenant appeler mysql_store_result(), mysql_warning_count(), mysql_affected_rows(), etc. sur la connexion.

Si mysql_next_result() retourne une erreur, aucune autre commande ne pourra être exécutée, et il n'y a pas d'autres résultats à lire.

Voir Section 24.2.9, « Gestion des commandes multiples avec l'interface C »24.2.9. Gestion des commandes multiples avec l'interface C.

Valeurs retournées

Valeur retournée

Description

0

Requête réussie et il reste des résultats

-1

Requête réussie et il ne reste pas de résultat

>0

Une erreur est survenue

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été exécutées dans un ordre invalide. Par exemple, si vous n'avez pas appelé mysql_use_result() avec un résultat précédent.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL s'est éteint.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue durant la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

24-B-4. Fonctions C de commandes préparées

Depuis MySQL 4.1, vous pouvez aussi utiliser les commandes préparées en utilisant le gestionnaire « MYSQL_STMT », qui supporte l'exécution de commandes multiples, avec liaison en entrée et sortie.

L'exécution de requêtes préparées est un moyen efficace d'exécuter une requête plus d'une fois. La requête est préparée, ou analysée une première fois. Elle est ensuite exécutée une ou plusieurs fois plus tard, en utilisant un pointeur de commandes qui est retourné durant la préparation.

Un autre avantage des commandes préparées est qu'elles utilisent un protocole binaire qui rend les transferts entre le client et le serveur bien plus efficaces que l'ancien protocole MySQL.

Les commandes préparées sont plus rapides que les exécutions directes de requêtes qui sont exécutées plus d'une fois, notamment parce que la requête est analysée une seule fois. Dans le cas de l'exécution directe, la requête est analysée à chaque fois. Les commandes préparées permettent de réduire le trafic réseau durant l'exécution, car seules les données paramètres sont échangées.

24-B-5. Types de données de l'API C

Note : les requêtes préparées sont susceptibles d'être revues. Les informations ci-dessous sont destinées aux nouveaux utilisateurs, mais soyez prévenus qu'elles peuvent changer. Des modifications incompatibles ont été faites en MySQL 4.1.2. Voyez Section 24.2.7, « Description des fonctions C pour les requêtes préparées »24.2.7. Description des fonctions C pour les requêtes préparées pour plus de détails.

Les requêtes préparées utilisent principalement les deux structures MYSQL_STMT et MYSQL_BIND :

  • MYSQL_STMT
    Cette structure représente un pointeur de commandes sur une commande préparée. Elle sert pour toutes les fonctions liées aux commandes.
    La commande est initialisée lorsque la requête est préparée en utilisant mysql_prepare().
    La structure est utilisée par toutes les fonctions ultérieures, liées aux commandes préparées.
    La structure MYSQL_STMT n'a pas de membre utilisable par l'application.
    Une connexion peut avoir de multiples pointeurs de commandes, et la limite ne dépend que des ressources système.
  • MYSQL_BIND
    Cette structure est utilisée pour lier les paramètres avec des buffers, avec mysql_bind_param(), pour utilisation avec mysql_execute(), ainsi que pour lier les résultats avec des buffers via mysql_bind_result()m, lors de la lecture de données avec mysql_fetch().
    La structure MYSQL_BIND contient les membres suivants. Chacun est utilisé pour la lecture et l'écriture, mais leur objectif est parfois différent, en fonction du sens de communication.

    • enum enum_field_types buffer_type
      Le type de buffer. Les valeurs possibles pour buffer_type sont listées plus loin dans cette section. Pour l'envoi, buffer_type indique le type de valeur que vous allez fournir, lors de l'association de paramètres. Pour la réception, cela indique le type de valeur que vous pouvez lire dans le buffer de résultats.
    • void *buffer
      Pour l'envoi, c'est un pointeur sur le buffer où sont stockées les valeurs du paramètre de la requête. Pour la réception, c'est un pointeur sur la valeur retournée. Pour les types numériques, buffer pointe sur une variable avec le bon type C. Si vous associez la variable avec une colonne qui a un attribut UNSIGNED, la variable doit être de type C unsigned. Pour les colonnes de type date, buffer doit pointer sur une structure MYSQL_TIME. Pour les caractères et les chaînes binaires, buffer doit pointer sur un buffer de caractères.
    • unsigned long buffer_length
      La taille de *buffer en octets. Pour les caractères et les données binaires C, buffer_length spécifie la taille de *buffer à utiliser comme paramètre s'il est utilisé avec mysql_bind_param(), ou la taille lue dans le résultat s'il est utilisé avec mysql_bind_result().
    • long *length
      Un pointeur sur une variable unsigned long qui indique le nombre réel d'octets stockés dans *buffer. length est utilisé pour les données de type caractère ou binaire. Pour l'envoi de données, length pointe sur une variable unsigned long qui indique la taille des valeurs des paramètres stockés dans *buffer, cette valeur est utilisée par mysql_execute(). Si length est un pointeur null, le protocole suppose que les données caractères ou binaires sont terminées par null. Pour la lecture, mysql_fetch() place la taille de la valeur de la colonne retournée dans la variable length.
      length est ignorée pour les valeurs numériques et temporelles, car la taille de ces valeurs est déterminée par la valeur de buffer_type.
    • my_bool *is_null
      Ce membre pointe sur une variable my_bool qui est true si la valeur est NULL, et false si elle n'est pas NULL. Pour l'envoi, donnez à *is_null la valeur de true pour indiquer que la valeur que vous émettez est NULL. Pour la réception, cette valeur sera true après avoir lu une ligne si le résultat est NULL.
  • MYSQL_TIME
    Cette structure est utilisée pour écrire et lire des données de type DATE, TIME et TIMESTAMP, directement avec le serveur. Cela se fait en donnant au membre buffer_type d'une structure MYSQL_BIND un des types temporels, et en donnant au membre buffer un pointeur sur une structure MYSQL_TIME.
    La structure MYSQL_TIME contient les membres suivants :

    • unsigned int year
      L'année.
    • unsigned int month
      Le mois de l'année.
    • unsigned int day
      Le jour du mois.
    • unsigned int hour
      L'heure du jour.
    • unsigned int minute
      La minute de l'heure.
    • unsigned int second
      La seconde de la minute.
    • my_bool neg
      Un booléen pour indiquer que le temps est négatif.
    • unsigned long second_part
      La partie décimale de la seconde. Ce membre est actuellement inutilisé.

    Seuls les membres d'une structure MYSQL_TIME qui s'appliquent à une valeur sont utilisés : les éléments year, month et day sont utilisés pour les types DATE, DATETIME et TIMESTAMP, les éléments hour, minute et second sont utilisés pour les types TIME, DATETIME et TIMESTAMP. Voir Section 24.2.10, « Gestion des dates et horaires avec l'interface C »24.2.10. Gestion des dates et horaires avec l'interface C.

La table suivante montre les valeurs permises, qui peuvent être spécifiées dans le membre buffer_type des structures MYSQL_BIND. La table montre aussi les types SQL qui correspondent à chaque type de buffer_type, et, pour les types numériques et temporels, le type C correspondant.

buffer_type Valeur

Type SQL

Type C

MYSQL_TYPE_TINY

TINYINT

char

MYSQL_TYPE_SHORT

SMALLINT

short int

MYSQL_TYPE_LONG

INT

long int

MYSQL_TYPE_LONGLONG

BIGINT

long long int

MYSQL_TYPE_FLOAT

FLOAT

float

MYSQL_TYPE_DOUBLE

DOUBLE

double

MYSQL_TYPE_TIME

TIME

MYSQL_TIME

MYSQL_TYPE_DATE

DATE

MYSQL_TIME

MYSQL_TYPE_DATETIME

DATETIME

MYSQL_TIME

MYSQL_TYPE_TIMESTAMP

TIMESTAMP

MYSQL_TIME

MYSQL_TYPE_STRING

CHAR

 

MYSQL_TYPE_VAR_STRING

VARCHAR

 

MYSQL_TYPE_TINY_BLOB

TINYBLOB/TINYTEXT

 

MYSQL_TYPE_BLOB

BLOB/TEXT

 

MYSQL_TYPE_MEDIUM_BLOB

MEDIUMBLOB/MEDIUMTEXT

 

MYSQL_TYPE_LONG_BLOB

LONGBLOB/LONGTEXT

 

Des conversions implicites de type peuvent survenir dans les deux directions de communication.

24-B-6. Présentation des fonctions de l'interface C

Note : les fonctions pour les commandes préparées sont 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 »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. Voir Section 24.2.7, « Description des fonctions C pour les requêtes préparées »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 métadonnées de la commande préparée, sous forme d'un jeu de résultats.

mysql_stmt_param_count()

Retourne le nombre de paramètres d'une commande préparée.

mysql_stmt_param_metadata()

Retourne les métadonnées des paramètres, sous forme d'un jeu de résultats.

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ées 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 à un numéro de ligne arbitraire dans un jeu de résultats.

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ésultats 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étadonnées de résultat sous la forme d'une structure MYSQL_RES avec mysql_prepare_result().

Vous pouvez fournir les buffers de résultats 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(). Voir Section 24.2.7.25, « mysql_stmt_send_long_data() »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 toutes les ressources allouées soient détruites.

Étapes 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éussit, 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ésultats.
  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ésultats, 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 ligne.

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éta-informations si un résultat est attendu. La syntaxe et la sémantique de la requête sont vérifiées 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 lignes affectées 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 buffers 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, ainsi que les codes d'erreur SQLSTATE avec les fonctions mysql_stmt_errno(), mysql_stmt_error() et mysql_stmt_sqlstate(), respectivement.

24-B-7. Description des fonctions C pour les requêtes préparées

Vous devez utiliser ces fonctions lorsque vous voulez préparer et exécuter des commandes.

Note : l'API des commandes préparées est en cours de révision. Ces informations sont destinées aux nouveaux utilisateurs, mais soyez conscients que l'API peut changer sans préavis.

En MySQL 4.1.2, les noms de plusieurs fonctions de commandes préparées ont changé :

Ancien nom

Nouveau nom

mysql_bind_param()

mysql_stmt_bind_param()

mysql_bind_result()

mysql_stmt_bind_result()

mysql_prepare()

mysql_stmt_prepare()

mysql_execute()

mysql_stmt_execute()

mysql_fetch()

mysql_stmt_fetch()

mysql_fetch_column()

mysql_stmt_fetch_column()

mysql_param_count()

mysql_stmt_param_count()

mysql_param_result()

mysql_stmt_param_metadata()

mysql_get_metadata()

mysql_stmt_result_metadata()

mysql_send_long_data()

mysql_stmt_send_long_data()

Toutes les fonctions qui utilisent une structure MYSQL_STMT sont préfixées par mysql_stmt_.

De plus, en version 4.1.2, la signature de la fonction mysql_stmt_prepare() a changé en int mysql_stmt_prepare(MYSQL_STMT *stmt, const char *query, unsigned long length). Pour créer un pointeur MYSQL_STMT, utilisez la fonction mysql_stmt_init().

24-B-7-a. mysql_stmt_affected_rows()

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

Description

Retourne le nombre total de lignes modifiées par la dernière commande. Cette fonction peut être appelée immédiatement après la fonction mysql_execute() pour les commandes UPDATE, DELETE ou INSERT. Pour les commandes SELECT, mysql_stmt_affected() fonctionne comme mysql_num_rows().

Valeurs retournées

Un entier supérieur à zéro indique le nombre de lignes affectées ou lues. Zéro indique qu'aucune ligne n'a été modifiée durant une commande UPDATE, ou qu'aucune ligne n'a vérifié la clause WHERE dans la requête, ou qu'aucune requête n'a été exécutée. -1 indique que la requête a retourné une erreur, ou que, pour une requête SELECT, mysql_stmt_affected_rows() a été appelée avant mysql_fetch(). Comme mysql_stmt_affected_rows() retourne une valeur non signée, vous pouvez surveiller la valeur -1 en analysant la valeur retournée par (my_ulonglong)-1 (ou (my_ulonglong)~0, qui est équivalent).

Erreurs

Aucune.

Exemple

Pour une illustration de mysql_stmt_affected_rows() voyez l'exemple de Section 24.2.7.10, « mysql_stmt_execute() »24.2.7.10. mysql_stmt_execute().

24-B-7-b. mysql_stmt_attr_get()

int mysql_stmt_attr_get(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, void *arg)

Description

Sert à lire la valeur courante pour un attribut de commande.

L'argument option est le nom de l'option que vous voulez lire, le pointeur arg doit pointer sur une variable qui contient la valeur de l'option. Si l'option est un entier, alors arg doit être un pointeur.

Voyez mysql_stmt_attr_set pour avoir la liste des options et leur type. Voir Section 24.2.7.3, « mysql_stmt_attr_set() »24.2.7.3. mysql_stmt_attr_set().

Valeur retournée

0 si tout va bien. 1 si attr_type est inconnu.

Erreurs

aucune

24-B-7-c. mysql_stmt_attr_set()

int mysql_stmt_attr_set(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, const void *arg)

Description

Sert à modifier le comportement d'une commande. Cette fonction peut être appelée plusieurs fois.

L'argument option est le nom de l'option que vous voulez modifier, le pointeur arg doit pointer sur une variable qui contient la valeur de l'option. Si l'option est un entier, alors arg doit être un pointeur.

Valeurs possibles pour les options :

Option

Type d'argument

Fonction

STMT_ATTR_UPDATE_MAX_LENGTH

my_bool *

Si la valeur est 1 : modifie les méta-données MYSQL_FIELD->max_length dans mysql_stmt_store_result().

Valeur retournée

0 si tout va bien. 1 si attr_type est inconnu.

Erreurs

aucune

24-B-7-d. mysql_stmt_bind_param()

my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Description

mysql_stmt_bind_param() sert à lire des données aux variables de requêtes dans une commande SQL, préparée avec mysql_stmt_prepare(). Elle utilise les structures MYSQL_BIND pour fournir les données. bind est l'adresse d'un tableau de structures MYSQL_BIND. La bibliothèque cliente attend un tableau contenant un élément pour chaque variable de requête '?' qui est présente dans la requête.

Supposez que vous ayez préparé la commande suivante :

 
Sélectionnez
INSERT INTO mytbl VALUES(?,?,?)

Lorsque vous liez les paramètres, le tableau de structures MYSQL_BIND doit contenir trois éléments, et peut être déclaré comme ceci :

 
Sélectionnez
MYSQL_BIND bind[3];

Les membres de chaque structure MYSQL_BIND doivent être configurés comme décrit dans la section Section 24.2.5, « Types de données de l'API C »24.2.5. Types de données de l'API C.

Valeurs retournées

Zéro, si l'association a réussi. Non nul si une erreur est survenue.

Erreurs

  • CR_INVALID_BUFFER_USE
    Indique si les données seront fournies par bloc et si le type de buffer n'est pas chaîne, ou binaire.
  • CR_UNSUPPORTED_PARAM_TYPE
    La conversion n'est pas supportée. Éventuellement, la valeur de buffer_type est invalide, ou n'est pas d'un type supporté.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

Exemple

Pour un exemple avec mysql_stmt_bind_param(), voyez la fonction Section 24.2.7.10, « mysql_stmt_execute() »24.2.7.10. mysql_stmt_execute().

24-B-7-e. mysql_stmt_bind_result()

my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Description

mysql_stmt_bind_result() est utilisé pour lier (bind) les colonnes du résultat aux données et taille des buffers. Lorsque mysql_stmt_fetch() est appelée pour lire les données de la ligne suivante, le protocole client/serveur MySQL place les données des colonnes liées dans le buffer désigné.

Toutes les colonnes doivent être liées avant l'appel à mysql_stmt_fetch(). Le paramètre bind désigne l'adresse d'un tableau de structures MYSQL_BIND. La bibliothèque du client s'attend à recevoir un tableau contenant un élément correspondant à chaque colonne du résultat. Dans le cas contraire, mysql_stmt_fetch() va ignorer la nouvelle ligne lue. Les buffers doivent également être assez grands pour stocker les valeurs, car le protocole ne retourne pas les valeurs par morceaux.

Une colonne peut être liée ou ré-associée à n'importe quel moment, y compris pendant la réception des données. La nouvelle liaison devient effective au prochain appel de mysql_stmt_fetch(). Supposons qu'une application lie les colonnes à un résultat et appelle mysql_stmt_fetch(). Le protocole client/serveur va stocker les données dans les buffers associés. Supposez maintenant que l'application lie les colonnes à un nouveau jeu de buffers. Le protocole ne mettra aucune donnée dans ces nouveaux buffers tant qu'il n'y aura pas de nouvel appel à mysql_stmt_fetch().

Pour lier une colonne, l'application appelle la fonction mysql_stmt_bind_result() en passant le type, l'adresse du buffer et l'adresse de sa taille. Les membres requis de chaque MYSQL_BIND sont décrits Section 24.2.5, « Types de données de l'API C »24.2.5. Types de données de l'API C.

Valeurs retournées

Zéro si la liaison est effectuée avec succès. Une valeur non nulle si une erreur est survenue.

Erreurs

  • CR_UNSUPPORTED_PARAM_TYPE
    La conversion n'est pas supportée. Il est possible que la valeur de buffer_type soit erronée ou ne fasse pas partie de la liste des types supportés.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

Exemple

Référez-vous à l'exemple de la Section 24.2.7.13, « mysql_stmt_fetch() »24.2.7.13. mysql_stmt_fetch() pour l'utilisation de la fonction mysql_stmt_bind_result().

24-B-7-f. mysql_stmt_close()

my_bool mysql_stmt_close(MYSQL_STMT *)

Description

Termine la commande préparée. mysql_stmt_close() va aussi désallouer le pointeur de commande alloué par stmt.

Si les résultats de la requête courante sont en attente, ou non lus, ils seront annulés. Le prochain appel pourra donc être exécuté.

Valeur retournée

Zéro si la commande a pu être terminée. Une valeur non nulle si une erreur est survenue.

Erreurs

  • CR_SERVER_GONE_ERROR
    Le serveur MySQL s'est éteint.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

Exemple

Pour une illustration de la fonction mysql_stmt_close() voyez un exemple avec Section 24.2.7.10, « mysql_stmt_execute() »24.2.7.10. mysql_stmt_execute().

24-B-7-g. mysql_stmt_data_seek()

void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)

Description

Place le pointeur de résultats à une ligne arbitraire. La valeur de offset est un numéro de ligne, et doit être dans l'intervalle 0 à mysql_stmt_num_rows(stmt)-1.

Cette fonction impose que la structure du jeu de résultats soit entièrement téléchargée : mysql_stmt_data_seek() ne peut être utilisée qu'avec mysql_stmt_store_result().

Valeurs retournées

Aucune.

Erreurs

Aucune.

24-B-7-h. mysql_stmt_errno()

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

Description

Pour la commande spécifiée par stmt, mysql_stmt_errno() retourne le code d'erreur de la plus récente fonction d'API appelée, qu'elle ait réussi ou échoué. Une valeur de zéro indique qu'il n'y a pas eu d'erreur. Les numéros d'erreurs client sont listés dans le fichier d'entêtes errmsg.h. Les messages d'erreurs serveur sont listés dans le fichier d'entêtes mysqld_error.h. Dans la distribution source de MySQLm vous pouvez trouver une liste complète des messages d'erreurs et de leur numéro, dans le fichier Docs/mysqld_error.txt. Les codes d'erreur du serveur sont aussi listés dans Chapitre 26, Gestion des erreurs avec MySQLChapitre 26. Gestion des erreurs avec MySQL.

Valeurs retournées

Une valeur représentant un code d'erreur. Zéro représente l'absence d'erreur.

Erreurs

Aucune

24-B-7-i. mysql_stmt_error()

char *mysql_stmt_error(MYSQL_STMT *stmt)

Description

Pour la commande spécifiée par stmt, mysql_stmt_error() retourne le message d'erreur de la fonction d'API la plus récemment appelée, qu'elle ait réussi ou pas. Une chaîne vide ("") est retournée si aucune erreur n'est survenue. Cela signifie que les instructions suivantes sont identiques :

 
Sélectionnez
if (mysql_stmt_errno(stmt))
{
  // une erreur est survenue
}

if (mysql_stmt_error(stmt))
{
  // une erreur est survenue
}

La langue utilisée pour les messages d'erreurs du client MySQL peut être modifiée à la compilation de la bibliothèque cliente MySQL. Actuellement, vous pouvez choisir les messages d'erreur dans plusieurs langues.

Valeurs retournées

Une chaîne de caractères qui décrit l'erreur. Une chaîne vide signifie qu'il n'y a pas eu d'erreur.

Erreurs

Aucune

24-B-7-j. mysql_stmt_execute()

int mysql_stmt_execute(MYSQL_STMT *stmt)

Description

mysql_stmt_execute() exécute la requête préparée, associée avec le pointeur 'stmt'. Les valeurs des marqueurs de paramètres seront envoyées au serveur durant cet appel, pour que le serveur remplace les marqueurs avec les nouvelles valeurs.

Si la commande est UPDATE, DELETE ou INSERT, le nombre total de lignes changées, modifiées ou insérées est accessible avec la fonction mysql_stmt_affected_rows. Si la requête retourne un résultat, alors vous devez appeler la fonction mysql_stmt_fetch() pour lire les données avant d'appeler toute autre fonction de traitement du résultat. Pour plus d'informations sur comment lire les données binaires, voyez aussi Section 24.2.7.13, « mysql_stmt_fetch() »24.2.7.13. mysql_stmt_fetch().

Valeurs retournées

Zéro si l'exécution a réussi. Non zéro si une erreur est survenue. Le code d'erreur et le message peuvent être obtenus en appelant les fonctions mysql_stmt_errno() et mysql_stmt_error().

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été exécutées dans un ordre invalide.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL s'est éteint.
  • CR_SERVER_LOST
    La connexion a été perdue durant la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

Exemple

L'exemple suivant explique l'utilisation de mysql_prepare, mysql_param_count, mysql_bind_param, mysql_stmt_execute et mysql_stmt_affected_rows().

 
Sélectionnez
MYSQL_BIND   bind[3];
MYSQL_STMT   *stmt;
ulonglong    affected_rows;
long         length;
unsigned int param_count;
int          int_data;
short        small_data;
char         str_data[50], query[255];
my_bool      is_null;

  /* Passe en mode d'auto commit */
  mysql_autocommit(mysql, 1);
  
  if (mysql_query(mysql,"DROP TABLE IF EXISTS test_table"))
  {
    fprintf(stderr, "\n suppression de table a échoué");
    fprintf(stderr, "\n %s", mysql_error(mysql));
    exit(0);
  }
  if (mysql_query(mysql,"CREATE TABLE test_table(col1 int, col2 varchar(50), \
                                                 col3 smallint,\
                                                 col4 timestamp(14))"))
  {
    fprintf(stderr, "\n la création de table a échoué");
    fprintf(stderr, "\n %s", mysql_error(mysql));
    exit(0);
  }
  
  /* Prépare une requête d'insertion de trois paramètres */
  strmov(query, "INSERT INTO test_table(col1,col2,col3) values(?,?,?)");
  if(!(stmt = mysql_prepare(mysql, query, strlen(query))))
  {
    fprintf(stderr, "\n la préparation de l\'insertion a échoué");
    fprintf(stderr, "\n %s", mysql_error(mysql));
    exit(0);
  }
  fprintf(stdout, "\n la préparation de l\'insertion a réussi");

  /* Lit le nombre de paramètres de la requête */
  param_count= mysql_param_count(stmt);

  fprintf(stdout, "\n total parameters in insert: %d", param_count);
  if (param_count != 3) /* valide le nombre de paramètres */
  {
    fprintf(stderr, "\n le nombre de paramètres retourné par MySQL est invalide");
    exit(0);
  }

  /* Lie les données aux paramètres */

  /* INTEGER PART */
  bind[0].buffer_type= MYSQL_TYPE_LONG;
  bind[0].buffer= (char *)&int_data;
  bind[0].is_null= 0;
  bind[0].length= 0;

  /* STRING PART */
  bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
  bind[1].buffer= (char *)str_data;
  bind[1].buffer_length= sizeof(str_data);
  bind[1].is_null= 0;
  bind[1].length= 0;

  /* SMALLINT PART */
  bind[2].buffer_type= MYSQL_TYPE_SHORT;
  bind[2].buffer= (char *)&small_data;
  bind[2].is_null= &is_null;
  bind[2].length= 0;
  is_null= 0;


  /* Lie les buffers */
  if (mysql_bind_param(stmt, bind))
  {
    fprintf(stderr, "\n param bind failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }

  /* Spécifie les données */
  int_data= 10;             /* integer */
  strcpy(str_data,"MySQL"); /* string  */

  /* INSERT SMALLINT data as NULL */
  is_null= 1;

  /* Exécute la requête */
  if (mysql_stmt_execute(stmt))
  {
    fprintf(stderr, "\n l\'exécution 1 a échoué");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }
    
  /* Lit le nombre de lignes affectées */   
  affected_rows= mysql_stmt_affected_rows(stmt);

  fprintf(stdout, "\n total affected rows: %lld", affected_rows);
  if (affected_rows != 1) /* validation du nombre de lignes affectées */
  {
    fprintf(stderr, "\n nombre de lignes affectées par MySQL invalide");
    exit(0);
  }

  /* Réexécute l'insertion, en modifiant les valeurs */
  int_data= 1000;             
  strcpy(str_data,"La base de données Open Source la plus populaire"); 
  small_data= 1000;         /* smallint */
  is_null= 0;               /* remet à zéro NULL */
 
  /* Exécute l'insertion : 2e */
  if (mysql_stmt_execute(stmt))
  {
    fprintf(stderr, "\n la deuxième exécution a échoué");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }
    
  /* Lit le nombre total de lignes affectées */   
  affected_rows= mysql_stmt_affected_rows(stmt);

  fprintf(stdout, "\n Nombre de lignes affectées : %lld", affected_rows);
  if (affected_rows != 1) /* valide le nombre de lignes affectées */
  {
    fprintf(stderr, "\n Nombre de lignes affectées invalides");
    exit(0);
  }

  /* Ferme la requête */
  if (mysql_stmt_close(stmt))
  {
    fprintf(stderr, "\n erreur lors de la fermeture de la commande");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }
  
  /* Efface la table */
  if (mysql_query(mysql,"DROP TABLE test_table"))
  {
    fprintf(stderr, "\n suppression de table a échoué");
    fprintf(stderr, "\n %s", mysql_error(mysql));
    exit(0);
  }
  fprintf(stdout, "Bravo! les commandes préparées MySQL fonctionnent!!");

Note : pour des exemples complets sur l'utilisation des commandes préparées, voyez le fichier tests/mysql_client_test.c. Ce fichier est disponible dans la distribution source de MySQL,ou dans le serveur BitKeeper.

24-B-7-k. mysql_stmt_free_result()

my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)

À définir.

Description

Valeur retournée

Erreurs

24-B-7-l. mysql_stmt_insert_id()

my_ulonglong mysql_stmt_insert_id(MYSQL_STMT *stmt)

Description

Retourne la valeur générée pour une colonne de type AUTO_INCREMENT par une requête préparée INSERT ou UPDATE. Utilisez cette fonction après avoir exécuté la commande INSERT sur la table qui contient la colonne AUTO_INCREMENT.

Voyez Section 24.2.3.33, « mysql_insert_id() »24.2.3.33. mysql_insert_id() pour plus de détails.

Valeurs retournées

La valeur générée pour la colonne AUTO_INCREMENT qui était automatiquement générée ou explicitement donnée durant l'exécution de la requête, ou la valeur générée par la dernière fonction LAST_INSERT_ID(expr). La valeur retournée est indéfinie si la commande n'a pas manipulé de valeur AUTO_INCREMENT.

Erreurs

Aucune.

24-B-7-m. mysql_stmt_fetch()

int mysql_stmt_fetch(MYSQL_STMT *stmt)

Description

mysql_stmt_fetch() retourne la ligne suivante dans le résultat. La fonction peut être appelée uniquement si le résultat existe, c'est-à-dire après mysql_stmt_execute() qui crée le résultat, ou après mysql_stmt_store_result(), qui est appelé après mysql_stmt_execute() pour mettre en buffer tout le résultat.

Si les lignes sont liées à des buffers avec mysql_stmt_bind_result(), la fonction retourne les données dans ces buffers pour toutes les colonnes de la ligne en cours, et les tailles sont retournées dans le pointeur de taille.

Notez que toutes les colonnes doivent être liées par l'application avant d'appeler mysql_stmt_fetch().

Si les données lues contiennent la valeur NULL, alors la valeur is_null de MYSQL_BIND contiendra TRUE, 1, ou sinon, les données et leur longueur seront retournées dans les variables *buffer et *length, basées sur le type de buffers spécifié par l'application. Tous les nombres ont une taille fixe, listée en octet ci-dessous. La taille des types chaînes dépend des données, comme indiqué dans data_length.

Type

Longueur

MYSQL_TYPE_TINY

1

MYSQL_TYPE_SHORT

2

MYSQL_TYPE_LONG

4

MYSQL_TYPE_LONGLONG

8

MYSQL_TYPE_FLOAT

4

MYSQL_TYPE_DOUBLE

8

MYSQL_TYPE_TIME

sizeof(MYSQL_TIME)

MYSQL_TYPE_DATE

sizeof(MYSQL_TIME)

MYSQL_TYPE_DATETIME

sizeof(MYSQL_TIME)

MYSQL_TYPE_TIMESTAMP

sizeof(MYSQL_TIME)

MYSQL_TYPE_STRING

data length

MYSQL_TYPE_VAR_STRING

data_length

MYSQL_TYPE_TINY_BLOB

data_length

MYSQL_TYPE_BLOB

data_length

MYSQL_TYPE_MEDIUM_BLOB

data_length

MYSQL_TYPE_LONG_BLOB

data_length

*data_length ne vaut rien d'autre que 'la taille réelle des données'.

Valeurs retournées

Valeur retournée

Description

0

Réussi. Les données ont été lues, et placées dans les buffers.

1

Une erreur est survenue. Le code d'erreur et le message d'erreur sont disponibles grâce aux fonctions mysql_stmt_errno() et mysql_stmt_error().

100, MYSQL_NO_DATA

Il ne reste plus de donnée ou de ligne.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été exécutées dans un ordre invalide.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL s'est éteint.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue durant la requête.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.
  • CR_UNSUPPORTED_PARAM_TYPE
    Si le buffer est de type MYSQL_TYPE_DATE, DATETIME, TIME ou TIMESTAMP et le type de champ n'est pas DATE, TIME, DATETIME or TIMESTAMP.
  • Toutes les autres erreurs de conversions non supportées sont disponibles avec mysql_bind_result().

Exemple

L'exemple ci-dessous explique l'utilisation de mysql_get_metadata(), mysql_bind_result() et mysql_stmt_fetch() Cet exemple s'attend à lire les deux lignes insérées dans l'exemple de Section 24.2.7.10, « mysql_stmt_execute() »24.2.7.10. mysql_stmt_execute().) La variable mysql est supposée être une connexion valide.

 
Sélectionnez
#define STRING_SIZE 50

#define SELECT_SAMPLE "SELECT col1, col2, col3, col4 FROM test_table"

MYSQL_STMT    *stmt;
MYSQL_BIND    bind[4];
MYSQL_RES     *prepare_meta_result;
MYSQL_TIME    ts;
unsigned long length[4];
int           param_count, column_count, row_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
my_bool       is_null[4];

/* Prépare une commande SELECT pour lire les données dans la table test_table */
stmt = mysql_prepare(mysql, SELECT_SAMPLE, strlen(SELECT_SAMPLE));
if (!stmt)
{
  fprintf(stderr, " mysql_prepare(), SELECT failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
fprintf(stdout, " prepare, SELECT successful\n");

/* Lit le nombre de paramètres de la commande */
param_count= mysql_param_count(stmt);
fprintf(stdout, " total parameters in SELECT: %d\n", param_count);

if (param_count != 0) /* validate parameter count */
{
  fprintf(stderr, " invalid parameter count returned by MySQL\n");
  exit(0);
}

/* Lit les métadonnées */
prepare_meta_result = mysql_get_metadata(stmt);
if (!prepare_meta_result)
{
  fprintf(stderr, " mysql_get_metadata(), returned no meta information\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Lit le nombre de colonnes de la requête */
column_count= mysql_num_fields(prepare_meta_result);
fprintf(stdout, " total columns in SELECT statement: %d\n", column_count);

if (column_count != 4) /* validate column count */
{
  fprintf(stderr, " invalid column count returned by MySQL\n");
  exit(0);
}

/* Exécute la requête SELECT */
if (mysql_execute(stmt))
{
  fprintf(stderr, " mysql_execute(), failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Lie les buffers de résultats pour les 4 colonnes avant de les lire */

/* INTEGER COLUMN */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= &is_null[0];
bind[0].length= &length[0];

/* STRING COLUMN */
bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= &is_null[1];
bind[1].length= &length[1];
 
/* SMALLINT COLUMN */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;       
bind[2].is_null= &is_null[2];
bind[2].length= &length[2];
 
/* TIMESTAMP COLUMN */
bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
bind[3].buffer= (char *)&ts;       
bind[3].is_null= &is_null[3];
bind[3].length= &length[3];

/* Lit les résultats */
if (mysql_bind_result(stmt, bind))
{
  fprintf(stderr, " mysql_bind_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Maintenant, lit les résultats dans les buffers */
if (mysql_stmt_store_result(stmt))
{
  fprintf(stderr, " mysql_stmt_store_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Lit toutes les lignes */
row_count= 0;
fprintf(stdout, "Fetching results ...\n");
while (!mysql_stmt_fetch(stmt))
{
  row_count++;
  fprintf(stdout, "  row %d\n", row_count);

  /* colonne 1 */
  fprintf(stdout, "   column1 (integer)  : ");
  if (is_null[0])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", int_data, length[0]);

  /* colonne 2 */
  fprintf(stdout, "   column2 (string)   : ");
  if (is_null[1])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %s(%ld)\n", str_data, length[1]);

  /* colonne 3 */
  fprintf(stdout, "   column3 (smallint) : ");
  if (is_null[2])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", small_data, length[2]);

  /* colonne 4 */
  fprintf(stdout, "   column4 (timestamp): ");
  if (is_null[3])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n",
                                               ts.year, ts.month, ts.day,
                                               ts.hour, ts.minute, ts.second,
                                               length[3]);
  fprintf(stdout, "\n");
}

/* Valide la ligne lue */
fprintf(stdout, " total rows fetched: %d\n", row_count);
if (row_count != 2)
{
  fprintf(stderr, " MySQL failed to return all rows\n");
  exit(0);
} 

/* Libère les métadonnées de résultat */
mysql_free_result(prepare_meta_result);


/* Ferme la commande */
if (mysql_stmt_close(stmt))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
24-B-7-n. mysql_stmt_fetch_column()

int mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind, unsigned int column, unsigned long offset)

Description

Lit une colonne depuis la ligne de résultat actuelle. Le paramètre bind fournit le buffer à alimenter. Il doit être défini de la même façon que pour la fonction mysql_stmt_bind_result(). column indique la colonne à lire. La première colonne possède l'indice 0. offset représente l'offset à partir duquel la lecture est effectuée. Il peut être utilisé pour lire les données par morceaux. Les données de départ sont à l'offset 0.

Valeur retournée

Zéro si les données ont été lues, une valeur non nulle si une erreur est survenue.

Erreurs

  • CR_INVALID_PARAMETER_NO

Un indice de colonne non valide.

  • CR_NO_DATA

La fin de la ligne est déjà atteinte.

24-B-7-o. mysql_stmt_field_count()

unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)

Description

Retourne le nombre de colonnes de la commande exécutée la plus récente. Cette valeur vaudra zéro pour les commandes, telles que INSERT ou DELETE, qui n'ont pas produit de résultat.

mysql_stmt_field_count() peut être appelé après la préparation de la commande avec mysql_stmt_prepare().

Cette fonction a été ajoutée en MySQL 4.1.3.

Valeurs retournées

Un entier non signé, représentant le nombre de colonnes, si un jeu de résultats existe.

Erreurs

Aucune.

24-B-7-p. mysql_stmt_init()

MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)

Description

Crée une structure MYSQL_STMT.

Valeurs retournées

Un pointeur sur une structure MYSQL_STMT en cas de succès. NULL s'il n'y a plus de mémoire.

Erreurs

  • CR_OUT_OF_MEMORY
    Plus de mémoire.
24-B-7-q. mysql_stmt_num_rows()

my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)

Description

Retourne le nombre de lignes dans le jeu de résultats.

L'utilisation de mysql_stmt_num_rows() dépend du fait que vous avez utilisé ou non mysql_stmt_store_result() pour rapatrier l'intégralité du résultat dans le client.

Si vous utilisez mysql_stmt_store_result(), mysql_stmt_num_rows() peut être appelé immédiatement.

Valeur retournée

Le nombre de lignes dans le jeu de résultats.

Erreurs

Aucun.

24-B-7-r. mysql_stmt_param_count()

unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)

Description

Retourne le nombre de marqueurs de paramètres présents dans la requête préparée.

Valeurs retournées

Un entier non signé, représentant le nombre de paramètres dans la requête.

Erreurs

Aucune.

Exemple

Pour une illustration de la fonction mysql_stmt_param_count(), voyez l'exemple de la fonction Section 24.2.7.10, « mysql_stmt_execute() »24.2.7.10. mysql_stmt_execute().

24-B-7-s. mysql_stmt_param_metadata()

MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)

Cette fonction ne fait rien actuellement.

24-B-7-t. mysql_stmt_prepare()

int mysql_stmt_prepare(MYSQL_STMT *stmt, const char *query, unsigned long length)

Description

Prépare la requête représentée par la chaîne terminée par NUL query, et retourne un pointeur de commande à utiliser ultérieurement pour les autres opérations. La requête doit contenir une commande SQL unique. Vous ne devez pas ajouter le point-virgule (';') ni \g de fin de requête.

L'application peut inclure une ou plusieurs variables de requête SQL, grâce au caractère point d'interrogation ('?'), placé dans la commande SQL, aux bons endroits.

Les variables de requêtes ne sont valides qu'à certaines places dans les commandes SQL. Par exemple, elles sont autorisées dans les listes VALUES() d'une commande INSERT (pour spécifier les valeurs des lignes), ou dans les clauses de comparaisons WHERE, pour spécifier une valeur de comparaison. Sinon, elles ne sont pas autorisées pour les identifiants (comme les noms de tables ou de colonnes), dans les listes de colonnes sélectionnées par la commande SELECT, ou pour spécifier un opérateur tel que =. Cette dernière restriction est due au fait qu'il serait impossible de déterminer le type de paramètre. En général, les variables ne sont autorisées que dans les commandes de manipulations de données (Data Manipulation Language (DML)), et non pas dans les commandes de définition des données (Data Definition Language (DDL).

Les variables de requêtes doivent être liées par l'application à des variables, avec la fonction mysql_stmt_bind_param() avant exécution.

Valeurs retournées

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été exécutées dans un ordre invalide.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SERVER_GONE_ERROR
    Le serveur s'est éteint durant l'exécution de la requête.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue.
  • CR_UNKNOWN_ERROR
    Erreur inconnue.

Si la préparation échoue, c'est-à-dire si mysql_stmt_prepare() retourne NULL), un message d'erreur peut être obtenu en appelant mysql_error().

Exemple

Pour une utilisation de mysql_stmt_prepare(), voyez l'exemple dans Section 24.2.7.10, « mysql_stmt_execute() »24.2.7.10. mysql_stmt_execute().

24-B-7-u. mysql_stmt_reset()

my_bool mysql_stmt_reset(MYSQL_STMT *stmt)

Description

Remet la commande préparée sur le client et sur le serveur à son état juste après la préparation. Actuellement, on s'en sert surtout pour remettre à zéro les données envoyées par mysql_stmt_send_long_data().

Pour préparer à nouveau la commande pour une autre commande, utilisez mysql_stmt_prepare().

Valeurs retournées

Zéro si la commande a été remise à zéro. Non nulle, si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été exécutées dans un ordre invalide.
  • CR_SERVER_GONE_ERROR
    Le serveur s'est éteint.
  • CR_SERVER_LOST
    La connexion au serveur a été perdue durant l'exécution.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.
24-B-7-v. mysql_stmt_result_metadata()

MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)

Description

Si la fonction mysql_prepare() a généré un résultat, alors mysql_stmt_result_metadata() retourne les métadonnées de résultats sous la forme d'une structure MYSQL_RES, qui peut être utilisée ultérieurement pour traiter des méta-informations, telles que le nombre de champs et les informations individuelles de champs. Ce résultat peut être passé en argument à l'une des fonctions de champs suivantes, pour traiter les données :

  • mysql_num_fields()
  • mysql_fetch_field()
  • mysql_fetch_field_direct()
  • mysql_fetch_fields()
  • mysql_field_count()
  • mysql_field_seek()
  • mysql_field_tell()
  • mysql_free_result()

La structure de jeu de résultats doit être libérée une fois que vous en avez fini avec, grâce à la fonction mysql_free_result(). C'est similaire à la méthode pour libérer les ressources obtenues de mysql_store_result().

Le jeu de résultats retourné par mysql_stmt_result_metadata() contient uniquement des métadonnées. Il ne contient aucune ligne de résultat. Les lignes sont lues en utilisant la ressource de commande, avec la fonction mysql_stmt_fetch().

Valeurs retournées

Une structure de type MYSQL_RES. NULL si aucune métadonnée n'existe pour la requête préparée.

Erreurs

  • CR_OUT_OF_MEMORY
    Plus de mémoire
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

Exemple

Pour une illustration de la fonction mysql_stmt_result_metadata(), voyez l'exemple de la fonction Section 24.2.7.13, « mysql_stmt_fetch() »24.2.7.13. mysql_stmt_fetch().

24-B-7-w. mysql_stmt_row_seek()

MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)

Description

Place le pointeur de lignes à une position arbitraire dans le jeu de résultats. La valeur offset est un offset de ligne, qui doit être retourné par mysql_stmt_row_tell() ou par mysql_stmt_row_seek(). Cette valeur n'est pas un numéro de ligne : si vous voulez atteindre une ligne dans un résultat, à partir de son numéro, vous devez utiliser mysql_stmt_data_seek().

Cette fonction requiert que le jeu de résultats entier soit téléchargé, et donc, mysql_stmt_row_seek() ne peut être utilisé qu'avec mysql_stmt_store_result().

Valeur retournée

La position précédente du curseur de ligne. Cette valeur peut être passée à mysql_stmt_row_seek().

Erreurs

Aucune.

24-B-7-x. mysql_stmt_row_tell()

MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)

Description

Retourne la position courante du pointeur de ligne. C'est la position à laquelle le dernier appel à mysql_fetch() l'a laissé. Cette valeur peut être utilisée comme argument avec mysql_stmt_row_seek().

Vous ne devez utiliser mysql_stmt_row_tell() qu'après mysql_stmt_store_result().

Valeur retournée

La position courante du pointeur de lignes.

Erreurs

Aucune.

24-B-7-y. mysql_stmt_send_long_data()

my_bool mysql_stmt_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, unsigned long length)

Description

Permet à une application d'envoyer des données par parties au serveur. Cette fonction doit être utilisée pour envoyer des caractères ou du contenu binaire par parties dans une colonne (qui sera de type TEXT ou BLOB), avec un type de caractères ou de données binaires.

Le paramètre data est un pointeur sur un buffer qui contient les données pour le paramètre, représenté par parameter_number. Le paramètre length indique la quantité de données qui doit être envoyée, en octets.

Note : le prochain appel à mysql_stmt_execute() va ignorer les buffers de variables de requêtes, pour tous les paramètres qui ont été utilisés avec mysql_stmt_send_long_data() depuis le dernier appel à mysql_stmt_execute() ou mysql_stmt_reset().

Si vous voulez remettre à zéro cette fonction, utilisez mysql_stmt_reset(). Voir Section 24.2.7.21, « mysql_stmt_reset() »24.2.7.21. mysql_stmt_reset().

Valeurs retournées

Zéro si les données ont pu être envoyées au serveur. Non nul si une erreur est survenue.

Erreurs

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été envoyées dans un ordre invalide.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL s'est éteint.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_UNKNOWN_ERROR
    Yne erreur inconnue s'est produite.

Exemple

L'exemple ci-dessous explique comment envoyer des données par parties dans une colonne de type TEXT :

 
Sélectionnez
#define INSERT_QUERY "INSERT INTO test_long_data(text_column) VALUES(?)"
  
MYSQL_BIND bind[1];
long       length;

smtt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(INSERT_QUERY)))
{
  fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
 memset(bind, 0, sizeof(bind));
 bind[0].buffer_type= MYSQL_TYPE_STRING;
 bind[0].length= &length;
 bind[0].is_null= 0;

  /* Liaison des buffers */
if (mysql_stmt_bind_param(stmt, bind))
{
  fprintf(stderr, "\n param bind failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

   /* Envoi des données au serveur, par parties */
 if (!mysql_stmt_send_long_data(stmt,0,"MySQL",5))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

   /* Envoi des données suivantes */
 if (mysql_stmt_send_long_data(stmt,0," - The most popular open source database",40))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

   /* Exécution de la requête */
 if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, "\n mysql_stmt_execute failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
24-B-7-z. mysql_stmt_sqlstate()

const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)

Description

Pour la commande stmt, mysql_stmt_sqlstate() retourne une chaîne terminée par un null, contenant le code d'erreur SQLSTATE de la plus récente fonction de requête préparée qui a été utilisée. Le code d'erreur est constitué de 5 caractères. "00000" signifie « pas d'erreur ». Les valeurs sont spécifiées par les normes ANSI SQL et ODBC. Pour une liste des valeurs possibles, voyez Chapitre 26, Gestion des erreurs avec MySQLChapitre 26. Gestion des erreurs avec MySQL.

Notez que toutes les erreurs MySQL ne sont pas associées à une erreur SQLSTATE. La valeur "HY000" (erreur générale) sert pour les erreurs orphelines.

Cette fonction a été ajoutée en MySQL 4.1.1.

Valeur retournée

Une chaîne de caractères terminée par un null, contenant le code d'erreur SQLSTATE.

24-B-7-aa. mysql_stmt_store_result()

int mysql_stmt_store_result(MYSQL_STMT *stmt)

Description

Vous devez appeler la fonction mysql_stmt_store_result() pour chaque requête qui doit lire des données (SELECT, SHOW, DESCRIBE, EXPLAIN) et uniquement si vous voulez lire la totalité du résultat dans un buffer du client, pour que les appels suivants à mysql_fetch() retournent des données bufferisées.

Vous n'avez pas à appeler mysql_stmt_store_result() pour les requêtes suivantes, mais cela ne causera pas de ralentissement notable. Vous pouvez détecter si une requête n'a pas de résultat en vérifiant si mysql_prepare_result() retourne 0. Pour plus d'informations, voyez Section 24.2.7.22, « mysql_stmt_result_metadata() »24.2.7.22. mysql_stmt_result_metadata().

Note : MySQL ne calcule pas par défaut MYSQL_FIELD->max_length pour toutes les colonnes de mysql_stmt_store_result() car ce calcul ralentirait considérablement mysql_stmt_store_result() et la plupart des applications n'ont pas besoin de max_length. Si vous voulez max_length, vous pouvez appeler mysql_stmt_attr_set(MYSQL_STMT, STMT_ATTR_UPDATE_MAX_LENGTH, &flag) pour l'obtenir. Voir Section 24.2.7.3, « mysql_stmt_attr_set() »24.2.7.3. mysql_stmt_attr_set().

Valeurs retournées

Zéro si les résultats sont mis en buffer correctement, et non nul si une erreur survient.

Errors

  • CR_COMMANDS_OUT_OF_SYNC
    Les commandes ont été exécutées dans un ordre invalide.
  • CR_OUT_OF_MEMORY
    Plus de mémoire.
  • CR_SERVER_GONE_ERROR
    Le serveur MySQL s'est éteint.
  • CR_SERVER_LOST
    La connexion au serveur MySQL s'est interrompue durant la commande.
  • CR_UNKNOWN_ERROR
    Une erreur inconnue est survenue.

24-B-8. Problèmes avec l'interface C des commandes préparées

Voici la liste des problèmes connus avec les commandes préparées :

  • TIME, TIMESTAMP et DATETIME ne supportent pas les fractions de seconde (par exemple, issues de DATE_FORMAT().
  • Lors de la conversion d'un entier en chaîne, ZEROFILL est respecté avec les commandes préparées, même dans certains cas, où le serveur MySQL n'affiche pas les zéros initiaux (par exemple, avec MIN(number-with-zerofill)).
  • Lors de la conversion d'un nombre décimal en chaîne par le client, la valeur peut être légèrement différente pour le dernier chiffre.

24-B-9. Gestion des commandes multiples avec l'interface C

Depuis la version 4.1, MySQL supporte l'exécution de requêtes multiples dans une seule commande. Pour cela, vous devez activer l'option client CLIENT_MULTI_QUERIES lors de l'ouverture de la connexion.

Par défaut, mysql_query() ou mysql_real_query() ne retournent que le statut de la première requête, et les statuts suivants peuvent être obtenus avec mysql_more_results() et mysql_next_result().

 
Sélectionnez
  /* Connexion au serveur, avec l'option CLIENT_MULTI_QUERIES */
  mysql_real_query(..., CLIENT_MULTI_QUERIES);

  /* Exécution de plusieurs requêtes */
  mysql_query(mysql,"DROP TABLE IF EXISTS test_table;\
                     CREATE TABLE test_table(id int);\
                     INSERT INTO test_table VALUES(10);\
                     UPDATE test_table SET id=20 WHERE id=10;\
                     SELECT * FROM test_table;\
                     DROP TABLE test_table";
  while (mysql_more_results(mysql))
  {
    /* Traitement de tous les résultats */
    mysql_next_result(mysql);
    ...
    printf("total affected rows: %lld", mysql_affected_rows(mysql));
    ...
    if ((result= mysql_store_result(mysql))
    {
      /* Retourne un résultat, le traite */
    }
  }

24-B-10. Gestion des dates et horaires avec l'interface C

En utilisant le nouveau protocole binaire de MySQL 4.1 et plus récent, vous pouvez envoyer et recevoir les données de type (DATE, TIME, DATETIME et TIMESTAMP) avec la structure MYSQL_TIME. Les membres de cette structure sont décrits dans Section 24.2.5, « Types de données de l'API C »24.2.5. Types de données de l'API C.

Afin d'envoyer les données, il faut utiliser une requête préparée avec la fonction mysql_prepare(). Avant d'appeler la fonction mysql_execute(), pour exécuter la commande, utilisez la procédure suivante pour préparer chaque donnée :

  1. Dans la structure MYSQL_BIND, associée aux données, assignez au membre buffer_type le type de données que vous envoyez. Pour DATE, TIME, DATETIME, ou TIMESTAMP, utilisez buffer_type MYSQL_TYPE_DATE, MYSQL_TYPE_TIME, MYSQL_TYPE_DATETIME, ou MYSQL_TYPE_TIMESTAMP, respectivement.
  2. Donnez au membre buffer de la structure MYSQL_BIND, l'adresse de la structure MYSQL_TIME dans laquelle vous avez stocké votre valeur temporelle.
  3. Remplissez les membres de la structure MYSQL_TIME qui sont adaptés au type de données que vous passez.

Utilisez mysql_bind_param() pour lier les données à la requête. Puis, appelez mysql_execute().

Pour lire des données temporelles, la procédure est similaire, hormis le fait que vous donnez au membre buffer_type le type de données que vous attendez, et que buffer doit pointer sur l'adresse de la structure MYSQL_TIME qui va recevoir les données retournées. Utilisez mysql_bind_results() pour lier les buffers à la commande après avoir appelé mysql_execute() et avant de lire les résultats.

Voici un exemple qui réalise l'insertion de données DATE, TIME et TIMESTAMP. La variable mysql est supposée représenter une connexion valide.

 
Sélectionnez
MYSQL_TIME  ts;
MYSQL_BIND  bind[3];
MYSQL_STMT  *stmt;
  
  strmov(query, "INSERT INTO test_table(date_field, time_field,
                                        timestamp_field) VALUES(?,?,?");

  stmt= mysql_prepare(mysql, query, strlen(query))); 

  /* configure les trois buffers pour les trois paramètres */
  bind[0].buffer_type= MYSQL_TYPE_DATE;
  bind[0].buffer= (char *)&ts;  
  bind[0].is_null= 0;
  bind[0].length= 0;
  ..
  bind[1]= bind[2]= bind[0];
  ..

  mysql_bind_param(stmt, bind);

  /* Fournit les données à envoyer dans la structure ts */
  ts.year= 2002;
  ts.month= 02;
  ts.day= 03;

  ts.hour= 10;
  ts.minute= 45;
  ts.second= 20;

  mysql_execute(stmt);
  ..

24-B-11. Description des fonctions threadées de C

Vous devez utiliser les fonctions suivantes quand vous voulez créer un client threadé. Voir Section 24.2.15, « Comment faire un client MySQL threadé »24.2.15. Comment faire un client MySQL threadé.

24-B-11-a. my_init()

void my_init(void)

Description

Cette fonction doit être appelée une fois dans le programme avant tout appel à une fonction MySQL. Cela initialise quelques variables globales dont MySQL a besoin. Si vous utilisez une bibliothèque client sûre pour les threads, cela appellera aussi mysql_thread_init() pour ce thread.

Ceci est automatiquement appelé par mysql_init(), mysql_server_init() et mysql_connect().

Valeur de retour

Aucune.

24-B-11-b. mysql_thread_init()

my_bool mysql_thread_init(void)

Description

Cette fonction doit être appelée à chaque création de thread pour initialiser les variables spécifiques aux threads.

Elle est appelée automatiquement par my_init() et mysql_connect().

Valeur de retour

Aucune.

24-B-11-c. mysql_thread_end()

void mysql_thread_end(void)

Description

Cette fonction doit être appelée avant pthread_exit() pour libérer la mémoire allouée par mysql_thread_init().

Notez que cette fonction n'est pas invoquée automatiquement par la bibliothèque du client. Elle doit être invoquée explicitement pour éviter les pertes de mémoire.

Valeur de retour

Aucune.

24-B-11-d. mysql_thread_safe()

unsigned int mysql_thread_safe(void)

Description

Cette fonction indique si le client est compilé avec le support des threads (thread-safe).

Valeur de retour

1 indique que le client est thread-safe, 0 sinon.

24-B-12. Description des fonctions C du serveur embarqué

Vous devez utiliser les fonctions suivantes si vous voulez permettre à votre application d'être liée avec la bibliothèque du serveur embarqué MySQL. Voir Section 24.2.16, « libmysqld, la bibliothèque du serveur embarqué MySQL »24.2.16. libmysqld, la bibliothèque du serveur embarqué MySQL.

Si le programme est lié avec -lmysqlclient au lieu de -lmysqld, ces fonctions ne font rien. Cela permet de choisir d'utiliser un serveur embarqué MySQL, ou un serveur tournant à part sans avoir à changer votre code.

24-B-12-a. mysql_server_init()

int mysql_server_init(int argc, char **argv, char **groups)

Description

Cette fonction doit être appelée une fois dans le programme avant d'appeler toute autre fonction MySQL. Elle démarre le serveur et initialise tout sous-système (mysys, InnoDB, etc.) utilisé par le serveur. Si cette fonction n'est pas appelée, le programme plantera. Si vous utilisez le paquet DBUG fourni avec MySQL, vous devez exécuter cette fonction après avoir appelé MY_INIT().

Les arguments argc et argv sont analogues aux arguments de main(). Le premier élément argv est ignoré (il contient le plus souvent le nom du programme). Par convenance, argc peut être 0 (zéro) s'il n'y a aucun argument passé en ligne de commande pour le serveur.

La liste de mots terminée par NULL dans groups détermine les groupes dans les fichiers d'options qui seront actifs. Voir Section 4.3.2, « Fichier d'options my.cnf »4.3.2. Fichier d'options my.cnf. Par convenance, groups peut être NULL, dans ce cas, les groupes [server] et [emedded] sont activés.

Exemple

 
Sélectionnez
#include <mysql.h>
#include <stdlib.h>

static char *server_args[] = {
  "ce_programme",       /* cette chaîne n'est pas utilisée */
  "--datadir=.",
  "--key_buffer_size=32M"
};
static char *server_groups[] = {
  "embedded",
  "server",
  "this_program_SERVER",
  (char *)NULL
};

int main(void) {
  mysql_server_init(sizeof(server_args) / sizeof(char *),
                    server_args, server_groups);

  /* Utilisez les fonctions de L'API MySQL ici */

  mysql_server_end();

  return EXIT_SUCCESS;
}

Valeur de retour

0 en cas de succès, 1 si une erreur survient.

24-B-12-b. mysql_server_end()

void mysql_server_end(void)

Description

Cette fonction doit être appelée une fois dans le programme après toutes les autres fonctions MySQL. Elle coupe le serveur incorporé.

Valeur de retour

Aucune.

24-B-13. Questions courantes sur la bibliothèque C

24-B-13-a. Pourquoi est-ce que mysql_store_result() retourne parfois NULL après que mysql_query() ait réussi

Il est possible que mysql_store_result() retourne NULL après un appel à mysql_query(). Quand cela arrive, cela signifie que l'une des conditions suivantes a été remplie :

  • Il y a eu un problème avec malloc() (par exemple, si la taille du résultat était trop importante).
  • Les données n'ont pu être lues (erreur survenue à la connexion).
  • La requête n'a retourné aucun résultat (par exemple, il s'agissait d'un INSERT, UPDATE, ou d'un DELETE).

Vous pouvez toujours vérifier si la requête devait bien fournir un résultat non vide en invoquant mysql_field_count(). Si mysql_field_count() retourne zéro, le résultat est vide et la dernière requête n'en retournait pas (par exemple, un INSERT ou un DELETE). Si mysql_field_count() retourne un résultat non nul, la requête aurait dû produire un résultat non nul. Voyez la documentation de la fonction mysql_field_count() pour plus d'exemples.

Vous pouvez tester les erreurs en faisant appel à mysql_error() ou mysql_errno().

24-B-13-b. Quels résultats puis-je obtenir d'une requête?

En plus des enregistrements retournés par une requête, vous pouvez obtenir les informations suivantes :

  • mysql_affected_rows() retourne le nombre d'enregistrements affectés par la dernière requête INSERT, UPDATE, ou DELETE. Une exception est que si DELETE est utilisé sans clause WHERE, la table est recréée vide, ce qui est plus rapide. Dans ce cas, mysql_affected_rows() retournera zéro comme nombre d'enregistrements affectés.
  • mysql_num_rows() retourne le nombre d'enregistrements dans le résultat. Avec mysql_store_result(), mysql_num_rows() peut être utilisée dès que mysql_store_result() retourne un résultat. Avec mysql_use_result(), mysql_num_rows() ne doit être appelé qu'après avoir récupéré tous les enregistrements avec mysql_fetch_row().
  • mysql_insert_id() retourne l'ID généré par la dernière requête qui a inséré une ligne dans une table avec un index AUTO_INCREMENT. Voir Section 24.2.3.33, « mysql_insert_id() »24.2.3.33. mysql_insert_id().
  • Quelques requêtes (LOAD DATA INFILE ..., INSERT INTO ... SELECT ..., UPDATE) retournent des informations additionnelles. Le résultat est renvoyé par mysql_info(). Regardez la documentation de mysql_info() pour plus d'informations sur le format de la chaîne retournée. mysql_info() retourne un pointeur NULL s'il n'y a pas d'information additionnelle.
24-B-13-c. Comment lire l'identifiant unique de la dernière ligne insérée

Si vous insérez une ligne dans une table qui contient une colonne ayant l'attribut AUTO_INCREMENT, vous pouvez obtenir le dernier identifiant généré en appelant la fonction mysql_insert_id().

Vous pouvez aussi récupérer cet identifiant en utilisant la fonction LAST_INSERT_ID() dans une requête que vous passez à mysql_query().

Vous pouvez vérifier qu'un index AUTO_INCREMENT est utilisé en exécutant le code suivant. Cela vérifiera aussi si la requête était un INSERT avec un index AUTO_INCREMENT :

 
Sélectionnez
if (mysql_error(&mysql)[0] == 0 &&
    mysql_num_fields(result) == 0 &&
    mysql_insert_id(&mysql) != 0)
{
    used_id = mysql_insert_id(&mysql);
}

Pour plus d'informations, voyez la section Section 24.2.3.33, « mysql_insert_id() »24.2.3.33. mysql_insert_id().

Lorsqu'une nouvelle valeur AUTO_INCREMENT est générée, vous pouvez l'obtenir en utilisant la commande SELECT LAST_INSERT_ID() avec mysql_query() et en lisant la valeur dans le résultat obtenu.

Pour LAST_INSERT_ID(), l'identifiant généré par la dernière insertion est entretenu sur le serveur en se basant sur la connexion. Il ne sera pas changé par un autre client. Il ne changera pas non plus si vous mettez à jour une autre colonne AUTO_INCREMENT avec une valeur normale (ni NULL ni 0).

Si vous voulez utiliser l'identifiant généré pour une table et l'insérer dans une autre, vous pouvez utiliser les requêtes suivantes :

 
Sélectionnez
INSERT INTO foo (auto,text)
    VALUES(NULL,'text');              # génère un identifiant en insérant NULL
INSERT INTO foo2 (id,text)
    VALUES(LAST_INSERT_ID(),'text');  # on l'utilise dans la seconde page

Notez que mysql_insert_id() retourne la valeur stockée dans une colonne AUTO_INCREMENT, que cette valeur ait été générée automatiquement en enregistrant NULL ou 0 ou une valeur explicite. LAST_INSERT_ID() retourne les valeurs générées automatiquement par AUTO_INCREMENT. Si vous stockez une valeur explicite, autre que NULL ou 0, cela n'affecte pas le résultat de LAST_INSERT_ID().

24-B-13-d. Problèmes lors de la liaison avec l'API C

Lors de la liaison avec l'API C, l'erreur suivante peut survenir sur quelques systèmes :

 
Sélectionnez
gcc -g -o client test.o -L/usr/local/lib/mysql -lmysqlclient -lsocket -lnsl

Undefined        first referenced
 symbol          in file
floor            /usr/local/lib/mysql/libmysqlclient.a(password.o)
ld: fatal: Symbol referencing errors. No output written to client

Si cela se produit sur votre système, vous devez inclure la bibliothèque mathématique en ajoutant -lm à la fin de la ligne de compilation/liaison.

24-B-14. Compiler les clients

Si vous compilez des clients MySQL que vous avez écrits vous-même, ils doivent être liés en utilisant l'option -lmysqlclient -lz de la commande de liaison. Vous aurez peut-être besoin de spécifier l'option -L pour dire au programme ou trouver les bibliothèques. Par exemple, si la bibliothèque est installée dans /usr/local/mysql/lib, utilisez -L/usr/local/mysql/lib -lmysqlclient -lz dans votre commande.

Pour les clients qui utilisent les fichiers d'entêtes de MySQL, vous aurez besoin de spécifier une option -I lors de leur compilation (par exemple, -I/usr/local/mysql/include), pour que le programme puisse les trouver.

Pour rendre ce qui précède plus simple sur Unix, nous avons fourni le script mysql_config. Voir Section 24.1.2, « mysql_config lit les options de compilations du client MySQL »24.1.2. mysql_config lit les options de compilations du client MySQL.

Vous pouvez l'utiliser pour compiler un client MySQL comme ceci :

 
Sélectionnez
CFG=/usr/local/mysql/bin/mysql_config
sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`"

sh -c est nécessaire pour s'assurer que le Shell ne traitera pas le résultat de mysql_config comme un seul mot.

24-B-15. Comment faire un client MySQL threadé

La bibliothèque cliente est presque compatible avec les threads. Le problème le plus important est les routines de net.c qui lisent les sockets, et qui ne sont pas compatibles avec les interruptions. Cela a été fait en imaginant que vous souhaitiez vos propres alarmes, qui pourraient interrompre une lecture trop longue. Si vous installez des gestionnaires d'interruption pour l'alarme SIGPIPE, la gestion des sockets devrait être compatible avec les threads.

Dans les anciennes versions binaires que nous distribuions sur notre site web, (http://www.mysql.com/), les bibliothèques clientes étaient normalement compilées avec l'option de compatibilité avec les threads (les exécutables Windows sont par défaut compatibles avec les threads). Les nouvelles distributions binaires doivent disposer des deux bibliothèques, compatibles ou non avec les threads.

Pour obtenir un client threadé où vous pouvez interrompre le client avec d'autres threads, mettre des délais d'expiration lors des discussions avec le serveur MySQL, vous devriez utiliser les bibliothèques -lmysys, -lmystrings et -ldbug, ainsi que net_serv.o que le serveur utilise.

Si vous n'avez pas besoin des interruptions ou des expirations, vous pouvez compiler simplement une bibliothèque compatible avec les threads, (mysqlclient_r) et l'utiliser. Voir Section 24.2, « API MySQL C  »24.2. API MySQL C . Dans ce cas, vous n'avez pas à vous préoccuper du fichier net_serv.o ou des autres bibliothèques MySQL.

Lorsque vous utiliser un client threadé et que vous souhaitez utiliser des délais d'expiration et des interruptions, vous pouvez faire grand usage des routines du fichier thr_alarm.c. Si vous utilisez des routines issues de la bibliothèque mysys, la seule chose à penser est de commencer par utiliser my_init(). Voir Section 24.2.11, « Description des fonctions threadées de C »24.2.11. Description des fonctions threadées de C.

Toutes les fonctions, hormis mysql_real_connect() sont compatibles avec les threads par défaut. Les notes suivantes décrivent comment compiler une bibliothèque cliente compatible avec les threads. Les notes ci-dessous, écrites pour mysql_real_connect() s'appliquent aussi à mysql_connect(), mais comme mysql_connect() est obsolète, vous devriez utiliser mysql_real_connect()).

Pour rendre mysql_real_connect() compatible avec les threads, vous devez recompiler la bibliothèque cliente avec cette commande :

 
Sélectionnez
shell> ./configure --enable-thread-safe-client

Cela va créer une bibliothèque cliente compatible avec les threads libmysqlclient_r. Supposons que votre système d'exploitation dispose d'une fonction gethostbyname_r() compatible avec les threads. Cette bibliothèque est compatible avec les threads pour chaque connexion. Vous pouvez partager une connexion entre deux threads, avec les limitations suivantes :

  • Deux threads ne peuvent pas envoyer de requêtes simultanées au serveur MySQL, sur la même connexion. En particulier, vous devez vous assurer qu'entre mysql_query() et mysql_store_result(), aucun autre thread n'utilise la même connexion.
  • De nombreux threads peuvent accéder à différents résultats qui sont lus avec mysql_store_result().
  • Si vous utilisez mysql_use_result, vous devez vous assurer qu'aucun autre thread n'utilise la même connexion jusqu'à ce qu'elle soit refermée. Cependant, il vaut bien mieux pour votre client threadé qu'il utilise mysql_store_result().
  • Si vous voulez utiliser de multiples threads sur la même connexion, vous devez avoir un verrou mutex autour de vos fonctions mysql_query() et mysql_store_result(). Une fois que mysql_store_result() est prêt, le verrou peut être libéré et d'autres threads vont pouvoir utiliser la connexion.
  • Si vous programmez avec les threads POSIX, vous pouvez utiliser les fonctions pthread_mutex_lock() et pthread_mutex_unlock() pour poser et enlever le verrou mutex.

Vous devez savoir ce qui suit si vous avez un thread qui appelle une fonction MySQL qui n'a pas créé de connexion à la base MySQL.

Lorsque vous appelez mysql_init() ou mysql_connect(), MySQL va créer une variable spécifique au thread qui est utilisée par la bibliothèque de débogage (entre autres).

Si vous appelez une fonction MYSQL, avant que le thread n'ait appelé mysql_init() ou mysql_connect(), le thread ne va pas avoir les variables spécifiques en place, et vous risquez d'obtenir un core dump tôt ou tard.

Pour faire fonctionner le tout proprement, vous devez suivre ces étapes :

  1. Appeler my_init() au début du programme, s'il appelle une autre fonction MySQL, avant d'appeler mysql_real_connect().
  2. Appeler mysql_thread_init() dans le gestionnaire de threads avant d'appeler une autre fonction MySQL.
  3. Dans le thread, appelez mysql_thread_end() avant d'appeler pthread_exit(). Cela va libérer la mémoire utilisée par les variables spécifiques MySQL.

Vous pouvez rencontrer des erreurs à cause des symboles non définis lors du lien de votre client avec libmysqlclient_r. Dans la plupart des cas, c'est parce que vous n'avez pas inclus la bibliothèque de threads dans la ligne de compilation.

24-B-16. libmysqld, la bibliothèque du serveur embarqué MySQL

24-B-16-a. Vue d'ensemble de la bibliothèque du serveur embarqué MySQL

La bibliothèque embarquée MySQL rend possible l'accès à un serveur MySQL complet, depuis une application. Le principal avantage est l'amélioration des performances, et une gestion bien plus simple des applications.

Les API sont identiques pour la version embarquée et la version client/serveur. Pour changer les anciennes applications threadées, et les faire utiliser la bibliothèque embarquée, vous devez simplement ajouter deux appels aux fonctions suivantes :

Fonction

Quand l'utiliser

mysql_server_init()

Doit être appelée avant toute autre fonction MySQL, et de préférence très tôt dans la fonction main().

mysql_server_end()

Doit être appelée avant que votre programme ne se termine.

mysql_thread_init()

Doit être appelée dans chaque thread que vous créez, qui aura accès à MySQL.

mysql_thread_end()

Doit être appelée avant d'appeler pthread_exit()

Puis, vous devez compiler votre code avec libmysqld.a au lieu de libmysqlclient.a.

Les fonctions ci-dessus mysql_server_xxx sont aussi incluses dans la bibliothèque libmysqlclient.a pour vous permettre de changer facilement entre les versions de la bibliothèque embarquée et celle de la bibliothèque client/serveur, en compilant simplement la bonne bibliothèque. Voir Section 24.2.12.1, « mysql_server_init() »24.2.12.1. mysql_server_init().

24-B-16-b. Compiler des programmes avec libmysqld

Pour avoir la bibliothèque libmysqld vous devez configurer MySQL avec l'option --with-embedded-server.

Quand vous liez votre programme avec libmysqld, vous devez aussi inclure les bibliothèques pthread spécifiques au système et quelques bibliothèques que le serveur MySQL utilise. Vous pouvez obtenir la liste complète des bibliothèques en exécutant mysql_config --libmysqld-libs.

Les options correctes pour compiler et lier un programme threadé doivent être utilisées, même si vous n'appelez pas directement une fonction de threads dans votre code.

24-B-16-c. Restrictions lors de l'utilisation du serveur embarqué MySQL

Le serveur embarqué possède les limitations suivantes.

  • Pas de support pour les tables ISAM. (Ceci est principalement fait pour rendre la bibliothèque plus petite)
  • Pas de fonctions définies par l'utilisateur (UDF).
  • Pas de traçage de piles lors des vidages de mémoire (core dump).
  • Pas de support pour les RAID internes. (Cela n'est normalement pas requis vu que la plupart des systèmes d'exploitation supportent aujourd'hui les grands fichiers).
  • Vous pouvez le configurer en tant que serveur ou maître (pas de réplication).
  • vous ne pouvez vous connecter au serveur embarqué à partir d'un processus externe avec les sockets ou TCP/IP.

Quelques-unes de ces limitations peuvent être changées en éditant le fichier mysql_embed.h et recompilant MySQL.

24-B-16-d. Utilisation de fichiers d'options avec le serveur embarqué

Voici la manière recommandée d'utiliser les fichiers d'options pour que le passage des applications client/serveur vers une application où MySQL est embarqué soit plus facile. Voir Section 4.3.2, « Fichier d'options my.cnf »4.3.2. Fichier d'options my.cnf.

  • Placez les options communes dans la section [server]. Elles seront lues par les deux versions de MySQL.
  • Placez les options spécifiques au client/serveur dans la section [mysqld].
  • Placez les options spécifiques à MySQL embarqué dans la section [embedded].
  • Placez les options spécifiques aux applications dans une section [NomApplication_SERVER].
24-B-16-e. Choses à faire pour le serveur embarqué (TODO)
  • Nous allons proposer des options pour se débarrasser de quelques parties de MySQL pour rendre la bibliothèque plus petite.
  • Il y a encore beaucoup d'optimisations de vitesse à faire.
  • Les erreurs sont écrites dans stderr. Nous ajouterons une option pour spécifier un fichier pour cela.
  • Nous devons changer InnoDB pour qu'il n'y ait plus tant de sorties lors de l'utilisation du serveur embarqué.
24-B-16-f. Un exemple simple de serveur embarqué

Ce programme exemple et son makefile devraient fonctionner sans changements sur un système Linux ou FreeBSD. Pour les autres systèmes d'exploitation, quelques petits changements seront requis. Cet exemple est là pour vous donner assez de détails pour comprendre le problème, sans avoir en tête qu'il s'agit d'une partie nécessaire d'une application réelle.

Pour essayer cet exemple, créez un dossier test_libmysqld au même niveau que le dossier des sources mysql-4.0. Sauvegardez le fichier source test_libmysqld.c et GNUmakefile dans le dossier, puis exécutez GNU make à l'intérieur du répertoire test_libmysqld.

test_libmysqld.c

 
Sélectionnez
/*
 * Un simple exemple de client, utilisant la bibliothèque du serveur embarqué MySQL
 */

#include <mysql.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>

MYSQL *db_connect(const char *dbname);
void db_disconnect(MYSQL *db);
void db_do_query(MYSQL *db, const char *query);

const char *server_groups[] = {
  "test_libmysqld_SERVER", "embedded", "server", NULL
};

int
main(int argc, char **argv)
{
  MYSQL *one, *two;

  /* mysql_server_init() doit être appelée avant toute autre fonction
   * mysql.
   *
   * Vous pouvez utiliser mysql_server_init(0, NULL, NULL), et cela initialisera
   * le serveur en utilisant groups = {
   *   "server", "embedded", NULL
   *  }.
   *
   * Dans votre fichier $HOME/.my.cnf, vous voudrez sûrement mettre :

[test_libmysqld_SERVER]
language = /chemin/vers/la/source/de/mysql/sql/share/english

   * Vous pouvez, bien sûr, modifier argc et argv avant de les passer
   * à cette fonction. Ou vous pouvez en créer de nouveaux de la manière
   * que vous souhaitez. Mais tous les arguments dans argv (à part
   * argv[0], qui est le nom du programme) doivent être des options valides
   * pour le serveur MySQL.
   *
   * Si vous liez ce client avec la bibliothèque mysqlclient normale,
   * cette fonction n'est qu'un bout de code qui ne fait rien.
   */
  mysql_server_init(argc, argv, (char **)server_groups);

  one = db_connect("test");
  two = db_connect(NULL);

  db_do_query(one, "SHOW TABLE STATUS");
  db_do_query(two, "SHOW DATABASES");

  mysql_close(two);
  mysql_close(one);

  /* Cela doit être appelé après toutes les autres fonctions mysql */
  mysql_server_end();

  exit(EXIT_SUCCESS);
}

static void
die(MYSQL *db, char *fmt, ...)
{
  va_list ap;
  va_start(ap, fmt);
  vfprintf(stderr, fmt, ap);
  va_end(ap);
  (void)putc('\n', stderr);
  if (db)
    db_disconnect(db);
  exit(EXIT_FAILURE);
}

MYSQL *
db_connect(const char *dbname)
{
  MYSQL *db = mysql_init(NULL);
  if (!db)
    die(db, "mysql_init a échoué : pas de mémoire");
  /*
   * Notez que le client et le serveur utilisent des noms de groupes séparés.
   * Ceci est critique, car le serveur n'acceptera pas les options du client
   * et vice versa.
   */
  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test_libmysqld_CLIENT");
  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
    die(db, "mysql_real_connect a échoué : %s", mysql_error(db));

  return db;
}

void
db_disconnect(MYSQL *db)
{
  mysql_close(db);
}

void
db_do_query(MYSQL *db, const char *query)
{
  if (mysql_query(db, query) != 0)
    goto err;

  if (mysql_field_count(db) > 0)
  {
    MYSQL_RES   *res;
    MYSQL_ROW    row, end_row;
    int num_fields;

    if (!(res = mysql_store_result(db)))
      goto err;
    num_fields = mysql_num_fields(res);
    while ((row = mysql_fetch_row(res)))
    {
      (void)fputs(">> ", stdout);
      for (end_row = row + num_fields; row < end_row; ++row)
        (void)printf("%s\t", row ? (char*)*row : "NULL");
      (void)fputc('\n', stdout);
    }
    (void)fputc('\n', stdout);
  }
  else
    (void)printf("Lignes affectées : %lld\n", mysql_affected_rows(db));

  return;

err:
  die(db, "db_do_query a échoué : %s [%s]", mysql_error(db), query);
}

GNUmakefile

 
Sélectionnez
# On suppose que MySQL est installé dans /usr/local/mysql
inc      := /usr/local/mysql/include/mysql
lib      := /usr/local/mysql/lib

# Si vous n'avez pas encore installé MySQL, essayez plutôt ceci
#inc      := $(HOME)/mysql-4.0/include
#lib      := $(HOME)/mysql-4.0/libmysqld

CC       := gcc
CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
CFLAGS   := -g -W -Wall
LDFLAGS  := -static
# Vous pouvez changer -lmysqld en -lmysqlclient pour utiliser
# la bibliothèque client/serveur
LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt

ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null))
# FreeBSD
LDFLAGS += -pthread
else
# Linux
LDLIBS += -lpthread
endif

# Cela fonctionne pour les programmes de tests sur un simple fichier
sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
targets := $(basename $(sources))

all: $(targets)

clean:
    rm -f $(targets) $(objects) *.core
24-B-16-g. Licence du serveur embarqué

Nous encourageons tout le monde à promouvoir le logiciel libre en réalisant du code sous la licence GPL ou une autre licence compatible. Pour ceux qui ne peuvent le faire, une autre option est d'acheter la licence commerciale pour le code MySQL chez MySQL AB. Pour plus d'informations, voyez http://www.mysql.com/company/legal/licensing/.

24-C. API PHP pour MySQL

PHP est un langage côté serveur, qui peut être utilisé pour créer des pages web dynamiques. Il fournit un support d'accès à plusieurs systèmes de bases de données, dont MySQL fait partie. PHP peut être utilisé en tant que programme séparé, ou être compilé en tant que module pour le serveur web Apache.

La distribution et documentation sont disponibles sur le site web de PHP (http://www.php.net/).

24-C-1. Problèmes fréquents avec MySQL et PHP

  • Error: "Maximum Execution Time Exceeded". C'est une limitation de PHP. Éditez le fichier php.ini et changez le temps maximal d'exécution d'un script de 30 secondes à plus, selon vos besoins. C'est aussi une bonne idée de doubler la quantité de RAM allouée par script en la changeant à 16 MB.
  • Error: "Fatal error: Call to unsupported or undefined function mysql_connect() in ...". Cela signifie que votre version de PHP n'est pas compilée avec le support de MySQL. Vous pouvez soit compiler un module dynamique MySQL et le charger dans PHP, ou bien recompiler PHP avec le support natif de MySQL. Ceci est décrit en détail dans le manuel PHP.
  • Error: "undefined reference to `uncompress". Cela signifie que la bibliothèque cliente est compilée avec support d'un protocole client/serveur compressé. La solution est d'ajouter -lz à la fin lors de la liaison avec -lmysqlclient.

24-D. API Perl pour MySQL

DBI est une interface générique à plusieurs systèmes de bases de données. Cela signifie que vous pouvez écrire un script qui fonctionne parfaitement avec plusieurs systèmes différents sans y apporter aucun changement. Vous avez besoin de définir un pilote de bases de données (DataBase Driver : DBD) pour chaque système. Pour MySQL, ce pilote se nomme DBD::mysql.

Perl DBI est maintenant l'interface recommandée pour Perl. Elle remplace une ancienne interface appelée mysqlperl, qui doit être abandonnée.

Vous pouvez trouver les dernières informations relatives à DBI dans la section Section 2.9, « Commentaires sur l'installation de Perl »2.9. Commentaires sur l'installation de Perl.

Plus de détails sur DBI sont disponibles en ligne de commande, sur Internet ou en version imprimée.

  • Une fois que vous avez installé DBI et DBD::mysql, vous pouvez utiliser la commande perldoc pour obtenir plus d'informations à propos de DBI.

     
    Sélectionnez
    shell> perldoc DBI
    shell> perldoc DBI::FAQ
    shell> perldoc DBD::mysql

    Vous pouvez aussi utiliser les outils pod2man, pod2html, etc. pour convertir la documentation en différents formats.

  • Pour plus d'informations sur le module DBI de Perl5, visitez la page web de DBI : http://dbi.perl.org/

  • Pour une documentation imprimée, voyez le guide officiel DBI : Programming the Perl DBI (Alligator Descartes et Tim Bunce, O'Reilly & Associates, 2000). Les informations sur le livre sont disponibles sur le site de DBI : http://dbi.perl.org/.
    Pour des informations qui sont spécifiques à DBI et MySQL, voyez MySQL and Perl for the Web (Paul DuBois, New Riders, 2001). Le site web de ce livre est http://www.kitebird.com/mysql-perl/.

24-E. Interface MySQL C++

MySQL Connector/C++ (or MySQL++) est l'interface officielle de MySQL pour le C++. Plus d'informations sont disponibles sur http://www.mysql.com/products/mysql++/.

24-E-1. Borland C++

Vous pouvez compiler la source Windows de MySQL avec Borland C++ 5.02. (La source Windows n'inclut que les fichiers issus de Microsoft VC++, pour Borland C++ vous devrez créer les fichiers de projet par vous-même.)

Un problème connu avec Borland C++ est qu'il utilise un alignement de structures différent de VC++. Cela signifie que vous aurez des problèmes si vous essayez d'utiliser la bibliothèque par défaut libmysql.dll (qui a été compilée avec VC++) avec Borland C++. Vous pouvez faire ce qui suit pour éviter ce problème.

  • Vous pouvez utiliser les bibliothèques MySQL statiques pour Borland C++ que vous trouverez sur http://www.mysql.com/downloads/os-win32.html.
  • Appelez mysql_init() avec NULL comme argument, et non une structure MYSQL préallouée.

24-F. MySQL Python API

MySQLdb fournit le support MySQL pour Python, compatible avec l'API de base de données Python version 2.0. Elle est disponible à l'URL http://sourceforge.net/projects/mysql-python/.

24-G. MySQL Tcl API

MySQLtcl est une API simple pour accéder au serveur MySQL depuis le langage de programmation Tcl. Il est disponible sur http://www.xdobry.de/mysqltcl/.

24-H. Couche MySQL pour Eiffel

Eiffel MySQL est une interface avec le langage de programmation Eiffel, écrit par Michael Ravits. Il est disponible sur http://efsa.sourceforge.net/archive/ravits/mysql.htm.


précédentsommairesuivant