9 MySQL-APIs

Dieses Kapitel beschreibt die APIs, die für MySQL bereitstehen, wo man sie bekommt und wie man sie benutzt. Die C-API ist am ausführlichsten beschrieben, da sie vom MySQL-Team stammt und als Basis für die meisten anderen APIs dient.

9.1 MySQL-PHP-API

PHP ist eine serverseitige Skriptsprache, die in HTML eingebettet werden kann und mit der man dynamische Webseiten erstellen kann. PHP unterstützt eine Vielzahl von Datenbanken. Darunter befindet sich auch MySQL. PHP kann als alleinstehendes Programm oder als Teil des Apache Webservers eingesetzt werden.

Die Distribution und die Dokumentation gibt es unter PHP-Website.

9.1.1 Allgemeine Probleme mit MySQL und PHP

• Error: "Maximum Execution Time Exceeded" Dies ist eine PHP-Beschränkung. Ändern sie den Wert für die maximale Ausführungszeit in der `php3.ini'-Datei. Es ist ausserdem keine schlechte Idee, die Beschränkung für die maximale Benutzung von RAM von 8 MB auf 16 MB per Skript zu verdoppeln.
• Error: "Fatal error: Call to unsupported oder undefined function mysql_connect() in .." Das bedeutet, dass Ihre PHP-Version nicht mit MySQL-Unterstützung ausgestattet ist. Sie können entweder ein dynamisches MySQL-Modul für PHP kompilieren oder PHP mit seiner eingebautet MySQL-Unterstützung neu kompilieren. Im PHP-Manual ist dies ausführlich beschrieben.
• Error: "undefined reference to `uncompress'" Die Client-Bibliothek wurde mit der Unterstützung für ein komprimiertes Client-/Server-Protokoll kompiliert. Um den Fehler zu beheben, müssen Sie -lz als letztes angeben, wenn Sie gegen -lmysqlclient linken.

9.2 MySQL-Perl-API

Dieser Abschnitt dokumentiert die Perl-DBI-Schnittstelle. Die frühere Schnittstelle hieß mysqlperl. DBI/DBD ist jetzt die empfohlene Perl-Schnittstelle. mysqlperl ist überflüßig und deshalb hier nicht näher beschrieben.

9.2.1 DBI mit DBD::mysql

DBI ist eine allgemeine Schnittstelle für viele Datenbanken. Das bedeutet, Sie können ein Skript schreiben, dass viele verschiedene Datenbanken unterstützt, ohne es zu ändern. Sie brauchen für jeden Datenbanktyp einen Datenbank-Treiber (DBD). Für MySQL heißt dieser Treiber DBD::mysql. Für weitere Informationen über Perl5 DBI besuchen Sie bitte die DBI-Website und lesen Sie die Dokumentation:

http://www.symbolstone.org/technology/perl/DBI/index.html

Für weitere Informationen über objektorientierte Programmierung (OOP) in Perl5 besuchen Sie die OOP-Seite:

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

Beachten Sie, dass Sie, wenn Sie Transaktionen mit Perl einsetzen wollen, Msql-Mysql-modules der Version 1.2216 oder neuer benötigen.

Installationsanweisungen für MySQL-Perl-Unterstützung finden Sie unter section 9.2 MySQL-Perl-API.

9.2.2 Die DBI-Schnittstelle

Portable DBI-Methoden

MySQL-spezifische Methoden

Die Perl-Methoden werden im Folgenden detaillierter erläutert. Die Variablen für die zurückgegebenen Werte haben folgende Bedeutung:

$dbh

Datenbank-Handle

$sth

Statement-Handle

$rc

Rückgabe-Code (oft ein Status)

$rv

Rückgabewert (oft ein Status)

Portable DBI-Methoden

connect($datenquelle, $benutzername, $passwort)

Benutzen Sie die connect-Methode, um eine Verbindung zur Datenbank der Datenquelle herzustellen. Der $datenquelle-Wert sollte mit DBI:Treiber_name: beginnen. Beispielanwendungen von connect mit dem DBD::mysql Treiber:

$dbh = DBI->connect("DBI:mysql:$datenbank", $benutzer, $passwort);
$dbh = DBI->connect("DBI:mysql:$datenbank:$hostname",
                    $benutzer, $passwort);
$dbh = DBI->connect("DBI:mysql:$datenbank:$hostname:$port",
                    $benutzer, $passwort);

Wenn der Benutzername und / oder das Passwort nicht angegeben werden, verwendet DBI die Werte der DBI_USER- und DBI_PASS- Umgebungsvariablen. Wen Sie keinen Hostnamen angeben, wird 'localhost' verwendet. Wenn Sie keine Portnummer angeben, wird der MySQL-Port (3306) verwendet. Seit Msql-Mysql-modules-Version 1.2009 erlaubt der $datenquelle-Wert bestimmte Modifikatoren:

mysql_read_default_file=datei

Liest `datei' als eine Optionsdatei. Für weitere Informationen zu Optionsdateien beachten Sie bitte section 5.1.2 my.cnf-Optionsdateien.

mysql_read_default_group=group_name

Beim Lesen einer Optionsdatei ist die Standardgruppe normalerweise die [client]-Gruppe. Wenn Sie die mysql_read_default_group- Option angeben, wird die Standardgruppe [gruppenname].

mysql_compression=1

Aktiviert die Kompression während der Kommunikation zwischen Client und Server (ab Version 3.22.3).

mysql_socket=/pfad/zur/socket

Gibt den Pfad des Unix-Sockets an, der zum Verbinden mit dem Server verwendet wird (MySQL-Version 3.21.15 oder neuer).

Sie können mehrere Modifikatoren angeben, dabei muss jedem ein Semikolon vorangestellt sein. Wenn Sie zum Beispiel vermeiden wollen, dass sie Benutzername und Passwort im DBI-Skript angeben müssen, können Sie sie aus der `~/.my.cnf'-Optionsdatei nehmen. Ihr connect-Aufruf sieht folgendermaßen aus:

$dbh = DBI->connect("DBI:mysql:$datenbank"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
                $benutzer, $passwort);

Dieser Aufruf liest die Optionen für die [client]-Gruppe aus der Optionsdatei. Wenn Sie dasselbe für die [perl]-Gruppe tun wollen, könnte Ihr Code so aussehen:

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

disconnect

Die disconnect-Methode beendet die Verbindung mit der Datenbank. Dies wird typischerweise kurz vor dem Ende eines Scripts ausgeführt. Beispiel:

$rc = $dbh->disconnect;

prepare($statement)

Bereitet ein SQL-Statement zum Ausführen durch den Datenbankserver vor und gibt ein "Statement-Handle" ($sth) zurück, mit der Sie die execute-Methode aufrufen. Normalerweise werden Sie SELECT-Statements (und SELECT-ähnliche Statements so wie SHOW, DESCRIBE und EXPLAIN) mit der Bedeutung von prepare und execute verwenden. Beispiel:

$sth = $dbh->prepare($statement)
    or die "$statement: $dbh->errstr kann nicht vorbereitet werden\n";

execute

Die execute-Methode führt ein vorbereitetes Statement aus. Bei Nicht-SELECT-Statements gibt execute die Anzahl der betroffenen Zeilen zurück. Wenn Zeilen betroffen sind, gibt execute "0E0" zurück, was in Perl als 0 und true erkannt wird. Wenn ein Fehler auftritt, gibt execute undef zurück. Bei SELECT-Statements beginnt execute die SQL-Anfrage in der Datenbank; Sie müssen eine der fetch_*-Methoden nutzen, die weiter unten beschrieben sind, um Daten erhalten. Beispiel:

$rv = $sth->execute
          or die "Die Query: $sth->errstr kann nicht ausgeführt werden.";

do($statement)

Die do-Methode bereitet ein Statement vor, führt es aus und gibt die Anzahl der betroffenen Zeilen zurück. Wenn Zeilen betroffen sind, gibt execute "0E0" zurück, was in Perl als 0 und true erkannt wird. Diese Methode wird normalerweise verwendet, um Nicht-SELECT-Statements zu bearbeiten, die (z. B. wegen Treiber-Beschränkungen) nicht vorbereitet werden können, oder die nicht mehr als einmal vorbereitet werden müssen (INSERTS, DELETE usw.). Beispiel:

$rv = $dbh->do($statement)
        or die "$statement: $dbh- >errstr kann nicht vorbereitet werden\n";

Im Allgemeinen ist die do-Methode VIEL schneller (und vorzuziehen) als die prepare/execute-Methoden, die ohne Parameter aufgerufen werden.

quote($string)

Die quote-Methode wird verwendet, um Sonderzeichen zu "escapen", die in Zeichenketten enthalten sein können, und um notwendige äußere Anführungszeichen hinzuzufügen. Beispiel:

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

fetchrow_array

Die Methode holt die nächste Datenzeile und gibt sie als ein Array mit den Feldwerten zurück. Beispiel:

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

fetchrow_arrayref

Die Methode holt die nächste Datenzeile und gibt sie als eine Referenz auf ein Array mit den Feldwerten zurück. Beispiel:

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

fetchrow_hashref

Diese Methode holt eine Datenzeile und gibt eine Referenz auf einen Hash zurück, der Name-/Wert-Paare enthält. Die Methode ist lange nicht so performant wie das Verwenden von Referenzen auf ein Array, wie weiter oben beschrieben ist. Beispiel:

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

fetchall_arrayref

Diese Methode gibt alle Zeilen eines Ergebnisses einer SQL-Anfrage zurück. Sie gibt eine Referenz auf ein Array mit Referenzen auf Arrays mit den Werten der einzelnen Zeilen zurück. Sie können mit zwei verschachtelten Schleifen auf die Werte zugreifen. Beispiel:

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

finish

Bewirkt, dass keine weiteren Daten von dem SQL-Anfrageergebnis geholt werden. Sie können diese Methode aufrufen, um Systemressourcen freizugeben. Beispiel:

s$rc = $sth->finish;

rows

Gibt die Anzahl der veränderten Zeilen (die aktualisiert oder gelöscht wurden) des letzten Befehls zurück. Dies wird normalerweise nach Nicht-SELECT-execute-Statements verwendet. Beispiel:

$rv = $sth->rows;

NULLABLE

Gibt eine Referenz auf ein Array mit Boole'schen Werten zurück; für jedes Element TRUE kann die Spalte NULL-Werte enthalten. Beispiel:

$null_possible = $sth->{NULLABLE};

NUM_OF_FIELDS

Dieses Attribut enthält die Anzahl der Zeilen, die eine SELECT- oder SHOW FIELDS-SQL-Anfrage zurückgibt. Sie können es verwenden, um zu prüfen, ob eine Anfrage ein Ergebnis zurückgegeben hat: 0 weist auf eine Nicht-SELECT-Anfrage hin, wie INSERT, DELETE oder UPDATE. Beispiel:

