Manuel de référence MySQL 5.0

my_ulonglong mysql_affected_rows(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

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

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

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

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

Description

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

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

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

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

Valeur de retour

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

Erreurs

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

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

Exemple

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 a été créée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

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

Exemple

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ésultats de requête. Cela nécessite que la structure du jeu de résultats contienne la totalité du résultat de la requête, de ce fait mysql_data_seek() peut être utilisée en conjonction avec mysql_store_result(), mais pas avec mysql_use_result().

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

Valeur de retour

Aucune.

Erreurs

Aucune.

void mysql_debug(const char *debug)

Description

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

Valeur de retour

Aucune.

Erreurs

Aucune.

Exemple

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

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 a été effacée avec succès. Différente de zéro si une erreur est survenue.

Erreurs

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

Exemple

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

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

my_bool mysql_eof(MYSQL_RES *result)

Description

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

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

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

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

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

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

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

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

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

Valeur de retour

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

Erreurs

Aucune.

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 une liste de plusieurs langues. Voir Section 5.8.2, « Langue des messages d'erreurs »5.8.2. Langue des messages d'erreurs.

Valeur de retour

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

Erreurs

Aucune.

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

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

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Description

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

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

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

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

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

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

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ésultats contient des données binaires, vous devez utiliser cette fonction pour déterminer la longueur des données, car strlen() retourne des résultats incorrects pour les champs contenant des caractères nuls.

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

Valeur de retour

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

Erreurs

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

Exemple

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 ligne à récupérer. Lorsqu'elle est utilisée après mysql_use_result(), mysql_fetch_row() retourne NULL quand il n'y a plus de ligne à récupérer ou qu'une erreur est rencontrée.

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

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

Valeur de retour

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

Erreurs

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

Exemple

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.

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

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

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

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 champs utilisé pour le dernier appel à mysql_fetch_field(). Cette valeur peut être utilisée en argument de mysql_field_seek().

Valeur de retour

L'indice courant du curseur de champs.

Erreurs

Aucune.

void mysql_free_result(MYSQL_RES *result)

Description

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

Valeur de retour

Aucune.

Erreurs

Aucune.

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

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

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

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

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

Exemple

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 correspondant à vos requêtes.

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

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

Valeur de retour

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

Erreurs

Aucune.

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 :

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

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

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

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

Valeur de retour

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

Erreurs

Aucune.

int mysql_kill(MYSQL *mysql, unsigned long pid)

Description

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

Valeur de retour

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

Erreurs

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

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

Description

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

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

void mysql_library_end(void)

Description

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

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

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

Description

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

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

Valeur de retour

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

Erreurs

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

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

Description

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

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

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

Valeur de retour

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

Erreurs

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

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

Description

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

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

Valeur de retour

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

Erreurs

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

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

Description

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

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

Valeur de retour

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

Erreurs

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

unsigned int mysql_num_fields(MYSQL_RES *result)

ou

unsigned int mysql_num_fields(MYSQL *mysql)

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

Description

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

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

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

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

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

my_ulonglong mysql_num_rows(MYSQL_RES *result)

Description

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

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

Valeur de retour

Le nombre de lignes dans le résultat.

Erreurs

Aucune.

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 »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 reconnexion automatique est tentée.

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

Valeur de retour

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

Erreurs

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

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

Description

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

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

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

Valeur de retour

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

Erreurs

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

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

Description

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

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

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

Valeur de retour

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

Erreurs

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

Exemple

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

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

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

Exemple

char query[1000],*end;

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

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

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

Valeur de retour

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

Erreurs

Aucune.

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

Description

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

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

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

Valeur de retour

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

Erreurs

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

int mysql_reload(MYSQL *mysql)

Description

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

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

Valeur retournée

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

Erreurs

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

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

Description

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

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

Valeur de retour

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

Erreurs

Aucune.

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

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

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 succès. Non nul si une erreur est survenue.

Erreurs

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

int mysql_shutdown(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

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

const char *mysql_sqlstate(MYSQL *mysql)

Description

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

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

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

Valeur retournée

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

Voir aussi

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

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

Description

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

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

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

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

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

Valeur retournée

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

char *mysql_stat(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

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

MYSQL_RES *mysql_store_result(MYSQL *mysql)

Description

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

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

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

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

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

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

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

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

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

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

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

Valeur de retour

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

Erreurs

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

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(). À la place, chaque ligne doit être récupérée manuellement à l'aide de la commande mysql_fetch_row(). Cela lit le résultat directement à partir du serveur sans l'enregistrer dans une table temporaire ou un tampon local, ce qui est plus rapide et utilise moins de mémoire que mysql_store_result(). Le client n'allouera de la mémoire que pour la ligne courante et un tampon de communication qui peut aller jusqu'à max_allowed_packet octets.

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

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

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

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

Valeur de retour

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

Erreurs

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

unsigned int mysql_warning_count(MYSQL *mysql)

Description

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

Valeur retournée

Le nombre d'alertes.

Erreurs

Aucune.

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'autovalidation (autocommit). Si le paramètre mode vaut 1, l'autovalidation est activée. Dans le cas où il vaut 0, l'autovalidation est désactivée. Disponible depuis MySQL 4.1

Valeurs retournées

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

Erreurs

Aucune.

my_bool mysql_more_results(MYSQL *mysql)

Description

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

Valeurs retournées

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

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

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

Erreurs

Aucune.

int mysql_next_result(MYSQL *mysql)

Description

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

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

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

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

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

Valeurs retournées

Erreurs

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

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

Description

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

Valeurs retournées

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

Erreurs

Aucune.

Exemple

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

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

Description

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

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

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

Valeur retournée

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

Erreurs

aucune

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ésente 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 doivent être configurés comme décrit dans la section Section 24.2.5, « Types de données de l'API C »24.2.5. Types de données de l'API C.

Valeurs retournées

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

Erreurs

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

Exemple

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

my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Description

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

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

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

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

Valeurs retournées

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

Erreurs

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

Exemple

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

my_bool mysql_stmt_close(MYSQL_STMT *)

Description

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

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

Valeur retournée

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

Erreurs

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

Exemple

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

void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)

Description

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

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

Valeurs retournées

Aucune.

Erreurs

Aucune.

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

Description

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

Valeurs retournées

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

Erreurs

Aucune

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 peut être modifiée à la compilation de la bibliothèque cliente MySQL. Actuellement, vous pouvez choisir les messages d'erreur dans plusieurs langues.

Valeurs retournées

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

Erreurs

Aucune

int mysql_stmt_execute(MYSQL_STMT *stmt)

Description

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

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

Valeurs retournées

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

Erreurs

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

Exemple

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)

À 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() »24.2.3.33. mysql_insert_id() pour plus de détails.

Valeurs retournées

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

Erreurs

Aucune.

int mysql_stmt_fetch(MYSQL_STMT *stmt)

Description

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

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

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

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

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

Valeurs retournées

Erreurs

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

Exemple

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

#define STRING_SIZE 50

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

Description

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

Valeur retournée

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

Erreurs

• CR_INVALID_PARAMETER_NO

Un indice de colonne non valide.

• CR_NO_DATA

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

unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)

