Chapitre 24. API MySQL
Précédent |  | Suivant

## Chapitre 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.1. 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.1.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. A cause de cela, les programmes mSQL peuvent souvent être convertis facilement à utiliser MySQL, en changeant simplement les noms de l'API C.

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

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

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

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

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

### 24.1.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 compilations 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 :

    shell> mysql_config
    Usage: /usr/local/mysql/bin/mysql_config [options]
    Options:
      --cflags         [-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]
      --include        [-I/usr/local/mysql/include/mysql]
      --libs           [-L/usr/local/mysql/lib/mysql -lmysqlclient -lz
                        -lcrypt -lnsl -lm -L/usr/lib -lssl -lcrypto]
      --libs_r         [-L/usr/local/mysql/lib/mysql -lmysqlclient_r
                        -lpthread -lz -lcrypt -lnsl -lm -lpthread]
      --socket         [/tmp/mysql.sock]
      --port           [3306]
      --version        [4.0.16]
      --libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld -lpthread -lz
                        -lcrypt -lnsl -lm -lpthread -lrt]

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

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

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

## 24.2. API MySQL C

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

De nombreux client 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, que vous pouvez exploiter adroitement de nombreux 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 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 croit à 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é. See Section 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é ». 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.1. Types de données de l'API C

- `MYSQL`

  Cette structure représente un gestionnaire de connexion à 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îne à 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, tel que son nom, son type, et sa taille. Ses membres sont décrit en plus de détails 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 là en `unsigned long` et utilisez un format d'impression `%lu`. Exemple :

      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éfinit 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 :

      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 parti d'une clef primaire
  `UNIQUE_KEY_FLAG` | Le champ fait parti d'une clef unique
  `MULTIPLE_KEY_FLAG` | Le champ fait parti 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` :

      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é; tester plutôt `field->type`)

- `unsigned int decimals`

  Le nombre de décimales pour les champs numériques.

### 24.2.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. See Section 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és 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ère 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épondants à 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épondants à 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 un 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'auto validation (nouveau en 4.1).
mysql_more_results() | Vérifie si il n'y a plus de résultats (nouveau en 4.1).
mysql_next_result() | Retourne/initie le prochain résultat dans une commande multi-requê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 tel que l'hôte, l'utilisateur et le mot de passe). Lors de la connexion, `mysql_real_connect()` définit l'option `reconnect` (quit fait partie de la structure MYSQL) à `1`. Cette option indique, dans le cas où une requête ne peut être exécutée à cause d'une perte de connexion, d'essayer de se reconnecter au serveur avant d'abandonner. Lorsque vous n'avez plus besoin de la connexion, appelez `mysql_close()` pour la clore.

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

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

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

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

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

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

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

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

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

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

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

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

### 24.2.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 :

    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.2.3.1. `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ée 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 lignes 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

    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 correspondants à 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é puis la nouvelle insérée.

#### 24.2.3.2. `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éponds 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

    if (mysql_change_user(&mysql, "user", "password", "new_database"))
    {
       fprintf(stderr, "Impossible de changer d'utilisateur.  Erreur : %s\n",
               mysql_error(&mysql));
    }

#### 24.2.3.3. `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.2.3.4. `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.2.3.5. `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.2.3.6. `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 à é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éponds 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

    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.2.3.7. `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ésultat de requête. Cela nécessite que la structure du jeu de résultat 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.2.3.8. `mysql_debug()`

`void mysql_debug(const char *debug)`

Description

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

Valeur de retour

Aucune.

Erreurs

Aucune.

Exemple

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

    mysql_debug("d:t:O,/tmp/client.trace");

#### 24.2.3.9. `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 à é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éponds 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

    if(mysql_drop_db(&mysql, "ma_base"))
      fprintf(stderr, "Impossible de supprimer la base de données. Erreur : %s\n",
              mysql_error(&mysql));

#### 24.2.3.10. `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éponds 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.2.3.11. `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¸ois 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ésultat 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()`. Puisque 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()`:

    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 :

    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.2.3.12. `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 serveurs sont listés dans Chapitre 26, Gestion des erreurs avec MySQL.

Notez que certaines fonctions comme `mysql_fetch_row()` ne donne 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éussisent.

Valeur de retour

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

Erreurs

Aucune.

#### 24.2.3.13. `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 :

    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 un choix de plusieurs langues. See Section 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.2.3.14. `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()` à l'exception faite que `mysql_real_escape_string()` prends deux identifiants de connexion comme premiers arguments et échappe la chaîne en se basant que le jeu de caractères courant. `mysql_escape_string()` ne prends pas d'identifiant de connexion et ne respecte pas le jeu de caractères courant.

