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


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

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

connect Errichtet eine Verbindung zum Datenbankserver.
disconnect Trennt eine Verbindung zum Datenbankserver.
prepare Bereitet ein SQL-Statement zur Abfrage vor.
execute Führt eine vorbereitetes Statement aus.
do Bereitet ein SQL-Statement vor und führt es aus.
quote Quotet eine Zeichenkette oder einen BLOB-Wert zum Einfügen.
fetchrow_array Holt die nächste Zeile als einen Array aus Feldern.
fetchrow_arrayref Holt die nächste Zeile als eine Referenz eines Arrays aus Feldern.
fetchrow_hashref Holt die nächste Zeile als eine Referenz einer Hash-Tabelle.
fetchall_arrayref Holt alle Zeilen als einen Array von Arrays.
finish Beendet ein Statement und läßt das System Resourcen freigeben.
rows Gibt die Anzahl der betroffenen Zeilen zurück.
data_sources Gibt einen Array mit den verfügbaren Daten auf localhost zurück.
ChopBlanks Kontroliert, ob die fetchrow_*-Methoden Leerzeichen entfernen.
NUM_OF_PARAMS Die Anzahl der Platzhalter in einem vorbereiteten Statement.
NULLABLE Welche Spalten NULL sein können.
trace Tracen zum Debuggen ausführen.

MySQL-spezifische Methoden

insertid Der letzte AUTO_INCREMENT-Wert.
is_blob Welche Spalten BLOB-Werte sind.
is_key Welche Spalten Schlüssel sind.
is_num Welche Spalten numerisch sind.
is_pri_key Welche Spalten Primärschlüssel sind.
is_not_null Welche Spalten NICHT NULL sein können. Siehe auch NULLABLE.
length Maximal mögliche Spaltengröße.
max_length Maximale Spaltengröße, die im aktuellen Ergebnis enthalten ist.
NAME Spaltennamen.
NUM_OF_FIELDS Anzahl der zurückgegebenen Felder.
table Tabellennamen im zurückgegebenen Ergebnis.
type Alle Spaltentypen.

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.

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:

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.159 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:

Parameter Standardwert Bedeutung
user ODBC (unter Windows) Der Benutzername, der verwendet wird, um zu MySQL zu verbinden.
server localhost Der Hostname des MySQL-Servers.
database Die Standarddatenbank
option 0 Eine Ganzzahl, die angibt, wie MyODBC arbeiten soll. Siehe unten.
port 3306 Der TCP/IP-Port, der verwendet werden soll, wenn der server nicht localhost ist.
stmt Ein Statement, das bei der Verbindung zu MySQL ausgeführt wird.
password Das Passwort für die server-user-Kombination.
socket Der Socket oder die Windows-Pipe, über die verbunden werden soll.

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:

Bit Bedeutung
1 Der Client kann nicht damit umgehen, dass MyODBC die wirkliche Breite einer Spalte zurückgibt.
2 Der Client kann nicht damit umgehen, dass MySQL die wirkliche Anzahl an "affected rows" zurückgibt. Wenn dieses Bit gesetzt ist, wird MySQL statt dessen 'found rows' zurückgeben. Dies wird erst ab MySQL 3.21.14 unterstützt.
4 Erstellt ein Debug-Log in c:\myodbc.log. Das ist dasselbe, als wenn Sie MYSQL_DEBUG=d:t:O,c::\myodbc.log in Ihre `AUTOEXEC.BAT' schreiben.
8 Entfernt jede Paket-Beschränkung für Ergebnisse und Parameter.
16 Nicht auf Eingaben warten, sogar wenn der Treiber dies verlangt.
32 Einen ODBC 1.0 Treiber simulieren.
64 Die Angabe 'datenbank' in 'datenbank.tabelle.spalte' ignorieren.
128 Die Verwendung von ODBC-Manager-Zeigern erzwingen (experimentell).
256 Die Verwendung des erweiterten 'fetch' verbieten (experimentell).
512 CHAR-Felder bis zur vollen Spaltenlänge füllen.
1024 SQLDescribeCol() wird voll qualifizierte Spaltennamen zurückgeben.
2048 Verwendet das komprimierte Client-/Server Protokoll.
4096 Weist den Server an, Leerzeichen nach einem Funktionsnamen und vor '(' zu ignorieren (wird von PowerBuilder benötigt). So werden alle Funktionsnamen zu Schlüsselwörtern!
8192 Über "Named Pipes" zu einem mysqld-Server verbinden, der unter Windows NT läuft.
16384 Ändert LONGLONG-Spalten zu INT-Spalten (einige Applikationen können mit LONGLONG nicht umgehen).
32768 Gibt 'user' als Tabellenqualifizierer und Tabellen-Besitzer von SQL-Tabellen zurück (experimentell).
65536 Liest die Parameter client und odbc-Gruppen aus der `my.cnf'-Datei.
131072 Fügt einige Sicherheitsüberprüfungen hinzu (sollte nicht nötig sein, aber ...).

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:

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:
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:
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:
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.

