xxx()

主要函數。這是計算函數結果的地方。SQL 函數資料類型與 C++ 函數傳回類型之間的對應關係如下所示。

也可以宣告 DECIMAL 函數，但該值會以字串形式傳回，因此您應該將該函數撰寫為 STRING 函數。ROW 函數未實作。

xxx_init()

xxx() 的初始化函數。如果存在，它可以用於以下目的

xxx_deinit()

xxx() 的取消初始化函數。如果存在，它應該釋放初始化函數所配置的任何記憶體。

xxx_clear()

重置目前的彙總值，但不會將引數作為新群組的初始彙總值插入。

xxx_add()

將引數新增至目前的彙總值。

bool maybe_null

如果 xxx() 可能會傳回 NULL，xxx_init() 應將 maybe_null 設定為 1。如果任何引數宣告為 maybe_null，則預設值為 1。

unsigned int decimals

小數點右邊的小數位數。預設值是傳遞至主函數的引數中小數位數的最大值。例如，如果函數傳遞了 1.34、1.345 和 1.3，則預設值會是 3，因為 1.345 有 3 個小數位數。

對於沒有固定小數位數的引數，decimals 值會設定為 31，這比 DECIMAL、FLOAT 和 DOUBLE 資料類型允許的最大小數位數多 1。此值在 mysql_com.h 標頭檔案中以常數 NOT_FIXED_DEC 提供。

在以下情況下，引數會使用 31 的 decimals 值：例如，FLOAT 或 DOUBLE 資料行宣告時沒有明確的小數位數（例如，FLOAT 而非 FLOAT(10,3)），以及浮點常數（例如 1345E-3）。它也用於字串和其他可能在函數中轉換為數值形式的非數字引數。

decimals 成員初始化的值只是預設值。可以在函數內變更它以反映執行的實際計算。預設值的決定方式為使用引數的最大小數位數。如果甚至有一個引數的小數位數為 NOT_FIXED_DEC，則該值會用於 decimals。

unsigned int max_length

結果的最大長度。預設的 max_length 值會因函數的結果類型而異。對於字串函數，預設值是最長引數的長度。對於整數函數，預設值為 21 位數。對於實數函數，預設值為 13 加上 initid->decimals 指示的小數位數。（對於數值函數，長度會包含任何符號或小數點字元。）

如果您想要傳回 blob 值，您可以將 max_length 設定為 65KB 或 16MB。此記憶體不會配置，但該值會用於決定是否需要暫時儲存資料時要使用哪種資料類型。

char *ptr

函數可以用於自身用途的指標。例如，函數可以使用 initid->ptr 在彼此之間傳遞配置的記憶體。xxx_init() 應配置記憶體並將其指派給此指標

initid->ptr = allocated_memory;

在 xxx() 和 xxx_deinit() 中，請參閱 initid->ptr 以使用或釋放記憶體。

bool const_item

如果 xxx() 總是傳回相同的值，xxx_init() 應將 const_item 設定為 1，否則設為 0。

xxx_reset()

當 MySQL 在新的群組中找到第一列時，會呼叫此函數。它應重設任何內部摘要變數，然後使用給定的 UDF_ARGS 引數作為群組中內部摘要值的起始值。宣告 xxx_reset()，如下所示

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

在 MySQL 9.0 中不需要或使用 xxx_reset()，在該版本中，可載入函數介面會改用 xxx_clear()。但是，如果您想要讓函數與舊版伺服器搭配使用，您可以定義 xxx_reset() 和 xxx_clear()。（如果您同時包含這兩個函數，在許多情況下，可以透過呼叫 xxx_clear() 來重設所有變數，然後呼叫 xxx_add() 將 UDF_ARGS 引數新增為群組中的第一個值，以在內部實作 xxx_reset() 函數。）

xxx_clear()

當 MySQL 需要重設摘要結果時，會呼叫此函數。它會在每個新群組的開頭呼叫，但也可以呼叫它來重設沒有相符列的查詢值。宣告 xxx_clear()，如下所示

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

在呼叫 xxx_clear() 之前，is_null 會設定為指向 CHAR(0)。

如果發生錯誤，您可以將值儲存在 error 引數指向的變數中。error 指向單一位元組變數，而不是字串緩衝區。

MySQL 9.0 需要 xxx_clear()。

xxx_add()

針對屬於相同群組的所有列呼叫此函數。您應使用它將 UDF_ARGS 引數中的值新增至您的內部摘要變數。

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

unsigned int arg_count

引數的數量。如果您要求您的函數使用特定數量的引數來呼叫，請在初始化函數中檢查此值。例如

if (args->arg_count != 2)
{
    strcpy(message,"XXX() requires two arguments");
    return 1;
}

對於其他為陣列的 UDF_ARGS 成員值，陣列參照是以零為基礎的。也就是說，使用索引值 0 到 args->arg_count − 1 來參照陣列成員。

