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