このセクションでは単純な 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
に設定します。