my_ulonglong mysql_affected_rows(MYSQL *mysql)

Beschreibung

Liefert die Anzahl der vom letzten UPDATE aktualisierten, vom letzten DELETE gelöschten oder vom letzten INSERT eingefügten Zeilen. Kann für UPDATE-, DELETE- oder INSERT-Anweisungen direkt nach mysql_query() aufgerufen werden. Bei SELECT-Anweisungen funktioniert mysql_affected_rows() genau wie mysql_num_rows().

Rückgabewerte

Ein Integer größer null zeigt die Anzahl der betroffenen oder abgerufenen Zeilen an. Null bedeutet, dass mit dem UPDATE keine Zeilen aktualisiert wurden, dass keine Zeilen zu der WHERE-Klausel der Anfrage gepasst haben oder die Anfrage noch gar nicht ausgeführt worden ist. -1 bedeutet, dass die Anfrage einen Fehler zurückgeliefert hat oder, bei einer SELECT-Anfrage, dass mysql_affected_rows() vor mysql_store_result() aufgerufen wurde. Da mysql_affected_rows() einen vorzeichenlosen Wert liefert, können Sie -1 feststellen, indem Sie den Rückgabewert mit (my_ulonglong)-1 vergleichen (oder mit (my_ulonglong)~0; das ist dasselbe).

Fehler

Keine.

Beispiel

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

Wenn Sie bei einer Verbindung mit mysqld das Flag CLIENT_FOUND_ROWS angeben, liefert mysql_affected_rows() die Anzahl der Zeilen, die die WHERE-Klausel von UPDATE-Anweisungen erkannt hat.

Beachten Sie, dass mysql_affected_rows() bei Verwendung eines REPLACE-Befehls 2 liefert, wenn die neue Zeile eine alte ersetzt, da hier eine Zeile eingefügt wird, nachdem das Duplikat gelöscht worden ist.

Wenn Sie mit INSERT ... ON DUPLICATE KEY UPDATE eine Zeile einfügen, liefert mysql_affected_rows() den Wert 1, wenn die Zeile als neue Zeile eingefügt wurde, und 2, wenn eine vorhandene Zeile geändert wurde.

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

Beschreibung

Schaltet den Autocommit-Modus ein, wenn mode 1 ist, und aus, wenn mode 0 ist.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

Keine.

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

Beschreibung

Wechselt auf der durch mysql angegebenen Verbindung den Benutzer und macht die in db angegebene zur (aktuellen) Standarddatenbank. In nachfolgenden Anfragen ist diese Datenbank dann der Standardbezugsrahmen für Tabellenverweise, die nicht explizit eine Datenbank angeben.

mysql_change_user() scheitert, wenn der Benutzer sich nicht authentifizieren kann oder keine Berechtigung zur Nutzung der Datenbank hat. In diesem Fall werden Benutzer und Datenbank nicht geändert.

Der Parameter db kann auf NULL gesetzt werden, wenn keine Standarddatenbank vorgegeben werden soll.

Dieser Befehl veranlasst immer ein ROLLBACK aller laufenden Transaktionen, schließt alle temporären Tabellen, hebt Tabellensperren auf und setzt den Status so zurück, als hätte jemand eine ganz neue Verbindung aufgebaut. Das geschieht sogar dann, wenn der Benutzer nicht wechselt.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

Dieselben wie bei mysql_real_connect().

Beispiel

if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
   fprintf(stderr, "Failed to change user.  Error: %s\n",
           mysql_error(&mysql));
}

const char *mysql_character_set_name(MYSQL *mysql)

Beschreibung

Gibt den Standardzeichensatz für die aktuelle Verbindung zurück.

Rückgabewerte

Der Standardzeichensatz.

Fehler

Keine.

void mysql_close(MYSQL *mysql)

Beschreibung

mysql_close() schließt eine zuvor geöffnete Verbindung und gibt den Verbindungs-Handle frei, den mysql benutzt hat, wenn der Handle automatisch von mysql_init() oder mysql_connect() zugewiesen worden war.

Rückgabewerte

Keine.

Fehler

Keine.

my_bool mysql_commit(MYSQL *mysql)

Beschreibung

Committet die laufende Transaktion.

Was diese Funktion tut, hängt von dem Wert der Systemvariablen completion_type ab. Wenn der completion_type 2 ist, gibt der Server nach Beendigung der Transaktion Ressourcen frei und schließt die Clientverbindung. Das Clientprogramm sollte mysql_close() aufrufen, um die Verbindung von der Clientseite aus zu schließen.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

Keine.

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

Beschreibung

Diese Funktion ist veraltet. Stattdessen sollte mysql_real_connect() verwendet werden.

mysql_connect() versucht, eine Verbindung zu einer auf dem host laufenden MySQL-Datenbank-Engine herzustellen. mysql_connect() muss erfolgreich gelaufen sein, ehe Sie irgendeine der anderen API-Funktionen ausführen können, ausgenommen mysql_get_client_info().

Die Parameter haben dieselbe Bedeutung wie die entsprechenden Parameter für mysql_real_connect(), mit dem Unterschied, dass der Verbindungsparameter NULL sein kann. In diesem Fall weist die C-API automatisch Speicher für die Verbindungsstruktur zu und gibt ihn wieder frei, wenn Sie mysql_close() aufrufen. Der Nachteil: Sie können keine Fehlermeldung abrufen, wenn die Verbindung scheitert. (Um von mysql_errno() oder mysql_error() Fehlerinformationen zu bekommen, müssen Sie einen gültigen MYSQL-Zeiger zur Verfügung stellen.)

Rückgabewerte

Dieselben wie für mysql_real_connect().

Fehler

Dieselben wie für mysql_real_connect().

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

Beschreibung

Legt die im db-Parameter genannte Datenbank an.

Diese Funktion ist veraltet. Bitte verwenden Sie stattdessen mysql_query(), um eine SQL-CREATE DATABASE-Anweisung zu geben.

Rückgabewerte

Null, wenn die Datenbank erfolgreich angelegt wurde, und ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Beispiel

if(mysql_create_db(&mysql, "my_database"))
{
   fprintf(stderr, "Failed to create new database.  Error: %s\n",
           mysql_error(&mysql));
}

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

Beschreibung

Findet eine beliebige Zeile in einer Ergebnismenge. Der offset-Wert ist eine Zeilennummer zwischen 0 und mysql_num_rows(result)-1.

Da für diese Funktion erforderlich ist, dass die Ergebnismengenstruktur die gesamte Ergebnismenge enthält, kann mysql_data_seek() nur in Verbindung mit mysql_store_result() und nicht mit mysql_use_result() verwendet werden.

Rückgabewerte

Keine.

Fehler

Keine.

void mysql_debug(const char *debug)

Beschreibung

Führt DBUG_PUSH auf dem gegebenen String aus. mysql_debug() benutzt die Fred Fish-Debugbibliothek. Um diese Funktion benutzen zu können, müssen Sie die Clientbibliothek mit Debuggingunterstützung kompilieren. Siehe Abschnitt E.1, „Einen MySQL-Server debuggen“ und Abschnitt E.2, „Einen MySQL-Client debuggen“.

Rückgabewerte

Keine.

Fehler

Keine.

Beispiel

Dieser Aufruf lässt die Clientbibliothek eine Trace-Datei iin /tmp/client.trace auf dem Clientcomputer generieren:

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

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

Beschreibung

Löscht die im db-Parameter angegebene Datenbank.

Diese Funktion ist veraltet. Bitte benutzen Sie stattdessen mysql_query(), um eine SQL-DROP DATABASE-Anweisung zu erteilen.

Rückgabewerte

Null, wenn die Datenbank erfolgreich gelöscht wurde. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Beispiel

if(mysql_drop_db(&mysql, "my_database"))
  fprintf(stderr, "Failed to drop the database: Error: %s\n",
          mysql_error(&mysql));

int mysql_dump_debug_info(MYSQL *mysql)

Beschreibung

Weist den Server an, Debugginginformationen in das Log zu schreiben. Damit dies funktioniert, benötigt der Benutzer das SUPER-Recht.

Rückgabewerte

Null, wenn der Befehl Erfolg hatte. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

my_bool mysql_eof(MYSQL_RES *result)

Beschreibung

Diese Funktion ist veraltet. mysql_errno() oder mysql_error() können stattdessen verwendet werden.

mysql_eof() stellt fest, ob die letzte Zeile einer Ergebnismenge gelesen worden ist.

Wenn Sie eine Ergebnismenge mit einem erfolgreichen Aufruf von mysql_store_result() abrufen, empfängt der Client die gesamte Menge mit einer einzigen Operation. Der Rückgabewert NULL von mysql_fetch_row() bedeutet in diesem Fall immer, dass das Ende der Ergebnismenge erreicht wurde, sodass sich mysql_eof() erübrigt. In Verbindung mit mysql_store_result() liefert mysql_eof() immer TRUE.

Wenn Sie dagegen den Abruf einer Ergebnismenge mit mysql_use_result() initiieren, werden die Zeilen eine nach der anderen mit wiederholten mysql_fetch_row()-Aufrufen vom Server geholt. Da bei diesem Prozess ein Verbindungsfehler auftreten kann, bedeutet eine NULL-Rückgabe von mysql_fetch_row() nicht unbedingt, dass ganz normal das Ende der Ergebnismenge erreicht wurde. In diesem Fall können Sie mit mysql_eof() feststellen, was tatsächlich geschah. mysql_eof() liefert einen von null verschiedenen Wert, wenn das Ende der Ergebnismenge erreicht wurde, und null, wenn ein Fehler auftrat.

Eigentlich ist mysql_eof() älter als die MySQL-Standardfehlerfunktionen mysql_errno() und mysql_error(). Da diese Fehlerfunktionen dieselben Informationen liefern, bevorzugen wir sie gegenüber der veralteten Funktion mysql_eof(). (Eigentlich geben sie sogar mehr Informationen, da mysql_eof() nur einen booleschen Wert zurückgibt, während die Fehlerfunktionen auch den Grund für einen Fehler verraten.)

Rückgabewerte

Null, wenn kein Fehler auftrat. Ein von null verschiedener Wert, wenn das Ende der Ergebnismenge erreicht wurde.

Fehler

Keine.

Beispiel

Das folgende Beispiel zeigt, wie sich mysql_eof() einsetzen lässt:

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
    // Tu etwas mit den Daten
}
if(!mysql_eof(result))  // mysql_fetch_row() scheiterte wegen eines Fehlers
{
    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

Sie können jedoch denselben Effekt auch mit den Standardfehlerfunktionen von MySQL erzielen:

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
  // Tu etwas mit den Daten
}
  if(mysql_errno(&mysql))  // mysql_fetch_row() scheiterte wegen eines Fehlers
{
    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

unsigned int mysql_errno(MYSQL *mysql)

Beschreibung

Für die von mysql angegebene Verbindung liefert mysql_errno() den Fehlercode zu der zuletzt aufgerufenen API-Funktion, die mit Erfolg gelaufen oder gescheitert sein kann. Der Rückgabewert null bedeutet, dass kein Fehler auftrat. Die Nummern der Clientfehlermeldungen sind in der MySQL-Header-Datei errmsg.h aufgelistet. Die Nummern der Serverfehlermeldungen stehen in der Datei mysqld_error.h. Außerdem werden die Fehler in Anhang B, Fehlercodes und -meldungen, aufgeführt.

Beachten Sie, dass manche Funktionen, wie etwa mysql_fetch_row(), keine mysql_errno() setzen, wenn sie Erfolg haben.

Als Faustregel gilt: Alle Funktionen, die vom Server Informationen abfragen müssen, setzen mysql_errno() zurück, wenn sie Erfolg hatten.

Rückgabewerte

Ein Fehlercodewert für den letzten mysql_xxx()-Aufruf, wenn dieser gescheitert ist. Null bedeutet, dass kein Fehler auftrat.

Fehler

Keine.

const char *mysql_error(MYSQL *mysql)

Beschreibung

Für die durch mysql angegebene Verbindung liefert mysql_error() einen auf null endenden String mit der Fehlermeldung für die zuletzt aufgerufene API-Funktion, die gescheitert ist. Wenn keine Funktion gescheitert ist, kann der Rückgabewert von mysql_error() auch der vorherige Fehler oder ein leerer String sein, der anzeigt, dass kein Fehler auftrat.

Als Faustregel gilt: Alle Funktionen, die vom Server Informationen abfragen müssen, setzen mysql_errno() zurück, wenn sie Erfolg hatten.

Für Funktionen, die mysql_errno() zurücksetzen, sind die beiden folgenden Tests äquivalent:

if(mysql_errno(&mysql))
{
    // Ein Fehler ist aufgetreten
}

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

Sie können die Sprache für die Fehlermeldungen des Clients ändern, indem Sie die MySQL-Clientbibliothek neu kompilieren. Zurzeit haben Sie die Auswahl zwischen Fehlermeldungen in mehreren verschiedenen Sprachen. Siehe Abschnitt 5.11.2, „Nicht englische Fehlermeldungen“.

Rückgabewerte

Ein auf null endender Zeichen-String, der den Fehler beschreibt. Ein leerer String, wenn kein Fehler auftrat.

Fehler

Keine.

Bitte verwenden Sie stattdessen mysql_real_escape_string()!

Diese Funktion gleicht mysql_real_escape_string(), mit dem Unterschied, dass mysql_real_escape_string() einen Verbindungs-Handler als erstes Argument entgegennimmt und den String entsprechend dem aktuellen Zeichensatz mit Escape-Zeichen versieht. mysql_escape_string() nimmt kein Verbindungsargument an und berücksichtigt auch nicht den aktuellen Zeichensatz.

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Beschreibung

Liefert die Definition einer Spalte einer Ergebnismenge in Form einer MYSQL_FIELD-Struktur. Um Informationen über alle Spalten der Ergebnismenge zu erhalten, rufen Sie diese Funktion wiederholt auf. mysql_fetch_field() liefert NULL, wenn keine weiteren Felder mehr übrig sind.

Mit jeder neuen SELECT-Anfrage wird mysql_fetch_field() so zurückgesetzt, dass sie wieder Informationen über das erste Feld liefert. Auch mysql_field_seek() nimmt Einfluss darauf, welches Feld mysql_fetch_field() zurückgibt.

Wenn Sie mit mysql_query() ein SELECT auf einer Tabelle ausgeführt haben, ohne jedoch mysql_store_result() zu benutzen, dann liefert MySQL, wenn Sie mit mysql_fetch_field() die Länge eines BLOB-Felds erfragen, die Standardlänge eines Blob-Werts (8 Kbyte). (Die Größe von 8 Kbyte wird gewählt, weil MySQL die maximale Länge für den BLOB nicht kennt. Irgendwann soll dies einmal konfigurierbar gemacht werden.) Wenn Sie die Ergebnismenge abgeholt haben, enthält field->max_length die Länge des längsten Werts dieser Spalte für diese konkrete 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(result)))
{
    printf("field name %s\n", field->name);
}

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

