24.3.2.1 単純な関数のための UDF の呼び出しシーケンス

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

メインの xxx() 関数は、このセクションに示すように宣言してください。CREATE FUNCTION ステートメントで SQL 関数 XXX() が STRING、INTEGER、または REAL のいずれを返すかに応じて、戻り型およびパラメータは異なります。

STRING 関数の場合:

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

INTEGER 関数の場合:

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

REAL 関数の場合:

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

DECIMAL 関数は文字列値を返すため、STRING 関数と同様に宣言してください。ROW 関数は実装されていません。

初期化関数および初期化解除関数は、次のように宣言します。

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

void xxx_deinit(UDF_INIT *initid);

initid パラメータは 3 つの関数すべてに渡されます。これは、関数間で情報をやり取りするために使用される UDF_INIT 構造体を指しています。UDF_INIT 構造体メンバーを次に示します。初期化関数で、変更するメンバーを設定してください。(メンバーのデフォルトを使用する場合は、変更せずにそのままにします。)

• my_bool maybe_null

  xxx() が NULL を返すことができる場合、xxx_init() は maybe_null を 1 に設定します。いずれかの引数が maybe_null として宣言されている場合、デフォルト値は 1 です。

• unsigned int decimals

  小数点の右側の桁数。デフォルト値は、メイン関数に渡された引数の小数点以下の桁数の最大値です。たとえば、関数に 1.34、1.345、および 1.3 が渡された場合、1.345 の小数点以下の桁数が 3 であるため、デフォルトは 3 になります。

  引数で小数点以下の桁数が固定されていない場合、decimals 値は 31 に設定され、これは DECIMAL、FLOAT、および DOUBLE データ型に許可される最大の小数点以下の桁数に 1 を加えた数です。MySQL 5.6 では、この値は mysql_com.h ヘッダーファイルの定数 NOT_FIXED_DEC として利用できます。

  decimals 値の 31 は、FLOAT カラムまたは DOUBLE カラムが小数点以下の桁数を明示せずに宣言された (たとえば、FLOAT(10,3) でなく FLOAT) 場合の引数、または 1345E-3 などの浮動小数点の定数に使用されます。これは、関数内で数値形式に変換される可能性がある、文字列およびその他の数値以外の引数に対しても使用されます。

  decimals メンバーを初期化する値は、デフォルトにすぎません。これは、実行される実際の計算が反映されるように関数内で変更できます。デフォルトは、引数の最大の小数点以下の桁数が使用されるように決定します。いずれかの引数の小数点以下の桁数が NOT_FIXED_DEC である場合、その値が decimals に使用されます。

• unsigned int max_length

  結果の最大長。デフォルトの max_length 値は、関数の結果の型に応じて異なります。文字列関数の場合、デフォルトはもっとも長い引数の長さです。整数関数の場合、デフォルトは 21 桁です。実数関数の場合、デフォルトは initid->decimals によって示されている小数点以下の桁数に 13 を加えた値です。(数値関数の場合、長さには符号文字または小数点文字が含まれています。)

  BLOB 値を返す場合は、max_length を 65K バイトまたは 16M バイトに設定できます。このメモリーは割り当てられませんが、この値は、データを一時的に格納する必要がある場合に使用するデータ型を決定するために使用されます。

• char *ptr

  関数が独自の用途に使用できるポインタ。たとえば、複数の関数間で initid->ptr を使用して、割り当て済みのメモリーをやり取りできます。xxx_init() でこのメモリーを割り当てて、それをこのポインタに割り当てます。

  initid->ptr = allocated_memory;

  xxx() および xxx_deinit() では、initid->ptr を参照して、メモリーを使用または割り当て解除します。

• my_bool const_item

  xxx_init() は、xxx() が常に同じ値を返す場合は const_item を 1 に設定し、それ以外の場合は 0 に設定します。