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 8.4 中，不需要或不使用 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 8.4 需要 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] alias_name 子句，在這種情況下，引數名稱是 alias_name。因此，每個引數的 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() 回傳平均成本。這是一個彙總函數。