Parameter der Dokumentation in SQL  (MySQL )

Das in dieser Lektion vermittelte Verständnis von Parameterbeschreibungen aus der Dokumentation erschließt die Möglichkeit zum Nutzung einer Vielzahl vordefinierter Funktionen.

Typerwartungen

Der Aufrufausdruck »FLOOR( 2.7 )« besteht aus einem Rahmen »FLOOR( … )« und einem an Stelle der Lücke »…« eingesetztem Argumentausdruck »2.7«.

Für diese Lücke »…« darf jedoch im allgemeinen nicht irgendein beliebiger  Wertausdruck eingesetzt werden. Das folgende Programm zeigt, daß ein Zeichenfolgenausdruck beispielsweise zu einer Fehlermeldung führt (genauer gesagt: Zu einer Warnung, die aber das Wort “incorrect ”, also „inkorrekt“, enthält, und damit praktisch einen Fehler beschreibt).

Konsole

SELECT FLOOR( 'abc' );

+----------------+
| FLOOR( 'abc' ) |
+----------------+
|              0 |
+----------------+
1 row in set, 1 warning (0.00 sec)

SHOW WARNINGS;

+---------+------+-----------------------------------------+
| Level   | Code | Message                                 |
+---------+------+-----------------------------------------+
| Warning | 1292 | Truncated incorrect DOUBLE value: 'abc' |
+---------+------+-----------------------------------------+

Konsole (übersetzt und gekürzt)

+---------+------+-----------------------------------------+
| Stufe   | Wert | Nachricht                               |
+---------+------+-----------------------------------------+
| Warnung | 1292 | Unrichtiger DOUBLE-Wert: 'abc'          |
+---------+------+-----------------------------------------+

Die Fehlermeldung drückt aus, daß ein Ausdruck vom Typ »DOUBLE« erwartet wurde. Tatsächlich wurde aber eine Zeichenfolge (Typ: »VARCHAR ( 3 )«) übergeben.

Eine Zeichenfolge, wie »VARCHAR ( 3 )«, wird auch oft als ein “string ” bezeichnet.

Anzeigen versteckter Warnungen direkt nach einem Hinweis auf Warnungen, Semikolon am Ende nötig

SHOW WARNINGS;

WARNINGS Warnungen nach jeder  Anweisung anzeigen

NOWARNING (kleines W) Warnungen nicht  nach jeder Anweisung anzeigen

Beispiel einer Dokumentation

Entfernt man aus einem Aufrufausdruck den Argumentausdruck, so enthält man einen Rahmen mit Lücke, wie beispielsweise den Rahmen »FLOOR( … )« mit einer Lücke »…« in den runden Klammern. Solch eine Lücke an der Stelle eines entfernten Argumentausdrucks nennt man einen Para̲meter  (Substantiv mit Genus Maskulinum und Betonung auf der zweiten Silbe, die Linie unter dem zweiten „a“ kennzeichnet die Betonung). Ein Para̲meter drückt die Erwartung  eines Argumentes aus. Der Para̲meter kennzeichnet die Stelle, an welcher ein Argumentausdruck von einem bestimmten Typ erwartet wird. Ein Para̲meter ist wie eine Lücke, die dann vom Argument gefüllt werden kann.

In der Dokumentation einer Funktion findet man eine nähere Beschreibung des Para̲meters.

Dokumentation einer Funktion mit einem Para̲meter (überarbeitet und übersetzt)

help floor

Name:         FLOOR
Synopse:      FLOOR( X )
Beschreibung: Ergibt die groesste ganze Zahl bis X (einschliesslich).

In der obenstehenden Dokumentation wird durch »X« ein Para̲meter mit dem Namen »X« dokumentiert. Die Funktion kann also mit einem Argument aufgerufen werden. In dem Text der Beschreibung der Funktion kann dann mit »X« auf den Argumentwert Bezug genommen werden (oben beispielsweise mit „bis X“).

