Global | Germany | UK | USA

Your privat CyberGadget - Die besten Resourcen für Web-Designer, Web-Master und Web-Developer!

HOME

SUCHE

NEWS

Quick Search

Partner & Freunde

CYGAD's Network

Affiliates

News einsenden

URL / Entry hinzufügen

Manuals & Dokumentationen: MySQL

Original Referenzhandbuch für MySQL Datenbanksysteme

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

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

9.2 MySQL-Perl-API

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

9.2.1 `DBI` mit `DBD::mysql`

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

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

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

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

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

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

9.2.2 Die `DBI`-Schnittstelle

Portable DBI-Methoden

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

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

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

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

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

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

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

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

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

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

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

Verwenden Sie die IP-Adresse des Servers.
Fügen Sie der Datei `\windows\lmhosts' folgende Informationen an:
```
ip hostname
```
Beispiel:
```
194.216.84.21 mein_hostname
```
Konfigurieren Sie DNS:

Beispiel: Wie Sie das ODBC setup ausfüllen:

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

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

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

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

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

9.3.3 Verbindungsparameter für MyODBC

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

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:

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

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

9.3.5 Programme, die bekanntermaßen mit MyODBC zusammenarbeiten

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

Programm

Anmerkung

Access

Um Access zum Laufen zu bringen:

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

ADO

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

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

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

myrs.Close
myconn.Close

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

Active server pages (ASP)

Sie sollten den Option-Flag Return matching rows benutzen.

BDE-Applikationen

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

Borland Builder 4

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

ColdFusion (unter Unix)

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

DataJunction

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

Excel

Funktioniert. Einige Tipps:

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

Word

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

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

odbcadmin

Test-Programm für ODBC.

Delphi

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

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

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

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

C++-Builder

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

Vision

Sie sollten den Option-Flag Return matching rows benutzen.

Visual Basic

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

VisualInterDev

Wenn Sie den Fehler

[Microsoft][ODBC Driver Manager] Driver does not
support this parameter

erhalten, kann es daran liegen, dass Sie ein BIGINT in Ihrem Ergebnis haben. Versuchen Sie, die

Change
BIGINT columns to INT

-Option im MySQL-Verbindungsbildschirm zu setzen.

Visual Objects

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

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

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

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

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

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

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

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

SELECT * FROM tabelle WHERE auto IS NULL;

9.3.7 Probleme mit MyODBC berichten

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

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

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

Beschreibung

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

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

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

Rückgabewerte

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

Fehler

Dieselben, die Sie von mysql_real_connect() erhalten.

CR_COMMANDS_OUT_OF_SYNC: Befehle wurde in nicht korrekter Reihenfolge ausgeführt.
CR_SERVER_GONE_ERROR: Der MySQL-Server ist weg.
CR_SERVER_LOST: Die Verbindung zum Server ging während der Anfrage verloren.
CR_UNKNOWN_ERROR: Ein unbekannter Fehler ist aufgetreten.
ER_UNKNOWN_COM_ERROR: Der MySQL-Server hat diesen Befehl nicht implementiert (wahrscheinlich ein alter Server).
ER_ACCESS_DENIED_ERROR: Benutzername oder Passwort sind falsch.
ER_BAD_DB_ERROR: Die Datenbank existiert nicht.
ER_DBACCESS_DENIED_ERROR: Der Benutzer hat keine Zugriffsrechte auf die Datenbank.
ER_WRONG_DB_NAME: Der Datenbankname war zu lang.

Beispiel

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

9.4.3.5 `mysql_character_set_name()`

const char *mysql_character_set_name(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

Der vorgabemäßige Zeichensatz

Fehler

Keine.

9.4.3.6 `mysql_create_db()`

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

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC: Befehle wurden in nicht korrekter Reihenfolge ausgeführt.
CR_SERVER_GONE_ERROR: Der MySQL-Server ist weg.
CR_SERVER_LOST: Die Verbindung zum Server ging während der Anfrage verloren.
CR_UNKNOWN_ERROR: Ein unbekannter Fehler trat auf.

Beispiel

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

9.4.3.7 `mysql_data_seek()`

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

Beschreibung

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

9.4.3.9 `mysql_drop_db()`

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

Beschreibung

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

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC: Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.
CR_SERVER_GONE_ERROR: Der MySQL-Server ist weg.
CR_SERVER_LOST: Die Verbindung zum Server ging während der Anfrage verloren.
CR_UNKNOWN_ERROR: Ein unbekannter Fehler trat auf.

Beispiel

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

9.4.3.10 `mysql_dump_debug_info()`

int mysql_dump_debug_info(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

CR_COMMANDS_OUT_OF_SYNC: Befehle wurden nicht in der korrekten Reihenfolge ausgeführt.
CR_SERVER_GONE_ERROR: Der MySQL-Server ist weg.
CR_SERVER_LOST: Die Verbindung zum Server ging während der Anfrage verloren.
CR_UNKNOWN_ERROR: Ein unbekannter Fehler trat auf.

9.4.3.11 `mysql_eof()`

my_bool mysql_eof(MYSQL_RES *result)

Beschreibung

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

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

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

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

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

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

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

9.4.3.12 `mysql_errno()`

unsigned int mysql_errno(MYSQL *mysql)

Beschreibung

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.13 `mysql_error()`

char *mysql_error(MYSQL *mysql)

Beschreibung

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

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

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

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

Rückgabewerte

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

Fehler

Keine.

9.4.3.14 `mysql_escape_string()`

Statt dessen sollten Sie mysql_real_escape_string() benutzen!

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

9.4.3.15 `mysql_fetch_field()`

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

MYSQL_FIELD *field;

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

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

Rückgabewerte

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

Fehler

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

Beispiel

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

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

9.4.3.19 `mysql_fetch_row()`

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

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

Beispiel

MYSQL_ROW zeile;
unsigned int anzahl_felder;
unsigned int i;

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

9.4.3.20 `mysql_field_count()`

unsigned int mysql_field_count(MYSQL *mysql)

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

Beschreibung

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

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

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

Rückgabewerte

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

Fehler

Keine.

Beispiel

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

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

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

9.4.3.21 `mysql_field_seek()`

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Beschreibung