8 Les interfaces pour MySQL

Ce chapitre décrit les interfaces fournies par plusieurs langages pour MySQL, où les obtenir, et comment les utiliser. L'interface C est la plus abordée dans ce chapitre, puisqu'elle a été développée par l'équipe de MySQL, et qu'elle sert de base à toutes les autres interfaces.

8.1 API PHP pour MySQL

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

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

8.1.1 Problèmes fréquents avec MySQL et PHP

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

8.2 API Perl pour MySQL

Cette section documente l'interface DBI de Perl. L'ancienne interface s'appelait mysqlperl. DBI/DBD est maintenant l'interface recommandée avec Perl et donc mysqlperl est obsolète et n'est pas documentée ici.

8.2.1 DBI avec DBD::mysql

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

Pour plus d'informations sur le module DBI de Perl5, visitez la page web de DBI et lisez la documentation :

http://dbi.perl.org/

Pour plus d'informations sur la programmation orientée objets (OOP) comme la définie Perl5, voyez la page OOP de Perl :

http://language.perl.com/info/documentation.html

Notez que si vous voulez utiliser les transactions avec Perl, vous avez besoin d'avoir au moins la version 1.2216 de Msql-Mysql-modules.

Le module Perl recommandé est DBD-mysql-2.1022 ou plus récent.

Les instructions pour l'installation du support Perl de MySQL sont données dans section 2.7 Commentaires sur l'installation de Perl.

Si vous avez le module MySQL installé, vous pouvez trouver des informations à propos des fonctionnalités spécifiques de MySQL avec l'une de ces commandes :

shell> perldoc DBD/mysql
shell> perldoc mysql

8.2.2 L'interface DBI

Méthodes portables

Méthodes spécifiques à MySQL

Les méthodes Perl sont décrites dans les sections suivantes. Les variables utilisée pour les valeurs de retour des méthodes ont les significations suivantes :

$dbh

Gestionnaire de base de données

$sth

Gestionnaire de requête

$rc

Code de retour (souvent un status)

$rv

Valeur de retour (souvent un comptage de lignes)

Méthodes DBI portables

connect($data_source, $username, $password)

Utilise la méthode connect pour crée une connexion de base de données à la source. La valeur doit commencer par DBI:nom_pilote:. Exemples d'utilisation de connect avec le pilote DBD::mysql :

$dbh = DBI->connect("DBI:mysql:$database", $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname",
                    $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",
                    $user, $password);

Si le nom d'utilisateur et/ou le mot de passe ne sont pas définis, DBI utilises la valeur des variables d'environnements DBI_USER et DBI_PASS, respectivement. Si vous ne spécifiez pas un nom d'hôte, il est à 'localhost' par défaut. Si vous ne spécifiez pas un numéro de port, il est mit par défaut au port par défaut de MySQL (3306). Depuis la version 1.2009 de Msql-Mysql-modules, la valeur de $data_source accepte certains modificateurs :

mysql_read_default_file=nom_du_fichier

Lit le fichier `filename' en tant que fichier d'options. Pour plus d'informations sur les fichiers d'options, consulter section 4.1.2 Fichier d'options `my.cnf'.

mysql_read_default_group=nom_du_groupe

Le groupe par défaut lors de la lecture d'un fichier d'options est normalement le groupe [client]. En spécifiant l'option mysql_read_default_group, le groupe par défaut devient le groupe [nom_du_groupe].

mysql_compression=1

Utiliser la communication compressée entre le client et le serveur (à partir de la version 3.22.3 de MySQL).

mysql_socket=/path/to/socket

Spécifie le chemin vers la socket Unix qui est utilisée pour se connecter au serveur. (MySQL version 3.21.15 ou plus).

Plusieurs modificateurs peuvent être donnés, ils doivent être séparés par des point-virgules. Par exemple, si vous voulez éviter d'avoir à écrire le nom d'utilisateur et le mot de passe en dur dans un script DBI, vous pouvez le prendre du fichier utilisateur d'options `~/.my.cnf' en écrivant votre appel à connect de la façon suivante :

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
                $user, $password);

Cet appel lira les options définies pour le groupe [client] dans le fichier d'options. Si vous voulez le faire aussi pour le groupe [perl] par exemple, vous pouvez utiliser ce qui suit :

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf"
                . ";mysql_read_default_group=perl",
                $user, $password);

disconnect

La méthode disconnect déconnecte le gestionnaire de base de données du serveur. On y fait appel avant de terminer le programme. Exemple :

$rc = $dbh->disconnect;

prepare($statement)

Prépare une requête SQL pour l'exécution par le serveur de base de données et retourne un gestionnaire de requête ($sth), que vous pouvez utiliser pour invoquer la méthode execute. Le plus souvent, vous gérez les requêtes SELECT (et ceux qui s'en rapprochent, comme SHOW, DESCRIBE, et EXPLAIN) à l'aide de prepare et execute. Exemple :

$sth = $dbh->prepare($statement)
    or die "Impossible de préparer $statement: $dbh->errstr\n";

execute

La méthode execute exécute une requête préparée. Pour les commandes qui ne se rapprochent pas de SELECT, execute retourne le nombre de lignes affectées. Si aucune ligne ne l'est, execute retourne "0E0", que Perl traite comme zéro mais considère comme vrai (true). Si une erreur survient, execute retourne undef. Pour les requêtes SELECT, execute ne fait que démarrer la requête SQL dans la base de données; vous avez besoin d'utiliser une des méthodes fetch_* décrites ici pour récupérer les données. Exemple :

$rv = $sth->execute
          or die "ne peut exécuter la requête : $sth->errstr;

do($statement)

La méthode do prépare et exécute une requête SQL et retourne le nombre de lignes affectées. Si aucune ne l'est, do retourne "0E0", que Perl traite comme zéro mais considère comme vrai (true). Cette méthode est généralement utilisée pour les requêtes qui ne se rapprochent pas de SELECT qui ne peuvent être préparées à l'avance (à cause d'une limitation du pilote) ou qui n'ont pas besoin d'être exécutées plus d'une fois (insertions, suppressions, etc.). Exemple :

$rv = $dbh->do($statement)
        or die "Ne peut exécuter la commande $statement: $dbh- >errstr\n";

Généralement, la commande 'do' est plus rapide (et préférable) à prepare/execute pour les requêtes ne contenant pas de paramètres.

quote($string)

La méthode quote est utilisée pour protéger les caractères spéciaux contenus dans la chaîne et ajouter les guillemets externes requis. Exemple :

$sql = $dbh->quote($string)

fetchrow_array

Cette méthode récupère la ligne de données suivante et la retourne en tant que tableau de valeurs de champs. Exemple :

while(@row = $sth->fetchrow_array) {
        print qw($row[0]\t$row[1]\t$row[2]\n);
}

fetchrow_arrayref

Cette méthode récupère la ligne de données suivante et la retourne en tant que référence de tableau de valeurs de champs. Exemple :

while($row_ref = $sth->fetchrow_arrayref) {
        print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n);
}

fetchrow_hashref

Cette méthode récupère la ligne de données et retourne une référence vers un tableau associatif contenant des paires nom du champ / valeur. Cette méthode n'est pas aussi efficace que l'utilisation des références sur tableaux comme expliqué plus haut. Exemple :

while($hash_ref = $sth->fetchrow_hashref) {
        print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\
                $hash_ref- > title}\n);
}

fetchall_arrayref

Cette méthode est utilisée pour faire en sorte que toutes les données (lignes) soient retournées par la requête SQL. Elle retourne une référence à un tableau de références à des tableaux pour chaque ligne. Vous pouvez accéder aux données en utilisant des boucles profondes. Exemple :

my $table = $sth->fetchall_arrayref
                or die "$sth->errstr\n";
my($i, $j);
for $i ( 0 .. $#{$table} ) {
        for $j ( 0 .. $#{$table->[$i]} ) {
                print "$table->[$i][$j]\t";
        }
        print "\n";
}

finish

Indique que plus aucune donnée ne sera récupérée du gestionnaire de requête. Vous appelez cette méthode pour libérer le gestionnaire de connexion et les ressources système lui étant associées. Exemple :

$rc = $sth->finish;

rows

Retourne le nombre de lignes changées (mises à jour, supprimées, etc.) par la dernière commande. En l'utilise généralement après les requêtes autres que SELECT exécutées avec la méthode execute. Exemple :

$rv = $sth->rows;

NULLABLE

Retourne une référence vers un tableau de valeurs qui indiquent si les colonnes peuvent contenir des valeurs NULL. Les valeurs possibles pour chaque élément sont 0 ou la chaîne vide si la colonne ne peut être NULL, 1 si elle peut, et 2 si l'état NULL de la colonne est inconnu. Exemple :

$null_possible = $sth->{NULLABLE};

NUM_OF_FIELDS

Cet attribut indique le nombre de champs retournés par une requête SELECT ou SHOW FIELDS. Vous pouvez l'utiliser pour savoir si une requête a retourné un résultat : une valeur nulle indique que la requête n'est pas une sélection, comme INSERT, DELETE, ou UPDATE. Exemple :

$nr_of_fields = $sth->{NUM_OF_FIELDS};

data_sources($driver_name)

Cette méthode retourne un tableau contenant les noms des bases de données disponibles pour le serveur MySQL sur l'hôte 'localhost'. Exemple :

@dbs = DBI->data_sources("mysql");

ChopBlanks

Cet attribut détermine si les méthodes fetchrow_* enlèvent les caractères blancs au début et à la fin des valeurs retournées. Exemple :

$sth->{'ChopBlanks'} =1;

trace($trace_level)

trace($trace_level, $trace_filename)

La méthode trace active ou désactive le traçage. Lorsqu'elle est invoquée en tant que méthode de la classe DBI, elle affecte le traçage à tout les gestionnaire. Lorsqu'elle est invoquée comme un gestionnaire de base de données ou de requête, elle n'affecte le traçage que pour le gestionnaire donné (et tout ses descendants). Mettre $trace_level à 2 fournit des informations détaillées de traçage. Le mettre à 0 désactive le traçage. Les sorties de traçages vont dans la sortie d'erreurs standards par défaut. Si $trace_filename est spécifié, le fichier est ouvert et le pointeur de fichier est placé à la fin de celui-ci et les sorties de tout les gestionnaires tracés sont écrits dans ce fichier. Exemple :

DBI->trace(2);                # trace tout
DBI->trace(2,"/tmp/dbi.out"); # trace tout dans
                              # /tmp/dbi.out
$dth->trace(2);               # trace ce gestionnaire de base de données
$sth->trace(2);               # trace ce gestionnaire de requête

Vous pouvez aussi activer le traçage DBI en définissant la variable d'environnement DBI_TRACE. La définir en tant que valeur numérique revient à appeler DBI->(value). La définir en tant que chemin revient à appeler DBI->(2,value).

Méthodes spécifiques à MySQL

Les méthodes montrées ici sont spécifiques à MySQL et ne font pas partie du standard DBI. Beaucoup d'entre-elles sont aujourd'hui désapprouvées : is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length, et table. Lorsque des alternatives utilisant le standard DBI existent, elles sont mentionnées ici :

insertid