Beschreibung

Wenn man ihr die Feldnummer fieldnr einer Spalte aus einer Ergebnismenge übergibt, liefert die Funktion die Felddefinition dieser Spalte als MYSQL_FIELD-Struktur. Mit dieser Funktion können Sie die Definition einer beliebigen Spalte abfragen. Der Wert von fieldnr sollte zwischen 0 und mysql_num_fields(result)-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(result);
for(i = 0; i < num_fields; i++)
{
    field = mysql_fetch_field_direct(result, i);
    printf("Field %u is %s\n", i, field->name);
}

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

Beschreibung

Gibt ein Array mit allen MYSQL_FIELD-Strukturen für eine Ergebnismenge zurück. Jede Struktur liefert die Felddefinition für eine Spalte der Ergebnismenge.

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(result);
fields = mysql_fetch_fields(result);
for(i = 0; i < num_fields; i++)
{
   printf("Field %u is %s\n", i, fields[i].name);
}

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

Beschreibung

Gibt die Länge der Spalten der aktuellen Zeile einer Ergebnismenge zurück. Wenn Sie planen, Feldwerte zu kopieren, sind diese Längenangaben auch für die Optimierung hilfreich, da Sie sich dadurch den Aufruf von strlen() ersparen können. Wenn die Ergebnismenge Binärdaten enthält, müssen Sie sogar diese Funktion zur Ermittlung der Datenlänge einsetzen, da strlen() für Felder mit Nullwerten verkehrte Ergebnisse liefert.

Die Länge von leeren Spalten und Spalten mit NULL-Werten ist null. Unter der Beschreibung von mysql_fetch_row() erfahren Sie, wie Sie diese beiden Fälle unterscheiden können.

Rückgabewerte

Ein Array von vorzeichenlosen Long-Integers, das die Größen der Spalten angibt (ausschließlich eventueller Nullzeichen am Ende). Ist NULL, wenn ein Fehler auftrat.

Fehler

mysql_fetch_lengths() ist nur für die aktuelle Zeile der Ergebnismenge gültig. Diese Funktion liefert NULL, wenn Sie sie vor mysql_fetch_row() oder nach dem Abruf aller Ergebniszeilen aufrufen.

Beispiel

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

row = mysql_fetch_row(result);
if (row)
{
    num_fields = mysql_num_fields(result);
    lengths = mysql_fetch_lengths(result);
    for(i = 0; i < num_fields; i++)
    {
         printf("Column %u is %lu bytes in length.\n", i, lengths[i]);
    }
}

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

Beschreibung

Ruft die nächste Zeile einer Ergebnismenge ab. Nach mysql_store_result() aufgerufen, liefert mysql_fetch_row() den Wert NULL, wenn keine weiteren Zeilen mehr abzuholen sind. Nach mysql_use_result() aufgerufen, liefert mysql_fetch_row() den Wert NULL, wenn keine Zeilen mehr vorliegen oder wenn ein Fehler auftrat.

mysql_num_fields(result) gibt die Anzahl der Werte in einer Zeile an. Wenn row den Rückgabewert eines mysql_fetch_row()-Aufrufs speichert, können Sie mit row[0] bis row[mysql_num_fields(result)-1] die Zeiger auf die Werte dieser Zeile ansprechen. NULL-Werte in der Zeile werden durch NULL-Zeiger angezeigt.

Die Längen der Feldwerte der Zeile können Sie sich mit mysql_fetch_lengths() beschaffen. Leere Felder und Felder mit NULL haben beide die Länge null. Sie können sie unterscheiden, indem Sie sich den Zeiger auf den Feldwert anschauen: Ist er NULL, speichert das Feld den Wert NULL; andernfalls ist es leer.

Rückgabewerte

Eine MYSQL_ROW-Struktur für die nächste Zeile oder NULL, wenn keine weiteren Zeilen mehr vorliegen oder ein Fehler aufgetreten ist.

Fehler

Beachten Sie, dass der Fehler zwischen zwei Aufrufen von mysql_fetch_row() nicht zurückgesetzt wird.

Beispiel

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

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

unsigned int mysql_field_count(MYSQL *mysql)

Beschreibung

Liefert die Anzahl der Spalten für die jüngste Anfrage auf dieser Verbindung.

Normalerweise benutzen Sie diese Funktion, wenn mysql_store_result() den Wert NULL zurückgegeben hat (und Sie deshalb keinen Zeiger auf die Ergebnismenge haben). In diesem Fall können Sie mit mysql_field_count() feststellen, ob mysql_store_result() ein nichtleeres Ergebnis hätte produzieren müssen. So kann das Clientprogramm die richtigen Maßnahmen ergreifen, ohne zu wissen, ob die Anfrage eine SELECT- (oder SELECT-ähnliche) Anweisung war. Wie dies funktioniert, zeigt das folgende Beispiel.

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

Rückgabewerte

Ein vorzeichenloser Integer, der die Anzahl der Spalten einer Ergebnismenge angibt.

Fehler

Keine.

Beispiel

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

if (mysql_query(&mysql,query_string))
{
    // Fehler
}
else // Anfrage erfolgreich, Rückgabedaten können verarbeitet werden
{
    result = mysql_store_result(&mysql);
    if (result)  // Es sind Zeilen vorhanden
    {
        num_fields = mysql_num_fields(result);
        // Hole Zeilen ab und rufe dann mysql_free_result(result) auf
    }
    else  // mysql_store_result() gab nichts zurück. Hätte es sollen?
    {
        if(mysql_field_count(&mysql) == 0)
        {
            // Anfrage liefert keine Daten
            // (Es war kein SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
        else // mysql_store_result() hätte Daten zurückgeben müssen
        {
            fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
        }
    }
}

Eine Alternative wäre es, den Aufruf von mysql_field_count(&mysql) durch mysql_errno(&mysql) zu ersetzen. In diesem Fall schauen Sie direkt in mysql_store_result() nach einem Fehler, anstatt aus dem Wert von mysql_field_count() zu erschließen, ob die Anweisung ein SELECT war.

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Beschreibung

Setzt den Feld-Cursor auf den gegebenen Offset. Der nächste mysql_fetch_field()-Aufruf fragt die Felddefinition der mit diesem Offset verbundenen Spalte ab.

Um den Zeilenanfang zu suchen, übergeben Sie den offset-Wert null.

Rückgabewerte

Der vorherige Wert des Feld-Cursors.

Fehler

Keine.

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

Beschreibung

Liefert die Position des Feld-Cursors, der für den letzten mysql_fetch_field()-Aufruf verwendet wurde. Dieser Wert kann als Argument für mysql_field_seek() dienen.

Rückgabewerte

Der aktuelle Offset des Feld-Cursors.

Fehler

Keine.

void mysql_free_result(MYSQL_RES *result)

Beschreibung

Gibt den Speicher frei, der einer Ergebnismenge durch mysql_store_result(), mysql_use_result(), mysql_list_dbs() und so weiter zugewiesen wurde. Wenn Sie mit einer Ergebnismenge fertig sind, müssen Sie ihren Speicher mit mysql_free_result() wieder freigeben.

Versuchen Sie nicht mehr, auf eine Ergebnismenge zuzugreifen, nachdem Sie sie freigegeben haben.

Rückgabewerte

Keine.

Fehler

Keine.

void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs)

Beschreibung

Diese Funktion liefert Informationen über den Standardzeichensatz des Clients. Dieser kann mit der Funktion mysql_set_character_set() geändert werden.

Diese Funktion kam in MySQL 5.0.10 hinzu.

Beispiel

if (!mysql_set_character_set(&mysql, "utf8"))
{
    MY_CHARSET_INFO cs;
    mysql_get_character_set_info(&mysql, &cs);
    printf("character set information:\n");
    printf("character set name: %s\n", cs.name);
    printf("collation name: %s\n", cs.csname);
    printf("comment: %s\n", cs.comment);
    printf("directory: %s\n", cs.dir);
    printf("multi byte character min. length: %d\n", cs.mbminlen);
    printf("multi byte character max. length: %d\n", cs.mbmaxlen);
}

char *mysql_get_client_info(void)

Beschreibung

Liefert einen String, der die Version der Clientbibliothek darstellt.

Rückgabewerte

Ein Zeichen-String, der die Version der MySQL-Clientbibliothek darstellt.

Fehler

Keine.

unsigned long mysql_get_client_version(void)

Beschreibung

Liefert einen Integer, der die Version der Clientbibliothek darstellt. Der Wert hat das Format XYYZZ, wobei X die Hauptversion, YY der Release-Level und ZZ die Versionsnummer innerhalb des Releases ist. So bedeutet beispielsweise der Wert 40102 die Clientbibliotheksversion 4.1.2.

Rückgabewerte

Ein Integer, der die Version der MySQL-Clientbibliothek angibt.

Fehler

Keine.

char *mysql_get_host_info(MYSQL *mysql)

Beschreibung

Liefert einen String, der den benutzten Verbindungstyp einschließlich des Hostnamens des Servers beschreibt.

Rückgabewerte

Ein Zeichen-String, der den Hostnamen des Servers und den Verbindungstyp darstellt.

Fehler

Keine.

unsigned int mysql_get_proto_info(MYSQL *mysql)

Beschreibung

Liefert die Protokollversion der aktuellen Verbindung.

Rückgabewerte

Ein vorzeichenloser Integer, der die Protokollversion der aktuellen Verbindung darstellt.

Fehler

Keine.

char *mysql_get_server_info(MYSQL *mysql)

Beschreibung

Liefert einen String, der die Versionsnummer des Servers darstellt.

Rückgabewerte

Ein Zeichen-String, der die Versionsnummer des Servers darstellt.

Fehler

Keine.

unsigned long mysql_get_server_version(MYSQL *mysql)

Beschreibung

Liefert die Versionsnummer des Servers als Integer.

Rückgabewerte

Eine Zahl, welche die MySQL Server-Version in folgendem Format darstellt:

major_version*10000 + minor_version *100 + sub_version

So wird beispielsweise 5.1.5 als 50105 zurückgegeben.

Diese Funktion ist nützlich, um in Clientprogrammen schnell herauszufinden, ob eine versionsspezifische Serverfähigkeit geboten wird.

Fehler

Keine.

unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)

Beschreibung

Diese Funktion dient der Erstellung eines gültigen SQL-Strings, den Sie in einer SQL-Anweisung benutzen können. Siehe Abschnitt 9.1.1, „Strings“.

Der String in from ist im Hexadezimalformat verschlüsselt, wobei jedes Zeichen als zwei Hexadezimalziffern kodiert ist. Das Ergebnis wird in to eingesetzt und ein Nullbyte als Abschlusszeichen angehängt.