mysql_affected_rows() Gibt die Anzahl von Zeilen zurück, die durch die letzte UPDATE-, DELETE- oder INSERT-Anfrage geändert, gelöscht bzw. hinzugefügt wurden.
mysql_close() Schließt eine Server-Verbindung.
mysql_connect() Stellt die Verbindung mit einem MySQL-Server her. Diese Funktion ist veraltet, benutzen Sie statt dessen mysql_real_connect().
mysql_change_user() Ändert Benutzer und Datenbank bei einer geöffneten Verbindung.
mysql_character_set_name() Gibt den Namen des vorgabemäßigen Zeichensatzes für die Verbindung zurück.
mysql_create_db() Erzeugt eine Datenbank. Diese Funktion ist veraltet, benutzen Sie statt dessen den SQL-Befehl CREATE DATABASE.
mysql_data_seek() Sucht bis zu einer beliebigen Zeile in einer Anfrage-Ergebnismenge.
mysql_debug() Macht ein DBUG_PUSH mit der angegebenen Zeichenkette.
mysql_drop_db() Löscht eine Datenbank. Diese Funktion ist veraltet, benutzen Sie statt dessen den SQL-Befehl DROP DATABASE.
mysql_dump_debug_info() Veranlasst den Server, Debug-Informationen in die Log-Datei zu schreiben.
mysql_eof() Stellt fest, ob die letzte Zeile der Ergebnismenge gelesen wurde oder nicht. Diese Funktion ist veraltet, benutzen Sie statt dessen mysql_errno() oder mysql_error().
mysql_errno() Gibt die Fehlernummer der zuletzt aufgerufenen MySQL-Funktion zurück.
mysql_error() Gibt die Fehlermeldung der zuletzt aufgerufenen MySQL-Funktion zurück.
mysql_real_escape_string() Escapet Sonderzeichen in einer Zeichenkette, die für ein SQL-Statement benutzt wird, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird.
mysql_escape_string() Escapet Sonderzeichen in einer Zeichenkette, die für ein SQL-Statement benutzt wird.
mysql_fetch_field() Gibt den Typ des nächsten Tabellenfelds zurück.
mysql_fetch_field_direct() Gibt den Typ eines Tabellenfelds zurück, angegeben durch eine Feldnummer.
mysql_fetch_fields() Gibt ein Array aller Feldstrukturen zurück.
mysql_fetch_lengths() Gibt die Länge aller Spalten in der aktuellen Zeile zurück.
mysql_fetch_row() Holt die nächste Zeile aus der Ergebnismenge.
mysql_field_seek() Setzt den Spaltencursor auf eine bestimmte Spalte.
mysql_field_count() Gibt die Anzahl der Ergebnisspalten für die letzte Anfrage zurück.
mysql_field_tell() Gibt die Position des Feldcursors zurück, der für das letzte mysql_fetch_field() benutzt wurde.
mysql_free_result() Gibt Speicher frei, der von einer Ergebnismenge benutzt wird.
mysql_get_client_info() Gibt Client-Versionsinformationen zurück.
mysql_get_host_info() Gibt eine Zeichenkette zurück, die die Verbindung beschreibt.
mysql_get_proto_info() Gibt die Protokollversion zruück, die von der Verbindung benutzt wird.
mysql_get_server_info() Gibt die Server-Versionsnummer zurück.
mysql_info() Gibt Informationen über die zuletzt ausgeführte Anfrage zurück.
mysql_init() Holt oder initialisiert eine MYSQL-Struktur.
mysql_insert_id() Gibt die Kennung zurück, die für eine AUTO_INCREMENT-Spalte durch die letzte Anfrage erzeugt wurde.
mysql_kill() Tötet einen angegebenen Thread.
mysql_list_dbs() Gibt die Datenbanknamen zurück, die mit einem einfachen regulären Ausdruck übereinstimmen.
mysql_list_fields() Gibt die Feldnamen zurück, die mit einem einfachen regulären Ausdruck übereinstimmen.
mysql_list_processes() Gibt eine Liste der aktuellen Server-Threads zurück.
mysql_list_tables() Gibt Tabellenamen zurück, die mit einem einfachen regulären Ausdruck übereinstimmen.
mysql_num_fields() Gibt die Anzahl von Spalten in einer Ergebnismenge zurück.
mysql_num_rows() Gibt die Anzahl von Zeilen in einer Ergebnismenge zurück.
mysql_options() Setzt Verbindungsoptionen für mysql_connect().
mysql_ping() Prüft, ob die Verbindung zum Server funktioniert oder nicht und verbindet sich erneut, falls notwendig.
mysql_Anfrage() Führt eine SQL-Anfrage aus, die als NULL-begrenzte Zeichenkette angegeben wird.
mysql_real_connect() Verbindet sich mit einem MySQL-Server.
mysql_real_query() Führt eine SQL-Anfrage aus, die als gezählte Zeichenkette angegeben wird.
mysql_reload() Weist den Server an, die Berechtigungstabellen erneut zu laden.
mysql_row_seek() Sucht bis zu einer Zeile in einer Ergebnismenge, indem sie den Wert benutzt, der von mysql_row_tell() zurückgegeben wird.
mysql_row_tell() Gibt die Zeilencursorposition zurück.
mysql_select_db() Wählt eine Datenbank aus.
mysql_shutdown() Fährt den Datenbankserver herunter.
mysql_stat() Gibt den Serverstatus als Zeichenkette zurück.
mysql_store_result() Ruft eine komplette Ergebnismenge zum Client ab.
mysql_thread_id() Gibt die aktuelle Thread-Kennung zurück.
mysql_thread_safe() Gibt 1 zurück, wenn die Clients Thread-sicher kompiliert sind.
mysql_use_result() Initialisiert den zeilenweisen Abruf einer Ergebnismenge.

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)