$nr_of_fields = $sth->{NUM_OF_FIELDS};

datasource($Treiber_name)

Diese Methode gibt einen Array zurück, der die Namen der verfügbaren Datenbanken auf 'localhost' enthält. Beispiel:

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

ChopBlanks

Dieses Attribut gibt an, ob die fetchrow_*-Methoden vor- und nachstehende Leerzeichen entfernen. Beispiel:

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

trace($trace_ebene)

trace($trace_ebene, $trace_dateiname)

trace aktiviert oder deaktiviert "Tracing". Wenn DBI als eine Klassenmethode aufgerufen wird, steuert es das "Tracing" mit allen Datenbankverbindungen. Wenn es als Datenbank- oder Statement-Handle-Methode aufgerufen wird, steuert es nur die verwendete Verbindung (und deren spätere Ableitungen). Wenn Sie $trace_ebene auf 2 setzen, bewirkt es detaillierte Informationen. Der Wert 0 stellt "Tracing" ab. Die Ausgabe des "Tracing" wird vorgabemäßig nach "standard error" geleitet. Wenn $trace_dateiname angegeben ist, wird die Ausgabe für alle "getraceten" Verbindungen an das Ende dieser Datei geschrieben. Beispiel:

DBI->trace(2);                # alles tracen
DBI->trace(2,"/tmp/dbi.out"); # alles nach /tmp/dbi.out tracen
$dth->trace(2);               # diese Datenbankverbindung tracen
$sth->trace(2);               # dieses Statement-Handle tracen.

Sie können DBI-Tracing auch anschalten, indem Sie die DBI_TRACE-Umgebungsvariable setzen. Wenn Sie sie auf einen numerischen Wert setzen, ist das dasselbe, wie DBI->(wert) aufzurufen. Wenn Sie sie auf einen Pfadnamen setzen, ist das dasselbe, wie DBI->(2,wert) aufzurufen.

MySQL-spezifische Methoden

Die unten stehenden Methoden sind MySQL-spezifisch und nicht Teil des DBI-Standards. Mehrere von ihnen sind veraltet: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length und table. Wo immer es DBI-Standard-Alternativen gibt, ist das unten angemerkt:

insertid

Wenn Sie das AUTO_INCREMENT-Feature von MySQL benutzen, werden neue, automatisch heraufgezählte Werte hier gespeichert. Beispiel:

$new_id = $sth->{insertid};

Alternativ können Sie $dbh->{'mysql_insertid'} verwenden.

is_blob

Gibt eine Referenz auf einen Array mit Boole'schen Werten zurück; für jedes Element des Arrays bedeutet der Wert TRUE, dass die entsprechende Spalte ein BLOB ist. Beispiel:

$keys = $sth->{is_blob};

is_key

Gibt eine Referenz auf einen Array mit Boole'schen Werten zurück; für jedes Element des Arrays bedeutet der Wert TRUE, dass die entsprechende Spalte ein Schlüssel ist. Beispiel:

$keys = $sth->{is_key};

is_num

Gibt eine Referenz auf einen Array mit Boole'schen Werten zurück; für jedes Element des Arrays bedeutet der Wert TRUE, dass die entsprechende Spalte numerische Werte enthält. Beispiel:

$nums = $sth->{is_num};

is_pri_key

Gibt eine Referenz auf einen Array mit Boole'schen Werten zurück; für jedes Element des Arrays bedeutet der Wert TRUE, dass die entsprechende Spalte ein Primärschlüssel ist. Beispiel:

$pri_keys = $sth->{is_pri_key};

is_not_null

Gibt eine Referenz auf einen Array mit Boole'schen Werten zurück; für jedes Element des Arrays bedeutet der Wert FALSE, dass die entsprechende Spalte NULL enthalten kann. Beispiel:

$not_nulls = $sth->{is_not_null};

Das oben beschriebene NULLABLE-Attribut ist is_not_null in jedem Fall vorzuziehen, da es zum DBI-Standard gehört.

length

max_length

Beide Methoden geben je einen Array mit Spaltenlängen zurück. Der length-Array gibt die maximal mögliche Länge jeder Spalte an (wie es in der Tabellendefinition festgelegt wurde). Der max_length-Array gibt die Länge des aktuell längsten Wertes in den Spalten an. Beispiel:

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

NAME

Gibt eine Referenz auf ein Array mit den Spaltennamen zurück. Beispiel:

$names = $sth->{NAME};

table

Gibt eine Referenz auf ein Array mit den Tabellennamen zurück. Beispiel:

$tables = $sth->{table};

type

Gibt eine Referenz auf ein Array mit den Spaltentypen zurück. Beispiel:

$types = $sth->{type};

9.2.3 Weitere DBI/DBD-Informationen

Bitte verwenden Sie den perldoc-Befehl, um weitere Informationen über DBI zu erhalten.

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

Sie können ausserdem pod2man, pod2html usw. verwenden, um in andere Formate zu wandeln.

Die neuesten DBI-Informationen finden Sie auf der DBI Website:

http://www.symbolstone.org/technology/perl/DBI/index.html

9.3 MySQL-ODBC-Unterstützung

MySQL unterstützt ODBC mit Hilfe des MyODBC-Programms. Dieses Kapitel erläutert, wie Sie MyODBC installieren und benutzen. Hier werden Sie außerdem eine Liste von Programmen finden, die mit MyODBC zusammenarbeiten.

9.3.1 Wie Sie MyODBC installieren

MyODBC ist ein 32-Bit-ODBC- (2.50) -Level-0- (mit Level-1- und Level-2-Features) Treiber für die Anbindung an ODBC-fähige Applikationen an MySQL. MyODBC funktioniert unter Windows95, Windows98, NT, und auf den meisten Unix-Plattformen.

MyODBC ist "public domain". Sie finden die neueste Version bei http://www.mysql.com/downloads/api-myodbc.html.

Wenn Sie ein Problem mit MyODBC haben und Ihr Programm auch mit OLEDB arbeitet, sollten sie den OLEDB Treiber probieren, den sie im "Contrib"-Abschnitt finden. See section B Beigesteuerte Programme.

Normalerweise müssen Sie MyODBC nur auf Windows-Maschinen installieren. Sie brauchen MyODBC für Unix nur, wenn sie ein Programm wie ColdFusion haben, das auf einer Unix-Maschine läuft und ODBC für die Datenbankverbindung nutzt.

Wenn Sie MyODBC unter Unix installieren wollen, brauchen Sie noch einen ODBC-Manager. MyODBC arbeitet mit den meisten Unix-ODBC-Managern zusammen.

Um MyODBC unter Windows zu installieren, sollten sie die passende MyODBC Zip-Datei (für Windows 95/98 oder NT / Windows 2000) herunterladen, es mit WINZIP oder einem ähnlichen Programm entpacken, und die SETUP.EXE-Datei ausführen.

Unter Windows NT kann folgender Fehler während der Installation auftreten (MyODBC):

Während des Kopiervorgangs ist ein Fehler aufgetreten:
C:\WINDOWS\SYSTEM\MFC30.DLL. Starten Sie Windows neu und beginnen die
Installation erneut, noch bevor sie ein anderes Programm starten, das ODBC
verwendet.

Das Problem in diesem Fall ist, dass ein anderes Programm ODBC verwendet und dass unter Windows zwei Programme nicht gleichzeitig auf eine Datei zugreifen können. Deshalb kann es sein, dass Sie nicht in der Lage sind, die ODBC-Treiber mit Microsofts ODBC Setup Programm zu installieren. In den meisten Fällen genügt es, den Ignorieren-Knopf zu drücken, um die restlichen Dateien zu installieren und die Installation abzuschließen. Wenn das nicht funktioniert, booten Sie Ihren Rechner im Abgesicherten Modus, indem sie F8 vor dem Starten von Windows drücken und den Abgesicherten Modus auswählen. Installieren sie MyODBC, und starten Sie wieder im normalen Modus.

• Um eine Verbindung mit einer ODBC-Applikation, die MySQL nicht nativ unterstützt, von Windows zu Unix herzustellen, müssen Sie zunächst MyODBC unter Windows installieren.
• Der Windows-Benutzer muss Zugriffsrechte auf den MySQL-Server der Unix-Maschine besitzen. Diese richten Sie mit dem GRANT-Befehl ein. See section 5.3.1 GRANT- und REVOKE-Syntax.
• Sie müssen wie folgt einen ODBC-DSN-Eintrag erstellen:
  • Öffnen Sie die Systemsteuerung der Windows-Maschine.
  • Doppelklicken Sie das ODBC-Datenquellen-Symbol.
  • Klicken Sie auf die Registerkarte Benutzer-DSN.
  • Klicken Sie auf Hinzufügen.
  • Wählen Sie MySQL im Fenster "Neue Datenquelle hinzufügen" und klicken Sie auf den Fertig-Knopf.
  • Das MySQL-Treiber-Standard-Konfigurationsfenster wird nun angezeigt. See section 9.3.2 Wie Sie die verschiedenen Felder im ODBC-Administrator Programm ausfüllen.
• Starten Sie nun ihre Applikation und wählen Sie den ODBC-Treiber mit der von ihnen im ODBC angegebenen DSN.