Der String, auf den from verweist, muss length Bytes lang sein. Den to-Puffer müssen Sie mindestens mit einer Länge von length*2+1 Bytes zuweisen. Wenn mysql_hex_string() zurückkehrt, ist der Inhalt von to ein auf null endender String. Der Rückgabewert ist die Länge des kodierten Strings ohne das abschließende Nullzeichen.

Der Rückgabewert kann in eine SQL-Anweisung in einem der Formate 0xvalue oder X'value' eingesetzt werden. Allerdings enthält der Rückgabewert nicht das 0x oder X'...'. Der Aufrufer muss dieses Element selbst beisteuern, je nachdem, für welches er sich entscheidet.

Beispiel

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
end = strmov(end,"0x");
end += mysql_hex_string(end,"What's this",11);
end = strmov(end,",0x");
end += mysql_hex_string(end,"binary data: \0\r\n",16);
*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}

Die im Beispiel verwendete Funktion strmov() stammt aus der mysqlclient-Bibliothek und funktioniert wie strcpy(), liefert jedoch einen Zeiger auf die abschließende Null des ersten Parameters.

Rückgabewerte

Die Länge des in to eingesetzten Werts ohne die abschließende Null.

Fehler

Keine.

char *mysql_info(MYSQL *mysql)

Beschreibung

Holt einen String mit Informationen über die zuletzt ausgeführte Anfrage ab, aber nur für die hier aufgeführten Anweisungen. Für andere Anweisungen liefert mysql_info() die Funktion NULL. Das Format des Strings hängt von der Art der Anfrage ab, wie hier beschrieben. Die Zahlen dienen nur der Veranschaulichung; der String enthält Werte, die für die Anfrage passend sind.

Beachten Sie, dass mysql_info() bei INSERT ... VALUES lediglich für die mehrzeilige Form der Anweisung (also dann, wenn mehrere Wertelisten angegeben werden) einen von NULL verschiedenen Wert liefert.

Rückgabewerte

Ein Zeichen-String mit Zusatzinformationen über die zuletzt ausgeführte Anfrage. NULL, wenn keine Informationen über die Anfrage zur Verfügung stehen.

Fehler

Keine.

MYSQL *mysql_init(MYSQL *mysql)

Beschreibung

Reserviert oder initialisiert ein geeignetes MYSQL-Objekt für mysql_real_connect(). Wenn mysql ein NULL-Zeiger ist, reserviert, initialisiert und liefert die Funktion ein neues Objekt. Andernfalls wird das Objekt initialisiert und seine Adresse zurückgegeben. Wenn mysql_init() ein neues Objekt zuweist, wird dieses wieder freigegeben, wenn mysql_close() zum Schließen der Verbindung aufgerufen wird.

Rückgabewerte

Ein initialisierter MYSQL*-Handle. NULL, wenn nicht genügend Speicher zur Zuweisung eines neuen Objekts verfügbar war.

Fehler

Wenn der Speicher nicht ausreichte, wird NULL zurückgegeben.

my_ulonglong mysql_insert_id(MYSQL *mysql)

Beschreibung

Liefert den von der vorherigen INSERT- oder UPDATE-Anweisung für eine AUTO_INCREMENT-Spalte generierten Wert. Verwenden Sie diese Funktion, wenn Sie eine INSERT-Anweisung auf einer Tabelle mit einem AUTO_INCREMENT-Feld ausgeführt haben.

Genauer gesagt: mysql_insert_id() wird unter folgenden Bedingungen aktualisiert:

Beachten Sie, dass mysql_insert_id() den Wert 0 liefert, wenn die Anweisung keinen AUTO_INCREMENT-Wert verwendet. Wenn Sie den Wert zur späteren Benutzung speichern möchten, müssen Sie unmittelbar nach der Anweisung, die den Wert generiert, mysql_insert_id() aufrufen.

Der Wert von mysql_insert_id() wird nur von Anweisungen beeinflusst, die innerhalb der aktuellen Clientverbindung gegeben werden, aber nicht durch Anweisungen von anderen Clients.

Siehe Abschnitt 12.10.3, „Informationsfunktionen“.

Bitte beachten Sie auch, dass der Wert der SQL-Funktion LAST_INSERT_ID() immer den zuletzt generierten AUTO_INCREMENT-Wert enthält. Dieser wird zwischen zwei Anweisungen nicht zurückgesetzt, da der Wert dieser Funktion im Server gespeichert ist. Ein weiterer Unterschied ist der, dass LAST_INSERT_ID() nicht aktualisiert wird, wenn Sie eine AUTO_INCREMENT-Spalte auf einen bestimmten Wert setzen, der kein Spezialwert ist.

Der Grund für den Unterschied zwischen LAST_INSERT_ID() und mysql_insert_id() besteht darin, dass LAST_INSERT_ID() in Skripten einfach zu benutzen sein soll, während mysql_insert_id() versucht, etwas genauere Informationen über die Vorgänge in der AUTO_INCREMENT-Spalte zu liefern.

Rückgabewerte

Siehe oben.

Fehler

Keine.

int mysql_kill(MYSQL *mysql, unsigned long pid)

Beschreibung

Lässt den Server den Thread pid anhalten.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

void mysql_library_end(void)

Beschreibung

Dies ist ein Synonym für die mysql_server_end()-Funktion.

Informationen zur Verwendung finden Sie unter Abschnitt 24.2.2, „C-API: Funktionsüberblick“.

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

Beschreibung

Dies ist ein Synonym für die mysql_server_init()-Funktion. Siehe Abschnitt 24.2.12.1, „mysql_server_init()“.

Informationen zur Verwendung finden Sie unter Abschnitt 24.2.2, „C-API: Funktionsüberblick“.

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

Beschreibung

Liefert eine Ergebnismenge mit Namen von Datenbanken auf dem Server, die mit dem einfachen regulären Ausdruck im Parameter wild übereinstimmen. wild kann die Wildcard-Zeichen ‘%’ oder ‘_’ enthalten oder aber ein NULL-Zeiger sein, der auf alle Datenbanken passt. Ein Aufruf von mysql_list_dbs() ist dasselbe wie die Anfrage SHOW databases [LIKE wild].

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

Rückgabewerte

Bei einem Erfolg eine MYSQL_RES-Ergebnismenge und bei einem Fehler der Wert NULL.

Fehler

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

Beschreibung

Liefert eine Ergebnismenge mit Namen von Feldern aus der gegebenen Tabelle, die mit dem einfachen regulären Ausdruck im Parameter wild übereinstimmen. wild kann die Wildcard-Zeichen ‘%’ oder ‘_’ enthalten oder aber ein NULL-Zeiger sein, der auf alle Felder passt. Ein Aufruf von mysql_list_fields() ist dasselbe wie die Anfrage SHOW COLUMNS FROM tbl_name [LIKE wild].

Wir empfehlen, SHOW COLUMNS FROM tbl_name anstelle von mysql_list_fields() zu benutzen.

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

Rückgabewerte

Bei Erfolg eine MYSQL_RES-Ergebnismenge und bei einem Fehler der Wert NULL.

Fehler

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

Beschreibung

Gibt eine Ergebnismenge mit einer Beschreibung der laufenden Server-Threads zurück. Dieselben Informationen erhalten Sie auch mit mysqladmin processlist oder der Anfrage SHOW PROCESSLIST.

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

Rückgabewerte

Bei Erfolg eine MYSQL_RES-Ergebnismenge und bei einem Fehler der Wert NULL.

Fehler

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

Beschreibung

Liefert eine Ergebnismenge mit Namen von Tabellen aus der aktuellen Datenbank, die mit dem einfachen regulären Ausdruck im Parameter wild übereinstimmen. wild kann die Wildcard-Zeichen ‘%’ oder ‘_’ enthalten oder aber ein NULL-Zeiger sein, der auf alle Tabellen passt. Ein Aufruf von mysql_list_tables() ist dasselbe wie die Anfrage SHOW tables [LIKE wild].

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

Rückgabewerte

Bei Erfolg eine MYSQL_RES-Ergebnismenge und bei einem Fehler der Wert NULL.

Fehler

my_bool mysql_more_results(MYSQL *mysql)

Beschreibung

Gibt TRUE zurück, wenn noch weitere Ergebnisse der aktuellen Anfrage vorliegen und die Anwendung mysql_next_result() aufrufen muss, um diese Ergebnisse abzuholen.

Rückgabewerte

TRUE (1), wenn noch weitere Ergebnisse existieren. FALSE (0), wenn keine Ergebnisse mehr vorhanden sind.

In den meisten Fällen können Sie stattdessen mit mysql_next_result() testen, ob noch Ergebnisse übrig sind, und den Abruf der Daten initiieren, wenn dies der Fall ist.

Siehe Abschnitt 24.2.9, „C-API: Behandlung der Ausführung mehrerer Anweisungen“, und Abschnitt 24.2.3.45, „mysql_next_result()“.

Fehler

Keine.

int mysql_next_result(MYSQL *mysql)

Beschreibung

Wenn noch Anfrageergebnisse vorliegen, liest mysql_next_result() die nächsten Ergebnisse und gibt den Status an die Anwendung zurück.

Sie müssen für die vorherige Anfrage mysql_free_result() aufrufen, falls diese eine Ergebnismenge zurückgegeben hat.

Nach einem Aufruf von mysql_next_result() hat die Verbindung denselben Status, als hätten Sie mysql_real_query() oder mysql_query() für die nächste Anfrage aufgerufen. Das bedeutet, dass Sie mysql_store_result(), mysql_warning_count(), mysql_affected_rows() und so weiter aufrufen können.

Wenn mysql_next_result() einen Fehler zurückgibt, werden andere Anweisungen ausgeführt und es liegen keine Ergebnisse mehr zum Abruf bereit.

Siehe Abschnitt 24.2.9, „C-API: Behandlung der Ausführung mehrerer Anweisungen“.

Rückgabewerte

Fehler

unsigned int mysql_num_fields(MYSQL_RES *result)

Um stattdessen ein MYSQL*-Argument zu übergeben, sagen Sie unsigned int mysql_field_count(MYSQL *mysql).

Beschreibung

Liefert die Anzahl der Spalten einer Ergebnismenge.

Beachten Sie, dass Sie die Anzahl der Spalten entweder aus einem Zeiger auf eine Ergebnismenge oder aus einem Verbindungs-Handle erfahren können. Den Verbindungs-Handle verwenden Sie, wenn mysql_store_result() oder mysql_use_result() den Wert NULL zurückgegeben hat (sodass kein Zeiger auf die Ergebnismenge zur Verfügung steht). In diesem Fall können Sie mit mysql_field_count() ermitteln, ob mysql_store_result() eigentlich ein nichtleeres Ergebnis hätte liefern sollen. So kann das Clientprogramm geeignete Maßnahmen ergreifen, ohne zu wissen, ob die Anfrage eine SELECT- (oder SELECT-ähnliche) Anweisung war. Das Beispiel zeigt, wie man dies macht.

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

Rückgabewerte

Ein vorzeichenloser Integer, der die Anzahl der Spalten einer Ergebnismenge angibt.

Fehler

Keine.

Beispiel

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