9.4.3.2 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().

9.4.3.3 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.

9.4.3.4 Fehler

Keine.

9.4.3.5 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.6 mysql_close()

void mysql_close(MYSQL *mysql)

9.4.3.7 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.

9.4.3.8 Rückgabewerte

Keine.

9.4.3.9 Fehler

Keine.

9.4.3.10 mysql_connect()

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

9.4.3.11 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.)

9.4.3.12 Rückgabewerte

Dieselben wie für mysql_real_connect().

9.4.3.13 Fehler

Dieselben wie für mysql_real_connect().

9.4.3.14 mysql_change_user()

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

9.4.3.15 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.

9.4.3.16 Rückgabewerte

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

9.4.3.17 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.

9.4.3.18 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.19 mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

9.4.3.20 Beschreibung

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

9.4.3.21 Rückgabewerte

Der vorgabemäßige Zeichensatz

9.4.3.22 Fehler

Keine.

9.4.3.23 mysql_create_db()

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

9.4.3.24 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.

9.4.3.25 Rückgabewerte

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

9.4.3.26 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.

9.4.3.27 Beispiel

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

9.4.3.28 mysql_data_seek()

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

9.4.3.29 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.

9.4.3.30 Rückgabewerte

Keine.

9.4.3.31 Fehler

Keine.