#### 24.2.3.15. `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ésultat. `mysql_fetch_field()` retourne `NULL` quand il ne reste plus de champs.

`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 8K 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 colonnes.

Erreurs

Aucune.

Exemple

    MYSQL_FIELD *field;

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

#### 24.2.3.16. `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ésultat.

Erreurs

Aucune.

Exemple

    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.2.3.17. `mysql_fetch_field_direct()`

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

Description

Etant 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

    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.2.3.18. `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ésultat contient des données binaires, vous devez 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 la caractère nul de terminaison). `NULL` si une erreur se produit.

Erreurs

`mysql_fetch_lengths()` n'st 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

    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.2.3.19. `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 lignes a 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 lignes a 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 lignes a 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

    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.2.3.20. `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.

See Section 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

    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 renvoit
    {
        result = mysql_store_result(&mysql);
        if (result)  // il y a des lignes
        {
            num_fields = mysql_num_fields(result);
            // récupère les lignes, puis appele 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 du retourner des données
            {
                fprintf(stderr, "Erreur : %s\n", mysql_error(&mysql));
            }
        }
    }

Une alternative 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.2.3.21. `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.2.3.22. `mysql_field_tell()`

`MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)`

Description

Retourne la position du curseur de champ 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 champ.

Erreurs

Aucune.

#### 24.2.3.23. `mysql_free_result()`

`void mysql_free_result(MYSQL_RES *result)`

Description

Libère la mémoire alloué à 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ésultat, vous devez libérer la mémoire qu'il occupe en appelant `mysql_free_result()`.

Valeur de retour

Aucune.

Erreurs

Aucune.

#### 24.2.3.24. `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.2.3.25. `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 `XYYZZ` où `X` 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.2.3.26. `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.2.3.27. `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.2.3.28. `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.2.3.29. `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 :

    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.2.3.30. `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. See Section 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 `0x`value`` 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

    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.2.3.31. `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 correspondantes à 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.2.3.32. `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.2.3.33. `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ère 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édent 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)`. See Section 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'autre 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.2.3.34. `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éponds 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.2.3.35. `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 » pour connaître son utilisation.

#### 24.2.3.36. `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 » pour connaître son utilisation.

#### 24.2.3.37. `mysql_list_dbs()`

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

Description

Retourne une 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é 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()` reviens à 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éponds 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.2.3.38. `mysql_list_fields()`

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

Description

Retourne un jeu de résultats consistant 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éponds 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.2.3.39. `mysql_list_processes()`

`MYSQL_RES *mysql_list_processes(MYSQL *mysql)`

Description

Retourne un jeu de résultat 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ésultat avec `mysql_free_result()`.

Valeur de retour

Un jeu de résultat `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éponds 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.2.3.40. `mysql_list_tables()`

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

Description

Retourne un jeu de résultats consistant des noms de tables dans la base de données courante qui concordent avec l'expression régulière spécifié 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'erreurs.

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éponds 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.2.3.41. `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 du 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é.

See Section 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

    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'etait pas un SELECT)
                num_rows = mysql_affected_rows(&mysql);
            }
        }
    }

Une alternative (si vous savez que votre requête aurait du 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.2.3.42. `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 résultat. 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.2.3.43. `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 re-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.cnf`ou 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 re-exécutée lors des reconnexions.
`interactive-timeout` | Revient à spécifier `CLIENT_INTERACTIVE` à `mysql_real_connect()`. See Section 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` ».

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

    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.2.3.44. `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 re-connexion 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 re-connecter 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éponds pas.

- `CR_UNKNOWN_ERROR`

  Une erreur inconnue s'est produite.

#### 24.2.3.45. `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 bianaires, 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ésultat ou non, vous pouvez utiliser `mysql_field_count()` pour vérifier. See Section 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éponds 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.2.3.46. `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()`. See Section 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 local 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. See Section 25.1.9.2, « Configuration du DSN MyODBC sur Windows ».

