Skip navigation links
MySQL 5.1 Referenzhandbuch :: 24 APIs und Bibliotheken :: 24.2 MySQL-C-API :: 24.2.6 C-API Prepared Statements: Funktionsüberblick
24.2.7 C-API Prepared Statements: Funktionsbeschreibungen »
Section Navigation      [Toggle]

24.2.6. C-API Prepared Statements: Funktionsüberblick

Die Funktionen für vorbereitete Anweisungen werden hier zusammengefasst und im Weiteren genauer beschrieben. Siehe Abschnitt 24.2.7, „C-API Prepared Statements: Funktionsbeschreibungen“.

Funktion Beschreibung
mysql_stmt_affected_rows() Liefert die Anzahl der Änderungen, Löschungen und Einfügungen in Zeilen durch eine vorbereitete UPDATE-, DELETE- oder INSERT-Anweisung.
mysql_stmt_attr_get() Holt den Wert eines Attributs für eine vorbereitete Anweisung.
mysql_stmt_attr_set() Setzt ein Attribut für eine vorbereitete Anweisung.
mysql_stmt_bind_param() Verbindet Anwendungsdatenpuffer mit den Parametermarkern einer vorbereiteten SQL-Anweisung.
mysql_stmt_bind_result() Verbindet Anwendungsdatenpuffer mit den Spalten der Ergebnismenge.
mysql_stmt_close() Gibt den von einer vorbereiteten Anweisung benutzten Speicher frei.
mysql_stmt_data_seek() Sucht nach einer beliebigen Zeilennummer in der Ergebnismenge einer Anweisung.
mysql_stmt_errno() Liefert die Fehlernummer für die letzte Ausführung einer Anweisung.
mysql_stmt_error() Liefert die Fehlermeldung für die letzte Ausführung einer Anweisung.
mysql_stmt_execute() Führt die vorbereitete Anweisung aus.
mysql_stmt_fetch() Holt die nächste Datenzeile aus der Ergebnismenge und liefert Daten für alle gebundenen Spalten.
mysql_stmt_fetch_column() Holt Daten einer Spalte aus der aktuellen Zeile der Ergebnismenge.
mysql_stmt_field_count() Liefert die Anzahl der Ergebnisspalten für die letzte Anweisung.
mysql_stmt_free_result() Gibt die für den Anweisungs-Handle zugewiesenen Ressourcen frei.
mysql_stmt_init() Weist der MYSQL_STMT-Struktur Speicher zu und initialisiert sie.
mysql_stmt_insert_id() Liefert die für eine AUTO_INCREMENT-Spalte von einer vorbereiteten Anweisung generierte ID.
mysql_stmt_num_rows() Liefert die Gesamtzahl der Zeilen in der gepufferten Ergebnismenge der Anweisung.
mysql_stmt_param_count() Liefert die Anzahl der Parameter in einer vorbereiteten SQL-Anweisung.
mysql_stmt_param_metadata() Liefert Parametermetadaten in Form einer Ergebnismenge.
mysql_stmt_prepare() Bereitet einen SQL-String zur Ausführung vor.
mysql_stmt_reset() Setzt die Anweisungspuffer im Server zurück.
mysql_stmt_result_metadata() Liefert Metadaten zu einer vorbereiteten Anweisung in Form einer Ergebnismenge.
mysql_stmt_row_seek() Sucht einen Zeilen-Offset in der Ergebnismenge einer Anweisung und verwendet dazu den Rückgabewert von mysql_stmt_row_tell().
mysql_stmt_row_tell() Liefert die Zeilen-Cursor-Position der Anweisung.
mysql_stmt_send_long_data() Sendet lange Daten stückweise an den Server.
mysql_stmt_sqlstate() Liefert den SQLSTATE-Fehlercode für die letzte Anweisungsausführung.
mysql_stmt_store_result() Lädt die gesamte Ergebnismenge auf den Client herunter.