Si vous utilisez la fonctionnalité AUTO_INCREMENT de MySQL, la nouvelle valeur auto-incrémentée sera stockée ici. Exemple :

$new_id = $sth->{insertid};

Vous pouvez, en alternative, utiliser $dbh->{'mysql_insertid'}.

is_blob

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question est un BLOB. Exemple :

$keys = $sth->{is_blob};

is_key

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question est une clef. Exemple :

$keys = $sth->{is_key};

is_num

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question contient une valeur numérique. Exemple :

$nums = $sth->{is_num};

is_pri_key

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur TRUE indique que la colonne en question est une clef primaire. Exemple :

$pri_keys = $sth->{is_pri_key};

is_not_null

Retourne une référence vers un tableau de valeurs booléennes; pour chaque élément du tableau, une valeur FALSE indique que la colonne peut contenir NULL values. Exemple :

$not_nulls = $sth->{is_not_null};

is_not_null est désapprouvé; il est préférable d'utiliser l'attribut NULLABLE (décrit plus haut), car c'est un standard DBI.

length

max_length

Chacune de ces méthodes retourne une référence vers un tableau de tailles de colonnes. Le tableau length indique les tailles maximales de colonnes (comme déclarés lors de la création de la table). Le tableau max_length indique la plus grande taille occupée jusqu'à présent dans les colonnes de la table. Exemple :

$lengths = $sth->{length};
$max_lengths = $sth->{max_length};

NAME

Retourne une référence vers un tableau de noms de colonnes. Exemple :

$names = $sth->{NAME};

table

Retourne une référence vers un tableau de noms de tables. Exemple :

$tables = $sth->{table};

type

Retourne une référence vers un tableau de types de colonnes. Exemple :

$types = $sth->{type};

8.2.3 Plus d'informations relatives à DBI/DBD

Vous pouvez utiliser la commande perldoc pour obtenir plus d'informations à propos de DBI.

perldoc DBI
perldoc DBI::FAQ
perldoc DBD::mysql

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

Vous pouvez trouver les dernières informations relatives à DBI à l'adresse suivante : http://dbi.perl.org/.

8.3 Support ODBC avec MySQL

MySQL fournit un support de ODBC via le programme MyODBC. Ce chapitre vous apprendra à installer MyODBC, et à l'utiliser. Vous trouverez aussi une liste de programmes connus pour leur utilisation de MyODBC.

8.3.1 Comment installer MyODBC

MyODBC 2.50 est un pilote 32-bit ODBC 2.50 avec un niveau de spécification 0 (avec le niveau 1 et 2 de proposés) pour connecter une application compatible ODBC à MySQL. MyODBC fonctionne sur Windows 9x/Me/NT/2000/XP et la plupart des plate-formes Unix. MyODBC 3.51 est une version améliorée avec les spécifications de niveau 1 de ODBC 3.5x (API noyau complète + fonctionnalités du niveau 2).

MyODBC est Open Source, et vous pouvez trouver la version la plus récente sur http://www.mysql.com/downloads/api-myodbc.html. Notez que les version 2.50.x sont licencées LGPL tandis que les versions 3.51.x sont licencées GPL.

Si vous avez des problèmes avec MyODBC et que votre programme fonctionne aussi avec OLEDB, essayez le pilote OLEDB.

Normalement, vous n'avez besoin d'installer MyODBC que sur les machines Windows. Vous avez besoin d'installer MyODBC sous Unix si vous avez un programme tel que ColdFusion qui fonctionne sur les machines Unix et utilise ODBC pour se connecter aux bases de données.

Si vous voulez installer MyODBC sur un ordinateur Unix, vous aurez aussi besoin d'un gestionnaire ODBC. MyODBC est connu pour fonctionner avec la plupart des gestionnaires ODBC d'Unix.

Pour installer MyODBC sur Windows, vous devez télécharger le fichier `.zip' de MyODBC approprié, le décompresser avec WinZIP ou un programme similaire et exécuter le fichier `SETUP.EXE'.

Sur Windows/NT/XP vous pouvez obtenir l'erreur suivante durant l'installation de MyODBC :

An error occurred while copying C:\WINDOWS\SYSTEM\MFC30.DLL. Restart
Windows and try installing again (before running any applications which
use ODBC)

Le problème dans ce cas est qu'un autre programme utilise ODBC et du fait de l'architecture Windows, vous ne pouvez pas installer de nouveau pilote ODBC avec le programme d'installation de Microsoft ODBC. Dans la plupart des cas, vous pouvez continuer en clickant juste sur Ignore pour copier le reste des fichiers MyODBC et l'installation finale devrait fonctionner. Si ce n'est pas le cas, la solution est de redémarrer votre machine en mode ``safe mode`` (faites le en appuyant sur F8 juste avant que votre machine ne démarre Windows), installez MyODBC, et redémarrez en mode normal.

• Pour créer une connexion à un ordinateur Unix depuis un ordinateur Windows, avec une application ODBC (une qui ne supporte pas MySQL nativement), vous devez installer MyODBC sur l'ordinateur Windows.
• L'utilisateur et la machine Windows doivent avoir les droits d'accès au serveur MySQL situé sur la machine Unix. vous pouvez configurer cela avec la commande GRANT. See section 4.3.1 Syntaxe de GRANT et REVOKE.
• Vous devez créer une entrée DNS ODBC comme suit :
  • Ouvrez le panneau de configuration de Windows.
  • Double-clickez sur l'icône Sources de données ODBC (32 bits).
  • Clickez sur le volet User DSN.
  • Clickez sur le bouton Add.
  • Sélectionnez MySQL dans l'écran Create New Data Source et clickez sur le bouton Terminer.
  • L'écran de configuration par défaut du pilote MySQL est affiché. See section 8.3.2 Comment remplir les différents champs dans le programme d'administrateur ODBC.
• Démarrez maintenant votre application et sélectionnez le pilote ODBC avec les DSN que vous avez spécifié dans l'administrateur ODBC.

Notez que d'autres options de configuration sont présentes dans l'écran de MySQL (traçage, se connecter automatiquement, etc.), vous pouvez les essayer en cas de problèmes.

8.3.2 Comment remplir les différents champs dans le programme d'administrateur ODBC

Il y a trois possibilités pour indiquer le nom du serveur sous Windows95 :

• Utiliser l'adresse IP du serveur.
• Ajouter un fichier `\windows\lmhosts' avec les informations suivantes :

  ip nomhote
  

  Pour exemple :

  194.216.84.21 mon_nom_hote
  

• Configurer le PC pour qu'il utilise DNS.

Exemple de valeurs dans l'installation ODBC :

Windows DSN name:   test
Description:        Ceci est ma base de données
MySql Database:     test
Server:             194.216.84.21
User:               monty
Password:           mon_pass
Port:

La valeur du champ Windows DSN name est n'importe quel nom qui est unique pour votre installation de ODBC sur Windows.

Vous n'avez pas besoin de spécifier des valeurs pour les champs Server, User, Password, et Port dans l'écran d'installation d'ODBC. Toutefois, si vous le faites, ces valeurs seront celles utilisées par défaut par la suite lorsque vous tenterez d'établir une connexion. Vous pourrez changez les options à ce moment là.

Si le numéro du port n'est pas donné, le port par défaut (3306) est utilisé.

Si vous spécifiez l'option Read options from C:\my.cnf, les groupes client et odbc seront lus à partir du fichier `C:\my.cnf'. Vous pouvez utiliser toutes les options utilisables par mysql_options(). See section 8.4.3.39 mysql_options().

8.3.3 Paramètres de connexion de MyODBC

Il est possible de spécifier les paramètres suivants à MyODBC dans la section [Servername] du fichier `ODBC.INI' ou bien, avec l'argument InConnectionString dans l'appel de SQLDriverConnect().

L'argument option est utilisé pour indiquer à MyODBC que le client n'est pas 100% compatible avec ODBC. Sous Windows, il est possible de configurer cette option en activant les options dans l'écran de connexion, mais il est aussi possible de le configurer dans ce paramètre. Les options suivantes sont listées dans l'ordre dans lequel elles apparaissent dans l'écran MyODBC :

Si vous voulez combiner des options, vous devez additionner les options ci-dessus. Par exemple, activer l'option 12 (4+8), active le déboggage sans limite de paquets.

La librairie par défaut `MYODBC.DLL' est compilée pour des performances optimales. Si vous voulez déboguer MyODBC (par exemple, pour activer le traçage), vous devriez utiliser `MYODBCD.DLL'. Pour installer ce ficher, copiez `MYODBCD.DLL' à la place de la librairie isntallé `MYODBC.DLL'.

8.3.4 Comment reporter les problèmes avec ODBC

MyODBC a été testé avec Access, Admndemo.exe, C++-Builder, Borland Builder 4, Centura Team Developer (formerly Gupta SQL/Windows), ColdFusion (on Solaris and NT with svc pack 5), Crystal Reports, DataJunction, Delphi, ERwin, Excel, iHTML, FileMaker Pro, FoxPro, Notes 4.5/4.6, SBSS, Perl DBD-ODBC, Paradox, Powerbuilder, Powerdesigner 32 bit, VC++, et Visual Basic.

Si vous avez connaissance de n'importe quelle autre application qui utilise MyODBC, merci d'envoyer un mail à myodbc@lists.mysql.com à ce propos !

Avec quelques programmes, vous pouvez avoir l'erreur suivante : Another user has modifies the record that you have modified. Dans la plupart des cas, le problème peut être résolu en suivant l'une des méthodes suivantes :

• ajouter une clef primaire à la table s'il n'en existe pas déjà une.
• Ajouter une colonne timestamp s'il n'y en a pas déjà une.
• N'utilisez que des champs réels doubles. Certains programmes peuvent se bloquer lorsqu'ils comparent des réels simples.

Si ce qui précède ne vous aide pas, vous devez tracer MyODBC et essayer de voir pourquoi les choses vont de travers.

8.3.5 Programmes qui fonctionnent avec MyODBC

La majorité des programmes devraient fonctionner avec MyODBC, mais tous ceux que nous avons listés ici sont ceux que nous avons testé nous même, ou dont nous avons reçu la confirmation de la part d'utilisateurs :

Programme

Commentaire

Access

Pour le faire fonctionner avec Access :

