Skip navigation links
26.3.4.3 Verarbeitung von Argumenten »
Section Navigation      [Toggle]

26.3.4.2. UDF-Aufrufsequenzen für Aggregatfunktionen

In diesem Abschnitt erfahren Sie, welche Funktionen Sie definieren müssen, um eine Aggregatfunktion als UDF anzulegen. Abschnitt 26.3.4, „Hinzufügen einer neuen benutzerdefinierten Funktion“, beschreibt die Reihenfolge, in der MySQL diese Funktionen aufruft.

  • xxx_reset()

    Diese Funktion wird aufgerufen, wenn MySQL die erste Zeile einer neuen Gruppe findet. Sie sollte eventuell vorhandene interne Summenvariablen zurücksetzen und dann das gegebene UDF_ARGS-Argument als ersten Wert des neuen internen Summenwerts für diese Gruppe verwenden. xxx_reset() wird folgendermaßen deklariert: 

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

    xxx_reset() wird in MySQL 5.1 weder benötigt noch benutzt. Die UDF-Schnittstelle verwendet stattdessen xxx_clear(). Sie können jedoch xxx_reset() zusätzlich zu xxx_clear() definieren, wenn Ihre UDF auch mit älteren Serverversionen laufen soll. (Wenn Sie beide Funktionen einbeziehen möchten, können Sie xxx_reset() intern oft implementieren, indem Sie zunächst xxx_clear() alle Variablen zurücksetzen lassen und dann xxx_add() aufrufen, um das Argument UDF_ARGS als ersten Wert der Gruppe hinzuzufügen.)

  • xxx_clear()

    Diese Funktion wird aufgerufen, wenn MySQL die Summenergebnisse zurücksetzen muss. Sie wird für jede neue Gruppe ganz am Anfang aufgerufen, kann aber auch verwendet werden, um die Werte für eine Anfrage zurückzusetzen, wenn keine übereinstimmenden Zeilen gefunden wurden. xxx_clear() wird folgendermaßen deklariert: 

    char *xxx_clear(UDF_INIT *initid, char *is_null, char *error);

    is_null wird auf CHAR(0) eingestellt, bevor xxx_clear() aufgerufen wird.

    Wenn etwas schief gegangen ist, können Sie einen Wert in der Variablen speichern, auf die das Argument error verweist. error zeigt auf eine Singlebyte-Variable, nicht auf einen String-Puffer.

    xxx_clear() ist für MySQL 5.1 obligatorisch.

  • xxx_add()

    Diese Funktion wird für alle Zeilen außer der ersten aufgerufen, die zu derselben Gruppe gehören. Mit ihr addieren Sie den Wert des Arguments UDF_ARGS zu Ihrer internen Summenvariablen. 

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

Die xxx()-Funktion für eine Aggregat-UDF sollte genauso definiert werden wie die für eine einfache UDF. Siehe hierzu Abschnitt 26.3.4.1, „UDF-Aufrufsequenzen“.

Für eine Aggregat-UDF ruft MySQL die Funktion xxx() auf, nachdem alle Zeilen der Gruppe abgearbeitet sind. Im Normalfall greifen Sie hier niemals auf ihr UDF_ARGS-Argument zu, sondern geben einen Wert zurück, der auf Ihren internen Summenvariablen beruht.

Rückgabewerte sollten in xxx() genau wie bei einer UDF behandelt werden, die keine Aggregatfunktion ist. Siehe Abschnitt 26.3.4.4, „Rückgabewerte und Fehlerbehandlung“.

Die Funktionen xxx_reset() und xxx_add() gehen mit ihrem UDF_ARGS-Argument genauso um wie Funktionen für Nicht-Aggregat-UDFs. Siehe Abschnitt 26.3.4.3, „Verarbeitung von Argumenten“.

Die Zeigerargumente für is_null und error sind dieselben wie bei allen Aufrufen von xxx_reset(), xxx_clear(), xxx_add() und xxx(). Das können Sie nutzen, um sich zu merken, dass ein Fehler ausgelöst wurde oder ob die xxx()-Funktion NULL zurückgeben sollte. Bitte speichern Sie keinen String in *error! error verweist auf eine Single-Byte-Variable, nicht auf einen String-Puffer.

*is_null wird für jede Gruppe (vor dem Aufruf von xxx_clear()) zurückgesetzt, *error nie.

Sind *is_null oder *error gesetzt, wenn xxx() zurückkehrt, liefert MySQL NULL als Ergebnis der Gruppenfunktion zurück.

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.