my_ulonglong mysql_affected_rows(MYSQL *mysql)

Beschreibung

Gibt die Anzahl von Zeilen zurück, die durch das letzte UPDATE geändert, durch das letzte DELETE gelöscht oder durch das letzte INSERT eingefügt wurden. Kann direkt nach mysql_query() aufgerufen werden, bei UPDATE-, DELETE- oder INSERT-Statements. Bei SELECT-Statements funktioniert mysql_affected_rows() wie mysql_num_rows().

Rückgabewerte

Eine Ganzzahl größer als 0 gibt die Anzahl von Zeilen an, die betroffen oder abgerufen wurden. 0 gibt an, dass keine Datensätze bei einem UPDATE-Statement geändert wurden, keine Zeilen der WHERE-Klausel in der Anfrage entsprachen oder dass bislang keine Anfrage ausgeführt wurde. -1 gibt an, dass die Anfrage einen Fehler zurückgab oder dass - bei einer SELECT-Anfrage - mysql_affected_rows() vor mysql_store_result() aufgerufen wurde.

Fehler

Keine.

Beispiel

mysql_query(&mysql,"UPDATE produkte SET kosten=kosten*1.25 WHERE gruppe=10");
printf("%ld produkte updated",(long) mysql_affected_rows(&mysql));

Wenn man den Flag CLIENT_FOUND_ROWS angibt, wenn man sich mit mysqld verbindet, gibt mysql_affected_rows() die Anzahl von Zeilen zurück, die mit dem WHERE-Statement bei UPDATE-Statements übereinstimmten.

Beachten Sie bei der Benutzung des REPLACE-Befehls, dass mysql_affected_rows() 2 zurückgibt, wenn die neue Zeile eine alte Zeile ersetzte. Das liegt daran, dass in diesem Fall eine neue Zeile eingefügt und dann das alte Duplikat gelöscht wurde.

void mysql_close(MYSQL *mysql)

Beschreibung

Schließt eine vorher geöffnete Verbindung. mysql_close() gibt auch den Verbindungs-Handle frei, der von mysql zugewiesen wurde, wenn der Handle automatisch mit mysql_init() oder mysql_connect() zugewiesen wurde.

Rückgabewerte

Keine.

Fehler

Keine.

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

Beschreibung

Diese Funktion ist veraltet. Sie sollten statt dessen mysql_real_connect() benutzen.

mysql_connect() versucht, eine Verbindung zu einer MySQL-Datenbankmaschine aufzubauen, die auf host läuft. mysql_connect() muss erfolgreich beendet werden, bevor Sie irgend welche weiteren API-Funktionen aufrufen können, mit Ausnahme von mysql_get_client_info().

Die Bedeutung der Parameter ist dieselbe wie die entsprechenden Parameter bei mysql_real_connect(), mit dem Unterschied, dass die Verbindungsparameter NULL sein dürfen. In diesem Fall weist die C-API automatisch Speicher für die Verbindungsstruktur zu und gibt diesen frei, wenn Sie mysql_close() aufrufen. Der Nachteil dieses Ansatzes besteht darin, dass Sie keine Fehlermeldung abrufen können, wenn die Verbindung fehlschlägt. (Um Fehlerinformationen von mysql_errno() oder mysql_error() abrufen zu können, müssen Sie einen gültigen MYSQL-Zeiger angeben.)

Rückgabewerte

Dieselben wie für mysql_real_connect().

Fehler

Dieselben wie für mysql_real_connect().

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

Beschreibung

Ändert den Benutzer und veranlasst, dass die Datenbank, die mit db angegeben wurde, die vorgabemäßige (aktuelle) Datenbank für die Verbindung wird, die durch mysql festgelegt wurde. In nachfolgenden Anfragen ist diese Datenbank die Vorgabe für Tabellenverweise, bei denen nicht explizit eine Datenbank angegeben wird.

Diese Funktion wurde in MySQL-Version 3.23.3 eingeführt.

mysql_change_user() schlägt fehl, wenn sich der Benutzer nicht authentifizieren kann oder wenn er keine Zugriffsrechte auf die Datenbank hat. In diesem Fall werden Benutzer und Datenbank nicht geändert.

Der db-Parameter kann auf NULL gesetzt werden, wenn Sie keine vorgabemäßige Datenbank haben wollen.

Rückgabewerte

0 für Erfolg. Nicht-0, wenn ein Fehler auftrat.

Fehler

Dieselben, die Sie von mysql_real_connect() erhalten.

Beispiel

if (mysql_change_user(&mysql, "benutzer", "passwort", "neue_datenbank"))
{
   fprintf(stderr, "Änderung des Benutzers fehlgeschlagen. Fehler: %s\n",
           mysql_error(&mysql));
}

const char *mysql_character_set_name(MYSQL *mysql)

Beschreibung

Gibt den vorgabemäßigen Zeichensatz für die aktuelle Verbindung zurück.

Rückgabewerte

Der vorgabemäßige Zeichensatz

Fehler

Keine.

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

Beschreibung

Erzeugt die Datenbank, die durch den db-Parameter angegeben wird.

Diese Funktion ist veraltet. Vorzugsweise sollten Sie mysql_query() benutzen, um statt dessen ein SQL-CREATE DATABASE-Statement abzusetzen.

Rückgabewerte

0, wenn die Datenbank erfolgreich erzeugt wurde. Nicht-0, wenn ein Fehler auftrat.

Fehler

Beispiel

if(mysql_create_db(&mysql, "meine_datenbank"))
{
   fprintf(stderr, "Erzeugung der neuen Datenbank fehlgeschlagen. Fehler: %s\n",
           mysql_error(&mysql));
}

void mysql_data_seek(MYSQL_RES *result, unsigned long long offset)

Beschreibung

Sucht bis zu einer beliebigen Zeile in einer Anfrageergebnismenge. Das setzt voraus, dass die Ergebnismengenstruktur das gesamte Anfrageergebnis enthält. Daher kann mysql_data_seek() nur in Verbindung mit mysql_store_result() benutzt werden, nicht in Verbindung mit mysql_use_result().

Der Offset sollte ein Wert im Bereich von 0 bis mysql_num_rows(ergebnis)-1 sein.

Rückgabewerte

Keine.

Fehler

Keine.

void mysql_debug(char *debug)

Beschreibung

Führt ein DBUG_PUSH mit der angegebenen Zeichenkette durch. mysql_debug() benutzt die Debug-Bibliothek von Fred Fish. Um diese Funktion benutzen zu können, müssen Sie die Client-Bibliothek so kompilieren, dass sie Debuggen unterstützt. See Abschnitt D.1, „Einen MySQL-Server debuggen“. See Abschnitt D.2, „Einen MySQL-Client debuggen“.

Rückgabewerte

Keine.

Fehler

Keine.

Beispiel

Der unten stehende Aufruf führt dazu, dass die Client-Bibliothek eine Trace-Datei in /tmp/client.trace auf der Client-Maschine erzeugt:

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

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

Beschreibung

Löscht die Datenbank, die durch den db-Parameter angegeben wird.

Diese Funktion ist veraltet. Benutzen Sie vorzugsweise mysql_query(), um statt dessen ein SQL-DROP DATABASE-Statement abzusetzen.

Rückgabewerte

0, wenn die Datenbank erfolgreich gelöscht wurde. Nicht-0, wenn ein Fehler auftrat.

Fehler

Beispiel

if(mysql_drop_db(&mysql, "meine_datenbank"))
  fprintf(stderr, "Löschen der Datenbank fehlgeschlagen: Fehler: %s\n",
          mysql_error(&mysql));

int mysql_dump_debug_info(MYSQL *mysql)

Beschreibung

Weist den Server an, Debug-Informationen ins Log zu schreiben. Damit das funktioniert, muss der verbundene Benutzer die process-Berechtigung haben.

Rückgabewerte

0, wenn der Befehl erfolgreich war. Nicht-0, wenn ein Fehler auftrat.

Fehler

my_bool mysql_eof(MYSQL_RES *result)

Beschreibung

Diese Funktion ist veraltet. Benutzen Sie statt dessen mysql_errno() oder mysql_error().

mysql_eof() stellt fest, ob die letzte Zeile einer Ergebnismenge gelesen wurde oder nicht.

Wenn Sie eine Ergebnismenge durch einen erfolgreichen Aufruf von mysql_store_result() erhalten, erhält der Client den gesamten Satz in einer Operation. In diesem Fall bedeutet eine NULL-Rückgabe von mysql_fetch_row() immer, dass das Ende der Ergebnismenge erreicht wurde und es unnötig ist, mysql_eof() aufzurufen.

