ACI编程概述¶

头文件¶

神通数据库安装完成后，会自动安装aci相关文件，aci的头文件在数据库的安装目录中，比如$SZ_OSCAR_HOME/drivers/aci/include中，主要头文件如下：

头文件名称	作用	备注
aci.h	对外主要头文件，包含部分宏定义，间接引用其他.h头文件	程序中只包含aci.h或oci.h头文件即可，其他文件会间接包含
oci.h	引用aci.h，兼容部分应用程序可以不用修改应用头文件，和Oracle兼容。	程序中只包含aci.h或oci.h头文件即可，其他文件会间接包含
aciapi.h	包含接口声明定义头文件
acidef.h	aci接口到oci接口名称映射
aciext.h	aci部分扩展定义
acitype.h	数据类型定义和声明

备注：头文件windows和Linux通用；仅安装数据库客户端，aci驱动也会被安装。

动态库文件¶

aci目前主要提供方式为动态库(暂时不提供静态库)，动态的路径为：$SZ_OSCAR_HOME/drivers/aci/{平台} :

CPU平台	系统平台	库路径	库名称
X86架构(interval、amd、海光、兆芯)	Win32	$SZ_OSCAR_HOME/drivers/aci/win32	aci.lib aci.dll
X86架构(interval、amd、海光、兆芯)	Win64	$SZ_OSCAR_HOME/drivers/aci/win64	aci.lib aci.dll
X86架构(interval、amd、海光、兆芯)	Linux-x86	$SZ_OSCAR_HOME/drivers/aci/linux32	libaci.so
X86架构(interval、amd、海光、兆芯)	Linux-x64	$SZ_OSCAR_HOME/drivers/aci/linux64	libaci.so
ARM(飞腾、鲲鹏系列)	Linux-x64	$SZ_OSCAR_HOME/drivers/aci/arm64	libaci.so
MIPS(龙芯)	Linux-x64	$SZ_OSCAR_HOME/drivers/aci/loongson64	libaci.so
LOONGARCH(龙芯)	Linux-x64	$SZ_OSCAR_HOME/drivers/aci/loongarch64	libaci.so
alpha(神威)	Linux-x64	$SZ_OSCAR_HOME/drivers/aci/shenwei64	libaci.so

备注：windows下的aci.lib为符号链接库，无法单独使用。使用平台不对应的aci库会导致程序无法执行。Windows下编译时的运行库模式是：MD，对于需要跨模块内存处理场景，应用程序的运行库模式需要ACI一致，否则会出现异常现象。

ACI信息查看¶

ACI从v2.0.36(不含)版本后更高版本支持通过直接执行ACI库的方式获得版本号、客户端默认字符集、引用的配置文件路径等信息，打印的信息项目各版本可能有所变化。

Linux下获取方式¶

直接执行libaci.so库文件，比如：

/opt/ShenTong/bin/libaci.so

会打印类似如下信息：

Version : ACI 2.0.0 (64bit)(build 211931 020) for Linux

ClientEncoding : UTF-8

ConfigFile : No config file is found,default parameters are used!

信息说明：

*Version 代表的是ACI的编译版本。

*ClientEncoding 代表的是客户端的默认字符集，设置NLS_OSCAR_LANG会影响这个值，如果代码中设置了charsetid也会改变ACI的默认字符集。

*ConfigFile 代表ACI配置文件的路径，如果没有找到配置文件，则输出：No config file is found,default parameters are used![意思为：没有找到配置文件，所有配置参数采用默认值]。

备注：打印信息中可能还会包含ACI的其他值，比如fetch size; 协议类型；网络相关配置等。

环境需求：

由于此功能依赖操作系统的ld库，但各个平台和操作系统的ld库版本不同，且做的软链接也不同，因此部分平台直接执行libaci.so库可能报错，比如：

[root@localhost Linux64]# ./libaci.so

-bash: ./libaci.so: /lib64/ld-linux.so: bad ELF interpreter: 没有那个文件或目录

提示需要/lib64/ld-linux.so文件，而一般在操作系统的/lib64目录下肯定有ld-2-*.so这个库，将这个库做一个ld-linux.so链接即可(ln -s ld-2-*.so /lib64/ld-linux.so)，再次执行libaci.so即可正确执行。

各个平台依赖的ld库的路径一般不同，如果执行出错，请根据错误信息做软链接，aci中对各个平台下的ld软链接要求：

x86-64 : /lib64/ld-linux-x86-64.so.2

x86-32 : /lib/ld-linux.so.2

arm-64 : /lib64/ld-linux-aarch64.so.1

mipsel-64 : /lib64/ld.so.1