• Si vous utilisez Access 2000, vous devez installer la dernière Microsoft MDAC (Microsoft Data Access Components) (version 2.6 ou plus récente) depuis http://www.microsoft.com/data/. Cela va corriger le bug suivant d'Access : lorsque vous exportez des données vers MySQL, les noms de la table et des colonnes ne sont pas spécifiés. Un autre moyen de pallier à ce bug est de passer en MyODBC version 2.50.33 et MySQL version 3.23.x, qui, ensemble, forment un correctif à ce bug! Vous devriez aussi installer le Microsoft Jet 4.0 Service Pack 5 (SP5) disponible à http://support.microsoft.com/support/kb/articles/Q 239/1/14.ASP. Cela va corriger certains cas ou les colonnes étaient marquées comme effacées (#deleted#) dans Access. Notez que si vous utilisez MySQL version 3.22, vous devez appliquer le patch MDAC et utiliser MyODBC 2.50.32 ou 2.50.34 et plus récent pour corriger ce bug.
• Pour toutes les versions d'Access, vous devez activer l'option MyODBC appelée Return matching rows. Pour Access 2.0, vous devez aussi activer Simulate ODBC 1.0.
• Vous devez avoir un timestamp dans toutes les tables que vous voulez pouvoir modifier. Pour une meilleure portabilité, TIMESTAMP(14) ou un simple TIMESTAMP est recommandé au lieu de TIMESTAMP(X).
• Vous devez avoir une clé primaire dans la table. Sinon, les nouvelles lignes et les lignes modifiées peuvent être marquées comme effacées #DELETED#.
• N'utilisez que les champs DOUBLE. Access échoue lors des comparaisons entre les champs en simple précision. Le symptôme est généralement que les nouvelles lignes ou les lignes modifiées sont marquées comme effacées (#DELETED#), ou que vous ne pouvez plus trouver les nouvelles lignes ou les lignes modifiées.
• Si vous reliez des tables via MyODBC, dont l'une des colonnes est de type BIGINT, les résultats sont affichés comme effacés (#DELETED). La solution est :
  • Avoir au moins une colonne de type TIMESTAMP comme type de données, et de préférence TIMESTAMP(14).
  • Vérifiez l'option de connexion 'Change BIGINT columns to INT' dans l'administrateur ODBC DSN.
  • Effacez le lien de table dans Access, et recréez le.
  Les anciennes lignes seront toujours marquées comme #DELETED#, mais les nouvelles lignes seront affichées correctement.
• Si vous butez toujours dans l'erreur Another user has changed your data après avoir ajouté une colonne TIMESTAMP, le truc suivant peut vous aider : N'utilisez pas la vue de table au format tableur. A la place, créez un formulaire avec les champs que vous souhaitez, et utilisez ce formulaire comme vue de la table. Vous devez utiliser la propriété DefaultValue pour la colonne TIMESTAMP, avec la valeur NOW(). C'est une bonne idée de cacher la colonne TIMESTAMP à vos utilisateurs, pour qu'ils ne soient pas perturbés.
• Dans certains cas, Access peut générer des requêtes SQL illégales, que MySQL ne peut comprendre. Vous pouvez corriger cela en sélectionnant "Query|SQLSpecific|Pass-Through" dans le menu Access.
• Access sur NT va indiquer que les colonnes BLOB sont des OLE OBJECTS. Si vous voulez avoir des colonnes de type MEMO à la place, vous devez changer le type de la colonne en TEXT avec ALTER TABLE.
• Access ne peut pas toujours gérer correctement les colonnes DATE. Sis vous avez des problèmes avec, changez ces colonnes en type DATETIME.
• Si vous avec une colonne Access de type BYTE, Access va essayer de l'exporter sous la forme d'un TINYINT au lieu d'un TINYINT UNSIGNED. Cela va vous donner des problèmes si vous avez des valeurs supérieures à 127!

ADO

Lorsque vous programmez avec l'API ADO et MyODBC vous devez faire attention aux propriétés par défaut qui ne sont pas supportées par MySQL. Par exemple, utiliser la propriété CursorLocation Property comme adUseServer va retourner des valeurs de -1 pour RecordCount Property. Pour avoir la véritable valeur, vous devez utiliser la valeur adUseClient, comme dans le code VB ci-contre :

Dim myconn As New ADODB.Connection
Dim myrs As New Recordset
Dim mySQL As String
Dim myrows As Long

myconn.Open "DSN=MyODBCsample"
mySQL = "SELECT * from user"
myrs.Source = mySQL
Set myrs.ActiveConnection = myconn
myrs.CursorLocation = adUseClient
myrs.Open
myrows = myrs.RecordCount

myrs.Close
myconn.Close

Un autre palliatif est d'utiliser la commande SELECT COUNT(*), pour connaître le nombre exact de lignes.

Active server pages (ASP)

Vous devez utiliser l'option Return matching rows.

Applications BDE

Pour faire fonctionner ces applications, vous devez activer les options Don't optimize column widths et Return matching rows.

Borland Builder 4

Lorsque vous démarrez une requête, vous pouvez utiliser la propriété Active ou utiliser la méthode Open. Notez que Active va commencer en générant automatiquement une requête SELECT * FROM ... qui peut ne pas être pratique avec de grosses tables!

ColdFusion (On Unix)

Les informations suivantes sont reprises de la documentation ColdFusion : Utilisez les informations suivantes pour configurer le serveur ColdFusion Server sous Linux pour utiliser le pilote unixODBC avec MyODBC pour les serveurs MySQL. Allaire a vérifié que MyODBC version 2.50.26 fonctionne avec MySQL version 3.22.27 et ColdFusion pour Linux. (toute nouvelle version doit aussi fonctionner). Vous pouvez télécharger MyODBC à http://www.mysql.com/downloads/api-myodbc.html ColdFusion version 4.5.1 vous permet d'utiliser l'administrateur ColdFusion pour ajouter des serveurs MySQL. Toutefois, le pilote n'est pas inclus dans ColdFusion version 4.5.1. Auparavant, le pilote MySQL était disponible dans le menu déroulant. Vous devez compiler et copier le pilote MyODBC dans `/opt/coldfusion/lib/libmyodbc.so'. Le dossier Contrib contient le programme `mydsn-xxx.zip' qui vous permet de compiler et supprimer des fichiers d'enregistrement DSN pour MyODBC sur les applications Coldfusion.

DataJunction

Vous devez le modifier pour qu'il exporte des VARCHAR plutôt que des ENUM, car il exporte ces derniers d'une manière qui pose des problèmes à MySQL.

Excel

Fonctionne. Quelques conseils :

• Si vous avez des problèmes avec les dates, essayez de les sélectionner comme des chaînes, en utilisant la fonction CONCAT(). Par exemple :

  select CONCAT(rise_time), CONCAT(set_time)
      from sunrise_sunset;
  

  Les valeurs lues sous forme de chaînes seront correctement relues par Excel97. Le but de la fonction CONCAT() est de faire croire à ODBC que cette colonne est de type ``string''. Sans la fonction CONCAT(), ODBC sait que la colonne est de type heure, et Excel ne le comprendra pas. Notez qu'il y a un bug dans Excel, car il convertit automatiquement une chaîne en heure. Cela serait bien si la source était un fichier texte, mais c'est totalement idiot si la source est une connexion ODBC qui fournit les types exacts.

Word

Pour lire des données depuis MySQL vers des documents Word ou Excel, vous devez utiliser le pilote MyODBC et l'aide Add-in Microsoft Query. Par exemple, pour créer une base de données avec une table contenant 2 colonnes de type texte :

• Insérez des lignes avec le client mysql.
• Créez un fichier DSN en utilisant le gestionnaire ODBC, par exemple, `my' pour la base ci-dessus.
• Ouvrez Word.
• Créez un nouveau document vide.
• Utilisez la barre "Database", pressez sur le bouton d'insertion.
• Pressez sur le bouton "Get Data".
• Sur la droite de l'écran, choisissez le bouton "Ms Query".
• Dans ce écran, créez une nouvelle source de données avec "New Data Source" et en utilisant le fichier DSN `my'.
• Sélectionner une nouvelle requête.
• Sélectionnez les colonnes que vous souhaitez.
• Faîtes votre filtre.
• Faîtes votre tri.
• Sélectionnez "Return Data" de Microsoft Word.
• Cliquez sur "Finish".
• Cliquez sur le bouton "Insert data" et sélectionnez les lignes.
• Cliquez sur "OK" et vous verrez vous lignes dans votre document Word.

odbcadmin

Programme de test pour ODBC.

Delphi

Vous devez utiliser BDE version 3.2 ou plus récent. Utilisez l'option Don't optimize column width lors de la connexion à MySQL. De plus, voici un code Delphi pratique, pour configurer une entrée ODBC et une entrée BDE pour MyODBC (l'entrée BDE requiert le BDE Alias Editor qui est gratuit sur les pages "Delphi Super Page" près de chez vous. (Merci à Bryan Brunton bryan@flesherfab.com pour cela ) :

fReg:= TRegistry.Create;
  fReg.OpenKey('\Software\ODBC\ODBC.INI\DocumentsFab', True);
  fReg.WriteString('Database', 'Documents');
  fReg.WriteString('Description', ' ');
  fReg.WriteString('Driver', 'C:\WINNT\System32\myodbc.dll');
  fReg.WriteString('Flag', '1');
  fReg.WriteString('Password', '');
  fReg.WriteString('Port', ' ');
  fReg.WriteString('Server', 'xmark');
  fReg.WriteString('User', 'winuser');
  fReg.OpenKey('\Software\ODBC\ODBC.INI\ODBC Data Sources', True);
  fReg.WriteString('DocumentsFab', 'MySQL');
  fReg.CloseKey;
  fReg.Free;

  Memo1.Lines.Add('DATABASE NAME=');
  Memo1.Lines.Add('USER NAME=');
  Memo1.Lines.Add('ODBC DSN=DocumentsFab');
  Memo1.Lines.Add('OPEN MODE=READ/WRITE');
  Memo1.Lines.Add('BATCH COUNT=200');
  Memo1.Lines.Add('LANGDRIVER=');
  Memo1.Lines.Add('MAX ROWS=-1');
  Memo1.Lines.Add('SCHEMA CACHE DIR=');
  Memo1.Lines.Add('SCHEMA CACHE SIZE=8');
  Memo1.Lines.Add('SCHEMA CACHE TIME=-1');
  Memo1.Lines.Add('SQLPASSTHRU MODE=SHARED AUTOCOMMIT');
  Memo1.Lines.Add('SQLQRYMODE=');
  Memo1.Lines.Add('ENABLE SCHEMA CACHE=FALSE');
  Memo1.Lines.Add('ENABLE BCD=FALSE');
  Memo1.Lines.Add('ROWSET SIZE=20');
  Memo1.Lines.Add('BLOBS TO CACHE=64');
  Memo1.Lines.Add('BLOB SIZE=32');

  AliasEditor.Add('DocumentsFab','MySQL',Memo1.Lines);

C++ Builder

Testé avec BDE version 3.0. Le seul problème connu est que lorsque la structure d'une table change, les champs de requêtes ne changent pas. BDE ne semble pas reconnaître les clés primaires, mais uniquement l'index PRIMARY, même si cela n'a jamais été un problème.

Vision

Vous devriez utiliser l'option Return matching rows.

Visual Basic

Pour être capable de modifier une table, vous devez définir une clé primaire. Visual Basic avec ADO ne peut pas gérer les grands entiers. Cela signifie que les requêtes comme SHOW PROCESSLIST ne vont pas fonctionner correctement. Le correctif consiste à ajouter l'option OPTION=16834 dans la chaîne de connexion ODBC pour d'utiliser l'option Change BIGINT columns to INT de MyODBC. Vous pouvez aussi utiliser l'option Return matching rows.

VisualInterDev

Si vous rencontrez l'erreur [Microsoft][ODBC Driver Manager] Driver does not support this parameter, la raison est que vous avez un grand entier BIGINT dans votre résultat. Essayez d'utiliser l'option Change BIGINT columns to INT de MyODBC.

Visual Objects

Vous devez utiliser l'option Don't optimize column widths.

8.3.6 Comment obtenir la valeur d'une colonne AUTO_INCREMENT avec ODBC

Un problème récurrent est d'obtenir la dernière valeur générée automatiquement par une commande INSERT. Avec ODBC, vous pouvez procéder de cette façon (en supposons que auto est un champ AUTO_INCREMENT):

INSERT INTO foo (auto,text) VALUES(NULL,'text');
SELECT LAST_INSERT_ID();

Ou, si vous voulez juste insérer cette valeur dans une autre table :

INSERT INTO foo (auto,text) VALUES(NULL,'text');
INSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),'text');

