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

24.2.5. C-API: Prepared Statement-Datentypen

Vorbereitete Anweisungen nutzen hauptsächlich die Datenstrukturen MYSQL_STMT und MYSQL_BIND. Eine dritte Datenstruktur, nämlich MYSQL_TIME, wird zur Übertragung von Temporaldaten verwendet.

  • MYSQL_STMT

    Diese Struktur stellt eine vorbereitete Anweisung dar. Eine Anweisung wird mit der Funktion mysql_stmt_init() angelegt, die einen Anweisungs-Handle liefert (d. h. einen Zeiger auf MYSQL_STMT). Der Handle wird für alle folgenden mit der Anweisung verbundenen Funktionen benutzt, bis Sie ihn mit mysql_stmt_close() wieder schließen.

    Die MYSQL_STMT-Struktur hat keine Bestandteile für Anwendungen. Legen Sie bitte auch keine Kopie einer MYSQL_STMT-Struktur an, da nicht garantiert werden kann, dass eine solche Kopie benutzbar sein wird.

    Mehrere Anweisungs-Handles können mit einer einzigen Verbindung verknüpft werden. Wie viele Handles möglich sind, hängt von den Systemressourcen ab.

  • MYSQL_BIND

    Diese Struktur wird sowohl für die Eingabe einer Anweisung (der Datenwerte, die an den Server gesandt werden) als auch für ihre Ausgabe verwendet (die Ergebnisse, die vom Server zurückkommen). Für die Eingabe wird sie mit mysql_stmt_bind_param() benutzt, um die Parameterwerte an die Puffer zu binden, die mysql_stmt_execute() verwenden. Für die Ausgabe wird sie mit mysql_stmt_bind_result() benutzt, um die Ergebnismengenpuffer zu binden, die zum Abholen der Zeilen mit mysql_stmt_fetch() verwendet werden.

    Die MYSQL_BIND-Struktur enthält folgende Bestandteile zur Nutzung durch Anwendungsprogramme. Jeder Bestandteil wird sowohl für die Ein- als auch für die Ausgabe verwendet, allerdings manchmal zu unterschiedlichen Zwecken, je nachdem, in welche Richtung die Daten übertragen werden.

    • enum enum_field_types buffer_type

      Der Puffertyp. Die zulässigen buffer_type-Werte werden weiter unten in diesem Abschnitt aufgeführt. Für die Eingabe zeigt buffer_type an, welchen Werttyp Sie mit einem Anweisungsparameter verbinden. Für die Ausgabe zeigt er an, welchen Werttyp Sie in einem Ergebnispuffer erwarten.

    • void *buffer

      Für die Eingabe ist dies ein Zeiger auf den Puffer, in welchem die Parameterwerte einer Anweisung gespeichert werden. Für die Ausgabe ist es ein Zeiger auf den Puffer, in welchen die Spaltenwerte einer Ergebnismenge zurückgeliefert werden. Für numerische Datentypen sollte buffer auf eine Variable des korrekten C-Typs verweisen. (Wenn Sie die Variable mit einer Spalte verbinden, die das UNSIGNED-Attribut hat, sollte sie ein unsigned-C-Typ sein. Ob die Variable ein Vorzeichen hat oder nicht, geben Sie mithilfe des weiter unten beschriebenen Strukturbestandteils is_unsigned an.) Für Datums- und Uhrzeittypen sollte buffer auf eine MYSQL_TIME-Struktur verweisen. Für Zeichen- und Binär-String-Typen sollte buffer auf einen Zeichenpuffer verweisen.

    • unsigned long buffer_length

      Die tatsächliche Größe von *buffer in Bytes. Dies zeigt an, wie viele Daten maximal in dem Puffer gespeichert werden können. Für Zeichen und binäre C-Daten ist der buffer_length-Wert die Länge von *buffer, wenn er mit mysql_stmt_bind_param() gebraucht wird, beziehungsweise die Höchstzahl der Datenbytes, die in den Puffer zu laden sind, wenn er mit mysql_stmt_bind_result() gebraucht wird.

    • unsigned long *length

      Ein Zeiger auf eine unsigned long-Variable, die angibt, wie viele Bytes tatsächlich in *buffer gespeichert sind. length wird für Zeichen- oder Binärdaten in C verwendet. Zum Binden der Eingabeparameterdaten verweist length auf eine unsigned long-Variable, welche die Länge des in *buffer gespeicherten Parameterwerts angibt. Diese wird von mysql_stmt_execute() benutzt. Zum Binden der Ausgabewerte speichert mysql_stmt_fetch() die Länge des Rückgabespaltenwerts in der Variablen, auf die length verweist.

      length wird bei numerischen und temporalen Datentypen ignoriert, weil die Länge des Datenwerts anhand des Werts von buffer_type ermittelt wird.

    • my_bool *is_null

      Dies verweist auf eine my_bool-Variable, die TRUE ist, wenn ein Wert NULL ist, und FALSE, wenn er nicht NULL ist. Für die Eingabe setzen Sie *is_null auf TRUE, wenn Sie mitteilen möchten, dass Sie einen NULL-Wert als Anweisungsparameter übergeben. Für die Ausgabe wird dieser Wert nach dem Abruf einer Zeile der Ergebnismenge immer dann auf TRUE gesetzt, wenn der Spaltenwert, den die Anweisung zurückliefert, NULL ist.

      is_null ist ein Zeiger auf einen booleschen Wert anstatt auf einen booleschen Skalar. Daher kann er auf folgende Weise eingesetzt werden:

      • Wenn Ihre Datenwerte immer NULL sind, verwenden Sie MYSQL_TYPE_NULL, um die Spalte zu binden.

      • Wenn Ihre Datenwerte immer NOT NULL sind, stellen Sie ein: is_null = (my_bool*) 0.

      • In allen anderen Fällen sollten Sie is_null auf die Adresse einer my_bool-Variablen einstellen und deren Wert zwischen den Ausführungen jeweils so einstellen, dass sie anzeigt, ob Datenwerte NULL oder NOT NULL sind.

    • my_bool is_unsigned

      Dies wird für Integer-Typen benutzt (die den Typcodes MYSQL_TYPE_TINY, MYSQL_TYPE_SHORT, MYSQL_TYPE_LONG und MYSQL_TYPE_LONGLONG entsprechen.) is_unsigned sollte für vorzeichenlose Typen auf TRUE und für vorzeichenbehaftete auf FALSE gesetzt werden.

    • my_bool error

      Für die Ausgabe wird dieser Strukturbestandteil zur Meldung von Fehlern wegen abgeschnittener Datenwerte eingesetzt. Sie müssen diese Meldungen aktivieren, indem Sie mysql_options() mit der Option MYSQL_REPORT_DATA_TRUNCATION aufrufen. Wenn dies aktiviert ist, liefert mysql_stmt_fetch() die MYSQL_DATA_TRUNCATED-Meldungen und error ist in den MYSQL_BIND-Strukturen für Parameter, deren Datenwerte abgeschnitten wurden, TRUE. Beim Abschneiden geht ein Vorzeichen oder eine signifikante Ziffer verloren oder ein String hat nicht in eine Spalte gepasst.

    Um eine MYSQL_BIND-Struktur zu verwenden, müssen Sie zur Initialisierung ihren Inhalt auf null setzen und dann die soeben beschriebenen Bestandteile in geeigneter Weise einstellen. Wenn Sie beispielsweise ein Array von drei MYSQL_BIND-Strukturen deklarieren und initialisieren möchten, verfahren Sie folgendermaßen: 

    MYSQL_BIND    bind[3];
