TrendDB数据库JAVA语言程序接口手册

TrendDB 实时数据库
JAVA 语言接口参考手册
2021年04月
目录
1、概述.......................................................................................................................... 4
2、服务连接维护和查询接口...................................................................................... 6
2.1、命名服务初始化........................................................................................... 6
2.2、服务枚举....................................................................................................... 7
2.3、建立服务连接............................................................................................... 7
2.4、关闭连接....................................................................................................... 8
2.5、查询连接状态............................................................................................... 9
2.6、测试服务连接状态....................................................................................... 9
3、标签配置信息维护和查询接口............................................................................ 10
3.1、创建标签..................................................................................................... 14
3.2、批量创建标签............................................................................................. 15
3.3、删除标签..................................................................................................... 16
3.4、修改标签配置............................................................................................. 17
3.5、批量更新标签配置..................................................................................... 17
3.6、标签更名..................................................................................................... 19
3.7、标签用户自定义属性维护和查询............................................................. 19
3.8、标签过滤与枚举......................................................................................... 22
3.9、获得标签配置信息..................................................................................... 24
4、数据提交接口........................................................................................................ 25
4.1、二进制数据写入......................................................................................... 25
4.2、单标签多数据批量提交............................................................................. 26
4.3、多标签单数据批量提交............................................................................. 28
4.4、清空服务连接缓存..................................................................................... 29
5、数据查询接口........................................................................................................ 30
5.1、历史数据存储范围查询............................................................................. 30
5.2、最近更新值查询......................................................................................... 31
5.3、历史数据定位查询..................................................................................... 31
5.4、历史原始数据查询..................................................................................... 33
5.5、历史采样数据查询..................................................................................... 34
5.6、极值统计查询............................................................................................. 36
5.7、历史断面查询............................................................................................. 37
5.8、二进制历史数据查询................................................................................. 38
5.9、历史统计查询接口..................................................................................... 39
5.10、变化次数统计接口................................................................................... 40
5.11、起止时刻差值查询接口 ........................................................................... 41
5.11、时间占比统计接口 ................................................................................... 42
5.12、批量历史定位查询................................................................................... 43
5.13、批量采样值查询....................................................................................... 44
5.14、批量极值查询........................................................................................... 44
5.15、批量统计值查询....................................................................................... 45
5.16、批量变化次数查询................................................................................... 45
5.17、批量时间占比查询................................................................................... 46
5.18、时间占比实时计算参数设定接口........................................................... 46
5.19、变化次数实时计算参数设定接口........................................................... 47
5.20、时间占比实时计算参数查询接口........................................................... 47
5.21、变化次数实时计算参数查询接口........................................................... 48
6、服务状态监测接口................................................................................................ 48
6.1、服务器性能监测接口................................................................................. 48
6.2、客户端连接枚举......................................................................................... 49
6.2、服务状态查询............................................................................................. 49
7、时间运算函数........................................................................................................ 50
8、标签脚本程序维护接口........................................................................................ 51
8.1、TrendDB 计算引擎 JS 函数 ....................................................................... 52
8.2、水及水蒸气物性计算 JS 函数 ................................................................... 55
8.3、WEB RestAPI 接口函数 ............................................................................ 57
8.4、日志接口函数............................................................................................. 57
8.5、复杂数学计算函数..................................................................................... 58
9、TrendDB 接口函数错误代码 ................................................................................ 58
TrendDB 实时数据库 JAVA 语言程序接口手册
1、概述
现代工业自动化领域（包括电力系统自动化）普遍存在着连续存储量测数
据的应用要求。过去通常采用关系数据库来存储和处理该类数据，但随着工业
自动化系统监测和控制对象的不断复杂化，自动化系统需要监测和控制的数据
越来越多，对数据采集精度和采集速度的要求也不断提高了；加之用户对历史
数据在系统设计、系统优化、企业经营决策、故障预诊断、故障过程记录以及
事后故障分析等方面价值的认识不断深入，用户对历史数据的访问便利性和访
问速度的要求也不断提高了，传统的关系数据库解决方案已经越来越不能满足
应用要求了。
TrendDB 实时数据库（也称为时序数据库）因其采用专门的数据结构，数
据存储和访问接口简单直接，同时还能针对时序历史数据的特点进行数据压缩
处理，能够显著减少存储空间的占用，因此在工业自动化领域（如电网、电厂、
化工、石油、钢铁、制药、IT 数据中心等等领域）得到了越来越广泛的应用。
TrendDB 实时数据库的核心部分由服务管理器（trenddb_manager）、数据处
理服务器（trenddb_server）、命名授权服务器（trenddb_licserv）和客户端数据
访问程序接口（trenddb_api）组成。其中，trenddb_manager 服务管理器用于管
理单个服务器上运行的多个 trenddb_server 数据处理服务，trenddb_server 数据
处理服务器和 trenddb_api 客户端访问接口是 TrendDB 实时数据库系统的核心，
完成对时序历史数据的压缩存储和查询功能；命名授权服务器则主要完成服务
名转换和 TrendDB 的授权控制功能。
TrendDB 的体系架构可以用下图来示意表示：
4
如上图所示，数据处理服务器（trenddb_server）在系统启动时，向命名授
权服务器（trenddb_licserv）注册其服务名称和服务地址（包括服务 IP 和端口
号）；客户端数据访问程序接口 trenddb_api 在访问数据处理服务器之前，先与
命名服务器建立连接，查询取得需要访问的 trenddb_server 的服务地址，然后与
trenddb_server 建立网络连接，开始进行数据提交和查询访问。由于客户端只需
要具有 trenddb_server 的逻辑服务名就可以进行数据提交和数据查询，因此，当
部署 trenddb_server 的服务器其物理地址发生变化时，客户端不受任何影响，从
而可以做到客户端应用与数据的物理位置完全无关，能显著增强客户端应用的
独立性和可维护性。
一个 trenddb_server 数据处理服务可以同时向最多两个 trenddb_licserv 命名
授权服务注册，可以实现命名授权服务的冗余备份以提高可靠性；同时，一个
命名授权服务可同时管理多个数据处理服务，在同一台物理服务器上可以同时
运行多个 trenddb_server 实例，在不增加物理服务器的情况下，可以保证整个系
统的性能和容量能够平滑升级。
为了便于应用系统的开发，TrendDB 提供了基于标准 JAVA 语言的程序开发
接口（TrendDB_API.jar），TrendDB_API.jar 是按照 JNI 规范调用 TrendDB 的 C
接口函数实现的，因此，在使用 TrendDB_API.jar 时，必须确保 trenddb_api 的
C 接口在 Java 程序的运行目录下，在 Windows 平台上，需确保 TrendDB 的系统
目录设置到环境变量 Path；在 UNIX 以及 LINUX 上，需确保 TrendDB/lib 设置
到环境变量 LD_LIBRARY_PATH 中，一般在 LINUX 上正确安装 TrendDB 即可。
按照接口功能，可以分为如下几类：
5
1、服务连接维护、查询接口
2、标签配置信息维护、查询接口
3、实时历史数据提交接口（写数据接口）
4、实时历史数据查询接口
5、命名服务器访问接口
6、数据处理服务器状态监测接口
7、标签脚本程序配置接口
本手册将逐一给出 TrendDB 程序开发接口函数的说明，在必要时给出示例
程序。
2、服务连接维护和查询接口
TrendDB 采用分布式的体系架构，客户端在与服务端通讯之前，必须先建
立与服务端之间的通讯连接，为了隔离客户端应用对服务端地址的敏感性，
TrendDB 引入了“命名服务”的概念，客户端只需要知道服务端的服务名称，客
户端通过命名服务将服务名称转换为服务地址（IP 地址和服务端口号），然后建
立与服务端的通讯连接，所有的接口函数功能必须通过一个建立好的通讯连接
来完成。
TrendDB 客户端通过一个用户指定的字符串来表示一个通讯连接，连接标
识符的典型格式为“id@server”，其中，id 部分表示客户端到一个服务的连接标
识，而 server 则表示该通讯连接所连接的数据处理服务（trenddb_server）的服
务名称。TrendDB 通讯连接标识符只需要在客户端应用进程内唯一标识即可，
不需要在数据处理服务器的服务范围内唯一标识。
2.1、命名服务初始化
TrendDB 客户端在访问服务端之前，必须先设置所使用的命名服务的服务
地址，接口函数如下：
void InitNameServers(String[] servers) throws DB_Exception;
6
使用 InitNameServers 最多可以为客户端设置 2 个命名服务的地址，
name_servers 是一个字符串数组，用来存储命名服务的服务地址，命名服务的
服务地址的格式为“IP:PORT”，例如“192.168.1.19:9000”。
当所设置服务地址有效，客户端能建立与命名服务之间的连接时，
InitNameServers 则成功，否则抛出异常。
示例程序如下：
String[] servers = {"127.0.0.1:9000"}; //数据库地址及端口
try {
API.InitNameServers (servers);
} catch (DB_Exception e) {
e.printStackTrace ();
}
2.2、服务枚举
在正确设置了命名服务地址之后，用户可以在客户端枚举得到在命名授权
服务（trenddb_licserv）注册的数据处理服务的服务名列表，接口函数如下：
String[] ListServers() throws DB_Exception;
如果调用成功，ListServers 返回 String 类型的数组，代表得到的服务名称
列表（ServiceName），如果调用失败，则抛出异常。
示例程序如下：
try {
String [] serviceName = API.ListServers ();
}
2.3、建立服务连接
int CreateConnection(String connection, boolean bFireWall, boolean bCacheEnabled, String

user, String passwd) throws DB_Exception;
其中，connection 是所要建立的连接的标识符，其格式为“id@server”，其中
id 为一个不包含‘@’字符的任意字符串，server 为所要连接服务的服务名称，连
接标识符在客户端应用进程内要唯一标识，同一个连接标识符可以在不同的进
7
程间复用。
bFireWall 是一个布尔量，如果在 TrendDB 客户端与服务端分别位于单向网
络隔离设备的两边，此参数必须设置为 TRUE，在其他情况下，设置为 FALSE。
bCacheEnabled 是一个布尔量，如果要求对所建立的连接做数据缓存和自动
重发处理，则需要将此参数设置为 TRUE，反之，设置 FALSE。
userName 是数据库登录用户名，password 是数据库登录密码。
连接创建成功，CreateConnection 返回值为连接 ID（为非负整数），否则返
回负整数，表示错误类型，同时抛出异常。
程序示例如下：
String connStr = "123@TrendDB"; //连接标识符
try {
int connId = API.CreateConnection(connStr, false, true,
"admin", "123456");
// TODO Auto-generated catch block
}
2.4、关闭连接
void CloseConnection(String connection) throws DB_Exception;

void CloseConnection(int connId) throws DB_Exception;
connection 或 connId 为要关闭的连接标识符。
关闭失败则抛出异常。
由于 TCP 连接通常会缓冲数据，为了保证不丢失客户端写入的数据，在客
户端程序退出之前，应该对每一个创建的连接都调用 CloseConnection 进行关闭，
以保证缓存在 TCP 协议栈中的数据全部都传送到服务端。
程序示例如下：
try {
API.CloseConnection(connStr);
}
8
2.5、查询连接状态
int GetConnectionStatus(String connection) throws DB_Exception;

int GetConnectionStatus(int connId) throws DB_Exception;
其中，connection 或 connId 是连接标识符。
如果连接正常，返回值为0，否则抛出异常。
GetConnectionStatus 只是返回 TrendDB 接口在客户端维护的连接状态，并
不是实际与服务器进行了通讯，所以 GetConnectionStatus 返回成功并不能说明
客户端与服务端之间的连接一定是正常的，如果要保证这一点，就需要使用
TestServer 函数。
try {
int status = API.GetConnectionStatus(connStr);
}
2.6、测试服务连接状态
int TestServer(String connection) throws DB_Exception;

int TestServer(int connId) throws DB_Exception;
connection 或 connId 是连接标识符。
如果连接正常，返回值为0，否则抛出异常。
TestServer 向服务端发送数据并得到应答才返回正常，否则报告错误，因此，
使用这个函数可以保证获得连接的真正连接状态，但其系统开销要比
GetConnectionStatus 大。
try {
int status = API.TestServer(connStr);
}
9
3、标签配置信息维护和查询接口
TrendDB 中标签的配置信息用如下的实体类来描述：
Class TagConfig
{
String name;
String addr;
String desc;
String unit;
int tagId;
float comDev, expDev, loloLim, hihiLim, lowLim, highLim;
int histDays, normalStatus;
short histDepth, limitTimeout, statusTimeout;
byte type;
byte alarmRule;
boolean mirror, archive, statistics,
byte precision;
boolean grpRD, grpWR, otherRD, otherWR;
};
其中，name 是标签的名称，最大长度为63个字符，标签的名称在同一个数
据处理服务上必须具有唯一性。
addr 是标签的地址，最大长度为63个字符，标签的地址在同一个数据处理
服务上必须具有唯一性。
TrendDB 采用2种标识符（Name 和 Address）来标识所存储的数据，每个标
识符最多可以由63个 ASCII 字符组成，在同一个数据处理服务上，这2种标识符
都必须具有唯一性，在不同的数据处理服务器上，数据标签标识符可以复用。
desc 表示标签的描述信息，最大长度为255个字符。
unit 表示标签的数值单位，最大长度为15个字符。
tagId 表示标签在服务器上的唯一标识整数，由系统自动生成，tagId 不会随
着标签的其他属性变化而变化。
comDev 表示对连续标签进行基于线性带宽算法有损压缩时所容许的误差值，
该误差值为容许误差的绝对值，经过线性带宽有损压缩后，TrendDB 可以保证
在同一时刻压缩后的值与压缩前的值之差绝对值小于 comDev。
expDev 表示对连续标签进行越限报警处理时，能够引起报警状态改变的最
小限值，其物理意义详细如下图所示。
10
loloLim, hihiLim, lowLim, highLim 分别是连续标签的“低低”、“高高”、“低”、