Um zu beschreiben, daß bestimmte Lücken nur Ausdrücke bestimmter Typen zulassen, ordnet man Para̲metern einen Typ  zu, den man auch als Para̲metertyp  bezeichnen kann. Zunächst akzeptiert ein Para̲meter dann nur Argumente des Para̲metertyps, jedoch werden oft auch Argumente anderer Typen toleriert und dann uminterpretiert. Ein Para̲meter vom Typ »STRING« (Zeichenfolge) akzeptiert also zunächst ein Argument vom Typ »VARCHAR«, nicht jedoch vom Typ »INT« oder »DOUBLE«. Umgekehrt akzeptiert ein Para̲meter vom Typ »INT« oder »DOUBLE« zunächst kein Argument vom Typ »STRING«. Ein DOUBLE-Para̲meter einer Funktion besagt unter anderem, daß jene Funktion noch eines DOUBLE-Wertes bedarf, um ihre Aufgabe zu erfüllen.

In der Dokumentation von MySQL wird der Typ eines Parameters leider oft nicht direkt angegeben. In vielen Fällen gibt der Parametername in der Dokumentation aber einen Hinweis auf den Parametertyp. In anderen Fällen ist man darauf angewiesen, den Parametertyp aus dem Zusammenhang zu erraten.

Oft haben Parameter mit den folgenden Namen den in der folgenden Tabelle angegebenen Typ. Allerdings könnte es auch Abweichungen davon geben, da diese Zuordnung nicht offiziell festgelegt ist.

Typen häufiger Parameternamen der Dokumentation

Name            Typ
X               DOUBLE
Y               DOUBLE
N               INT (manchmal auch DOUBLE)
D               INT, Anzahl der Nachkommastellen
POS             INT
LEN             INT
STR             VARCHAR (wie andere Namen mit "STR")
EXPR            kann alles moeglich sein

Es folgt noch eine Liste einiger weiterer Parameternamen, die oft den dahinter angegebenen Typ haben. Es sind aber Abweichungen möglich!

Typen einiger weiterer Parameternamen der Dokumentation

B          INT        key_str         VARCHAR    pos             INT
bits       INT        len             INT        S               VARCHAR
count      INT        log_name        VARCHAR    salt            VARCHAR
crypt_str  VARCHAR    log_pos         INT        second          INT
D          INT        M (=Feldbreite) INT        seconds         INT
dayofyear  INT        minute          INT        timeout         INT
days       INT        mode            INT        to_base         INT
duration   INT        name            VARCHAR    to_tz           VARCHAR
exprN      INT        new_xml         VARCHAR    unix_timestamp  INT
file_name  VARCHAR    newstr          VARCHAR    X               DOUBLE
format     VARCHAR    number_of_bits  INT        xml_frag        VARCHAR
from_base  INT        P               INT        xml_target      VARCHAR
from_str   VARCHAR    P1              INT        xpath_expr      VARCHAR
from_tz    VARCHAR    P2              INT        Y               DOUBLE
hour       INT        padstr          VARCHAR    year            INT
interval   INT        pass_str        VARCHAR    key_num         INT

Auch, wenn diese Listen einen Anhaltspunkt geben, sollte bei ihrer Verwendung immer noch einmal geprüft werden, ob der angegebene Typ bei einer bestimmten Funktion auch plausibel ist, in manchen Fällen gehören zu einem Parameternamen noch mehr Typen als in den Listen angegeben. Falls der Parametername in dieser Liste nicht zu finden ist, dann muß der Paramtertyp erraten werden oder eine der untenstehenden Techniken verwendet werden, um den Typ zu ermitteln oder den in der Liste angegebenen Typ abzusichern.

Falls die Klammern hinter dem Funktionsnamen in der Dokumentation leer sind, dann hat die Funktion keinen Parameter und ist dementsprechend auch mit leeren Klammern aufzurufen.

Para̲meter und Argumente

Para̲meterbeschreibungen  und Argumentausdrücke  werden manchmal miteinander verwechselt : Para̲meterbeschreibungen  finden sich in der Dokumentation  als Beschreibung einer Lücke, sie drücken das Fehlen  eines bestimmten Wertes aus, die Erwartung  eines Ausdrucks beim Aufruf im Quelltext. Argumentausdrücke  finden sich im Quelltext innerhalb mancher Ausdrücke und geben den zur Ermittlung des Para̲meterwerts zu nutzenden Ausdruck an, beispielsweise als ein Numerale oder als eine Summe. Da Para̲meterbeschreibungen das Fehlen  eines Wertes ausdrücken und Argumentausdrücken einen Wert  ausdrücken, sind Argumentausdrücke  gewissermaßen das Gegenstück zu Para̲meterbeschreibungen.