- La 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 aient 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ée 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é 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'innactivité 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 serveru 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éveler 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 connexion `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 tunnel 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

    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.2.3.47. `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. See Section 9.1.1, « Chaînes ».

La string dans `de` est encodée en chaîne échappé SQL, prenom 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 (see Section 9.1, « Littéraux : comment écrire les chaînes et les nombres »). (En fait, MySQL a seulement besoin que l'anti-slash et le guillemet utilisé pour entourer la chaîne soient échappés. Cette fonction échappe les autre caractères pour les rendre plus facile à 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

    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 inclue 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 la caractère nul de fin de chaîne.

Erreurs

Aucune.

#### 24.2.3.48. `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 continent 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ésultat ou non, vous pouvez utiliser `mysql_field_count()` pour vérifier cela. See Section 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éponds 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.2.3.49. `mysql_reload()`

`int mysql_reload(MYSQL *mysql)`

Description

Demande au serveur MySQL de recharger les tables de droits. L'utilisateur soit 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éponds 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.2.3.50. `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ée 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.2.3.51. `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.2.3.52. `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éponds 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.2.3.53. `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 succes. 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éponds 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.2.3.54. `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éponds 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.2.3.55. `mysql_sqlstate()`

`const char *mysql_sqlstate(MYSQL *mysql)`

Description

Retourne une chaîne termineé 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 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

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

#### 24.2.3.56. `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 à établire 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 est activéé dans la bibliothèque cliente.

`mysql` est un gestionnaire de connexion, retourné par `mysql_init()`. Les autres paramètre 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 certifications SSL reconnus, 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.2.3.57. `mysql_stat()`

`char *mysql_stat(MYSQL *mysql)`

Description

Retourne une chaîne de caractères contenant des informations similaires à celle fournies par la commande `mysqladmin status`. Cela inclus 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éponds 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.2.3.58. `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. See Section 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.

See Section 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éponds 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.2.3.59. `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.2.3.60. `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()`. A la place, chaque ligne doit être récupéré 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ée seront inclues dans le jeu de résultat 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éponds 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.2.3.61. `mysql_warning_count()`

`unsigned int mysql_warning_count(MYSQL *mysql)`

Description

Retourne le nombre l'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.2.3.62. `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.2.3.63. `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.2.3.64. `mysql_autocommit()`

`my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)`

Description

Active ou désactive le mode d'auto-validation (`autocommit`). Si le paramètre `mode` vaut 1, l'auto-validation est activée. Dans le cas où il vaut 0, l'auto-validation 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.2.3.65. `mysql_more_results()`

`my_bool mysql_more_results(MYSQL *mysql)`

Description

Retourne TRUE si il y a d'autre 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` si 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ésultat si c'est le cas.

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

Erreurs

Aucune.

#### 24.2.3.66. `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ésultat.

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é, et il n'y a pas d'autres résultats à lire.

See Section 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ésultats
>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.2.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 commande 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 efficace 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 seuls les données paramètres sont échangées.

### 24.2.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 » 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 commande 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ées par toutes les fonctions ultérieures, liées au commandes préparées.

  La structure `MYSQL_STMT` n'a pas de membres utilisables par l'application.

  Une connexion peut avoir de multiples pointeurs de commandes, et la limite ne dépend que des ressources systèmes.

- `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 objectifs et 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ésultat.

  - `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 si il est utilisé avec `mysql_bind_param()`, ou la taille lue dans le résultat si 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ères ou binaires. Pour l'envoi de données, `length` point 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 sont déterminées 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`. See Section 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.2.6. Présentation des fonctions de l'interface C

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

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