loongarch-64 : /lib64/ld-linux-loongarch64.so.1

sw-64 : /lib/ld-linux.so.2

Windows下获取方式¶

windows下通过rundll32.exe去执行，在64位操作系统中，c:\Windows\System32\rundll32.exe是64位的，c:\Windows\SysWOW64\rundll32.exe下是32位的。执行方式入下，打开一个cmd窗口，并进入aci.dll所在目录中去：

rundll32.exe aci.dll,__get_info

执行完成后，会在当前工作目录中生成aci_info.txt的文件，注意aci_info.txt生成在工作目录，如果cmd当前的目录是c:\,则aci_info.txt生成在c:\aci_info.txt。

ACI依赖情况¶

Linux对pthread库的依赖，因此需要在makefile文件的编译参数中加入-lpthread ，Ubuntu系统-pthread。

与OCI兼容¶

神通ACI的接口规范完全与Oracle的OCI一样，只是函数接口或者参数开头以ACI开头，Oracle以OCI开头，但神通ACI文件中提供了ACI到OCI的函数接口和参数的映射，因此引入神通头ACI相关文件以后，既可以按照Oracle的OCI开头的函数进行编码，也可以用神通ACI开头的函数进行编码，也可以混合使用(不建议混合使用)；同时部分ACI扩展(OCI中不存在)的一些函数和参数，只能以ACI开头。

对象大小写¶

由于神通数据库与Oracle保持一致，对象名称对大小写不敏感，任何对象名称到数据库中会转换成为大写，对象名称包含表名、列名、视图名、约束名等。

开发者在获得对象描述信息时，获得到的也是大写的；如果想让对象名保留输入大小写，则需要在创建对象时，给对象名称前后加双引号，比如：create table "Test" ( col1 int , "Col2" int);这样创建的表，col1字段名会变成大写，而且表名和Col2字段名称保留输入大小写格式；在任何查询SQL语句中，都需要给表名或列名加双引号：select col1,"Col2" from "Test"。

部分大小写敏感的神通数据库版本，ACI也提供了name_case_sensitive参数进行对应，详细参阅《参数配置文件》章节。

服务名配置文件¶

为了Oracle兼容，在连接数据库时，连接的URL可以是一个服务名称，ACI为了兼容这种使用，有一个tnsnames.aci配置文件。文件中单行为一个数据源配置，一个配置文件中允许有多个服务名的配置，格式如下：

{服务名} = {主机名/IP}:{端口号}/{数据库实例名称}

比如：

stdb = localhost:2003/osrdb

aci在查找tnsnames.aci文件的顺序：

$ ACI_TNS_FILE_DIR环境变量指定的目录
程序所引用的aci库所在目录
在安装过数据库服务端或客户端时，有环境变量$SZ_OSCAR_HOME ，则寻找$SZ_OSCAR_HOME/admin/
Linux系统下，会寻找/etc/

备注：在一些Linux环境普通用户数据访问环境下，对于tnsnames.aci的2、3、4种寻找方式可能是不具备权限的，因此建议优先采用1）方式设置环境变量的方式进行设置。

参数配置文件¶

aci驱动可通过sqlnet.aci文件来修改aci部分属性的值。sqlnet.aci中的参数，在aci驱动中有一个默认值，当sqlnet.aci文件不存在时，会采用aci源码中的默认值。

aci在查找sqlnet.aci文件时，遵循以下顺序，文件一旦寻找到，将终止继续寻找：

$ ACI_CONF_FILE_DIR环境变量指定的路径下
程序所引用的aci库所在目录
在安装过数据库服务端或客户端时，有环境变量$SZ_OSCAR_HOME ，则寻找$SZ_OSCAR_HOME/admin/
Linux系统下，会寻找/etc/

备注：在一些Linux环境普通用户数据访问环境下，对于sqlnet.aci的2、3、4种寻找方式可能是不具备权限的，因此建议优先采用第一种设置环境变量的方式进行设置。

参数说明¶

trace_level¶

描述

调试信息打印级别，开启调试后，会根据级别打印调试信息，方便开发过程中的问题调试。

所属句柄及属性

全局，只能通过文件修改

取值范围
- 0 不打印；
- 1 打印SQL语句；
- 2 打印函数调用；
- 4 打印简单网络协议
- 8 打印详细网络协议
- 16 打印网络级系统调用日志
- 上述可选值可累加使用，比如 3 表示打印SQL语句和函数调用

trace_file_path¶

描述

调试信息输出文件路径。

所属句柄及属性

全局，只能通过文件修改

取值范围

默认值 aci_trace.log，默认路径为aci库所在目录。需要注意的是路径前后需要加单引号，比如：trace_file_path='/opt/log/'