if (mysql_query(&mysql,query_string))
{
    // Fehler
}
else // Anfrage erfolgreich, Rückgabedaten werden verarbeitet
{
    result = mysql_store_result(&mysql);
    if (result)  // Es liegen Zeilen vor
    {
        num_fields = mysql_num_fields(result);
        // Zeilen abrufen und dann mysql_free_result(result) aufrufen
    }
    else  // mysql_store_result() gab nichts zurück, hätte es sollen?
    {
        if (mysql_errno(&mysql))
        {
           fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
        }
        else if (mysql_field_count(&mysql) == 0)
        {
            // Anfrage liefert keine Daten
            // (war kein SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
    }
}

Wenn Sie wissen, dass Ihre Anfrage eine Ergebnismenge hätte zurückgeben müssen, können Sie alternativ den Aufruf von mysql_errno(&mysql) durch eine Prüfung ersetzen, die feststellt, ob mysql_field_count(&mysql) gleich 0 ist. Das geschieht nur, wenn etwas schief gegangen ist.

my_ulonglong mysql_num_rows(MYSQL_RES *result)

Beschreibung

Liefert die Anzahl der Zeilen in der Ergebnismenge.

Die Verwendung von mysql_num_rows() hängt davon ab, ob Sie die Ergebnismenge mit mysql_store_result() oder mysql_use_result() zurückgeben. Wenn Sie mysql_store_result() benutzen, kann mysql_num_rows() direkt aufgerufen werden, aber wenn Sie mysql_use_result() benutzen, gibt mysql_num_rows() erst dann den richtigen Wert zurück, wenn alle Zeilen der Ergebnismenge abgeholt worden sind.

Rückgabewerte

Die Anzahl der Zeilen in der Ergebnismenge.

Fehler

Keine.

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

Beschreibung

Kann verwendet werden, um zusätzliche Verbindungsoptionen einzustellen und das Verhalten einer Verbindung zu beeinflussen. Diese Funktion kann auch mehrmals 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 einzustellende Option und das arg-Argument ist ihr Wert. Ist die Option ein Integer, so sollte arg auf den Wert dieses Integers verweisen.

Mögliche Optionswerte:

Beachten Sie, dass immer die client-Gruppe 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 zwar durch connect-timeout ersetzt, aber timeout in MySQL 5.1.5-alpha aus Gründen der Abwärtskompatibilität immer noch unterstützt wird.

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

Rückgabewerte

Bei Erfolg null und bei Verwendung einer unbekannten Option ein von null verschiedener Wert.

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","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

Dieser Code veranlasst den Client, das komprimierte Client/Server-Protokoll zu verwenden und die zusätzlichen Optionen aus dem Abschnitt odbc der Datei my.cnf zu lesen.

int mysql_ping(MYSQL *mysql)

Beschreibung

Prüft, ob die Serververbindung funktioniert. Wenn die Verbindung abgebrochen ist, wird automatisch eine Neuverbindung versucht.

Mit dieser Funktion können Clients, die geraume Zeit untätig waren, prüfen, ob der Server die Verbindung geschlossen hat, und sich notfalls neu verbinden.

Rückgabewerte

Null, wenn die Serververbindung noch steht, und ein von null verschiedener Wert, wenn ein Fehler auftrat. Ein von null verschiedener Wert bedeutet nicht unbedingt, dass der MySQL Server selbst abgestürzt ist, sondern kann auch bedeuten, dass die Verbindung aus anderen Gründen abgebrochen ist, etwa wegen eines Netzwerkproblems.

Fehler

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

Beschreibung

Führt die SQL-Anfrage in dem auf null endenden String query aus. Normalerweise muss der String eine einzige SQL-Anweisung ohne abschließendes Semikolon (‘;’) oder \g enthalten. Wenn die Ausführung von Mehrfachanweisungen aktiviert wurde, kann der String auch mehrere, durch Semikola getrennte Anweisungen enthalten. Siehe Abschnitt 24.2.9, „C-API: Behandlung der Ausführung mehrerer Anweisungen“.

mysql_query() darf nicht für Anfragen mit Binärdaten verwendet werden. Hierfür müssen Sie stattdessen mysql_real_query() aufrufen. (Binärdaten können das Zeichen ‘\0’ enthalten, das mysql_query() als Ende des Anfrage-Strings interpretiert.)

Wenn Sie wissen möchten, ob die Anfrage eine Ergebnismenge liefern sollte, können Sie dies mit mysql_field_count() überprüfen. Siehe Abschnitt 24.2.3.22, „mysql_field_count()“.

Rückgabewerte

Null, wenn die Anfrage Erfolg hatte. Ein von null verschiedener Wert, 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 long client_flag)

Beschreibung

mysql_real_connect() versucht, eine Verbindung zu einer MySQL-Datenbank-Engine auf host herzustellen. mysql_real_connect() muss erfolgreich zum Abschluss kommen, ehe Sie irgendwelche anderen API-Funktionen ausführen können, die eine gültige MYSQL-Verbindungs-Handle-Struktur erfordern.

Die Parameter werden folgendermaßen angegeben:

Manche Parameterwerte können einer Optionsdatei entnommen werden, anstatt sie explizit im Aufruf von mysql_real_connect() zu setzen. Um dies zu tun, rufen Sie mysql_options() mit der Option MYSQL_READ_DEFAULT_FILE oder MYSQL_READ_DEFAULT_GROUP auf, bevor Sie mysql_real_connect() verwenden. Danach geben Sie im Aufruf von mysql_real_connect() den Wert „no-value“ für jeden Parameter an, der seinen Wert aus einer Optionsdatei holen soll:

Wenn in der Optionsdatei für einen Parameter kein Wert gefunden wird, wird sein Standardwert gemäß der Beschreibung weiter oben in diesem Abschnitt verwendet.

Rückgabewerte

Ein MYSQL*-Verbindungs-Handle, wenn die Verbindung erfolgreich eingerichtet wurde, und NULL, wenn der Verbindungsversuch keinen Erfolg hatte. Der Rückgabewert für eine erfolgreiche Verbindung ist derselbe wie der Wert des ersten Parameters.

Fehler

Beispiel

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

Wenn Sie mysql_options() aufrufen, liest die MySQL-Bibliothek die Abschnitte [client] und [your_prog_name] in der Datei my.cnf. So ist gewährleistet, dass Ihr Programm auch dann funktioniert, wenn jemand MySQL in nichtstandardmäßiger Weise eingerichtet hat.

Beachten Sie, dass mysql_real_connect() beim Einrichten einer Verbindung das Flag reconnect (ein Teil der MYSQL-Struktur) bei API-Versionen vor 5.0.3 auf 1 und bei neueren Versionen auf 0 setzt. Hat das Flag den Wert 1, versucht sich das System erneut mit dem Server zu verbinden, wenn eine Anweisung wegen einer abgebrochenen Verbindung nicht ausgeführt werden konnte. Seit MySQL 5.0.13 können Sie das Verhalten in Bezug auf Neuverbindungen mit der Option MYSQL_OPT_RECONNECT zu mysql_options() steuern.

unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)

Beachten Sie, dass mysql eine gültige, offene Verbindung sein muss. Diese ist erforderlich, da das Escape-Verhalten von dem Zeichensatz des Servers abhängt.

Beschreibung

Diese Funktion wird verwendet, um einen gültigen SQL-String zu erzeugen, den Sie in einer SQL-Anweisung benutzen können. Siehe Abschnitt 9.1.1, „Strings“.

Der String in from ist als SQL-String mit Escape-Zeichen unter Berücksichtigung des aktuellen Zeichensatzes der Verbindung kodiert. Das Ergebnis wird in to platziert und ein abschließendes Nullbyte angehängt. Kodierte Zeichen sind NUL (ASCII 0), ‘\n’, ‘\r’, ‘\’, ‘'’, ‘"’ und Strg-Z (siehe Abschnitt 9.1, „Literale: wie Strings und Zahlen geschrieben werden“). (Streng genommen verlangt MySQL ein Escape-Zeichen im Anfrage-String nur für den Backslash und die Sorte Anführungszeichen, in welche der String eingefasst ist. Diese Funktion setzt auch die anderen Zeichen in Anführungszeichen, damit sie in Logdateien leichter zu lesen sind.)

Der String, auf den from verweist, muss length Bytes lang sein. Den Puffer für to müssen Sie mit einer Länge von mindestens length*2+1 Bytes zuweisen. (Im schlimmsten Fall braucht vielleicht jedes Zeichen 2 Byte für die Kodierung und am Ende muss noch Platz für das Nullbyte vorhanden sein.) Wenn mysql_real_escape_string() zurückkehrt, ist der Inhalt von to ein auf null endender String. Der Rückgabewert ist die Länge des kodierten Strings ohne das abschließende Nullzeichen.

Wenn Sie den Zeichensatz für die Verbindung umstellen müssen, sollten Sie die Funktion mysql_set_character_set() anstelle einer SET NAMES- (oder SET CHARACTER SET-)Anweisung verwenden. mysql_set_character_set() arbeitet wie SET NAMES, beeinflusst aber auch den von mysql_real_escape_string() verwendeten Zeichensatz. Das tut SET NAMES nicht.

Beispiel

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"What's this",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);
*end++ = '\'';
*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}

Die im Beispiel verwendete strmov()-Funktion gehört zur mysqlclient-Bibliothek und funktioniert wie strcpy(), gibt jedoch einen Zeiger auf die abschließende Null des ersten Parameters zurück.

Rückgabewerte

Die Länge des in to gesetzten Werts ohne das abschließende Nullzeichen.

Fehler

Keine.

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

Beschreibung

Führt die SQL-Anfrage aus, auf die query verweist. Diese sollte ein length Bytes langer String sein. Normalerweise muss der String eine einzelne SQL-Anweisung ohne abschließendes Semikolon (‘;’) oder \g enthalten. Wenn Mehrfachanweisungen aktiviert sind, kann der String auch mehrere durch Semikola getrennte Anweisungen enthalten. Siehe Abschnitt 24.2.9, „C-API: Behandlung der Ausführung mehrerer Anweisungen“.

Sie müssen mysql_real_query() anstelle von mysql_query() benutzen, wenn Ihre Anfragen Binärdaten enthalten, da diese das ‘\0’-Zeichen enthalten können. Überdies ist die Funktion mysql_real_query() schneller als mysql_query(), da sie nicht strlen() auf dem Anfrage-String aufruft.

Wenn Sie wissen möchten, ob die Anfrage eigentlich eine Ergebnismenge zurückliefern sollte, können Sie dies mit mysql_field_count() überprüfen. Siehe Abschnitt 24.2.3.22, „mysql_field_count()“.

Rückgabewerte

Null, wenn die Anfrage Erfolg hatte. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

int mysql_refresh(MYSQL *mysql, unsigned int options)

Beschreibung

Diese Funktionen leeren Tabellen oder Caches oder setzen Replikationsserver-Informationen zurück. Der Benutzer, der die Verbindung innehat, benötigt hierzu das RELOAD-Recht.

Das options-Argument ist eine Bitmaske, die sich aus einer beliebigen Kombination von folgenden Werten zusammensetzt. Mehrere Werte können mit OR verknüpft werden, um mehrere Operationen mit einem einzigen Aufruf zu erledigen.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

int mysql_reload(MYSQL *mysql)

Beschreibung

Veranlasst den MySQL Server, die Berechtigungstabellen neu zu laden. Der verbundene Benutzer benötigt hierzu das RELOAD-Recht.

Diese Funktion ist veraltet. Bitte benutzen Sie stattdessen mysql_query(), um die SQL-Anweisung FLUSH PRIVILEGES zu erteilen.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

my_bool mysql_rollback(MYSQL *mysql)

Beschreibung

Rollt die aktuelle Transaktion zurück.

Was diese Funktion tut, hängt von dem Wert der Systemvariablen completion_type ab. Wenn der Wert von completion_type 2 ist, gibt der Server nach dem Abschluss der Transaktion Ressourcen frei und schließt die Clientverbindung. Das Clientprogramm sollte mysql_close() aufrufen, um die Verbindung auf der Clientseite zu schließen.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

Keine.

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

Beschreibung

Setzt den Zeilen-Cursor auf eine beliebige Zeile in der Ergebnismenge einer Anfrage. Der offset-Wert ist ein Zeilen-Offset. Dieser sollte ein von mysql_row_tell() oder mysql_row_seek() zurückgegebener Wert sein. Er ist keine Zeilennummer; wenn Sie eine Zeile einer Ergebnismenge anhand ihrer Nummer suchen möchten, müssen Sie stattdessen mysql_data_seek() aufrufen.

Da für diese Funktion erforderlich ist, dass die Ergebnismengenstruktur das gesamte Anfrageergebnis enthält, kann mysql_row_seek() nur in Verbindung mit mysql_store_result() und nicht mit mysql_use_result() benutzt werden.

Rückgabewerte

Der vorherige Wert des Zeilen-Cursors. Dieser Wert kann an einen nachfolgenden mysql_row_seek()-Aufruf übergeben werden.

Fehler

Keine.

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

Beschreibung

Gibt die aktuelle Position des Zeilen-Cursors für den letzten mysql_fetch_row()-Aufruf zurück. Dieser Wert kann als Argument an mysql_row_seek() übergeben werden.

Verwenden Sie mysql_row_tell() bitte nur nach mysql_store_result() und nicht nach mysql_use_result().

Rückgabewerte

Der aktuelle Offset des Zeilen-Cursors.

Fehler

Keine.

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

Beschreibung

Macht die Datenbank db zur Standarddatenbank auf der durch mysql angegebenen Verbindung. In den nachfolgenden Anfragen ist diese Datenbank der Standard für Tabellenreferenzen, die keine explizite Datenbankbezeichnung enthalten.

mysql_select_db() funktioniert nur, wenn der verbundene Benutzer mit der Berechtigung, die Datenbank zu nutzen, authentifiziert werden kann.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

int mysql_set_character_set(MYSQL *mysql, char *csname)

Beschreibung

Diese Funktion stellt den Standardzeichensatz für die laufende Verbindung ein. Der String csname ist ein gültiger Zeichensatzname. Die Sortierreihenfolge der Verbindung wird die Standardsortierreihenfolge dieses Zeichensatzes. Die Funktion arbeitet wie die SET NAMES-Anweisung, stellt jedoch auch den Wert von mysql->charset ein und beeinflusst dadurch den von mysql_real_escape_string() verwendeten Zeichensatz.

Diese Funktion wurde in MySQL 5.0.7 hinzugefügt.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Beispiel

MYSQL mysql;

mysql_init(&mysql);
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

if (!mysql_set_charset_name(&mysql, "utf8")) 
{
    printf("New client character set: %s\n", mysql_character_set_name(&mysql));
}

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