9.4.3.32 mysql_debug()

void mysql_debug(char *debug)

9.4.3.33 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.

9.4.3.34 Rückgabewerte

Keine.

9.4.3.35 Fehler

Keine.

9.4.3.36 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.37 mysql_drop_db()

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

9.4.3.38 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.

9.4.3.39 Rückgabewerte

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

9.4.3.40 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 Beispiel

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

9.4.3.42 mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

9.4.3.43 Beschreibung

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

9.4.3.44 Rückgabewerte

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

9.4.3.45 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.46 mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

9.4.3.47 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.)

9.4.3.48 Rückgabewerte

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

9.4.3.49 Fehler

Keine.

9.4.3.50 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.51 mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

9.4.3.52 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'.

9.4.3.53 Rückgabewerte

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

9.4.3.54 Fehler

Keine.

9.4.3.55 mysql_error()

char *mysql_error(MYSQL *mysql)

9.4.3.56 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.

9.4.3.57 Rückgabewerte

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

9.4.3.58 Fehler

Keine.

9.4.3.59 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.60 mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

9.4.3.61 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.

9.4.3.62 Rückgabewerte

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

9.4.3.63 Fehler

Keine.

9.4.3.64 Beispiel

MYSQL_FIELD *field;

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

9.4.3.65 mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

9.4.3.66 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.

9.4.3.67 Rückgabewerte

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

9.4.3.68 Fehler

Keine.

9.4.3.69 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.70 mysql_fetch_field_direct()

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

9.4.3.71 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.

9.4.3.72 Rückgabewerte

Die MYSQL_FIELD-Struktur für die angegebene Spalte.

9.4.3.73 Fehler

Keine.

9.4.3.74 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.75 mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

9.4.3.76 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.

9.4.3.77 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.

9.4.3.78 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.

9.4.3.79 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.80 mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

9.4.3.81 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.

9.4.3.82 Rückgabewerte

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

9.4.3.83 Fehler

CR_SERVER_LOST
Die Verbindung zum Server ging während der Anfrage verloren.
CR_UNKNOWN_ERROR
Ein unbekannter Fehler trat auf.

9.4.3.84 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.85 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.

9.4.3.86 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?.

9.4.3.87 Rückgabewerte

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

9.4.3.88 Fehler

Keine.

9.4.3.89 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.90 mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

9.4.3.91 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.

9.4.3.92 Rückgabewerte

Der vorherige Wert des Feldcursors.

9.4.3.93 Fehler

Keine.

9.4.3.94 mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

9.4.3.95 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.

9.4.3.96 Rückgabewerte

Der aktuelle Offset des Feldcursors.

9.4.3.97 Fehler

Keine.

9.4.3.98 mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

9.4.3.99 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.

9.4.3.100 Rückgabewerte

Keine.

9.4.3.101 Fehler

Keine.

9.4.3.102 mysql_get_client_info()

char *mysql_get_client_info(void)

9.4.3.103 Beschreibung

Returns a string that represents the client Bibliothek version.

9.4.3.104 Rückgabewerte

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

9.4.3.105 Fehler

Keine.

9.4.3.106 mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

9.4.3.107 Beschreibung

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

9.4.3.108 Rückgabewerte

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

9.4.3.109 Fehler

Keine.

9.4.3.110 mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

9.4.3.111 Beschreibung

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

9.4.3.112 Rückgabewerte

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

9.4.3.113 Fehler

Keine.