See section 8.4.12.3 Comment obtenir l'identifiant unique du dernier enregistrement inséré ?.

Pour quelques applications utilisant ODBC (du moins Delphi et Access), la requête suivante peut être utilisée pour trouver une ligne insérée dernièrement :

SELECT * FROM nom_de_table WHERE auto IS NULL;

8.3.7 Rapporter des problèmes avec MyODBC

Si vous rencontrez des difficultés avec MyODBC, commencez par faire un fichier de log avec le gestionnaire ODBC (le fichier de log que vous obtenez en demande les logs de ODBCADMIN) et un log MyODBC.

Pour obtenir un fichier de log MyODBC, vous devez faire ceci :

1. Assurez vous que vous utilisez `myodbcd.dll' et non pas `myodbc.dll'. Le moyen le plus facile pour le faire est d'obtenir `myodbcd.dll' dans la distribution MyODBC et de le copier à la place de `myodbc.dll', qui est probablement dans le dossier `C:\windows\system32' ou `C:\winnt\system32'. Notez que vous voudrez probablement récupérer votre vieux fichier `myodbc.dll' lorsque vous aurez fini de tester, car il est bien plus rapide que `myodbcd.dll'.
2. Activez l'option `Trace MyODBC' dans l'écran de configuration de MyODBC. Le fichier de log sera écrit dans le fichier `C:\myodbc.log'. Si l'option de trace n'est pas recommandée lorsque vous retournez dans l'écran précédent, cela signifie que vous n'utilisez pas myodbcd.dll (voir ci-dessus).
3. Démarrez votre application, et faîtes la planter.