Wenn Sie auf der anderen Seite mysql_use_result() aufrufen, um den Abruf einer Ergebnismenge zu initialisieren, werden die Zeilen des Satzes Zeile für Zeile vom Server erlangt, indem Sie mysql_fetch_row() wiederholt aufrufen. Weil während dieses Prozesses ein Verbindungsfehler auftreten kann, bedeutet ein NULL-Rückgabewert von mysql_fetch_row() nicht notwendigerweise, dass das Ende der Ergebnismenge auf normale Weise erreicht wurde. In diesem Fall können Sie mysql_eof() benutzen, um festzustellen, was passiert ist. mysql_eof() gibt einen Nicht-0-Wert zurück, wenn das Ende der Ergebnismenge erreicht wurde, und 0, wenn ein Fehler auftrat.

Historisch liegt mysql_eof() vor den Standard-MySQL-Fehlerfunktionen mysql_errno() und mysql_error(). Weil diese Fehlerfunktionen dieselben Informationen zur Verfügung stellen, wird ihre Benutzung des des veralteten mysql_eof() empfohlen. (Sie stellen in der Tat sogar mehr Informationen zur Verfügung, weil mysql_eof() nur einen Bool'schen Wert zurückgibt, während die Fehlerfunktionen den Grund angeben, warum der Fehler auftrat.)

Rückgabewerte

0, wenn kein Fehler auftrat. Nicht-0, wenn das Ende der Ergebnismenge erreicht wurde.

Fehler

Keine.

Beispiel

Folgendes Beispiel zeigt, wie Sie mysql_eof() benutzen können:

mysql_query(&mysql,"SELECT * FROM tabelle");
ergebnis = mysql_use_result(&mysql);
while((zeile = mysql_fetch_row(ergebnis)))
{
    // Daten verarbeiten usw.
}
if(!mysql_eof(ergebnis))  // mysql_fetch_row() schlug wegen eines Fehlers fehl
{
    fprintf(stderr, "Fehler: %s\n", mysql_error(&mysql));
}

Sie können denselben Effekt jedoch auch mit den Standard-MySQL-Fehlerfunktionen erreichen:

mysql_query(&mysql,"SELECT * FROM tabelle");
result = mysql_use_result(&mysql);
while((zeile = mysql_fetch_row(ergebnis)))
{
    // Daten verarbeiten usw.
}
if(mysql_errno(&mysql))  // mysql_fetch_row() schlug wegen eines Fehlers fehl
{
    fprintf(stderr, "Fehler: %s\n", mysql_error(&mysql));
}

unsigned int mysql_errno(MYSQL *mysql)

Beschreibung

Für die von mysql angegebene Verbindung gibt mysql_errno() den Fehlercode für die zuletzt aufgerufene API-Funktion zurück, die erfolgreich sein oder fehlschlagen kann. Ein Rückgabewert von 0 bedeutet, dass kein Fehler auftrat. Client-Fehlermeldungsnummern sind in der MySQL-errmsg.h-Header-Datei aufgelistet. Server-Fehlermeldungsnummern sind in mysqld_error.h aufgelistet. In der MySQL-Quelldistribution finden Sie eine komplette Liste der Fehlermeldungen und Fehlernummern in der Datei Docs/mysqld_error.txt.

Rückgabewerte

Ein Fehlercode-Wert. 0, wenn kein Fehler auftrat.

Fehler

Keine.

char *mysql_error(MYSQL *mysql)

Beschreibung

Für die von mysql angegebene Verbindung gibt mysql_error() die Fehlermeldung für die zuletzt aufgerufene API-Funktion zurück, die erfolgreich sein oder fehlschlagen kann. Eine leere Zeichenkette ("") wird zurückgegeben, wenn kein Fehler auftrat. Das bedeutet, dass folgende zwei Tests äquivalent sind:

if(mysql_errno(&mysql))
{
    // Ein Fehler trat auf
}

if(mysql_error(&mysql)[0] != '\0')
{
    // Ein Fehler trat auf
}

Die Sprache der Client-Fehlermeldungen kann durch erneutes Kompilieren der MySQL-Client-Bibliothek geändert werden. Sie können Fehlermeldungen in mehreren unterschiedlichen Sprachen auswählen. See Abschnitt 5.6.2, „Nicht englische Fehlermeldungen“.

Rückgabewerte

Eine Zeichenkette, die den Fehler beschreibt. Eine leere Zeichenkette, wenn kein Fehler auftrat.

Fehler

Keine.

Statt dessen sollten Sie mysql_real_escape_string() benutzen!

Das ist identisch mit mysql_real_escape_string(), ausser dass die Verbindung als erstes Argument genommen wird. mysql_real_escape_string() escapet die Zeichenkette gemäß dem aktuellen Zeichensatz, wohingegen mysql_escape_string() die aktuelle Zeichensatzeinstellung ignoriert.

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Beschreibung

Gibt die Definition einer Spalte der Ergebnismenge als MYSQL_FIELD-Struktur zurück. Rufen Sie diese Funktion wiederholt auf, um Informationen über alle Spalten in der Ergebnismenge zu erhalten. mysql_fetch_field() gibt NULL zurück, wenn es keine weiteren Felder mehr gibt.

mysql_fetch_field() wird zurückgesetzt, so dass sie Informationen über das erste Feld zurückgibt, und zwar jedes Mal, wenn Sie eine neue SELECT-Anfrage ausführen. Das von mysql_fetch_field() zurückgegebene Feld wird auch durch Aufrufe von mysql_field_seek() betroffen.

Wenn Sie mysql_query() aufgerufen haben, um ein SELECT auf eine Tabelle auszuführen, aber nicht mysql_store_result() aufgerufen haben, gibt MySQL die vorgabemäßige BLOB-Länge (8 KB) zurück, wenn Sie mysql_fetch_field() aufrufen, um nach der Länge eines BLOB-Felds zu fragen. (Die Größe von 8 KB wird gewählt, weil MySQL die maximale Länge des BLOB nicht kennt. Das wird irgendwann einmal konfigurierbar gemacht.) Nachdem Sie die Ergebnismenge erst einmal abgerufen haben, enthält field->max_length die Länge des längsten Werts dieser Spalte in der bestimmten Anfrage.

Rückgabewerte

Die MYSQL_FIELD-Struktur der aktuellen Spalte. NULL, wenn keine Spalten mehr übrig sind.

Fehler

Keine.

Beispiel

MYSQL_FIELD *field;

while((field = mysql_fetch_field(ergebnis)))
{
    printf("Feldname %s\n", field->name);
}

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

Beschreibung

Gibt ein Array aller MYSQL_FIELD-Strukturen für eine Ergebnismenge zurück. Jede Struktur stellt Felddefinitionen für eine Spalte der Ergebnismenge zur Verfügung.

Rückgabewerte

Ein Array von MYSQL_FIELD-Strukturen für alle Spalten einer Ergebnismenge.

Fehler

Keine.

Beispiel

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

num_fields = mysql_num_fields(ergebnis);
fields = mysql_fetch_fields(ergebnis);
for(i = 0; i < num_fields; i++)
{
   printf("Feld %u ist %s\n", i, fields[i].name);
}

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

Beschreibung

Mit der Angabe einer Feldnummer feldnr für eine Spalte innerhalb einer Ergebnismenge gibt sie die Felddefinition dieser Spalte als MYSQL_FIELD-Struktur zurück. Sie können diese Funktion verwenden, um die Definition für eine beliebige Spalte abzurufen. Der Wert von feldnr sollte im Bereich von 0 bis mysql_num_fields(ergebnis)-1 liegen.

Rückgabewerte

Die MYSQL_FIELD-Struktur für die angegebene Spalte.

Fehler

Keine.

Beispiel

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

num_fields = mysql_num_fields(ergebnis);
for(i = 0; i < num_fields; i++)
{
    field = mysql_fetch_field_direct(ergebnis, i);
    printf("Feld %u ist %s\n", i, field->name);
}

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

Beschreibung

Gibt die Länge der Spalten der aktuellen Zeile innerhalb der Ergebnismenge zurück. Wenn Sie vorhaben, Feldwerte zu kopieren, sind diese Längeninformationen auch nützlich für Optimierungen, weil Sie vermeiden können, strlen() aufzurufen. Wenn die Ergebnismenge Binärdaten enthält, kommt hinzu, dass Sie diese Funktion benutzen müssen, um die Größe der Daten zu bestimmen, weil strlen() falsche Ergebnisse für Felder zurückgibt, die NULL-Zeichen enthalten.

Die Länge leerer Spalten und von Spalten, die NULL-Werte enthalten, ist 0. Um zu sehen, wie man diese beiden Fälle auseinander hält, sehen Sie in der Beschreibung von mysql_fetch_row() nach.

Rückgabewerte

Ein Array vorzeichenloser langer Ganzzahlen (long integer), die die Größe jeder Spalte darstellen (ohne irgend welche begrenzenden NULL-Zeichen). NULL, wenn ein Fehler auftrat.

Fehler

mysql_fetch_lengths() ist nur für die aktuelle Zeile der Ergebnismenge gültig. Sie gibt NULL zurück, wenn Sie sie vor mysql_fetch_row() oder nach dem Abruf aller Zeilen im Ergebnis aufrufen.

Beispiel

MYSQL_ROW zeile;
unsigned long *laengen;
unsigned int anzahl_felder;
unsigned int i;

zeile = mysql_fetch_row(ergebnis);
if (zeile)
{
    anzahl_felder = mysql_num_fields(ergebnis);
    laengen = mysql_fetch_lengths(ergebnis);
    for(i = 0; i < anzahl_felder; i++)
    {
         printf("Spalte %u ist %lu Bytes lang.\n", i, lengths[i]);
    }
}

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

Beschreibung

Ruft die nächste Zeile einer Ergebnismenge ab. Wenn sie nach mysql_store_result() benutzt wird, gibt mysql_fetch_row() NULL zurück, wenn es keine weiteren Zeilen zum Abruf mehr gibt. Wenn sie nach mysql_use_result() benutzt wird, gibt mysql_fetch_row() NULL zurück, wenn es keine Zeilen mehr zum Abruf gibt oder wenn ein Fehler auftrat.

Die Anzahl von Werten in der Zeile wird durch mysql_num_fields(ergebnis) gegeben. Wenn zeile den Rückgabewert eines Aufrufs von mysql_fetch_row() enthält, wird auf Zeiger auf die Werte als zeile[0] bis zeile[mysql_num_fields(ergebnis)-1] zugegriffen. NULL-Werte in der Zeile werden durch NULL-Zeiger angezeigt.

Die Längen der Feldwerte in der Zeile können durch Aufruf von mysql_fetch_lengths() bestimmt werden. Leere Felder und Felder, die NULL enthalten, haben beide die Länge 0. Sie können diese auseinanderhalten, indem Sie den Zeiger für den Feldwert überprüfen. Wenn der Zeiger NULL ist, ist das Feld NULL, ansonsten ist das Feld leer.

Rückgabewerte

Eine MYSQL_ROW-Struktur für die nächste Zeile. NULL, wenn keine weiteren Zeilen abzurufen sind oder wenn ein Fehler auftrat.

Fehler

Beispiel

MYSQL_ROW zeile;
unsigned int anzahl_felder;
unsigned int i;

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

unsigned int mysql_field_count(MYSQL *mysql)

Wenn Sie eine Version von MySQL vor Version 3.22.24 benutzen, sollten Sie statt dessen unsigned int mysql_num_fields(MYSQL *mysql) benutzen.

Beschreibung

Gibt die Anzahl von Spalten der letzten Anfrage auf der Verbindung zurück.

Normalerweise wird diese Funktion benutzt, wenn mysql_store_result() NULL zurückgab (und Sie daher keinen Ergebnismengen-Zeiger haben). In diesem Fall können Sie mysql_field_count() aufrufen, um festzustellen, ob mysql_store_result() ein leeres Ergebnis hätte zurückgeben sollen oder nicht. Das gestattet dem Client-Programm, die richtigen Aktionen zu ergreifen, ohne wissen zu müssen, ob die Anfrage ein SELECT war oder nicht (oder ein SELECT-ähnliches Statement). Das unten stehende Beispiel zeigt, wie man das machen kann.

See Abschnitt 9.4.6.1, „Warum gibt mysql_store_result() manchmal NULL zurück, nachdem mysql_query() Erfolg zurückgegeben hat?“.

Rückgabewerte

Eine vorzeichenlose Ganzzahl, die die Anzahl von Feldern in einer Ergebnismenge darstellt.

Fehler

Keine.

Beispiel

MYSQL_RES *result;
unsigned int anzahl_felder;
unsigned int anzahl_zeilen;

if (mysql_query(&mysql,anfrage))
{
    // FEHLER
}
else // Anfrage war erfolgreich, zurückgegebene Daten verarbeiten
{
    ergebnis = mysql_store_result(&mysql);
    if (ergebnis)  // Es gibt Zeilen
    {
        anzahl_felder = mysql_num_fields(ergebnis);
        // Zeilen abrufen, dann mysql_free_result(result) aufrufen
    }
    else  // mysql_store_result() gab nichts zurück, hätte es etwas zurückgeben sollen?
    {
        if(mysql_field_count(&mysql) == 0)
        {
            // Anfrage gibt keine Daten zurück
            // (Anfrage war kein SELECT)
            anzahl_zeilen = mysql_affected_rows(&mysql);
        }
        else // mysql_store_result() hätte Daten zurückgeben sollen
        {
            fprintf(stderr, "Fehler: %s\n", mysql_error(&mysql));
        }
    }
}

Eine Alternative besteht darin, den mysql_field_count(&mysql)-Aufruf durch mysql_errno(&mysql) zu ersetzen. In diesem Fall überprüfen Sie direkt auf einen Fehler von mysql_store_result(), statt aus dem Wert von mysql_field_count() zu schlussfolgern, ob das Statement ein SELECT war oder nicht.

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Beschreibung

Setzt den Feldcursor auf den angegebenen Offset. Der nächste Aufruf von mysql_fetch_field() ruf die Felddefinition der Spalte ab, die mit diesem Offset verknüpft ist.

Um bis zum Anfang einer Zeile zu suchen, geben Sie einen offset-Wert von 0 an.

Rückgabewerte

Der vorherige Wert des Feldcursors.

Fehler

Keine.

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

Beschreibung

Gibt die Position des Feldcursors für die letzte mysql_fetch_field() zurück. Dieser Wert kann als Argument für mysql_field_seek() benutzt werden.

Rückgabewerte

Der aktuelle Offset des Feldcursors.

Fehler

Keine.

void mysql_free_result(MYSQL_RES *result)

Beschreibung

Gibt den Speicher frei, der für eine Ergebnismenge von mysql_store_result(), mysql_use_result(), mysql_list_dbs() usw. zugewiesen wurde. Wenn Sie mit einer Ergebnismenge fertig sind, müssen Sie den von ihr benutzten Speicher durch Aufruf von mysql_free_result() freigeben.

Rückgabewerte

Keine.

Fehler

Keine.

char *mysql_get_client_info(void)

Beschreibung

Returns a string that represents the client Bibliothek version.

Rückgabewerte

A character string that represents the MySQL-Client Bibliothek version.

Fehler

Keine.

char *mysql_get_host_info(MYSQL *mysql)

Beschreibung

Gibt eine Zeichenkette zurück, die den Typ der benutzten Verbindung beschreibt, inklusive des Server-Hostnamens.

Rückgabewerte

Eine Zeichenkette, die den Server-Hostnamen und den Verbindungstyp bezeichnet.

Fehler

Keine.

unsigned int mysql_get_proto_info(MYSQL *mysql)

Beschreibung

Gibt die Protokollversion zurück, die von der aktuellen Verbindung benutzt wird.

Rückgabewerte

Eine vorzeichenlose Ganzzahl, die die Protokollversion bezeichnet, die von der aktuellen Verbindung benutzt wird.

Fehler

Keine.

char *mysql_get_server_info(MYSQL *mysql)

Beschreibung

Gibt eine Zeichenkette zurück, die die Server-Versionsnummer bezeichnet.

Rückgabewerte

Eine Zeichenkette, die die Server-Versionsnummer bezeichnet.

Fehler

Keine.

char *mysql_info(MYSQL *mysql)

Beschreibung

Ruft eine Zeichenkette ab, die Informationen über die zuletzt ausgeführte Anfrage zurückgibt, aber nur für die unten aufgeführten Statements. Bei anderen Statements gibt mysql_info() NULL zurück. Das Format der Zeichenkette variiert in Abhängigkeit vom Anfragetyp, wie unten beschrieben. Die Nummern dienen nur der Veranschaulichung; die Zeichenkette enthält die der Anfrage entsprechenden Werte.

Beachten Sie, dass mysql_info() einen Nicht-NULL-Wert für das INSERT ... VALUES-Statement nur dann zurückgibt, wenn im Statement mehrfache Wertlisten angegeben sind.

Rückgabewerte

Eine Zeichenkette, die zusätzliche Informationen über die zuletzt ausgeführte Anfrage bereitstellt. NULL, wenn für die Anfrage keine Information verfügbar ist.

Fehler

Keine.

MYSQL *mysql_init(MYSQL *mysql)

Beschreibung

Alloziert oder initialisiert ein MYSQL-Objekt, das für mysql_real_connect() geeignet ist. Wenn mysql ein NULL-Zeiger ist, alloziert, initialisiert und gibt diese Funktion ein neues Objekt zurück. Ansonsten wird das Objekt initialisiert und die Adresse des Objekts zurückgegeben. Wenn mysql_init() ein neues Objekt alloziert, wird es freigegeben, wenn mysql_close() aufgerufen wird, um die Verbindung zu schließen.

Rückgabewerte

Ein initialisiertes MYSQL*-Handle. NULL, wenn der Speicher nicht ausreichte, um ein neues Objekt zu allozieren.

Fehler

Im Falle von ungenügendem Speicher wird NULL zurückgegeben.

my_ulonglong mysql_insert_id(MYSQL *mysql)

Beschreibung

Gibt die Kennung zurück, die für eine AUTO_INCREMENT-Spalte durch die vorherige Anfrage erzeugt wurde. Benutzen Sie diese Funktion, nachdem Sie eine INSERT-Anfrage für eine Tabelle durchgeführt haben, die ein AUTO_INCREMENT-Feld enthält.

Beachten Sie, dass mysql_insert_id() 0 zurückgibt, wenn die vorherige Anfrage keinen AUTO_INCREMENT-Wert erzeugt hat. Wenn Sie den Wert für spätere Benutzung speichern wollen, stellen Sie sicher, dass Sie mysql_insert_id() unmittelbar nach der Anfrage aufrufen, die den Wert erzeugt.

mysql_insert_id() wird nach INSERT- und UPDATE-Statements aktualisiert, die einen AUTO_INCREMENT-Wert erzeugen oder einen Spaltenwert auf LAST_INSERT_ID(ausdruck) setzen. See Abschnitt 7.3.5.2, „Verschiedene Funktionen“.

Beachten Sie auch, dass der Wert der SQL-LAST_INSERT_ID()-Funktion immer den aktuellsten erzeugten AUTO_INCREMENT-Wert enthält, und zwischen Anfragen nicht zurückgesetzt wird, weil der Wert dieser Funktion im Server gewartet wird.

Rückgabewerte

Der Wert des AUTO_INCREMENT-Felds, das durch die vorherige Anfrage aktualisiert wurde. Gibt 0 zurück, wenn es keine vorherige Anfrage auf der Verbindung gab oder wenn die Anfrage keinen AUTO_INCREMENT-Wert aktualisierte.

Fehler

Keine.

int mysql_kill(MYSQL *mysql, unsigned long pid)

Beschreibung

Bittet den Server, den Thread zu töten, der durch pid angegeben wurde.

Rückgabewerte

0 für Erfolg. Nicht-0, wenn ein Fehler auftrat.

Fehler

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

Beschreibung

Gibt eine Ergebnismenge zurück, die aus den Datenbanknamen auf dem Server besteht, die mit dem einfachen regulären Ausdruck übereinstimmen, der durch den wild-Parameter angegeben wird. wild darf die Platzhalterzeichen ‘%’ oder ‘_’ enthalten oder ein NULL-Zeiger sein, der mit allen Datenbanken übereinstimmt. Der Aufruf von mysql_list_dbs() ist ähnlich der Ausführung der Anfrage SHOW DATABASES [LIKE wild].

Sie müssen die Ergebnismenge mit mysql_free_result() freigeben.

Rückgabewerte

Eine MYSQL_RES-Ergebnismenge bei Erfolg. NULL, wenn ein Fehler auftrat.

Fehler

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

Beschreibung

Gibt eine Ergebnismenge zurück, die aus Feldnamen in der angegebenen Tabelle bestehen, die mit einem einfachen regulären Ausdruck übereinstimmen, der durch den wild-Parameter angegeben wird. wild darf die Platzhalterzeichen ‘%’ oder ‘_’ enthalten oder ein NULL-Zeiger sein, der mit allen Datenbanken übereinstimmt. Der Aufruf von mysql_list_fields() ist ähnlich der Ausführung der Anfrage SHOW COLUMNS FROM tabelle [LIKE wild].

Beachten Sie, dass empfohlen wird, SHOW COLUMNS FROM tabelle statt mysql_list_fields() zu benutzen.

Sie müssen die Ergebnismenge mit mysql_free_result() freigeben.

Rückgabewerte

Eine MYSQL_RES-Ergebnismenge bei Erfolg. NULL, wenn ein Fehler auftrat.

Fehler

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

Beschreibung

Gibt eine Ergebnismenge zurück, die die aktuellen Server-Threads beschreibt. Das ist dieselbe Art von Information, die von mysqladmin processlist oder einer SHOW PROCESSLIST-Anfrage zur Verfügung gestellt wird.

Sie müssen die Ergebnismenge mit mysql_free_result() freigeben.

Rückgabewerte

Eine MYSQL_RES-Ergebnismenge bei Erfolg. NULL, wenn ein Fehler auftrat.

Fehler

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

Beschreibung

Gibt eine Ergebnismenge zurück, die aus Tabellennamen in der aktuellen Datenbank besteht, die mit einem einfachen regulären Ausdruck übereinstimmen, der durch den wild-Parameter angegeben wird. wild darf die Platzhalterzeichen ‘%’ oder ‘_’ enthalten oder ein NULL-Zeiger sein, der mit allen Tabellen übereinstimmt. Der Aufruf von mysql_list_tables() ist ähnlich der Ausführung der Anfrage SHOW tables [LIKE wild].

Sie müssen die Ergebnismenge mit mysql_free_result() freigeben.

Rückgabewerte

Eine MYSQL_RES-Ergebnismenge bei Erfolg. NULL, wenn ein Fehler auftrat.

Fehler

unsigned int mysql_num_fields(MYSQL_RES *result)

oder

unsigned int mysql_num_fields(MYSQL *mysql)

Die zweite Form funktioniert nicht bei MySQL-Version 3.22.24 oder neuer. Um ein MYSQL*-Argument zu übergeben, müssen Sie statt dessen unsigned int mysql_field_count(MYSQL *mysql) benutzen.

Beschreibung

Gibt die Anzahl von Spalten in einer Ergebnismenge zurück.

Beachten Sie, dass Sie die Anzahl von Spalten entweder durch einen Zeiger auf die Ergebnismenge oder auf ein Verbindungs-Handle erhalten. Das Verbindungs-Handle benutzen Sie, wenn mysql_store_result() oder mysql_use_result() NULL zurückgibt (und Sie daher keinen Ergebnismengen-Zeiger haben). In diesem Fall können Sie mysql_field_count() aufrufen, um festzustellen, ob mysql_store_result() eine leere Ergebnismenge produziert haben sollte oder nicht. Das erlaubt dem Client-Programm, die korrekten Aktionen vorzunehmen, ohne wissen zu müssen, ob die Anfrage ein SELECT- (oder SELECT-ähnliches) Statement war oder nicht. Das unten stehende Beispiel zeigt, wie das gemacht wird.

See Abschnitt 9.4.6.1, „Warum gibt mysql_store_result() manchmal NULL zurück, nachdem mysql_query() Erfolg zurückgegeben hat?“.

Rückgabewerte

Eine vorzeichenlose Ganzzahl, die die Anzahl von Feldern in einer Ergebnismenge darstellt.

Fehler

Keine.

Beispiel

MYSQL_RES *ergebnis;
unsigned int anzahl_felder;
unsigned int anzahl_zeilen;

if (mysql_query(&mysql,anfrage_zeichenkette))
{
    // FEHLER
}
else // Anfrage erfolgreich, zurückgegebene Daten verarbeiten
{
    ergebnis = mysql_store_result(&mysql);
    if (ergebnis)  // Es gibt Zeilen
    {
        anzahl_felder = mysql_num_fields(ergebnis);
        // Zeilen abrufen, dann mysql_free_result(ergebnis) aufrufen
    }
    else  // mysql_store_result() gab nichts zurück, hätte es das tun sollen?
    {
        if (mysql_errno(&mysql))
	{
           fprintf(stderr, "Fehler: %s\n", mysql_error(&mysql));
	}
        else if (mysql_field_count(&mysql) == 0)
        {
            // Anfrage gibt keine Daten zurück
            // (war kein SELECT)
            anzahl_zeilen = mysql_affected_rows(&mysql);
        }
    }
}

Eine Alternative (wenn Sie WISSEN, dass Ihre Anfrage eine Ergebnismenge hätte zurückgeben sollen) ist es, den mysql_errno(&mysql)-Aufruf durch eine Prüfung zu ersetzen, ob mysql_field_count(&mysql) gleich 0 ist. Das passiert nur, wenn etwas schief lief.

my_ulonglong mysql_num_rows(MYSQL_RES *result)

Beschreibung

Gibt die Anzahl von Zeilen in der Ergebnismenge zurück.

Die Benutzung von mysql_num_rows() hängt davon ab, ob Sie mysql_store_result() oder mysql_use_result() benutzen, um die Ergebnismenge zurückzugeben.. Wenn Sie mysql_store_result() benutzen, kann mysql_num_rows() unmittelbar aufgerufen werden. Wenn Sie mysql_use_result() benutzen, gibt mysql_num_rows() nicht den richtigen Wert zurück, bis alle Zeilen in der Ergebnismenge abgerufen wurden.

Rückgabewerte

Die Anzahl von Zeilen in der Ergebnismenge.

Fehler

Keine.

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

Beschreibung

Kann benutzt werden, um zusätzliche Optionen zu setzen und das Verhalten einer Verbindung zu beeinflussen. Diese Funktion kann mehrfach aufgerufen werden, um mehrere Optionen zu setzen.

mysql_options() sollte nach mysql_init() und vor mysql_connect() oder mysql_real_connect() aufgerufen werden.

Das option-Argument ist die Option, die Sie setzen wollen. Das arg-Argument ist der Wert für die Option. Wenn die Option eine Ganzzahl ist, sollte arg auf den Wert der Ganzzahl zeigen.

Mögliche Optionswerte:

Beachten Sie, dass die Gruppe client immer gelesen wird, wenn Sie MYSQL_READ_DEFAULT_FILE oder MYSQL_READ_DEFAULT_GROUP benutzen.

Die angegebene Gruppe in der Optionsdatei kann folgende Optionen enthalten:

Beachten Sie, dass timeout durch connect_timeout ersetzt wurde. Dennoch wird timeout noch für eine Weile funktionieren.

Weitere Informationen über Optionsdateien finden Sie unter Abschnitt 5.1.2, „my.cnf-Optionsdateien“.

Rückgabewerte

0 bei Erfolg. Nicht-0, wenn Sie eine unbekannte Option verwenden.

Beispiel

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","benutzer","passwort","datenbank",0,NULL,0))
{
    fprintf(stderr, "Keine Verbindung zur Datenbank: Fehler: %s\n",
          mysql_error(&mysql));
}

Im obigen Beispiel wird der Client angewiesen, das komprimierte Client-/Server-Protokoll zu benutzen und zusätzliche Optionen aus dem odbc-Abschnitt in my.cnf zu lesen.

int mysql_ping(MYSQL *mysql)

Beschreibung

Prüft, ob die Verbindung zum Server funktioniert oder nicht. Wenn diese weg ist, wird automatisch eine erneute Verbindung versucht.

Diese Funktion kann von Clients benutzt werden, die für lange Zeit im Leerlauf laufen, um zu prüfen, ob der Server die Verbindung geschlossen hat, und sich bei Bedarf erneut zu verbinden.

Rückgabewerte

0, wenn der Server da ist. Nicht-0, wenn ein Fehler auftrat.

Fehler

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

Beschreibung

Führt die SQL-Anfrage aus, auf die durch die NULL-begrenzte Zeichenkette anfrage gezeigt wird. Die Anfrage muss aus einem einzelnen SQL-Statement bestehen. Sie dürfen kein Semikolon (‘;’) oder \g zum Statement hinzufügen.

mysql_query() kann nicht für Anfragen benutzt werden, die Binärdaten enthalten. Hierfür sollten Sie statt dessen mysql_real_query() benutzen. (Binärdaten können das ‘\0’-Zeichen enthalten, was mysql_query() als Ende der Anfrage-Zeichenkette interpretiert.)

Wenn Sie wissen wollen, ob die Anfrage eine Ergebnismenge zurückgeben sollte oder nicht, können Sie mysql_field_count() benutzen, um hierauf zu prüfen. See Abschnitt 9.4.3.20, „mysql_field_count()“.

Rückgabewerte

0, wenn die Anfrage erfolgreich war. Nicht-0, wenn ein Fehler auftrat.

Fehler

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)

