《变量数据检索说明》由会员分享，可在线阅读，更多相关《变量数据检索说明（9页珍藏版）》请在金锄头文库上搜索。
1、变量数据检索说明文档1 检索条件的取值范围：变量名称（TagNames）： 可以是一个变量名，或多个变量名，也可以不指定变量名，不可以使用通配符。 指定变量名必须是数据库变量表中存在的变量，如果不存在该变量，则该变量的返回错误码为-18。如果不 指定变量名，则搜索整个变量表，将变量表中的全部变量作为要检索的变量。如果数据库中没有变量，则 直接返回。（如果是通过SQL进行查询，将返回-24。）起始时间（StartTime）:时间必须是1970-1-1 00： 00： 00 （标准时间）以后的时间，如果采用北京时 间，则必须是 1970-1-1 08： 00： 00 以后的时间。如果没有指定起始时
2、间，则起始时间为终止时间前的 1 小时。 例外： 如果指定了终止时间没有指定起始时间，并且采样模式为 SAMPLE_RAW_BY_TIME 或 SAMPLE_RAW_BY_NUMBER，则起始时间相当于1970-1-1 00： 00： 00 （标准时间），系统将检索终止时间前 的所有原始数据。终止时间（EndTime）:时间必须是1970-1-1 00： 00： 00 （标准时间）以后的时间，如果采用北京时间， 则必须是 1970-1-1 08： 00： 00 以后的时间。终止时间可以不指定。如果终止时间不指定，则终止时间为 当前时间。如果终止时间和起始时间都不指定，则终止时间为当前时间，起始
3、时间为当前时间前一小时。 如果起始时间和终止时间都指定了，则必须保证终止时间大于起始时间（ StartTime EndTime ）。如果 采样模式为SAMPLE_CURRENT_VALUE,不需要指定起始时间，如果指定了必须保证终止时间大于起始时间。 （注意：变量数据的检索时间范围是左闭右开区间，就是说检索时间大于等于起始时间，小于终止时间， 即检索时间中不包含终止时间。）记录行数（RowCount）：指定检索返回的记录的数目。如果检索到的记录的数目小于指定数值，则返回检 索到的记录数目。如果记录的行数小于等于0,则记录行数为默认行数DEFAULT_ROW_COUNT （5000）。如果 记录
4、行数大于最大记录行数UNLIMIT_ROW_COUNT（15000000），则记录行数为最大记录行数。注意：记录 行数不是指每个变量的记录数目，而是所有包括所有检索变量在内的记录数目。（如果是通过SQL进行查 询，记录行数将被忽略）数据版本（DataVersion）:数据版本是SHORT类型，有效的数据版本取值为0-32767。其中0是第一个数 据版本（原始版本）， 1 是第一个修改版本，以此类推。数据的最后一个版本为数据的最新版本。为便于 查询，增加几中特殊的数据版本，DATA_VERSION_UNKNOWN（-4）表示无效版本，DATA_VERSION_MODIFIED （-3）表示修改后
5、版本，即不包含版本为0的的其他数据版本，DATA_VERSION_LATEST （-2）表示最近的版 本，即版本号最大的数据版本，DATA_VERSION_ALL （-1）表示所有版本。在检索参数中，只有当采样模式为SAMPLE_RAW_BY_NUMBER或SAMPLE_RAW_BY_TIME的时候，版本参数 才有效，在其他检索条件下，指定版本没有效果。其他采样模式下，只考虑数据的最新版本。（如果没有 指定采样模式，采样模式默认为SAMPLE_RAW_BY_TIME,会考虑到数据版本条件） 采样模式（SamplingMode）：采样模式包含7中，即SAMPLE_CURRENT_VALUE1SA
6、MPLE_INTERPOLATED2SAMPLE_RAW_BY_TIME3SAMPLE_RAW_BY_NUMBER 4SAMPLE_CALCULATED 5 SAMPLE_STEPPED 6 SAMPLE_TREND 7当前值（实时值，时间戳最新的变量值，数据质量不论） 线性插值采样（根据时间区间、采样点数或采样周期等时间间隔线性插值） 根据时间区间获取原始值（时间区间为前闭后开）根据指定数量和起始时间获取原始值统计计算（必须指定CalculationMode） 步进插值（非线性插值，取前一值） 趋势采样（指定时间区间、采样点数或采样周期返回每个采样间隔的最大和最小原始值，用于画趋势曲线）如果
7、指定采样模式为 SAMPLE_UNKNOWN （0 ） ，或不指定采样模式或大于最大的采样模式，则默认采 样模式为 SAMPLE_RAW_BY_TIME。如果采样模式为SAMPLE_CURRENT_VALUE，除了变量名称（TagNames）和记录行数（RowCount），所有 其他检索条件都被忽略。当采样模式为SAMPLE_RAW_BY_TIME或SAMPLE_RAW_BY_NUMBER，如果指定了终止时间而没有指定起始 时间，则将检索变量的全部历史数据。当采样模式为SAMPLE_TREND,过滤条件将被忽略，并且采样间隔必须大于等于0。参考采样间隔的说 明。采样点数（SamplingNum
8、ber）:只有当采样模式为SAMPLE_RAW_BY_NUMBER的时候才有效。如果指定采样模 式为SAMPLE_RAW_BY_NUMBER，采样点数小于等于0,则采样点数采用默认值DEFAULT_SAMPLING_NUMBER1000 ）。采样间隔 （ SamplingInterval ） : 当采样模式为 SAMPLE_INTERPOLATED ， SAMPLE_CALCULATED ， SAMPLE_STEPPED，或 SAMPLE_TREND 时有效。单位为毫秒（ms）。如果采样模式为SAMPLE_TREND，采样间隔不可以小于0,如果采样间隔等于0,则采样间隔为检索时 间范围（终止时
9、间-起始时间）除以默认趋势间隔数目（DEFAULT_TREND_INTERVAL_NUMBER = 512 ）。如果 采样间隔大于最大采样间隔MAX_SAMPLING_INTERVAL（1000天=1000*24*60*60*1000ms），则采样间隔是最 大采样间隔。如果采样模式为 SAMPLE_STEPPED，SAMPLE_INTERPOLATED 或 SAMPLE_CALCULATED，采样间隔可以小于 0,如果采样间隔小于0,则采样间隔为默认采样间隔DEFAULT_SAMPLING_INTERVAL（60秒=60*1000ms）。 如果采样间隔等于0，则采样间隔为整个检索时间范围（终止
10、时间-起始时间）。通过设置采样间隔，把整个检索时间范围划分为若干采样区间，所有采样区间都为左闭右开区间。下 一个采样区间的起始时间为上一个采样区间的终止时间，第一个采样区间的起始时间为检索时间的起始时 间，最后一个采样区间的终止时间为检索条件的终止时间。计算方式（CalculationMode）:计算方式支持21种。只有在采样模式为SAMPLE_CALCULATED的时候才有效。采样模式为 SAMPLE_CALCULATED 必须要指定一种有效的计算方式。CALCULATION_UNKNOWNCALCULATION_COUNTCALCULATION_AVERAGECALCULATION_TOT
11、ALCALCULATION_STDEVCALCULATION_RAW_TOTALCALCULATION_RAW_AVERAGECALCULATION_RAW_STDEVCALCULATION_MINIMUM8CALCULATION_MAXIMUM9CALCULATION_MINIMUM_TIME CALCULATION_MAXIMUM_TIME CALCULATION_DURATION_GOOD CALCULATION_DURATION_BAD0 未知的计算方式1 计数（每个采样区间的原始值的个数，数据质量必须是好的）2 时间加权的原始平均值3 时间加权的原始值求和4 时间加权的标准方差5 求
12、和（每个采样区间的原始值的求和）6 平均值（每个采样区间的原始值的算术平均值）7 标准方差（原始值的算术标准方差）最小值（每个采样区间内的最小值，是原始值，数据质量必须是好的） 最大值（每个采样区间内的最大值，是原始值，数据质量必须是好的）10 最小值对应的时间11 最大值对应的时间12 好数据的时间总长（s）CALCULATION_MAXIMUM_ACTUAL_TIME14 最大值（取数据实际时间）13 坏数据的时间总长（s）最小值（取数据时间时间）CALCULATION_STARTCALCULATION_ENDCALCULATION_DELTACALCULATION_RANGECALCUL
13、ATION_PERCENT_GOODCALCULATION_PERCENT_BADCALCULATION_MINIMUM_ACTUAL_TIME 1516 区间内的第一个原始数据（质量戳可能是好的，也可能是坏的）17 区间内的最后一个原始数据（质量戳可能是好的，也可能是坏的）18 区间内的第一个和最后一个好的原始数据之差19 区间内最大/最小值的绝对差值（只计算好数据）20 好数据总长/区间长度21 坏数据总长/区间长度CALCULATION_UNKNOWN 是无效的计算方式，如果检索条件中的计算方式不是 CALCULATION_COUNT 到CALCULATION_PERCENT_BAD这2
14、1种计算方式，系统将返回非法参数错误。过滤变量（FilterTag）:用做过滤条件的变量名，该变量必须在数据库的变量表中存在，否则返回错误T8。过滤变量可以是待检索变量中的一个，也可以是其他的变量。如果过滤变量为空，则不进行过滤操作。当 采样模式为SAMPLE_CURRENT_VALUE或SAMPLE_TREND时，过滤变量无效，不进行过滤操作。注意： 过滤变量只可以是一个变量，不能是多个变量，不支持通配符。过滤模式（FilterMode）:支持的过滤模式有：FILTER_UNKNOWN 0 FILTER_EXACT_TIME 1 FILTER_BEFORE_TIME 2 FILTER_AFT
15、ER_TIME 3 FILTER_BEFORE_AND_AFTER_TIME 4 过滤模式图解如下：未知的方式过滤条件为真的确切时间点 从过滤条件为假一直到过滤条件为真的时间段 从过滤条件为真到下一次过滤条件为假之间的时间段 从过滤条件为假到下次过滤条件为假的时间段DEFG-真*-*ABC-假*-*-*K L M*-*H IJN*-*- 时间轴过滤条件取值FILTER_COMPARSION_UNKNOWN 0 FILTER_COMPARSION_EQUAL 1 FILTER_COMPARSION_NOT_EQUAL 2 FILTER_COMPARSION_LESS 3 FILTER_COMPARSION_GREATER 4 FILTER_COMPARSION_LESS_EQUAL 5FILTER_COMPARSION_GREATER_EQUAL 6未知的操作ExactTime条件为真的那些时间点，如图中的 D、E、F、G、K、L、MBeforeTime(last false,first true ，如图中的(C,D,(J,K；BeforeAndAfterTime(last false,next false),如图