指向的目录必须存在，aci不会去创建，且目录结束必须有/，否则会报错。

同时：如果指定路径不具有权限或者子目录不存在，写入日志会失败。

aci_trace_log_maxsize¶

描述

设置日志记录大小上限，日志文件写满后，文件会被重写，日志内容会被覆盖。单位为MB。

所属句柄及属性

全局，只能通过文件修改

取值范围
- 最大值 2000
- 最小值 1
- 默认值 20

batch_buffer¶

描述

调试信息输出文件路径。

所属句柄及属性

句柄：ACIStmt，属性：ACI_ATTR_BATCH_BUFFER

取值范围
- 最大值 1024
- 最小值 1
- 默认值 10

execute_batch_size¶

描述

普通execute语句一次执行次数达到多少可以走batch协议。

所属句柄及属性

句柄：ACIStmt，属性：ACI_ATTR_EXECUTE_BATCH_SIZE

取值范围
- 最大值 5000
- 最小值 1
- 默认值 100

fetch_size¶

描述

一次从数据库预取的结果集行数，在查询结果函数比较多的情况下，适当调大改值可提高数据读取效率。

所属句柄及属性

句柄：ACIStmt，属性：ACI_ATTR_FETCH_SIZE

取值范围
- 最大值 5000
- 最小值 0
- 默认值 16

prepare_simple_execute¶

描述

不带参数的prepare语句是否可以直接走query协议执行sql语句。这样可以提高交互效率，减少游标使用量。

所属句柄及属性

句柄：ACIStmt，属性：ACI_ATTR_PREPARE_SIMPLE_EXECUTE

取值范围

默认值 on，即对于没有参数的sql，不再执行prepare语句。

net_data_by_str¶

描述

网络协议数据是否采用字符串方式传输。神通数据库的网络协议支持两种格式：一种为字符串方式：即将所有数据都穿换成字符串进行传输；另外一种为二进制格式，即传输的是数据的二进制内容。比如：对于int类型，一个值为10000000，如果按照字符串方式传输，需要8个字节，如果按照二进制传输，需要4个字节。

因此该参数主要影响性能，理论上二进制传输效率高于字符串传输，保留字符串传输方式为兼容神通数据库老版本，不建议使用。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_NET_DATA_BY_STR

取值范围

默认值 off，代表按二进制传输数据；

On，代表按字符串方式传输数据

send_floatingnumber_keep_precision¶

描述

小数的类型，如float、double、numeric、decimal是否按字符串格式传输。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_SEND_FLOATINGNUMBER_KEEP_PRECISION

取值范围

默认值 on，代表数值全部采用字符串方式传输，这样可保留高精度。

如果设置为off，低精度只能保留6位有效小数。

compress_min_size¶

描述

数据包达到多大可以使用压缩。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_COMPRESS_MIN_SIZE

取值范围
- 最大值 2147483647
- 最小值 50
- 默认值 50

备注：应当在调用 ACISessionBegin 之前进行设置。

compatible_old_protocal¶

描述

驱动是否直接使用旧协议，主要是兼容部分比较老的神通数据库版本，不建议修改。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_COMPATIBLE_OLD_PROTOCAL

取值范围

默认值 off，不使用老协议，采用新协议传输。

on：使用老协议

send_old_startup_packet¶

描述

驱动是否直接发送旧的启动包，主要是兼容部分比较老的神通数据库版本，不建议修改。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_SEND_OLD_STARTUP_PACKET

取值范围

默认值 off，代表不使用旧得启动包，采用新的启动包。

on：使用旧得启动包

socket_connway¶

描述

驱动是否使用阻塞模式创建连接，采用非阻塞模式，aci可以控制连接创建的超时时间，非阻塞模式的连接超时时间由系统控制。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_SOCKET_BLOCK_CONN

取值范围

默认值为off，代表采用非阻塞模式创建连接，

on为阻塞模式

socket_connect_timeout¶

描述

网络连接的超时时间，超过设定时间，返回创建连接失败；单位为秒，socket_connway设置为on时，此参数不生效。单位为秒。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_SOCKET_CONNECT_TIMEOUT

取值范围

默认值60秒；如果socket_connway为on，网络连接的超时时间受操作系统影响：windows一般为20秒；Linux一般为127秒(Linux内核参数net.ipv4.tcp_syn_retries默认为6，调小可减小网络超时时间)

reconnect_timeout¶

描述