Rufen Sie zuerst mysql_stmt_init() auf, um einen Anweisungs-Handle zu erzeugen, dann mysql_stmt_prepare, um die Anweisung vorzubereiten, dann mysql_stmt_bind_param(), um die Parameterdaten zu liefern, und zum Schluss mysql_stmt_execute(), um die Anweisung auszuführen. Sie können den mysql_stmt_execute()-Aufruf wiederholen, indem Sie die Parameterwerte in den jeweiligen von mysql_stmt_bind_param() zur Verfügung gestellten Puffern ändern.

Ist die Anweisung ein SELECT oder eine andere Anweisung, die eine Ergebnismenge erstellt, liefert mysql_stmt_prepare() zu dieser Ergebnismenge auch Metadaten in Form einer von mysql_stmt_result_metadata() zurückgegebenen MYSQL_RES-Ergebnismenge.

Sie können die Ergebnispuffer mit mysql_stmt_bind_result() zur Verfügung stellen, sodass mysql_stmt_fetch() automatisch Daten an diese Puffer liefert. Dabei handelt es sich um einen zeilenweisen Datenabruf.

Sie können auch die Text- oder Binärdaten mit mysql_stmt_send_long_data() stückweise an den Server senden. Siehe Abschnitt 24.2.7.25, „mysql_stmt_send_long_data()“.

Wenn die Anweisungsausführung abgeschlossen ist, muss der Anweisungs-Handle mit mysql_stmt_close() geschlossen werden, damit alle seine Ressourcen freigegeben werden können.

Wenn Sie mit mysql_stmt_result_metadata() Metadaten zur Ergebnismenge einer SELECT-Anweisung beschafft haben, müssen Sie mit mysql_free_result() auch diese Metadaten freigeben.

Ausführungsschritte

Um eine Anweisung zur Nutzung in einer Anwendung vorzubereiten und auszuführen, müssen Sie Folgendes tun:

  1. Mit msyql_stmt_init() erzeugen Sie einen Handle für eine vorbereitete Anweisung. Um die Anweisung auf dem Server vorzubereiten, müssen Sie die Funktion mysql_stmt_prepare() aufrufen und ihr einen String mit der SQL-Anweisung übergeben.

  2. Wenn die Anweisung eine Ergebnismenge erstellt, müssen Sie die Metadaten dieser Ergebnismenge mit mysql_stmt_result_metadata() abholen. Die Metadaten liegen selbst ebenfalls in Form einer Ergebnismenge vor, allerdings einer anderen als der, die die Rückgabezeilen der Anfrage enthält. Die Metadatenergebnismenge gibt an, wie viele Spalten das Ergebnis enthält, und gibt Informationen über jede dieser Spalten.

  3. Die Parameterwerte setzen Sie mit mysql_stmt_bind_param(). Alle Parameter müssen gesetzt werden. Andernfalls gibt die Anweisungsausführung einen Fehler zurück oder liefert unerwartete Resultate.

  4. Mit einem Aufruf von mysql_stmt_execute() führen Sie die Anweisung aus.

  5. Wenn die Anweisung eine Ergebnismenge erstellt, binden Sie die Datenpuffer zum Abruf der Zeilenwerte mit mysql_stmt_bind_result().

  6. Laden Sie die Daten zeilenweise durch wiederholten Aufruf von mysql_stmt_fetch() in die Puffer herunter, bis keine weiteren Zeilen mehr vorliegen.

  7. Wiederholen Sie die Schritte 3 bis 6 so oft wie nötig, indem Sie die Parameterwerte ändern und die Anweisung erneut ausführen.

