TINE Local History Server module plus API routines. More...
Functions | |
| int | AppendHistoryInformation (char *eqm, char *prp, char *dev, int len, int fmt, int idx, HistorySpecification *hspec) |
| Inserts a local history element into the local history server. | |
| int | AppendHistoryInformationEx (char *eqm, char *prp, char *dev, int len, int fmt, int idx, HistorySpecification *hspec, int hstFlags) |
| Inserts a local history element into the local history server. | |
| char * | GetHistoryFilesRepository (void) |
| Returns the directory location where local history files are maintained. | |
| char * | GetHistoryStaticFilesRepository (void) |
| Returns the directory location where static local history files are maintained. | |
| int | GetLastStoredData (char *eqm, char *prp, char *dev, int index, BYTE *data, int fmt, int arraysize) |
| Retreives the last stored data set from disk for the given input parameters. | |
| int | GetStandardSpillOverSize (void) |
| Gets the amount of additional space (number of addition records) to allocate as a worst case when using the standard local history data file set. | |
| void | SetHistoryFilesRepository (char *path) |
| Sets the directory location where local history files are maintained. | |
| void | SetHistoryStaticFilesRepository (char *path) |
| Sets the directory location where static local history files are maintained. | |
| void | SetMaximumHistoryTableRecords (int value) |
| Sets the maximum local history table size. | |
| void | SetMinimumDiskSpaceInBlocks (UINT32 spaceInBlocks) |
| Sets the amount of free disk space the local history subsystem should try to maintain. | |
| void | SetPointsOfInterestRangeFactor (float value) |
| Sets the definitive property range (maximum-minimum) factor which determines whether a value is consider a point of interest. | |
| void | SetPointsOfInterestToleranceFactor (float value) |
| Sets the definitive property tolerance factor which determines whether a value is consider a point of interest. | |
| void | SetStandardSpillOverSize (int value) |
| Sets the amount of additional space (number of addition records) to allocate as a worst case when using the standard local history data file set. | |
| void | SetUseStandardHistoryFiles (int value) |
| Instructs the server to use the so-called 'standard' set of local history files. | |
Variables | |
| int | useMinimalStorage = FALSE |
| Instructs the local history server to use a simple UTC timestamp (4-byte integer) when saving data to disk. | |
| int | useMonthlyHistoryFiles = FALSE |
| Instructs the local history server to keep monthly archive files instead of daily files. | |
TINE Local History Server module plus API routines.
A TINE server can be instructed to maintain a local history of certain properties. The stored data can then be obtained with normal data acquition calls to the TINE Local History Server. By and large the instructions as to which properties are to be maintained in the local history server and as to what filtering criteria are to be used in commiting the data to disk are typically entered into a startup configuration file 'history.csv'. As an alternative, see AppendHistoryInformation(). The local history server maintains two sets of histories, a short-term history kept in main memory and a long-term history kept on disk. Whereas the short-term history can be kept on a millisecond time raster, the long-term history will not be written to disk any more often than once per second.
| int AppendHistoryInformation | ( | char * | eqm, |
| char * | prp, | ||
| char * | dev, | ||
| int | len, | ||
| int | fmt, | ||
| int | idx, | ||
| HistorySpecification * | hspec | ||
| ) |
Inserts a local history element into the local history server.
A server can instruct the local history server to keep a history of the given property by utilizing this call. The local history server will periodically call the property as specified according to the following input parameters.
| eqm | is the 6-character local equipment identifier name, which is internal to server. |
| prp | is the requested property for which a history is to be kept |
| dev | is the device name to be associated with the property name supplied as the second parameter. |
| len | is the length of the local history call. |
| fmt | is the TINE format of the local history call. |
| idx | is the local history index to be identified with this local history element (Note: this must be unique with this server process and within the history data repository). |
| hspec | is a pointer to a HistorySpecification structure, where the relevant filtering criteria are given. |
Example:
#include "tine.h"; ... int initLocalHistoryInformation(void) { HistorySpecification h; h.pollingRate = 500; // aquire new data at 2 Hz h.archiveRate = 10; // don't write to disk more often than every 10 seconds h.depthShort = 300; // keep the fast data in a ringbuffer 300 deep h.depthLong = 2; // keep the long-term data on disk for at least 2 months h.heartbeat = 18000; // make sure a value is written to disk at least every half hour h.pTolerance = 10; // if data change is 10 percent or greater then write to disk h.aTolerance = 1; // (OR) if data change in absolute terms by 1 then write to disk if ((cc=AppendHistoryInformation("BPMEQM","POSITIONS.X","WL167",141,CF_FLOAT,1,&h)) != 0) printf("AppendHistoryInformation failed : %s\n",erlst[cc]); ... }
References AppendHistoryInformationEx().
| int AppendHistoryInformationEx | ( | char * | eqm, |
| char * | prp, | ||
| char * | dev, | ||
| int | len, | ||
| int | fmt, | ||
| int | idx, | ||
| HistorySpecification * | hspec, | ||
| int | hstFlags | ||
| ) |
Inserts a local history element into the local history server.
A server can instruct the local history server to keep a history of the given property by utilizing this call. The local history server will periodically call the property as specified according to the following input parameters. The extended version allows passing the additional parameter 'hstFlags' which can be used to direct the style of points-of-interest (USE_POI_NONE, USE_POI_RANGE, USE_POI_TOLERANCE).
| eqm | is the 6-character local equipment identifier name, which is internal to server. |
| prp | is the requested property for which a history is to be kept |
| dev | is the device name to be associated with the property name supplied as the second parameter. |
| len | is the length of the local history call. |
| fmt | is the TINE format of the local history call. |
| idx | is the local history index to be identified with this local history element (Note: this must be unique with this server process and within the history data repository). |
| hspec | is a pointer to a HistorySpecification structure, where the relevant filtering criteria are given. |
| hstFlags | gives additional storage directives. For example if no 'points of interest' companion files are desired, setting hstFlags = USE_POI_NONE will instruct the subsystem not to maintain them. If this parameter is 0, then the default criteria are used, and the call collapses to AppendHistoryInformation(). |
Example:
#include "tine.h"; ... int initLocalHistoryInformation(void) { HistorySpecification h; h.pollingRate = 500; // aquire new data at 2 Hz h.archiveRate = 10; // don't write to disk more often than every 10 seconds h.depthShort = 300; // keep the fast data in a ringbuffer 300 deep h.depthLong = 2; // keep the long-term data on disk for at least 2 months h.heartbeat = 18000; // make sure a value is written to disk at least every half hour h.pTolerance = 10; // if data change is 10 percent or greater then write to disk h.aTolerance = 1; // (OR) if data change in absolute terms by 1 then write to disk if ((cc=AppendHistoryInformationEx("BPMEQM","POSITIONS.X","WL167",141,CF_FLOAT,1,&h,USE_POI_NONE)) != 0) printf("AppendHistoryInformation failed : %s\n",erlst[cc]); ... }
References HistorySpecification::archiveRate, HistorySpecification::aTolerance, HistorySpecification::depthLong, HistorySpecification::depthShort, feclog(), GetExportedName(), HistorySpecification::heartbeat, HistorySpecification::pollingRate, HistorySpecification::pTolerance, HistorySpecification::rhsPropertyName, and HistorySpecification::rhsServerName.
Referenced by AppendHistoryInformation().
| char* GetHistoryFilesRepository | ( | void | ) |
Returns the directory location where local history files are maintained.
Typically the location for the local history repository is established by the environment variable HISTORY_HOME. If not set, the default location for local history files is given by an adjacent directory to the FEC_HOME location given by the sub-directory name HISTORY.
| char* GetHistoryStaticFilesRepository | ( | void | ) |
Returns the directory location where static local history files are maintained.
Normally the local history subsystem maintains a volatile history repository where history files older than the long term depth are regularly removed from the disk. If it is desired to keep certain local history files from being automatically removed, such files can be copied by hand into the designated static files repository.
By default, this will be a sub-directory 'SAVED' located within the normal history files repository given by e.g. the HISTORY_HOME environment variable or otherwise set via API. The location of the static repository can be retrieved via this API call.
| int GetLastStoredData | ( | char * | eqm, |
| char * | prp, | ||
| char * | dev, | ||
| int | idx, | ||
| BYTE * | data, | ||
| int | fmt, | ||
| int | len | ||
| ) |
Retreives the last stored data set from disk for the given input parameters.
A server can retrieve the last stored data set from disk for any given local history property. This is frequently useful to insure that a server restart will reload data various sets, for instance when data are collected according to intermittent triggers, etc.
| eqm | is the 6-character local equipment identifier name, which is internal to server. |
| prp | is the requested property for which a history is to be kept |
| dev | is the device name to be associated with the property name supplied as the second parameter. |
| idx | is the local history index to be identified with this local history element (Note: this must be unique with this server process and within the history data repository). |
| data | is the buffer to receive the data. It must be pre-allocated to at least the array length specified in the 'len' parameter. |
| fmt | is the TINE format of the local history call. |
| len | is the length of the local history call. |
Example:
#include "tine"; ... int initDataSets(void) { int cc = 0; cc = getLastStoredData("XFREQM","EFFICIENCY-TRIG","HEIDC",0,(BYTE *)g_efficiency_trigLast,CF_FLOAT,222); if (cc != 0) { printf("getLastStoredData for EFFICIENCY-TRIG HEIDC failed : %d\n",cc); } ... return cc; }
References GetDeviceNumberEx().
| int GetStandardSpillOverSize | ( | void | ) |
Gets the amount of additional space (number of addition records) to allocate as a worst case when using the standard local history data file set.
The local history standard file set is pre-allocated to manage a 'worst-case' number of stored records based on all filtering criteria coming up negative and making use of the configured history record polling interval and record size.
| void SetHistoryFilesRepository | ( | char * | path | ) |
Sets the directory location where local history files are maintained.
Typically the location for the local history repository is established by the environment variable HISTORY_HOME. If not set, the default location for local history files is given by an adjacent directory to the FEC_HOME location given by the sub-directory name HISTORY.
| path | is the desired history files repository location. |
References feclog().
| void SetHistoryStaticFilesRepository | ( | char * | path | ) |
Sets the directory location where static local history files are maintained.
Normally the local history subsystem maintains a volatile history repository where history files older than the long term depth are regularly removed from the disk. If it is desired to keep certain local history files from being automatically removed, such files can be copied by hand into the designated static files repository.
By default, this will be a sub-directory 'SAVED' located within the normal history files repository given by e.g. the HISTORY_HOME environment variable or otherwise set via API. The location of the static repository can otherwise be set via this API call.
| path | is the desired static history files repository location. |
References feclog().
| void SetMaximumHistoryTableRecords | ( | int | value | ) |
Sets the maximum local history table size.
The local history subsystem makes use of a table containing all relevant history contracts. The maximum size of the this table is governed by this routine.
| value | is the desired maximum history table size (default is 100). |
| void SetMinimumDiskSpaceInBlocks | ( | UINT32 | spaceInBlocks | ) |
Sets the amount of free disk space the local history subsystem should try to maintain.
Normally the local history subsystem maintains a history repository based on the assigned depth in months of the history records. In addition, one can make use of this call to establish a minimum floor to the amount of free disk space which should be maintained on the server. If this floor is reached, then the oldest history files will be removed until the disk free space is once again above the assigned floor.
| value | is the desired minimum free disk space (in blocks) to be maintained on the local history partition. |
References feclog().
| void SetPointsOfInterestRangeFactor | ( | float | value | ) |
Sets the definitive property range (maximum-minimum) factor which determines whether a value is consider a point of interest.
If the change in a property's readback value is greater than the value's display range times this range factor, then the value is considered a point of interest and therefore always returned in archive calls over the relevant time range.
| value | is the desired display range factor (default is 0.25). |
| void SetPointsOfInterestToleranceFactor | ( | float | value | ) |
Sets the definitive property tolerance factor which determines whether a value is consider a point of interest.
If the change in a property's readback value is greater than the value's tolerance (if non-zero) times this range factor, then the value is considered a point of interest and therefore always returned in archive calls over the relevant time range.
| value | is the desired display range factor (default is 10). |
| void SetStandardSpillOverSize | ( | int | value | ) |
Sets the amount of additional space (number of addition records) to allocate as a worst case when using the standard local history data file set.
The local history standard file set is pre-allocated to manage a 'worst-case' number of stored records based on all filtering criteria coming up negative and making use of the configured history record polling interval and record size. If it is anticipated that some local history data will be scheduled, then an additional spill-over space should be applied.
| value | is the desired additional spill over size (default 1000). |
| void SetUseStandardHistoryFiles | ( | int | value | ) |
Instructs the server to use the so-called 'standard' set of local history files.
The 'standard' set of local history files is pre-allocated on the local file system to be able to contain a 'worst-case' respository of random-access local history records according to the assigned polling interval and data size of the record (i.e. a null result is assumed for any would-be filtering action). The initial allocation of such a file set is of course time-consuming if a depth of several months is required and the records are large. However the subsequent data retrieval is very fast.
This routine will enforce the usage of the standard local history file set.
| value | is the desired value of this setting (default: FALSE). |
References feclog().
| int useMinimalStorage = FALSE |
Instructs the local history server to use a simple UTC timestamp (4-byte integer) when saving data to disk.
By default, the local history subsystem will timestamp the data records stored to disk with a higher resolution timestamp than the traditional UTC variable. The data system stamps will likewise be stored with the data record. This results in more disk space being used by an archive record, as the record prefix is now 16 bytes per archived record instead of 4. This can be controlled by setting this variable to TRUE (small prefix) or FALSE (large prefix).
Default: FALSE
| int useMonthlyHistoryFiles = FALSE |
Instructs the local history server to keep monthly archive files instead of daily files.
The local history subsystem maintains one file per record per day. In some cases it might be advantageous to keep one file per record per month, for instance when many small records are being maintained. You can influence this behavior be setting this flag to TRUE.
1.5.8