重连是由于连接因为网络原因断开后，需要重连过程，重连其实代表的为重连次数，每隔一秒会进行一次网络重连，每次重连的超时时间受socket_connect_timeout参数控制，比如reconnect_timeout设置为10，socket_connect_timeout设置为20秒，总的网络重连超时时间为10*20=200秒。单位为秒。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_RECONNECT_TIMEOUT

取值范围
- 最大值 4294967296
- 最小值 0
- 默认值 0(代表网络断开后直接报错，不进行重试连接)

call_timeout¶

描述

网络读写操作超时时间，如果执行的SQL语句超过设定时间，强行返回错误。单位毫秒。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_CALL_TIMEOUT，环境句柄级句柄：ACISvc，属性：ACI_ATTR_CALL_TIMEOUT，连接级

取值范围

默认0秒，代表不会超时。如果需要更改这个值，不建议太小，至少是分钟级(比如10分钟改值为：600000) ，如果部分应用场景，比较明确SQL语句执行较长时，可将该参数值加大，避免语句正常执行过程中被终止出现程序异常。

keepalive_on¶

描述

是否开启keepalive功能的全局开关，如果设置为off，则keepalive_idle、keepalive_interval 、keepalive_count几个参数都无效。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_KEEPALIVES_ON

取值范围

默认值 on，代表开启keepalive;

Off代表关闭keepalive；

keepalive_idle¶

描述

对一个连接进行有效性探测之前运行的最大非活跃时间间隔，单位为秒。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_KEEPALIVES_IDLE

取值范围
- 最大值 2147483647
- 最小值 60
- 默认值 300

keepalive_interval¶

描述

两个探测的时间间隔，单位为秒。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_KEEPALIVES_INTERVAL

取值范围
- 最大值 2147483647
- 最小值 1
- 默认值 75

keepalive_count¶

描述

关闭一个非活跃连接之前进行探测的最大次数。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_KEEPALIVES_COUNT

取值范围
- 最大值 100
- 最小值 5
- 默认值 9

enable_encoding¶

描述

是否开启字符集转换功能，开启后，aci会进行客户端字符集到数据库字符集直接的转换。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_ENABLE_ENCODING

取值范围

默认值on，开启转换，这边避免乱码；

Off，不转码。

enable_dispatch¶

描述

是否开启语句分发功能。

所属句柄及属性

句柄：ACISvcCtx，属性：ACI_ATTR_ENABLE_DISPATCH

取值范围

默认值 off 代表关闭语句分发功能；

on代表打开语句分发功能。

use_asynchronous_slave¶

描述

读操作是否可以分发到和非强制同步备机，强制同步备机是指数据库配置参数ENABLE_HA_SLAVE_SYNC_REDO为TURE的同步备机，只在enable_dispatch为on时起作用。

所属句柄及属性

句柄：ACISvcCtx，属性：ACI_ATTR_USE_ASYNCHRONOUS_SLAVE

取值范围

默认值 off，代表不分发；

On代表分发到异步备机。

host_percentage_of_statement¶

描述

查询语句分发到主机的语句所占比例。

所属句柄及属性

句柄：ACISvcCtx，属性：ACI_ATTR_HOST_PERCENTAGE_OF_STATEMENT

取值范围
- 最大值 100
- 最小值 -1
- 默认值 1

send_lsn_to_slave¶

描述

LSN是否发到备机，开启该参数备机需等待与主机相关事务进行同步，只在enable_dispatch为on时起作用。

所属句柄及属性

句柄：ACISvcCtx，属性：ACI_ATTR_SEND_LSN_TO_SLAVE

取值范围

默认值 off，代表不发；

On代表分发到备机。

mpp_loadnodenum¶

描述

Mpp数据导入功能中待加载节点数，只在与MPP建立连接时该参数才起作用。

所属句柄及属性

句柄：ACIHIMP，属性：ACI_ATTR_MPP_LOAD_NODENUM

取值范围
- 最大值 MPP集群节点个数
- 最小值 0
- 默认值 0

name_case_sensitive¶

描述

设置aci是否支持大小写敏感，如果设置为true，则代表支持大小写敏感，这样传入的用户名、表名等不会进行大小写转换处理，程序输入什么，ACI将原来的大小写发生给数据库。注意需要数据库后端开启这个两个参数，否则会引起登录不成功或者对象不存在等问题的出现。 LOWER_CASE_TABLE_NAMES=0 NAME_CASE_SENSITIVE=false

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_CASE_SENSITIVE

取值范围

默认值 false，不敏感；

True，大小写敏感。

errorinfo_language¶

描述

设置aci错误信息的中英文，本设置值针对aci内部错误，无法控制数据库后台返给aci的错误信息是否为中英文。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_CHINESE_ERRORINFO

取值范围