Vérifiez le fichier de trace MyODBC, pour essayer de comprendre ce qui ne va pas. Vous devriez être capable de trouver les requêtes émises en recherchant la chaîne >mysql_real_query dans le fichier `myodbc.log'.

Vous devriez aussi essayer de dupiquer la requête dans le client mysql ou admndemo pour voir si le problème vient de MyODBC ou MySQL.

Si vous trouvez quelques chose d'incorrect, n'envoyez que les lignes pertinentes (maximum, 40 lignes) à myodbc@lists.mysql.com. N'envoyez jamais le fichier de log MyODBC ou ODBC complet!

Si vous êtes incapables de trouver une erreur, la dernière option est de faire une archive (tar ou zip) qui contienne le fichier de trace MyODBC, le fichie de log ODBC, et un fichier README qui contienne une description du problème. Vous pouvez envoyer le tout à ftp://support.mysql.com/pub/mysql/secret/. Seuls nous, à MYSQL AB, pourront accéder à ces fichiers, et nous seront très diligents avec vos données.

Si vous pouvez créer un problème qui reproduit le problème, essayez de l'uploader aussi!

Si le programem fonctionne avec d'autres serveurs SQL, vous devriez faire un log ODBC où vous faîtes exactement la même chose sur les autres serveurs SQL.

N'oubliez jamais que plus vous nous fournissez d'explication, plus nous pourront vous aider!

8.4 MySQL C API

The C API code is distributed with MySQL. It is included in the mysqlclient library and allows C programs to access a database.

Many of the clients in the MySQL source distribution are written in C. If you are looking for examples that demonstrate how to use the C API, take a look at these clients. You can find these in the clients directory in the MySQL source distribution.

Most of the other client APIs (all except Java) use the mysqlclient library to communicate with the MySQL server. This means that, for example, you can take advantage of many of the same environment variables that are used by other client programs, because they are referenced from the library. See section 4.8 MySQL Scripts clients et utilitaires, for a list of these variables.

The client has a maximum communication buffer size. The size of the buffer that is allocated initially (16K bytes) is automatically increased up to the maximum size (the maximum is 16M). Because buffer sizes are increased only as demand warrants, simply increasing the default maximum limit does not in itself cause more resources to be used. This size check is mostly a check for erroneous queries and communication packets.

The communication buffer must be large enough to contain a single SQL statement (for client-to-server traffic) and one row of returned data (for server-to-client traffic). Each thread's communication buffer is dynamically enlarged to handle any query or row up to the maximum limit. For example, if you have BLOB values that contain up to 16M of data, you must have a communication buffer limit of at least 16M (in both server and client). The client's default maximum is 16M, but the default maximum in the server is 1M. You can increase this by changing the value of the max_allowed_packet parameter when the server is started. See section 5.5.2 Réglage des paramètres du serveur.

The MySQL server shrinks each communication buffer to net_buffer_length bytes after each query. For clients, the size of the buffer associated with a connection is not decreased until the connection is closed, at which time client memory is reclaimed.

For programming with threads, see section 8.4.14 Comment faire un client MySQL threadé. For creating a stand-alone application which includes the "server" and "client" in the same program (and does not communicate with an external MySQL server), see section 8.4.15 libmysqld, la librairie du serveur embarqué MySQL.

8.4.1 Types de données de l'API C

MYSQL

Cette structure représente un gestionnaire de connexion à la base de données. Elle est utilisée dans la plupart des fonctions MySQL.

MYSQL_RES

Cette structure représente le résultat d'une requête qui retourne des lignes (SELECT, SHOW, DESCRIBE, EXPLAIN). L'information retournée par une requête est appelée jeu de résultats dans le reste de cette section.

MYSQL_ROW

C'est une représentation sûre pour les types d'une ligne de données. Elle est actuellement implémentée en tant que tableau de chaîne à octets comptés. (Vous ne pouvez la traiter en tant que chaîne terminée par une valeur nulle si les valeurs du champ peuvent contenir des données binaires, car de telles valeurs peuvent contenir elles-même des octets nuls.) Les lignes sont obtenues en appelant mysql_fetch_row().

MYSQL_FIELD

Cette structure contient des informations à propos du champ, tel que son nom, son type, et sa taille. Ses membres sont décrit en plus de détails ici. Vous pouvez obtenir une structure MYSQL_FIELD pour chaque champ en appelant plusieurs fois mysql_fetch_field(). Les valeurs des champs ne font pas partie de la structure; elles sont contenues dans une structure MYSQL_ROW.

MYSQL_FIELD_OFFSET

C'est une représentation sûre des types pour les index dans une liste de champs MySQL. (Utilisés par mysql_field_seek().) Les index sont des numéros de champs, dans une ligne, commençant à zéro.

my_ulonglong

Le type utilisé pour le nombre de lignes et pour mysql_affected_rows(), mysql_num_rows(), et mysql_insert_id(). Ce type fournit une echelle allant de 0 à 1.84e19. Sur quelques systèmes, essayer d'écrire la valeur d'un type my_ulonglong ne fonctionnera pas. Pour écrire une telle valeur, convertissez là en unsigned long et utilisez un format d'impression %lu. Exemple :

printf ("Nombre de lignes : %lu\n", (unsigned long) mysql_num_rows(result));

La structure MYSQL_FIELD contient les membres listés ici :

char * name

Le nom du champ, une chaîne terminée par une valeur nulle.

char * table

Le nom de la table contenant ce champ, s'il n'est pas calculé. Pour les champs calculés, la valeur de table est une chaîne vide.

char * def

La valeur par défaut de ce champ, en tant que chaîne terminée par une valeur nulle. Ce n'est définit que si vous utilisez mysql_list_fields().

enum enum_field_types type

Le type du champ. La valeur de type peut être l'une des suivantes :

Valeur de type	Description du type
FIELD_TYPE_TINY	Champ TINYINT
FIELD_TYPE_SHORT	Champ SMALLINT
FIELD_TYPE_LONG	Champ INTEGER
FIELD_TYPE_INT24	Champ MEDIUMINT
FIELD_TYPE_LONGLONG	Champ BIGINT
FIELD_TYPE_DECIMAL	Champ DECIMAL ou NUMERIC
FIELD_TYPE_FLOAT	Champ FLOAT
FIELD_TYPE_DOUBLE	Champ DOUBLE ou REAL
FIELD_TYPE_TIMESTAMP	Champ TIMESTAMP
FIELD_TYPE_DATE	Champ DATE
FIELD_TYPE_TIME	Champ TIME
FIELD_TYPE_DATETIME	Champ DATETIME
FIELD_TYPE_YEAR	Champ YEAR
FIELD_TYPE_STRING	Champ chaîne de caractères (CHAR ou VARCHAR)
FIELD_TYPE_BLOB	Champ BLOB ou TEXT (utilisez max_length pour déterminer la taille maximale)
FIELD_TYPE_SET	Champ SET
FIELD_TYPE_ENUM	Champ ENUM
FIELD_TYPE_NULL	Champ de type NULL
FIELD_TYPE_CHAR	Désapprouvé, utilisez FIELD_TYPE_TINY à la place

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

if (IS_NUM(field->type))
    printf("Le champ est numérique\n");

unsigned int length

La taille du champ, comme spécifié dans la définition de la table.

unsigned int max_length

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

unsigned int flags

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

Valeur d'attribut	Description d'attribut
NOT_NULL_FLAG	Le champ ne peut être NULL
PRI_KEY_FLAG	Le champ fait parti d'une clef primaire
UNIQUE_KEY_FLAG	Le champ fait parti d'une clef unique
MULTIPLE_KEY_FLAG	Le champ fait parti d'une clef non-unique
UNSIGNED_FLAG	Le champ possède l'attribut UNSIGNED
ZEROFILL_FLAG	Le champ possède l'attribut ZEROFILL
BINARY_FLAG	Le champ possède l'attribut BINARY
AUTO_INCREMENT_FLAG	Le champ possède l'attribut AUTO_INCREMENT
ENUM_FLAG	Le champ est un ENUM (désapprouvé)
SET_FLAG	Le champ est un SET (désapprouvé)
BLOB_FLAG	Le champ est un BLOB ou TEXT (désapprouvé)
TIMESTAMP_FLAG	Le champ est un TIMESTAMP (désapprouvé)

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

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

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

Status de l'attribut	Description
IS_NOT_NULL(flags)	Vrai si le champ est défini en tant que NOT NULL
IS_PRI_KEY(flags)	Vrai si le champ est une clef primaire
IS_BLOB(flags)	Vrai si le champ est un BLOB ou TEXT (désapprouvé; tester plutôt field->type)

unsigned int decimals

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

8.4.2 Vue d'ensemble des fonctions de l'API C

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

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

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

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

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

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

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

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

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

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

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

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

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

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

8.4.3 Description des fonctions de l'API C

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

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

if (result)                   /* correct */
    ... erreur ...

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

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

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

8.4.3.1 mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

Description

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

Valeur de retour

Un entier supérieur à zéro indique le nombre de lignes affectées ou sélectionnées. Zéro indique qu'aucun enregistrement n'a été mis à jour pour une requête UPDATE, qu'aucune lignes n'a correspondu à la clause WHERE dans la requête ou que celle ci n'a pas encore été exécutée. -1 indique que la requête a renvoyé une erreur ou que, pour une requête SELECT, mysql_affected_rows() a été appelée avant mysql_store_result().

Erreurs

Aucune.

Exemple

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

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

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

8.4.3.2 mysql_change_user()

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

Description

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

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

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

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

Valeur de retour

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

Erreurs

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

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

ER_UNKNOWN_COM_ERROR

Le serveur MySQL n'implémente pas cette commande (probablement un ancien serveur)

ER_ACCESS_DENIED_ERROR

L'utilisateur ou le mot de passe étaient erronés.

ER_BAD_DB_ERROR

La base de données n'existe pas.

ER_DBACCESS_DENIED_ERROR

L'utilisateur n'a pas le droit d'accéder à la base de données.

ER_WRONG_DB_NAME

Le nom de la base de données était trop long.

Exemple

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

8.4.3.3 mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

Description

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

Valeur de retour

Le jeu de caractères par défaut

Erreurs

Aucune.

8.4.3.4 mysql_close()

void mysql_close(MYSQL *mysql)

Description

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

Valeur de retour

Aucune.

Erreurs

Aucune.

8.4.3.5 mysql_connect()

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

Description

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

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

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

Valeur de retour

La même que pour mysql_real_connect().

Erreurs

Les mêmes que pour mysql_real_connect().

8.4.3.6 mysql_create_db()

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

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

Exemple

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

8.4.3.7 mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

Description

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

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

Valeur de retour

Aucune.

Erreurs

Aucune.

8.4.3.8 mysql_debug()

void mysql_debug(const char *debug)

Description

Provoque un DBUG_PUSH avec la chaîne donnée. mysql_debug() utilises la librairie de débogage Fred Fish. Pour utiliser cette fonction vous devez compiler la librairie client avec le support débogage. See section D.1 Déboguer un serveur MySQL. See section D.2 Débogage un client MySQL.

Valeur de retour

Aucune.

Erreurs

Aucune.

Exemple

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

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

8.4.3.9 mysql_drop_db()

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

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

Exemple

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

8.4.3.10 mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.11 mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

Description

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

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

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

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

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

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

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

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

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

8.4.3.12 mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.13 mysql_error()

char *mysql_error(MYSQL *mysql)

Description

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

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

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

La langue des messages d'erreurs peut être changée en recompilant la librairie du client MySQL. Actuellement, vous pouvez choisir les messages d'erreur parmi un choix de plusieurs langues. See section 4.6.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.

8.4.3.14 mysql_escape_string()

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

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

8.4.3.15 mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Description

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

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

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

MYSQL_FIELD *field;

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

8.4.3.16 mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

Description

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;

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

8.4.3.17 mysql_fetch_field_direct()

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

Description

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

Valeur de retour

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

Erreurs

Aucune.

Exemple

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;

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

8.4.3.18 mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

Description

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

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

Valeur de retour

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

Erreurs

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

Exemple

MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;

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

8.4.3.19 mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

Description

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

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

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

Valeur de retour

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

Erreurs

CR_SERVER_LOST

La connexion au serveur a été perdue durant la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue est survenue.

Exemple

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

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

8.4.3.20 mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

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

Description

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

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

See section 8.4.12.1 Pourquoi est ce qu'après mysql_query() ait indiqué un résultat positif, mysql_store_result() retourne parfois NULL?.

Valeur de retour

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

Erreurs

Aucune.

Exemple

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

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

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

8.4.3.21 mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Description

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

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.22 mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

Description

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

Valeur de retour

L'indice courant du curseur de champ.

Erreurs

Aucune.

8.4.3.23 mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

Description

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

Valeur de retour

Aucune.

Erreurs

Aucune.

8.4.3.24 mysql_get_client_info()

char *mysql_get_client_info(void)

Description

Retourne une chaîne représentant la version de la librairie du client.

Valeur de retour

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

Erreurs

Aucune.

8.4.3.25 mysql_get_server_version()

unsigned long mysql_get_server_version(MYSQL *mysql)

Description

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

Valeurs retournées

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

main_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 connaitre ainsi ses fonctionnalités.

Erreurs

Aucune.

8.4.3.26 mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.27 mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.28 mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.29 mysql_info()

char *mysql_info(MYSQL *mysql)

Description

Récupère une chaîne de caractères fournissant des informations à propos de la requête exécutée le plus récemment, mais seulement pour celles listées ici. Pour les autres requêtes, mysql_info() retournera NULL. Le format de la chaîne varie selon le type de requête, comme décrit ici. Les nombres présentés sont des exemples; la chaîne retournée contiendra les informations correspondantes à vos requêtes.

INSERT INTO ... SELECT ...

String format: Records: 100 Duplicates: 0 Warnings: 0

INSERT INTO ... VALUES (...),(...),(...)...

String format: Records: 3 Duplicates: 0 Warnings: 0

LOAD DATA INFILE ...

String format: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0

ALTER TABLE

String format: Records: 3 Duplicates: 0 Warnings: 0

UPDATE

String format: 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.

8.4.3.30 mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

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

8.4.3.31 mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

Description

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

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 definissent la valeur d'une colonne à LAST_INSERT_ID(expr). See section 6.3.6.2 Fonctions diverses.

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.32 mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

Description

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.33 mysql_list_dbs()

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

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.34 mysql_list_fields()

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

Description

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

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.35 mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.36 mysql_list_tables()

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

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.37 mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

ou

unsigned int mysql_num_fields(MYSQL *mysql)

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

Description

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

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

See section 8.4.12.1 Pourquoi est ce qu'après mysql_query() ait indiqué un résultat positif, mysql_store_result() retourne parfois NULL?.

Valeur de retour

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

Erreurs

Aucune.

Exemple

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

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

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

8.4.3.38 mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

Description

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

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

Valeur de retour

Le nombre de lignes dans le résultat.

Erreurs

Aucune.

8.4.3.39 mysql_options()

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

Description

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

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

L'argument option est l'option que vous voulez configurer; l'arguement 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 moement.

Pour plus d'informations sur les fichiers d'options, reportez vous à section 4.1.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'.

8.4.3.40 mysql_ping()

int mysql_ping(MYSQL *mysql)

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.41 mysql_query()

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

Description

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

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

Si vous voulez savoir si la requête doit retourner un jeu de résultat ou non, vous pouvez utiliser mysql_field_count() pour vérifier. See section 8.4.3.20 mysql_field_count().

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.42 mysql_real_connect()

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

Description

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

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

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

  Nom de l'option	Description
  CLIENT_COMPRESS	Utilise le protocole compressé.
  CLIENT_FOUND_ROWS	Retourne le nombre de lignes trouvées, et non de lignes affectées.
  CLIENT_IGNORE_SPACE	Autorise les espaces après les noms de fonctions. Rend tous les noms de fonctions des mots réservés.
  CLIENT_INTERACTIVE	Autorise interactive_timeout secondes (au lieu de wait_timeout secondes) d'innactivité avant de fermer la connexion.
  CLIENT_NO_SCHEMA	N'autorise pas la syntaxe db_name.tbl_name.col_name. Cela est fait pour ODBC. Il fait génèrer une erreur à l'analyseur si vous utilisez cette syntaxe, ce qui peut se réveler fort utile pour la chasse aux bogues dans les programmes ODBC.
  CLIENT_ODBC	Le client est un client ODBC. Cela rend mysqld plus accueillant vis à vis de ODBC.
  CLIENT_SSL	Utilise SSL (protocole encrypté).

Valeur de retour

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

Erreurs

CR_CONN_HOST_ERROR

Impossible de se connecter au serveur MySQL.

CR_CONNECTION_ERROR

Impossible de se connecter au serveur MySQL local.

CR_IPSOCK_ERROR

Impossible de créer une socket IP.

CR_OUT_OF_MEMORY

Plus de mémoire.

CR_SOCKET_CREATE_ERROR

Impossible de créer une socket UNIX.

CR_UNKNOWN_HOST

Impossible de trouver l'adresse IP de l'hôte.

CR_VERSION_ERROR

Une disparité de protocole a résulté de la tentative de connexion à un serveur avec une librairie de client qui utilise une version différente du protocole. Cela peut arriver si vous utilisez une très vieille librairie cliente pour vous connecter à un serveur qui n'a pas été démarré avec l'option --old-protocol.

CR_NAMEDPIPEOPEN_ERROR

Impossible de créer un tunnel nommé sur Windows.

CR_NAMEDPIPEWAIT_ERROR

Impossible d'attendre un tunnel nommé sur Windows.

CR_NAMEDPIPESETSTATE_ERROR

Impossible d'obtenir un gestionnaire de tunnel sur Windows.

CR_SERVER_LOST

Si connect_timeout > 0 et qu'il a fallu plus de connect_timeout secondes pour se connecter au serveur, ou que celui-ci n'a plus répondu durant l'exécution de init-command.

Exemple

MYSQL mysql;

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

En utilisant mysql_options() la librairie 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.

8.4.3.43 mysql_real_escape_string()

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

Description

Cette fonction est utilisée pour créer une requête SQL légale que vous pouvez utiliser dans une commande SQL. See section 6.1.1.1 Chaînes.

La string dans de est encodée en chaîne échappé SQL, prenom en compte le jeu de caractères de la connexion. Le résultat est placé dans en et un octet nul de terminaison est ajouté à la fin de celui-ci. Les caractères encodés sont NUL (ASCII 0), `\n', `\r', `\', `'', `"', et Ctrl-Z (see section 6.1.1 Literals: Comment écrire les chaînes et les nombres). (En fait, MySQL a seulement besoin que l'anti-slash et le guillemet utilisé pour entourer la chaîne soient échappés. Cette fonction échappe les autre caractères pour les rendre plus facile à lire dans les fichiers de log.)

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

Exemple

char query[1000],*end;

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

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

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.44 mysql_real_query()

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

Description

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

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

Si vous voulez savoir si la requête est censée retourner un jeu de résultat ou non, vous pouvez utiliser mysql_field_count() pour vérifier cela. See section 8.4.3.20 mysql_field_count().

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.45 mysql_reload()

int mysql_reload(MYSQL *mysql)

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.46 mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

Description

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

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

Valeur de retour

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

Erreurs

Aucune.

8.4.3.47 mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

Description

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

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

Valeur de retour

La position courante du pointeur de ligne.

Erreurs

Aucune.

8.4.3.48 mysql_select_db()

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

Description

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.49 mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.50 mysql_stat()

char *mysql_stat(MYSQL *mysql)

Description

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.51 mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

Description

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

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

Si vous voulez savoir si la requête devrait renvoyer un jeu de résultats ou non, vous pouvez utiliser mysql_field_count() pour vérifier. See section 8.4.3.20 mysql_field_count().

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

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

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

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

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

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

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

See section 8.4.12.1 Pourquoi est ce qu'après mysql_query() ait indiqué un résultat positif, mysql_store_result() retourne parfois NULL?.

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_OUT_OF_MEMORY

Plus de mémoire.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.52 mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

Description

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

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

Valeur de retour

L'identifiant du thread de la connexion courante.

Erreurs

Aucune.

8.4.3.53 mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

Description

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

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

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

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

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

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

Valeur de retour

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

Erreurs

CR_COMMANDS_OUT_OF_SYNC

Les commandes n'ont pas été exécutées dans le bon ordre.

CR_OUT_OF_MEMORY

Plus de mémoire.

CR_SERVER_GONE_ERROR

Le serveur MySQL ne réponds pas.

CR_SERVER_LOST

La connexion au serveur a été perdue au cours la requête.

CR_UNKNOWN_ERROR

Une erreur inconnue s'est produite.

8.4.3.54 mysql_commit()

my_bool mysql_commit(MYSQL *mysql)

Description

Valide la transaction courante. Disponible depuis MySQL 4.1

Valeurs retournées

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

Erreurs

Aucune

8.4.3.55 mysql_rollback()

my_bool mysql_rollback(MYSQL *mysql)

Description

Annule la transaction courante. Disponible avec MySQL 4.1

Valeurs retournées

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

Erreurs

Aucune.

8.4.3.56 mysql_autocommit()

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

Description

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

Valeurs retournées

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

Erreurs

Aucune.

8.4.3.57 mysql_more_results()

my_bool mysql_more_results(MYSQL *mysql)

Description

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

Valeurs retournées

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

Erreurs

Aucune.

8.4.3.58 mysql_next_result()

int mysql_next_result(MYSQL *mysql)

Description

Si 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

Valeurs retournées

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

Erreurs

Aucune.

8.4.4 Fonctions C de commandes préparées

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

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

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

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

8.4.5 C API Prepared Statements DataTypes

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

MYSQL_STMT

Cette structure représente un pointeur de comande sur une commande préparée. Elle sert pour toutes les fonctions liées aux commandes. La commande est initialisée lorsque la requête est préparée en utilisant mysql_prepare(). Une connexion peut avoir de multiples pointeurs de commandes, et la limite ne dépend que des ressources systèmes.

MYSQL_BIND

Cette structure est utilisée pour lier les paramètres avec des buffers, avec mysql_bind_param(), pour utilisation avec mysql_execute(), ainsi que pour lier les résultats avec des buffers via mysql_bind_result()m, lors de la lecture de données avec mysql_fetch(). La structure MYSQL_BIND contient les membres suivants :

enum enum_field_types buffer_type [input]

Le type de buffer. La valeur type doit être l'une des suivantes :

• MYSQL_TYPE_TINY
• MYSQL_TYPE_SHORT
• MYSQL_TYPE_LONG
• MYSQL_TYPE_LONGLONG
• MYSQL_TYPE_FLOAT
• MYSQL_TYPE_DOUBLE
• MYSQL_TYPE_TIME
• MYSQL_TYPE_DATE
• MYSQL_TYPE_DATETIME
• MYSQL_TYPE_TIMESTAMP
• MYSQL_TYPE_STRING
• MYSQL_TYPE_VAR_STRING
• MYSQL_TYPE_TINY_BLOB
• MYSQL_TYPE_MEDIUM_BLOB
• MYSQL_TYPE_LONG_BLOB
• MYSQL_TYPE_BLOB

void *buffer [input/output]

Un pointeur sur un buffer pour les données du paramètre, si il sert à fournir des données, ou un pointeur de buffer de retour, pour les données qui seront lues dans le résultat.

unsigned long buffer_length [input]

La taille de *buffer en octets. Pour les caractères et les données binaires C, buffer_length spécifie la taille de *buffer à utiliser comme paramètre si il est utilisé avec mysql_bind_param(), ou la taille lue dans le résultat si il est utilisé avec mysql_bind_result().

long *length [input/output]

Un pointeur sur le buffer pour le paramètre de taille. Lorsqu la structure est utilisée en entrée, cet argument pointe sur un buffer qui, lorsque mysql_execute() est appelé, contient la taille de la valeur stockée dans *buffer. Ceci est ignoré, sauf pour les données de type caractère, ou binaire C. Si la taill est un pointeur null, alors le protocole suppose que les données caractères ou binaires sont terminées par un null. Lorsque cette structure est utilisée dans des liaisons de lecture, alors mysql_fetch() retourne la taille des données retournées.

bool *is_null [input/output]

Indique si le paramètre data est NULL, ou si les données lues sont NULL.

MYSQL_TIME

Cette structure est utilisée pour écrire et lire des données de type DATE, TIME et TIMESTAMP, directement avec le serveur. La structure MYSQL_TIME contient les membres listées ci-dessous :

Member	Type	Description
year	unsigned int	Année.
month	unsigned int	Mois de l'année.
day	unsigned int	Jour du mois.
hour	unsigned int	Heure du jour(TIME).
minute	unsigned int	Minute de l'heure.
second	unsigned int	Seconde de la minute.
neg	my_bool	Un booléen qui indique si le temps est négatif.
second_part	unsigned long	Fraction de la second (utilisé ultérieurement)

8.4.6 Présentation des API C pour les commandes préparées.

Voici les fonctions disponibles pour les commandes préparées. Elles sont listées ici et détailles plus loin. See section 8.4.7 Descriptions des fonctions C pour les requêtes préparées.

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

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

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

Vous pouvez aussi envoyer le texte ou les données binaires par parties, au serveur, avec mysql_send_long_data(), en spécifiant l'optoin is_long_data=1 ou length=MYSQL_LONG_DATA ou -2 dans la structure MYSQL_BIND fournie avec mysql_bind_param().

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

Etapes d'exécution :

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

• appelle mysql_prepare() et passe une chaîne contenant la commande SQL. Si la préparation réussi, mysql_prepare() retourne un pointeur de commande valide.
• Si la requête a un résultat, alors mysql_prepare_result retourne les méta informations de résultat.
• spécifie les valeurs de tous les paramètres de mysql_bind_param. Tous les paramètres doivent être fournis, sinon, cela générera une erreur, ou engendrera des résultats inattendus.
• appelle mysql_execute() pour exécuter la requête.
• Répète les étapes 2 et 3 autant que nécessaire, en modifiant les valeurs des paramètres, et en ré-exécutant la commande.
• Lie les buffers de données aux lignes de résultat, si la commande génère un résultat, en utilisant mysql_bind_result().
• Lit les données dnas les buffers, ligne par ligne, en appelant mysql_fetch() jusqu'à ce qu'il n'y ait plus de lignes.
• Lorsque mysql_prepare() est appelé, dans le protocole client/serveur MySQL :
  • Le serveur analyse la requête et envoie le statut OK au client en lui assignant un identifiant de commande. Il renvoie aussi le nombre total de paramètres, le nombre de colonnes et des métas informations si un résultat est attendu. La syntaxe et la sémantique de la requête sont vérifiés durant cet appel.
  • Le client utilise cet identifiant de commande pour les exécutions ultérieures, pour que le serveur identifie la commande dans le pool de commandes. Désormais, le client alloue un pointeur de commande avec cet identifiant, et le retourne à l'application.
• Lorsque mysql_execute() est appelé, avec le protocole client/serveur MySQL :
  • Le client utilise le pointeur de comande et envoie les paramètres au serveur.
  • Le serveur identifie la commane en utilisant l'identifiant, et remplace les marqueurs de paramètres par leur valeur, puis il exécute la requête. Si cela conduit à un résultat, il est retourné au client, ou bien un statut OK, indiquant le nombre total de ligne affecté est retourné.
• Lorsque mysql_fetch() est appelé, dans le protocole client/serveur MySQL :
  • Le client lit les données dans le paquet, ligne par ligne, et les place dans les buffers de données, avec les conversions nécessaires. Si le type de buffer de l'application est le même que le type de champs, alors les conversions sont immédiates.

Vous pouvez lire les codes et messages d'erreurs avec les fonctions mysql_stmt_errno() et mysql_stmt_error(), respectivement.

8.4.7 Descriptions des fonctions C pour les requêtes préparées

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

8.4.7.1 mysql_prepare()

MYSQL_STMT * mysql_prepare(MYSQL *mysql, const char *query, unsigned long length)

Description

Prépare la requête SQL représentée par la chaîne terminée par le caractère null 'query'. La requête doit être une commande seule. Vous ne devez pas ajouter le point-virgule final (`;`) ou le caractère \g.

L'application peut inclure un ou plusieurs marqueur de paramètre dans la commande SQL. Pour inclure un marqueur de paramètre, l'application doit intégrer un point d'interrogation (?) dans la requête SQL, à la position appropriée.

Les marqueur ne sont valides que dans certaines parties de la requête SQL. Par exemple, ils ne sont pas autorisés dans la liste des colonnes d'une sélection, ni comme opérande d'un opérateur binaire tel que le signe égal (=), cas cela rendrait impossible la détermination du type de marqueur. En général, les marqueurs ne sont valides que dans les manipulations de données (Data Manipulation Languange, DML), et non pas dans les requêtes de définition des données (Data Defination Language, DDL).

Les marqueurs de paramtères sont ensuite remplis par les variables d'application, en utilisant mysql_bind_param().

Valeurs retournées

MYSQL_STMT si la préparation a été réussie. NULL si une erreur est survenue.

Erreurs

CR_COMMANDS_OUT_OF_SYNC

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

CR_OUT_OF_MEMORY

Out of memory : Plus de mémoire

CR_SERVER_GONE_ERROR

The MySQL server has gone away : le server MySQL n'est plus accessible.

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

An unkown error occured : Erreur inconnue

Si la préparation a échoué, i.e. si mysql_prepare() a retourné la valeur NULL, les erreurs sont disponibles grâce à la fonction mysql_error().

Exemple

Pour une illustration de l'utilisation de mysql_prepare(), voyez l'exemple de la fonction section 8.4.7.5 mysql_execute().

8.4.7.2 mysql_param_count()

unsigned int mysql_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

None

Exemple

Pour une illustration de la fonction mysql_param_count(), voyez l'exemple de la fonction section 8.4.7.5 mysql_execute().

8.4.7.3 mysql_prepare_result()

MYSQL_RES *mysql_prepare_result(MYSQL_STMT *stmt)

Description

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

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

Valeurs retournées

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

Erreurs

CR_OUT_OF_MEMORY

Out of memory : plus de mémoire

CR_UNKNOWN_ERROR

An unknown error occured : Une erreur inconnue est survenue.

Exemple

Pour une illustration de la fonction mysql_prepare_result(), voyez l'exemple de la fonction section 8.4.7.9 mysql_fetch().

8.4.7.4 mysql_bind_param()

int mysql_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Description

mysql_bind_param sert à lier des données avec les marqueurs de paramètres dans une requête SQL préparée avec mysql_prepare. Il utilise la strucutre MYSQL_BIND pour fournir les données : Les types de buffers supportés sont :

• MYSQL_TYPE_TINY
• MYSQL_TYPE_SHORT
• MYSQL_TYPE_LONG
• MYSQL_TYPE_LONGLONG
• MYSQL_TYPE_FLOAT
• MYSQL_TYPE_DOUBLE
• MYSQL_TYPE_TIME
• MYSQL_TYPE_DATE
• MYSQL_TYPE_DATETIME
• MYSQL_TYPE_TIMESTAMP
• MYSQL_TYPE_STRING
• MYSQL_TYPE_VAR_STRING
• MYSQL_TYPE_TINY_BLOB
• MYSQL_TYPE_MEDIUM_BLOB
• MYSQL_TYPE_LONG_BLOB

Valeurs retournées

Zéro si la liaison a été réussie. Non null si une erreur est survenue.

Erreurs

CR_NO_PREPARE_STMT

No prepared statement exists : Aucune requête préparée n'existe.

CR_NO_PARAMETERS_EXISTS

No parameters exists to bind : Aucun paramètre à lier n'existe.

CR_INVALID_BUFFER_USE

Indicates if the bind is to supply the long data in chunks and if the buffer type is non string or binary : Indique si la liason attend les données par morceaux, t si le type de buffer n'est pas chaîne ou binaire.

CR_UNSUPPORTED_PARAM_TYPE

The conversion is not supported, possibly the buffer_type is illegal or its not from the above list of supported types. La conversion n'est pas supportée, il est possible que le type de buffer soit illégal, ou qu'il ne fasse pas partie de la liste des options possibles.

CR_OUT_OF_MEMOR

Out of memory : Plus de mémoire.

CR_UNKNOWN_ERROR

An unknown error occured : une erreur inconnue est survenue.

Example

Pour une illustration de la fonction mysql_bind_param(), voyez l'exemple de la fonction section 8.4.7.5 mysql_execute().

8.4.7.5 mysql_execute()

int mysql_execute(MYSQL_STMT *stmt.

Description

mysql_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 une un résultat, alors vous devez appeler la fonction mysql_fetch() pour lire les données avant d'appeler tout autre fonction de traitement du résultat. Pour plus d'informations sur ocmment lire les données binaires, voyez section 8.4.7.9 mysql_fetch().

Valeurs retournées

mysql_execute() retourne les valeurs suivantes :

Erreurs

CR_NO_PREPARE_QUERY

No query prepared prior to execution : Aucune requête n'a été préparée.

CR_ALL_PARAMS_NOT_BOUND

Not all parameters data is supplied : Toutes les valeurs des paramtères n'ont pas été fournies.

CR_COMMANDS_OUT_OF_SYNC

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

CR_OUT_OF_MEMORY

Out of memory : plus de mémoire.

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

An unknown error occurred : une erreur inconnue est survenue.

Exemple

L'exemple suivant explique l'utilisation de mysql_prepare, mysql_param_count, mysql_bind_param, mysql_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 drop table failed");
    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 create table failed");
    fprintf(stderr, "\n %s", mysql_error(mysql));
    exit(0);
  }
  
  /* Prepare une requête d'insertion de trois paramètres */
  strmov(query, "INSERT INTO test_table(col1,col2,col3) values(?,?,?)");
  if(!(stmt = mysql_prepare(mysql, query, strlen(query))))
  {
    fprintf(stderr, "\n prepare, insert failed");
    fprintf(stderr, "\n %s", mysql_error(mysql));
    exit(0);
  }
  fprintf(stdout, "\n prepare, insert successful");

  /* 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) /* validate parameter count */
  {
    fprintf(stderr, "\n invalid parameter count returned by MySQL");
    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_execute(stmt))
  {
    fprintf(stderr, "\n execute 1 failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    fprintf(stderr, "\n send a bug report to bugs@lists.mysql.com, by asking why this is not working ?");
    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) /* validate affected rows */
  {
    fprintf(stderr, "\n invalid affected rows by MySQL");
    exit(0);
  }

  /* Ré-exécute l'insertion, en modifiant les valeurs */
  int_data= 1000;             
  strcpy(str_data,"The most popular open source database"); 
  small_data= 1000;         /* smallint */
  is_null= 0;               /* reset NULL */
 
  /* Exécute l'insertion : 2eme */
  if (mysql_execute(stmt))
  {
    fprintf(stderr, "\n execute 2 failed");
    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 total affected rows: %lld", affected_rows);
  if (affected_rows != 1) /* validate affected rows */
  {
    fprintf(stderr, "\n invalid affected rows by MySQL");
    exit(0);
  }

  /* Ferme la requête */
  if (mysql_stmt_close(stmt))
  {
    fprintf(stderr, "\n failed while closing the statement");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }
  
  /* Efface la table */
  if (mysql_query(mysql,"DROP TABLE test_table"))
  {
    fprintf(stderr, "\n drop table failed");
    fprintf(stderr, "\n %s", mysql_error(mysql));
    exit(0);
  }
  fprintf(stdout, "Success, MySQL prepared statements are working!!!");

8.4.7.6 mysql_stmt_affected_rows()

ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

Description

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

Valeurs retournées

Un entier supérieur à zéro indique le nombre de ligne affectées ou lues. Zéro indique qu'aucune ligne n'a été modifiées durant une commande UPDATE, ou qu'aucune ligne n'a vérifié la clause WHERE dans la requête, ou qu'aucune requête n'a été exécuté. -1 indique que la requête a retourné une erreur, ou que, pour une requête SELECT, mysql_stmt_affected_rows() a été appelé avant mysql_fetch().

Erreurs

None.

Exemple

Plus une illustration de mysql_stmt_affected_rows() voyez l'exemple de section 8.4.7.5 mysql_execute().

8.4.7.7 mysql_bind_result()

my_bool mysql_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Description

mysql_bind_result() sert à associer, (dit aussi lier) des colonnes disponibles dans un résultat avec des buffers de données. Lorsque mysql_fetch() est appelé pour lire les données, le protocole client MySQL retourne les données des colonnes liées, dans les buffers spécifiés.

Notez que toutes les colonnes doivent être liées avant d'appleler la fonction mysql_fetch(), dans le cas de liaisons avec des buffers, sinon, mysql_fetch() ignorera simplement les données. De plus, les buffers doient être suffisamment grands pour contenir les données, car le protocole ne retourne pas les données par parties.

Une colonne peut être liée ou reliée à tout moment, même après avoir lue des donées dans le résultat. La nouvelle liaison prendra effet au prochain appel de mysql_fetch(). Par exemple, suposons que l'application lie les colonnes d'un résultat, et appelle mysql_fetch(). Le protocole retourne alors les données dans les buffers. Supposons maintenant que l'application lie les colonnes vers d'autres buffers. Le protocole ne placera pas les données dans les nouveaux buffers, mais il le fera lors du prochain appel de mysql_fetch().

Pour lier une colonne, une application doit appeler la fonction mysql_bind_result(), et indiquer le type, l'adresse et l'adresse de la taille du buffer. Les types de buffers supportés sont :

• MYSQL_TYPE_TINY
• MYSQL_TYPE_SHORT
• MYSQL_TYPE_LONG
• MYSQL_TYPE_LONGLONG
• MYSQL_TYPE_FLOAT
• MYSQL_TYPE_DOUBLE
• MYSQL_TYPE_TIME
• MYSQL_TYPE_DATE
• MYSQL_TYPE_DATETIME
• MYSQL_TYPE_TIMESTAMP
• MYSQL_TYPE_STRING
• MYSQL_TYPE_VAR_STRING
• MYSQL_TYPE_BLOB
• MYSQL_TYPE_TINY_BLOB
• MYSQL_TYPE_MEDIUM_BLOB
• MYSQL_TYPE_LONG_BLOB

Valeurs retournées

Zéro si la liaison a réussi, et non-nul si une erreur est survenue.

Errors

CR_NO_PREPARE_STMT

No prepared statement exists : Aucune requête préparé n'existe.

CR_UNSUPPORTED_PARAM_TYPE

The conversion is not supported, possibly the buffer_type is illegal or its not from the list of supported types : la conversion n'est pas supportée, possiblement parce que le type de buffer est invalide ou qu'il ne fait pas partie de la liste des types autorisés.

CR_OUT_OF_MEMOR

Out of memory : plus de mémoire.

CR_UNKNOWN_ERROR

An unknown error occured : une erreur inconnue est survenue.

Exemple

Pour une illustration de mysql_bind_result(), voyez l'exemple de la fonction section 8.4.7.9 mysql_fetch()

8.4.7.8 mysql_stmt_store_result()

int mysql_stmt_store_result(MYSQL_STMT *stmt)

Description

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

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

Valeurs retournées

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

Errors

CR_COMMANDS_OUT_OF_SYNC

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

CR_OUT_OF_MEMORY

Out of memory : plus de mémoire.

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

An unknown error occurred : une erreur inconnue est survenue.

8.4.7.9 mysql_fetch()

int mysql_fetch(MYSQL_STMT *stmt)

Description

mysql_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_execute() qui crée le résultat, ou après mysql_stmt_store_result(), qui est appelé après mysql_execute() pour mettre en buffer tout le résultat.

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

Notez que toutes les colonnes doivent être liées par l'application.

Si les données lues contiennent la valeur NULL, alors la valeur is_null de MYSQL_BIND contiendra TRUE, 1, ou sinon, les données et leur longueur seront reoturnées dans les variables *buffer et *length, basées sur le type de buffer, spécifié par l'application. Tous les nombres ont une taille fixe, listée en octet ci-dessous :

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

Valeurs retournées

Erreurs

CR_COMMANDS_OUT_OF_SYNC

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

CR_OUT_OF_MEMORY

Out of memory : plus de mémoire.

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

An unknown error occurred : Une erreur inconnue est survenue.

CR_UNSUPPORTED_PARAM_TYPE

If the buffer type is MYSQL_TYPE_DATE,DATETIME,TIME,or TIMESTAMP; and if the field type is not DATE, TIME, DATETIME or TIMESTAMP. Le buffer est de type MYSQL_TYPE_DATE,DATETIME,TIME ou TIMESTAMP et le type de champs n'est pas DATE, TIME, DATETIME or TIMESTAMP.

All other unsupported conversion errors are returned from mysql_bind_result(). 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_prepare_result, mysql_bind_result() et mysql_fetch()

  
MYSQL_STMT *stmt;  
MYSQL_BIND bind[2];
MYSQL_RES  *result;
int        int_data;
long       int_length, str_length;
char       str_data[50];
my_bool    is_null[2];

  query= "SELECT col1, col2 FROM test_table WHERE col1= 10)");
  if (!(stmt= mysql_prepare(&mysql, query, strlen(query)))
  {
    fprintf(stderr, "\n prepare failed");
    fprintf(stderr, "\n %s", mysql_error(&stmt));
    exit(0);
  }

  /* Lit les méta informations sur les champs */
  if (!(result= mysql_prepare_result(stmt)))
  {
    fprintf(stderr, "\n prepare_result failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }

  fprintf(stdout, "Total fields: %ld", mysql_num_fields(result));

  if (mysql_num_fields(result) != 2)
  {
    fprintf(stderr, "\n prepare returned invalid field count");
    exit(0);
  }

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

  /* Lie les résultats dans les buffers */
  bind[0].buffer_type= MYSQL_TYPE_LONG;
  bind[0].buffer= (char *)&int_data;
  bind[0].is_null= &is_null[0];
  bind[0].length= &int_length;

  bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
  bind[1].buffer= (void *)str_data;
  bind[1].is_null= &is_null[1];
  bind[1].length= &str_length;

  if (mysql_bind_result(stmt, bind))
  {
    fprintf(stderr, "\n bind_result failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }  

  /* Lit les données dans les buffers */
  if (mysql_fetch(stmt))
  {
    fprintf(stderr, "\n fetch failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }  
  
  if (is_null[0])
    fprintf(stdout, "\n Col1 data is NULL");
  else
    fprintf(stdout, "\n Col1: %d, length: %ld", int_data, int_length);
   
   if (is_null[1])
     fprintf(stdout, "\n Col2 data is NULL");
   else
    fprintf(stdout, "\n Col2: %s, length: %ld", str_data, str_length);

   
  /* Nouvel appel de mysql_fetch() */
  if (mysql_fetch(stmt) |= MYSQL_NO_DATA)
  {
    fprintf(stderr, "\n fetch return more than one row);
    exit(0);
  }  

  /* Libère la mémoire des données du résultat */
  mysql_free_result(result);

  /* Libère la mémoire de la commande */
  if (mysql_stmt_free(stmt))
  {
    fprintf(stderr, "\n failed to free the statement handle);
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }  
 

8.4.7.10 mysql_send_long_data()

int mysql_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, ulong length)

Description

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

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

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_INVALID_PARAMETER_NO

Invalid parameter number : nombre de paramètres invalide.

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_OUT_OF_MEMOR

Out of memory : plus de mémoire.

CR_UNKNOWN_ERROR

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

Exemple

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

  
MYSQL_BIND bind[1];
long       length;

  query= "INSERT INTO test_long_data(text_column) VALUES(?)");
  if (!mysql_prepare(&mysql, query, strlen(query))
  {
    fprintf(stderr, "\n prepare failed");
    fprintf(stderr, "\n %s", mysql_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_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_send_long_data(stmt,1,"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_send_long_data(stmt,1," - 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_execute(stmt))
  {
    fprintf(stderr, "\n mysql_execute failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }

   Cet exemple va insérer la phrase, "MySQL - The most popular open source database" 
   dans la colonne de type 'text_column'.  

8.4.7.11 mysql_stmt_close()

my_bool mysql_stmt_close(MYSQL_STMT *)

Description

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

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

Valeur retournée

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

Erreurs

CR_SERVER_GONE_ERROR

The MySQL server has gone away

CR_UNKNOWN_ERROR

An unkown error occured

Exemple

Pour une illustration de la fonction mysql_stmt_close() voyez un exemple avec section 8.4.7.5 mysql_execute().

8.4.7.12 mysql_stmt_errno()

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

Description

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

Valeurs retournées

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

Erreurs

Aucune

8.4.7.13 mysql_stmt_error()

char *mysql_stmt_error(MYSQL_STMT *stmt)

Description

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

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

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

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

Valeurs retournées

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

Erreurs

Aucune

8.4.8 C API pour gérer les requêtes multiples

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

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

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

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

8.4.9 C API de gestions des DATE, TIME et TIMESTAMP

En utilisant le nouveau protocole binaire de MySQL 4.1 et plus récent, vous pouvez envoyer et recevoir les données de type DATE, TIME et TIMESTAMP avec la structure MYSQL_TIME.

La structure MYSQL_TIME est constituée des membres suivants :

• year
• month
• day
• hour
• minute
• second
• second_part

Afin d'envoyer les données, il faut utiliser une requête préparée avec les fonctions mysql_prepare() et mysql_execute(), et vous devez lier le paramètre en utilisant le type MYSQL_TYPE_DATE afin de traiter la valeur de date, MYSQL_TYPE_TIME pour les heures, et MYSQL_TYPE_DATETIME ou MYSQL_TYPE_TIMESTAMP pour les dates complètes (datetime) ou les timestamp en utilisant mysql_bind_param() lors de l'envoi, ou mysql_bind_results() lors de la reception.

Voici un exemple simple qui insert des données de type DATE, TIME and TIMESTAMP.

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

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

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

  mysql_bind_param(stmt, bind);

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

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

  mysql_execute(stmt);
  .. 

8.4.10 Description des fonctions threadées de C

Vous devez utiliser les fonctions suivantes quand vous voulez créer un client threadé. See section 8.4.14 Comment faire un client MySQL threadé.

8.4.10.1 my_init()

void my_init(void)

Description

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

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

Valeur de retour

Aucune.

8.4.10.2 mysql_thread_init()

my_bool mysql_thread_init(void)

Description

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

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

Valeur de retour

Aucune.

8.4.10.3 mysql_thread_end()

void mysql_thread_end(void)

Description

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

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

Valeur de retour

Aucune.

8.4.10.4 mysql_thread_safe()

unsigned int mysql_thread_safe(void)

Description

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

Valeur de retour

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

8.4.11 Description des fonctions C du serveur embarqué

Vous devez utiliser les fonctions suivantes si vous voulez permettre à votre application d'être liée avec la librairie du serveur embarqué MySQL. See section 8.4.15 libmysqld, la librairie du serveur embarqué MySQL.

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

8.4.11.1 mysql_server_init()

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

Description

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

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

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

Exemple

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

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

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

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

  mysql_server_end();

  return EXIT_SUCCESS;
}

Valeur de retour

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

8.4.11.2 mysql_server_end()

void mysql_server_end(void)

Description

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

Valeur de retour

Aucune.

8.4.12 Questions courantes sur la librairie C

8.4.12.1 Pourquoi est ce qu'après mysql_query() ait indiqué un résultat positif, mysql_store_result() retourne parfois NULL?

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

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

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

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

8.4.12.2 Quels résultats puis-je obtenir d'une requête?

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

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

8.4.12.3 Comment obtenir l'identifiant unique du dernier enregistrement inséré ?

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

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

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

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

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

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

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

8.4.12.4 Problèmes lors de la liaison avec l'API C

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

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

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

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

8.4.13 Compiler les clients

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

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

Pour rendre ce qui pr�c�de plus simple sur Unix, nous avons fourni le script mysql_config. See section 4.8.9 mysql_config lit les options de compilations du client MySQL.

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

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

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

8.4.14 Comment faire un client MySQL threadé

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

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

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

Si vous n'avez pas besoin des interruption ou des expirations, vous pouvez compiler simplement une librairie compatible avec les threads, (mysqlclient_r) et l'utiliser. See section 8.4 MySQL C API. Dans ce cas, vous n'avez pas à vous préoccuper du fichier net_serv.o ou des autres librairies MySQL.

Lorsque vous utiliser un client threadé et que vous souhaitez utiliser des délais d'expiration et des interruptions, vous pouvez faire grand usage des routines du fichier `thr_alarm.c'. Si vous utiliser des routines issues de la librairie mysys, la seule chose à penser est de commencer par utiliser my_init()! See section 8.4.10 Description des fonctions threadées de C.

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

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