enum Item_result *arg_type

指向包含每個引數類型的陣列的指標。可能的值類型為 STRING_RESULT、INT_RESULT、REAL_RESULT 和 DECIMAL_RESULT。

為了確保引數屬於給定類型，並且在引數不屬於該類型時傳回錯誤，請在初始化函數中檢查 arg_type 陣列。例如

if (args->arg_type[0] != STRING_RESULT ||
    args->arg_type[1] != INT_RESULT)
{
    strcpy(message,"XXX() requires a string and an integer");
    return 1;
}

DECIMAL_RESULT 類型的引數會以字串形式傳遞，因此您會以與 STRING_RESULT 值相同的方式處理它們。

作為要求函數引數為特定類型的替代方法，您可以使用初始化函數將 arg_type 元素設定為您想要的類型。這會導致 MySQL 在每次呼叫 xxx() 時強制轉換引數為這些類型。例如，若要指定前兩個引數應分別強制轉換為字串和整數，請在 xxx_init() 中執行此動作

args->arg_type[0] = STRING_RESULT;
args->arg_type[1] = INT_RESULT;

精確值十進位引數（例如 1.3 或 DECIMAL 資料行值）會以 DECIMAL_RESULT 類型傳遞。但是，這些值會以字串形式傳遞。若要接收數字，請使用初始化函數指定引數應強制轉換為 REAL_RESULT 值

args->arg_type[2] = REAL_RESULT;

char **args

args->args 會將關於傳遞給您函數之引數的一般性質的資訊傳達給初始化函數。對於常數引數 i，args->args[i] 指向引數值。(請參閱後續說明，了解如何正確存取值。)對於非常數引數，args->args[i] 為 0。常數引數是僅使用常數的表示式，例如 3 或 4*7-2 或 SIN(3.14)。非常數引數是指向可能會逐列變更之值的表示式，例如欄名稱或使用非常數引數呼叫的函數。

對於主要函數的每個調用，args->args 都包含目前正在處理的列所傳遞的實際引數。

如果引數 i 代表 NULL，則 args->args[i] 為空指標 (0)。如果引數不是 NULL，函數可以透過以下方式參考它

unsigned long *lengths

對於初始化函數，lengths 陣列會指出每個引數的最大字串長度。您不應變更這些。對於主要函數的每個調用，lengths 都會包含目前正在處理的列所傳遞之任何字串引數的實際長度。對於類型為 INT_RESULT 或 REAL_RESULT 的引數，lengths 仍然包含引數的最大長度 (如同初始化函數一樣)。

char *maybe_null

對於初始化函數，maybe_null 陣列會指出每個引數的引數值是否可能為 null (如果否則為 0，如果是則為 1)。

char **attributes

args->attributes 會傳達關於函數引數名稱的資訊。對於引數 i，屬性名稱會以字串形式在 args->attributes[i] 中提供，而屬性長度則為 args->attribute_lengths[i]。請勿假設字串以 null 結尾。

預設情況下，函數引數的名稱是指定引數所用之表示式的文字。對於可載入函數，引數也可能具有選用的 [AS] 別名 子句，在這種情況下，引數名稱為 別名。因此，每個引數的 attributes 值取決於是否提供了別名。

假設可載入函數 my_udf() 的調用方式如下

SELECT my_udf(expr1, expr2 AS alias1, expr3 alias2);

在此情況下，attributes 和 attribute_lengths 陣列將具有以下值

args->attributes[0] = "expr1"
args->attribute_lengths[0] = 5

args->attributes[1] = "alias1"
args->attribute_lengths[1] = 6

args->attributes[2] = "alias2"
args->attribute_lengths[2] = 6

unsigned long *attribute_lengths

attribute_lengths 陣列會指出每個引數名稱的長度。

關於它們傳遞給可載入函數的引數，應用程式將繼續運作，因為該函數現在能夠處理任何字元集中的字串引數，包括二進位字串。

如果要讓可載入函數以與其引數字元集不同的字元集傳回字串結果，則該函數必須在內部執行字元集轉換。例如，如果函數接受 latin1 引數但傳回 utf8mb4 結果，就會發生這種情況。

metaphon() 會傳回字串引數的 metaphon 字串。這有點像 soundex 字串，但它更適合英文。

myfunc_double() 會傳回其引數中字元的 ASCII 值總和，除以其引數長度的總和。

myfunc_int() 會傳回其引數長度的總和。

sequence([const int]) 會傳回從給定數字開始的序列，如果未給定數字則傳回 1。

lookup() 會傳回主機名稱的 IP 位址。

reverse_lookup() 會傳回 IP 位址的主機名稱。可以使用 'xxx.xxx.xxx.xxx' 形式的單一字串引數或四個數字來呼叫該函數。

avgcost() 會傳回平均成本。這是一個彙總函數。