Beschreibung

mysql_real_connect() versucht, eine Verbindung zu einer MySQL-Datenbankmaschine aufzubauen, die auf host läuft. mysql_real_connect() muss erfolgreich verlaufen sein, bevor Sie irgend eine andere API-Funktion ausführen können, mit Ausnahme von mysql_get_client_info().

Die Parameter werden wie folgt angegeben:

Rückgabewerte

Ein MYSQL*-Verbindungs-Handle, wenn die Verbindung erfolgreich war, NULL, wenn die Verbindung nicht erfolgreich war. Bei einer erfolgreichen Verbindung ist der Rückgabewert derselbe wie der Wert des ersten Parameters, es sei denn, Sie übergeben für diesen Parameter NULL.

Fehler

Beispiel

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","benutzer","passwort","datenbank",0,NULL,0))
{
    fprintf(stderr, "Verbindung zur Datenbank fehlgeschlagen: Fehler: %s\n",
          mysql_error(&mysql));
}

Wenn Sie mysql_options() benutzen, liest die MySQL-Bibliothek die [client]- und ihr_programm_name-Abschnitte in der my.cnf-Datei. Das stellt sicher, dass Ihr Programm funktioniert, selbst wenn jemand MySQL auf Nicht-Standard-Weise eingerichtet hat.

