金仓数据库KingbaseES客户端编程接口指南-DCI（3. DCI 工程配置）

3. DCI 工程配置¶

• Windows 平台工程搭建(vs2008)

• Linux平台工程搭建

• 服务的配置方法与参数说明

• 多主机地址配置

3.1. Windows 平台工程搭建(VS2008)

3.2. Linux平台工程搭建

 

3.3. 服务的配置方法与参数说明

DCI 通过服务名连接数据库。服务在文件 sys_service.conf 中配置。

在 DCI 中，可使用的参数和含义如下所示：

注意:

3.4. 多主机地址配置

通过此配置方法，可以实现多主机地址连接，并区分主备机。

多主机配置示例（值连接主机，连接超时5秒，ACK超时3000毫秒）：

[Kingbase]
host=192.168.0.1,192.168.0.2
dbname=test
user=system
port=54321
pqopt={target_session_attrs=read-write connect_timeout=5 tcp_user_timeout=3000}

该示例中参数含义如下所示：

其它可配置参数可参见 服务的配置方法与参数说明。

1. 使用VS建立DCI工程，示例代码使用的是“程序示例->登陆和注销数据库”的用例。将DCI库包解压到需求目录，本例的解压目录为 C:\dci_dll_dirpath 。

    

    

   【提醒】

2. 在连接数据库前，请参照 服务的配置方法与参数说明 ，配置服务文件sys_service.conf。

3. 运行程序需要配置DLL的路径：

   1. 将DLL放置到应用程序生成目录；

   2. 将动态库目录写入环境变量PATH中(需要重启visual studio软件)。

4. host 主机名 如果有多个 host 值可以使用“,”将它们分隔开或使用"( )"将他们括起来。

5. port 端口号

6. dbname 数据库名

7. UseExtendedProtocol 使用扩展协议（取值0或者1）

8. UsePackage 是否使用 Package（取值0或者1）

9. Print 是否打印语句信息（输出到标准输出，而非日志文件；取值0或者1）

10. sys_service.conf 文件的书写格式如下：

    [servicename1]
    keyword=value
    ...
    
    [servicename2]
    ...
    
    示例：
    
    [kingbase]
    host=192.168.0.1,198.168.0.2
    dbname=SAMPLES
    port=54321
    

11. 在 sys_service.conf 文件中服务名使用方括号 '[]' 识别, 如果出现多个相同的服务名(不区分大小写)，第一个出现的那个将被使用；如果一个服务中出现多个相同参数（host 除外），最后一个出现的那个将被使用；如果参数是 host，则直接把其 host 值加入 host 列表中。

12. sys_service.conf 文件每行不得超过 256 个字符，使用“#“来进行注释

13. sys_service.conf 文件所在路径：

    DCI接口提供两种配置方法，用来建立与sys_service.conf的关联：

    • 根据不同平台，将config文件夹中的sys_service.conf拷贝到指定的路径下：

      Windows XP指定路径为：X:\Documents and Settings\All Users\Application Data\KingbaseES 目录。

      Windows 7指定路径为：X:\ProgramData\KingbaseES 目录。

      Linux指定路径为：/etc/KingbaseES 目录。

      注：

      1. 路径中KingbaseES文件夹需要用户自己建立；

      2. X为系统盘符；

      3. 在Windows平台，需注意Application Data与ProgramData为系统隐藏文件夹。

    • 指定环境变量

      在Windows和Linux平台，用户可以根据需要更改 sys_service.conf 文件的位置，但在连接数据库之前需要通过设置环境变量 KINGBASE_CONFDIR 指定其所在目录的路径。

14. keyword 格式说明：keyword 以及 其后的 value 不区分大小写；keyword 之前以及 '=' 前后允许有空格，但 keyword 和 value 内部的空格不会被忽略；若想将 keyword 赋为空串，则 '=' 后的 value 保持空白即可（'' 或 "" 不会作为空串而是作为 value 值处理）。

15. 如果使用DCI接口的应用程序以“IP:PORT:DBNAME”的方式连接数据库，则sys_service.conf文件中服务名为“Default”的配置将生效。

16. 如果使用DCI接口的应用程序以“IP:PORT:DBNAME”的方式连接数据库， 但是无法通过默认路径或指定的环境变量找到sys_service.conf配置文件时，应用程序将在DCI默认参数下启动，默认参数为：

    AutoCommit=0
    AutoCommitDDL=1
    BatchInsertSize_Ext=1
    Protocol=7.4-2
    

    注：该功能生效后，在DCI端会有两套默认值，即原有的默认值模式和类Oracle默认值模式， 只有在当前配置中描述的情况下，参数的默认值才会采用类Oracle的默认值模式。 其他情况下为了与原有功能保持一致，所以保持了原有的默认值。 两套默认值的不同在于：原默认值中默认AutoCommit=1，并且不配置BatchInsertSize_Ext，即默认该配置为0；类Oracle默认值则开启上述四个配置。