Bei einem Aufruf von mysql_stmt_prepare() tut das MySQL-Client/Server-Protokoll Folgendes:

  • Der Server parst die Anweisung und sendet den Okay-Status an den Client, indem er eine Anweisungs-ID zuweist. Außerdem sendet er, falls die Anweisung eine Ergebnismenge liefert, die Gesamtzahl der Parameter, eine Zeilenzahl und die Metadaten. Die Syntax und Semantik der Anweisung werden auf dem Server während dieses Aufrufs überprüft.

  • Der Client verwendet diese Anweisungs-ID für weitere Operationen, damit der Server die Anweisung in seinem Anweisungspool wiederfinden kann.

Bei einem Aufruf von mysql_stmt_execute() geht das MySQL-Client/Server-Protokoll folgendermaßen vor:

  • Der Client nutzt den Anweisungs-Handle und sendet die Parameterdaten an den Server.

  • Der Server findet die Anweisung anhand der vom Client übergebenen ID wieder, ersetzt die Parametermarker mit den frisch gelieferten Daten und führt die Anweisung aus. Wenn die Anweisung eine Ergebnismenge erstellt, sendet der Server die Daten an den Client zurück, ansonsten sendet er einen Okay-Status und die Gesamtzahl der geänderten, gelöschten oder eingefügten Zeilen.

Bei einem Aufruf von mysql_stmt_fetch() geht das MySQL-Client/Server-Protokoll folgendermaßen vor:

  • Der Client liest die Daten zeilenweise aus dem Paket ein und setzt sie in die Datenpuffer der Anwendung, indem er die notwendigen Typkonvertierungen vornimmt. Hat der Anwendungsdatenpuffer denselben Typ wie das vom Server zurückgegebene Feld, ist die Konvertierung einfach.

Wenn ein Fehler auftritt, können Sie den Anweisungsfehlercode, die Fehlermeldung und den SQLSTATE-Wert mit den Funktionen mysql_stmt_errno(), mysql_stmt_error() und mysql_stmt_sqlstate() erhalten.

Protokollierung vorbereiteter Anweisungen

Für vorbereitete Anweisungen, die mit den C-API-Funktionen mysql_stmt_prepare() und mysql_stmt_execute() ausgeführt werden, schreibt der Server Prepare- und Execute-Zeilen in das allgemeine Anfragenlog, damit Sie hinterher wissen, wann Anweisungen vorbereitet und ausgeführt wurden.

Angenommen, Sie bereiten eine Anweisung folgendermaßen vor und führen sie aus:

  1. Sie rufen mysql_stmt_prepare() auf, um den Anweisungs-String "SELECT ?" vorzubereiten.

  2. Sie rufen mysql_stmt_bind_param() auf, um den Wert 3 an den Parameter der vorbereiteten Anweisung zu binden.

  3. Sie rufen mysql_stmt_execute() auf, um die vorbereitete Anweisung auszuführen.

Aufgrund dieser Funktionsaufrufe schreibt der Server folgende Zeilen in das allgemeine Anfragenlog: 

Prepare  [1] SELECT ?
Execute  [1] SELECT 3

Jede Prepare- und Execute-Zeile im Log wird mit einem [N]-Anweisungsbezeichner markiert, damit Sie nachvollziehen können, welche vorbereitete Anweisung gerade protokolliert wird. N ist ein positiver Integer. Wenn mehrere vorbereitete Anweisungen zugleich für den Client aktiv sind, kann N größer als 1 sein. Jede Execute-Zeile zeigt eine vorbereitete Anweisung nach Einsetzung der Datenwerte in die ?-Parameter an.

Versionshinweise: Prepare-Zeilen werden vor MySQL 4.1.10 ohne [N] angezeigt. Execute-Zeilen werden vor MySQL 4.1.10 überhaupt nicht angezeigt.

Dies ist eine Übersetzung des MySQL-Referenzhandbuchs, das sich auf dev.mysql.com befindet. Das ursprüngliche Referenzhandbuch ist auf Englisch, und diese Übersetzung ist nicht notwendigerweise so aktuell wie die englische Ausgabe. Das vorliegende deutschsprachige Handbuch behandelt MySQL bis zur Version 5.1.