Beachten Sie, dass mysql_real_connect() beim Verbinden den reconnect-Flag (Teil der MySQL-Struktur) auf einen Wert von 1 setzt. Dieser Flag gibt an, dass ein erneuter Verbindungsversuch zum Server gemacht wird, bevor aufgegeben wird, wenn eine Anfrage wegen einer verloren gegangenen Verbindung nicht ausgeführt werden kann.

unsigned int mysql_real_escape_string(MYSQL *mysql, char *nach, const char *von, unsigned int laenge)

Beschreibung

Diese Funktion wird benutzt, um eine zulässige SQL-Zeichenkette zu erzeugen, die Sie in einem SQL-Statement benutzen können. See Abschnitt 7.1.1.1, „Zeichenketten“.

Die Zeichenkette in von wird in eine escapete SQL-Zeichenkette kodiert, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird. Das Ergebnis wird in nach platziert und ein Null-Byte am Ende angefügt. Kodierte Zeichen sind NUL (ASCII 0), ‘\n’, ‘\r’, ‘\’, ‘'’, ‘"’ und Control-Z (see Abschnitt 7.1.1, „Literale: Wie Zeichenketten und Zahlen geschrieben werden“).

Die Zeichenkette, auf die von von gezeigt wird, muss laenge Bytes lang sein. Sie müssen den nach-Puffer so zuweisen, dass er mindestens laenge*2+1 Bytes lang ist. (Im schlimmsten Fall muss jedes Zeichen mit zwei Bytes kodiert werden, und Sie brauchen Platz für das Null-Byte am Ende.) Wenn mysql_escape_string() zurückgibt, sind die Inhalte von nach eine Null-begrenzte Zeichenkette. Der Rückgabewert ist die Länge der kodierten Zeichenkette, ohne das Null-Zeichen am Ende.