Fonction | Description
`mysql_stmt_init()` | Alloue la mémoire pour une structure `MYSQL_STMT` et l'initialise.
`mysql_stmt_bind_param()` | Associe un buffer avec une variable de requêtes, dans une commande préparée.
`mysql_stmt_bind_result()` | Lie les buffers de l'application avec les colonnes d'un résultat.
`mysql_stmt_execute()` | Exécute une commande préparée.
`mysql_stmt_fetch()` | Lit la prochaine ligne de données dans le résultat, et retourne toutes les données des colonnes liées.
`mysql_stmt_fetch_column()` | Lit les données d'une seule colonne, dans le résultat.
`mysql_stmt_result_metadata()` | Retourne les meta-données de la commande préparée, sous forme d'un jeu de résultat.
`mysql_stmt_param_count()` | Retourne le nombre de paramètres d'une commande préparée.
`mysql_stmt_param_metadata()` | Retourne les meta-données des paramètres, sous forme d'un jeu de résultat.
`mysql_stmt_prepare()` | Prépare une chaîne SQL pour l'exécution.
`mysql_stmt_send_long_data()` | Envoie de grandes données par parties.
`mysql_stmt_affected_rows()` | Retourne le nombre de lignes modifiées, effacées ou insérée dans la dernière requête `UPDATE`, `DELETE` ou `INSERT`.
`mysql_stmt_insert_id()` | Retourne l'identifiant généré par la colonne `AUTO_INCREMENT` de la dernière commande préparée.
`mysql_stmt_close()` | Libère une commande préparée de la mémoire.
`mysql_stmt_data_seek()` | Se place à une numéro de ligne arbitraire dans un jeu de résultat.
`mysql_stmt_errno()` | Retourne le numéro d'erreur de la dernière requête.
`mysql_stmt_error()` | Retourne le message d'erreur de la dernière requête.
`mysql_stmt_free_result()` | Libère les ressources allouées pour la commande.
`mysql_stmt_num_rows()` | Retourne le nombre total de lignes dans un jeu de résultat bufferisé.
`mysql_stmt_reset()` | Remet à zéro les buffers de la commande, sur le serveur.
`mysql_stmt_row_seek()` | Se place à un numéro de ligne, dans un résultat de commande, en utilisant la valeur retournée par `mysql_stmt_row_tell()`.
`mysql_stmt_row_tell()` | Retourne la position du curseur de ligne de la commande.
`mysql_stmt_sqlstate()` | Retourne le code d'erreur SQLSTATE de la dernière opération.
`mysql_stmt_store_result()` | Lit tout le résultat dans le client.
`mysql_stmt_attr_set()` | Modifie un attribut d'une commande préparée.
`mysql_stmt_attr_get()` | Lit la valeur d'un attribut d'une commande préparée.

Appelez `mysql_prepare()` pour préparer et initialiser la commande, puis appelez `mysql_bind_param()` pour fournir les données des paramètres, enfin appelez `mysql_execute()` pour exécuter la requête. Vous pouvez répéter `mysql_execute()` en modifiant les valeurs des paramètres des buffers respectifs via `mysql_bind_param()`.

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

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

Vous pouvez aussi envoyer le texte ou les données binaires au serveur en utilisant la fonction `mysql_stmt_send_long_data()`. See Section 24.2.7.25, « `mysql_stmt_send_long_data()` ».

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

Etapes d'exécution :

Pour préparer et exécuter une commande, l'application :

1. appelle `mysql_prepare()` et passe une chaîne contenant la commande SQL. Si la préparation réussi, `mysql_prepare()` retourne un pointeur de commande valide.

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

3. spécifie les valeurs de tous les paramètres de `mysql_bind_param`. Tous les paramètres doivent être fournis, sinon, cela générera une erreur, ou engendrera des résultats inattendus.

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

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

6. Lie les buffers de données aux lignes de résultat, si la commande génère un résultat, en utilisant `mysql_bind_result()`.

7. Lit les données dans les buffers, ligne par ligne, en appelant `mysql_fetch()` jusqu'à ce qu'il n'y ait plus de lignes.

Lorsque `mysql_prepare()` est appelé, dans le protocole client/serveur MySQL :

- Le serveur analyse la requête et envoie le statut OK au client en lui assignant un identifiant de commande. Il renvoie aussi le nombre total de paramètres, le nombre de colonnes et des meta-informations si un résultat est attendu. La syntaxe et la sémantique de la requête sont vérifiés durant cet appel.

- Le client utilise cet identifiant de commande pour les exécutions ultérieures, pour que le serveur identifie la commande dans le pool de commandes. Désormais, le client alloue un pointeur de commande avec cet identifiant, et le retourne à l'application.

Lorsque `mysql_execute()` est appelé, avec le protocole client/serveur MySQL :

- Le client utilise le pointeur de commande et envoie les paramètres au serveur.

- Le serveur identifie la commande en utilisant l'identifiant, et remplace les marqueurs de paramètres par leur valeur, puis il exécute la requête. Si cela conduit à un résultat, il est retourné au client, ou bien un statut OK, indiquant le nombre total de ligne affecté est retourné.