Beschreibung

Aktiviert oder deaktiviert eine Verbindungsoption. option kann einen der folgenden Werte haben:

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

int mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)

Beschreibung

Veranlasst den Datenbankserver, herunterzufahren. Der Benutzer der Verbindung muss dieSHUTDOWN-Rechte besitzen. MySQL 5.1 Server unterstützen nur eine einzige Art von Shutdown; der shutdown_level muss der SHUTDOWN_DEFAULT sein. Wir planen, noch weitere Shutdown-Level einzuführen, um eine Wahlmöglichkeit zu eröffnen. Dynamisch verlinkte Executables, die mit älteren Versionen der libmysqlclient-Header kompiliert wurden und mysql_shutdown() aufrufen, müssen mit der älteren dynamischen Bibliothek libmysqlclient benutzt werden.

Der Shutdown-Prozess wird in Abschnitt 5.2.6, „Herunterfahren des MySQL Servers“, beschrieben.

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

Fehler

const char *mysql_sqlstate(MYSQL *mysql)

Beschreibung

Gibt einen auf null endenden String mit dem SQLSTATE-Fehlercode für den letzten Fehler zurück. Der Fehlercode besteht aus fünf Zeichen. '00000' bedeutet „kein Fehler“. Die Werte sind durch ANSI-SQL und ODBC spezifiziert. Eine Liste der möglichen Werte finden Sie unter Anhang B, Fehlercodes und -meldungen.

Beachten Sie, dass sich nicht alle MySQL-Fehler SQLSTATE-Fehlercodes zuordnen lassen. Der Wert 'HY000' (allgemeiner Fehler) wird für Fehler verwendet, die nicht zuzuordnen sind.

Rückgabewerte

Ein auf null endender Zeichen-String mit dem SQLSTATE-Fehlercode.

Siehe auch

Siehe Abschnitt 24.2.3.14, „mysql_errno()“, Abschnitt 24.2.3.15, „mysql_error()“, und Abschnitt 24.2.7.26, „mysql_stmt_sqlstate()“.

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

Beschreibung

mysql_ssl_set() richtet sichere SSL-Verbindungen ein. Diese Funktion muss vor mysql_real_connect() aufgerufen werden.

mysql_ssl_set() arbeitet nur, wenn in der Clientbibliothek die OpenSSL-Unterstützung aktiviert ist.

mysql ist der Verbindungs-Handler, der von mysql_init() zurückgegeben wird. Die anderen Parameter sind folgendermaßen spezifiziert:

Ungenutzte SSL-Parameter können mit NULL angegeben werden.

Rückgabewerte

Diese Funktion liefert immer 0. Wenn SSL verkehrt eingerichtet ist, gibt mysql_real_connect() bei Verbindungsversuchen einen Fehler zurück.

char *mysql_stat(MYSQL *mysql)

Beschreibung

Gibt einen Zeichen-String mit ähnlichen Informationen wie der Befehl mysqladmin status zurück. Dazu gehört die Uptime in Sekunden und die Anzahl der laufenden Threads, Fragen, Reloads und offenen Tabellen.

Rückgabewerte

Ein Zeichen-String, der 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, CHECK TABLE, und so weiter).

Für andere Anfragen brauchen Sie mysql_store_result() oder mysql_use_result() nicht zu verwenden, aber es schadet auch nichts und bringt keine spürbaren Leistungseinbußen, wenn Sie in jedem Fall mysql_store_result() aufrufen. Sie können erkennen, ob die Anfrage eine Ergebnismenge hatte oder nicht, indem Sie prüfen, ob mysql_store_result() 0 zurückgibt (darüber später mehr).

Wenn Sie wissen möchten, ob die Anfrage eine Ergebnismenge zurückgeben müsste, prüfen Sie dies mit mysql_field_count(). Siehe Abschnitt 24.2.3.22, „mysql_field_count()“.

mysql_store_result() liest das gesamte Anfrageergebnis auf den Client ein, weist eine MYSQL_RES-Struktur zu und setzt das Resultat in diese Struktur ein.

mysql_store_result() liefert einen Nullzeiger, wenn die Anfrage keine Ergebnismenge zurückgab (also beispielsweise eine INSERT-Anweisung war).

mysql_store_result() liefert auch einen Nullzeiger, wenn die Ergebnismenge nicht gelesen werden konnte. Ein Fehler ist aufgetreten, wenn mysql_error() einen nichtleeren String oder einen von null verschiedenen Wert liefert oder wenn mysql_field_count() null zurückgibt.

Eine leere Ergebnismenge bedeutet, dass keine Zeilen zurückgegeben wurden. (Eine leere Ergebnismenge ist etwas anderes als ein Nullzeiger als Rückgabewert.)

Wenn Sie mysql_store_result() aufgerufen und ein Ergebnis erhalten haben, das kein Nullzeiger ist, können Sie mit mysql_num_rows() ermitteln, wie viele Zeilen die Ergebnismenge hat.

Sie können mit mysql_fetch_row() Zeilen aus der Ergebnismenge abrufen oder mit mysql_row_seek() und mysql_row_tell() die aktuelle Zeilenposition in der Ergebnismenge ermitteln oder einstellen.

Wenn Sie mit der Ergebnismenge fertig sind, rufen Sie mysql_free_result() auf.

Siehe Abschnitt 24.2.13.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 Resultaten. NULL, wenn ein Fehler auftrat.

Fehler

Die Funktion mysql_store_result() setzt mysql_error() und mysql_errno() zurück, wenn sie erfolgreich gelaufen ist.

unsigned long mysql_thread_id(MYSQL *mysql)

Beschreibung

Gibt die Thread-ID der aktuellen Verbindung zurück. Dieser Wert kann als Argument für mysql_kill() verwendet werden, um den Thread anzuhalten.

Wenn die Verbindung abgebrochen ist und Sie sich mit mysql_ping() erneut zu verbinden versuchen, ändert sich die Thread-ID. Daher sollten Sie keine Thread-ID zur späteren Benutzung speichern, sondern sie erst dann erfragen, wenn Sie sie benötigen.

Rückgabewerte

Die Thread-ID 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 den Abruf einer Ergebnismenge, lädt sie jedoch im Gegensatz zu mysql_store_result() nicht komplett auf den Client herunter. Stattdessen wird jede Zeile einzeln mit einem Aufruf von mysql_fetch_row() abgefragt. So wird ein Anfrageergebnis direkt vom Server gelesen, ohne es in einer temporären Tabelle oder in einem lokalen Puffer zwischenzuspeichern. Das geht schneller und belegt weniger Speicher als mysql_store_result(). Der Client weist nur für die aktuelle Zeile Speicher zu und reserviert einen Kommunikationspuffer, der bis zur Größe von max_allowed_packet Bytes anwachsen kann.

Demgegenüber sollten Sie mysql_use_result() nicht verwenden, wenn Sie jede Zeile auf der Clientseite aufwändig vearbeiten oder die Ausgabe an einen Bildschirm senden, in den der Benutzer ^S (Stop Scroll) eintippen kann. Dies würde den Server sperren und verhindern, dass andere Threads Tabellen aktualisieren können, aus denen die Daten abgerufen werden.

Wenn Sie mit mysql_use_result() arbeiten, müssen Sie mysql_fetch_row() so oft ausführen, bis ein NULL-Wert zurückgeliefert wird. Sonst werden die nicht abgerufenen Zeilen zu einem Teil der Ergebnismenge der nächsten Anfrage. Wenn Sie dies vergessen, meldet die C-API den Fehler Commands out of sync; you can't run this command now!

Die Funktionen mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_rows() oder mysql_affected_rows() können nicht mit einer Ergebnisrückgabe von mysql_use_result() benutzt werden. Ebenso wenig können Sie andere Anfragen absetzen, bevor die Funktion mysql_use_result() ihre Arbeit beendet hat. (Immerhin liefert mysql_num_rows() ein akkurates Ergebnis, wenn Sie alle Zeilen abgeholt haben.)

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

Bei Verwendung des Embedded Servers libmysqld geht der Vorteil des geringen Speicherbedarfs verloren, da die Speicherbelegung inkrementell mit jeder abgeholten Zeile anwächst, bis Sie mysql_free_result() aufrufen.

Rückgabewerte

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

Fehler

mysql_use_result() setzt bei Erfolg mysql_error() und mysql_errno() zurück.

unsigned int mysql_warning_count(MYSQL *mysql)

Beschreibung

Gibt die Anzahl der während der Ausführung der vorangegangenen SQL-Anweisung ausgelösten Warnungen zurück.

Rückgabewerte

Die Anzahl der Warnungen.

Fehler

Keine.

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

Beschreibung

Diese Funktion gibt die Gesamtzahl der von der zuletzt ausgeführten Anweisung geänderten, gelöschten oder eingefügten Zeilen zurück. Für UPDATE-, DELETE- oder INSERT-Anweisungen kann sie unmittelbar nach mysql_stmt_execute() aufgerufen werden. Für SELECT-Anweisungen arbeitet mysql_stmt_affected_rows() genau wie mysql_num_rows().

Rückgabewerte

Ein Integer größer null zeigt die Anzahl der betroffenen oder abgerufenen Zeilen an. Null zeigt für eine UPDATE-Anweisung an, dass keine Zeilen aktualisiert wurden, für eine WHERE-Klausel in der Anfrage, dass keine Zeilen gepasst haben, oder ansonsten, dass die Anfrage noch gar nicht ausgeführt wurde. -1 bedeutet, dass die Anfrage einen Fehler zurückgeliefert hat oder, bei einer SELECT-Anfrage, dass mysql_stmt_affected_rows() vor mysql_stmt_store_result() aufgerufen wurde. Da mysql_stmt_affected_rows() einen vorzeichenlosen Wert liefert, können Sie -1 überprüfen, indem Sie den Rückgabewert mit (my_ulonglong)-1 (oder dem Äquivalent (my_ulonglong)~0) vergleichen.

Weitere Informationen über den Rückgabewert finden Sie unter Abschnitt 24.2.3.1, „mysql_affected_rows()“.

Fehler

Keine.

Beispiel

Ein Anwendungsbeispiel für mysql_stmt_affected_rows() finden Sie im Beispiel von Abschnitt 24.2.7.10, „mysql_stmt_execute()“.

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

Beschreibung

Kann genutzt werden, um den aktuellen Wert eines Anweisungsattributs abzufragen.

Das option-Argument ist die abzufragende Option; das arg sollte auf eine Variable mit dem Optionswert verweisen. Wenn die Option ein Integer ist, sollte arg auf den Wert dieses Integers verweisen.

Eine Liste aller Optionen und Optionstypen finden Sie unter Abschnitt 24.2.7.3, „mysql_stmt_attr_set()“.

Rückgabewerte

0, wenn alles okay ist. Ein von null verschiedener Wert, wenn option unbekannt ist.

Fehler

Keine.

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

Beschreibung

Kann genutzt werden, um das Verhalten einer vorbereiteten Anweisung zu beeinflussen. Diese Funktion kann auch mehrmals aufgerufen werden, um mehrere Optionen zu setzen.

Das option-Argument ist die Option, die Sie einstellen möchten, und arg ist ihr Wert. Wenn die Option ein Integer ist, muss arg auf den Wert eines Integers verweisen.

Mögliche option-Werte:

Wenn Sie die Option STMT_ATTR_CURSOR_TYPE mit CURSOR_TYPE_READ_ONLY verwenden, wird ein Cursor für die Anweisung geöffnet, sobald Sie mysql_stmt_execute() aufrufen. Existiert bereits ein geöffneter Cursor aus einem früheren mysql_stmt_execute()-Aufruf, schließt die Option diesen Cursor, bevor ein neuer geöffnet wird. Die Funktion mysql_stmt_reset() schließt auch offene Cursors, bevor sie die Anweisung zur erneuten Ausführung vorbereitet. mysql_stmt_free_result() schließt ebenfalls einen eventuell noch offenen Cursor.

Wenn Sie einen Cursor für eine vorbereitete Anweisung öffnen, ist mysql_stmt_store_result() überflüssig, da diese Funktion die Ergebnismenge auf der Clientseite puffern lässt.

Die Option STMT_ATTR_CURSOR_TYPE wurde in MySQL 5.0.2 hinzugefügt. Die Option STMT_ATTR_PREFETCH_ROWS wurde in MySQL 5.0.6 hinzugefügt.

Rückgabewerte

0, wenn alles okay ist. Ein von null verschiedener Wert, wenn option unbekannt ist.

Fehler

Keine.

Beispiel

Das folgende Beispiel öffnet einen Cursor für eine vorbereitete Anweisung und setzt die Anzahl der in einem Schwung abzuholenden Zeilen auf 5:

MYSQL_STMT *stmt;
int rc;
unsigned long type;
unsigned long prefetch_rows = 5;

