Skip navigation links
26.3.4.2 UDF-Aufrufsequenzen für Aggregatfunktionen »
Section Navigation      [Toggle]

26.3.4.1. UDF-Aufrufsequenzen

Dieser Abschnitt beschreibt die verschiedenen Funktionen, die Sie definieren müssen, um eine einfache UDF anzulegen. Abschnitt 26.3.4, „Hinzufügen einer neuen benutzerdefinierten Funktion“, beschreibt die Reihenfolge, in der MySQL diese Funktionen aufruft.

Die xxx()-Hauptfunktion sollte so deklariert werden, wie es in diesem Abschnitt gezeigt wird. Beachten Sie, dass der Rückgabetyp und die Parameter unterschiedlich sind, je nachdem, ob Sie die SQL-Funktion XXX() in der CREATE FUNCTION-Anweisung mit dem Rückgabetyp STRING, INTEGER oder REAL deklarieren:

Für STRING-Funktionen gilt: 

char *xxx(UDF_INIT *initid, UDF_ARGS *args,
          char *result, unsigned long *length,
          char *is_null, char *error);

Für INTEGER-Funktionen gilt: 

long long xxx(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

Für REAL-Funktionen gilt: 

double xxx(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

Die Initialisierungs- und Deinitialisierungsfunktionen werden wie folgt deklariert: 

my_bool xxx_init(UDF_INIT *initid, UDF_ARGS *args, char *message);

void xxx_deinit(UDF_INIT *initid);

Der Parameter initid wird an alle drei Funktionen übergeben. Er verweist auf eine UDF_INIT-Struktur, die Informationen zwischen Funktionen übergibt. Die Bestandteile der UDF_INIT-Struktur werden im Folgenden aufgeführt. Die Initialisierungsfunktion sollte alle diejenigen Bestandteile ausfüllen, die geändert werden sollen. (Um einen Standardwert beizubehalten, ändern Sie einfach nichts.)

  • my_bool maybe_null

    xxx_init() sollte maybe_null auf 1 einstellen, wenn xxx() den Wert NULL zurückliefern kann. Der Standardwert ist 1, wenn irgendwelche Argumente als maybe_null deklariert sind.

  • unsigned int decimals

    Die Anzahl der Dezimalstellen rechts vom Dezimalpunkt (also salopp ausgedrückt: die Nachkommastellen). Der Standardwert ist die Höchtzahl der Dezimalstellen in den an die Hauptfunktion übergebenen Argumenten. (Wenn beispielsweise 1.34, 1.345 und 1.3 an die Funktion übergeben werden, wäre der Standardwert 3, da 1.345 3 Nachkommastellen hat.

  • unsigned int max_length

    Die Maximallänge des Ergebnisses. Der Standardwert max_length richtet sich nach dem Ergebnistyp der Funktion. Bei String-Funktionen ist er die Länge des längsten Arguments; bei Integer-Funktionen ist er 21 Ziffern. Bei Real-Funktionen ist der Standardwert 13 plus die Anzahl der durch initid->decimals vorgegebenen Dezimalstellen. (Bei numerischen Funktionen sind in der Länge auch Vorzeichen und Dezimalpunkt inbegriffen.)

    Wenn Sie einen Blob-Wert zurückliefern möchten, können Sie max_length auf 65 Kbyte oder 16 Mbyte einstellen. Der Speicherplatz wird zwar nicht reserviert, aber anhand der Länge entscheidet das System, welcher Datentyp für eine eventuell erforderliche temporäre Speicherung der Daten verwendet wird.

  • char *ptr

    Ein Zeiger, den die Funktion für ihre eigenen Zwecke verwenden kann. So können sich die Funktionen beispielsweise mit initid->ptr gegenseitig mitteilen, wie viel Speicher sie reservieren müssen. xxx_init() sollte den Speicher reservieren und diesem Zeiger zuweisen. 

    initid->ptr = allocated_memory;

    In xxx() und xxx_deinit() verweisen Sie auf initid->ptr, um Speicher zu benutzen oder freizugeben.

  • my_bool const_item

    xxx_init() sollte const_item auf 1 setzen, wenn xxx() immer denselben Wert zurückgibt, und auf 0, wenn das nicht der Fall ist.

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.