Description

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

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

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

Valeurs retournées

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

Erreurs

Aucune.

MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)

Description

Crée une structure MYSQL_STMT.

Valeurs retournées

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

Erreurs

• CR_OUT_OF_MEMORY
  Plus de mémoire.

my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)

Description

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

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

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

Valeur retournée

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

Erreurs

Aucun.

unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)

Description

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

Valeurs retournées

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

Erreurs

Aucune.

Exemple

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

MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)

Cette fonction ne fait rien actuellement.

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

Description

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

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

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

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

Valeurs retournées

Erreurs

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

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

Exemple

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

my_bool mysql_stmt_reset(MYSQL_STMT *stmt)

Description

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

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

Valeurs retournées

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

Erreurs

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

MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)

Description

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

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

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

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

Valeurs retournées

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

Erreurs

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

Exemple

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

MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)

Description

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

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

Valeur retournée

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

Erreurs

Aucune.

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 parties dans une colonne (qui sera de type TEXT ou BLOB), avec un type de caractères ou de données binaires.

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

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

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

Valeurs retournées

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

Erreurs

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

Exemple

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

#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 a été utilisée. Le code d'erreur est constitué de 5 caractères. "00000" signifie « pas d'erreur ». Les valeurs sont spécifiées par les normes ANSI SQL et ODBC. Pour une liste des valeurs possibles, voyez Chapitre 26, Gestion des erreurs avec MySQLChapitre 26. Gestion des erreurs avec MySQL.

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

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

Valeur retournée

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

int mysql_stmt_store_result(MYSQL_STMT *stmt)

Description

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

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

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

Valeurs retournées

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

Errors

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

void my_init(void)

Description

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

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

Valeur de retour

Aucune.

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

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

Valeur de retour

Aucune.

unsigned int mysql_thread_safe(void)