stmt = mysql_stmt_init(mysql);
type = (unsigned long) CURSOR_TYPE_READ_ONLY;
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &type);
/* ... prüfe Rückgabewert... */
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS,
                         (void*) &prefetch_rows);
  /* ... prüfe Rückgabewert ... */

my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Beschreibung

Die Funktion mysql_stmt_bind_param() bindet Daten an die Parametermarker in der SQL-Anweisung, die an mysql_stmt_prepare() übergeben wurde. Zur Übergabe der Daten verwendet sie MYSQL_BIND-Strukturen. bind ist die Adresse eines Arrays von MYSQL_BIND-Strukturen. Die Clientbibliothek erwartet, dass das Array für jeden ‘?’-Parametermarker in der Anfrage einen Wert enthält.

Angenommen, Sie bereiten folgende Anweisung vor:

INSERT INTO mytbl VALUES(?,?,?)

Wenn Sie die Parameter binden, muss das Array von MYSQL_BIND-Strukturen drei Elemente enthalten. Es kann wie folgt deklariert werden:

MYSQL_BIND bind[3];

Die Bestandteile jedes MYSQL_BIND-Elements, das gesetzt werden muss, sind in Abschnitt 24.2.5, „C-API: Prepared Statement-Datentypen“, beschrieben.

Rückgabewerte

Null, wenn das Binden erfolgreich verlief. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Beispiel

Wie man mysql_stmt_bind_param() verwendet, sehen Sie im Beispiel von Abschnitt 24.2.7.10, „mysql_stmt_execute()“.

my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Beschreibung

mysql_stmt_bind_result() bindet Spalten der Ergebnismenge an Daten- und Längenpuffer. Wenn Daten mit mysql_stmt_fetch() abgeholt werden, setzt das MySQL-Client/Server-Protokoll die Daten für gebundene Spalten in die angegebenen Puffer ein.

Alle Spalten müssen an ihre Puffer gebunden sein, bevor mysql_stmt_fetch() aufgerufen wird. bind ist die Adresse eines Arrays von MYSQL_BIND-Strukturen. Die Clientbibliothek erwartet, dass dieses Array für jede Spalte der Ergebnismenge ein Element enthält. Wenn Sie es versäumen, Spalten an MYSQL_BIND-Strukturen zu binden, ignoriert mysql_stmt_fetch() einfach den Datenabruf. Die Puffer sollten groß genug sein, um die Datenwerte speichern zu können, da dieses Protokoll die Daten nicht stückweise zurückgeben kann.

Eine Spalte kann jederzeit gebunden oder neu gebunden werden, auch dann, wenn eine Ergebnismenge teilweise abgeholt wurde. Die neue Bindung tritt beim nächsten Aufruf von mysql_stmt_fetch() in Kraft. Nehmen wir an, eine Anwendung bindet die Spalten in einer Ergebnismenge und ruft mysql_stmt_fetch() auf. Das Client/Server-Protokoll liefert die Daten in die gebundenen Puffer. Wenn die Anwendung nun aber die Spalten an andere Puffer bindet, schreibt das Protokoll die Daten erst beim nächsten Aufruf von mysql_stmt_fetch() in diese anderen Puffer.

Um eine Spalte zu binden, ruft eine Anwendung mysql_stmt_bind_result() auf und übergibt den Typ, die Adresse und die Adresse des Längenpuffers. Die Bestandteile der MYSQL_BIND-Elemente sollten so eingestellt werden wie in Abschnitt 24.2.5, „C-API: Prepared Statement-Datentypen“, beschrieben.

Rückgabewerte

Null, wenn das Binden erfolgreich verlief. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Beispiel

Die Verwendung von mysql_stmt_bind_result() wird im Beispiel von Abschnitt 24.2.7.11, „mysql_stmt_fetch()“, gezeigt.

my_bool mysql_stmt_close(MYSQL_STMT *)

Beschreibung

Schließt die vorbereitete Anweisung. Außerdem gibt mysql_stmt_close() den Anweisungs-Handle von stmt frei.

Wenn die aktuelle Anweisung noch ausstehende oder ungelesene Ergebnisse hat, werden sie durch diese Funktion annulliert, damit die nächste Anfrage ausgeführt werden kann.

Rückgabewerte

Null, wenn die Anweisung erfolgreich freigegeben wurde. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Beispiel

Die Anwendung von mysql_stmt_close() sehen Sie im Beispiel zu Abschnitt 24.2.7.10, „mysql_stmt_execute()“.

void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)

Beschreibung

Findet eine beliebige Zeile in einer Ergebnismenge einer Anweisung. Der offset-Wert ist eine Zeilennummer zwischen 0 und mysql_stmt_num_rows(stmt)-1.

Für diese Funktion ist erforderlich, dass die Ergebnismengenstruktur der Anweisung das gesamte Ergebnis der zuletzt ausgeführten Anfrage enthält. Daher kann mysql_stmt_data_seek() nur in Verbindung mit mysql_stmt_store_result() eingesetzt werden.

Rückgabewerte

Keine.

Fehler

Keine.

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

Beschreibung

Für die durch stmt spezifizierte Anweisung liefert mysql_stmt_errno() den Fehlercode der zuletzt aufgerufenen Anweisungs-API-Funktion, die erfolgreich laufen oder scheitern kann. Null wird zurückgegeben, wenn kein Fehler auftrat. Die Nummern der Clientfehlermeldungen sind in der MySQL-Header-Datei errmsg.h aufgeführt. Die Nummern der Serverfehlermeldungen finden Sie in mysqld_error.h. Außerdem sind die Fehler in Anhang B, Fehlercodes und -meldungen, aufgelistet.

Rückgabewerte

Der Wert eines Fehlercodes. Null, wenn kein Fehler auftrat.

Fehler

Keine.

const char *mysql_stmt_error(MYSQL_STMT *stmt)

Beschreibung

Für die durch stmt spezifizierte Anweisung liefert mysql_stmt_error() einen auf null endenden String mit der Fehlermeldung für die zuletzt aufgerufene Anweisungs-API-Funktion, die erfolgreich laufen oder scheitern kann. Ein leerer String ("") wird zurückgegeben, wenn kein Fehler auftrat. Das bedeutet, dass die beiden folgenden Tests äquivalent sind:

if (mysql_stmt_errno(stmt))
{
  // Ein Fehler trat auf
}

if (mysql_stmt_error(stmt)[0])
{
  // Ein Fehler trat auf
}

Die Sprache der Clientfehlermeldungen kann sich durch Rekompilieren der MySQL-Clientbibliothek ändern. Zurzeit haben Sie die Wahl zwischen Fehlermeldungen in mehreren verschiedenen Sprachen.

Rückgabewerte

Ein Zeichen-String, der den Fehler beschreibt. Ein leerer String, wenn kein Fehler auftrat.

Fehler

Keine.

int mysql_stmt_execute(MYSQL_STMT *stmt)

Beschreibung

mysql_stmt_execute() führt die vorbereitete Anfrage aus, die zu dem Anweisungs-Handle gehört. Die aktuellen Werte der gebundenen Parametermarker werden bei diesem Aufruf an den Server geschickt, und der Server ersetzt die Marker durch die frisch gelieferten Daten.

Wenn die Anweisung ein UPDATE, DELETE oder INSERT ist, erfahren Sie durch einen Aufruf von mysql_stmt_affected_rows(), wie viele Zeilen geändert, gelöscht oder eingefügt wurden. Ist es eine Anweisung wie SELECT, die eine Ergebnismenge generiert, müssen Sie zuerst mit mysql_stmt_fetch() die Daten abholen, bevor Sie irgendwelche Funktionen aufrufen, um die Anfrage zu verarbeiten. Weitere Informationen über den Abruf von Ergebnissen finden Sie in Abschnitt 24.2.7.11, „mysql_stmt_fetch()“.

Für Anweisungen, die eine Ergebnismenge generieren, können Sie verlangen, dass mysql_stmt_execute() einen Cursor öffnet, indem Sie vor Ausführung der Anweisung mysql_stmt_attr_set() aufrufen. Wenn Sie eine Anweisung mehrmals ausführen, schließt mysql_stmt_execute() einen eventuell noch offenen Cursor, ehe es einen neuen öffnet.

Rückgabewerte

Null, wenn die Ausführung Erfolg hatte. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Beispiel

Das folgende Beispiel zeigt, wie eine Tabelle mithilfe von mysql_stmt_init(), mysql_stmt_prepare(), mysql_stmt_param_count(), mysql_stmt_bind_param(), mysql_stmt_execute() und mysql_stmt_affected_rows() angelegt und mit Daten gefüllt wird. Die mysql-Variable sei ein gültiger Verbindungs-Handle.

#define STRING_SIZE 50

#define DROP_SAMPLE_TABLE "DROP TABLE IF EXISTS test_table"
#define CREATE_SAMPLE_TABLE "CREATE TABLE test_table(col1 INT,\
                                                 col2 VARCHAR(40),\
                                                 col3 SMALLINT,\
                                                 col4 TIMESTAMP)"
#define INSERT_SAMPLE "INSERT INTO test_table(col1,col2,col3) VALUES(?,?,?)"

MYSQL_STMT    *stmt;
MYSQL_BIND    bind[3];
my_ulonglong  affected_rows;
int           param_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
unsigned long str_length;
my_bool       is_null;

if (mysql_query(mysql, DROP_SAMPLE_TABLE))
{
  fprintf(stderr, " DROP TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}

if (mysql_query(mysql, CREATE_SAMPLE_TABLE))
{
  fprintf(stderr, " CREATE TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}

/* Bereite eine INSERT-Anfrage mit 3 Parametern vor */
/* (Die TIMESTAMP-Spalte ist nicht benannt; der Server */
/*  stellt sie auf das aktuelle Datum und die Uhrzeit ein.) */
stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_SAMPLE, strlen(INSERT_SAMPLE)))
{
  fprintf(stderr, " mysql_stmt_prepare(), INSERT failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
fprintf(stdout, " prepare, INSERT successful\n");

/* Hole die Zahl der Parameter aus der Anweisung */
param_count= mysql_stmt_param_count(stmt);
fprintf(stdout, " total parameters in INSERT: %d\n", param_count);

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

/* Binde die Daten für alle 3 Parameter */

memset(bind, 0, sizeof(bind));

/* INTEGER PARAM */
/* Da dies ein Zahlentyp ist, muss buffer_length nicht angegeben werden */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= 0;
bind[0].length= 0;

/* STRING PARAM */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= 0;
bind[1].length= &str_length;

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

/* Binde die Puffer */
if (mysql_stmt_bind_param(stmt, bind))
{
  fprintf(stderr, " mysql_stmt_bind_param() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Gib Datenwerte für die erste Zeile an */
int_data= 10;             /* Integer */
strncpy(str_data, "MySQL", STRING_SIZE); /* String  */
str_length= strlen(str_data);

/* INSERT SMALLINT-Daten als NULL */
is_null= 1;

/* Führe die INSERT-Anweisung aus - 1*/
if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_execute(), 1 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Hole Gesamtzahl der betroffenen Zeilen */
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 1): %lu\n",
                (unsigned long) affected_rows);

if (affected_rows != 1) /* validiere betroffene Zeilen */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}

/* Gib Datenwerte für zweite Zeile an und führe Anweisung erneut aus */
int_data= 1000;
strncpy(str_data, "The most popular Open Source database", STRING_SIZE);
str_length= strlen(str_data);
small_data= 1000;         /* smallint */
is_null= 0;               /* Zurücksetzen */

/* Führe die INSERT-Anweisung aus - 2*/
if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_execute, 2 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

  /* Hole Gesamtzahl der betroffenen Zeilen */
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 2): %lu\n",
                (unsigned long) affected_rows);

  if (affected_rows != 1) /* validiere betroffene Zeilen */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}

/* Schließe die Anweisung */
if (mysql_stmt_close(stmt))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

Hinweis: Vollständigere Beispiele für die Nutzung von Funktionen für vorbereitete Anweisungen finden Sie in der Datei tests/mysql_client_test.c. Diese liegt in der MySQL-Quelldistribution und im BitKeeper-Quellarchiv.

int mysql_stmt_fetch(MYSQL_STMT *stmt)

Beschreibung

Die Funktion mysql_stmt_fetch() liefert die nächste Zeile der Ergebnismenge und kann nur aufgerufen werden, während die Ergebnismenge besteht, also nach einem mysql_stmt_execute()-Aufruf, der eine Ergebnismenge produziert, oder nach einem mysql_stmt_store_result()-Aufruf, der im Anschluss an mysql_stmt_execute() die gesamte Ergebnismenge puffert.

Die Funktion mysql_stmt_fetch() liefert Zeilendaten über alle Spalten der aktuellen Zeilenmenge an die in mysql_stmt_bind_result() gebundenen Puffer. Die Längen werden an den length-Zeiger zurückgegeben.