shell> ./configure --enable-thread-safe-client

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

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

Vous devez savoir ce qui suit si vous avez un thread qui appel une fonction MySQL qui n,a pas crée de connexion à la base MySQL :

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

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

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

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

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

8.4.15 libmysqld, la librairie du serveur embarqué MySQL

8.4.15.1 Vue d'ensemble de la librairie du serveur embarqué MySQL

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

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

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

Les fonctions ci-dessus mysql_server_xxx sont aussi inclues dans la librairie `libmysqlclient.a' pour vous permettre de changer facilement entre les versions de la librairie embarquée et celle de la librairie client/serveur, en compilant simplement la bonne librairie. See section 8.4.11.1 mysql_server_init().

8.4.15.2 Compiler des programmes avec libmysqld

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

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

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

8.4.15.3 Restrictions lors de l'utilisation du serveur embarqué MySQL

Le serveur embarqué possède les limitations suivantes :

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

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

8.4.15.4 Utilisation de fichiers d'options avec le serveur embarqué

Voici la manière recommandée d'utiliser les fichiers d'options pour que le passage des applications client/serveur vers une application où MySQL est embarqué soit plus facile. See section 4.1.2 Fichier d'options `my.cnf'.

• Placez les options communes dans la section [server]. Elles seront lues par les deux versions de MySQL.
• Placez les options spécifiques au client/serveur dans la section [mysqld].
• Placez les options spécifiques à MySQL embarqué dans la section [embedded].
• Placez les options spécifiques aux applications dans une section [NomApplication_SERVER].