memset(bind, 0, sizeof(bind));

  • MYSQL_TIME

    Diese Struktur sendet und empfängt Daten vom Typ DATE, TIME, DATETIME und TIMESTAMP direkt an den bzw. von dem Server. Dies tut sie, indem der buffer_type-Teil einer MYSQL_BIND-Struktur auf einen der temporalen Datentypen und der buffer auf eine MYSQL_TIME-Struktur eingestellt wird.

    Die MYSQL_TIME-Struktur enthält folgende Bestandteile:

    • unsigned int year

      Das Jahr.

    • unsigned int month

      Der Monat des Jahres.

    • unsigned int day

      Der Tag des Monats.

    • unsigned int hour

      Die Stunde des Tages.

    • unsigned int minute

      Die Minute der Stunde.

    • unsigned int second

      Die Sekunde der Minute.

    • my_bool neg

      Ein boolesches Flag, das angibt, ob der Zeitwert negativ ist.

    • unsigned long second_part

      Ein Sekundenbruchteil. Dieser Teil wird zurzeit nicht benutzt.

    Es werden nur diejenigen Teile einer MYSQL_TIME-Struktur benutzt, die auf einen gegebenen Temporalwerttyp anwendbar sind: Die Elemente year, month und day werden für DATE-, DATETIME- und TIMESTAMP-Werte gebraucht und die Elemente hour, minute und second für TIME-, DATETIME- und TIMESTAMP-Werte. Siehe Abschnitt 24.2.10, „C-API: Behandlung von Datums- und Zeitwerten“.

Die folgende Tabelle zeigt die zulässigen Werte an, die im buffer_type-Teil von MYSQL_BIND-Strukturen angegeben werden können. Sie dokumentiert auch, welche SQL-Typen am ehesten den buffer_type-Werten entsprechen, sowie den entsprechenden C-Typ für numerische und temporale Typen.

buffer_type Wert SQL-Typ C-Typ
MYSQL_TYPE_BIT BIT
MYSQL_TYPE_TINY TINYINT char
MYSQL_TYPE_SHORT SMALLINT short int
MYSQL_TYPE_LONG INT int
MYSQL_TYPE_LONGLONG BIGINT long long int
MYSQL_TYPE_FLOAT FLOAT float
MYSQL_TYPE_DOUBLE DOUBLE double
MYSQL_TYPE_TIME TIME MYSQL_TIME
MYSQL_TYPE_DATE DATE MYSQL_TIME
MYSQL_TYPE_DATETIME DATETIME MYSQL_TIME
MYSQL_TYPE_TIMESTAMP TIMESTAMP MYSQL_TIME
MYSQL_TYPE_STRING CHAR  
MYSQL_TYPE_VAR_STRING VARCHAR  
MYSQL_TYPE_TINY_BLOB TINYBLOB/TINYTEXT  
MYSQL_TYPE_BLOB BLOB/TEXT  
MYSQL_TYPE_MEDIUM_BLOB MEDIUMBLOB/MEDIUMTEXT  
MYSQL_TYPE_LONG_BLOB LONGBLOB/LONGTEXT  

Eine implizite Typumwandlung ist in beiden Richtungen möglich.

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.