Lorsque `mysql_fetch()` est appelé, dans le protocole client/serveur MySQL :

- Le client lit les données dans le paquet, ligne par ligne, et les place dans les buffers de données, avec les conversions nécessaires. Si le type de buffer de l'application est le même que le type de champs, alors les conversions sont immédiates.

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

### 24.2.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.2.7.1. `mysql_stmt_affected_rows()`

`my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)`

Description

Retourne le nombre total de ligne 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 ligne affectées ou lues. Zéro indique qu'aucune ligne n'a été modifiées 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é. −1 indique que la requête a retourné une erreur, ou que, pour une requête SELECT, mysql_stmt_affected_rows() a été appelé 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 to `(my_ulonglong)~0`, qui est équivalent).

Erreurs

Aucune.

Exemple

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

#### 24.2.7.2. `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. See Section 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.2.7.3. `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 meta-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.2.7.4. `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ésent dans la requête.

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

    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 :

    MYSQL_BIND bind[3];

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

Return Values

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. Eventuellement, 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 une exemple avec `mysql_stmt_bind_param()`, voyez l'exemple de la fonction Section 24.2.7.10, « `mysql_stmt_execute()` ».

#### 24.2.7.5. `mysql_stmt_bind_result()`

`my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)`

Description

`mysql_stmt_bind_result()` is used to associate (bind) columns in the result set to data buffers and length buffers. When `mysql_stmt_fetch()` is called to fetch data, the MySQL client/server protocol places the data for the bound columns into the specified buffers.

All columns must be bound to buffers prior to calling `mysql_stmt_fetch()`. `bind` is the address of an array of `MYSQL_BIND` structures. The client library expects the array to contain an element for each column of the result set. Otherwise, `mysql_stmt_fetch()` simply ignores the data fetch. Also, the buffers should be large enough to hold the data values, because the protocol doesn't return data values in chunks.

A column can be bound or rebound at any time, even after a result set has been partially retrieved. The new binding takes effect the next time `mysql_stmt_fetch()` is called. Suppose that an application binds the columns in a result set and calls `mysql_stmt_fetch()`. The client/server protocol returns data in the bound buffers. Then suppose the application binds the columns to a different set of buffers. The protocol does not place data into the newly bound buffers until the next call to `mysql_stmt_fetch()` occurs.

To bind a column, an application calls `mysql_stmt_bind_result()` and passes the type, address, and the address of the length buffer. The members of each `MYSQL_BIND` element that should be set are described in Section 24.2.5, « Types de données de l'API C ».

Return Values

Zero if the bind was successful. Non-zero if an error occurred.

Errors

- `CR_UNSUPPORTED_PARAM_TYPE`

  The conversion is not supported. Possibly the `buffer_type` value is illegal or is not one of the supported types.

- `CR_OUT_OF_MEMORY`

  Out of memory.

- `CR_UNKNOWN_ERROR`

  An unknown error occurred.

Example

For the usage of `mysql_stmt_bind_result()`, refer to the Example from Section 24.2.7.13, « `mysql_stmt_fetch()` ».

#### 24.2.7.6. `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`

  The MySQL server has gone away

- `CR_UNKNOWN_ERROR`

  An unkown error occured

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.7. `mysql_stmt_data_seek()`

`void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)`

Description

Place le pointeur de résultat à une ligne arbitaire. 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ésultat 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.2.7.8. `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 clients sont listés dans le fichier d'entêtes `errmsg.h`. Les messages d'erreurs serveurs 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ées dans Chapitre 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.2.7.9. `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 :

    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 peuvent être modifiées à la compilation de la bibliothèque cliente MySQL. Actuellement, vous pouvez choisir les message 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.2.7.10. `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 tout 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()` ».

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`

  Commands were executed in an improper order : les commandes ont été exécutées dans un ordre invalide.

- `CR_OUT_OF_MEMORY`

  Out of memory : plus de mémoire.

- `CR_SERVER_GONE_ERROR`

  The MySQL server has gone away : le serveur MySQL s'est éteint.

- `CR_SERVER_LOST`

  The connection to the server was lost during the query : la connexion a été perdue durant la requête.

- `CR_UNKNOWN_ERROR`

  An unknown error occurred : 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()`.

    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);
      }

      /* Prepare 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épartion 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 : 2eme */
      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 échouée");
        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.2.7.11. `mysql_stmt_free_result()`

