当前位置：首页 > news >正文

达梦数据库-学习-21-C 外部函数

news 来源：原创 2025/5/24 5:59:28

一、环境信息

二、说点什么

三、介绍

四、参数介绍

五、语法树

六、标量类型参数

七、DM 结构化参数

1、结构体

（1）de_data

（2）de_args

2、函数介绍

（1）de_get_int

（2）de_get_double

（3）de_get_str

（4）de_get_str_with_len

（5）de_set_int

（6）de_get_int

（7）de_set_double

（8）de_set_str

（9）de_set_str_with_len

（10）de_return_int

（11）de_return_double

（12）de_return_str

（13）de_return_str_with_len

（14）de_return_null

（15）de_str_free

（16）de_is_null

八、实验

1、测试数据

2、PLSQL自定义函数

3、C外部函数源码

4、C外部函数编译

5、C外部函数动态库拷贝

6、调整参数

7、重启数据库

8、C外部函数创建

9、验证正确性

10、效率对比

一、环境信息

名称	值
CPU	12th Gen Intel(R) Core(TM) i7-12700H
操作系统	CentOS Linux release 7.9.2009 (Core)
内存	4G
逻辑核数	4
DM版本	1 DM Database Server 64 V8 2 DB Version: 0x7000c 3 03134284194-20240703-234060-20108 4 Msg Version: 12 5 Gsu level(5) cnt: 0

二、说点什么

工作中我们有时会遇到一个简单的查询，上面嵌套了一个用户自定义的PLSQL编写的函数，去掉此函数非常快，加上就效率堪忧，需要我们去优化，这时C外部函数就是一个好的选择，或者做ORACLE到信创数据库的迁移，有些函数用户是用C外部函数实现的，需要我们去改写成信创数据库的C外部函数，今天我们就来介绍一下达梦C外部函数如何编写。

三、介绍

C 外部函数是使用 C、C++语言编写，在数据库外编译并保存在.dll、.so 共享库文件中，被用户通过 DMSQL 程序调用的函数。

C 外部函数的执行一般通过代理 dmap 工具进行，此时为了执行 C 外部函数，需要先启动 dmap 服务。dmap 执行程序在 DM8 安装目录的 bin 子目录下，直接执行即可启动 dmap 服务。

同时，结构化的 C 外部函数支持结合 INI 参数 EFC_USE_AP 进行性能优化，当指定参数值为 0 时，结构化的 C 外部函数会在 dmserver 内部调用，不再和 dmap 进行通信，可以提高函数的执行效率。

当用户调用 C 外部函数时，服务器操作步骤如下：首先，确定调用的（外部函数使用的）共享库及函数；然后，通知代理进程工作。代理进程装载指定的共享库，并在函数执行后将结果返回给服务器。

C外部函数分为标量类型参数和DM 结构化参数两种。

四、参数介绍

参数名	描述
ENABLE_EXTERNAL_CALL	是否允许创建或执行外部函数。 0：不允许； 1：允许；
EFC_USE_AP	是否允许结构化的C外部函数在DMSERVER内部执行。 1：表示使用常规DMAP方式通信； 0：表示不使用DMAP，直接在DMSERVER内部调用执行，可以提高函数的执行效率；

五、语法树

CREATE [OR REPLACE] FUNCTION [IF NOT EXISTS] [<模式名>.]<函数名>[(<参数列表>)] 
RETURN <返回值类型> 
EXTERNAL '<动态库路径>' [<引用的函数名>] USING < C | CS >;

参数名	描述
函数名	指明被创建的 C 外部函数的名字；
模式名	指明被创建的 C 外部函数所属模式的名字，缺省为当前模式名；
参数列表	指明 C 外部函数参数信息，如果是使用 DM 结构化参数编写的 C 函数，参数模式可设置为 IN、OUT 或 IN OUT（OUT IN），缺省为 IN 类型；使用标量类型参数编写的 C 函数则参数模式只能是 IN 类型。参数类型、个数都应和动态库里定义的一致；
返回值类型	必须和动态库里定义的一致；
动态库路径	用户按照 DM 规定的 C 语言函数格式编写的 DLL 文件生成的动态库所在的路径；动态库分为 64 位和 32 位两种，使用的时候要和操作系统一一对应。例如， 64 位的操作系统要用 64 位的动态库；
引用函数名	指明函数名>在动态库路径>中对应的函数名；
USING	USING 子句指明函数的类型，如果是 DM 结构化参数的 C 函数，类型为 C；标量类型参数的 C 函数，类型为 CS；

六、标量类型参数

该方案中，用户不必引用 DM 提供的外部函数接口，可以按照标准的 C 风格编码，使用 C 标量类型作为参数类型。使用该方案编写的 C 函数，只能在使用 X86 CPU 的 64 位非 Windows 系统中，被数据库引用作为外部函数。

例子可以参考之前写的博客《达梦数据库-学习-07-C外部函数创建，及与Plsql自定义函数效率对比》。