Alle Spalten müssen von der Anwendung gebunden werden, ehe mysql_stmt_fetch() aufgerufen werden kann.

Ist ein abgerufener Datenwert NULL, ist der *is_null-Wert der zugehörigen MYSQL_BIND-Struktur TRUE (1). Andernfalls werden die Daten und ihre Länge in die Elemente *buffer und *length zurückgegeben, und zwar basierend auf dem von der Anwendung angegebenen Puffertyp. Jeder numerische und temporale Typ hat eine festgelegte Länge, wie in der folgenden Tabelle angegeben. Die Länge von String-Typen hängt von der Länge des tatsächlichen Datenwerts ab, wie in data_length angegeben.

Rückgabewerte

MYSQL_DATA_TRUNCATED-Meldungen werden nur zurückgegeben, wenn dies mit mysql_options() eingestellt wurde. Um bei einer Rückgabe dieses Werts festzustellen, welche Daten abgeschnitten wurden, schauen Sie sich die error-Bestandteile der MYSQL_BIND-Parameterstrukturen an.

Fehler

Beispiel

Das folgende Beispiel zeigt, wie man Daten aus einer Tabelle mit mysql_stmt_result_metadata(), mysql_stmt_bind_result() und mysql_stmt_fetch() abholt. (Es wird erwartet, dass mit diesem Beispiel die beiden Zeilen abgerufen werden, die in Abschnitt 24.2.7.10, „mysql_stmt_execute()“, eingefügt wurden.) Die Variable mysql sei ein gültiger Verbindungs-Handle.

#define STRING_SIZE 50

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

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

/* SELECT-Anfrage vorbereiten, um Daten aus test_table zu holen*/
stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, SELECT_SAMPLE, strlen(SELECT_SAMPLE)))
{
  fprintf(stderr, " mysql_stmt_prepare(), SELECT failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
fprintf(stdout, " prepare, SELECT successful\n");

/* Hole Zahl der Parameter aus der Anweisung */
param_count= mysql_stmt_param_count(stmt);
fprintf(stdout, " total parameters in SELECT: %d\n", param_count);

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

/* Hole Metainformationen zur Ergebnismenge */
prepare_meta_result = mysql_stmt_result_metadata(stmt);
if (!prepare_meta_result)
{
  fprintf(stderr,
         " mysql_stmt_result_metadata(), returned no meta information\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Hole Gesamtzahl der Spalten in der Anfrage */
column_count= mysql_num_fields(prepare_meta_result);
fprintf(stdout, " total columns in SELECT statement: %d\n", column_count);

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

/* Führe die SELECT-Anfrage aus */
if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_execute(), failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Binde die Ergebnispuffer für alle 4 Spalten, bevor sie abgeholt werden */

memset(bind, 0, sizeof(bind));

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

/* STRING COLUMN */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= &is_null[1];
bind[1].length= &length[1];

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

/* TIMESTAMP COLUMN */
bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
bind[3].buffer= (char *)&ts;
bind[3].is_null= &is_null[3];
bind[3].length= &length[3];

/* Binde die Ergebnispuffer */
if (mysql_stmt_bind_result(stmt, bind))
{
  fprintf(stderr, " mysql_stmt_bind_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Alle Ergebnisse auf dem Client zwischenspeichern */
if (mysql_stmt_store_result(stmt))
{
  fprintf(stderr, " mysql_stmt_store_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Alle Zeilen abholen */
row_count= 0;
fprintf(stdout, "Fetching results ...\n");
while (!mysql_stmt_fetch(stmt))
{
  row_count++;
  fprintf(stdout, "  row %d\n", row_count);

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

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

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

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

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

/* Vorbereitete Ergebnismetadaten freigeben */
mysql_free_result(prepare_meta_result);


/* Anweisung schließen */
if (mysql_stmt_close(stmt))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

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

Beschreibung

Holt eine Spalte aus der aktuellen Zeile der Ergebnismenge. bind sagt, in welchen Puffer die Daten geschrieben werden sollen. Dieser sollte wie für mysql_stmt_bind_result() eingestellt sein. column gibt an, welche Spalte abgefragt wird. Die erste Spalte hat die Nummer 0. offset ist der Offset im Datenwert, wo der Datenabruf beginnen soll. Dieser kann genutzt werden, um die Daten stückweise abzuholen. Der Anfang des Werts hat den Offset 0.

Rückgabewerte

Null, wenn der Wert erfolgreich abgeholt wurde. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)

Beschreibung

Liefert die Anzahl der Spalten für die letzte Anweisung des Anweisungs-Handlers. Dieser Wert ist für Anweisungen wie INSERT oder DELETE, die keine Ergebnismengen produzieren, null.

mysql_stmt_field_count() kann nach der Vorbereitung einer Anweisung mit mysql_stmt_prepare() aufgerufen werden.

Rückgabewerte

Ein vorzeichenloser Integer, der die Anzahl der Spalten in einer Ergebnismenge angibt.

Fehler

Keine.

my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)

Beschreibung

Gibt den Speicher für die Ergebnismenge frei, die von der Ausführung der vorbereiteten Anweisung erstellt wurde. Wenn noch ein Cursor für die Anweisung geöffnet ist, wird er von mysql_stmt_free_result() geschlossen.

Rückgabewerte

Null, wenn die Ergebnismenge erfolgreich freigegeben wurde, und ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

(nicht verfügbar)

MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)

Beschreibung

Erzeugt einen MYSQL_STMT-Handle. Der Handle sollte mit mysql_stmt_close(MYSQL_STMT *) wieder freigegeben werden.

Rückgabewerte

Bei Erfolg ein Zeiger auf eine MYSQL_STMT-Struktur. Bei einem Speicherüberlauf NULL.

Fehler

my_ulonglong mysql_stmt_insert_id(MYSQL_STMT *stmt)

Beschreibung

Gibt den Wert zurück, der für eine AUTO_INCREMENT-Spalte von der vorbereiteten INSERT- oder UPDATE-Anweisung generiert wurde. Diese Funktion verwenden Sie nach Ausführung einer vorbereiteten INSERT-Anweisung auf einer Tabelle, die ein AUTO_INCREMENT-Feld enthält.

Siehe auch Abschnitt 24.2.3.36, „mysql_insert_id()“.

Rückgabewerte

Der Wert der AUTO_INCREMENT-Spalte, der automatisch generiert oder während der Ausführung einer vorbereiteten Anweisung explizit gesetzt wurde, oder der Wert, der von der Funktion LAST_INSERT_ID(expr) generiert wurde. Wenn die Anweisung keinen AUTO_INCREMENT-Wert setzt, ist der Rückgabewert undefiniert.

Fehler

Keine.

my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)

Beschreibung

Liefert die Anzahl der Zeilen in der Ergebnismenge.

mysql_stmt_num_rows() können Sie nur benutzen, wenn Sie die gesamte Ergebnismenge im Anweisungs-Handle mit mysql_stmt_store_result() gepuffert haben.

Wenn Sie mysql_stmt_store_result() verwenden, können Sie mysql_stmt_num_rows() sofort aufrufen.

Rückgabewerte

Die Anzahl der Zeilen in der Ergebnismenge.

Fehler

Keine.

unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)

Beschreibung

Liefert die Anzahl der Parametermarker in der vorbereiteten Anweisung.

Rückgabewerte

Ein vorzeichenloser Long-Integer, der die Anzahl der Parameter in einer Anweisung darstellt.

Fehler

Keine.

Beispiel

Wie man mysql_stmt_param_count() einsetzt, sehen Sie im Beispiel zu Abschnitt 24.2.7.10, „mysql_stmt_execute()“.

MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)

Diese Funktion tut zurzeit gar nichts.

Beschreibung

Rückgabewerte

Fehler

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

Beschreibung

Wenn man ihr den von mysql_stmt_init() gelieferten Anweisungs-Handle übergibt, bereitet diese Funktion die SQL-Anweisung vor, auf die der String query verweist, und liefert einen Statuswert. Die Länge des Strings sollte im length-Argument angegeben werden. Der String muss aus einer einzigen SQL-Anweisung bestehen. Bitte fügen Sie am Ende der Anweisung kein Semikolon (‘;’) oder \g an.

Die Anwendung kann einen oder mehrere Parametermarker in die SQL-Anweisung einbinden, indem sie die Fragezeichen (‘?’) an den passenden Stellen in den SQL-String einbettet.

Die Marker sind nur an bestimmten Stellen in den SQL-Anweisungen erlaubt, beispielsweise in der VALUES()-Liste einer INSERT Anweisung (um Spaltenwerte für eine Zeile vorzugeben) oder um einen Vergleichswert zum Vergleich mit einer Spalte einer WHERE-Klausel anzugeben. Sie dürfen jedoch nicht für Bezeichner (wie etwa Tabellen- oder Spaltennamen) oder für die Operanden eines Binäroperators wie etwa des Gleichheitszeichens = benutzt werden. Die zweite Beschränkung ist notwendig, weil es ansonsten unmöglich wäre, den Parametertyp festzustellen. Generell sind Parameter nur in Data Manipulation Language(DML)-Anweisungen und nicht in Data Definition Language(DDL)-Anweisungen zulässig.

Die Parametermarker müssen mit mysql_stmt_bind_param() an die Anwendungsvariablen gebunden werden, bevor die Anweisung ausgeführt wird.

Rückgabewerte

Null, wenn die Anweisung erfolgreich vorbereitet wurde, und ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Wenn die Vorbereitung gescheitert ist (d. h., wenn mysql_stmt_prepare() nicht null zurückliefert), können Sie die Fehlermeldung mit mysql_stmt_error() abrufen.

Beispiel

Wie mysql_stmt_prepare() eingesetzt wird, erfahren Sie im Beispiel von Abschnitt 24.2.7.10, „mysql_stmt_execute()“.

my_bool mysql_stmt_reset(MYSQL_STMT *stmt)

Beschreibung

Setzt die vorbereitete Anweisung auf dem Client und Server in den Zustand zurück, den sie nach der Vorbereitung hatte. Wird vor allen Dingen genutzt, um die mit mysql_stmt_send_long_data() übersandten Daten zurückzusetzen und eventuell noch offene Anweisungs-Cursors zu schließen.

Um die Anweisung mit einer anderen Anfrage erneut vorzubereiten, rufen Sie mysql_stmt_prepare() auf.

Rückgabewerte

Null, wenn die Anweisung erfolgreich zurückgesetzt wurde, und ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)

Beschreibung

Wenn an mysql_stmt_prepare() eine Anweisung übergeben wird, die eine Ergebnismenge produziert, liefert mysql_stmt_result_metadata() die Metadaten zu dieser Ergebnismenge in Form eines Zeigers auf eine MYSQL_RES-Struktur, die genutzt werden kann, um solche Daten wie etwa die Gesamtzahl der Felder und Informationen über einzelne Felder zu verarbeiten. Dieser Ergebnismengenzeiger kann als Argument an API-Feldfunktionen übergeben werden, die Metadaten von Ergebnismengen verarbeiten, wie zum Beispiel:

Die Ergebnismengenstruktur sollte nach Abschluss der Verarbeitung freigegeben werden, indem man sie an mysql_free_result() übergibt. Auf dieselbe Weise wird eine Ergebnismenge aus einem mysql_store_result()-Aufruf freigegeben.

Die von mysql_stmt_result_metadata() zurückgegebene Ergebnismenge enthält nur Metadaten und keine Ergebniszeilen. Diese rufen Sie ab, indem Sie den Anweisungs-Handle in Verbindung mit mysql_stmt_fetch() benutzen.

Rückgabewerte

Eine MYSQL_RES-Ergebnisstruktur oder NULL, wenn keine Metainformationen über die vorbereitete Anfrage existieren.

Fehler

Beispiel

Die Benutzung von mysql_stmt_result_metadata() wird aus dem Beispiel von Abschnitt 24.2.7.11, „mysql_stmt_fetch()“, ersichtlich.

MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)

Beschreibung

Setzt den Zeilen-Cursor auf eine beliebige Zeile in der Ergebnismenge einer Anweisung. Der offset-Wert ist ein Zeilen-Offset. Dieser sollte ein Rückgabewert von mysql_stmt_row_tell() oder von mysql_stmt_row_seek() sein. Er ist keine Zeilennummer; wenn Sie in einer Ergebnismenge eine Zeile anhand ihrer Nummer ausfindig machen möchten, verwenden Sie stattdessen mysql_stmt_data_seek().

Da für diese Funktion erforderlich ist, dass die Ergebnismengenstruktur die gesamte Ergebnismenge der Anfrage enthält, kann mysql_stmt_row_seek() nur in Verbindung mit mysql_stmt_store_result() benutzt werden.

Rückgabewerte

Der vorherige Wert des Zeilen-Cursors. Dieser Wert kann an einen nachfolgenden mysql_stmt_row_seek()-Aufruf übergeben werden.

Fehler

Keine.

MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)