9.4.3.114 mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

9.4.3.115 Beschreibung

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

9.4.3.116 Rückgabewerte

Eine Zeichenkette, die die Server-Versionsnummer bezeichnet.

9.4.3.117 Fehler

Keine.

9.4.3.118 mysql_info()

char *mysql_info(MYSQL *mysql)

9.4.3.119 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.

9.4.3.120 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.

9.4.3.121 Fehler

Keine.

9.4.3.122 mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

9.4.3.123 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.

9.4.3.124 Rückgabewerte

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

9.4.3.125 Fehler

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

9.4.3.126 mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

9.4.3.127 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.

9.4.3.128 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.

9.4.3.129 Fehler

Keine.

9.4.3.130 mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

9.4.3.131 Beschreibung

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

9.4.3.132 Rückgabewerte

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

9.4.3.133 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.134 mysql_list_dbs()

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

9.4.3.135 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.

9.4.3.136 Rückgabewerte

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

9.4.3.137 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.138 mysql_list_fields()

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

9.4.3.139 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.

9.4.3.140 Rückgabewerte

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

9.4.3.141 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.142 mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

9.4.3.143 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.

9.4.3.144 Rückgabewerte

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

9.4.3.145 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.146 mysql_list_tables()

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

9.4.3.147 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.

9.4.3.148 Rückgabewerte

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

9.4.3.149 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.150 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.

9.4.3.151 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?.

9.4.3.152 Rückgabewerte

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

9.4.3.153 Fehler

Keine.

9.4.3.154 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.155 mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

9.4.3.156 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.

9.4.3.157 Rückgabewerte

Die Anzahl von Zeilen in der Ergebnismenge.

9.4.3.158 Fehler

Keine.

9.4.3.159 mysql_options()

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

9.4.3.160 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:

Option Argumenttyp Funktion
MYSQL_OPT_CONNECT_TIMEOUT unsigned int * Verbindungszeitüberschreitung (Timeout) in Sekunden.
MYSQL_OPT_COMPRESS Unbenutzt Das komprimierte Client-/Server-Protokoll verwenden.
MYSQL_OPT_NAMED_PIPE Unbenutzt Named Pipes benutzen, um sich mit einem MySQL-Server unter NT zu verbinden.
MYSQL_INIT_COMMAND char * Befehl, der beim Verbinden mit dem MySQL-Server ausgeführt werden soll. Wird beim erneuten Verbinden automatisch wieder ausgeführt.
MYSQL_READ_DEFAULT_FILE char * Optionen aus der benannten Optionsdatei einlesen anstelle von `my.cnf'.
MYSQL_READ_DEFAULT_GROUP char * Optionen aus der benannten Gruppe von `my.cnf' oder der Datei einlesen, die durch MYSQL_READ_DEFAULT_FILE angegeben wurde.

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:

connect_timeout Zeitüberschreitung (Timeout) für die Verbindung in Sekunden. Unter Linux wird dieser Wert zusätzlich für die Wartezeit auf die erste Antwort vom Server benutzt.
compress Das komprimierte Client-/Server-Protokoll benutzen.
database Mit dieser Datenbank verbinden, wenn im Verbindungsbefehl keine Datenbank angegeben wurde.
debug Debug-Optionen.
host Vorgabemäßiger Hostname.
init-commund Befehl, der bei der Verbindung zum MySQL-Server ausgeführt wird. Wird automatisch beim erneuten Verbinden erneut ausgeführt.
interactive-timeout Dasselbe wie die Angabe von CLIENT_INTERACTIVE für mysql_real_connect(). See section 9.4.3.171 mysql_real_connect().
password Vorgabemäßiges Passwort.
pipe Named Pipes benutzen, um sich mit einem MySQL-Server unter NT zu verbinden.
port Vorgabemäßige Port-Nummer.
return-found-rows Weist mysql_info() an, gefundene Zeilen anstelle von aktualisierten Zeilen zurückzugeben, wenn UPDATE benutzt wird.
socket Vorgabemäßige Socket-Nummer.
user Vorgabemäßiger Benutzer.

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.