Beispiel

char anfrage[1000],*end;

end = strmov(anfrage,"INSERT INTO tabelle values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"Was is'n das?",12);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"Binärdaten: \0\r\n",17);
*end++ = '\'';
*end++ = ')';

if (mysql_real_query(&mysql,anfrage,(unsigned int) (end - anfrage)))
{
   fprintf(stderr, "Einfügen der Zeile fehlgeschlagen, Fehler: %s\n",
           mysql_error(&mysql));
}

Die im Beispiel benutzte strmov()-Funktion ist in der mysqlclient-Bibliothek enthalten und funktioniert wie strcpy(), gibt aber einen Zeiger auf Null am Ende des ersten Parameters zurück.

Rückgabewerte

Die Länge des Wertes in nach, ohne das Null-Zeichen am Ende.

Fehler

Keine.

int mysql_real_query(MYSQL *mysql, const char *anfrage, unsigned int laenge)

Beschreibung

Führt die SQL-Anfrage aus, auf die von anfrage gezeigt wird, was eine laenge Bytes lange Zeichenkette sein sollte. Die0 Anfrage muss aus einem einzelnen SQL-Statement bestehen. Sie dürfen kein Semikolon (‘;’) oder \g zum Statement hinzufügen.

Sie müssen mysql_real_query() statt mysql_query() für Anfragen benutzen, die Binärdaten enthalten, weil Binärdaten das ‘\0’-Zeichen enthalten können. Ausserdem ist mysql_real_query() schneller als mysql_query(), weil es in der Anfragezeichenkette nicht strlen() aufruft.

Wenn Sie wissen wollen, ob die Anfrage eine Ergebnismenge zurückgeben sollte oder nicht, können Sie hierfür mysql_field_count() benutzen. See Abschnitt 9.4.3.20, „mysql_field_count()“.

Rückgabewerte

0, wenn die Anfrage erfolgreich war. Nicht-0, wenn ein Fehler auftrat.

Fehler

int mysql_reload(MYSQL *mysql)

Beschreibung

Weist den MySQL-Server an, die Berechtigungstabellen neu zu laden. Der verbundene Benutzer muss die reload-Berechtigung haben.

Diese Funktion ist veraltet. Vorzugsweise sollten Sie mysql_query() benutzen, um statt dessen ein SQL-FLUSH PRIVILEGES-Statement auszuführen.

Rückgabewerte

0 bei Erfolg. Nicht-0, wenn ein Fehler auftrat.

Fehler

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *ergebnis, MYSQL_ROW_OFFSET offset)