17. host： 配置多个地址，使用逗号分隔，驱动处理时会按顺序连接，直到有一个成功并符合 target_session_attrs 条件并返回。

18. pqopt： 配置其它扩展参数，使用大括号"{}"括起来，中间用空格分隔。

    其他扩展参数解释：

    • target_session_attrs=read-write：表明只返回可读写的节点连接，即主机连接，如果不满足，会继续尝试下一个地址。 默认是any，即主备都可以。

    • connect_timeout=5：表示连接超时时间，单位是秒，最少2秒，默认为10秒。如果是多个地址，就是指所有连接尝试的总时长。

    • tcp_user_timeout=3000：表示TCP报文的等待ACK的最大等待时间，单位为毫秒，默认为0，即没有限制，以操作系统配置为准。

    • DCILog 指定日志信息文件的保存路径（文件可不存在，但是其父目录必须存在，并且有写权限） 日志配置是全局生效的，所以DCI只会根据找到的第一个有效的日志参数值为准。因此如果有多个数据源都有日志配置，其实也只有第一个日志配置参数生效。

    • DCILogLevel 指定日志级别，可取值为：LOG / DEBUG1 / DEBUG2 / DEBUG3 / DEBUG4 / DEBUG5

    • UseDciDat

      当 UseDciDat=0 时，对于数据库中的timestamp类型，返回的DCI类型为SQLT_DAT，默认值为0。

      当 UseDciDat=1 时，对于数据库中的timestamp(0)，返回的 DCI类型为SQLT_DAT；对于其他的timestamp类型返回的DCI类型为SQLT_TIMESTAMP。

      当 UseDciDat=2 时，对于数据库中的timestamp类型，无论精度是多少，返回的DCI类型为SQLT_TIMESTAMP。

      UseDciDat 取 0，1，2 以外的值时，接口按照默认值0进行处理。

    • AutoCommit 是否采用自动提交事务方式，默认是1，表示采用自动提交模式；如果指定为0，表示采用手动提交模式。

    • BatchInsertSize_Ext 批量DML扩展优化

      指定是否开启批量INSERT，UPDATE，DELETE扩展优化，默认值为0表示关闭。如果指定为1，则会开启批量DML扩展优化。该参数仅在V8.6.4 及以上版本的 KingbaseES 数据库上支持。

    • SSLMode SSL加密连接的方式

      指定SSL加密连接的模式。可配置值如下所示：

      d(disable:关闭，不关心安全，不想花费加密开销)

      a(allow:允许，不关心安全性，但如果服务器支持，则会花费加密开销)

      p(prefer:优先，不关心加密，但如果服务器支持，则花费加密开销)

      r(require:要求，希望数据是加密的并接受加密开销，默认当前网络将确保始终连接到想要连接的服务器)

      vc(verify-ca:验证CA，希望数据是加密的并接受加密开销，确保连接到受信任的服务器)

      vf(verify-full:全验证，希望数据是加密的并接受加密开销，确保连接到指定的受信任的服务器)

    • pqopt SSL加密连接相关的从属配置

      指定SSL加密连接相关的从属（证书路径）配置，所有的子配置项需要放在大括号"{}"中。子配置项有如下几个：

      sslrootcert：可信的证书机构

      sslcert：客户端证书

      sslkey：客户端私钥

      配置示例：pgopt={sslrootcert=/home/sslconf/root.crt sslcert=/home/sslconf/kingbase8.crt sslkey=/home/sslconf/kingbase8.key}

    • Protocol 语句级自动回滚配置项

      目前只能严格按照如下配置值进行配置，默认情况下不开启该配置：

      Protocol=7.4-0：不开启语句级自动回滚

      Protocol=7.4-2：开启语句级自动回滚

      该配置项需配合AutoCommit配置项使用，在AutoCommit=0时，可通过上述配置开启（取消）语句级自动回滚，在AutoCommit=1时，该配置无效； 当AutoCommit=0且不使用该配置项时，默认值等同于Protocol=7.4-0。

    • AutoCommitDDL 是否开启DDL语句自动提交事务，默认是0，表示不采用DDL语句自动提交模式；如果指定为1，表示采用DDL语句自动提交模式。该配置只在AutoCommit=0时有效。

    •