“高”报警限值，他们与 expDev 的关系如下图所示：
产生“越高限”报警
不解除“越高限”报警状态 highLim
expDev
解除“越高限”报警状态
histDays 表示标签需要保留历史数据的天数，当历史数据的时间跨度超出
设定天数时，TrendDB 会自动删除最早的历史数据，回收其占用的存储空间，
实现存储空间循环利用。
histDepth 是数值标签的历史数据缓存深度，TrendDB 是分组对数值标签的
历史数据进行无损压缩的，histDepth 就是这个分组中包含的历史数据个数。历
史数据缓存深度越大，数据中所包含的冗余信息就越丰富，无损压缩的压缩比
就越大，压缩后占用的存储空间也就越小；但是历史缓存深度越大，就需要更
多的物理内存为其缓存空间，当系统内存有限时，就要增加虚拟内存的内存交
换量，系统性能会显著降低。因此，在实际应用中要综合考虑压缩比和系统性
能之间的平衡、合理设置 histDepth 的值。
limitTimeout 表示标签处于越限报警状态下以秒为单位的时间限值，当某标
签处于越限报警状态的时间超过这个值，TrendDB 会进一步产生报警。
statusTimeout 表示标签处于状态异常报警状态下以秒为单位的时间限值，
当某标签处于状态异常报警状态的时间超过这个值，TrendDB 会进一步产生报
警。
normalStatus 表示标签的正常状态值，当标签的状态值不等于指定的值时，
TrendDB 会根据该标签的报警规则产生状态异常报警。
type 表示标签类型，有连续（ TAG_CONTINUOUS ）、离散
（TAG_DISCRETE）、二进制数据（TAG_BLOB）三种，TrendDB 对连续标签
的数据先采用有损压缩方式进行过滤压缩，然后在此基础上进行无损压缩；对
离散标签和二进制标签的数据则值进行无损压缩。
TrendDB 支持三种数据标签，分别是连续数据标签（TAG_CONTINUOUS）、
11
离散数据标签（TAG_DISCRETE）和二进制数据标签（TAG_BLOB）。
对于连续数据标签和离散数据标签，TrendDB 存储的历史数据由三部分组
成：时标（Timestamp）、值（Value）和质量标志（Status）。其中，时标由两个
4字节整数（hours 和 usecs）表示，其中 hours 表示的是当前时刻到公元元年的
小时数，usecs 则表示当前时刻到上一个整点时刻的微秒数，时标的表示精度为
1微妙，可以表达的时间范围则是从公元元年到公元后490，000年；数据值由单
精度浮点数（4字节）表示；质量标志由一个4字节整数表示。因此，一个完整
的数据标签事件点占用的存储空间大小为16字节。连续数据标签和离散数据标
签历史数据结构可以用下图表示：
时标，8字节数据值，4字节质量标志，4字节
离散数据标签对应工业控制领域中的变化不连续的量测量，例如设备运行
状态、控制系统设定值等等；连续数据标签则对应连续变化的量测量，如电压、
电流、压力、流量等物理上连续变化的数据。对于离散数据标签，TrendDB 对
其历史数据序列只进行无损压缩处理，在查询时也只返回所存储的原始值，不
进行插值处理；对于连续数据标签，TrendDB 根据用户所设置的有损压缩允许
误差（comDev），对其历史数据序列进行线性带宽压缩或者直线压缩，有损压
缩处理后的结果再经过无损压缩处理后存储在磁盘上。
二进制数据标签的历史数据由两部分组成，分别是时标（Timestamp）和二
进制数据内容，由下图所示：
时标，8字节二进制数据，最大96K 字节
在实际应用中，二进制数据标签可以用于存储事件信息，也可以用于具有
时序特征的设备配置参数，如电力系统中继电保护设备的定值等，这类数据的
特点是他们都随着时间而变化，具有时序特征，另一方面其变化频率不是很高
但数量很大，像保护定值一般一年只变化几次，但电网中运行的保护设备很多，
每个设备的定值平均至少有几十项，如果直接采用连续或者离散数据标签来表
示定值项，会占用大量的标签容量，造成一定的浪费，采用二进制数据标签来
存储这类数据，可以有效地避免这个问题。
12
在存储任何数据标签的历史数据之前，TrendDB 首先检查相应数据标签历
史数据的实际保留时间是否超过了用户的设定值，如果超过了设定值，
TrendDB 数据处理服务器首先删除该数据标签最早的历史数据，回收其占用的
磁盘空间，然后再将压缩数据存储到磁盘文件中，达到磁盘空间循环利用的目
的。TrendDB 的数据处理流程可以用下图来表示：
原始数据数值数据连续数据

有损压缩
二
进
制
数
据
无损压缩
数据存储
对于二进制数据，TrendDB 采用通用的 Huffman 压缩算法对其进行压缩，

其压缩比一般可以达到2～5：1，具体数值取决于二进制数据块的内容。
对于离散数据标签和连续数据标签，TrendDB 针对其数据类型和时序数据
本身的特点，采用改良的 Huffman 压缩算法对需要存储的数据进行无损压缩处
理，改良的内容包括：
将浮点数按照 IEEE-754的表示方法分解为符号位（1位）、指数位（7位）
和小数位（23位），对于小数位则进一步按照压缩存储精度要求将其截断，最后
将这三部分分别采用 Huffman 压缩算法进行压缩；
1、求取相邻事件点时标的差值，存储起始时标值，并对时标差值序列应用
Huffman 压缩算法进行压缩处理；
2、对质量位直接采用 Huffman 进行压缩处理
通过所述处理措施，在不降低压缩速度的情况下，数据压缩率平均可以提
高1～2倍。对于数值数据，TrendDB 的无损压缩比率一般可以达到2～5：1，具
体数值取决于缓存深度、质量位变化情况以及数值曲线变化情况。
13
对于连续数据标签，TrendDB 采用线性带宽压缩算法对其历史序列进行压
缩处理，通过设置合理的有损压缩精度，在满足工业应用精度要求的情况下，
对于一般的工业量测量变化过程，其有损压缩的压缩比率一般都可以达到8倍以
上，有损压缩的结果经过无损压缩处理后，对于连续数据标签 TrendDB 的综合
数据压缩比率可以达到25：1以上，相对于只有无损压缩或者有损压缩一种压缩
处理方法的数据库，TrendDB 在压缩比更高，更加节省存储空间。
mirror 表示是否需要将标签的数据同步到位于其他网络安全隔离区域的数
据处理服务器上。
archive 表示是否存储该标签的历史数据。
statistics 表示是否需要实时统计该标签的最大、最小值，当该标志位为
TRUE 时，TrendDB 会实时对该标签的数据进行最大、最小值统计，并将统计
结果存储在服务端，这种预先统计可以大大加快统计查询接口的查询效率。
precision 表示在存储标签的历史数据时所保留的数位精度，最大值为23，
最小值为1。当某标签的数据其数值有效位数要求不高时，对 precision 设置合理
的值，可以有效地提高无损压缩的压缩比。
grpRD， grpWR 分别表示与该标签的创建者属于同一用户组的用户是否有权
对该标签进行读写的权利。
otherRD， otherWR 分别表示与该标签的创建者不属于同一用户组的用户是否
有权对该标签进行读写的权利。
alarmRule 表示对该标签进行报警处理方法，Java 接口都设置为0。
3.1、创建标签
void AddTag(String connection, TagConfig config) throws DB_Exception;

void AddTag(int connId, TagConfig config) throws DB_Exception;
其中，connection 或 connId 为与服务端的连接标识符，tagConfig 为要创建
标签的配置信息类，其中除 tagId 有系统自动产生外，TagConfig 的所有成员都
是有效的。
标签创建不成功，则抛出异常。示例：
try {
TagConfig config = new TagConfig();
14
config.type = TagConfig.TAG_CONTINUOUS;
config.comDev = 0.01f;
config.histDepth = 300;
config.histDays = 36500;
config.precision = 23;
config.archive = true;
config.statistics = true;
config.grpRD = true;
config.grpWR = true;
config.mirror = false;
config.name = String.format("P%08d", i);
config.addr = String.format("A%08d", i);
config.desc = String.format("D%08d", i);
config.unit = "kA";
API.AddTag(connId, config);
}
3.2、批量创建标签
int[] AddTagList(String connection, TagConfig[] configs) throws

DB_Exception;
int[] AddTagList(int connId, TagConfig[] configs) throws DB_Exception;
其中，connection 或 connId 为连接标识符；tagConfigs 为批量标签的配置信息
数组， TagConfig[]为标签配置信息结构数组，最大长度为100；返回值为整型数
组，用于承载每一个标签的创建结果，0表示相应位置的标签创建成功，负整数
则表示相应位置的标签创建失败，其值表明失败原因。
如果 AddTagList 返回数组有效且长度大于0，则表示与服务端的通讯正常，
int[]中包含有效信息；否则抛出异常。示例：
try
{
for(int k = 1; k <= 400000; k+= 40)
{
TagConfig[] configList = new TagConfig[40];
for(int i = k; i < 40 + k; ++i)
{
configList[i - k] = config;
15
config.unit = "kA";
}
int[] retV = API.AddTagList(connId, configList);
for(int j = 0; j < retV.length; ++j)
{
System.out.println(j + ", ret code: " + retV[j]);
}
}
}
catch(DB_Exception ex)
{
System.out.println(ex.GetErrMsg() + ", error: " +
ex.errno);
}
3.3、删除标签
void DeleteTagByName(int connId, String name) throws DB_Exception;

void DeleteTagByAddr(int connId, String addr) throws DB_Exception;
void DeleteTagByID(int connId, int tagId) throws DB_Exception;
void DeleteTagByName(String connection, String name) throws DB_Exception;
void DeleteTagByAddr(String connection, String addr) throws DB_Exception;
void DeleteTagByID(String connection, int tagId) throws DB_Exception;
connection 或 connId 为通讯连接标识，name 为待标签的名称，addr 为待删除标签的地
址，tagId 则为待删除标签的唯一 ID。
DeleteTagByName 按标签名称删除标签，DeleteTagByAddr 则按标签地址删除
标签，DeleteTagByID 按数据标 ID 删除标签，成功则删除标签，不成功则抛出异

常。
在 TrendDB 中，删除一个标签，同时也意味着删除了这个标签的所有历史
数据。示例：
try {
int status = API.DeleteTagByName(connId, "TagName");
16
}
3.4、修改标签配置
void UpdateTagByID(String connection, TagConfig config) throws DB_Exception;

void UpdateTagByName(String connection, TagConfig config) throws DB_Exception;
void UpdateTagByID(int connId, TagConfig config) throws DB_Exception;
void UpdateTagByName(int connId, TagConfig config) throws DB_Exception;
connection 或 connId 为通讯连接标识符，tagConfig 为标签更新后的配置信
息， UpdateTagByName 按照 TagConfig 结构中的 name 来标识标签；UpdateTagByID
则按照 TagConfig 结构中的 tagId 来标识标签。修改标签配置接口不能改变标签
类型。
配置信息更新不成功则抛出异常。示例：
try {
config.unit = "kA";
API.UpdateTagByName(connId, config);
}
3.5、批量更新标签配置
int[] UpdateTagListByName(String connection, TagConfig[] configs) throws DB_Exception;

int[] UpdateTagListByName(int connId, TagConfig[] configs) throws DB_Exception;
17
其中，connection 或 connId 为连接标识符；configs 为批量标签配置信息数组，

最大长度为100。
返回值为整型数组，用于承载每一个标签的更新结果，0表示相应位置的标
签更新成功，负整数则表示相应位置的标签更新失败，其值表明失败原因。
如果 UpdateTagListByName 返回数组长度大于0，则表示与服务端的通讯正
常，结果包含有效信息；否则抛出异常。示例：
try
{
for(int k = 1; k <= 400000; k+= 40)
{
TagConfig[] configList = new TagConfig[40];
for(int i = k; i < 40 + k; ++i)
{
configList[i - k] = config;
config.unit = "kA";
}
int[] retV = API.UpdateTagListByName(connId, con-
figList);
for(int j = 0; j < retV.length; ++j)
{
System.out.println(j + ", ret code: " + retV[j]);
}
}
}
{
ex.errno);
}
18
3.6、标签更名
void RenameTag(String connection, String oldName, String newName) throws

DB_Exception;
void RenameTag(int connId, String oldName, String newName) throws DB_Exception;
connection 或 connId 为连接标识符，oldName 为标签的原来名称，newName
为标签的新名称。
更名失败则抛出异常。示例：
try {
API.RenameTag(connId, "oldName", "newName");
}
3.7、标签用户自定义属性维护和查询
AttrHandle GetTagAttrByName(String connection, String name) throws DB_Exception;