Beschreibung

Setzt den Zeilencursor auf eine beliebige Zeile in einer Anfrageergebnismenge. Dafür ist erforderlich, dass die Ergebnismengenstruktur das gesamte Ergebnis der Anfrage enthält, so dass mysql_row_seek() nur in Verbindung mit mysql_store_result() benutzt werden kann, nicht mit mysql_use_result().

Der Offset sollte ein Wert sein, der von einem Aufruf von mysql_row_tell() oder mysql_row_seek() zurückgegeben wird. Dieser Wert ist nicht einfach eine Zeilennummer; wenn Sie eine Zeile innerhalb einer Ergebnismenge mittels einer Zeilennummer suchen wollen, benutzen Sie statt dessen mysql_data_seek().

Rückgabewerte

Der vorherige Wert des Zeilencursors. Dieser Wert kann an einen nachfolgenden Aufruf von mysql_row_seek() übergeben werden.

Fehler

Keine.

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *ergebnis)

Beschreibung

Gibt die aktuelle Position des Zeilencursors für das letzte mysql_fetch_row() zurück. Dieser Wert kann als Argument für mysql_row_seek() benutzt werden.

Sie sollten mysql_row_tell() nur nach mysql_store_result(), nicht nach mysql_use_result() benutzen.

Rückgabewerte

Der aktuelle Offset des Zeilencursors.

Fehler

Keine.

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

Beschreibung

Führt dazu, dass die Datenbank, die durch db angegeben wird, die vorgabemäßige (aktuelle) Datenbank auf der von mysql angegebenen Verbindung wird. Bei nachfolgenden Anfragen ist diese Datenbank die Vorgabe für Tabellenverweise, die nicht explizit einen Datenbank-Spezifizierer enthalten.

mysql_select_db() schlägt fehl, wenn der verbundene Benutzer keine Zugriffsrechte auf die Datenbank hat.

Rückgabewerte

0 bei Erfolg. Nicht-0, wenn ein Fehler auftrat.

Fehler

int mysql_shutdown(MYSQL *mysql)

Beschreibung

Führt dazu, dass der Datenbankserver herunter fährt. Der verbundene Benutzer muss die shutdown-Berechtigung haben.

Rückgabewerte

0 bei Erfolg. Nicht-0, wenn ein Fehler auftrat.

Fehler

char *mysql_stat(MYSQL *mysql)

Beschreibung

Gibt eine Zeichenkette zurück, die Informationen enthält, die ähnlich denen sind, die vom mysqladmin status-Befehl zur Verfügung gestellt werden. Das schließt die Betriebszeit (Uptime) in Sekunden und die Anzahl laufender Threads, Anfragen (Questions), Neuladen (Reloads) und offener Tabellen ein.

Rückgabewerte

Eine Zeichenkette, die den Serverstatus beschreibt. NULL, wenn ein Fehler auftrat.

Fehler

MYSQL_RES *mysql_store_result(MYSQL *mysql)

Beschreibung

Sie müssen mysql_store_result() oder mysql_use_result() für jede Anfrage aufrufen, die erfolgreich Daten abruft (SELECT, SHOW, DESCRIBE, EXPLAIN).

Für andere Anfragen müssen Sie mysql_store_result() oder mysql_use_result() nicht aufrufen, es schadet aber auch nicht, noch führt es zu wahrnehmbaren Performance-Störungen, wenn Sie mysql_store_result() in jedem Fall aufrufen. Sie können feststellen, ob die Anfrage keine Ergebnismenge hatte, wenn Sie prüfen, ob mysql_store_result() 0 zurückgibt (mehr darüber später).

Wenn Sie wissen wollen, ob die Anfrage eine Ergebnismenge zurückgeben sollte oder nicht, können Sie hierfür mysql_field_count() benutzen. See Abschnitt 9.4.3.20, „mysql_field_count()“.

mysql_store_result() liest das gesamte Ergebnis einer Anfrage zum Client ein, weist eine MYSQL_RES-Struktur zu und platziert das Ergebnis in diese Struktur.

mysql_store_results() gibt einen NULL-Zeiger zurück, wenn die Anfrage keine Ergebnismenge zurückgab (wenn die Anfrage zum Beispiel ein INSERT-Statement war).

mysql_store_results() gibt auch einen NULL-Zeiger zurück, wenn das Lesen der Ergebnismenge fehlschlug. Sie können prüfen, ob Sie einen Fehler erhielten, wenn mysql_error() keinen NULL-Zeiger zurückgibt, wenn mysql_errno() ungleich 0 zurückgibt oder wenn mysql_field_count() ungleich 0 zurückgibt.

Eine leere Ergebnismenge wird zurückgegeben, wenn keine Zeilen zurückgegeben werden. (Eine leere Ergebnismenge unterscheidet sich als Rückgabewert von einem NULL-Zeiger.)

Nachdem Sie erst einmal mysql_store_result() aufgerufen und ein Ergebnis erhalten haben, das kein NULL-Zeiger ist, können Sie mysql_num_rows() aufrufen, um herauszufinden, wie viele Zeilen es in der Ergebnismenge gibt.

Sie können mysql_fetch_row() aufrufen, um Zeilen aus der Ergebnismenge zu holen, oder mysql_row_seek() und mysql_row_tell(), um die aktuelle Zeilenposition innerhalb der Ergebnismenge zu erhalten oder zu setzen.

Sie müssen mysql_free_result() aufrufen, wenn Sie mit der Ergebnismenge fertig sind.

See Abschnitt 9.4.6.1, „Warum gibt mysql_store_result() manchmal NULL zurück, nachdem mysql_query() Erfolg zurückgegeben hat?“.

Rückgabewerte

Eine MYSQL_RES-Ergebnisstruktur mit den Ergebnissen. NULL, wenn ein Fehler auftrat.

Fehler

unsigned long mysql_thread_id(MYSQL *mysql)

Beschreibung

Gibt die Thread-Kennung der aktuellen Verbindung zurück. Der Wert kann als Argument für mysql_kill() benutzt werden, um den Thread zu töten.

Wenn die Verbindung verloren ging und Sie sich mit mysql_ping() erneut verbinden, ändert sich die Thread-Kennung. Das heißt, dass Sie nicht die Thread-Kennung holen und für spätere Benutzung speichern sollten. Sie sollten sie holen, wenn Sie sie benötigen.

Rückgabewerte

Die Thread-Kennung der aktuellen Verbindung.

Fehler

Keine.

MYSQL_RES *mysql_use_result(MYSQL *mysql)

Beschreibung

Sie müssen mysql_store_result() oder mysql_use_result() für jede Anfrage aufrufen, die erfolgreich Daten abruft (SELECT, SHOW, DESCRIBE, EXPLAIN).

mysql_use_result() initiiert einen Ergebnismengen-Abruf, aber liest die Ergebnismenge nicht tatsächlich in den Client wie mysql_store_result(). Statt dessen muss jede Zeile individuell abgerufen werden, indem Aufrufe von mysql_fetch_row() durchgeführt werden. Das liest das Ergebnis einer Anfrage direkt vom Server, ohne es in einer temporären Tabelle oder einem lokalen Puffer zu speichern, was manchmal schneller ist und viel weniger Speicher benutzt als mysql_store_result(). Dem Client wird nur Speicher für die aktuelle Zeile zugewiesen sowie ein Kommunikationspuffer, der bis zu max_allowed_packet Bytes Groß werden kann.

Auf der anderen Seite sollten Sie mysql_use_result() nicht benutzen, wenn Sie viele Verarbeitungen für jede Zeile auf der Client-Seite durchführen oder wenn die Ausgabe auf den Bildschirm geschickt wird, auf dem der Benutzer ^S (stop scroll) eingeben kann. Das bindet den Server und verhindert, dass andere Threads irgend welche Tabellen aktualisieren können, von denen gerade Daten geholt werden.

Wenn Sie mysql_use_result() benutzen, müssen Sie mysql_fetch_row() ausführen, bis ein NULL-Wert zurückgegeben wird, denn ansonsten werden die nicht geholten Zeilen als Teil der Ergebnismenge bei Ihrer nächsten Anfrage zurückgegeben. Die C-API gibt den Fehler Commands out of sync; You can't run this command now aus, wenn Sie das vergessen!