默认值 true，中文；

False，英文。

dbtext_max_len¶

描述

设置aci从数据库获取text数据类型返回长度的大小

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_DB_TEXT_MAX_LEN

取值范围

最大值 2147483647

最小值 1

默认值 150000

emptystring_is_null¶

描述

aci在处理空串时是否处理成null值。默认为0，空字符串插入到数据库中也是空字符串，如果为1，则空字符串插入到数据库中会变为NULL。值得注意的是该参数只能在连接字符串中设置。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_EMPTYSTRING_IS_NULL

取值范围

默认值 0 ，空字符串插入到数据库中也是空字符串

值如果为 1 ，空字符串插入到数据库中会变为NULL

ssl_wallet_enable¶

描述

是否开启SSL安全通信

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_LDAP_AUTH

取值范围

默认值 0 ，代表不开启

值大于等于1 ，代表开启

ssl_wallet_path¶

描述

指定客户端证书和密钥文件的路径,ssl_wallet_enable参数值大于等于1时生效。

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_WALL_LOC

取值范围

指定一个文件夹路径，比如：/opt/wallet/

ssl_wallet_pwd¶

描述

指定客户端密钥的密码

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_WALL_PWD

取值范围

在生成客户端密钥时指定的密码

ssl_wallet_cipherlist¶

描述

指定客户端的加密套件

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_WALL_CIPHERLIST

取值范围

该属性可以不设置。如需设置，需要设置对应的加密协议及加密算法，加密协议及加密算法之间使用逗号进行分隔，比如: tls1.3,TLS_AES_128_GCM_SHA256

enable_os_auth¶

描述

是否开启OS认证(免密登录)

所属句柄及属性

句柄：ACIEnv，属性：ACI_ATTR_OS_AUTH

取值范围

默认值 0 ，代表不开启

值为 1 ，代表开启

修改方式¶

配置参数的设置一般有三种：

1）第一种：直接在指定路径的配置参数文件中修改，需要确保参数文件能被正确引用到。

2）第二种：在ACI程序中设置，通过 ACIAttrSet 接口进行设置，需要注意每一个参数对应的句柄类型，进行对应设置，比如：

ACIEnv *m_penv;
ACIError *m_perr;
boolean sendDataByStr = FALSE;
ACIAttrSet(m_penv, ACI_HTYPE_ENV,&sendDataByStr,sizeof(sendDataByStr), ACI_ATTR_NET_DATA_BY_STR, m_perr);

3）第三种：设置ACI的连接字符串，以"?"作为参数标志符，参数属性之间以“;”作为分隔，比如设置：fetch_size参数方式如下： localhost:2003/OSRDB?fetch_size=1000;chinese_errorinfo=false

备注：几种方式参数设置的优先级为：3> 2> 1，优先级高的将覆盖优先级低的设置。

生效说明¶

按照以前章节中的设置方式后，ACI并不会自动加载参数文件的变化，所以此时不会生效，想要ACI应用程序能生效，必须重启应用软件，让ACI重新加载一次配置文件即可。

ACI平台兼容性¶

CPU平台¶

CPU类型	版本	支持情况
ARM架构	鲲鹏920	支持
ARM架构	飞腾1500A	支持
ARM架构	飞腾2000/飞腾2000+	支持
MIPS架构	龙芯1500A/1500B	支持
MIPS架构	龙芯2000A/2000B	支持
MIPS架构	龙芯3000A/3000B	支持
MIPS架构	龙芯4000A/4000B	支持
MIPS架构	龙芯5000A/5000B	自研LOONGARCH指令集平台，神通全线支持
X86架构	Intel系列	支持
X86架构	AMD系列	支持
X86架构	海光	支持
X86架构	兆芯	支持
Alpha架构	神威1600/400	支持
Alpha架构	神威1610	支持
Alpha架构	神威1621/6A	支持

备注：此信息会定期更新，但不一定包括支持的所有平台

操作系统¶

系统类型	版本	支持情况
Windows	XP	不支持
Windows	Win7	支持
Windows	Win8	支持
Windows	Win10	支持
Windows	Server2008	支持
Windows	Server2012	支持
Windows	Server2016	支持
Windows	Server2019	支持
Redhat	全系操作系统	支持
Centos	全系操作系统	支持
中标麒麟	5.x、6.x、7.x系列	支持
银河麒麟	2.x、4.x、kylin10系列	支持
统一操作系统UOS	UOS20	支持
深度操作系统	15.x	支持
统信UOS	V20	支持
UKYLIN	全系操作系统	支持
中科方德	全系操作系统	支持

备注：此信息会定期更新，但不一定包括支持的所有平台