Historian


`Historian`
Prev	Chapter 14. Classes from `HistorianSupport.g`	Next

`Historian`

Historian — encapsulates the Historian facility in the DataHub program.

Synopsis

class Historian
{
}

Instance Variables

None.

Methods

allowAutoHistoryAdds(state, defaultgroup)

Configures automatic history addition. The state should be nil to turn off the function and t to turn it on. The defaultgroup is a string naming the History Group to which automatic histories are added. This method corresponds to this setting in the Historian option of the Properties window:

addGroup(label, basedir, cachesize)

Creates a new History Group with the provided label, basedir (base directory) and cachesize (cache size). This corresponds approximately to pressing the Add ... button in the Historian option of the Properties window.

removeGroup(label)

Removes the History Group with the given label.

setFileTimes(labelpattern, days, hours, minutes)

Assigns the file times for all History Groups whose labels match the labelpattern. The pattern uses the pattern matching rules documented in the shell_match function. This method corresponds to this setting in the Properties window Historian configuration:

setRentionTimes(labelpattern, days, hours, minutes)

Assigns the data retention times for all History Groups whose labels match the labelpattern. The pattern uses the pattern matching rules documented in the shell_match function. This method corresponds to this setting in the Properties window Historian configuration:

setFlushTimes(labelpattern, days, hours, minutes), ()

Assigns the file flush times for all History Groups whose labels match the labelpattern. The pattern uses the pattern matching rules documented in the shell_match function. This method corresponds to this setting in the Properties window Historian configuration:

setDeadband(labelpattern, flags, absolute, percent, maxsecs, maxcount)

Assigns the deadband settings for all History Groups whose labels match the labelpattern. The pattern uses the pattern matching rules documented in the shell_match function. This method corresponds to this section of the Properties window Historian configuration:

The flags argument is 0 to turn off all deadbands, or any combination of:

0x0008 - Turn on the percent deadband

0x0020 - Turn on the absolute deadband

0x0040 - Turn on the maximum time limit

0x0080 - Turn on the maximum skip count

addPoint(pointname, grouplabel?=nil)

Adds a point to the named History Group. If grouplabel is nil or not specified then the point will be added to the automatic group. If the automatic group is not set and the grouplabel is not specified, this method will fail silently.

The pointname is a string specifying the fully qualified point name. That is, the point name must contain the data domain and the full path of the point, for example, DataPid:PID1.Mv

removePoint(pointpattern, grouppattern?="*")

Removes all points matching the pointpattern from all groups matching the grouppattern.

saveConfig()

Causes the Historian to save its configuration to disk.

startConfiguring()

Tells the Historian to enter configuring mode. In this mode, changes to group configurations are accepted but not applied. This allows a number of configuration commands to be sent without affecting the current state of the Historian. This method must eventually be followed by a call to endConfiguring for the configuration changes to be applied.

endConfiguring()

Tells the Historian to exit configuring mode, and to apply any changes to the configuration that have been made since the call to startConfiguring.

queryRawData(pointname, start_unixtime, duration_secs)

Queries the history for a given point, starting at the specified time (start_unixtime) and running for the specified number of seconds (duration_secs). The pointname must be a string containing the fully qualified name of the point. The start_unixtime must be specified as number of seconds since midnight January 1, 1970 UTC. Both the start_unixtime and duration_secs are floating point values and can contain a fractional component.

The return value from this function is either nil or an instance of HistoryBuffer containing the values that fall within the specified range.

The data returned from this method is the exact data set as stored on disk without modification.

queryStatistic(pointname, start_unixtime, duration_secs, aggregation_period_secs, stat_name)

Queries a statistical measure of the history for a given point, starting at the specified time (start_unixtime) and running for the specified number of seconds (duration_secs). The pointname must be a string containing the fully qualified name of the point. The start_unixtime must be specified as number of seconds since midnight January 1, 1970 UTC. Both the start_unixtime and duration_secs are floating point values and can contain a fractional component.

The return value from this function is either nil or an instance of HistoryBuffer containing the values that fall within the specified range.

The aggregation_period_secs specifies the number of seconds in each time interval within the overall query on which to produce statistics. For example, a query may request the average value in each 5-second period for a minute. The aggregation period would be 5 seconds, and the duration would be 60 seconds. The result set will contain 12 values, one for each 5-second interval within the duration of the query.

The stat_name is a string that specifies which statistical measure to query. The statistical measures available are:

Statistic Name	Description
`Total`	Retrieve the totalized value (time integral) of the data over the sample interval.
`Average`	Retrieve the average data over the sample interval.
`TimeAverage`	Retrieve the time weighted average data over the sample interval.
`Count`	Retrieve the number of good quality raw values over the sample interval.
`RawCount`	Retrieve the number of raw values over the sample interval.
`StDev`	Retrieve the standard deviation over the sample interval.
`MinimumActualTime`	Retrieve the minimum value in the sample interval and the timestamp of the minimum value.
`Minimum`	Retrieve the minimum value in the sample interval.
`MaximumActualTime`	Retrieve the maximum value in the sample interval and the timestamp of the maximum value.
`Maximum`	Retrieve the maximum value in the sample interval.
`Start`	Retrieve the value at the beginning of the sample interval. The time stamp is the time stamp of the beginning of the interval.
`End`	Retrieve the value at the end of the sample interval. The time stamp is the time stamp of the end of the interval.
`First`	Retrieve the first value change within the interval. The time stamp is the time stamp of the first value change.
`Last`	Retrieve the last value change within the interval. The time stamp is the time stamp of the last value change.
`Delta`	Retrieve the difference between the first and last value in the sample interval.
`RegSlope`	Retrieve the slope of the regression line over the sample interval.
`RegConst`	Retrieve the starting point of the regression line over the sample interval. This is the value of the regression line at the start of the interval.
`RegPearsonR`	Retrieve Pearson R measure of correlation between Y and Time over the sample interval. This is a number between -1.0 and 1.0.
`RegRSquared`	Retrieve R-squared measure of regression fitness over the sample interval. This is a number between 0 and 1.0.
`Variance`	Retrieve the variance over the sample interval .
`Range`	Retrieve the difference between the minimum and maximum value over the sample interval.
`DurationGood`	Retrieve the duration (in seconds) of time in the interval during which the data is good.
`DurationBad`	Retrieve the duration (in seconds) of time in the interval during which the data is bad.
`PercentGood`	Retrieve the percent of data (`1` equals 100 percent) in the interval which has good quality.
`PercentBad`	Retrieve the percent of data (`1` equals 100 percent) in the interval which has bad quality.
`WorstQuality`	Retrieve the worst quality of data in the interval.
`ValueSum`	Retrieve the sum of all raw values over the sample interval.