REFERENCE MYSQL
dernière mise à jour de la documentation : janvier 2013Preface | Informations générales | Installer MySQL | Tutoriels d'introduction | Utiliser les programmes MySQL | Administration du serveur | Réplication de MySQL | Optimisation de MySQL | MySQL Scripts clients et utilitaires | Structure du langage | Jeux de caractères et Unicode | Types de colonnes | Fonctions à utiliser dans les clauses SELECT et WHERE | . Syntaxe des commandes SQL | . Moteurs de tables MySQL et types de table | Le moteur de tables InnoDB | Introduction à MySQL Cluster | Introduction à MaxDB | Données spatiales avec MySQL | . Procédures stockées et fonctions | Déclencheurs | La base de données d'informations INFORMATION_SCHEMA | Mathématiques de précision | API MySQL | Pilotes MySQL | Gestion des erreurs avec MySQL | Etendre MySQL | Problèmes et erreurs communes | Port vers d'autres systèmes | Variables d'environnement | Expressions régulières MySQL | Index
Chapitre 24. API MySQL | ||
---|---|---|
Précédent | Suivant |
Table des matières
- 24.1. Utilitaires de développement des programmes MySQL
- 24.2. API MySQL C
- 24.2.1. Types de données de l'API C
- 24.2.2. Vue d'ensemble des fonctions de l'API C
- 24.2.3. Description des fonctions de l'API C
- 24.2.4. Fonctions C de commandes préparées
- 24.2.5. Types de données de l'API C
- 24.2.6. Présentation des fonctions de l'interface C
- 24.2.7. Description des fonctions C pour les requêtes préparées
- 24.2.8. Problèmes avec l'interface C des commandes préparées
- 24.2.9. Gestion des commandes multiples avec l'interface C
- 24.2.10. Gestion des dates et horaires avec l'interface C
- 24.2.11. Description des fonctions threadées de C
- 24.2.12. Description des fonctions C du serveur embarqué
- 24.2.13. Questions courantes sur la bibliothèque C
- 24.2.14. Compiler les clients
- 24.2.15. Comment faire un client MySQL threadé
- 24.2.16.
libmysqld
, la bibliothèque du serveur embarqué MySQL
- 24.3. API PHP pour MySQL
- 24.4. API Perl pour MySQL
- 24.5. Interface MySQL C++
- 24.6. MySQL Python API
- 24.7. MySQL Tcl API
- 24.8. Couche MySQL pour Eiffel
Ce chapitre décrit les interfaces disponibles pour MySQL, où les trouver, et comment les utiliser. L'API C est celle qui est couverte le plus en détail, puisqu'elle est développée par l'équipe MySQL, et sert de base à toutes les autres API.
Cette section décrit certains utilitaires que vous pouvez trouver utiles, lors du développement de programmes MySQL.
Initialement, l'API C de MySQL a été développée pour être très similaire à celle du serveur mSQL. A cause de cela, les programmes mSQL peuvent souvent être convertis facilement à utiliser MySQL, en changeant simplement les noms de l'API C.
L'utilitaire msql2mysql
fait cette
conversion, et transforme les appels C mSQL en leurs
équivalents MYSQL.
msql2mysql
convertit le fichier sur place :
il est recommandé de faire une copie avant de lancer la
conversion. Par exemple, utilisez msql2mysql
comme ceci :
shell>cp client-prog.c client-prog.c.orig
shell>msql2mysql client-prog.c
client-prog.c converted
Puis, examinez le fichier client-prog.c
et
faites toutes les modifications post-conversion nécessaires.
msql2mysql
utilise l'utilitaire
replace
pour faire les substitutions. See
Section 8.13, « L'utilitaire de remplacement de chaînes replace
».
mysql_config
vous indique des informations
pratiques pour compiler votre client MySQL et le connecter au
serveur.
mysql_config
supporte les options
suivantes :
--cflags
Options de compilations utilisées pour trouver les fichiers inclus.
--include
Options du compilateur pour trouver les fichiers d'inclusion MySQL. (Normalement, il faut utiliser
--cflags
au lieu de cette commande)--libs
Les bibliothèques et options requises pour compiler avec la bibliothèque client MySQL.
--libs_r
Les bibliothèques et options requises pour la compilation avec la sécurité thread de la bibliothèque client MySQL.
--socket
Le nom par défaut de la socket, défini lors de la configuration de MySQL.
--port
Le numéro de port par défaut, défini lors de la configuration de MySQL.
--version
Le numéro de version et la version de la distribution MySQL.
--libmysqld-libs
Les bibliothèques et options requises pour compiler avec la bibliothèque intégrée MySQL.
Si vous exécutez mysql_config
sans aucune
option, il va afficher toutes les options qu'il supporte, ainsi
que la valeur de toutes les options :
shell> mysql_config
Usage: /usr/local/mysql/bin/mysql_config [options]
Options:
--cflags [-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]
--include [-I/usr/local/mysql/include/mysql]
--libs [-L/usr/local/mysql/lib/mysql -lmysqlclient -lz
-lcrypt -lnsl -lm -L/usr/lib -lssl -lcrypto]
--libs_r [-L/usr/local/mysql/lib/mysql -lmysqlclient_r
-lpthread -lz -lcrypt -lnsl -lm -lpthread]
--socket [/tmp/mysql.sock]
--port [3306]
--version [4.0.16]
--libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld -lpthread -lz
-lcrypt -lnsl -lm -lpthread -lrt]
Vous pouvez utiliser mysql_config
dans une
ligne de commande pour inclure la valeur qui sera affichée par
une option. Par exemple, pour compiler un client MySQL, utilisez
mysql_config
comme ceci :
CFG=/usr/local/mysql/bin/mysql_config sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`"
Lorsque vous utilisez mysql_config
de cette
manière, assurez vous de l'invoquer entre des guillemets
obliques (‘`
’). Cela indique que
le Shell doit exécuter cette expression, et remplacer le
résultat dans la commande.
- 24.2.1. Types de données de l'API C
- 24.2.2. Vue d'ensemble des fonctions de l'API C
- 24.2.3. Description des fonctions de l'API C
- 24.2.4. Fonctions C de commandes préparées
- 24.2.5. Types de données de l'API C
- 24.2.6. Présentation des fonctions de l'interface C
- 24.2.7. Description des fonctions C pour les requêtes préparées
- 24.2.8. Problèmes avec l'interface C des commandes préparées
- 24.2.9. Gestion des commandes multiples avec l'interface C
- 24.2.10. Gestion des dates et horaires avec l'interface C
- 24.2.11. Description des fonctions threadées de C
- 24.2.12. Description des fonctions C du serveur embarqué
- 24.2.13. Questions courantes sur la bibliothèque C
- 24.2.14. Compiler les clients
- 24.2.15. Comment faire un client MySQL threadé
- 24.2.16.
libmysqld
, la bibliothèque du serveur embarqué MySQL
L'interface C est distribuée avec MySQL. Elle est inclues dans la
bibliothèque mysqlclient
et permet aux
programmes écrits en C d'accéder à la base de données.
De nombreux client de la distribution source de MySQL sont écrits
en C. Si vous recherchez des exemples d'illustration de
l'utilisation de l'interface C, étudiez donc ces clients. Vous
pouvez les trouver dans le dossier clients
de
la distribution source MySQL.
La plupart des autres interfaces clientes (sauf Connector/J)
utilisent la bibliothèque mysqlclient
pour
communiquer avec le serveur MySQL. Cela signifie que, par exemple,
que vous pouvez exploiter adroitement de nombreux autres variables
qui sont utilisées par les autres programmes clients, car elles
sont utilisées dans la bibliothèque. Voyez
Chapitre 8, MySQL Scripts clients et utilitaires, pour une liste de ces
variables.
Le client a une taille maximale de buffer de communication. La taille du buffer qui est allouée au lancement 16 ko bytes, est automatiquement augmentée jusqu'à la taille maximum de 16 Mo. Comme la taille du buffer croit à la demande, vous ne consommerez pas de ressources supplémentaires en augmentant la limite maximum par défaut. Cette limite sert surtout à s'assurer de bien identifier des problèmes de requêtes erronées ou des paquets de communication.
Le buffer de communication doit être assez grand pour contenir
une commande SQL complète (dans le sens du trafic allant vers le
serveur), et une ligne complète (dans le sens du trafic allant
vers le client). Chaque buffer de threads est dynamiquement
agrandi pour gérer les requêtes jusqu'à la taille limite. Par
exemple, si vous avez des valeurs de type BLOB
qui contient jusqu'à 16 Mo de données, vous devez avoir un
buffer de communication dont la limite doit être au minimum de 16
Mo, aussi bien sur le serveur que sur le client. La limite par
défaut sur le client est de 16 Mo mais elle est de 1 Mo sur le
serveur. Vous pouvez augmenter cette valeur en modifiant le
paramètre max_allowed_packet
lorsque le
serveur est lancé. See Section 7.5.2, « Réglage des paramètres du serveur ».
Le serveur MySQL réduit la taille des buffers de communication à
net_buffer_length
octets après chaque
requête. Pour les clients, le buffer est associé à une
connexion, et les ressources ne seront libérées que lorsque
cette dernière sera refermée.
Pour la programmation avec les threads, voyez la section
Section 24.2.15, « Comment faire un client MySQL threadé ». Pour la création
d'applications qui incluent le serveur et le client dans le même
programme, et ne communiquent avec aucun serveur externe, voyez
Section 24.2.16, « libmysqld
, la bibliothèque du serveur embarqué
MySQL ».
Cette structure représente un gestionnaire de connexion à la base de données. Elle est utilisée dans la plupart des fonctions MySQL.
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.C'est une représentation sûre pour les types d'une ligne de données. Elle est actuellement implémentée en tant que tableau de chaîne à octets comptés. (Vous ne pouvez la traiter en tant que chaîne terminée par une valeur nulle si les valeurs du champ peuvent contenir des données binaires, car de telles valeurs peuvent contenir elles-mêmes des octets nuls.) Les lignes sont obtenues en appelant
mysql_fetch_row()
.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 foismysql_fetch_field()
. Les valeurs des champs ne font pas partie de la structure; elles sont contenues dans une structureMYSQL_ROW
.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()
, etmysql_insert_id()
. Ce type fournit une échelle allant de0
à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à enunsigned 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
ouNUMERIC
FIELD_TYPE_FLOAT
Champ FLOAT
FIELD_TYPE_DOUBLE
Champ DOUBLE
ouREAL
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
ouVARCHAR
)FIELD_TYPE_VAR_STRING
Champ VARCHAR
FIELD_TYPE_BLOB
Champ BLOB
ouTEXT
(utilisezmax_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 placeVous pouvez utiliser la macro
IS_NUM()
pour tester si un champ est de type numérique ou non. Passez la valeur detype
à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()
oumysql_list_fields()
, cela contient la longueur maximale pour le champ. Si vous utilisezmysql_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
ouTEXT
(désapprouvé)TIMESTAMP_FLAG
Le champ est un TIMESTAMP
(désapprouvé)L'utilisation des attributs
BLOB_FLAG
,ENUM_FLAG
,SET_FLAG
, etTIMESTAMP_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 testerfield->type
avecFIELD_TYPE_BLOB
,FIELD_TYPE_ENUM
,FIELD_TYPE_SET
, ouFIELD_TYPE_TIMESTAMP
à la place.L'exemple suivant illustre une utilisation typique de la valeur de
flags
:if (field->flags & NOT_NULL_FLAG) printf("Le champ ne peut être nul\n");
Vous pouvez utiliser les différentes macros ci-dessous pour déterminer le statut booléen de la valeur de l'attribut :
Statut de l'attribut Description IS_NOT_NULL(flags)
Vrai si le champ est défini en tant que NOT NULL
IS_PRI_KEY(flags)
Vrai si le champ est une clef primaire IS_BLOB(flags)
Vrai si le champ est un BLOB
ouTEXT
(désapprouvé; tester plutôtfield->type
)unsigned int decimals
Le nombre de décimales pour les champs numériques.
Les fonctions disponibles dans l'API C sont listées ici et décrites en plus de détails dans la section suivante. See Section 24.2.3, « Description des fonctions de l'API C ».
Fonction | Description |
mysql_affected_rows() | Retourne le nombre de lignes changées/effacées/insérés par le
dernier UPDATE ,
DELETE , ou INSERT . |
mysql_change_user() | Change l'utilisateur et la base de données pour une connexion ouverte. |
mysql_character_set_name() | Retourne le nom du jeu de caractère de la connexion. |
mysql_close() | Ferme une connexion au serveur. |
mysql_connect() | Connecte à un serveur MySQL. Cette fonction est désapprouvée;
utilisez mysql_real_connect() à la
place. |
mysql_create_db() | Crée une base de données. Cette fonction est désapprouvée, utilisez
plutôt la commande SQL CREATE
DATABASE . |
mysql_data_seek() | Déplace le pointeur vers une ligne arbitraire dans le jeu de résultats de la requête. |
mysql_debug() | Effectue un DBUG_PUSH avec la chaîne donnée. |
mysql_drop_db() | Supprime une base de données. Cette fonction est désapprouvée,
utilisez plutôt la commande SQL DROP
DATABASE . |
mysql_dump_debug_info() | Demande au serveur d'écrire les informations de débogage dans un fichier de log. |
mysql_eof() | Détermine si la dernière ligne du jeu de résultats a été lue ou
non. Cette fonction est désapprouvée, vous pouvez
utiliser mysql_errno() ou
mysql_error() à la place. |
mysql_errno() | Retourne le numéro de l'erreur de la fonction appelée en dernier. |
mysql_error() | Retourne le message d'erreur de la dernière fonction MySQL appelée. |
mysql_escape_string() | Protège une chaîne en échappant les caractères spéciaux. |
mysql_fetch_field() | Retourne le type du champ suivant dans la table. |
mysql_fetch_field_direct() | Retourne le type d'une colonne, étant donné un numéro de champ. |
mysql_fetch_fields() | Retourne un tableau avec toutes les structures de champs. |
mysql_fetch_lengths() | Retourne la longueur de toutes les colonnes dans la ligne suivante. |
mysql_fetch_row() | Récupère la ligne suivante dans le jeu de résultats. |
mysql_field_seek() | Place le curseur de colonne sur une colonne précise. |
mysql_field_count() | Retourne le nombre de colonnes dans le résultat pour la requête la plus récente. |
mysql_field_tell() | Retourne la position du curseur de champs utilisé pour le dernier appel
à mysql_fetch_field() . |
mysql_free_result() | Libère la mémoire utilisée par un jeu de résultats. |
mysql_get_client_info() | Retourne la version du client sous forme de chaîne. |
mysql_get_client_version() | Retourne la version du client sous forme d'entier. |
mysql_get_host_info() | Retourne une chaîne décrivant la connexion. |
mysql_get_server_version() | Retourne le numéro de version du serveur sous forme d'entier (nouveau en 4.1). |
mysql_get_proto_info() | Retourne la version du protocole utilisé par la connexion. |
mysql_get_server_info() | Retourne la version du serveur. |
mysql_info() | Retourne des informations à propos de la requête la plus récente. |
mysql_init() | Récupère ou initialise une structure MYSQL . |
mysql_insert_id() | Retourne l'identifié généré pour une colonne
AUTO_INCREMENT par la dernière
requête. |
mysql_kill() | Termine un processus donné. |
mysql_list_dbs() | Retourne les noms des bases de données répondant à une expression régulière simple. |
mysql_list_fields() | Retourne les noms des champs répondants à une expression régulière simple. |
mysql_list_processes() | Retourne une liste des processus courants du serveur. |
mysql_list_tables() | Retourne les noms des tables répondants à une expression régulière simple. |
mysql_num_fields() | Retourne le nombre de colonnes dans un jeu de résultats. |
mysql_num_rows() | Retourne le nombre de lignes dans le jeu de résultats. |
mysql_options() | Configure les options de connexion pour
mysql_connect() . |
mysql_ping() | Vérifie si la connexion au serveur a toujours lieu. Reconnecte si besoin. |
mysql_query() | Exécute une requête SQL spécifiée en tant que chaîne terminée par un caractère nul. |
mysql_real_connect() | Connecte à un serveur MySQL. |
mysql_real_escape_string() | Protège les caractères spéciaux dans une chaîne utilisable dans une requête SQL, en prenant en compte le jeu de caractères courant de la connexion. |
mysql_real_query() | Exécute une requête SQL spécifiée en tant que chaîne comptée. |
mysql_reload() | Demande au serveur de recharger la table des droits. |
mysql_row_seek() | Déplace le pointeur vers un ligne dans le jeu de résultats, en
utilisant une valeur retournée par
mysql_row_tell() . |
mysql_row_tell() | Retourne la position du curseur de lignes. |
mysql_select_db() | Sélectionne une base de données. |
mysql_set_server_option() | Spécifie la valeur d'une option pour la connexion (comme
multi-statements ). |
mysql_sqlstate() | Retourne l'erreur SQLSTATE de la dernière erreur. |
mysql_shutdown() | Termine le serveur de base de données. |
mysql_stat() | Retourne le statut du serveur dans une chaîne. |
mysql_store_result() | Récupère le jeu de résultats complet dans le client. |
mysql_thread_id() | Retourne l'identifiant du thread courant. |
mysql_thread_safe() | Retourne 1 si le client est compilé avec la sécurité thread. |
mysql_use_result() | Initialise une récupération ligne par ligne des résultats. |
mysql_warning_count() | Retourne le nombre d'alertes générées par la dernière commande SQL. |
mysql_commit() | Valide une transaction (nouveau en 4.1). |
mysql_rollback() | Annule une transaction (nouveau en 4.1). |
mysql_autocommit() | Active et désactive le mode d'auto validation (nouveau en 4.1). |
mysql_more_results() | Vérifie si il n'y a plus de résultats (nouveau en 4.1). |
mysql_next_result() | Retourne/initie le prochain résultat dans une commande multi-requête (nouveau en 4.1). |
Pour vous connecter au serveur, appelez
mysql_init()
pour initialiser un gestionnaire
de connexion, puis appelez
mysql_real_connect()
avec ce gestionnaire
(avec d'autres informations tel que l'hôte, l'utilisateur et le
mot de passe). Lors de la connexion,
mysql_real_connect()
définit l'option
reconnect
(quit fait partie de la structure
MYSQL) à 1
. Cette option indique, dans le
cas où une requête ne peut être exécutée à cause d'une
perte de connexion, d'essayer de se reconnecter au serveur avant
d'abandonner. Lorsque vous n'avez plus besoin de la connexion,
appelez mysql_close()
pour la clore.
Tant qu'une connexion est active, le client envoi des requêtes
SQL au serveur à l'aide de mysql_query()
ou
mysql_real_query()
. La différence entre les
deux est que mysql_query()
s'attend à ce que
la requête soit spécifiée en tant que chaîne terminée par
la chaîne nulle, tandis que
mysql_real_query()
attend une chaîne de
longueur connue. Si la chaîne contient des données binaires
(incluant l'octet nul), vous devez utiliser
mysql_real_query()
.
Pour chaque requête non-sélective (par exemple,
INSERT
, UPDATE
,
DELETE
), vous pouvez trouver combien de
lignes ont été mises à jour (affectées) en appelant
mysql_affected_rows()
.
Pour les requêtes SELECT
, vous récupérez
les lignes sélectionnées dans un jeu de résultat. (Notez que
quelques commandes ont le même comportement que
SELECT
, dans le sens où elle renvoient des
lignes. Cela inclut SHOW
,
DESCRIBE
, et EXPLAIN
.
Elles doivent être traitées de la même fa¸on que les
requêtes SELECT
.)
Il y a deux fa¸ons pour un client de gérer les jeux de
résultats. Une méthode consiste à récupérer le jeu de
résultat en entier et en une seule fois en appelant
mysql_store_result()
. Cette fonction obtient
toutes les lignes retournées par la requête et les stocke dans
le client. La seconde méthode consiste à initialiser une
récupération ligne par ligne du jeu de résultats en appelant
mysql_use_result()
. Cette fonction initie la
récupération, mais ne récupère actuellement aucune ligne à
partir du serveur.
Dans les deux cas, vous accédez aux ligne en appelant
mysql_fetch_row()
. Avec
mysql_store_result()
,
mysql_fetch_row()
accède aux lignes qui ont
déjà été récupérées à partir du serveur. Avec
mysql_use_result()
,
mysql_fetch_row()
récupère actuellement la
ligne à partir du serveur. Les informations à propos de la
taille des données dans chaque ligne est disponible en appelant
mysql_fetch_lengths()
.
Après avoir fini de traiter le jeu de résultats, appelez
mysql_free_result()
pour libérer la mémoire
utilisée.
Les deux mécanismes de récupération sont complémentaires.
Les programmes clients doivent utiliser l'approche qui leur
convient le mieux. En pratique, les clients tendent plus à
utiliser mysql_store_result()
.
Un avantage de mysql_store_result()
est que
puisque toutes les lignes ont été récupérées dans le
client, vous ne pouvez pas que accéder aux lignes
séquentiellement, vous pouvez revenir en arrière ou avancer
dans le jeu de résultats en utilisant
mysql_data_seek()
ou
mysql_row_seek()
pour changer la position de
la ligne courante dans le jeu de résultats. Vous pouvez aussi
trouver le nombre total des lignes en appelant
mysql_num_rows()
. D'un autre côté, les
besoins en mémoire de mysql_store_result()
peuvent être très grands pour les grands jeux de résultats et
vous aurez des chances d'obtenir un manque de mémoire.
Un avantage de mysql_use_result()
est que le
client a besoin de moins de mémoire pour le jeu de résultats
car il utilise une ligne à la fois (et puisque il y a moins de
pertes de mémoire, mysql_use_result()
peut
être plus rapide). Les inconvénients sont que vous devez
récupérer chaque ligne rapidement pour éviter de bloquer le
serveur, vous n'avez pas d'accès aléatoires aux lignes dans le
jeu de résultats (vous ne pouvez accéder aux lignes que
séquentiellement), et vous ne savez pas combien de lignes
comporte le jeu de résultats tant que vous ne les avez pas
toutes récupérées. De plus, vous
devez récupérer toutes les
lignes même si vous trouvez entre-temps l'informations que vous
cherchiez.
L'API permet aux clients de gérer correctement les requêtes
(récupérant les lignes seulement en cas de besoin) sans savoir
si la requête était un SELECT
ou non. Vous
pouvez faire cela en appelant
mysql_store_result()
après chaque
mysql_query()
(ou
mysql_real_query()
). Si l'appel au jeu de
résultats réussi, la requête était un
SELECT
et vous pouvez lire les lignes. Sinon,
appelez mysql_field_count()
pour vérifier si
un résultat aurait du être retourné. Si
mysql_field_count()
retourne zéro, la
requête n'a pas retourné de données (cela indique que
c'était un INSERT
,
UPDATE
, DELETE
, etc.), et
ne devait pas retourner de lignes. Si
mysql_field_count()
est non-nul, la requête
aurait du retourner des lignes, mais ne l'a pas fait. Cela
indique que la requête était un SELECT
qui
a échoué. Reportez vous à la description de
mysql_field_count()
pour un exemple
d'utilisation.
mysql_store_result()
et
mysql_use_result()
vous permettent d'obtenir
des informations à propos des champs qui constituent le jeu de
résultat (le nombre de champs, leurs noms et types, etc.). Vous
pouvez accéder aux informations du champ séquentiellement dans
une ligne en appelant plusieurs fois
mysql_fetch_field()
, ou avec le numéro du
champ dans la ligne en appelant
mysql_fetch_field_direct()
. La position
courante du pointeur de champ peut être changée en appelant
mysql_field_seek()
. Changer le pointeur de
champ affecte les appels suivants à
mysql_fetch_field()
. Vous pouvez aussi
obtenir en une seule fois les informations sur les champs en
appelant mysql_fetch_fields()
.
Pour détecter les erreurs, MySQL fournit un accès aux
informations des erreurs via les fonctions
mysql_errno()
et
mysql_error()
. Elles retournent le code de
l'erreur et le message pour la dernière fonction invoquée qui
aurait pu réussir ou échouer, vous permettant ainsi de
déterminer les erreurs et leurs causes.
- 24.2.3.1.
mysql_affected_rows()
- 24.2.3.2.
mysql_change_user()
- 24.2.3.3.
mysql_character_set_name()
- 24.2.3.4.
mysql_close()
- 24.2.3.5.
mysql_connect()
- 24.2.3.6.
mysql_create_db()
- 24.2.3.7.
mysql_data_seek()
- 24.2.3.8.
mysql_debug()
- 24.2.3.9.
mysql_drop_db()
- 24.2.3.10.
mysql_dump_debug_info()
- 24.2.3.11.
mysql_eof()
- 24.2.3.12.
mysql_errno()
- 24.2.3.13.
mysql_error()
- 24.2.3.14.
mysql_escape_string()
- 24.2.3.15.
mysql_fetch_field()
- 24.2.3.16.
mysql_fetch_fields()
- 24.2.3.17.
mysql_fetch_field_direct()
- 24.2.3.18.
mysql_fetch_lengths()
- 24.2.3.19.
mysql_fetch_row()
- 24.2.3.20.
mysql_field_count()
- 24.2.3.21.
mysql_field_seek()
- 24.2.3.22.
mysql_field_tell()
- 24.2.3.23.
mysql_free_result()
- 24.2.3.24.
mysql_get_client_info()
- 24.2.3.25.
mysql_get_client_version()
- 24.2.3.26.
mysql_get_host_info()
- 24.2.3.27.
mysql_get_proto_info()
- 24.2.3.28.
mysql_get_server_info()
- 24.2.3.29.
mysql_get_server_version()
- 24.2.3.30.
mysql_hex_string()
- 24.2.3.31.
mysql_info()
- 24.2.3.32.
mysql_init()
- 24.2.3.33.
mysql_insert_id()
- 24.2.3.34.
mysql_kill()
- 24.2.3.35.
mysql_library_end()
- 24.2.3.36.
mysql_library_end()
- 24.2.3.37.
mysql_list_dbs()
- 24.2.3.38.
mysql_list_fields()
- 24.2.3.39.
mysql_list_processes()
- 24.2.3.40.
mysql_list_tables()
- 24.2.3.41.
mysql_num_fields()
- 24.2.3.42.
mysql_num_rows()
- 24.2.3.43.
mysql_options()
- 24.2.3.44.
mysql_ping()
- 24.2.3.45.
mysql_query()
- 24.2.3.46.
mysql_real_connect()
- 24.2.3.47.
mysql_real_escape_string()
- 24.2.3.48.
mysql_real_query()
- 24.2.3.49.
mysql_reload()
- 24.2.3.50.
mysql_row_seek()
- 24.2.3.51.
mysql_row_tell()
- 24.2.3.52.
mysql_select_db()
- 24.2.3.53.
mysql_set_server_option()
- 24.2.3.54.
mysql_shutdown()
- 24.2.3.55.
mysql_sqlstate()
- 24.2.3.56.
mysql_ssl_s et()
- 24.2.3.57.
mysql_stat()
- 24.2.3.58.
mysql_store_result()
- 24.2.3.59.
mysql_thread_id()
- 24.2.3.60.
mysql_use_result()
- 24.2.3.61.
mysql_warning_count()
- 24.2.3.62.
mysql_commit()
- 24.2.3.63.
mysql_rollback()
- 24.2.3.64.
mysql_autocommit()
- 24.2.3.65.
mysql_more_results()
- 24.2.3.66.
mysql_next_result()
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