8.4.15.5 Choses à faire pour le serveur embarqué (TODO)

• Nous ne fournissons pour l'instant qu'une version statique de la librairie mysqld, nous fournirons aussi une librairie partagée pour cela plus tard.
• Nous allons proposer des options pour se débarrasser de quelques parties de MySQL pour rendre la librairie plus petite.
• Il y a encore beaucoup d'optimisations de vitesse à faire.
• Les erreurs sont écrites dans stderr. Nous ajouterons une options pour spécifier un fichier pour cela.
• Nous devons changer InnoDB pour qu'il n'y ait plus tant de sorties lors de l'utilisation du serveur embarqué.

8.4.15.6 Un exemple simple de serveur embarqué

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

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

`test_libmysqld.c'

/*
 * Un simple exemple de client, utilisant la librairie du serveur embarqué MySQL
 */

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

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

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

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

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

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

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

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

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

  mysql_close(two);
  mysql_close(one);

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

  exit(EXIT_SUCCESS);
}

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

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

  return db;
}

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

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

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

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

  return;

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

`GNUmakefile'

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

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

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

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

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

all: $(targets)

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

8.4.15.7 Licence du serveur embarqué

Le code source de MySQL est couvert par la licence GNU GPL (see section G Licence Publique Générale GNU). L'un des effets de cela est que tout programme qui inclut, par liaison avec libmysqld, le code source de MySQL doit être réalisé en tant que logiciel libre (sous une licence compatible avec la GPL).

Nous encourageons tout le monde à promouvoir le logiciel libre en réalisant du code sous la licence GPL ou une autre licence compatible. Pour ceux qui ne peuvent le faire, une autre option est d'acheter la licence commerciale pour le code MySQL chez MySQL AB. Pour plus de détails, voyez section 1.4.3 Licences MySQL.

8.5 Interfaces MySQL pour C++

8.5.1 Borland C++

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

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

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

8.6 Connectivité Java/MySQL (JDBC)

Il y a 2 pilotes JDBC supportés pour MySQL :

• MySQL Connector/J de MySQL AB, implémenté 100% Java natif. Ce produit était connu sous le nom de pilote mm.mysql. Vous pouvez télécharger MySQL Connector/J depuis l'URL http://www.mysql.com/products/connector-j/.
• Le pilote Resin JDBC, qui est disponible sur l'URL http://www.caucho.com/projects/jdbc-mysql/index.xtp.

Pour de la documentation, consultez celle de JDBC et des pilotes pour les fonctionnalités relatives à MySQL.

8.7 Interface Python pour MySQL

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

8.8 Interface Tcl pour MySQL

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

8.9 Couche MySQL pour Eiffel

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

Go to the first, previous, next, last section, table of contents.