Sie können mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_rows() oder mysql_affected_rows() nicht bei einem Ergebnis verwenden, das von mysql_use_result() zurückgegeben wird. Ausserdem dürfen Sie keine anderen Anfragen absetzen, bis mysql_use_result() beendet ist. (Nachdem Sie alle Zeilen abgeholt haben, wird mysql_num_rows() jedoch exakt die Anzahl der geholten Zeilen zurückgeben.)

Sie müssen mysql_free_result() aufrufen, wenn Sie mit der Ergebnismenge fertig sind.

Rückgabewerte

Eine MYSQL_RES-Ergebnisstruktur. NULL, wenn ein Fehler auftrat.

Fehler

Beschreibung

Diese Funktion muss einmal im Programm aufgerufen werden, bevor Sie irgend eine MySQL-Funktion aufrufen. Sie initialisiert einige globale Variablen, die MySQL braucht. Wenn Sie eine Thread-sichere Client-Bibliothek benutzen, wird diese ebenfalls mysql_thread_init() für diesen Thread aufrufen.

Diese Funktion wird automatisch von mysql_init(), mysql_server_init() und mysql_connect() aufgerufen.

Rückgabewerte

Keine.

Beschreibung

Diese Funktion muss für jeden erzeugten Thread aufgerufen werden, um Thread-spezifische Variablen zu initialisieren.

Diese Funktion wird automatisch von my_init() und mysql_connect() aufgerufen.

Rückgabewerte

Keine.

Beschreibung

Diese Funktion muss vor dem Aufruf von pthread_exit() aufgerufen werden, um den von mysql_thread_init() zugewiesenen Speicher freizusetzen.

Beachten Sie, dass diese Funktion nicht automatisch von der Client-Bibliothek aufgerufen wird. Sie muss explizit aufgerufen werden, um Speicherlecks zu vermeiden.

Rückgabewerte

Keine.

unsigned int mysql_thread_safe(void)

Description

This function indicates whether the client is compiled as thread safe.

Return Values

1 is the client is thread safe, 0 otherwise.

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

Beschreibung

Diese Funktion muss einmal im Programm aufgerufen werden, bevor irgend eine andere MySQL-Funktion aufgerufen wird. Sie startet den Server und initialisiert jegliche Subsysteme (mysys, InnoDB usw.), die der Server benutzt. Wenn diese Funktion nicht aufgerufen wird, stürzt das Programm ab.

Die argc- und argv-Argumente sind analog zu den Argumenten für main(). Das erste Element von argv wird ignoriert (es enthält typischerweise den Programmnamen). Aus Bequemlichkeitsgründen kann argc 0 sein, wenn es keine Kommandozeilenargumente für den Server gibt.

Die NULL-begrenzte Liste von Zeichenketten in groups wählt aus, welche Gruppen in den Optionsdateien aktiv sind. See Abschnitt 5.1.2, „my.cnf-Optionsdateien“. Aus Bequemlichkeitsgründen kann groups NULL sein. In diesem Fall ist die [server]-Gruppe aktiv.

Beispiel

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

static char *server_args[] = {
  "Mein Programm",       /* Diese Zeichenkette ist unbenutzt */
  "--datadir=.",
  "--set-variable=key_buffer_size=32M"
};
static char *server_groups[] = {
  "server",
  "Dieser_Programm_SERVER",
  (char *)NULL
};

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

  /* Hier können Sie irgend welche MySQL-API-Funktionen benutzen */

  mysql_server_end();

  return EXIT_SUCCESS;
}

Rückgabewerte

Keine.

Beschreibung

Diese Funktion muss einmal im Programm nach allen anderen MySQL-Funktionen aufgerufen werden. Sie fährt den eingebetteten Server herunter.

Rückgabewerte

Keine.

mysql_store_result() kann NULL zurückgeben, auch nach einem erfolgreichen Aufruf von mysql_query(). Wenn das passiert, bedeutet das, dass eine der folgenden Bedingungen eingetreten ist:

Sie können jederzeit prüfen, ob das Statement eine leere Ergebnismenge geliefert haben sollte oder nicht, indem Sie mysql_field_count() aufrufen. Wenn mysql_field_count() 0 zurückliefert, ist das Ergebnis leer und die letzte Anfrage war ein Statement, die keine Rückgabewerte liefert (zum Beispiel ein INSERT oder ein DELETE). Wenn mysql_field_count() einen Nicht-0-Wert zurückgibt, hätte das Statement ein nicht leeres Ergebnis zurückliefern sollen. Sehen Sie in der Beschreibung von mysql_field_count()-Funktion wegen eines Beispiels nach.

Sie können durch Aufruf von mysql_error() oder mysql_errno() auf einen Fehler überprüfen.

Zusätzlich zur Ergebnismenge, die von einer Anfrage zurückgegeben wird, können Sie auch folgende Informationen bekommen:

Wenn Sie einen Datensatz in eine Tabelle einfügen, der eine Spalte enthält, die das AUTO_INCREMENT-Attribut hat, erhalten Sie die letzte erzeugte Kennung durch Aufruf der mysql_insert_id()-Funktion.

Sie können die Kennung auch dadurch abrufen, dass Sie die LAST_INSERT_ID()-Funktion in einer Anfrage-Zeichenkette verwenden, die Sie an mysql_query() übergeben.

Sie können überprüfen, ob ein AUTO_INCREMENT-Index benutzt wird, wenn Sie folgenden Code ausführen. Er prüft auch, ob die Anfrage ein INSERT mit einem AUTO_INCREMENT-Index war:

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

Die letzte erzeugte Kennung wird im Server auf der Grundlage der jeweiligen Verbindung gewartet. Sie wird nicht durch andere Clients geändert. Sie wird nicht einmal geändert, wenn Sie eine andere AUTO_INCREMENT-Spalte mit einem nicht magischen Wert aktualisieren (einem Wert, der nicht NULL und nicht 0 ist).

Wenn Sie die Kennung benutzen wollen, die für eine Tabelle erzeugt wurde, um sie in eine zweite Tabelle einzufügen, können Sie SQL-Statements wie folgt benutzen:

INSERT INTO foo (auto,text)
    VALUES(NULL,'text');              # Kennung durch Einfügen von NULL erzeugen
INSERT INTO foo2 (id,text)
    VALUES(LAST_INSERT_ID(),'text');  # Kennung in zweiter Tabelle benutzen

Wenn Sie mit der C-API linken, können auf manchen Systemen folgende Fehler auftreten:

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

Wenn das auf Ihrem System passiert, müssen Sie die math-Bibliothek einschließen, indem Sie -lm am Ende der Kompilier- / Link-Zeile hinzufügen.

Die eingebettete MySQL-Server-Bibliothek ermöglicht es, einen MySQL-Server mit allen Features innerhalb einer Client-Applikation laufen zu lassen. Die hauptsächlichen Vorteile sind erhöhte Geschwindigkeit und einfachere Verwaltung eingebetteter Applikationen.

Momentan müssen alle unterstützten Bibliotheken explizit aufgelistet werden, wenn Sie mit -lmysqld linken. In Zukunft wird mysql_config --libmysqld-libs die Bibliotheken benennen, um das zu erleichtern. Darüber hinaus werden alle unterstützten Bibliotheken wahrscheinlich in libmysqld eingeschlossen werden, um dies noch weiter zu vereinfachen.

Die korrekten Flags zum Kompilieren und Linken eines threaded Programms müssen benutzt werden, selbst wenn Sie nicht direkt irgend welche Thread-Funktionen in Ihrem Code aufrufen.

Dieses Beispiel-Programm und makefile sollten ohne Änderungen auf einem Linux- oder FreeBSD-System funktionieren. Bei anderen Betriebssystemen sind kleinere Änderungen notwendig. Dieses Beispiel ist so angelegt, dass genügend Details dargestellt werden, um die Problematik zu verstehen, ohne zu viel "Verwirrendes" einzubringen, das Teil einer echten Applikation ist.

Um das Beispiel auszuprobieren, erzeugen Sie ein example-Verzeichnis auf derselben Ebene wie das mysql-4.0-Quell-Verzeichnis. Speichern Sie die example.c-Quelle und das GNUmakefile im Verzeichnis und lassen Sie GNU-make innerhalb des example-Verzeichnisses laufen.

example.c

/*
 * Ein einfacher Beispiel-Client, der die eingebettete
 * MySQL-Server-Bibliothek benutzt
 */

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

enum on_error { E_okay, E_warn, E_fail };