Ermitteln des Parametertyps im Klienten

Die Dokumentation gibt den Parametertyp nicht immer ausdrücklich an. Manchmal kann dieser auch im Klienten ermittelt werden.

Funktionen haben selten DECIMAL-Parameter. Daher kann man zunächst einmal davon ausgehen, daß ein Parameter nicht »DECIMAL« als Typ hat (obwohl das auch manchmal vorkommt).

In den meisten Fällen bleiben dann noch die drei Möglichkeiten »STRING«, »DOUBLE« und »INTEGER« übrig. Ruft man eine Funktion nun mit der Zeichenfolge »'a'« auf und erhält keine Warnung, so hat diese wahrscheinlich einen STRING-Parameter (der am besten zu einem VARCHAR-Argument paßt).

Konsole

SELECT CONCAT( 'a' );

+---------------+
| CONCAT( 'a' ) |
+---------------+
| a             |
+---------------+

Erhält man die Warnung »Truncated incorrect DOUBLE value«, so hat die Funktion einen DOUBLE-Parameter (der am besten zu einem DOUBLE-Argument paßt).

Konsole

SELECT FLOOR( 'A' ); SHOW WARNINGS;

+--------------+
| FLOOR( 'A' ) |
+--------------+
|            0 |
+--------------+
+---------+------+---------------------------------------+
| Level   | Code | Message                               |
+---------+------+---------------------------------------+
| Warning | 1292 | Truncated incorrect DOUBLE value: 'A' |
+---------+------+---------------------------------------+

Erhält man die Warnung »Truncated incorrect INTEGER value«, so hat die Funktion einen INT-Parameter (der am besten zu einem INT-Argument paßt, der Datentyp »INT« wird auch »INTEGER« genannt).

Konsole

SELECT RAND( 'A' ); SHOW WARNINGS;
+---------------------+
| RAND( 'A' )         |
+---------------------+
| 0.15522042769493574 |
+---------------------+
+---------+------+----------------------------------------+
| Level   | Code | Message                                |
+---------+------+----------------------------------------+
| Warning | 1292 | Truncated incorrect INTEGER value: 'A' |
+---------+------+----------------------------------------+

Allerdings ist diese Vorgehensweise nicht immer ganz zuverlässig, falls es mehrere mögliche Parametertypen bei einer Funktion gibt.

Ermitteln des Parametertyps im Quellcode *

Falls ein Leser C++  lesen kann, dann kann er auch den Quellcode zu einer Funktion im Web suchen, indem er dem Namen der Funktion »MySQL cc Item_func_« voranstellt (weitere mögliche Suchwörter: »mysql cc -"control center" "affiliates" "sql_priv.h"«). Den Quellcode der Funktion »EXP« findet man beispielsweise, wenn man nach »MySQL cc Item_func_EXP« sucht.

Dort kann man dann folgendes lesen:

Quellcode von »EXP«

double Item_func_exp::val_real()
{ double value= args[0]->val_real();

Hier wird mit »->val_real()« der Parameter (er heißt im Quelltext »args[0]«) als DOUBLE-Parameter verwendet, was man an dem »real« erkennen kann, das eine Art von Synonym für »DOUBLE« ist.

Auf diese Weise kann man zu jeder Funktion genau ablesen, welchen Typ der Parameter hat.

Der folgende Auszug aus der Definition der Funktion »FORMAT« zeigt, daß ihr Parameter »DECIMAL«, »INT« oder »DOUBLE« als Typ hat, je nachdem was am besten zum Typ des verwendeten Arguments paßt. Solche Feinheiten sind leider nicht immer dokumentiert und manchmal nur durch Lesen des Quelltextes zu ermitteln.

Quellcode von »FORMAT«

String *Item_func_format::val_str_ascii(String *str)
{ ... dec= (int) args[1]->val_int();
  if (args[0]->result_type() == DECIMAL_RESULT ||
  args[0]->result_type() == INT_RESULT ) ...
  else { double nr= args[0]->val_real(); ...