24.3.2.2 集約関数のための UDF の呼び出しシーケンス

このセクションでは集約 UDF を作成するときに定義する必要があるさまざまな関数について説明します。セクション24.3.2「新しいユーザー定義関数の追加」には、MySQL がこれらの関数を呼び出す順序が記載されています。

• xxx_reset()

  この関数は、MySQL が新しいグループ内で最初の行を見つけたときに呼び出されます。これはすべての内部サマリー変数をリセットし、指定された UDF_ARGS 引数をグループの内部サマリー値の最初の値として使用します。xxx_reset() は次のように宣言します。

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

  MySQL 5.6 では、xxx_reset() は必要がないか使用されず、UDF インタフェースでは代わりに xxx_clear() が使用されます。ただし、古いバージョンのサーバーで UDF を動作させる場合、xxx_reset() と xxx_clear() を両方定義できます。(両方の関数を含める場合、xxx_reset() 関数は、すべての変数をリセットする xxx_clear() を呼び出してから、xxx_add() を呼び出して UDF_ARGS 引数をグループの最初の値として追加することによって、多くの場合内部的に実装できます。)

• xxx_clear()

  この関数は、MySQL でサマリー結果をリセットする必要がある場合に呼び出されます。これは新しいグループになるたびに最初に呼び出されますが、一致する行のないクエリーの値をリセットするために呼び出されることもあります。xxx_clear() は次のように宣言します。

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

  is_null は、xxx_clear() を呼び出す前に、CHAR(0) を指すように設定されます。

  処理に問題があった場合は、error 引数が指している変数に値を格納できます。error は文字列バッファーでなく単一バイト変数を指しています。

  xxx_clear() は MySQL 5.6 で必要となります。

• xxx_add()

  この関数は、同じグループに属するすべての行に対して呼び出されます。これは、UDF_ARGS 引数内の値を内部サマリー変数に追加するために使用します。

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

集約 UDF の xxx() 関数は、非集約 UDF と同様に宣言してください。セクション24.3.2.1「単純な関数のための UDF の呼び出しシーケンス」を参照してください。

集約 UDF の場合、MySQL はグループ内のすべての行が処理されたあとに xxx() 関数を呼び出します。通常はここで UDF_ARGS 引数にアクセスすることはなく、内部サマリー変数に基づいて値を返します。

xxx() での戻り値の処理は、非集約 UDF と同様に行います。セクション24.3.2.4「UDF の戻り値およびエラー処理」を参照してください。

xxx_reset() 関数および xxx_add() 関数は、UDF_ARGS 引数を非集約 UDF の関数と同様に処理します。セクション24.3.2.3「UDF 引数の処理」を参照してください。

is_null および error へのポインタ引数は、xxx_reset()、xxx_clear()、xxx_add()、および xxx() へのすべての呼び出しで同じです。これを使用すると、エラーが発生したこと、または xxx() 関数が NULL を返すかどうかを記憶できます。文字列を *error に格納しないでください。error は文字列バッファーでなく単一バイト変数を指しています。

*is_null は (xxx_clear() を呼び出す前に) グループごとにリセットされます。*error がリセットされることはありません。

xxx() が戻るときに *is_null または *error が設定されていた場合、MySQL はグループ関数の結果として NULL を返します。