static void   die(MYSQL *db, char *fmt, ...);
MYSQL *db_connect(const char *dbname);
void db_disconnect(MYSQL *db);
void db_do_Anfrage(MYSQL *db, const char *query, enum on_error on_error);

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

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

  /* Das muss vor allen weiteren mysql-Funktionen aufgerufen werden.
   *
   * Sie können mysql_server_init(0, NULL, NULL) benutzen, 
   * was den Server initialisiert und die Gruppen
   * groups = { "server", NULL } benutzt.
   *
   * In Ihre $HOME/.my.cnf-Datei sollten Sie folgendes eintragen:

[test_client_SERVER]
language = /pfad/zur/quelle/von/mysql/sql/share/english

   * Natürlich können Sie auch argc und argv ändern,
   * bevor Sie sie an diese Funktion übergeben.
   * Oder erzeugen Sie neue auf jede Art, die Sie wollen.
   * Alle Argumente in argv (ausser argv[0], was der Programmname ist)
   * müssen allerdings gültige Optionen für den MySQL-Server sein.
   * Wenn Sie diesen Client gegen die normale mysqlclient-
   * Bibliothek linken, ist diese Funktion nur ein Stumpf, der nichts tut.
   */
  mysql_server_init(argc, argv, server_groups);

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

  db_do_query(one, "show table status", E_fail);
  db_do_query(two, "show databases", E_fail);

  mysql_close(two);
  mysql_close(one);

  /* Folgendes muss nach allen anderen mysql-Funktionen aufgerufen werden */
  mysql_server_end();

  exit(EXIT_SUCCESS);
}

void
die(MYSQL *db, char *fmt, ...)
{
  va_list ap;
  va_start(ap, fmt);
  vfprintf(stderr, fmt, ap);
  va_end(ap);
  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 fehlgeschlagen: kein Speicher mehr");
  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "simple");
  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
    die(db, "mysql_real_connect fehlgeschlagen: %s", mysql_error(db));

  return db;
}

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

/*
 * show_query: Dieser Code ist aus mysql.cc. Diese Funktion
 * ist dafür gedacht, intern für db_do_query() benutzt zu werden.
 */
static char *
show_query(MYSQL *db)
{
  MYSQL_RES   *res;
  MYSQL_FIELD *field;
  MYSQL_ROW    row;
  char         sep[256], *psep = sep;
  char        *is_num = 0;
  char        *err = 0;
  unsigned int length = 1;      /* anfangs "|" */
  unsigned int off;

  if (!(res = mysql_store_result(db)))
    return mysql_error(db);

  if (!(is_num = malloc(mysql_num_fields(res))))
  {
    err = "Kein Speicher mehr";
    goto err;
  }

  /* set up */
  *psep++ = '+';
  while ((field = mysql_fetch_field(res)))
  {
    unsigned int len = strlen(field->name);
    if (len < field->max_length)
      len = field->max_length;
    if (len < 2 && !IS_NOT_NULL(field->flags))
      len = 2;  /* \N */
    field->max_length = len + 1;        /* die API verbiegen ... */
    len += 2; length += len + 1;        /* " " davor, " |" danach */
    if (length >= 255)
    {
      err = "Zeile zu lang";
      goto err;
    }
    memset(psep, '-', len); psep += len;
    *psep++ = '+';
    *psep   = '\0';
  }

  /* Spaltenüberschriften */
  puts(sep);
  mysql_field_seek(res,0);
  fputc('|',stdout);
  für (off=0; (field = mysql_fetch_field(res)) ; off++)
  {
    printf(" %-*s|",field->max_length, field->name);
    is_num[off]= IS_NUM(field->type);
  }
  fputc('\n',stdout);
  puts(sep);

  /* Zeilen */
  while ((row = mysql_fetch_row(res)))
  {
    (void) fputs("|",stdout);
    mysql_field_seek(res,0);
    for (off=0 ; off < mysql_num_fields(res); off++)
    {
      field = mysql_fetch_field(res);
      printf(is_num[off] ? "%*s |" : " %-*s|",
             field->max_length, row[off] ? (char*) row[off] : "NULL");
    }
    (void) fputc('\n',stdout);
  }
  puts(sep);

err:
  if (is_num)
    free(is_num);
  mysql_free_result(res);

  return err;
}

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

  if (mysql_field_count(db) > 0)
  {
    if ((err = show_query(db)))
      goto err;
  }
  else if (mysql_affected_rows(db))
    printf("Betroffene Zeilen: %lld [%s]\n", mysql_affected_rows(db), query);

  return;

err:
  switch (on_error) {
  case E_okay:
    break;
  case E_warn:
    fprintf(stderr, "db_do_query fehlgeschlagen: %s [%s]\n",
        err ? err : mysql_error(db), query);
    break;
  case E_fail:
    die(db, "db_do_query fehlgeschlagen: %s [%s]",
        err ? err : mysql_error(db), query);
    break;
  }
}

GNUmakefile

# Platzieren Sie diese in Ihr mysql-Quell-Verzeichnis
m        := ../mysql-4.0

CC       := cc
CPPFLAGS := -I$m/include -D_thread_SAFE -D_REENTRANT
CFLAGS   := -g -W -Wall
LDFLAGS  := -static
LDLIBS    = $(embed_libs) -lz -lm -lcrypt

ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null))
# FreeBSD
LDFLAGS += -pThread
else
# Linux wird angenommen
LDLIBS += -lpThread
endif


# Standard-Bibliotheken

embed_libs := \
        $m/libmysqld/.libs/libmysqld.a \
        $m/isam/libnisam.a \
        $m/myisam/libmyisam.a \
        $m/heap/libheap.a \
        $m/merge/libmerge.a \
        $m/myisammrg/libmyisammrg.a


# Optional gebaute Bibliotheken

ifneq (,$(shell test -r $m/innobase/usr/libusr.a && echo "yes"))
embed_libs += \
        $m/innobase/usr/libusr.a \
        $m/innobase/odbc/libodbc.a \
        $m/innobase/srv/libsrv.a \
        $m/innobase/que/libque.a \
        $m/innobase/srv/libsrv.a \
        $m/innobase/dict/libdict.a \
        $m/innobase/ibuf/libibuf.a \
        $m/innobase/row/librow.a \
        $m/innobase/pars/libpars.a \
        $m/innobase/btr/libbtr.a \
        $m/innobase/trx/libtrx.a \
        $m/innobase/read/libread.a \
        $m/innobase/usr/libusr.a \
        $m/innobase/buf/libbuf.a \
        $m/innobase/ibuf/libibuf.a \
        $m/innobase/eval/libeval.a \
        $m/innobase/log/liblog.a \
        $m/innobase/fsp/libfsp.a \
        $m/innobase/fut/libfut.a \
        $m/innobase/fil/libfil.a \
        $m/innobase/lock/liblock.a \
        $m/innobase/mtr/libmtr.a \
        $m/innobase/page/libpage.a \
        $m/innobase/rem/librem.a \
        $m/innobase/thr/libthr.a \
        $m/innobase/com/libcom.a \
        $m/innobase/sync/libsync.a \
        $m/innobase/data/libdata.a \
        $m/innobase/mach/libmach.a \
        $m/innobase/ha/libha.a \
        $m/innobase/dyn/libdyn.a \
        $m/innobase/mem/libmem.a \
        $m/innobase/sync/libsync.a \
        $m/innobase/ut/libut.a \
        $m/innobase/os/libos.a \
        $m/innobase/ut/libut.a
endif

ifneq (,$(shell test -r $m/bdb/build_unix/libdb.a && echo "yes"))
embed_libs += $m/bdb/build_unix/libdb.a
endif


# Unterstützte Bibliotheken

embed_libs += \
        $m/mysys/libmysys.a \
        $m/strings/libmystrings.a \
        $m/dbug/libdbug.a \
        $m/regex/libregex.a


# Optional gebaute unterstützte Bibliotheken

ifneq (,$(shell test -r $m/readline/libreadline.a && echo "yes"))
embed_libs += $m/readline/libreadline.a
endif

# Das funktioniert bei einfachen Ein-Datei-Test-Programmen
sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
targets := $(basename $(sources))

all: $(targets)

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

Der MySQL-Quelltext wird von der GNU-GPL-Lizenz abgedeckt (see Anhang G, GNU GENERAL PUBLIC LICENSE). Eine Folge davon ist, dass jegliches Programm, das durch Linken mit libmysqld den MySQL-Quelltext enthält, als freie Software (unter einer mit der GPL kompatiblen Lizenz) veröffentlicht werden muss.

Wir ermutigen jeden, freie Software durch Veröffentlichung von Code unter der GPL oder einer kompatiblen Lizenz zu fördern. Für diejenigen, die dazu nicht in der Lage sind, ist eine weitere Option, den MySQL-Code von MySQL AB unter einer lockereren Lizenz zu erwerben. Wegen Details betreffs dieses Themas siehe unter Abschnitt 2.4.4, „MySQL-Lizenzpolitik“.