AttrHandle GetTagAttrByAddr(String connection, String addr) throws DB_Exception;
AttrHandle GetTagAttrByID(String connection, int tagId) throws DB_Exception;
AttrHandle GetTagAttrByName(int connId, String name) throws DB_Exception;
AttrHandle GetTagAttrByAddr(int connId, String addr) throws DB_Exception;
AttrHandle GetTagAttrByID(int connId, int tagId) throws DB_Exception;
void SetTagAttr(AttrHandle handle, String attrName, String attrVal) throws DB_Exception;
void DelTagAttr(AttrHandle handle, String attrName) throws DB_Exception;
void ClearTagAttr(AttrHandle handle) throws DB_Exception;
String GetTagAttr(AttrHandle handle, String attrName) throws DB_Exception;
int GetTagAttrCount(AttrHandle handle) throws DB_Exception;
String[] GetTagAttrAt(AttrHandle handle, int index) throws DB_Exception;
void CloseTagAttrHandle(AttrHandle handle) throws DB_Exception;
void SetTagAttrByName(String connection, String name, AttrHandle handle) throws
DB_Exception;
void SetTagAttrByAddr(String connection, String addr, AttrHandle handle) throws
DB_Exception;
void SetTagAttrByID(String connection, int tagId, AttrHandle handle) throws DB_Exception;
void SetTagAttrByName(int connId, String name, AttrHandle handle) throws DB_Exception;
void SetTagAttrByAddr(int connId, String addr, AttrHandle handle) throws DB_Exception;
19
void SetTagAttrByID(int connId, int tagId, AttrHandle handle) throws DB_Exception;

标签的用户自定义属性以“属性—值”对来表示，“属性”和“值”都以字符串的方式存储
和表示。创建、删除、修改、查询标签的用户自定义属性需要先获得一个自定义属性句柄，
这个句柄代表该标签的用户自定义属性集合，通过这个句柄进行的用户自定义属性的创建、
删除、修改等操作只是在客户端应用进程空间内有效，当需要对标签的用户自定义属性做
永久修改时，必须调用 SetTagAttrByName、SetTagAttrByAddr 或 SetTagAttrByID 将应用进程
空间内的信息传送到服务端，由服务端来集中存储；最后，当完成对用户自定义属性的创
建、删除、修改、查询操作后，必须调用 CloseTagAttrHandle 将所创建的属性句柄关闭，
否则会造成客户端应用进程的内存泄漏。
AttrHandle GetTagAttrByName(int connection, String name);
AttrHandle GetTagAttrByAddr(int connection, String addr);
AttrHandle GetTagAttrByID(int connection, int tagId);
用来在应用进程空间创建与指定标签关联的用户自定义属性句柄，
connection 或 connId 是连接标识符，name、addr 和 tagId 分别是标签的名称、
地址和 ID，handle 是一个传出参数，用来承载所创建的自定义属性句柄。成功
返回 AttrHandle 类，否则抛出异常。
void CloseTagAttrHandle(AttrHandle handle);
用来关闭使用上述两个函数创建的自定义属性句柄，handle 是待关闭的自
定义属性句柄。
void SetTagAttr(AttrHandle handle, String attrName, String attrVal);
用来创建或修改一个用户自定义属性， handle 是自定义属性句柄，
attrName 是属性名称，attrVal 是属性值，如果 handle 所指示的自定义属性集合
原来有 attrName 所表示的属性，那么该函数就进行修改操作；否则，该函数将
在 handle 所指示的属性集合内创建名称为 attrName 的自定义属性，并将其属性
值设置为 attrVal。不成功抛出异常。
void DelTagAttr(AttrHandle handle, String attrName);
void ClearTagAttr(AttrHandle handle);
用来删除某个指定的属性或者清除全部属性，handle 是自定义属性句柄，attrName 是
属性名称。函数执行失败抛出异常，表明失败原因。
String GetTagAttr(AttrHandle handle, String attrName);
用来获得某指定属性名称对应的属性值， handle 是自定义属性句柄，
attrName 是属性的名称。成功返回结果，否则抛出异常。需要注意的是，如果
成功返回，结果所指示的字符串其存储空间由 trenddb_api 管理，客户端应用不
20
需要负责将其释放，但是当用户将 handle 调用 CloseTagAttrHandle 关闭后，handle

所指示的内容将失效。
int GetTagAttrCount(AttrHandle handle);
String[] GetTagAttrAt(AttrHandle handle, int index);
这两个函数用来枚举 handle 所指示的自定义属性集合的全部“属性—值”，
GetTagAttrCount 用来获得“属性—值”对的个数，结果为 int 类型，GetTagAttrAt
用来获得指定位置的属性名和属性值，属性名为数组第一个元素，属性值为第
二个元素。
增加、修改标签自定义属性示例：
try {
AttrHandle attrHandle = API.GetTagAttrByName(connStr,
"tag");
API.SetTagAttr(attrHandle, "name", "value");
API.SetTagAttrByName(connStr, "tag", attrHandle);
API.CloseTagAttrHandle(attrHandle);
}
删除标签自定义属性示例：
try {
"tag");
API.DelTagAttr(attrHandle, "name");
}
清除标签自定义属性示例：
try {
"tag");
API.ClearTagAttr(attrHandle);
21
枚举标签自定义属性示例：
try {
"tag");
int cnt = API.GetTagAttrCount(attrHandle);
for(int i = 0; i < cnt; ++i)
{
String[] attrs = API.GetTagAttrAt(attrHandle, i);
System.out.println("attr: " + attrs[0] + ", value: "
+ attrs[1]);
}
}
查询标签自定义属性示例：
try {
"tag");
String val = API.GetTagAttr(attrHandle, "name");
System.out.println("attr: " + "name" + ", value: " +
val);
}
}
3.8、标签过滤与枚举
void SetTagFilter(String connection, String type, String value) throws DB_Exception;

int TagCount(String connection, ConfigPosition outPos) throws DB_Exception;
TagConfig[] ListTags(String connection, ConfigPosition inOutPos) throws DB_Exception;
void SetTagFilter(int connId, String type, String value) throws DB_Exception;
int TagCount(int connId, ConfigPosition outPos) throws DB_Exception;
TagConfig[] ListTags(int connId, ConfigPosition inOutPos) throws DB_Exception;
其中，connection 或 connId 是连接标识符，type 是过滤条件主语，value 是过滤条件谓
语，pos 是标签的位置指示器。
22
以上三个函数配合使用可以用来枚举 TrendDB 服务器上定义的符合过滤条