9.4.3.161 Rückgabewerte

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

9.4.3.162 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.163 mysql_ping()

int mysql_ping(MYSQL *mysql)

9.4.3.164 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.

9.4.3.165 Rückgabewerte

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

9.4.3.166 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.167 mysql_query()

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

9.4.3.168 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.85 mysql_field_count().

9.4.3.169 Rückgabewerte

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

9.4.3.170 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.171 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)

9.4.3.172 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:

9.4.3.173 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.

9.4.3.174 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.

9.4.3.175 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.176 mysql_real_escape_string()

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

9.4.3.177 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.

9.4.3.178 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.

9.4.3.179 Rückgabewerte

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

9.4.3.180 Fehler

Keine.

9.4.3.181 mysql_real_query()

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

9.4.3.182 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.85 mysql_field_count().

9.4.3.183 Rückgabewerte

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

9.4.3.184 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.185 mysql_reload()

int mysql_reload(MYSQL *mysql)

9.4.3.186 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.

9.4.3.187 Rückgabewerte

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

9.4.3.188 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.189 mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *ergebnis, MYSQL_ROW_OFFSET offset)

9.4.3.190 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().

9.4.3.191 Rückgabewerte

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

9.4.3.192 Fehler

Keine.

9.4.3.193 mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *ergebnis)

9.4.3.194 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.

9.4.3.195 Rückgabewerte

Der aktuelle Offset des Zeilencursors.

9.4.3.196 Fehler

Keine.

9.4.3.197 mysql_select_db()

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

9.4.3.198 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.

9.4.3.199 Rückgabewerte

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

9.4.3.200 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.201 mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

9.4.3.202 Beschreibung

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

9.4.3.203 Rückgabewerte

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

9.4.3.204 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.205 mysql_stat()

char *mysql_stat(MYSQL *mysql)

9.4.3.206 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.

9.4.3.207 Rückgabewerte

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

9.4.3.208 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.209 mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

9.4.3.210 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.85 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?.

9.4.3.211 Rückgabewerte

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

9.4.3.212 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.213 mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

9.4.3.214 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.

9.4.3.215 Rückgabewerte

Die Thread-Kennung der aktuellen Verbindung.

9.4.3.216 Fehler

Keine.

9.4.3.217 mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

9.4.3.218 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.

9.4.3.219 Rückgabewerte

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

9.4.3.220 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()

9.4.4.2 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.

9.4.4.3 Rückgabewerte

Keine.

9.4.4.4 mysql_thread_init()

9.4.4.5 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.

9.4.4.6 Rückgabewerte

Keine.

9.4.4.7 mysql_thread_end()

9.4.4.8 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.

9.4.4.9 Rückgabewerte

Keine.

9.4.4.10 mysql_thread_safe()

unsigned int mysql_thread_safe(void)

9.4.4.11 Description

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

9.4.4.12 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)

9.4.5.2 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.

9.4.5.3 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;
}

9.4.5.4 Rückgabewerte

Keine.

9.4.5.5 mysql_server_end()

9.4.5.6 Beschreibung

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

9.4.5.7 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:

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:

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:

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

Zwei APIs sind im MySQL-Contrib-Verzeichnis verfügbar.

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:

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.

Sie können auch die Python-Schnittstelle zu iODBC benutzen, um auf einen MySQL-Server zuzugreifen. mxODBC

9.8 MySQL-Tcl-APIs

Tcl bei binevolve. Das Contrib-Verzeichnis enthält eine Tcl-Schnittstelle, die auf msqltcl 1.50 basiert.

9.9 MySQL-Eiffel-Wrapper

Das MySQL-Contrib-Verzeichnis enthält einen Eiffel-Wrapper, der von Michael Ravits geschrieben wurde.


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