七、DM 结构化参数

该方案中，C 用户必须使用 DM8 提供的编写 C 外部函数动态库的接口，严格按照要求格式书写外部函数的 C 代码。

优点在于效率高且适用于各个平台。

1、结构体

（1）de_data

返回值结构体。

typedef struct de_data_struct de_data;
struct de_data_struct
{udint4 null_flag; /*whether is null, 1:not null 0: null*/union	          {sdint4   v_int;ddouble  v_double;de_str   v_str;}data;
};
//只支持 int、double、float、binary_float、char 类型。其中 float 类型在系统内部被转化为 double 类型执行，相关接口请使用 double 类型的接口

（2）de_args

传入参数结构体。

typedef struct de_args_struct de_args;
struct de_args_struct
{udint4        n_args;       de_data*      args;         
};

2、函数介绍

（1）de_get_int

/*** <p>Function: return the arg_id para as int</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: get the id para value, start with 0, not null</li>
* </ul></p>* <p>return val : the arg_id para as int</p>*/
sdint4 
de_get_int(de_args* args, udint4   arg_id
);

第 arg_id 参数的数据类型为整型，从参数列表args中取出第arg_id参数的值。

（2）de_get_double

/*** <p>Function: return the arg_id para as double</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: get the id para value,start with 0,not null</li>
* </ul></p>* <p>return val : the arg_id para as double</p>*/
ddouble 
de_get_double(de_args*  args, udint4    arg_id
);

第 arg_id 参数的数据类型为 double 类型，从参数列表 args 中取出第 arg_id 参数的值。

（3）de_get_str

/*** <p>Function: return the arg_id para as string</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: get the id para value,start with 0,not null</li>
* </ul></p>* <p>return val : the arg_id para as string</p>*/
udbyte* 
de_get_str(de_args* args, udint4   arg_id
);

第 arg_id 参数的数据类型为字符串类型，从参数列表 args 中取出第 arg_id 参数的值。

（4）de_get_str_with_len

/*** <p>Function: return the arg_id para as string</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: get the id para value,start with 0,not null</li><li> alen: return the length of string</li>
* </ul></p>* <p>return val : the arg_id para as string</p>*/
udbyte* 
de_get_str_with_len(de_args*    args, udint4      arg_id, udint4*     alen
);

第 arg_id 参数的数据类型为字符串类型，从参数列表 args 中取出第 arg_id 参数的值以及字符串长度。

（5）de_set_int

/*** <p>Function: set the arg_id para as int</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: set the id para value,start with 0,not null</li> 
* </ul></p>* <p>return val: the arg_id para as int</p>*/
void 
de_set_int(de_args*    args, udint4      arg_id, sdint4      ret
);

第 arg_id 参数的数据类型为整型，设置参数列表args的第arg_id参数的值为 ret。

（6）de_get_int

/*** <p>Function: return the arg_id para as int</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: get the id para value, start with 0, not null</li>
* </ul></p>* <p>return val : the arg_id para as int</p>*/
sdint4 
de_get_int(de_args* args, udint4   arg_id
);

第 arg_id 参数的数据类型为整型，从参数列表args中取出第arg_id参数的值。

（7）de_set_double

/*** <p>Function: set the arg_id para as double</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: set the id para value,start with 0,not null</li> 
* </ul></p>* <p>return val: the arg_id para as double</p>*/
void 
de_set_double(de_args* args, udint4   arg_id, ddouble  ret
);

第 arg_id 参数的数据类型为 double 类型，设置参数列表 args 的第 arg_id 参数的值为 ret。

（8）de_set_str

/*** <p>Function: set the arg_id para as string</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: set the id para value,start with 0,not null</li> <li> ret: the new arg_id para as string,end with '\0'</li>
* </ul></p>* <p>return val: nothing</p>*/
void de_set_str(de_args*    args, udint4      arg_id, udbyte*     ret
);

第 arg_id 参数的数据类型为字符串类型，设置第 arg_id 参数的值为 ret。

（9）de_set_str_with_len

/*** <p>Function: set the arg_id para as string</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> args: not null</li><li> arg_id: set the id para value,start with 0,not null</li> <li> alen: length of the new string</li><li> ret: the new arg_id para as string,not end with '\0'</li>
* </ul></p>* <p>return val: nothing</p>*/
void 
de_set_str_with_len(de_args*    args, udint4      arg_id, udbyte*     ret, udint4      alen
);

第 arg_id 参数的数据类型为字符串类型，将字符串 ret 的前 len 个字符赋值给参数列表 args 的第 arg_id 参数。

（10）de_return_int

/*** <p>Function: return the arg_id para as int</p>* <p>Arthimetic: none</p>* <p>arg list: <br><ul><li> ret: return the int value</li>
* </ul></p>* <p>return val: int</p>*/
de_data 
de_return_int(sdint4 ret
);

返回值类型为整型。