件的标签配置信息。
SetTagFilter 用于设置过滤条件，过滤条件用 type 和 value 来描述，type 的
取值可以是：“name”、“name-end”、“addr”、“addr-end”、“desc”、“desc-end”、
“unit”、“unit-end”，分别用来代表标签的 name（名称）、addr（地址）、desc
（描述）和 unit（单位）等属性的前缀和后缀，value 则用来表示这些属性的前
缀和后缀所包含的字符串，例如当 type 取值为“name”、value 取值为“P00003”
时，则符合该过滤条件的标签其 name 属性全部以“P00003”为开头；其他情
形以此类推。过滤接口只能对标签的一个属性同时设置过滤条件。过滤条件设
置成功，正在执行函数，否则抛出异常，表示失败原因。
TagCount 用于获得连接标识符所代表的数据处理服务器上所配置的标签的
总数，如果访问成功，函数返回标签的总数，pos 指向符合过滤条件的标签列表
的起端，否则抛出异常，表明失败原因。
ListTags 用来枚举获得标签的配置信息，pos 用于指定获得标签的起始位置，
从服务器获得的标签配置信息存放在 TagConfig 数组中，每次调用 ListTags 成功
后，pos 的值被相应进行更新以指向新的检索位置，程序示例如下：
try
{
ConfigPosition pos = new ConfigPosition();
API.SetTagFilter("name-end", "Power");
int count = API.TagCount(connId, pos);
List<Integer> names = new ArrayList<>();
for(int i = 0; i < count; ++i)
{
try
{
TagConfig[] tags = API.ListTags(connId, pos);
for(int j = 0; j < tags.length; ++j)
{
names.add(new Integer(tags[j].tagId));
}
}
{
break;
}
}
Integer[] tags = new Integer[names.size()];
tags = names.toArray(tags);
return tags;
}
catch(Exception ex)
{
23
3.9、获得标签配置信息
TagInfo GetTagInfoByName(String connection, String name, boolean bComplete) throws

DB_Exception;
TagInfo GetTagInfoByAddr(String connection, String addr, boolean bComplete) throws
DB_Exception;
TagInfo GetTagInfoByID(String connection, int tagId, boolean bComplete) throws
DB_Exception;
TagInfo GetTagInfoByName(int connId, String name, boolean bComplete) throws
DB_Exception;
TagInfo GetTagInfoByAddr(int connId, String addr, boolean bComplete) throws
DB_Exception;
TagInfo GetTagInfoByID(int connId, int tagId, boolean bComplete) throws DB_Exception;
connection 或 connId 是连接标识符，name 是标签的名称，addr 是标签的地
址，tagId 是标签 ID，TagInfo 的定义如下：
Class TagInfo
{
TagConfig config;
String owner;
String group;
DB_Time createTime, modifiedTime;
};
从上述定义可以看出，除了标签的基本配置信息之外，TagInfo还包含标签
的所属用户、所属用户组、创建时间、最后修改时间等信息。当需要获得所有
这些标签信息时，bComplete参数应当指定为TRUE，否则，指定为FALSE，函
数返回时，除config之外的所有项目的值无效。
获得标签信息成功，返回结果，否则抛出异常，表明失败原因。示例：
try {
TagInfo info = API.GetTagInfoByName(connStr);
}
24
4、数据提交接口
客户端与服务端建立通讯连接之后，即可以通过数据提交接口向服务端写
入数据。TrendDB 支持三种标签，即连续标签、离散标签、二进制标签，提供
了两类数据写入接口，一类是数值标签写入接口，用来写入连续数据和离散数
据；另外一类是二进制标签写入接口，用于写入二进制数据。
对于连续标签和离散标签，TrendDB 提供了两种写入方式，一种是单标签
多数据批量写入方式，另一种是多标签单数据批量写入方式。前者用于数据产
生速度快（如电力系统的广域测量系统 WAMS，一个标签一秒钟就需要写入
25～100个数据）或者数据补充追加的情形，而后者则用于在一般情形下对
TrendDB 写入数据。这两种数据提交接口既可以用于按时间顺序追加数据，也
可以按照需要插入和修改历史数据。
如果写入数据所使用的网络连接开放了客户端数据缓存功能，那么在写入
数据的过程中如果网络连接中断，客户端应用可以在网络中断期间继续提交数
据，客户端在通讯中断期间提交的数据会缓存在客户端机器磁盘上，当网络连
接恢复时，数据提交接口会将其缓存的数据发送到服务端，保证数据不丢失。
4.1、二进制数据写入
void SetBlobValueByName(String connection, String name, BlobValue value) throws

DB_Exception;
void SetBlobValueByAddr(String connection, String addr, BlobValue value) throws
DB_Exception;
void SetBlobValueByID(String connection, int tagId, BlobValue value) throws DB_Exception;
void SetBlobValueByName(int connId, String name, BlobValue value) throws DB_Exception;
void SetBlobValueByAddr(int connId, String addr, BlobValue value) throws DB_Exception;
void SetBlobValueByID(int connId, int tagId, BlobValue value) throws DB_Exception;
这三个函数分别用于按标签名称、地址和 ID 写入二进制数据。其中，
connection 或 connId 是连接标识符，name 是标签的名称，addr 是标签的地址，
tagId 是标签 ID，blob 是二进制标签数据值结构指针，其定义如下：
25
public class BlobValue

{
public DB_Time time;
public byte[] data;
}
TrendDB 所支持的二进制数据的最大长度为96kB。BLOB 标签用于一个
时刻对应一个二进制数据块的应用场景，对同一个标签，同一个时刻只能对应
一个二进制数据块。二进制数据块的内容由客户端应用程序定义。
数据写入失败抛出异常，表明失败原因。示例：
try {
BlobValue blob = new BlobValue();
blob.time = tNow;
String msg = "This is a test";
blob.data = msg.getBytes(Charset.forName("UTF-
8"));
API.SetBlobValueByName(connId, "blob", blob);
}
4.2、单标签多数据批量提交
void InsertBlockValueByName(String connection, String name, DB_Value[] values) throws

DB_Exception;
void InsertBlockValueByAddr(String connection, String addr, DB_Value[] values) throws
DB_Exception;
void InsertBlockValueByID(String connection, int tagId, DB_Value[] values) throws
DB_Exception;
void InsertBlockValueByName(int connId, String name, DB_Value[] values) throws
DB_Exception;
void InsertBlockValueByAddr(int connId, String addr, DB_Value[] values) throws
DB_Exception;
void InsertBlockValueByID(int connId, int tagId, DB_Value[] values) throws DB_Exception;
这三个函数分别用于按标签名称、地址和 ID 批量写入多个连续或离散数据。
其中，connection 或 connId 是连接标识符，name 是标签的名称，addr 是标签的
地址，tagId 是标签的 ID，values 是要提交的数值数组，TrendDB 可接收的数据
数组最大长度为200。
在使用单标签多数据批量提交接口写入数据时，应用端程序必须保证
26
values 数组中的数据值的时标是按照从过去到现在的顺序排列，否则可能会导
致中间某些乱序数据的丢失。
为了保证数据提交的效率，数据批量提交接口是以异步方式进行的，即如
果函数执行完成，则表明数据已成功发送或缓存，并不表明服务端已经成功处
理；如果抛出异常，则可能是参数不合理或者数据发送失败。因此，数据提交
接口不能用于检查标签是否在服务端存在等目的。示例：
try
{
DB_Time now = API.TimeNow();
for(int h = 0; h < 5000; ++h)
{
DB_Time begin = API.TimeNow();
System.out.println("BEGIN: " + h + ", " +
API.FormatTime(begin));
DB_Value[] values = new DB_Value[100];
for(int d = 0; d < 100; ++d)
{
API.TimeAdd(now, 1, 0);
values[d] = new DB_Value();
values[d].time = new DB_Time();
values[d].time.hours = now.hours;
values[d].time.usecs = now.usecs;
values[d].status = 3;
values[d].value = (float)Math.random();
}
for(int i = 1; i <= 400000; ++i)
{
String name = String.format("P%08d", i);
try
{
API.InsertBlockValueByName(connId, name, val-
ues);
}
{
System.out.println("internal exception: " +
ex.GetErrMsg());
}
}
DB_Time end = API.TimeNow();
System.out.println("END: " + API.FormatTime(end));
double duration = (end.hours - begin.hours)*3600.0 +
(end.usecs - begin.usecs)/1000.0/1000.0;
System.out.println("Duration: " + duration + ", rate:
" + 40*100/duration);
27
}
API.FlushConnectionBuffer(connId);
}
{
System.out.println(ex.GetErrMsg());
}
4.3、多标签单数据批量提交
void UpdateValueByName(String connection, String[] names, DB_Value[] values) throws

DB_Exception;
void UpdateValueByAddr(String connection, String[] addrs, DB_Value[] values) throws
DB_Exception;
void UpdateValueByID(String connection, int[] ids, DB_Value[] values) throws
DB_Exception;
void UpdateValueByName(int connId, String[] names, DB_Value[] values) throws
DB_Exception;
void UpdateValueByAddr(int connId, String[] addrs, DB_Value[] values) throws
DB_Exception;
void UpdateValueByID(int connId, int[] ids, DB_Value[] values) throws DB_Exception;
这三个函数分别用于按标签名称、地址和 ID 多标签单数据批量提交连续或离散数据。
其中，connection 或 connId 是连接标识符；names 是标签的名称数组，addrs 是标签的地址
数组，ids 是标签的编号数组，values 是标签的值数组， names 数组、addrs 数组、ids 数组
以及 values 数组的长度必须相等，其最大长度为为200。
为了保证数据提交的效率，数据批量提交接口是以异步方式进行的，即如
果函数执行完成，则表明数据已成功发送或缓存，并不表明服务端已经成功处
理；如果抛出异常，则可能是参数不合理或者数据发送失败。因此，数据提交
接口不能用于检查标签是否在服务端存在等目的。示例：
long tBegin = System.currentTimeMillis();
for(int i = 1; i < 5000000; ++i)
{
API.TimeAdd(tNow, 1, 0);
values[0].time = tNow;
values[0].value = (float)(100.0*(1.0 +
Math.sin(3.1415926/100.0*k++)));
try
{
API.UpdateValueByName(connId, names, values);
}
28
{
System.out.println("UpdateValueByName failed due to:
" + ex.GetErrMsg() + ", error: " + ex.errno);
}
}
long tDuration = System.currentTimeMillis() - tBegin;
System.out.println("5 millions tags: " + tDuration + " ms");
4.4、清空服务连接缓存
void FlushConnectionBuffer(String connection) throws DB_Exception;

void FlushConnectionBuffer(int connId) throws DB_Exception;
为了提高网络传输效率，利用 TrendDB API 的数据提交接口写入的数据并
没有立即发送到服务端，而是先缓存在客户端的内部发送缓存里，只有当发送
缓存溢出时才将缓存中的数据发送给服务端进行处理。所以，为了将客户端写
入数据及时发送到服务端，应用程序应该在集中调用数据提交接口的代码段后
及时调用 FlushConnectionBuffer 将发送缓存区内的数据发送到服务端。
下面给出了一个合理使用 FlushConnectionBuffer 函数的代码示例，其核心
思想是将 FlushBufferConnection 调用放置在 UpdateValue 的循环之外：
while (true) {
for (int i = 0; i < tagCount; i++) {
try {
API.UpdateValueByID(connId, ids, values);
e.printStackTrace();
}
}
try {
Thread.sleep(1000);
} catch (InterruptedException e) {
}
}
29
5、数据查询接口
TrendDB 的数据查询接口用于查询存储在 TrendDB 服务端的实时历史数据，

包括标签的历史数据存储范围查询、最近更新值查询、历史原始数据查询、历
史采样数据查询、历史统计值查询、历史断面查询和二进制历史数据查询等功
能。
5.1、历史数据存储范围查询
HistoryStatus QueryHistStatusByName(String connection, String name) throws

DB_Exception;
HistoryStatus QueryHistStatusByAddr(String connection, String addr) throws DB_Exception;
HistoryStatus QueryHistStatusByID(String connection, int tagId) throws DB_Exception;
HistoryStatus QueryHistStatusByName(int connId, String name) throws DB_Exception;
HistoryStatus QueryHistStatusByAddr(int connId, String addr) throws DB_Exception;
HistoryStatus QueryHistStatusByID(int connId, int tagId) throws DB_Exception;
以上三个函数分别用于按照标签名称、地址和 ID 查询历史数据存储范围。
其中，connection 或 connId 是连接标识符，name 是标签的名称，addr 是标签的
地址，用于承载标签历史数据的存储范围，其定义如下：
Class HistoryStatus
{
DB_Time start, end;
};
其中，start 和 end 分别用来表示标签历史数据存储的起始和终止时间。历

史数据存储单位查询接口对所有的标签类型都可以查询。
查询成功返回值，否则抛出异常，表明失败原因。示例：
HistoryStatus status = API.QueryHistStatusByName(connId,
tags[k]);
DB_Statistics stat = API.GetStatisticsByName(connId,
tags[k], status.start, status.end);
System.out.println(tags[k] + ": max: " + stat.max.value + ",
min: " + stat.min.value + ", avg: " + stat.avg + ", dev: " +
stat.dev + ", delta: " + stat.delta);
30
5.2、最近更新值查询
DB_Value[] GetLatestValueByName(String connection, String[] names) throws

DB_Exception;
DB_Value[] GetLatestValueByAddr(String connection, String[] addrs) throws DB_Exception;
DB_Value[] GetLatestValueByID(String connection, int[] ids) throws DB_Exception;
DB_Value[] GetLatestValueByName(int connId, String[] names) throws DB_Exception;
DB_Value[] GetLatestValueByAddr(int connId, String[] addrs) throws DB_Exception;
DB_Value[] GetLatestValueByID(int connId, int[] ids) throws DB_Exception;
以上两个函数分别用于按照标签名称、地址和 ID 批量获得数值标签的最近
更新值。其中，connection 或 connId 是连接标识符，names 是标签名称数组，
addrs 是标签地址数组，ids 是标签 ID 数组，names 数组、addrs 数组和 ids 数组
的最大长度为1000，即调用一次最多可以查询1000个标签的最近更新值。
如果正常返回结果，表示客户端与服务端通讯过程正常，DB_Value[]有可能
包含有所查询标签的最近更新值，可以通过判断 DB_Value 的 time 项是否有效
（为非 NULL）来判别返回值是否有效，如果某位置的 DB_Value 其 time 为无效
时标，则说明对应位置的标签名称或地址不存在或者没有数据；否则抛出异常，
表明失败原因。示例：
String[] sys_vars = {"system.cpu", "system.disk"};
DB_Value[] values = API.GetLatestValueByName(connId,
sys_vars);
System.out.println("CPU: " + values[0].value + ", DISK: " +
values[1].value);
5.3、历史数据定位查询
HistoryPosition QueryHistPositionByName(String connection, String name, HistoryPosition

pos) throws DB_Exception;
HistoryPosition QueryHistPositionByAddr(String connection, String addr, HistoryPosition
HistoryPosition QueryHistPositionByID(String connection, int tagId, HistoryPosition pos)
throws DB_Exception;
HistoryPosition QueryHistPositionByName(int connId, String name, HistoryPosition pos)
HistoryPosition QueryHistPositionByAddr(int connId, String addr, HistoryPosition pos)
31
HistoryPosition QueryHistPositionByID(int connId, int tagId, HistoryPosition pos) throws
DB_Exception;
以上三个函数分别用于按照标签名称、地址和 ID 定位历史数据在 TrendDB
数据库的位置。其中，connection 或 connId 是连接标识符，name 是标签的名称，
addr 是标签的地址，tagId 是标签的 ID，position 是历史数据位置指示结构，其
定义如下：
Class HistoryPosition
{
DB_Time start, end, current;
};
上述定义中 start、end、current 分别代表历史数据的起始、终止和当前时标
指示。对历史数据的任何查询，都要需要使用这三个函数定位其查询位置。在
调用函数前，用户首先用查询起点时间和终止时间设置 HistoryPosition 中的 start
和 end 成员，然后调用函数确定 HistoryPosition 的 current 成员。经查询函数确定
的查询位置，可以用于后面所介绍的历史数据查询函数。
查询定位成功，返回结果，否则抛出异常，表明失败原因。示例：
HistoryPosition historyPosition = new HistoryPosition();
HistoryPosition position = new HistoryPosition();
DB_Value[] dv = null;
List<DB_Value> list = new ArrayList<DB_Value>();
historyPosition = new HistoryPosition();
list.clear();
String tagName = “Demo000001”;
try{
HistoryStatus hs = API.QueryHistStatusByName(connId,
tagName);
position.start = hs.start;
position.end = hs.end;
historyPosition = API.QueryHistPositionByName(connId,
tempTagName, position);
}
while (true) {
dv = null;
try {
dv = API.RetrieveTrendByName(connId,
tagName,historyPosition);
for (int j = 0; j < dv.length; j++) {
list.add(dv[j]);
}
break;
}
if (dv == null)
32
break;
}
}
5.4、历史原始数据查询
DB_Value[] RetrieveTrendByName(String connection, String name,

HistoryPosition inOutPos) throws DB_Exception;
DB_Value[] RetrieveTrendByAddr(String connection, String addr,
HistoryPosition inOutPos) throws DB_Exception;
DB_Value[] RetrieveTrendByID(String connection, int tagId, HistoryPosition
inOutPos) throws DB_Exception;
DB_Value[] RetrieveTrendByName(int connId, String name, HistoryPosition
DB_Value[] RetrieveTrendByAddr(int connId, String addr, HistoryPosition
DB_Value[] RetrieveTrendByID(int connId, int tagId, HistoryPosition
历史原始数据查询接口用于查询指定标签在指定时间范围内数据库实际存
储的历史数据序列，对于连续标签而言，查询得到的数据是用户提交的数据经
过有损压缩处理后的结果；对于离散标签来说，其查询得到的结果就是用户所
提交的原始数据。其中，connection 或 connId 是连接标识符，name 是标签的名
称，addr 是标签的地址， tagId 是标签的 ID，position 是经过查询定位函数确认
的历史数据位置指示结构，DB_Values[]是返回结果，用于承载是查询获得的历
史数据序列。
查询成功，返回结果，同时将 position 结构中的 current 指向下一个有效的
历史数据位置；否则，抛出异常，说明失败原因。
在使用该函数，position 必须通过5.3方法获取，查询历史原始数据的示例
程序如下：
list.clear();
33
try{
tagName);
}
while (true) {
dv = null;
try {
dv = API.RetrieveTrendByName(connId,
tagName,historyPosition);
list.add(dv[j]);
}
break;
}
if (dv == null)
break;
}
}
5.5、历史采样数据查询
DB_Value[] RetrieveSamplesByName(String connection, String name, HistoryPosition

inOutPos, DB_Time period) throws DB_Exception;
DB_Value[] RetrieveSamplesByAddr(String connection, String addr, HistoryPosition
DB_Value[] RetrieveSamplesByID(String connection, int tagId, HistoryPosition inOutPos,
DB_Time period) throws DB_Exception;
DB_Value[] RetrieveSamplesByName(int connId, String name, HistoryPosition inOutPos,
DB_Value[] RetrieveSamplesByAddr(int connId, String addr, HistoryPosition inOutPos,
DB_Value[] RetrieveSamplesByID(int connId, int tagId, HistoryPosition inOutPos, DB_Time
period) throws DB_Exception;
历史采样数据擦和讯接口用于按照指定时间间隔采样的历史数据，对于连
续标签，历史采样数据是按照指定的时间间隔对原始历史数据进行线性插值计
算而得到的结果；对于离散标签，则按照阶梯形状对原始数据采样的结果，如
下图所示：
34
上图中，蓝色星标代表 TrendDB 所存储的原始数据，绿色星标代表的是连

续标签的采样值，而红色星标则代表离散标签的采样值。
历史采样数据查询接口的参数和返回值与原始数据查询接口的类似，此处
不再赘述，period 为采样间隔时间。示例：
DB_Time period = new DB_Time();
period.hours = 0;
period.usecs = 60*1000000;
list.clear();
try{
tagName);
}
while (true) {
dv = null;
try {
dv = API.RetrieveSamplesByName(connId,
tagName,historyPosition, period);
list.add(dv[j]);
}
break;
}
if (dv == null)
35
break;
}
}
5.6、极值统计查询
DB_Profile GetProfileByName(String connection, String name, DB_Time start, DB_Time

end) throws DB_Exception;
DB_Profile GetProfileByAddr(String connection, String addr, DB_Time start, DB_Time end)
DB_Profile GetProfileByID(String connection, int tagId, DB_Time start, DB_Time end)
DB_Profile GetProfileByName(int connId, String name, DB_Time start, DB_Time end)
DB_Profile GetProfileByAddr(int connId, String addr, DB_Time start, DB_Time end) throws
DB_Exception;
DB_Profile GetProfileByID(int connId, int tagId, DB_Time start, DB_Time end) throws
DB_Exception;
DB_Profile[] RetrieveProfilesByName(String connection, String name, HistoryPosition
DB_Profile[] RetrieveProfilesByAddr(String connection, String addr, HistoryPosition
DB_Profile[] RetrieveProfilesByID(String connection, int tagId, HistoryPosition inOutPos,
DB_Profile[] RetrieveProfilesByName(int connId, String name, HistoryPosition inOutPos,
DB_Profile[] RetrieveProfilesByAddr(int connId, String addr, HistoryPosition inOutPos,
DB_Profile[] RetrieveProfilesByID(int connId, int tagId, HistoryPosition inOutPos,
极值统计查询接口用于查询得到一个标签在指定的时间范围内最大、最小
值及其发生时间，GetProfileByName、GetProfileByAddr 和 GetProfileByID 用于
查询标签在单个时间范围内最大、最小值及其发生时间，而
RetrieveProfilesByName、RetrieveProfilesByAddr 和 RetrieveProfilesByID 则用于批量查询
按照指定时间间隔重复的多个时间范围内的最大、最小值及其发生时间。
DB_Profile 是标签极值信息数据结构，其定义如下:
Class DB_Profile
{
36
DB_Value min, max;

};
RetrieveProfiles 查询接口的参数和返回值与原始数据查询接口的类似，示
例如下：
period.hours = 0;
list.clear();
try{
tagName);
}
while (true) {
DB_Profile[] dv = null;
try {
dv = API.RetrieveProfilesByName(connId,
break;
}
if (dv == null)
break;
}
}
5.7、历史断面查询
DB_Value[] RetrieveSnapshotsByName(String connection, DB_Time start, String[] names)

DB_Value[] RetrieveSnapshotsByAddr(String connection, DB_Time start, String[] addrs)
DB_Value[] RetrieveSnapshotsByID(String connection, DB_Time start, int[] ids) throws
DB_Exception;
DB_Value[] RetrieveSnapshotsByName(int connId, DB_Time start, String[] names) throws
DB_Exception;
DB_Value[] RetrieveSnapshotsByAddr(int connId, DB_Time start, String[] addrs) throws
DB_Exception;
DB_Value[] RetrieveSnapshotsByID(int connId, DB_Time start, int[] ids) throws
37
DB_Exception;
历史断面查询函数用于批量查询多个标签在某一指定时刻的采样值。以上
函数分别用于按照标签名称、地址和 ID 查询历史断面数据。其中，connection
或 connId 是连接标识符，start 是指定的历史断面时刻，names 是标签名称数组，
addrs 是标签地址数组, ids 是标签 ID 数组，DB_Value[]是返回结果，用于存放返
回的各标签在指定时刻的采样值，如果某标签在指定时刻不存在采样值，则
DB_Value[]数组中相应位置的返回值其 time 成员为无效值（为 NULL）。
如果返回结果，表示客户端与服务端通讯过程正常，values 有可能包含有
所查询标签的最近更新值，可以通过判断 DB_Value 的 time 项是否有效（为
NULL）来判别返回值是否有效，如果某位置的 DB_Value 其 time 为无效时标，
则说明对应位置的标签名称或地址不存在或者没有数据；否则抛出异常，表明
失败原因。示例：
DB_Time tNow = API.TimeNow();
DB_Value[] values = API.RetrieveSnapshotsByName(connId, tNow,
sys_vars);
values[1].value);
5.8、二进制历史数据查询
BlobValue RetrieveBlobByName(String connection, String name, HistoryPosition inOutPos)

BlobValue RetrieveBlobByAddr(String connection, String addr, HistoryPosition inOutPos)
BlobValue RetrieveBlobByID(String connection, int tagId, HistoryPosition inOutPos) throws
DB_Exception;
BlobValue RetrieveBlobByName(int connId, String name, HistoryPosition inOutPos) throws
DB_Exception;
BlobValue RetrieveBlobByAddr(int connId, String addr, HistoryPosition inOutPos) throws
DB_Exception;
BlobValue RetrieveBlobByID(int connId, int tagId, HistoryPosition inOutPos) throws
DB_Exception;
以上函数分别用于按照标签名称、地址和 ID 查询二进制历史数据。其中，
38
connection 或 connId 是连接标识符，position 是指定的历史数据位置指示结构，

name 是标签名称，addr 是标签地址，tagId 是标签编号，BlobValue 是返回结果
用于存放返回的二进制数据值。
查询成功返回结果，否则抛出异常，表明失败原因。示例：
period.hours = 0;
list.clear();
try{
tagName);
}
while (true) {
BlobValue dv = null;
try {
dv = API.RetrieveBlobByName(connId,
break;
}
if (dv == null)
break;
}
}
5.9、历史统计查询接口
DB_Statistics GetStatisticsByName(String connection, String name, DB_Time start, DB_Time

DB_Statistics GetStatisticsByAddr(String connection, String addr, DB_Time start, DB_Time
DB_Statistics GetStatisticsByID(String connection, int tagId, DB_Time start, DB_Time end)
DB_Statistics GetStatisticsByName(int connId, String name, DB_Time start, DB_Time end)
DB_Statistics GetStatisticsByAddr(int connId, String addr, DB_Time start, DB_Time end)
39
DB_Statistics GetStatisticsByID(int connId, int tagId, DB_Time start, DB_Time end) throws
DB_Exception;
以上函数分别用于按照标签名称、地址和 ID 查询标签在指定时间范围内的
最大、最小、平均、标准差以及时间范围起始和终止时间的差值等统计指标。
其中，connection 或 connId 是连接标识符，start 是起始时间，end 是终止时间，
name 是标签名称，addr 是标签地址，tagId 是标签编号，DB_Statistics 是返回结
果结构，其定义为：
class DB_Statistics
{
public DB_Value min;
public DB_Value max;
public float avg;
public float dev;
public float delta;
}
其中，min 为最小值，max 为最大值，avg 为平均值，dev 为标准差，delta
为差值。示例：
tags[k]);
DB_Statistics stat = API.GetStatisticsByName(connId, tags[k],
status.start, status.end);
DB_Statistics stat1 = API.GetStatisticsByName(connStr, tags[k],
status.start, status.end);
System.out.println(tags[k] + ": max: " + stat.max.value + ",
min: " + stat.min.value + ", avg: " + stat.avg + ", dev: " +
stat.dev + ", delta: " + stat.delta);
System.out.println(tags[k] + ": max1: " + stat1.max.value + ",
min: " + stat1.min.value + ", avg: " + stat1.avg + ", dev: " +
stat1.dev + ", delta: " + stat1.delta);
5.10、变化次数统计接口
DB_ChangeCount GetChangeCountByName(String connection, String name, DB_Time start,

DB_Time end, float low, float high) throws DB_Exception;
DB_ChangeCount GetChangeCountByAddr(String connection, String name, DB_Time start,
DB_ChangeCount GetChangeCountByID(String connection, int tagId, DB_Time start,
DB_ChangeCount GetChangeCountByName(int connId, String name, DB_Time start,
DB_ChangeCount GetChangeCountByAddr(int connId, String name, DB_Time start,
40
DB_ChangeCount GetChangeCountByID(int connId, int tagId, DB_Time start, DB_Time

end, float low, float high) throws DB_Exception;
GetChangeCount 接口用于查询指定标签在指定时间范围内的值的变化次数，
即由小于 low 值变化到大于 high 值的上升次数 riseCount 和由大于 high 值变化
到小于 low 值的下降次数 downCount，返回接口为：
public class DB_ChangeCount
{
public long riseCount;
public long downCount;
}
程序示例：
String[] servers = new String[1];
servers[0] = "127.0.0.1:9000";
String connStr = "thr1@DB-1";
int connId = -1;
try
{
API.InitNameServers(servers);
connId = API.CreateConnection(connStr, false, false,
"admin", "123456");
"tag");
DB_ChangeCount cnt = API.GetChangeCountByName(connStr, "tag",
status.start, status.end, 0.1f, 0.9f);
System.out.println("tag" + ": change count: " +
cnt.toString());
}
{
ex.errno);
}
5.11、起止时刻差值查询接口
double[] RetrieveDifferencesByName(String connection, DB_Time start, DB_Time end,

String[] names) throws DB_Exception;
double[] RetrieveDifferencesByAddr(String connection, DB_Time start, DB_Time end,
String[] addrs) throws DB_Exception;
double[] RetrieveDifferencesByID(String connection, DB_Time start, DB_Time end, int[] ids)
double[] RetrieveDifferencesByName(int connId, DB_Time start, DB_Time end, String[]
names) throws DB_Exception;
double[] RetrieveDifferencesByAddr(int connId, DB_Time start, DB_Time end, String[]
addrs) throws DB_Exception;
double[] RetrieveDifferencesByID(int connId, DB_Time start, DB_Time end, int[] ids) throws
41
DB_Exception;
RetrieveDifferences 接口返回指定标签在指定终止和起始时刻的值的变化量，
起止时刻都必须是有效时间，否则抛出无数据异常。
程序示例：
servers[0] = "127.0.0.1:9000";
int connId = -1;
try
{
"admin", "123456");
"tag");
String[] parts = {"tag1", "tag2", "tag3"};
double[] diffs = API.RetrieveDifferencesByName(connStr,
status.start, status.end, parts);
double[] diff1s = API.RetrieveDifferencesByName(connId,
status.start, status.end, parts);
System.out.println(parts[0] + ": 0: " + diffs[0] + ", 1: "
+ diffs[1] + ", 2: " + diffs[2]);
System.out.println(parts[0] + ": 01: " + diff1s[0] + ", 11:
" + diff1s[1] + ", 21: " + diff1s[2]);
}
{
ex.errno);
}
catch(Exception ex)
{
System.out.println("" + ex);
}
5.11、时间占比统计接口
float[] RetrieveDutyRatioByName(String connection, String tag, DB_Time start, DB_Time

end, float[] levels) throws DB_Exception;
float[] RetrieveDutyRatioByAddr(String connection, String tag, DB_Time start, DB_Time
float[] RetrieveDutyRatioByID(String connection, int tagId, DB_Time start, DB_Time end,
float[] levels) throws DB_Exception;
float[] RetrieveDutyRatioByName(int connId, String tag, DB_Time start, DB_Time end,
float[] levels) throws DB_Exception;
float[] RetrieveDutyRatioByAddr(int connId, String tag, DB_Time start, DB_Time end, float[]
42
levels) throws DB_Exception;

float[] RetrieveDutyRatioByID(int connId, int tagId, DB_Time start, DB_Time end, float[]
RetrieveDutyRatio 接口返回指定标签在指定时间范围内的取值时间占比统计，
输入参数 levels 为取值占比统计的值范围，必须由小到大排序，例如可以指定
levels 为1、2、3，其返回值为长度为4的数组，其意义分别为统计标签 X 取值 x
< 1、1 =< x < 2、2 =< x < 3以及 x > 3的时间占比。也就是说，如果 levels 数组
的长度为 N，则返回数据的长队为 N+1，其取值为对应取值范围的时间占比。
levels 的最大长度为100。
示例：
servers[0] = "127.0.0.1:9000";
int connId = -1;
try
{
"admin", "123456");
"tag");
float[] levels = {30.0f, 60.0f};
float[] ratios = API.RetrieveDutyRatioByName(connStr, "tag",
status.start, status.end, levels);
System.out.println("tag" + ": 0: " + ratios[0] + ", 1: " +
ratios[1] + ", 2: " + ratios[2]);
}
{
ex.errno);
}
catch(Exception ex)
{
System.out.println("" + ex);
}
5.12、批量历史定位查询
HistoryPosition QueryGroupPositionByName(String connection, String[] names,

HistoryPosition pos) throws DB_Exception;
HistoryPosition QueryGroupPositionByAddr(String connection, String[] addrs,
HistoryPosition pos) throws DB_Exception;
HistoryPosition QueryGroupPositionByID(String connection, int[] ids, HistoryPosition pos)
43
HistoryPosition QueryGroupPositionByName(int connId, String[] names, HistoryPosition

HistoryPosition QueryGroupPositionByAddr(int connId, String[] addrs, HistoryPosition pos)
HistoryPosition QueryGroupPositionByID(int connId, int[] ids, HistoryPosition pos) throws
DB_Exception;
批量一次性查询定位多个标签的历史定位。查询成功返回标签的定位位置
对象，失败则抛出 DB_Exception 异常，表明失败原因。
5.13、批量采样值查询
DB_Value[][] RetrieveGroupSamplesByName(String connection, String[] names,

HistoryPosition inOutPos, DB_Time period) throws DB_Exception;
DB_Value[][] RetrieveGroupSamplesByAddr(String connection, String[] addrs,
HistoryPosition inOutPos, DB_Time period) throws DB_Exception;
DB_Value[][] RetrieveGroupSamplesByID(String connection, int[] ids, HistoryPosition
DB_Value[][] RetrieveGroupSamplesByName(int connId, String[] names, HistoryPosition
DB_Value[][] RetrieveGroupSamplesByAddr(int connId, String[] addrs, HistoryPosition
DB_Value[][] RetrieveGroupSamplesByID(int connId, int[] ids, HistoryPosition inOutPos,
用于批量查询多个标签的采样查询值，返回值为二维 DB_Value 数组，第一
维对应每个标签，第二维则对应时间轴，即第一维数组的维度与传入的 names、
addrs 或 ids 的维度一致；第二维则对应所对应的标签在时间轴上的数据取值。
查询成功返回数据数组，失败则抛出 DB_Exception 异常，表明失败原因。
5.14、批量极值查询
DB_Profile[] RetrieveGroupProfilesByName(String connection, String[] names, DB_Time

start, DB_Time end) throws DB_Exception;
DB_Profile[] RetrieveGroupProfilesByAddr(String connection, String[] addrs, DB_Time
DB_Profile[] RetrieveGroupProfilesByID(String connection, int[] ids, DB_Time start,
44
DB_Time end) throws DB_Exception;

DB_Profile[] RetrieveGroupProfilesByName(int connId, String[] names, DB_Time start,
DB_Profile[] RetrieveGroupProfilesByAddr(int connId, String[] addrs, DB_Time start,
DB_Profile[] RetrieveGroupProfilesByID(int connId, int[] ids, DB_Time start, DB_Time end)
用于批量查询多个标签值的最大、最小值及其发生时刻，如果某个标签的
极值为无效，则对应位置的返回值为 NULL。返回的 DB_Profile 数组每标签对
应一个元素。
5.15、批量统计值查询
DB_Statistics[] RetrieveGroupStatsByName(String connection, String[] names, DB_Time

DB_Statistics[] RetrieveGroupStatsByAddr(String connection, String[] addrs, DB_Time start,
DB_Statistics[] RetrieveGroupStatsByID(String connection, int[] ids, DB_Time start,
DB_Statistics[] RetrieveGroupStatsByName(int connId, String[] names, DB_Time start,
DB_Statistics[] RetrieveGroupStatsByAddr(int connId, String[] addrs, DB_Time start,
DB_Statistics[] RetrieveGroupStatsByID(int connId, int[] ids, DB_Time start, DB_Time end)
批量统计值查询接口用于批量查询多个标签在指定时间范围内的包括最大、
最小、平均、标准方差等统计值。返回的 DB_Statistics 数组每标签对应一个
元素。
5.16、批量变化次数查询
DB_ChangeCount[] RetrieveGroupChangeCountsByName(String connection, String[]

names, DB_Time start, DB_Time end, float low, float high) throws DB_Exception;
45
DB_ChangeCount[] RetrieveGroupChangeCountsByAddr(String connection, String[] addrs,

DB_Time start, DB_Time end, float low, float high) throws DB_Exception;
DB_ChangeCount[] RetrieveGroupChangeCountsByID(String connection, int[] ids,
DB_ChangeCount[] RetrieveGroupChangeCountsByName(int connId, String[] names,
DB_ChangeCount[] RetrieveGroupChangeCountsByAddr(int connId, String[] addrs,
DB_ChangeCount[] RetrieveGroupChangeCountsByID(int connId, int[] ids, DB_Time start,
批量变化次数查询接口用于批量查询多个标签在指定时间范围内的值变化
次数，变化次数的概念具体参考变化次数查询接口的说明。
5.17、批量时间占比查询
float[][] RetrieveGroupDutiesByName(String connection, String[] names, DB_Time start,

DB_Time end, float[] levels) throws DB_Exception;
float[][] RetrieveGroupDutiesByAddr(String connection, String[] addrs, DB_Time start,
DB_Time end, float[] levels) throws DB_Exception;
float[][] RetrieveGroupDutiesByID(String connection, int[] ids, DB_Time start, DB_Time
float[][] RetrieveGroupDutiesByName(int connId, String[] names, DB_Time start, DB_Time
float[][] RetrieveGroupDutiesByAddr(int connId, String[] addrs, DB_Time start, DB_Time
float[][] RetrieveGroupDutiesByID(int connId, int[] ids, DB_Time start, DB_Time end, float[]
批量时间占比查询接口用于批量查询多个标签在指定时间范围内的时间占
比，时间占比的概念具体参见时间占比查询接口的说明。
5.18、时间占比实时计算参数设定接口
void SetDutyParaByName(String connection, String tag, float[] levels) throws DB_Exception;

void SetDutyParaByAddr(String connection, String tag, float[] levels) throws DB_Exception;
46
void SetDutyParaByID(String connection, int tagId, float[] levels) throws DB_Exception;

void SetDutyParaByName(int connId, String tag, float[] levels) throws DB_Exception;
void SetDutyParaByAddr(int connId, String tag, float[] levels) throws DB_Exception;
void SetDutyParaByID(int connId, int tagId, float[] levels) throws DB_Exception;
接口参数说明请参见时间占比查询接口的说明。
查询成功返回 void，失败则抛出 DB_Exception 异常，表明失败原因。
如果所设置的标签原来没有设置时间占比自动计算参数或者原来设置的参
数与现在要设置的参数不一致，那么服务器会自动对所设置标签的历史数据进
行自动计算，使其时间占比的计算结果与所设置的参数相一致。
5.19、变化次数实时计算参数设定接口
void SetChangeCountParaByName(String connection, String tag, float low, float high)

void SetChangeCountParaByAddr(String connection, String tag, float low, float high) throws
DB_Exception;
void SetChangeCountParaByID(String connection, int tagId, float low, float high) throws
DB_Exception;
void SetChangeCountParaByName(int connId, String tag, float low, float high) throws
DB_Exception;
void SetChangeCountParaByAddr(int connId, String tag, float low, float high) throws
DB_Exception;
void SetChangeCountParaByID(int connId, int tagId, float low, float high) throws
DB_Exception;
接口参数说明请参见变化次数查询接口的说明。
查询成功返回 void，失败则抛出 DB_Exception 异常，表明失败原因。
如果所设置的标签原来没有设置变化次数自动计算参数或者原来设置的参
数与现在要设置的参数不一致，那么服务器会自动对所设置标签的历史数据进
行自动计算，使其变化次数的计算结果与所设置的参数相一致。
5.20、时间占比实时计算参数查询接口
float[] GetDutyParaByName(String connection, String tag) throws DB_Exception;

float[] GetDutyParaByAddr(String connection, String tag) throws DB_Exception;
float[] GetDutyParaByID(String connection, int tagId) throws DB_Exception;
47
float[] GetDutyParaByName(int connId, String tag) throws DB_Exception;

float[] GetDutyParaByAddr(int connId, String tag) throws DB_Exception;
float[] GetDutyParaByID(int connId, int tagId) throws DB_Exception;
查询获取指定标签的时间占比实时计算参数，如果标签的时间占比实时计
算参数没有指定，则返回值为 NULL。
5.21、变化次数实时计算参数查询接口
float[] GetChangeCountParaByName(int connId, String tag) throws DB_Exception;

float[] GetChangeCountParaByAddr(int connId, String tag) throws DB_Exception;
float[] GetChangeCountParaByID(int connId, int tagId) throws DB_Exception;
float[] GetChangeCountParaByName(String connection, String tag) throws DB_Exception;
float[] GetChangeCountParaByAddr(String connection, String tag) throws DB_Exception;
float[] GetChangeCountParaByID(String connection, int tagId) throws DB_Exception;
查询获取指定标签的变化次数实时计算参数，返回值为长度为2的浮点数数
组，第1个元素为 low，第2个元素为 high；如果标签的变化次数实时计算参数
没有指定，则返回值为 NULL。
6、服务状态监测接口
6.1、服务器性能监测接口
TrendDB 数据库服务自定义了2个标签，分别为 system.cpu 以及 system.disk，

这2个标签每10秒采集一次 TrendDB 服务器的 CPU 利用率和磁盘剩余空间大小，
应用程序可以使用通常的数据接口获取这2个标签的数据并作出适合的应用。
示例：
DB_Value[] values = API.GetLatestValueByName(connId, sys_vars);
values[1].value);
48
6.2、客户端连接枚举
ClientStatus[] ListClients(String connection) throws DB_Exception;

ClientStatus[] ListClients(int connId) throws DB_Exception;
用于获得当前连接到服务端的客户端的基本信息。其中，connection 或
connId 是连接标识符，最多可以返回500个客户端连接信息。
ClientStatus 的定义如下：
public class ClientStatus
{
public String address;
public String user;
public String command;
public double requests;
public double replies;
DB_Time start;
}
在上述定义中，address 表示客户端的地址，其格式为 IP:PORT，例如192.168.1.10：
9123，requests 是该客户端向服务器所发送的请求报文的总字节数，replies 是服务端向该客
户端发送应答报文的总字节数，start 则为该客户端建立连接的服务器时间，command 则是
该客户端应用进程的启动命令。
查询成功，返回结果，否则抛出异常，表明失败原因。示例：
ClientStatus[] clients = API.ListClients(connId);
for(k = 0; k < clients.length; ++k)
{
System.out.println("addr: " + clients[k].address + ", start:
" + clients[k].start);
}
6.2、服务状态查询
ServerStatus QueryServerStatus(String connection) throws DB_Exception;

ServerStatus QueryServerStatus(int connId) throws DB_Exception;
QueryServerStatus 返回 TrendDB 数据库的服务状态信息， ServerStatus 定义
如下：
public class ServerStatus
{
public DB_Time start;
public int tagCount, cleanStart;
public long rt;
public long arch;
public long insert;
public long dataSize;
public long indexSize;
49
}
其中，start 为 TrendDB 数据库服务的最近启动时间；tagCount 为当前的标
签数；cleanStart 表示最近一次启动是否为正常启动，如果取值为非0，则为正
常启动，如果为0，则表示 TrendDB 服务在最近一次启动之前产生过非正常关
闭；rt 为到目前为止 TrendDB 接收到的所有数据条目数；arch 为 TrendDB 已经
存储到磁盘上的数据条目数；insert 是 TrendDB 已经处理的非顺序写入的数据条
目数；dataSize 为 TrendDB 数据库所存储的数据占用的磁盘空间大小，单位为
字节；indexSize 为 TrendDB 数据索引的大小，单位为字节。示例：
ServerStatus servStat = API.QueryServerStatus(connId);
System.out.println("Started: " + serveStat.start + ", clean
start: " + servStat.cleanStart);
7、时间运算函数
TrendDB 提供的时间运算函数可以用于获得系统当前时间、时间格式化、
将指定时间转换为 TrendDB 时间格式、基于 TrendDB 时间格式的各种运算等。
时间运算函数有：
DB_Time TimeNow();
DB_Time SetTime(int year, int mon, int day, int hour, int min, int sec, int usec);
DB_TimeDetail MakeTime(DB_Time now);
String FormatTime( DB_Time now);

void TimeAdd(DB_Time t, int secs, int usecs);
void TimeSub(DB_Time t, int secs, int usecs);
void TimeAddDay(DB_Time t, int days);
void TimeAddHour(DB_Time t, int hours);
void TimeAddMinute(DB_Time t, int minutes);
void TimeAddSeconds(DB_Time t, int seconds);
DB_Time TimeAddExt(DB_Time time, int secs, int usecs);

DB_Time TimeSubExt(DB_Time time, int secs, int usecs);
DB_Time TimeAddDayExt(DB_Time time, int days);
DB_Time TimeAddHourExt(DB_Time time, int hours);
DB_Time TimeAddMinuteExt(DB_Time time, int minutes);
50
DB_Time TimeAddSecondsExt(DB_Time time, int seconds);

其中，TimeNow 用于获得系统当前时间，SetTime 则用于将指定时刻转换为
TrendDB 时间格式，FormatTime 则用于将指定时间以字符串的格式表示，其余
的函数是时间加减法运算。
8、标签脚本程序维护接口
TrendDB 用于设置和查询标签脚本程序的接口有：
void SetTagScriptByName(String connection, String name, byte[] script, int cycle) throws
DB_Exception;
void SetTagScriptByAddr(String connection, String addr, byte[] script, int cycle) throws
DB_Exception;
void SetTagScriptByID(String connection, int tagId, byte[] script, int cycle) throws
DB_Exception;
void SetTagScriptByName(int connId, String name, byte[] script, int cycle) throws
DB_Exception;
void SetTagScriptByAddr(int connId, String addr, byte[] script, int cycle) throws
DB_Exception;
void SetTagScriptByID(int connId, int tagId, byte[] script, int cycle) throws DB_Exception;
TagScript GetTagScriptByName(String connection, String name) throws DB_Exception;
TagScript GetTagScriptByAddr(String connection, String addr) throws DB_Exception;
TagScript GetTagScriptByID(String connection, int tagId) throws DB_Exception;
TagScript GetTagScriptByName(int connId, String name) throws DB_Exception;
TagScript GetTagScriptByAddr(int connId, String addr) throws DB_Exception;
TagScript GetTagScriptByID(int connId, int tagId) throws DB_Exception; void
SetLibraryScript(String connection, byte[] script) throws DB_Exception;
byte[] GetLibraryScript(String connection) throws DB_Exception;
void SetLibraryScript(int connId, byte[] script) throws DB_Exception;
byte[] GetLibraryScript(int connId) throws DB_Exception;
其中，SetTagScriptByName、SetTagScriptByAddr 和 SetTagScriptByID 分
别用于以名称、地址和 ID 来设置标签的脚本程序；SetLibraryScript 则用于
设置全局可见的脚本函数库；GetTagScriptByName、GetTagScriptByAddr 和
GetTagScriptByID 则分别用来以名称、地址和 ID 来获取标签的脚本程序；
51
而 GetLibraryScript 则用来获取全局可见的脚本函数库。
其中，connection 或 connId 是连接标识符，script 是脚本程序数据体（以
UTF-8编码表示），cycle 则用来表示脚本执行的周期，以秒为单位。
表示脚本程序 TagScript 定义如下：
public class TagScript
{
public byte[] data;
public int cycle;
}
其中，data 表示脚本程序体（以 UTF-8编码），TrendDB 中单个标签最大支
持的脚本程序长度为96kB；cycle 表示脚本执行周期。
如果在调用 SetTagScriptByName、SetTagScriptByAddr 或者 SetLibraryScript
时，指定的参数 script 为 NULL，其实际效果是将标签脚本程序或者脚本函数库
删除。
8.1、TrendDB 计算引擎 JS 函数
在脚本程序中，除了 Javascript 提供的基本函数和数据结构之外，TrendDB

还提供了以下数据结构和函数供用户使用：
Javascript 对象：
DBValue 表示 TrendDB 的一个量测值，有3个属性：
1、time，是一个 Date 对象，表示 DBValue 的时标分量；
2、value，是一个 Float 对象，表示 DBValue 的值分量；

3、status，是一个 Integer 对象，表示 DBValue 的质量位分量；
DBStatistics 表示 TrendDB 的标签的统计量，有4个属性：
1、min，是一个 DBValue 对象，表示标签最小值及其出现的时间；
2、max，是一个 DBValue 对象，表示标签最大值及其出现的时间；
3、avg，是一个浮点数，表示标签平均值；
4、dev，是一个浮点数，表示标签标准差；
5、delta，是一个浮点数，表示标签起止时间时刻取值的差值；
DBConnection 表示 TrendDB 运算模块访问 TrendDB 服务资源时需要的服务

连接，用户应采用以下所示的形式建立服务连接：
52
var dbConn = new DBConnection(“server”);

server 为脚本引擎要连接到的 TrendDB 服务名称。
DBConnection 对象的属性：
1、server，String 类型属性，返回服务连接所对应的服务名；
2、connected，Boolean 类型属性，用来测试此服务连接是否处于连接状态，
其功能相当于函数 TestServer，引用该属性会确认发送消息到服务器测试服
务器是否连接；
3、alive，Boolean 类型属性，用来测试此服务连接是否处于可用状态，其
功能相当于函数 GetConnectionStatus，引用该属性不会发送消息到服务
器，仅仅返回客户端所维护的连接状态；
DBConnection 对象的成员函数：
1、close，成员函数，用于关闭服务连接，关闭后服务连接处于不可用状态，
其调用形式为：dbConn.close();
2、getLatestValue，成员函数，用于获得指定标签的最近更新值，返回值为
DBValue 对象，其调用形式为：var dbVal = dbConn.getLatestValue(“tagName”)；
该成员函数的实际效果与在 C 语言中调用 GetLatestValueByName 一致；
3、updateValue，成员函数，用于更新指定标签的实时或历史数值，其调用
形式为：dbConn.updateValue(“tagName”, dbVal);该成员函数的实际运行效果与
在 C 语言中调用 UpdateValueByName 一致；
4、updateBlob，成员函数，用于插入或修改指定二进制标签的 BLOB 数据，
其调用形式为：dbConn.updateValue(“tagName”, dbTime, blobJson);该函数的调用
效果与 C 语言中调用 SetBlobValueByName 一致；
5、queryStatus，成员函数，用于查询指定标签的历史数据时间范围，返回
值为一个长度为2的 Date 对象数组，第1个 Date 对象表示指定标签历史数据的
起始时间，第2个 Date 对象表示历史数据的终止时间，其调用形式为：var
histArray = dbConn.queryStatus(“tagName”); 该成员函数的实际运行效果与 JAVA
语言中 QueryHistStatusByName 一致；
6、querySamples，成员函数，用于查询获得指定标签在指定时间范围内按
照指定时间间隔进行线性插值而得到的值序列，返回值为一个以 DBValue 对象
为元素的数组，其调用形式为：var valArray = dbConn.querySamples(“tagName”,
53
startTime, endTime, interval);其中，startTime 和 endTime 都是 Date 对象，分别表

示查询起始时间和终止时间，interval 为浮点数，表示以秒为单位的时间间隔；
由于网络通讯和系统内存的限制，QuerySamples 一次返回的插值个数有一个最
大值限制，因此当需要查询返回的插值个数超过 QuerySamples 一次能返回的最
大个数时，需要脚本程序采用不同的起始和终止时间对 QuerySamples 进行多次
调用；该成员函数的实际运行效果与 JAVA 语言接口中的
RetrieveSamplesByName 一致；
7、querySnapshot，成员函数，用于查询获得指定标签在指定时刻的历史断
面值，返回值为 DBValue 对象，其调用形式为 :var dbVal =
dbConn.querySnapshot(“tagName”, snapTime);该函数的实际运行效果与 JAVA 语
言接口中的 RetrieveSnapshotsByName 一致；
8、queryType，成员函数，用于查询指定标签的标签类型，返回值为 String，
当标签类型为 BLOB 时，返回值为“BLOB”，当标签类型为连续性标签时，返
回值为“CONTINUOUS”，当标签类型是离散型标签时，返回值为“DISCRETE”，
其他情况返回值为 “UNKNOWN” ；其调用形式为： var tagType =
dbConn.queryType(“tagName”);该成员函数的实际运行效果与 JAVA 语言接口中
GetTagInfoByName 一致；
9、queryAttribute，成员函数，用于查询获得指定标签的指定用户自定义属
性值，返回值为 String ，其调用形式为： var attrVal =
dbConn.queryAttribute(“tagName”, “attrName”);
10、getAttributeCount，成员函数，用于获得指定标签的用户自定义属性数
目，返回值为 Integer ，其调用形式为： var attrCnt =
dbConn.getAttributeCount(“tagName”);
11、getAttributeAt，成员函数，用于获得指定标签位于指定索引位置的用户
自定义属性的名称和值，返回值为一个长度为2的 String 数组，第1个 String 为
属性名称，第 2个 String 为对应的属性值，其调用形式为： var attrArray =
dbConn.getAttributeAt(“tagName”, attrIndex);
12、calculateStatistics，成员函数，用于获得指定标签在指定时间范围内的
最大、最小、平均值、标准差等统计值，该平均值是采用积分法计算得到的，
返回值为 DBStatistics 对象，其调用形式为：var stat = dbConn.calculateStatistics
54
(“tagName”, startTime, endTime);其中，startTime 和 endTime 分别代表计算平均

值的起始和终止时间；
值得注意的是，在调用以上 TrendDB 提供的 Javascript 函数和对象时，如果
发生错误情况，错误信息是以 Javascript 异常的方式反馈给脚本程序的，因此，
在编写计算脚本时，需要注意异常情况下的异常处理。
TrendDB 脚本计算模块在对每一个标签进行脚本计算处理时，会查找一个
名称为 Process 的函数，然后按照用户指定的计算间隔周期调用 Process 函数完
成计算功能，因此，在编写脚本计算功能时，需要注意将需要周期进行计算的
部分实现在 Process 函数当中。Process 的函数原型为：
function Process(tagName)
{
}
上述函数说明中的 tagName 参数在脚本处理模块调用 Process 函数时指定为
该 Process 函数计算功能所对应的标签名称，这样在 Process 函数体内的程序语
句就可以直接引用该标签名来对该标签进行各种需要的操作。下面是一个完整
的标签脚本计算程序示例，该程序的功能是计算得到指定标签的前一整点的平
均值，并将得到的平均值存储到与指定标签相关的标签上：
var dbConn = new DBConnection("DB-1");
function Process(tagName)
{
var tStart = new Date;
var tEnd = new Date;
tEnd.setMinutes(0, 0, 0);
tStart.setTime(tEnd.getTime() - 3600 * 1000);
var dbVal = new DBValue;
dbVal.value = dbConn.calculateStatistics(tagName, tStart, tEnd).avg;
dbVal.time = tEnd;
dbVal.status = 0;
dbConn.updateValue(tagName + ".avg", dbVal);
}
8.2、水及水蒸气物性计算 JS 函数
脚本计算引擎提供了 IF97水及水蒸气物性函数模块，用于计算水及水蒸气
的密度、焓、熵值及其逆运算，其具体函数如下：
1、rhomass_Tp，根据温度（T【K】）和压力（p【Pa】）计算水或水蒸
55
气的密度（【kg/m3】），调用格式为 rho = IF97. rhomass_Tp(T,p)；
2、 hmass_Tp ，根据温度（T【K】）和压力（p【Pa】）计算水或水蒸气
的单位质量焓值（【J/kg】），调用格式为 h = IF97. hmass_Tp(T,p)；
3、 smass_Tp，根据温度（T【K】）和压力（p【Pa】）计算水或水蒸气
的单位质量熵值（【J/kg/K】），调用格式为 s = IF97. smass_Tp(T,p)；
4、 umass_Tp ，根据温度（T【K】）和压力（p【Pa】）计算水或水蒸气
的单位质量内能（【J/kg】），调用格式为 h = IF97. umass_Tp(T,p)；
5、cpmass_Tp，根据温度（T【K】）和压力（p【Pa】）计算水或水蒸气
的单位质量定压比热（【J/kg/K】），调用格式为 h = IF97. cpmass_Tp(T,p)；
6、cvmass_Tp，根据温度（T【K】）和压力（p【Pa】）计算水或水蒸气
的单位质量定容比热（【J/kg/K】），调用格式为 h = IF97. cvmass_Tp(T,p)；
7、T_phmass，根据压力（p【Pa】）和单位质量焓值（h【J/kg】）计算水
或水蒸气的温度（【K】），调用格式为 T = IF97. T_phmass(p,h)；
8 、 rhomass_phmass ，根据压力（ p 【 Pa 】）和单位质量焓值（ h
【 J/kg 】）计算水或水蒸气的密度（【 kg/m3 】），调用格式为 T = IF97.

rhomass_phmass(p,h)；
9、T_psmass，根据压力（p【Pa】）和单位质量熵值（s【J/kg/K】）计算
水或水蒸气的温度（【T】），调用格式为 T = IF97. T_psmass(p,s)；
10 、 rhomass_psmass ，根据压力（ p 【 Pa 】）和单位质量熵值（ h
【 J/kg/K 】）计算水或水蒸气的密度（【 kg/m3 】），调用格式为 T = IF97.

rhomass_psmass(p,s)；
11、 p_hsmass ，根据单位质量焓值（h【J/kg】）和单位质量熵值（ s
【 J/kg/K 】）计算水或水蒸气的压力（【 Pa 】），调用格式为 p = IF97.

p_hsmass(h,s)；
12、 T_hsmass ，根据单位质量焓值（h【J/kg】）和单位质量熵值（ s
【 J/kg/K 】）计算水或水蒸气的温度（【 K 】），调用格式为 p = IF97.

T_hsmass(h,s)；
13、 region_ph ，根据温度（T【K】）和压力（p【Pa】）计算水或水蒸
气的所处的区域编号，调用格式为 q = IF97. region_ph(p,h)；
56
14、 region_ps ，根据压力（p【Pa】）和单位质量熵值（h【J/kg/K】）
计算水或水蒸气的水或水蒸气的所处的区域编号，调用格式为 q = IF97.
region_ps(p,s)；
8.3、WEB RestAPI 接口函数
脚本计算引擎提供了 WEB REST 调用接口，用于在脚本计算中从 REST 服

务获得数据或者向 REST 服务写入数据，其具体函数如下：
1、get，用于从一个 REST get 服务获取数据，具体调用形式为 var data =
REST.get(uri)，其中 uri 为具体的 get 服务标识；返回值 data 是 JSON 格式的对
象；
2、post，用于从一个 REST post 服务获取数据，具体调用形式为 var data =
REST.post(uri, json)，其中 uri 为具体的 post 服务标识，json 为可以转化为 JSON
数据格式的 JS 对象；返回值 data 是 JSON 格式的对象；
3、put，用于对一个 REST put 服务写入数据，具体调用形式为 var data =
REST.put(uri, json)，其中 uri 为具体的 post 服务标识，json 为可以转化为 JSON
数据格式的 JS 对象；
4、delete，用于对一个 REST delete 服务操作数据，具体调用形式为 var data
= REST.delete(uri)，其中 uri 为具体的 delete 服务标识。
8.4、日志接口函数
脚本计算引擎提供了 LOG 日志对象，用于在用于在脚本计算引擎日志文件

中写入一条日志信息，记录计算结果或者提示错误，其具体函数如下：
1、debug，输出调试级别的日志信息，其调用形式为 LOG.debug (arg1,
arg2,...)；其中 arg1、arg2等为可以转化为字符串的对象或值；
2、info，输出通知级别的日志信息，其调用形式为 LOG.info (arg1, arg2,...)；
其中 arg1、arg2等为可以转化为字符串的对象或值；
3 、 warn ，输出警告级别的日志信息，其调用形式为 LOG.warn (arg1,
57
4、error，输出一般错误级别的日志信息，其调用形式为 LOG.error (arg1,

5、fatal，输出严重错误级别的日志信息，其调用形式为 LOG.fatal (arg1,
8.5、复杂数学计算函数
脚本计算引擎集成了 MathJS 公式解析与计算模块的功能，可以支持大整数、

分数、复数、矩阵、单位转换等运算，具体使用方法请参见 http://mathjs.org/。
9、TrendDB 接口函数错误代码
TrendDB 的所有 Java 接口函数在发生错误时会抛出一个 DB_Exception 的异

常对象，DB_Exception 的定义如下：
public class DB_Exception extends Exception
{
public int errno;
public String GetErrMsg();
public String toString()
{
return GetErrMsg();
}
}
其中，errno 为引起错误的错误号，是一个负整数，GetErrMsg 成员函数则
返回错误号所代表的含义字符串。
TrendDB 的错误代码、代号及其含义如下表所示：
值代号含义
0 ERROR_OK 正常
-1 ERROR_CVT_OPEN 打开当前值表的时候发生错误
-2 ERROR_CVT_MAP 对当前值表进行映射操作时发
生错误
-3 ERROR_INVALID_ITEM 无效的标签项
58
-4 ERROR_NAME_EXIST 标签名称已经被占用
-5 ERROR_POINT_FULL 系统标签分配空间已满，无法
继续添加标签
-6 ERROR_POINT_MEM 内存或者磁盘空间不足，无法
继续添加标签
-7 ERROR_POINT_NONE 无法定位给定的标签定义
-8 ERROR_ITER_NONE 无效的标签迭代器
-9 ERROR_ITER_EMPTY 返回空的标签迭代器
-10 ERROR_ITER_END 已经到达标签迭代器的结尾
-11 ERROR_BTREE_NULL 检测到无效的标签历史数据索
引指针
-12 ERROR_BTREE_NOITEM 标签历史数据索引指针为空
-13 ERROR_DATA_NULL 在指定时间范围内没有历史数
据
-14 ERROR_INDEX_ALLOC 没有足够的内存或者磁盘空间
创建数据索引
-15 ERROR_DATA_ALLOC 没有足够的内存或者磁盘空间
存储数据
-16 ERROR_EMPTY_VALUE 标签当前值表为空
-17 ERROR_DATA_SPIT 标签数据存储分裂时检测到错
误
-18 ERROR_HIST_NONE 在指定的时间范围内没有历史
数据
-19 ERROR_HIST_END 指定时间范围内没有更多的历
史数据
-20 ERROR_NO_VALUE 标签没有实时数据
-21 ERROR_INVALID_CACHE 无效的高速缓存指针
-22 ERROR_BTREE_INVALID 无效的索引指针
-23 ERROR_CACHE_OPEN 打开高速缓存模块时遇到错误
59
-24 ERROR_PACKET_SEQ 无效的网络报文序号

-25 ERROR_PACKET_NULL 网络报文指针为空
-26 ERROR_MAP_INVALID 网络报文映射错误
-27 ERROR_CONNECT_ERROR 建立网络连接时发生错误
-28 ERROR_SEND_ERROR 发送网络报文时发生错误
-29 ERROR_RECV_ERROR 接收网络报文时发生错误
-30 ERROR_PACKET_ERROR 网络报文格式错误
-31 ERROR_BUFFER_ERROR 网络缓存错误
-32 ERROR_CONNECTION_NONE 网络连接不存在
-33 ERROR_CONNECTION_DISCONNECTED 网络连接处于断开状态
-34 ERROR_WAIT_QUEUE 网络连接处于发送缓存数据状

态，本次请求被缓存或忽略
-35 ERROR_CACHE_EMPTY 网络缓存为空
-36 ERROR_NAMESERVER_NONE 没有指定命名服务的地址
-37 ERROR_NAMESERVER_CONNECT 连接到命名服务时发生错误
-38 ERROR_CONNECTION_EXIST 网络连接已存在
-39 ERROR_INVALID_PARA 无效的接口调用参数
-40 ERROR_REPLY_BLOCKED 服务应答被物理隔离装置阻塞
-41 ERROR_POINT_EXCEED 标签书超过了授权许可的数目
-42 ERROR_LICENSE_RESTRICTED 没有有效的使用授权
-43 ERROR_SERVER_NONE 没有指定的数据服务
-44 ERROR_SERVER_EXIST 数据服务已经存在
-45 ERROR_SERVER_RESOLVE 解析服务命名时发生错误
-46 ERROR_CONNECTION_FORMAT 网络连接标识格式不对
-47 ERROR_SERVER_NETWORK 服务器没有正确或配置安装网
络模块
-48 ERROR_SYSTEM_LIMIT 标签数超过了系统物理限值
-49 ERROR_ARCHIVE_NONE 没有历史数据
-50 ERROR_SECURITY_FAILURE 读取安全配置数据错误
60
-51 ERROR_NET_TIMEOUT 网络通讯超时

-52 ERROR_NET_CLOSED 网络连接被服务关闭
-53 ERROR_SERVER_REDUNDANCY 冗余热备服务必须处于工作状
态
-54 ERROR_ADDR_EXIST 标签地址已经被占用
-55 ERROR_ID_EXIST 标签 ID 已经被占用
-70 ERROR_BUCKET_NULL 哈希单元无效
-71 ERROR_KEY_NOFOUND 找不到的给定的关键字
-72 ERROR_KEY_FOUND 关键字已存在
-73 ERROR_POINT_NULL 无效的标签配置指针
-74 ERROR_HASH_END 已到达哈希表末尾
-75 ERROR_PROTO_BAD 网络协议转化错误
-76 ERROR_HANDLE_BAD 网络协议句柄错误
-77 ERROR_ATTR_NONE 没有指定的属性
-78 ERROR_INDEX_OVER 属性索引号溢出
-79 ERROR_ATTR_MANY 标签属性数太多
-80 ERROR_TYPE_BAD 标签类型不匹配
-81 ERROR_BLOB_LARGE BLOB 数据太大，最大为96kB
-82 ERROR_ACCESS_BAD 非法访问
-83 ERROR_NO_MEM 内存分配失败
-84 ERROR_SCRIPT_NONE 计算脚本指针为空
-85 ERROR_SCRIPT_SYNTAX 计算脚本语法错误
-86 ERROR_HASH_CLASH 标签名称和地址哈希冲突
-87 ERROR_SERVER_INDEX 非法服务索引号
-88 ERROR_LOCAL_FILE 本地文件操作时发生错误
-89 ERROR_USER_CANCEL 用户主动取消了操作
-90 ERROR_ACCESS_ATTACK 疑似网络安全攻击，服务请求
被拒绝
61
如果您对 TrendDB 实时数据库感兴趣，请联系：

毛宝平
电话：13823725184
电邮：bpmao@qq.com
QQ：1310192558
62

TrendDB数据库JAVA语言程序接口手册

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TrendDB数据库JAVA语言程序接口手册

Uploaded by

Copyright:

Available Formats

TrendDB 实时数据库

int CreateConnection(String connection, boolean bFireWall, boolean bCacheEnabled, String

void CloseConnection(String connection) throws DB_Exception;

int GetConnectionStatus(String connection) throws DB_Exception;

int TestServer(String connection) throws DB_Exception;

loloLim, hihiLim, lowLim, highLim 分别是连续标签的“低低”、“高高”、“低”、

时标，8字节 数据值，4字节 质量标志，4字节

原始数据 数值数据 连续数据

对于二进制数据，TrendDB 采用通用的 Huffman 压缩算法对其进行压缩，

void AddTag(String connection, TagConfig config) throws DB_Exception;

int[] AddTagList(String connection, TagConfig[] configs) throws

void DeleteTagByName(int connId, String name) throws DB_Exception;

DeleteTagByName 按标签名称删除标签，DeleteTagByAddr 则按标签地址删除

标签，DeleteTagByID 按数据标 ID 删除标签，成功则删除标签，不成功则抛出异

void UpdateTagByID(String connection, TagConfig config) throws DB_Exception;

int[] UpdateTagListByName(String connection, TagConfig[] configs) throws DB_Exception;

其中，connection 或 connId 为连接标识符；configs 为批量标签配置信息数组，

void RenameTag(String connection, String oldName, String newName) throws

AttrHandle GetTagAttrByName(String connection, String name) throws DB_Exception;

void SetTagAttrByID(int connId, int tagId, AttrHandle handle) throws DB_Exception;

需要负责将其释放，但是当用户将 handle 调用 CloseTagAttrHandle 关闭后，handle

void SetTagFilter(String connection, String type, String value) throws DB_Exception;

以上三个函数配合使用可以用来枚举 TrendDB 服务器上定义的符合过滤条

TagInfo GetTagInfoByName(String connection, String name, boolean bComplete) throws

void SetBlobValueByName(String connection, String name, BlobValue value) throws

public class BlobValue

void InsertBlockValueByName(String connection, String name, DB_Value[] values) throws

void UpdateValueByName(String connection, String[] names, DB_Value[] values) throws

void FlushConnectionBuffer(String connection) throws DB_Exception;

TrendDB 的数据查询接口用于查询存储在 TrendDB 服务端的实时历史数据，

HistoryStatus QueryHistStatusByName(String connection, String name) throws

其中，start 和 end 分别用来表示标签历史数据存储的起始和终止时间。历

DB_Value[] GetLatestValueByName(String connection, String[] names) throws

HistoryPosition QueryHistPositionByName(String connection, String name, HistoryPosition

DB_Value[] RetrieveTrendByName(String connection, String name,

DB_Value[] RetrieveSamplesByName(String connection, String name, HistoryPosition

上图中，蓝色星标代表 TrendDB 所存储的原始数据，绿色星标代表的是连

DB_Profile GetProfileByName(String connection, String name, DB_Time start, DB_Time

DB_Value min, max;

DB_Value[] RetrieveSnapshotsByName(String connection, DB_Time start, String[] names)

BlobValue RetrieveBlobByName(String connection, String name, HistoryPosition inOutPos)

connection 或 connId 是连接标识符，position 是指定的历史数据位置指示结构，

DB_Statistics GetStatisticsByName(String connection, String name, DB_Time start, DB_Time

DB_ChangeCount GetChangeCountByName(String connection, String name, DB_Time start,

DB_ChangeCount GetChangeCountByID(int connId, int tagId, DB_Time start, DB_Time

double[] RetrieveDifferencesByName(String connection, DB_Time start, DB_Time end,

float[] RetrieveDutyRatioByName(String connection, String tag, DB_Time start, DB_Time

levels) throws DB_Exception;

HistoryPosition QueryGroupPositionByName(String connection, String[] names,

HistoryPosition QueryGroupPositionByName(int connId, String[] names, HistoryPosition

DB_Value[][] RetrieveGroupSamplesByName(String connection, String[] names,

DB_Profile[] RetrieveGroupProfilesByName(String connection, String[] names, DB_Time

DB_Time end) throws DB_Exception;

DB_Statistics[] RetrieveGroupStatsByName(String connection, String[] names, DB_Time

DB_ChangeCount[] RetrieveGroupChangeCountsByName(String connection, String[]

DB_ChangeCount[] RetrieveGroupChangeCountsByAddr(String connection, String[] addrs,

float[][] RetrieveGroupDutiesByName(String connection, String[] names, DB_Time start,

void SetDutyParaByName(String connection, String tag, float[] levels) throws DB_Exception;

void SetDutyParaByID(String connection, int tagId, float[] levels) throws DB_Exception;

void SetChangeCountParaByName(String connection, String tag, float low, float high)

float[] GetDutyParaByName(String connection, String tag) throws DB_Exception;

float[] GetDutyParaByName(int connId, String tag) throws DB_Exception;

float[] GetChangeCountParaByName(int connId, String tag) throws DB_Exception;

TrendDB 数据库服务自定义了2个标签，分别为 system.cpu 以及 system.disk，

时标，8字节数据值，4字节质量标志，4字节

原始数据数值数据连续数据

【 J/kg 】）计算水或水蒸气的密度（【 kg/m3 】），调用格式为 T = IF97.

【 J/kg/K 】）计算水或水蒸气的密度（【 kg/m3 】），调用格式为 T = IF97.

【 J/kg/K 】）计算水或水蒸气的压力（【 Pa 】），调用格式为 p = IF97.

【 J/kg/K 】）计算水或水蒸气的温度（【 K 】），调用格式为 p = IF97.