Beschreibung

Gibt die aktuelle Position des Zeilen-Cursors für die letzte mysql_stmt_fetch()-Operation zurück. Dieser Wert kann als Argument für mysql_stmt_row_seek() verwendet werden.

mysql_stmt_row_tell() sollte nur nach mysql_stmt_store_result() benutzt werden.

Rückgabewerte

Der aktuelle Offset des Zeilen-Cursors.

Fehler

Keine.

my_bool mysql_stmt_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, unsigned long length)

Beschreibung

Ermöglicht es einer Anwendung, Parameterdaten in Stücken (oder „Chunks“) an den Server zu schicken. Diese Funktion kann mehrmals aufgerufen werden, um die Teile eines Zeichen- oder Binärdatenwerts für eine Spalte zu übergeben. Die Werte müssen den Datentyp TEXT oder BLOB haben.

parameter_number gibt an, mit welchem Parameter die Daten verbunden werden sollen. Die Parameter werden beginnend mit 0 nummeriert. data ist ein Zeiger auf einen Puffer, der die zu übermittelnden Daten enthält, und length ist die Anzahl der Bytes im Puffer.

Hinweis: Der nächste Aufruf von mysql_stmt_execute() ignoriert den Bind-Puffer für alle Parameter, die seit dem letzten mysql_stmt_execute() oder mysql_stmt_reset() mit mysql_stmt_send_long_data() benutzt worden sind.

Wenn Sie die gesendeten Daten zurücksetzen/vergessen möchten, tun Sie dies mit mysql_stmt_reset(). Siehe Abschnitt 24.2.7.21, „mysql_stmt_reset()“.

Rückgabewerte

Null, wenn die Daten erfolgreich an den Server gesandt wurden. Ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

Beispiel

Das folgende Beispiel zeigt, wie die Daten für eine TEXT-Spalte stückchenweise übermittelt werden. Es fügt den Datenwert 'MySQL - The most popular Open Source database' in die Spalte text_column ein. Die Variable mysql sei ein gültiger Verbindungs-Handle.

#define INSERT_QUERY "INSERT INTO test_long_data(text_column) VALUES(?)"

MYSQL_BIND bind[1];
long       length;

smtt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(INSERT_QUERY)))
{
  fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
 memset(bind, 0, sizeof(bind));
 bind[0].buffer_type= MYSQL_TYPE_STRING;
 bind[0].length= &length;
 bind[0].is_null= 0;

/* Binde die Puffer */
if (mysql_stmt_bind_param(stmt, bind))
{
  fprintf(stderr, "\n param bind failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Liefere Daten stückweise an den Server */
 if (!mysql_stmt_send_long_data(stmt,0,"MySQL",5))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Sende das nächste Datenstück */
 if (mysql_stmt_send_long_data(stmt,0," - The most popular Open Source database",40))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Führe nun die Anfrage aus */
 if (mysql_stmt_execute(stmt))
{
  fprintf(stderr, "\n mysql_stmt_execute failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)

Beschreibung

Für die Anweisung stmt liefert mysql_stmt_sqlstate() einen auf null endenden String mit dem SQLSTATE-Fehlercode für die zuletzt aufgerufene Funktion der API für vorbereitete Anweisungen, die Erfolg haben oder scheitern kann. Der Fehlercode besteht aus fünf Zeichen. "00000" bedeutet „kein Fehler“. Die Werte sind durch ANSI-SQL und ODBC vorgegeben. Eine Liste der möglichen Werte finden Sie unter Anhang B, Fehlercodes und -meldungen.

Beachten Sie, dass noch nicht alle MySQL-Fehler SQLSTATE-Codes zugeordnet sind. Für Fehler, die sich nicht zuordnen lassen, wird der Wert "HY000" (allgemeiner Fehler) verwendet.

Rückgabewerte

Ein auf null endender Zeichen-String, der den SQLSTATE-Fehlercode enthält.

int mysql_stmt_store_result(MYSQL_STMT *stmt)

Beschreibung

Sie können mysql_stmt_store_result() für jede Anweisung aufrufen, die eine Ergebnismenge erstellt (SELECT, SHOW, DESCRIBE, EXPLAIN), sofern Sie die gesamte Ergebnismenge im Client puffern wollen, damit der nachfolgende mysql_stmt_fetch()-Aufruf die gepufferten Daten zurückgibt.

Es ist zwar nicht nötig, mysql_stmt_store_result() für andere Anweisungen aufzurufen, aber es schadet auch nichts und hat keine spürbaren Leistungseinbußen zur Folge. Ob die Anweisung eine Ergebnismenge erzeugt hat, können Sie ermitteln, indem Sie nachschauen, ob mysql_stmt_result_metadata() den Wert NULL zurückgibt. Weitere Informationen gibt es unter Abschnitt 24.2.7.22, „mysql_stmt_result_metadata()“.

Hinweis: MySQL berechnet nach Voreinstellung nicht die MYSQL_FIELD->max_length für alle Spalten in mysql_stmt_store_result(), da dieser Rechenaufwand mysql_stmt_store_result() deutlich verlangsamen würde und die meisten Anwendungen auf max_length gut verzichten können. Wenn Sie max_length aktualisieren möchten, können Sie dies mit mysql_stmt_attr_set(MYSQL_STMT, STMT_ATTR_UPDATE_MAX_LENGTH, &flag) ermöglichen. Siehe Abschnitt 24.2.7.3, „mysql_stmt_attr_set()“.

Rückgabewerte

Null, wenn die Ergebnisse erfolgreich gepuffert wurden, und ein von null verschiedener Wert, wenn ein Fehler auftrat.

Fehler

void my_init(void)

Beschreibung

Diese Funktion muss einmalig vor dem Aufruf jeder anderen MySQL-Funktion in einem Programm aufgerufen werden. Sie initialisiert einige globale Variablen, die MySQL benötigt. Wenn Sie eine Thread-sichere Clientbibliothek benutzen, wird auch für diesen Thread mysql_thread_init() aufgerufen.

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

Rückgabewerte

Keine.

my_bool mysql_thread_init(void)

Beschreibung

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

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

Rückgabewerte

Null bei Erfolg und ein von null verschiedener Wert bei einem Fehler.

void mysql_thread_end(void)

Beschreibung

Diese Funktion muss vor pthread_exit() benutzt werden, um den von mysql_thread_init() zugewiesenen Speicher wieder freizugeben.

Beachten Sie, dass diese Funktion nicht automatisch von der Clientbibliothek aufgerufen wird. Sie muss explizit aufgerufen werden, um ein Speicherleck zu verhindern.

Rückgabewerte

Keine.

unsigned int mysql_thread_safe(void)

Beschreibung

Diese Funktion zeigt an, ob der Client als Thread-sicher kompiliert wurde.

Rückgabewerte

1, wenn der Client Thread-sicher ist, andernfalls 0.

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

Beschreibung

Diese Funktion muss in einem Programm, das den Embedded Server benutzt, einmalig vor jeder anderen MySQL-Funktion aufgerufen werden. Sie startet den Server und initialisiert eventuelle Subsysteme (mysys, InnoDB und so weiter), die der Server benötigt. Wird diese Funktion nicht aufgerufen, führt der nächste mysql_init()-Aufruf mysql_server_init() aus. Wenn Sie das mit MySQL gelieferte DBUG-Paket benutzen, sollten Sie die Funktion nach my_init() aufrufen.

Die Argumente argc und argv entsprechen den Argumenten von main(). Das erste Element von argv wird ignoriert (es enthält typischerweise den Namen des Programms). Der Bequemlichkeit halber kann argc den Wert 0 (null) haben, wenn keine Kommandozeilenargumente für den Server vorhanden sind. Da mysql_server_init() die Argumente kopiert, kann argv oder groups nach dem Aufruf getrost zerstört werden.

Wenn Sie sich mit einem externen Server verbinden möchten, ohne den Embedded Server zu starten, müssen Sie einen negativen Wert für argc angeben.

Die mit NULL endende Liste der Strings in groups wählt die Gruppen aus den Optionsdateien aus, die aktiv sein sollen. Siehe Abschnitt 4.3.2, „my.cnf-Optionsdateien“. Der Bequemlichkeit halber kann groups den Wert NULL haben. In diesem Fall sind die Gruppen [server] und [embedded] aktiv.

Beispiel

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

static char *server_args[] = {
  "this_program",       /* Dieser String wird nicht benutzt */
  "--datadir=.",
  "--key_buffer_size=32M"
};
static char *server_groups[] = {
  "embedded",
  "server",
  "this_program_SERVER",
  (char *)NULL
};

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

  /* Hier werden MySQL-API-Funktionen benutzt */

  mysql_server_end();

  return EXIT_SUCCESS;
}

Rückgabewerte

0, wenn alles okay ist, 1, wenn ein Fehler auftrat.

void mysql_server_end(void)

Beschreibung

Diese Funktion muss unbedingt einmalig im Programm aufgerufen werden, und zwar nach allen anderen MySQL-Funktionen. Sie fährt den Embedded Server herunter.

Rückgabewerte

Keine.

Es ist möglich, dass mysql_store_result() nach einem erfolgreichen Aufruf von mysql_query() den Wert NULL zurückgibt. Wenn dies geschieht, so bedeutet es, dass eine der folgenden Bedingungen eingetreten ist:

Sie können immer mit mysql_field_count() prüfen, ob die Anweisung eine nichtleere Ergebnismenge hätte produzieren sollen. Wenn mysql_field_count() null liefert, ist das Ergebnis leer und es handelte sich um eine Anweisung, die keine Werte zurückgibt (beispielsweise ein INSERT oder DELETE). Wenn mysql_field_count() einen von null verschiedenen Wert liefert, hätte die Anweisung eigentlich ein nichtleeres Ergebnis zurückgeben müssen. Ein Beispiel finden Sie in der Beschreibung der mysql_field_count()-Funktion.

Ob ein Fehler auftrat, verrät Ihnen mysql_error() oder mysql_errno().

Zusätzlich zu der Frage, ob eine Anfrage eine Ergebnismenge zurückgibt, können Sie auch die folgenden Informationen herausfinden:

Wenn Sie einen Datensatz in eine Tabelle mit einer AUTO_INCREMENT-Spalte einfügen, können Sie den in dieser Spalte gespeicherten Wert mit der Funktion mysql_insert_id() erhalten.

In Ihren C-Anwendungen können Sie überprüfen, ob ein Wert in einer UTO_INCREMENT-Spalte gespeichert wurde. Hierzu führen Sie folgenden Code aus (der voraussetzt, dass Sie sich vom Erfolg der Anweisung überzeugt haben). Der Code ermittelt, ob die Anfrage ein INSERT mit einem AUTO_INCREMENT-Index war:

if ((result = mysql_store_result(&mysql)) == 0 &&
    mysql_field_count(&mysql) == 0 &&
    mysql_insert_id(&mysql) != 0)
{
    used_id = mysql_insert_id(&mysql);
}

Weitere Informationen finden Sie unter Abschnitt 24.2.3.36, „mysql_insert_id()“.

Wurde ein neuer AUTO_INCREMENT-Wert generiert, so können Sie diesen auch erhalten, indem Sie die SELECT LAST_INSERT_ID()-Anweisung mit mysql_query() ausführen und den Wert aus der Ergebnismenge dieser Anweisung abfragen.

Für LAST_INSERT_ID() wird die zuletzt generierte ID für jede Verbindung im Server gespeichert. Sie wird von keinem anderen Client geändert, noch nicht einmal dann, wenn Sie eine andere AUTO_INCREMENT-Spalte mit einem nichtmagischen Wert aktualisieren (also einem Wert, der nicht NULL und nicht 0 ist).

Wenn Sie die für eine Tabelle generierte ID benutzen und in eine andere Tabelle einfügen möchten, erledigen Sie dies mit SQL-Anweisungen wie diesen:

INSERT INTO foo (auto,text)
    VALUES(NULL,'text');              # generiert ID durch Einfügen von NULL
INSERT INTO foo2 (id,text)
    VALUES(LAST_INSERT_ID(),'text');  # benutzt ID in einer zweiten Tabelle

Beachten Sie, dass mysql_insert_id() den Wert liefert, der in einer AUTO_INCREMENT-Spalte gespeichert war, egal ob dieser Wert automatisch durch Speichern von NULL oder 0 generiert oder als expliziter Wert angegeben wurde. LAST_INSERT_ID() liefert nur automatisch generierte AUTO_INCREMENT-Werte. Wenn Sie einen expliziten Wert, der nicht NULL oder 0 ist, speichern, so beeinflusst dieser nicht den Rückgabewert von LAST_INSERT_ID().

Beim Verlinken mit der C-API können folgende Fehler auf manchen Systemen 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 dies auf Ihrem System geschieht, müssen Sie die Mathe-Bibliothek einbinden, indem Sie -lm am Ende der Compile/link-Zeile hinzufügen.