Chapitre 24 API MySQL

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.

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

Exemple

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

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.

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.

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

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

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

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.

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

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

Exemple

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

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

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

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.

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.

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.

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 0xvalue ou X'value'. Cependant, la valeur de retour n'inclut pas les éléments de syntaxe 0x ou X'...'. Le code appelant doit fournir les éléments dont il a besoin.

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

Exemple

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.

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.

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.

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

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 :

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.

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

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.

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.

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

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

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

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

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

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.

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 :

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 :

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.

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

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

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 :

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

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.

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.

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

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

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.

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.

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

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 :

Valeur retournée

Zéro en cas de succes. Non nul si une erreur est survenue.

Erreurs

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

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

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 :

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.

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

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

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.

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

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.

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

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.

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.

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.

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

Erreurs

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

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

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 :

Valeur retournée

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

Erreurs

aucune

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

Exemple

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

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

Example

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

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

Exemple

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

void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)

Description

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

Cette fonction impose que la structure du jeu de ré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.

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

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

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

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.

my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)

A définir.

Description

Valeur retournée

Erreurs

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.

int mysql_stmt_fetch(MYSQL_STMT *stmt)

Description

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

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

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

Si les données lues contiennent la valeur NULL, alors la valeur is_null de MYSQL_BIND contiendra TRUE, 1, ou sinon, les données et leur longueur seront retournées dans les variables *buffer et *length, basées sur le type de 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.

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

Valeurs retournées

Erreurs

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

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

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.

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

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.

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

MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)

A définir.

Description

Valeurs retournées

Erreurs

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

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

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

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 :

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

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

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.

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.

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

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

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.

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

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.

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.

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.

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.

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 [embedded] 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.

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.

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 :

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

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

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

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.

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 :

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

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.

Le serveur embarqué possède les limitations suivantes :

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

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

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 programmes de tests sur un simple fichier
sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
targets := $(basename $(sources))

all: $(targets)

clean:
	rm -f $(targets) $(objects) *.core

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