Bitte beachten Sie, dass weitere Konfigurationsoptionen im MySQL-Fenster vorhanden sind (trace, don't prompt on connect usw.). Probieren Sie diese aus, wenn Sie Probleme haben.

9.3.2 Wie Sie die verschiedenen Felder im ODBC-Administrator Programm ausfüllen

Es gibt drei Möglichkeiten, den Server unter Windows 95 anzugeben:

• Verwenden Sie die IP-Adresse des Servers.
• Fügen Sie der Datei `\windows\lmhosts' folgende Informationen an:

  ip hostname
  

  Beispiel:

  194.216.84.21 mein_hostname
  

• Konfigurieren Sie DNS:

Beispiel: Wie Sie das ODBC setup ausfüllen:

Windows DSN Name:   test
Beschreibung:       Das ist meine Datenbank
MySql Datenbank:    test
Server:             194.216.84.21
User:               monty
Password:           mein_passwort
Port:

Der Wert für Windows DSN Namen muss in ihrem Windows-ODBC-Setup eindeutig sein.

Sie müssen die Werte für Server, User, Password oder Port im ODBC-Setup-Fenster nicht angeben. Wenn Sie es jedoch tun, werden diese Werte als Standardwerte verwendet, wenn Sie versuchen, eine Verbindung aufzubauen. Sie können die Werte auch zur Laufzeit ihres Programms angeben.

Wenn Sie die Portnummer nicht angeben, wird der Standard-Port (3306) verwendet.

Wenn Sie die Option Optionen aus C:\my.cnf lesen angeben, werden die Gruppen client und odbc aus der `C:\my.cnf'-Datei gelesen. Sie können alle Optionen verwenden, die für mysql_options() gültig sind. See section 9.4.3.38 mysql_options().

9.3.3 Verbindungsparameter für MyODBC

Man kann die folgenden Parameter für MyODBC im [Servername]-Abschnitt in der ODBC.INI-Datei oder über das InConnectionString-Argument im SQLDriverConnect()-Aufruf angeben:

Die Option "argument" wird verwendet, um MyODBC zu sagen, dass der Client nicht 100% ODBC-kompatibel ist. Unter Windows setzt man diese Option normalerweise im Verbindungsdialog, Sie können aber auch das "option"-Argument verwenden. Die folgenden Optionen sind in derselben Reihenfolge wie im MyODBC-Verbindungsdialog:

Wenn Sie viele Optionen haben wollen, sollten Sie die obigen Flags hinzufügen. Zum Beispiel gibt Ihnen die Option 12 (4+8) Debugging und keine Paketbeschränkungen.

Die Standard-`MYODBC.DLL'-Datei wird für optimale Performance kompiliert. Wenn Sie MyODBC debuggen wollen (um zum Beispiel "tracing" zu aktivieren), sollten Sie stattdessen MYODBCD.DLL verwenden. Um diese Datei zu installieren, kopieren Sie `MYODBCD.DLL' einfach über die installierte MYODBC.DLL-Datei.

9.3.4 Wie Sie Probleme mit MyODBC berichten

MyODBC wurde mit Access, Admndemo.exe, C++-Builder, Borland Builder 4, Centura Team Developer (vorher Gupta SQL/Windows), ColdFusion (unter Solaris und NT mit Service Pack 5), Crystal Reports, DataJunction, Delphi, ERwin, Excel, iHTML, FileMaker Pro, FoxPro, Notes 4.5/4.6, SBSS, Perl DBD-ODBC, Paradox, Powerbuilder, Powerdesigner 32 bit, VC++ und Visual Basic getestet.

Wenn Sie weitere Applikationen kennen, die mit MyODBC zusammenarbeiten, sagen Sie uns bitte unter myodbc@lists.mysql.com Bescheid!

Mit einigen Programmen können Fehler wie diese auftreten: Another user hat modifies the record that you have modified. Meistens lösen Sie das folgendermaßen:

• Fügen Sie der Tabelle einen Primärschlüssel hinzu, wenn noch keiner existiert.
• Fügen Sie eine TIMESTAMP-Spalte hinzu, wenn noch keine existiert.
• Verwenden Sie ausschließlich 'Double Float'-Felder. Manche Programme kommen mit 'Single Float'-Feldern nicht klar.

Wenn das nicht helfen sollte, dann erstellen Sie eine MyODBC 'Trace'-Datei und versuchen Sie, die Fehlerquelle so zu erschließen.

9.3.5 Programme, die bekanntermaßen mit MyODBC zusammenarbeiten

Die meisten Programme sollten mit MyODBC zusammenarbeiten. Für die unten aufgeführten haben wir es selbst getestet oder haben die Bestätigung eines Benutzers, dass es läuft.

Programm

Anmerkung

Access

Um Access zum Laufen zu bringen:

• Wenn Sie Access 2000 verwenden, sollten Sie die neuesten (Version 2.6 oder höher) Microsoft-MDAC (Microsoft Data Access Components) von http://www.microsoft.com/data herunterladen. Dies wird folgenden Bug in Access beheben: Wenn Sie Daten nach MySQL exportieren, werden Tabellen- und Spaltennamen nicht spezifiziert. Ein anderer Weg, diesen Bug zu umgehen, ist, MyODBC auf Version 2.50.33 und MySQL auf Version 3.23.x zu aktualisieren, welche beide zusammen einen Workaround für diesen Bug implementiert haben. Ausserdem sollten Sie das Microsoft-Jet-4.0-Service-Pack 5 (SP5) einspielen, welches hier http://support.microsoft.com/support/kb/articles/Q 239/1/14.ASP gefunden werden kann. Dies behebt einige Fälle, in denen Spalten als #deleted# in Access markiert sind. Beachten Sie, dass Sie, wenn Sie die MySQL-Version 3.22 verwenden, den MDAC-Patch einspielen und MyODBC 2.50.32 oder 2.50.34 und höher benutzen müssen, um dieses Problem zu umgehen.
• Für alle Access-Versionen sollten Sie die MyODBC-Optionen auf Return matching rows setzen. Für Access 2.0 sollten Sie ausserdem Simulate ODBC 1.0 einschalten.
• Sie sollten einen Timestamp in alle Tabellen einfügen, die Sie aktualisieren wollen. Für maximale Portablilität werden TIMESTAMP(14) oder einfach TIMESTAMP anstelle von TIMESTAMP(X)-Variationen empfohlen.
• Sie sollten einen Primärschlüssel in Ihren Tabellen haben. Falls nicht, können neue oder geänderte Zeilen als #DELETED# erscheinen.
• Verwenden sie ausschließlich DOUBLE-Float-Felder. Access kann nicht richtig mit "Single Floats" vergleichen. Die Symptome sind, dass entweder neue oder geänderte Zeilen als #DELETED# erscheinen oder Sie keine Zeilen finden oder ändern können.
• Wenn Sie eine Tabelle mit MyODBC verbinden, die eine BIGINT-Spalte hat, werden die Ergebnisse als #DELETED angezeigt. Sie umgehen das Problem folgendermaßen:
  • Fügen Sie eine weitere TIMESTAMP-"Dummy-Spalte" hinzu, am besten TIMESTAMP(14).
  • Wählen Sie 'BIGINT Spalten zu INT wandeln' im Verbindungsdialog des ODBC-DSN-Administrators.
  • Entfernen Sie die Tabellenverknüpfung aus Access und stellen Sie sie wieder her.
  Die vorherigen Zeilen werden weiterhin als #DELETED# angezeigt, aber neue/geänderte Zeilen werden korrekt dargestellt.
• Wenn Sie weiterhin den Fehler Ein anderer Benutzer hat Ihre Daten geändert erhalten, nachdem Sie die TIMESTAMP-Spalte hinzugefügt haben, könnte Ihnen der folgende Trick helfen: Verwenden Sie anstelle von Datenblattansicht ein Formular mit den von Ihnen gewünschten Feldern und benutzen Sie dann Formularblattansicht. Sie sollten den StandardWert für die TIMESTAMP-Spalte auf NOW() setzen. Zusätzlich ist es sicher nützlich, die TIMESTAMP-Spalte zu verstecken, damit Ihre Anwender nicht erschrecken.
• Manchmal erstellt Access ungültige SQL-Anfragen, die MySQL nicht versteht. Wählen Sie zur Lösung dieses Problems "Abfrage|SQL-spezifisch|Pass-Through" aus dem Access-Menü.
• Wenn Sie statt dessen MEMO-Spalten haben wollen, sollten Sie die Spalte mit ALTER TABLE in TEXT ändern.
• Access kann nicht immer sauber mit DATE-Spalten umgehen. Wenn Sie ein solches Problem haben, ändern Sie die entsprechenden Spalten in DATETIME.
• Wenn Sie in Access eine Spalte BYTE haben, wird Access versuchen, diese in TINYINT anstelle von TINYINT UNSIGNED zu exportieren. Das führt zu Problemen, wenn Sie Werte in der Spalte haben, die größer als 127 sind!

ADO

Wenn Sie mit der ADO-API und MyODBC kodieren, müssen Sie auf einige vorgabemäßige Eigenschaften achten, die vom MySQL-Server nicht unterstützt werden. Die Benutzung von CursorLocationProperty als adUseServer zum Beispiel gibt für RecordCountProperty ein Ergebnis von -1 zurück. Um den richtigen Wert zu erhalten, müssen Sie diese Eigenschaft auf adUseClient setzen, wie im unten stehenden Visual-Basic-Code gezeigt:

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

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

myrs.Close
myconn.Close

Ein weiterer Workaround besteht darin, ein SELECT COUNT(*)-Statement für eine ähnliche Anfrage zu benutzen, um das korrekte Zählen der Zeilen zu erreichen.

Active server pages (ASP)

Sie sollten den Option-Flag Return matching rows benutzen.

BDE-Applikationen

Damit diese funktionieren, sollten Sie die Option-Flags Don't optimize column widths und Return matching rows benutzen.

Borland Builder 4

Wenn Sie eine Anfrage starten, können Sie die Eigenschaft Active oder die Methode Open benutzen. Beachten Sie, dass Active automatisch mit einer SELECT * FROM ...-Anfrage startet, was keine gute Idee ist, wenn Ihre Tabellen Groß sind!

ColdFusion (unter Unix)

Die folgenden Informationen sind der ColdFusion-Dokumentation entnommen: Lesen Sie folgende Informationen, um den ColdFusion-Server für Linux so zu konfigurieren, dass er den unixODBC-Treiber bei MyODBC für MySQL-Datenquellen benutzt. Allaire kann bestätigen, dass die MyODBC-Version 2.50.26 mit MySQL-Version 3.22.27 und ColdFusion für Linux funktioniert. (Jede neuere Version sollte ebenfalls funktionieren.) Sie können MyODBC von http://www.mysql.com/downloads/api-myodbc.html herunter laden. Bei ColdFusion Version 4.5.1 können Sie den ColdFusion Administrator benutzen, um die MySQL-Datenquelle hinzuzufügen. Der Treiber liegt der ColdFusion Version 4.5.1 jedoch nicht bei. Bevor der MySQL-Treiber in der Auswahlliste der ODBC-Datenquellen erscheint, müssen Sie den MyODBC-Treiber bauen und nach `/opt/coldfusion/lib/libmyodbc.so' kopieren. Das Contrib-Verzeichnis enthält das Programm mydsn-xxx.zip, mit dem Sie die DSN-Registrierungs-Datei für den MyODBC-Treiber auf Coldfusion-Applikationen bauen können.

DataJunction

Sie müssen es ändern, damit es VARCHAR statt ENUM ausgibt, weil es Letzteres in einer Art ausgibt, die MySQL nicht versteht.

Excel

Funktioniert. Einige Tipps:

• Wenn Sie Probleme mit Datumsangaben haben, versuchen Sie, sie als Zeichenketten mit der CONCAT()-Funktion abzurufen. Beispiel:

  select CONCAT(sonnenaufgang), CONCAT(sonnenuntergang)
      from aufgang_untergang;
  

  Werte, die auf diese Art als Zeichenketten abgerufen werden, sollten korrekt als Zeitwerte von Excel97 erkannt werden. Der Zweck von CONCAT() in diesem Beispiel ist, ODBC auszutricksen, so dass es denkt, dass die Spalte vom Typ "Zeichenkette" sei. Ohne CONCAT() weiß ODBC, dass die Spalte vom Typ "Zeit" ist, und Excel versteht das nicht. Beachten Sie, dass das ein Bug in Excel ist, weil es eine Zeichenkette automatisch in eine Zeitangabe umwandelt. Das wäre sehr gut, wenn die Quelle eine Textdatei wäre, ist aber einfach nur dumm, wenn die Quelle eine ODBC-Verbindung ist, die exakte Typen für jede Spalte übermittelt.

Word

Um Daten von MySQL in Word- / Excel-Dokumente abzurufen, müssen Sie den MyODBC-Treiber benutzen und das Add-in Microsoft Query hinzufügen. Erzeugen Sie zum Beispiel eine Datenbank mit einer Tabelle, die 2 Text-Spalten enthält:

• Fügen Sie Zeilen mit dem mysql-Kommandozeilenwerkzeug ein.
• Erzeugen Sie eine DSN-Datei mit dem MyODBC-Treiber, die Sie zum Beispiel my nennen, für die oben genannten Datenbank.
• Öffnen Sie Word.
• Erzeugen Sie ein leeres Dokument.
• Öffnen Sie die Symbolleiste 'Datenbank' und klicken Sie auf die Schaltfläche 'Datenbank einfügen'.
• Klicken Sie auf die Schaltfläche 'Daten abrufen'.
• Klicken Sie auf die Schaltfläche 'MS Query'.
• Erzeugen Sie in MS Query eine neue Datenquelle unter Benutzung der DSN-Datei my.
• Wählen Sie die neue Anfrage aus.
• Wählen Sie die Spalten aus, die Sie haben wollen.
• Legen Sie bei Bedarf einen Filter fest.
• Legen Sie bei Bedarf eine Sortierung fest.
• Wählen Sie 'Daten an Word zurückgeben'.
• Klicken Sie auf 'Beenden'.
• Klicken Sie auf 'Daten einfügen' und wählen Sie die Datensätze aus.
• Klicken Sie auf 'OK', und Sie sehen die Zeilen in Ihrem Word-Dokument.

odbcadmin

Test-Programm für ODBC.

Delphi

Sie müssen BDE-Version 3.2 oder neuer benutzen. Setzen Sie die `Don't optimize column width'-Option, wenn Sie sich mit MySQL verbinden. Hier ist möglicherweise nützlicher Delphi-Code, der sowohl einen ODBC-Eintrag als auch einen BDE-Eintrag für MyODBC setzt (der BDE-Eintrag erfordert einen BDE-Alias-Editor, der kostenlos auf einer Delphi Super Page in Ihrer Nähe herunter geladen werden kann (Dank dafür an Bryan Brunton bryan@flesherfab.com:

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

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

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

C++-Builder

Getestet mit BDE-Version 3.0. Das einzige bekannte Problem ist, dass Anfragefelder nicht aktualisiert werden, wenn sich die Tabellenstruktur ändert. BDE scheint jedoch keine Primärschlüssel zu erkennen, sondern nur den Index PRIMARY, obwohl das eigentlich kein Problem darstellt.

Vision

Sie sollten den Option-Flag Return matching rows benutzen.

Visual Basic

Damit Sie eine Tabelle aktualisieren können, müssen Sie für die Tabelle einen Primärschlüssel definieren. Visual Basic mit ADO kann keine großen Ganzzahlen handhaben. Das heißt, dass einige Anfragen wie SHOW PROCESSLIST nicht korrekt funktionieren. Das läßt sich beheben, indem man die Option OPTION=16834 in der ODBC-Verbindungs-Zeichenkette hinzufügt oder die Change BIGINT columns to INT-Option im MySQL-Verbindungsbildschirm setzt. Eventuell sollten Sie auch die Return matching rows-Option setzen.

VisualInterDev

Wenn Sie den Fehler [Microsoft][ODBC Driver Manager] Driver does not support this parameter erhalten, kann es daran liegen, dass Sie ein BIGINT in Ihrem Ergebnis haben. Versuchen Sie, die Change BIGINT columns to INT-Option im MySQL-Verbindungsbildschirm zu setzen.

Visual Objects

Sie sollten den Option-Flag Don't optimize column widths setzen.

9.3.6 Wie man den Wert einer AUTO_INCREMENT-Spalte in ODBC erhält

Ein häufiges Problem ist es, den Wert einer automatisch erzeugten Kennung von einem INSERT zu erhalten. Bei ODBC können Sie etwas wie folgendes tun (unter der Annahme, dass auto ein AUTO_INCREMENT-Feld ist):

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

Oder, wenn Sie die Kennung in eine andere Tabelle einfügen wollen:

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

See section 9.4.6.3 Wie erhalte ich die eindeutige Kennung für die letzte eingefügte Zeile?.

Bei einigen ODBC-Applikationen (zumindest Delphi und Access) kann folgende Anfrage benutzt werden, um eine neu eingefügte Zeile zu finden:

SELECT * FROM tabelle WHERE auto IS NULL;

9.3.7 Probleme mit MyODBC berichten

Wenn Sie Probleme mit MyODBC bekommen, sollten Sie als erstes eine Log-Datei durch den ODBC-Manager anlegen lassen (das Log, das Sie erhalten, wenn Sie Logs von ODBCADMIN abfragen) sowie ein MyODBC-Log.

Um ein MyODBC-Log zu erhalten, tun Sie folgendes:

1. Stellen Sie sicher, dass Sie myodbcd.dll und nicht myodbc.dll benutzen. Am einfachsten ist es, wenn Sie sich myodbcd.dll aus der MyODBC-Distribution holen und es über myodbc.dll kopieren, die sich wahrscheinlich in Ihrem C:\windows\system32- oder C:\winnt\system32-Verzeichnis befindet. Denken Sie daran, dass Sie wahrscheinlich die alten myodbc.dll nach dem Testen wiederherstellen wollen, weil Sie um einiges schneller ist als myodbcd.dll.
2. Kreuzen Sie `Trace MyODBC' im MyODBC-Verbindungs- bzw. Konfigurationsfenster an. Das Log wird in die Datei `C:\myodbc.log' geschrieben. Wenn Sie zu diesem Fenster zurückkehren und feststellen, dass die Trace-Option nicht mehr angekreuzt ist, heißt das, dass Sie nicht den myodbcd.dll-Treiber benutzen (siehe oben).
3. Starten Sie Ihre Applikation und versuchen Sie, eine Fehlfunktion zu bekommen.

Untersuchen Sie die MyODBC-Trace-Datei, um herauszufinden, was möglicherweise schief geht. Sie können die abgesetzten Anfragen finden, indem Sie nach der Zeichenkette >mysql_real_query in der `myodbc.log'-Datei suchen.

Sie sollten die Anfragen auch zusätzlich im mysql-Monitor oder in admndemo laufen lassen, um herauszufinden, ob der Fehler bei MyODBC oder bei MySQL liegt.

Wenn Sie herausgefunden haben, was schief läuft, schicken Sie bitte nur die relevanten Zeilen (maximal 40 Zeilen) an myodbc@lists.mysql.com. Bitte schicken Sie nie die gesamte MyODBC- oder ODBC-Log-Datei!

Wenn Sie nicht herausfinden können, was schief läuft, besteht die letzte Option darin, eine Archivdatei anzulegen (tar oder zip), die eine MyODBC-Trace-Datei, die ODBC-Log-Datei und eine README-Datei enthält, die das Problem erläutert. Schicken Sie diese an ftp://support.mysql.com/pub/mysql/secret. Nur wir bei MySQL AB haben Zugriff auf die Dateien, die Sie hochspielen, und wir gehen mit den Daten sehr diskret um!

Wenn Sie ein Programm erzeugen können, das dieses Problem ebenfalls zeigt, laden Sie dieses bitte ebenfalls hoch!

Wenn das Programm mit irgend einem anderen SQL-Server funktioniert, sollten Sie eine ODBC-Log-Datei anlegen, in der Sie dasselbe in dem anderen SQL-Server ausführen.

Bedenken Sie, dass wir umso eher das Problem beheben können, desto mehr Informationen Sie uns zur Verfügung stellen!

9.4 MySQL-C-API

Der C-API-Code wird mit MySQL ausgeliefert. Er ist in der mysqlclient-Bibliothek enthalten und erlaubt C-Programmen, auf eine Datenbank zuzugreifen.

Viele Clients in der MySQL-Quelldistribution sind in C geschrieben. Wenn Sie nach Beispielen für den Gebrauch der C-API suchen, schauen Sie sich diese Clients an. Sie finden Sie im clients-Verzeichnis in der MySQL-Quelldistribution.

Viele andere Client-APIs (alle ausser Java) benutzen die mysqlclient-Bibliothek, um mit dem MySQL-Server zu kommunizieren. Das heißt zum Beispiel, dass Sie viele derselben Umgebungsvariablen nutzen können, die von anderen Client-Programmen benutzt werden, weil sie von der Bibliothek referenziert werden. Eine Liste dieser Variablen findet sich unter section 5.8 Clientseitige Skripte und Hilfsprogramme von MySQL.

Der Client hat eine maximale Kommunikationspuffergröße. Die anfänglich zugewiesene Puffergröße (16 KB) wird automatisch bis zur maximale Größe (16 MB) vergrößert. Weil Puffergrößen nur bei Bedarf vergrößert werden, bedeutet die einfache Erhöhung der maximalen Größe nicht per se, dass mehr Ressourcen benutzt werden. Die Überprüfung der Größe ist hauptsächlich eine Prüfung auf irrtümliche Anfragen und Kommunikationspakete.

Der Kommunikationspuffer muss Groß genug sein, um ein einzelnes SQL-Statement aufzunehmen (für den Client-Server-Verkehr) und eine Zeile zurückgegebener Daten (für den Server-Client-Verkehr). Der Kommunikationspuffer jedes Threads wird dynamisch vergrößert, um jede Anfrage oder Zeile bis zur maximalen Größe zu handhaben. Wenn Sie beispielsweise BLOB-Werte haben, die bis zu 16 MB an Daten beinhalten, müssen Sie eine Kommunikationspuffergrenze von zumindest 16 MB haben (sowohl beim Server als auch beim Client). Die vorgabemäßige maximale Größe beim Client liegt bei 16 MB, aber die vorgabemäßige maximale Grenze beim Server liegt bei 1 MB. Das können Sie vergrößern, indem Sie den Wert des max_allowed_packet-Parameters setzen, wenn der Server gestartet wird. See section 6.5.2 Serverparameter tunen.

Der MySQL-Server verringert den Kommunikationspuffer auf net_buffer_length Bytes nach jeder Anfrage. Bei Clients wird die Größe des zugewiesenen Puffers bei einer Verbindung nicht herabgesetzt, bis die Verbindung geschlossen wird. Dann wird der Client-Speicher wieder freigesetzt.

Zum Programmieren mit Threads siehe section 9.4.8 Wie man einen threaded Client herstellt. Um eine Standalone-Applikation herzustellen, die "Server" und "Client" im selben Programm beinhaltet (und nicht mit einem externen MySQL-Server kommuniziert), siehe section 9.4.9 libmysqld, die eingebettete MySQL-Server-Bibliothek.

9.4.1 C-API-Datentypen

MYSQL

This structure represents a handle to one Datenbank connection. It is used für almost all MySQL Funktionen.

MYSQL_RES

Diese Struktur repräsentiert das Ergebnis einer Anfrage, die Zeilen zurückgibt (SELECT, SHOW, DESCRIBE, EXPLAIN). Die von der Anfrage zurückgegebene Informationen wird im Weiteren result set (Ergebnismenge) genannt.

MYSQL_ROW

Das ist eine Typ-sichere Repräsentation einer Zeile von Daten. Momentan ist sie als ein Array gezählter Byte-Zeichenketten implementiert. (Sie können diese nicht als NULL-begrenzte Zeichenketten behandeln, falls Feldwert binäre Daten enthalten können, welche solche Werte intern NULL-Bytes enthalten können.) Zeilen werden mit dem Aufruf von mysql_fetch_row() abgeholt.

MYSQL_FIELD

Diese Struktur enthält Informationen über ein Feld, wie Feldname, Feldtyp und Feldgröße. Seine Elemente werden weiter unten genauer beschrieben. Sie erhalten die MYSQL_FIELD-Strukturen für jedes Feld durch den wiederholten Aufruf von mysql_fetch_field(). Feldwerte sind nicht Teil dieser Struktur, sondern in der MYSQL_ROW-Struktur enthalten.

MYSQL_FIELD_OFFSET

Das ist eine Typ-sichere Repräsentation eines Offsets in einer MySQL-Feldliste (benutzt von mysql_field_seek().) Offsets sind Feldnummern innerhalb einer Zeile, beginnend mit 0.

my_ulonglong

Der Typ, der für die Anzahl von Zeilen und für mysql_affected_rows(), mysql_num_rows(), und mysql_insert_id() benutzt wird. Dieser Typ stellt einen Bereich von 0 bis 1.84e19 zur Verfügung. Auf manchen Systemen funktioniert der Versuch, einen Wert des Typs my_ulonglong auszugeben, nicht. Um einen solchen Wert auszugeben, wandeln Sie ihn in unsigned long um und benutzen Sie ein %lu-Ausgabeformat. Beispiel:

printf (Anzahl von Zeilen: %lu\n", (unsigned long) mysql_num_rows(result));

Die MYSQL_FIELD-Struktur enthält die unten aufgeführten Elemente:

char * name

Der Name des Feldes, als NULL-begrenzte Zeichenkette.

char * table

Der Name der Tabelle, die dieses Feld enthält, falls es kein berechnetes Feld ist. Bei berechneten Feldern ist der table-Wert eine leere Zeichenkette.

char * def

Der Vorgabewert dieses Felds als eine NULL-begrenzte Zeichenkette. Dieser wird nur gesetzt, wenn Sie mysql_list_fields() benutzen.

enum enum_field_types-Typ

Der Typ des Felds. Der type-Wert kann einer der folgenden sein:

Typwert	Typbedeutung
FIELD_TYPE_TINY	TINYINT-Feld
FIELD_TYPE_SHORT	SMALLINT-Feld
FIELD_TYPE_LONG	INTEGER-Feld
FIELD_TYPE_INT24	MEDIUMINT-Feld
FIELD_TYPE_LONGLONG	BIGINT-Feld
FIELD_TYPE_DECIMAL	DECIMAL- oder NUMERIC-Feld
FIELD_TYPE_FLOAT	FLOAT-Feld
FIELD_TYPE_DOUBLE	DOUBLE- oder REAL-Feld
FIELD_TYPE_TIMESTAMP	TIMESTAMP-Feld
FIELD_TYPE_DATE	DATE-Feld
FIELD_TYPE_TIME	TIME-Feld
FIELD_TYPE_DATETIME	DATETIME-Feld
FIELD_TYPE_YEAR	YEAR-Feld
FIELD_TYPE_STRING	CHAR- oder VARCHAR-Feld
FIELD_TYPE_BLOB	BLOB- oder TEXT-Feld (benutzen Sie max_length, um die maximale Länge festzulegen)
FIELD_TYPE_SET	SET-Feld
FIELD_TYPE_ENUM	ENUM-Feld
FIELD_TYPE_NULL	NULL-Feld
FIELD_TYPE_CHAR	Veraltet; benutzen Sie statt dessen FIELD_TYPE_TINY

Sie können das IS_NUM()-Makro benutzen, um zu testen, ob ein Feld einen numerischen Typ besitzt oder nicht. Übergeben Sie den type-Wert an IS_NUM(), und Sie erhalten WAHR (true), wenn das Feld numerisch ist:

if (IS_NUM(field->type))
    printf("Feld ist numerisch\n");

unsigned int length

Die Breite des Felds, wie in der Tabellendefinition festgelegt.

unsigned int max_length

Die maximale Breite des Felds für die Ergebnismenge (die Länge des längsten Feldwerts für die Zeilen, die tatsächlich in der Ergebnismenge enthalten sind). Wenn Sie mysql_store_result() oder mysql_list_fields() benutzen, enthält die Variable die maximale Länge für das Feld. Wenn Sie mysql_use_result() benutzen, ist sie 0.

unsigned int flags

Unterschiedliche Bit-Flags für das Feld. Der flags-Wert kann 0 oder mehr der folgenden Bits gesetzt haben:

Flag-Wert	Flag-Bedeutung
NOT_NULL_FLAG	Feld darf nicht NULL sein
PRI_KEY_FLAG	Feld ist Teil eines Primärschlüssels
UNIQUE_KEY_FLAG	Feld ist Teil eines eindeutigen Schlüssels
MULTIPLE_KEY_FLAG	Feld ist Teil eines nicht eindeutigen Schlüssels
UNSIGNED_FLAG	Feld hat das UNSIGNED-Attribute
ZEROFILL_FLAG	Feld hat das ZEROFILL-Attribute
BINARY_FLAG	Feld hat das BINARY-Attribute
AUTO_INCREMENT_FLAG	Feld hat das AUTO_INCREMENT-Attribut
ENUM_FLAG	Feld ist ein ENUM (veraltet)
BLOB_FLAG	Feld ist ein BLOB oder TEXT (veraltet)
TIMESTAMP_FLAG	Feld ist ein TIMESTAMP (veraltet)

Die Benutzung der BLOB_FLAG-, ENUM_FLAG- und TIMESTAMP_FLAG-Flags ist veraltet, weil sie den Feldtyp statt eines Attributs seines Typs angeben. Statt dessen sollten Sie field->type gegen FIELD_TYPE_BLOB, FIELD_TYPE_ENUM oder FIELD_TYPE_TIMESTAMP testen. Das unten stehende Beispiel zeigt eine typische Benutzung des flags-Werts:

if (field->flags & NOT_NULL_FLAG)
    printf("Feld darf nicht NULL sein\n");

Sie können aus Bequemlichkeitsgründen folgende Makros benutzen, um den Bool'schen Status des flags-Werts zu bestimmen:

IS_NOT_NULL(flags)	WAHR, wenn der Feldwert als NOT NULL definiert ist
IS_PRI_KEY(flags)	WAHR, wenn der Feldwert ein Primärschlüssel ist
IS_BLOB(flags)	WAHR, wenn der Feldwert ein BLOB oder TEXT ist (veraltet; testen Sie statt dessen field->type)

unsigned int decimals

Die Anzahl von Dezimalstellen für numerische Felder.

9.4.2 C-API-Funktionsüberblick

Die in der C-API verfügbaren Funktionen sind unten aufgeführt und im nächsten Abschnitt detaillierter beschrieben. See section 9.4.3 C-API-Funktionsbeschreibungen.

Um sich mit dem Server zu verbinden, rufen Sie mysql_init() auf, um einen Verbindungs-Handler zu initialisieren. Rufen Sie dann mysql_real_connect() mit diesem Handler auf (mit Informationen wie Hostname, Benutzername und Passwort). Beim Verbinden setzt mysql_real_connect() den reconnect-Flag (Teil der MYSQL-Struktur) auf einen Wert von 1. Dieser Flag legt bei einer Anfrage, die wegen einer verloren gegangenen Serververbindung nicht ausgeführt werden kann, fest, dass ein erneutes Verbinden versucht wird, bevor aufgegeben wird. Wenn Sie mit der Verbindung fertig sind, rufen Sie mysql_close() auf, um sie zu beenden.

Während eine Verbindung aktiv ist, kann der Client SQL-Anfragen an den Server schicken, indem er mysql_query() oder mysql_real_query() benutzt. Der Unterschied zwischen beiden ist, dass mysql_query() erwartet, dass die Anfrage als NULL-separierte Zeichenkette angegeben wird, während mysql_real_query() eine gezählte Zeichenkette erwartet. Wenn die Zeichenkette Binärdaten enthält (was NULL-Bytes beinhalten kann), müssen Sie mysql_real_query() benutzen.

Bei jeder Nicht-SELECT-Anfrage (wie INSERT, UPDATE, DELETE) finden Sie heraus, wie viele Zeilen geändert (betroffen) wurden, indem Sie mysql_affected_rows() aufrufen.

Bei SELECT-Anfragen rufen Sie die ausgewählten Zeilen als Ergebnismenge ab. (Beachten Sie, dass einige Statements ähnlich wie SELECT sind, weil auch sie Zeilen zurückgeben. Das sind SHOW, DESCRIBE und EXPLAIN. Sie werden auf dieselbe Weise behandelt wie SELECT-Statements.)

Es gibt für einen Client zwei Möglichkeiten, Ergebnismengen zu verarbeiten. Eine Möglichkeit besteht darin, die gesamte Ergebnismenge auf einmal abzurufen, indem mysql_store_result() aufgerufen wird. Diese Funktion holt alle Zeilen vom Server ab, die von der Anfrage zurückgegeben werden, und speichert sie im Client. Die zweite Möglichkeit besteht darin, dass der Client die Ergebnismenge zeilenweise abruft, indem er mysql_use_result() aufruft. Diese Funktion initialisiert den Abruf, holt aber keinerlei Zeilen vom Server ab.

In beiden Fällen können Sie auf Zeilen zugreifen, indem Sie mysql_fetch_row() aufrufen. Bei mysql_store_result() greift mysql_fetch_row() auf Zeilen zurück, die bereits vom Server geholt wurden. Bei mysql_use_result() ruft mysql_fetch_row() die Zeilen direkt vom Server ab. Informationen über die Größe der Daten in jeder Zeile sind durch Aufruf von mysql_fetch_lengths() verfügbar.

Wenn Sie mit einer Ergebnismenge fertig sind, rufen Sie mysql_free_result() auf, um den hierfür benutzten Speicher freizugeben.

Die beiden Abrufmechanismen sind komplementär. Client-Programme sollten entscheiden, welcher Ansatz der für ihre Erfordernisse geeignetste ist. In der Praxis wird für Clients häufiger mysql_store_result() verwendet.

Ein Vorteil von mysql_store_result() ist, dass bereits alle Zeilen zum Client geholt wurden. Deshalb können Sie nicht nur sequentiell auf Zeilen zugreifen, sondern sich in der Ergebnismenge vorwärts und rückwärts bewegen, indem Sie mysql_data_seek() oder mysql_row_seek() benutzen, um die aktuelle Position innerhalb der Ergebnismenge zu ändern. Sie können auch herausfinden, wie viele Zeilen es gibt, indem Sie mysql_num_rows() aufrufen. Auf der anderen Seite kann der Speicherbedarf für mysql_store_result() sehr hoch sein, wenn Sie große Ergebnismengen abrufen, so dass Speichermangel eintreten kann.

Ein Vorteil von mysql_use_result() ist, dass der Client weniger Arbeitsspeicher für die Ergebnismenge benötigt, weil er nur eine Zeile zugleich erhält (und weil weniger Zuweisungs-Overhead da ist, kann mysql_use_result() schneller sein). Die Nachteile liegen darin, dass Sie jede Zeile schnell verarbeiten müssen, um zu vermeiden, den Server zu blockieren. Ausserdem haben Sie keinen wahlfreien (random) Zugriff auf die Zeilen innerhalb einer Ergebnismenge (Sie können auf die Zeilen nur sequentiell zugreifen), und Sie wissen nicht, wie viele Zeilen sich in der Ergebnismenge befinden, bis Sie sie alle abgerufen haben. Darüber hinaus müssen Sie alle Zeilen abrufen, selbst wenn Sie während des Abrufs feststellen, dass Sie die Information gefunden haben, nach der Sie suchen.

Die API ermöglicht Clients, auf die Anfragen entsprechend zu antworten (Zeilen nur wenn nötig abzurufen), ohne zu wissen, ob die Anfragen ein SELECT ist oder nicht. Das erreichen Sie durch Aufruf von mysql_store_result() nach jedem mysql_query() (oder mysql_real_query()). Wenn der Ergebnismengenaufruf erfolgreich ist, war die Anfrage ein SELECT und Sie können die Zeilen lesen. Wenn der Ergebnismengenaufruf fehlschlägt, rufen Sie mysql_field_count() auf, um festzustellen, ob ein Ergebnis erwartet wurde oder nicht. Wenn mysql_field_count() 0 zurückgibt, gab die Anfrage keine Daten zurück (was anzeigt, dass sie kein INSERT, UPDATE, DELETE usw. war), und es wurde nicht erwartet, dass sie Zeilen zurückgibt. Wenn mysql_field_count() ungleich 0 ist, sollte die Anfrage Zeilen zurückgegeben haben, tat das aber nicht. Das zeigt an, dass die Anfrage ein SELECT war, das fehlschlug. Sehen Sie in der Beschreibung von mysql_field_count() wegen eines Beispiels nach, wie das gemacht wird.

Sowohl mysql_store_result() als auch mysql_use_result() gestatten Ihnen, Informationen über die Felder zu erlangen, aus denen die Ergebnismenge besteht (die Anzahl der Felder, ihre Namen, Typen usw.). Sie können sequentiell auf Feldinformationen innerhalb der Zeile zugreifen, indem Sie mysql_fetch_field() wiederholt aufrufen, oder direkt auf die Feldnummer innerhalb einer Zeile durch Aufruf von mysql_fetch_field_direct(). Die aktuelle Feldcursorposition kann durch den Aufruf von mysql_field_seek() geändert werden. Wenn Sie den Feldcursor setzen, betrifft das nachfolgende Aufrufe von mysql_fetch_field(). Sie erhalten alle Feldinformationen auf einmal, wenn Sie mysql_fetch_fields() aufrufen.

Um Fehler zu erkennen und zu berichten, stellt MySQL den Zugriff auf Fehlerinformationen durch die mysql_errno()- und mysql_error()-Funktionen zur Verfügung. Diese geben den Fehlercode oder die Fehlermeldung für die zuletzt aufgerufenen Funktionen zur Verfügung, die erfolgreich sein oder fehlschlagen können, so dass Sie feststellen können, wann ein Fehler auftrat und welcher es war.

9.4.3 C-API-Funktionsbeschreibungen

In den unten stehenden Beschreibungen bedeutet ein Parameter oder Rückgabewert von NULL NULL im Sinne der C-Programmier-Sprache, nicht einen MySQL-NULL-Wert.

Funktionen, die einen Wert zurückgeben, geben allgemein einen Zeiger oder eine Ganzzahl zurück. Falls nicht anders angegeben geben Funktionen, die einen Zeiger zurückgeben, einen Nicht-NULL-Wert zurück, um Erfolg anzuzeigen, oder einen NULL-Wert, um einen Fehler anzuzeigen. Funktionen, die eine Ganzzahl zurückgeben, geben 0 zurück, um Erfolg anzuzeigen, und Nicht-0, um einen Fehler anzuzeigen. Beachten Sie, dass ``Nicht-0'' genau das bedeutet. Wenn die Funktionsbeschreibung nichts anderes aussagt, testen Sie nicht gegen einen anderen Wert als 0:

if (ergebnis)                   /* korrekt */
    ... FEHLER ...

if (ergebnis < 0)               /* nicht korrekt */
    ... FEHLER ...

if (ergebnis == -1)             /* nicht korrekt */
    ... FEHLER ...

Wenn eine Funktion einen Fehler zurückgibt, listet der Unterabschnitt Errors der Funktionsbeschreibung die möglichen Fehlertypen auf. Sie finden heraus, welcher davon auftrat, indem Sie mysql_errno() aufrufen. Eine Zeichenketten-Darstellung des Fehler kann durch Aufruf von mysql_error() erlangt werden.

9.4.3.1 mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

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

9.4.3.2 mysql_close()

void mysql_close(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

Keine.

Fehler

Keine.

9.4.3.3 mysql_connect()

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

Beschreibung

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

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

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

Rückgabewerte

Dieselben wie für mysql_real_connect().

Fehler

Dieselben wie für mysql_real_connect().

9.4.3.4 mysql_change_user()

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

Beschreibung

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

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

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

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

Rückgabewerte

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

Fehler

Dieselben, die Sie von mysql_real_connect() erhalten.

CR_COMMANDS_OUT_OF_SYNC

Befehle wurde in nicht korrekter Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler ist aufgetreten.

ER_UNKNOWN_COM_ERROR

Der MySQL-Server hat diesen Befehl nicht implementiert (wahrscheinlich ein alter Server).

ER_ACCESS_DENIED_ERROR

Benutzername oder Passwort sind falsch.

ER_BAD_DB_ERROR

Die Datenbank existiert nicht.

ER_DBACCESS_DENIED_ERROR

Der Benutzer hat keine Zugriffsrechte auf die Datenbank.

ER_WRONG_DB_NAME

Der Datenbankname war zu lang.

Beispiel

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

9.4.3.5 mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

Der vorgabemäßige Zeichensatz

Fehler

Keine.

9.4.3.6 mysql_create_db()

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

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden in nicht korrekter Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

Beispiel

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

9.4.3.7 mysql_data_seek()

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

Beschreibung

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

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

Rückgabewerte

Keine.

Fehler

Keine.

9.4.3.8 mysql_debug()

void mysql_debug(char *debug)

Beschreibung

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

Rückgabewerte

Keine.

Fehler

Keine.

Beispiel

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

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

9.4.3.9 mysql_drop_db()

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

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

Beispiel

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

9.4.3.10 mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.11 mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

Beschreibung

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

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

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

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

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

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

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

9.4.3.12 mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.13 mysql_error()

char *mysql_error(MYSQL *mysql)

Beschreibung

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

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

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

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.14 mysql_escape_string()

Statt dessen sollten Sie mysql_real_escape_string() benutzen!

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

9.4.3.15 mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

MYSQL_FIELD *field;

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

9.4.3.16 mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

Beschreibung

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

9.4.3.17 mysql_fetch_field_direct()

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

Beschreibung

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

Rückgabewerte

Die MYSQL_FIELD-Struktur für die angegebene Spalte.

Fehler

Keine.

Beispiel

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

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

9.4.3.18 mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

Beschreibung

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

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

Rückgabewerte

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

Fehler

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

Beispiel

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

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

9.4.3.19 mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

Beispiel

MYSQL_ROW zeile;
unsigned int anzahl_felder;
unsigned int i;

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

9.4.3.20 mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

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

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

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

9.4.3.21 mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Beschreibung

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

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

Rückgabewerte

Der vorherige Wert des Feldcursors.

Fehler

Keine.

9.4.3.22 mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

Beschreibung

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

Rückgabewerte

Der aktuelle Offset des Feldcursors.

Fehler

Keine.

9.4.3.23 mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

Beschreibung

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

Rückgabewerte

Keine.

Fehler

Keine.

9.4.3.24 mysql_get_client_info()

char *mysql_get_client_info(void)

Beschreibung

Returns a string that represents the client Bibliothek version.

Rückgabewerte

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

Fehler

Keine.

9.4.3.25 mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.26 mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.27 mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

Eine Zeichenkette, die die Server-Versionsnummer bezeichnet.

Fehler

Keine.

9.4.3.28 mysql_info()

char *mysql_info(MYSQL *mysql)

Beschreibung

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

INSERT INTO ... SELECT ...

Zeichenkettenformat: Records: 100 Duplicates: 0 Warnings: 0

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

Zeichenkettenformat: Records: 3 Duplicates: 0 Warnings: 0

LOAD DATA INFILE ...

Zeichenkettenformat: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0

ALTER TABLE

Zeichenkettenformat: Records: 3 Duplicates: 0 Warnings: 0

UPDATE

Zeichenkettenformat: Rows matched: 40 Changed: 40 Warnings: 0

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.29 mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

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

9.4.3.30 mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

Beschreibung

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

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

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

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.31 mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

Beschreibung

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.32 mysql_list_dbs()

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

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_OUT_OF_MEMORY

Kein Speicher mehr.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.33 mysql_list_fields()

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

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.34 mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.35 mysql_list_tables()

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

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.36 mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

oder

unsigned int mysql_num_fields(MYSQL *mysql)

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

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

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

9.4.3.37 mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

Beschreibung

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

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

Rückgabewerte

Die Anzahl von Zeilen in der Ergebnismenge.

Fehler

Keine.

9.4.3.38 mysql_options()

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

Beschreibung

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

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

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

Mögliche Optionswerte:

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

Die angegebene Gruppe in der Optionsdatei kann folgende Optionen enthalten:

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

Weitere Informationen über Optionsdateien finden Sie unter section 5.1.2 my.cnf-Optionsdateien.

Rückgabewerte

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

Beispiel

MYSQL mysql;

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

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

9.4.3.39 mysql_ping()

int mysql_ping(MYSQL *mysql)

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.40 mysql_query()

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

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.41 mysql_real_connect()

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

Beschreibung

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

Die Parameter werden wie folgt angegeben:

• Der erste Parameter sollte die Adresse einer existierenden MYSQL-Struktur sein. Vor dem Aufruf von mysql_real_connect() müssen Sie mysql_init() aufrufen, um die MYSQL-Struktur zu initialisieren. Sie können viele der Verbindungsoptionen mit dem mysql_options()-Aufruf ändern. See section 9.4.3.38 mysql_options().
• Der Wert von host kann entweder ein Hostname oder eine IP-Adresse sein. Wenn host NULL oder die Zeichenkette "localhost" ist, wird eine Verbindung zum lokalen Host angenommen. Wenn das Betriebssystem Sockets (Unix) oder Named Pipes (Windows NT) unterstützt, werden diese statt TCP/IP benutzt, um sich mit dem Server zu verbinden.
• Der user-Parameter enthält die MySQL-Login-Benutzerkennung. Wenn user NULL ist, wird der aktuelle Benutzer angenommen. Unter Unix ist das der aktuelle Login-Name. Unter Windows-ODBC muss der aktuelle Benutzername explizit angegeben werden. See section 9.3.2 Wie Sie die verschiedenen Felder im ODBC-Administrator Programm ausfüllen.
• Der passwd-Parameter enthält das Passwort für user. Wenn passwd NULL ist, werden nur Einträge in der user-Tabelle für Benutzer auf Übereinstimmung überprüft, die ein leeres Passwort-Feld haben. Das erlaubt dem Datenbank-Administrator, das MySQL-Berechtigungssystem so einzurichten, dass Benutzer unterschiedliche Berechtigungen haben, je nachdem, ob sie ein Passwort angegeben haben oder nicht. HINWEIS: Versuchen Sie nicht, dass Passwort zu verschlüsseln, bevor Sie mysql_real_connect() aufrufen. Die Passwortverschlüsselung wird automatisch durch die Client-API gehandhabt.
• db ist der Datenbankname. Wenn db nicht NULL ist, wird die vorgabemäßige Datenbank für die Verbindung auf diesen Wert gesetzt.
• Wenn port nicht 0 ist, wird dieser Wert als Port-Nummer für die TCP/IP-Verbindung benutzt. Beachten Sie, dass der host-Parameter den Verbindungstyp festlegt.
• Wenn unix_socket nicht NULL ist, legt die Zeichenkette den Socket oder die Named Pipe fest, die benutzt werden sollen. Beachten Sie, dass der host-Parameter den Verbindungstyp festlegt.
• Der Wert von client_flag ist üblicherweise 0, kann aber unter sehr speziellen Umständen auf eine Kombination folgender Flags gesetzt werden:

  Flag-Name	Flag-Bedeutung
  CLIENT_COMPRESS	Komprimiertes Protokoll benutzen.
  CLIENT_FOUND_ROWS	Die Anzahl gefundener (übereinstimmender) Zeilen zurückgeben, nicht die Anzahl betroffener Zeilen.
  CLIENT_IGNORE_SPACE	Leerzeichen nach Funktionsnamen zulassen. Macht alle Funktionsnamen zu reservierten Wörter.
  CLIENT_INTERACTIVE	interactive_timeout Sekunden zulassen (anstelle von wait_timeout Sekunden) von Inaktivität, bevor die Verbindung geschlossen wird.
  CLIENT_NO_SCHEMA	Die datenbank.tabelle.spalte-Syntax nicht zulassen. Das ist für ODBC. Der Flag veranlasst den Parser, einen Fehler zu erzeugen, wenn Sie diese Syntax benutzen, was für die Fehlersuche in einigen ODBC-Programmen hilfreich ist.
  CLIENT_ODBC	Der Client ist ein ODBC-Client. Das ändert
  CLIENT_SSL	SSL benutzen (verschlüsseltes Protokoll).

Rückgabewerte

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

Fehler

CR_CONN_HOST_ERROR

Verbindung zum MySQL-Server fehlgeschlagen.

CR_CONNECTION_ERROR

Verbindung zum lokalen MySQL-Server fehlgeschlagen.

CR_IPSOCK_ERROR

IP-Socket konnte nicht erzeugt werden.

CR_OUT_OF_MEMORY

Kein Speicher mehr.

CR_SOCKET_CREATE_ERROR

Unix-Socket konnte nicht erzeugt werden.

CR_UNKNOWN_HOST

IP-Adresse für den Hostnamen konnte nicht gefunden werden.

CR_VERSION_ERROR

Eine Protokollunverträglichkeit resultierte aus dem Versuch, sich mit einer Client-Bibliothek mit einem Server zu verbinden, die eine andere Protokollversion benutzt. Das kann passieren, wenn Sie eine sehr alte Client-Bibliothek benutzen und sich mit einem neuen Server verbinden, der nicht mit der --old-protocol-Option gestartet wurde.

CR_NAMEDPIPEOPEN_ERROR

Named Pipe unter Windows konnte nicht erzeugt werden.

CR_NAMEDPIPEWAIT_ERROR

Fehler beim Warten auf eine Named Pipe unter Windows.

CR_NAMEDPIPESETSTATE_ERROR

Pipe-Handler unter Windows konnte nicht erlangt werden.

CR_SERVER_LOST

Wenn connect_timeout > 0 ist und die Verbindung zum Server länger als connect_timeout benötigte, oder wenn der Server während der Ausführung von init-command starb.

Beispiel

MYSQL mysql;

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

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

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

9.4.3.42 mysql_real_escape_string()

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

Beschreibung

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

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

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

Beispiel

char anfrage[1000],*end;

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

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

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.43 mysql_real_query()

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

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.44 mysql_reload()

int mysql_reload(MYSQL *mysql)

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.45 mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *ergebnis, MYSQL_ROW_OFFSET offset)

Beschreibung

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

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.46 mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *ergebnis)

Beschreibung

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

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

Rückgabewerte

Der aktuelle Offset des Zeilencursors.

Fehler

Keine.

9.4.3.47 mysql_select_db()

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

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.48 mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.49 mysql_stat()

char *mysql_stat(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.50 mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

Beschreibung

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

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

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

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

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

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

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

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

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

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_OUT_OF_MEMORY

Kein Speicher mehr.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.3.51 mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

Beschreibung

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

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

Rückgabewerte

Die Thread-Kennung der aktuellen Verbindung.

Fehler

Keine.

9.4.3.52 mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

Beschreibung

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

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

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

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

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC

Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.

CR_OUT_OF_MEMORY

Kein Speicher mehr.

CR_SERVER_GONE_ERROR

Der MySQL-Server ist weg.

CR_SERVER_LOST

Die Verbindung zum Server ging während der Anfrage verloren.

CR_UNKNOWN_ERROR

Ein unbekannter Fehler trat auf.

9.4.4 C-Threaded-Funktionsbeschreibungen

Sie benötigen folgende Funktionen, wenn Sie einen threaded Client erstellen wollen. See section 9.4.8 Wie man einen threaded Client herstellt.

9.4.4.1 my_init()

Beschreibung

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

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

Rückgabewerte

Keine.

9.4.4.2 mysql_thread_init()

Beschreibung

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

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

Rückgabewerte

Keine.

9.4.4.3 mysql_thread_end()

Beschreibung

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

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

Rückgabewerte

Keine.

9.4.4.4 mysql_thread_safe()

unsigned int mysql_thread_safe(void)

Description

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

Return Values

1 is the client is thread safe, 0 otherwise.

9.4.5 C-Embedded-Server-Funktionsbeschreibungen

Sie müssen folgende Funktionen benutzen, wenn Sie wollen, dass Ihre Applikation gegen die eingebettete MySQL-Server-Bibliothek gelinkt werden kann. See section 9.4.9 libmysqld, die eingebettete MySQL-Server-Bibliothek.

Wenn das Programm mit -lmysqlclient anstelle von -lmysqld gelinkt wird, tun diese Funktionen nicht. Das ermöglicht die Auswahl zwischen der Benutzung des eingebetteten MySQL-Servers und eines Standalone-Servers, ohne irgend welchen Code zu verändern.

9.4.5.1 mysql_server_init()

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

Beschreibung

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

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

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

Beispiel

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

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

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

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

  mysql_server_end();

  return EXIT_SUCCESS;
}

Rückgabewerte

Keine.

9.4.5.2 mysql_server_end()

Beschreibung

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

Rückgabewerte

Keine.

9.4.6 Häufige Fragen und Probleme bei der Benutzung der C-API

9.4.6.1 Warum gibt mysql_store_result() manchmal NULL zurück, nachdem mysql_query() Erfolg zurückgegeben hat?

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

• Es gab einen malloc()-Fehler (zum Beispiel, wenn die Ergebnismenge zu Groß war).
• Die Daten konnten nicht gelesen werden (ein Fehler mit der Verbindung trat auf).
• Die Anfrage gab keine Daten zurück (sie war zum Beispiel ein INSERT, UPDATE oder DELETE).

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

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

9.4.6.2 Welche Ergebnisse kann ich von einer Anfrage bekommen?

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

• mysql_affected_rows() gibt die Anzahl von Zeilen zurück, die durch die letzte Anfrage betroffen wurden, wenn Sie ein INSERT, UPDATE oder DELETE ausführen. Eine Ausnahme besteht darin, wenn DELETE ohne eine WHERE-Klausel benutzt wird. In diesem Fall wird die Tabelle leer neu erzeugt, was viel schneller ist! Daher gibt mysql_affected_rows() 0 für die Anzahl betroffener Datensätze zurück.
• mysql_num_rows() gibt die Anzahl von Zeilen in einer Ergebnismenge zurück. Bei mysql_store_result() kann mysql_num_rows() aufgerufen werden, sobald mysql_store_result() etwas zurückgibt. Bei mysql_use_result() kann mysql_num_rows() erst aufgerufen werden, nachdem Sie alle Zeilen mit mysql_fetch_row() geholt haben.
• mysql_insert_id() gibt die Kennung zurück, die von der letzten Anfrage erzeugt wurde, die eine Zeile in eine Tabelle mit einem AUTO_INCREMENT-Index einfügte. See section 9.4.3.30 mysql_insert_id().
• Einige Anfragen (LOAD DATA INFILE ..., INSERT INTO ... SELECT ..., UPDATE) geben zusätzliche Informationen zurück. Das Ergebnis wird von mysql_info() zurückgegeben. Siehe die Beschreibung für mysql_info() hinsichtlich des Formats der Zeichenkette, die diese Funktion zurückgibt. mysql_info() gibt einen NULL-Zeiger zurück, wenn es keine zusätzlichen Informationen gibt.

9.4.6.3 Wie erhalte ich die eindeutige Kennung für die letzte eingefügte Zeile?

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

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

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

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

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

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

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

9.4.6.4 Probleme beim Linken mit der C-API

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

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

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

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

9.4.7 Client-Programme bauen

Wenn Sie MySQL-Clients kompilieren, die Sie selbst geschrieben oder von Dritten erhalten haben, müssen diese mit der -lmysqlclient -lz-Option für den Link-Befehl gelinkt werden. Eventuell sollten Sie auch eine -L-Option verwenden, um dem Linker mitzuteilen, wo sich die Bibliothek befindet. Wenn zum Beispiel die Bibliothek in `/usr/local/mysql/lib' installiert ist, benutzen Sie -L/usr/local/mysql/lib -lmysqlclient -lz für den Link-Befehl.

Für Clients, die MySQL-Header-Dateien benutzen, müssen Sie eventuell eine -I-Option angeben, wenn Sie sie kompilieren (zum Beispiel -I/usr/local/mysql/include), so dass der Kompiler die Header-Dateien finden kann.

9.4.8 Wie man einen threaded Client herstellt

Die Client-Bibliothek ist fast Thread-sicher. Das größte Problem besteht darin, dass die Subroutinen in `net.c', die von Sockets lesen, nicht Interrupt-sicher sind. Das wurde mit dem Hintergedanken gemacht, dass Sie eventuell Ihre eigenen Alarme haben möchten, die ein langes Lesen vom Server unterbrechen können. Wenn Sie Interrupt-Handler für den SIGPIPE-Interrupt installieren, sollte die Socket-Handhabung Thread-sicher sein.

In den älteren Binärdistributionen wurden die Client-Bibliotheken normalerweise nicht mit der Thread-sicheren Option kompiliert (die Windows-Binärdateien sind vorgabemäßig Thread-sicher kompiliert). Neuere Binärdistributionen sollten sowohl eine normale als auch eine Thread-sichere Client-Bibliothek haben.

Um einen threaded Client zu erhalten, bei dem Sie den Client durch andere Threads unterbrechen (interrupt) und Zeitüberschreitungen (Timeouts) setzen können, wenn Sie mit dem MySQL-Server kommunizieren, sollten Sie die -lmysys-, -lstring-, und -ldbug-Bibliotheken und den net_serv.o-Code benutzen, den der Server benutzt.

Wenn Sie keine Unterbrechungen (Interrupts) oder Zeitüberschreitungen (Timeouts) benötigen, können Sie einfach eine Thread-sicher Client-Bibliothek (mysqlclient_r) kompilieren und diese benutzen. See section 9.4 MySQL-C-API. In diesem Fall müssen Sie sich nicht um die net_serv.o-Objektdatei oder die anderen MySQL-Bibliotheken kümmern.

Wenn Sie einen threaded Client benutzen und Unterbrechungen (Interrupts) und Zeitüberschreitungen (Timeouts) benutzen wollen, können Sie in umfangreicher Weise die Routinen in der `thr_alarm.c'-Datei benutzen. Wenn Sie Routinen aus der mysys-Bibliothek benutzen, müssen Sie lediglich daran denken, my_init() zuerst aufzurufen! See section 9.4.4 C-Threaded-Funktionsbeschreibungen.

Alle Funktionen ausser mysql_real_connect() sind vorgabemäßig Thread-sicher. Die folgenden Hinweise beschreiben, wie man eine Thread-sichere Client-Bibliothek kompiliert und sie auf Thread-sichere Weise benutzt. (Die unten stehenden Hinweise für mysql_real_connect() beziehen sich in der Tat auch auf mysql_connect(). Weil aber mysql_connect() veraltet ist, sollten Sie in jedem Fall mysql_real_connect() benutzen.)

Um mysql_real_connect() Thread-sicher zu machen, müssen Sie die Client-Bibliothek mit diesem Befehl neu kompilieren:

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

Das erzeugt eine Thread-sichere Client-Bibliothek libmysqlclient_r. --enable-thread-safe-client. Diese Bibliothek ist pro Verbindung Thread-sicher. Sie können zwei Threads dieselbe Verbindung benutzen lassen, solange Sie folgendes tun:

• Zwei Threads können zur gleichen Zeit keine Anfrage an MySQL über dieselbe Verbindung schicken. Insbesondere müssen Sie sicherstellen, dass zwischen einem mysql_query() und einem mysql_store_result() kein anderer Thread dieselbe Verbindung benutzt.
• Viele Threads können auf unterschiedliche Ergebnismengen zugreifen, die mit mysql_store_result() abgerufen wurden.
• Wenn Sie mysql_use_result benutzen, müssen Sie sicherstellen, dass kein anderer Thread irgend etwas über dieselbe Verbindung anfragt, bis die Ergebnismenge geschlossen wurde. Für threaded Clients, die dieselbe Verbindung benutzen, ist es jedoch am besten, mysql_use_result() zu benutzen.
• Wenn Sie mehrfache Threads über dieselbe Verbindung benutzen wollen, müssen Sie eine mutex-Sperre um Ihre mysql_query()- und mysql_store_result()-Aufruf-Kombination haben. Sobald mysql_store_result() fertig ist, kann die Sperre aufgehoben werden und andere Threads können über dieselbe Verbindung anfragen.
• Wenn Sie mit POSIX-Threads programmieren, können Sie pthread_mutex_lock() und pthread_mutex_unlock() benutzen, um eine mutex-Sperre aufzubauen und aufzuheben.

Sie müssen folgendes wissen, wenn Sie einen Thread haben, der MySQL-Funktionen aufruft, dieser Thread aber keine Verbindung zur MySQL-Datenbank aufgebaut hat:

Wenn Sie mysql_init() oder mysql_connect() aufrufen, erzeugt MySQL eine Thread-spezifische Variable für diesen Thread, die von der Debug-Bibliothek benutzt wird (unter anderem).

Wenn Sie in einem Thread-Aufruf eine MySQL-Funktion haben, bevor ein Thread mysql_init() oder mysql_connect() aufgerufen hat, hat der Thread nicht notwendigerweise Thread-spezifische Variablen zur Hand, und Sie werden wahrscheinlich früher oder später einen Coredump erhalten. Damit alles reibungslos funktioniert, müssen Sie folgendes tun:

1. Rufen Sie bei Programmbeginn my_init() auf, wenn Ihr Programm irgend welche MySQL-Funktion vor dem Aufruf von mysql_real_connect() benutzt.
2. Rufen Sie mysql_thread_init() im Thread-Handler auf, bevor Sie irgend welche MySQL-Funktionen aufrufen.
3. Rufen Sie im Thread mysql_thread_end() auf, bevor Sie pthread_exit() aufrufen. Das gibt Speicher frei, der von MySQL-Thread-spezifischen Variablen benutzt wird.

Eventuell erhalten Sie Fehler wegen undefinierter Symbole, wenn Sie Ihren Client mit mysqlclient_r linken. In den meisten Fällen liegt das daran, dass Sie die Thread-Bibliotheken nicht auf der Link- / Kompilierzeile eingeschlossen haben.

9.4.9 libmysqld, die eingebettete MySQL-Server-Bibliothek

9.4.9.1 Überblick über die eingebettete MySQL-Server-Bibliothek

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

9.4.9.2 Programme mit libmysqld kompilieren

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

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

9.4.9.3 Ein einfaches Embedded-Server-Beispiel

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

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

`example.c'

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

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

enum on_error { E_okay, E_warn, E_fail };

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

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

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

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

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

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

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

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

  mysql_close(two);
  mysql_close(one);

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

  exit(EXIT_SUCCESS);
}

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

MYSQL *
db_connect(const char *dbname)
{
  MYSQL *db = mysql_init(NULL);
  if (!db)
    die(db, "mysql_init fehlgeschlagen: kein Speicher mehr");
  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "simple");
  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
    die(db, "mysql_real_connect fehlgeschlagen: %s", mysql_error(db));

  return db;
}

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

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

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

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

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

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

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

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

  return err;
}

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

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

  return;

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

`GNUmakefile'

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

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

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

# Standard-Bibliotheken

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

# Optional gebaute Bibliotheken

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

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

# Unterstützte Bibliotheken

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

# Optional gebaute unterstützte Bibliotheken

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

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

all: $(targets)

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

9.4.9.4 Lizensierung des eingebetteten Servers

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

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

9.5 MySQL-C++-APIs

9.5.1 Borland C++

Sie können den MySQL-Windows-Quellcode mit Borlund C++ 5.02 kompilieren. (Der Windows-Quellcode beinhaltet nur Projekte für Microsoft VC++, für Borland C++ müssen Sie die Projektdateien selbst erstellen).

Ein bekanntes Problem bei Borland C++ ist, dass es eine andere Strukturanordnung benutzt als VC++. Das bedeutet, dass Sie Probleme bekommen, wenn Sie versuchen, die vorgabemäßigen libmysql.dll-Bibliotheken (die mit VC++ kompiliert wurden) mit Borland C++ zu verwenden. Sie können eins der folgenden Dinge tun, um dieses Problem zu vermeiden:

• Sie können statische MySQL-Bibliotheken für Borland C++ verwenden, die Sie unter http://www.mysql.com/downloads/os-win32.html finden.
• Rufen Sie mysql_init() nur mit NULL als Argument auf, kein vorher zugewiesenes (prä-alloziertes) MySQL-Strukt.

9.6 MySQL Java Connectivity (JDBC)

Es gibt 2 unterstützte JDBC-Treiber für MySQL (den mm-Treiber und den Reisin JDBC-Treiber). Sie finden den mm-Treiber unter http://mmmysql.sourceforge.net/ oder http://www.mysql.com/Downloads/Contrib/ und den Reisin-Treiber unter http://www.caucho.com/Projekte/jdbc-mysql/index.xtp. Wegen der Dokumentation sehen Sie sich irgend eine JDBC-Dokumentation durch sowie die eigene Dokumentation der Treiber wegen MySQL-spezifischer Features.

9.7 MySQL-Python-APIs

Das MySQL-Contrib-Verzeichnis enthält eine Python-Schnittstelle, die von Joseph Skinner geschrieben wurde.

MySQLdb bietet MySQL-Unterstützung für Python, konform mit Python DB API Version 2.0. MySQLdb finden Sie hier: http://sourceforge.net/projects/mysql-python/.

9.8 MySQL-Tcl-APIs

MySQLtcl ist eine einfache API zum Zugriff auf einen MySQL-Datenbankserver von der Tcl-Programmiersprache aus. Sie finden die API hier: http://www.xdobry.de/mysqltcl/.

9.9 MySQL-Eiffel-Wrapper

Eiffel MySQL ist eine Schnittstelle zum MySQL-Datenbankserver, die die von Michael Ravits geschriebene Programmiersprache benutzt. Sie finden die Schnittstelle hier: http://efsa.sourceforge.net/archive/ravits/mysql.htm.

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