Documentation Home
MySQL 5.6 リファレンスマニュアル
Download this Manual
PDF (US Ltr) - 27.1Mb
PDF (A4) - 27.1Mb
EPUB - 7.5Mb
HTML Download (TGZ) - 7.2Mb
HTML Download (Zip) - 7.2Mb


MySQL 5.6 リファレンスマニュアル  /  ...  /  単純な関数のための UDF の呼び出しシーケンス

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

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

メインの xxx() 関数は、このセクションに示すように宣言してください。CREATE FUNCTION ステートメントで SQL 関数 XXX()STRINGINTEGER、または 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_null1 に設定します。いずれかの引数が maybe_null として宣言されている場合、デフォルト値は 1 です。

  • unsigned int decimals

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

    引数で小数点以下の桁数が固定されていない場合、decimals 値は 31 に設定され、これは DECIMALFLOAT、および 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_item1 に設定し、それ以外の場合は 0 に設定します。


User Comments
  Posted by Tim Eliseo on January 2, 2014
Despite the supposed clarification of const_item added after http://bugs.mysql.com/bug.php?id=15470, and the discussion at http://forums.mysql.com/read.php?168,57613,57613, my own testing of code and reading of MySQL source reveals:

• const_item is an input/output parameter. It comes in as 1 (true) if and only if all UDF arguments are known to be constant throughout the query. That is, const_item will come into init as true only if there are no NULLs in the args array.

• If const_item is returned non-zero (true), MySQL may assume that your main function returns the same value for all calls in this context, and only call your main function once. (Or it may call your main function multiple times anyway, as I have noticed. If you care to optimize this, you should cache your return value instead of recalculating every time.) Otherwise (const_item is zero upon return), your main function will be called for every row.

This means that, in the common case where your return value is only dependent on the arguments, your init function shouldn’t touch const_item at all. You should only change const_item if:

• You might return a different value even with the same args, in which case you should set const_item to 0 (false). Random number generators or sequence number functions would be examples of this.

• The values of certain constant args will cause your function to return the same value regardless of the remaining non-constant ones, in which case you should set const_item to 1 (true). (If your return value is always the same, and independent of the value of *any* args, you should check if your function is pointless.)
Sign Up Login You must be logged in to post a comment.