`my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)`

A définir.

Description

Valeur retournée

Erreurs

#### 24.2.7.12. `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()` » pour plus de détails.

Valeurs retournées

La valeur générée puor 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.2.7.13. `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 reoturnées dans les variables `*buffer` et `*length`, basées sur le type de buffer, 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 | Length
`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`

où `*data_length` ne vaut rien d'autre que 'la taille réelle des donées'.

Valeurs retournées

Return Value | 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ées ou de lignes.

Erreurs

- `CR_COMMANDS_OUT_OF_SYNC`

  `Commands were executed in an improper order` : les commandes ont été exécutées dans un ordre invalide.

- `CR_OUT_OF_MEMORY`

  `Out of memory` : plus de mémoire.

- `CR_SERVER_GONE_ERROR`

  `The MySQL server has gone away` : Le serveur MySQL s'est éteint.

- `CR_SERVER_LOST`

  `The connection to the server was lost during the query` : la connexion au serveur a été perdue durant la requête.

- `CR_UNKNOWN_ERROR`

  `An unknown error occurred` : Une erreur inconnue est survenue.

- `CR_UNSUPPORTED_PARAM_TYPE`

  `If the buffer type is MYSQL_TYPE_DATE,DATETIME,TIME,or TIMESTAMP; and if the field type is not DATE, TIME, DATETIME or TIMESTAMP` Le buffer est de type MYSQL_TYPE_DATE,DATETIME,TIME ou TIMESTAMP et le type de champs 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()` Cette exemple s'attend à lire les deux lignes insérées dans l'exemple de Section 24.2.7.10, « `mysql_stmt_execute()` ».) La variable `mysql` est supposée être une connexion valide.

    #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ètrs 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éta-donné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, lis 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éta-donné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.2.7.14. `mysql_stmt_fetch_column()`

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

A définir.

Description

Valeur retournée

Erreurs

#### 24.2.7.15. `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 colonne, si un jeu de résultats existe.

Erreurs

Aucune.

#### 24.2.7.16. `mysql_stmt_init()`

`MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)`

Description

Crée une structure MYSQL_STMT.

Valeur 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`

  Out of memory : plus de mémoire.

#### 24.2.7.17. `mysql_stmt_num_rows()`

`my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)`

Description

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

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édiamtement.

Valeur retournée

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

Erreurs

Aucun.

#### 24.2.7.18. `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.19. `mysql_stmt_param_metadata()`

`MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)`

A définir.

Description

Valeurs retournées

Erreurs

#### 24.2.7.20. `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 variable 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 Defination Language (DDL)`.

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

Valeur retournées

Erreurs

- `CR_COMMANDS_OUT_OF_SYNC`

  `Commands were executed in an improper order` : les commandes ont été exécutées dans un ordre invalide.

- `CR_OUT_OF_MEMORY`

  `Out of memory` : plus de mémoire.

- `CR_SERVER_GONE_ERROR`

  `The MySQL server has gone away` : le serveur s'est éteint durant l'exécution de la requête.

- `CR_SERVER_LOST`

  `The connection to the server was lost during the query` : la connexion au serveur a été perdue.

- `CR_UNKNOWN_ERROR`

  `An unknown error occurred` : 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.21. `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épartion. 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`

  `Commands were executed in an improper order.` : Les commandes ont été exécutées dans un ordre invalide.

- `CR_SERVER_GONE_ERROR`

  `The MySQL server has gone away` : Le serveur s'est éteind.

- `CR_SERVER_LOST`

  `The connection to the server was lost during the query` : La connexion au serveur a été perdue durant l'exécution.

- `CR_UNKNOWN_ERROR`

  `An unknown error occurred.` : Une erreur inconnue est survenue.

#### 24.2.7.22. `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éta données de résultats sous la forme d'un structure `MYSQL_RES`, qui peut être utilisée ultérieurement pour traiter des méta informations, telles qu 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 ave fini avec, grâce à la fonction `mysql_free_result()`. C'est similaire à la méthode pour libérer les ressources obtenus de `mysql_store_result()`.

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

Valeurs retournées

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

Erreurs

- `CR_OUT_OF_MEMORY`

  Out of memory : plus de mémoire

- `CR_UNKNOWN_ERROR`

  An unknown error occured : 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.23. `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ésultat 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.2.7.24. `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.2.7.25. `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 partie dans une colonne (qui sera de type TEXT ou BLOB), avec un type de caractère 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é 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()`. See Section 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`

  Commands were executed in an improper order : Les conmmandes ont été envoyées dans un ordre invalide.

- `CR_SERVER_GONE_ERROR`

  The MySQL server has gone away : le serveur MySQL s'est éteind.

- `CR_OUT_OF_MEMORY`

  Out of memory : plus de mémoire.

- `CR_UNKNOWN_ERROR`

  An unknown error occured : une erreur inconnue s'est produite.

Exemple

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

    #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.2.7.26. `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 ait é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 MySQL.

Notez que toutes les erreurs MySQL ne sont pas associée à 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.2.7.27. `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 de 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()` retourne 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()` ».

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. See Section 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`

  Commands were executed in an improper order : les commandes ont été exécutées dans un ordre invalide.

- `CR_OUT_OF_MEMORY`

  Out of memory : plus de mémoire.

- `CR_SERVER_GONE_ERROR`

  The MySQL server has gone away : le serveur MySQL s'est éteind.

- `CR_SERVER_LOST`

  The connection to the server was lost during the query : la connexion au serveur MySQL s'est interrompue durant la commande.

- `CR_UNKNOWN_ERROR`

  An unknown error occurred : une erreur inconnue est survenue.

### 24.2.8. Problèmes avec l'interface C des commandes préparées

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

- `TIME`, `TIMESTAMP` et `DATETIME` ne supportent pas les fractions de secondes (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.2.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 peut être obtenu avec `mysql_more_results()` et `mysql_next_result()`.

      /* 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.2.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 ».

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ée 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.

    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.2.11. Description des fonctions threadées de C

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

#### 24.2.11.1. `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ûr 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.2.11.2. `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.2.11.3. `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 part `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.2.11.4. `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.2.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. See Section 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.2.12.1. `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 fournit 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) si 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. See Section 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

    #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 fonction 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.2.12.2. `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.2.13. Questions courantes sur la bibliothèque C

#### 24.2.13.1. 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 du 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.2.13.2. 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 re-créé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`. See Section 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'informations additionelles.

#### 24.2.13.3. 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` :

    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()` ».

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 :

    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.2.13.4. 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 :

    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.2.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`. See Section 24.1.2, « `mysql_config` lit les options de compilations du client MySQL ».

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

    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.2.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 devraient ê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 compatible avec les threads). Les nouvelles distributions binaires doivent disposer des deux bibliothèques, compatibles ou non avec les threads.

Pour obtenir une 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 interruption ou des expirations, vous pouvez compiler simplement une bibliothèque compatible avec les threads, `(mysqlclient_r)` et l'utiliser. See Section 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 utiliser des routines issues de la bibliothèque `mysys`, la seule chose à penser est de commencer par utiliser `my_init()`! See Section 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 :

    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'ils utilisent `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 appel une fonction MySQL qui n,a pas crée 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 libaririe de débogage (entre autres).

Si vous appelez une fonction MYSQL, avant que le thread n'ai 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, si 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 utiliser par les variables spécifiques MySQL.

Vous pouvez rencontrer des erreurs à cause des symboles non définis lors du link 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.2.16. `libmysqld`, la bibliothèque du serveur embarqué MySQL

#### 24.2.16.1. 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 inclues 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. See Section 24.2.12.1, « `mysql_server_init()` ».

#### 24.2.16.2. 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.2.16.3. 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 pile 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ée en éditant le fichier `mysql_embed.h` et recompilant MySQL.

#### 24.2.16.4. 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. See Section 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.2.16.5. 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 options 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.2.16.6. 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 ccet 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`

    /*
     * 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 tout 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`

    # 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 programes 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.2.16.7. 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'information, voyez http://www.mysql.com/company/legal/licensing/.

## 24.3. 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.3.1. Problèmes fréquents avec MySQL et PHP

- Error: "Maximum Execution Time Exceeded" C'est une limitation de PHP; Editez 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 à 16MB.

- 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étails 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.4. 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 base 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 remple 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 ».

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

      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.5. 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.5.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 pre-allouée.

## 24.6. 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.7. 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.8. 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.

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

Précédent |  | Suivant
Chapitre 23. Mathématiques de précision | Sommaire | Chapitre 25. Pilotes MySQL