History API Calls File Reference

TINE Local History Server module plus API routines. More...

Functions
int	AppendHistoryData (char *eqm, char *prp, char *dev, DTYPE *dout)
	Inserts local history data into the local history ring buffer. More...
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. More...
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. More...
int	ApplyHistoryFilter (int idx, char *parsableFilterString)
	Applies a history filter to an existing local history record. More...
char *	GetHistoryFilesRepository (void)
	Returns the directory location where local history files are maintained. More...
char *	GetHistoryStaticFilesRepository (void)
	Returns the directory location where static local history files are maintained. More...
int	GetLastStoredData (char *eqm, char *prp, char *dev, int index, BYTE *data, int fmt, int len)
	Retreives the last stored data set from disk for the given input parameters. More...
int	GetLastStoredDataEx (char *eqm, char *prp, char *dev, int index, BYTE *data, int fmt, int len, double *tstamp)
	Retreives the last stored data set from disk for the given input parameters (extended call). More...
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. More...
int	GetUseStandardHistoryFiles (int index)
	Returns TRUE of FALSE depending on whether the given history record index makes use of the so-called 'standard' set of local history files. More...
void	SetHistoryFilesRepository (char *path)
	Sets the directory location where local history files are maintained. More...
void	SetHistoryStaticFilesRepository (char *path)
	Sets the directory location where static local history files are maintained. More...
void	SetMaximumHistoryTableRecords (int value)
	Sets the maximum local history table size. More...
void	SetMinimumDiskSpaceInBlocks (UINT32 spaceInBlocks)
	Sets the amount of free disk space the local history subsystem should try to maintain. More...
void	SetPointsOfInterestRangeFactor (float value)
	Sets the definitive property range (maximum-minimum) factor which determines whether a value is consider a point of interest. More...
void	SetPointsOfInterestToleranceFactor (float value)
	Sets the definitive property tolerance factor which determines whether a value is consider a point of interest. More...
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. More...
void	SetUseStandardHistoryFiles (int value)
	Instructs the server to use the so-called 'standard' set of local history files. More...

Variables
int	useMinimalStorage = FALSE
	Instructs the local history server to use a simple UTC timestamp (4-byte integer) when saving data to disk. More...
int	useMonthlyHistoryFiles = FALSE
	Instructs the local history server to keep monthly archive files instead of daily files. More...

Detailed Description

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.

Function Documentation

AppendHistoryData()

int AppendHistoryData	(	char *	eqm,
		char *	prp,
		char *	dev,
		DTYPE *	dout
	)

Inserts local history data into the local history ring buffer.

A server can insert data into the local history ring buffer directly with this call. The inserted data behave in exactly the same manner as if added via a call the the designated equipment module from the local history subsystem.

The information provided in the call MUST correspond to a registered local history element or the call will fail. The server developer can ensure that history data are inserted ONLY via this call (and not via the local history subsystem) by trapping the CA_HIST bit in the access flag within the equipment module dispatch and returning an error condition such as 'not_implemented'.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
prp	is the requested property for which a history record is being kept.
dev	is the device name for which a history record is being kept.
dout	is a reference to a DTYPE object specifying the array length, data format, timestamp and other data stamps of the history record along with the accompanying data.

Returns

0 upon success, otherwise a TINE error code.

Example:

#include "tine.h";
...
 
DBLDBL myReadbackData[100]; // data + timestamp pairs 
void myCallback(int id,int cc)
{
  DTYPE d;
  int i;
 
  if (cc != 0) return;
  // link is okay: push the data into the local history system
  memset(&d,0,sizeof(DTYPE));
  d.dFormat = CF_DOUBLE;
  d.dArrayLength = 1;
  for (i=0; i<100; i++)
  {
    d.dTimeStamp = myReadbackData[i].d2val;
    d.data.dptr = &myReadbackData[i].d1val;
    AppendHistoryData("MYEQM","MyValue","MyDevice",&d);
  }
} 
 
void myInit(void)
{
  DTYPE dout;
  HistorySpecification hspec;
  // register property "MyValue"
  memset(&dout,0,sizeof(DTYPE));
  dout.dFormat = CF_FLOAT; dout.dArrayLength = 1;
  RegisterPropertyInformation("MYEQM","MyValue",&dout,&dout,CA_READ,AT_SCALAR,10,"[0:100 V]my values",PRP_MYVALUE,NULL);
 
  // append propery "MyValue" to the local history sub-system (or use history.csv)
  hspec.pollingRate = 2000;              /* polling rate in msec */
  hspec.archiveRate = 10000;               /* archive rate in sec */
  hspec.depthShort = 300;             /* for short term storage */
  hspec.depthLong = 1;               /* for long term storage */
  hspec.heartbeat = 900;            /* archive heartbeat in sec */
  hspec.pTolerance = 0;                 /* percent tolerance */
  hspec.aTolerance = .1;                /* absolute tolerance */
  hspec.rhsServerName = "";             /* Remote Server Name */
  hspec.rhsPropertyName = "";         /* Remote Property Name */
  AppendHistoryInformation("MYEQM","MyValue","MyDevice",1,CF_DOUBLE,1,&hspec);
 
  // etc ...
 
  // start a link to another server which supplies a array of data to archive with very high resolution timestamps
  dout.dFormat = CF_DBLDBL; 
  dout.dArrayLength = 100;
  AttachLink("/TEST/SourceServer/SourceDevice","SourceProperty",&dout,NULL,CA_READ,1000,myCallback);
 
}
 
int myeqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  // ....
  switch (GetPropertyId("MYEQM",devProperty))
  {
    case PRP_MYVALUE:
      if (access & CA_HIST)
      {
        // don't let the local history sub-system in
        // as we're added the history data via other means ...
        return not_implemented;
      }
      // ...
  }
  // remaining code omitted
}

References argument_list_error, HstTblEntry::c, DTYPE::dArrayLength, and DTYPE::dFormat.

AppendHistoryInformation()

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.

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.

Note

In lieu of calling AppendHistoryInformation(), it is recommended to make use of the startup configuration file 'history.csv', in which all local history critieria can be introduced. This has the advantage that no information is hard-coded. Indeed by introducing a 'history.csv' file one can immediately instruct a server to maintain local history information (even if the server is developed and maintained by someone else!).

Returns

0 upon success, otherwise a TINE error code.

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 = 0.1;      // if data change is 10 percent or greater then write to disk
  h.aTolerance = 1.0;      // (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().

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).

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.
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().

Note

In lieu of calling AppendHistoryInformation(), it is recommended to make use of the startup configuration file 'history.csv', in which all local history critieria can be introduced. This has the advantage that no information is hard-coded. Indeed by introducing a 'history.csv' file one can immediately instruct a server to maintain local history information (even if the server is developed and maintained by someone else!).

Returns

0 upon success, otherwise a TINE error code.

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 = 0.1;      // if data change is 10 percent or greater then write to disk
  h.aTolerance = 1.0;      // (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 argument_list_error.

Referenced by AppendHistoryInformation().

ApplyHistoryFilter()

int ApplyHistoryFilter	(	int	idx,
		char *	parsableFilterString
	)

Applies a history filter to an existing local history record.

A server can filter out long term storage by applying a filter condition which must be satisfied.

Parameters

idx

is the local history record index of the history element to which the filter should by applied. (Note: this must already be allocated).

parsableFilterString

is a parsable filter string defining the filter condition. This should be of the form /<context>/<server/<device>[<property>]<comparator><value> where <comparator> is one of '=', '!=', '>', or '<' and <value> is the filter's threshold value. The filter targer address should deliver (or be able to deliver) a single numeric or string name value. If the filter string cannot be parsed of the target address does not exists, then no filter will be established.

Returns

0 upon success, otherwise a TINE error code.

GetHistoryFilesRepository()

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.

Returns

the configured history files repository location.

See also

SetHistoryFilesRepository()

GetHistoryStaticFilesRepository()

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.

Returns

the configured static history files repository location.

See also

SetHistoryStaticFilesRepository(), SetHistoryFilesRepository(), GetHistoryFilesRepository()

GetLastStoredData()

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.

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.
idx	is the targeted array index (if the history element represents an array) identifying the beginning of the range of data to retrieve.
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.

Returns

0 upon success, otherwise a TINE error code.

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 GetLastStoredDataEx().

GetLastStoredDataEx()

int GetLastStoredDataEx	(	char *	eqm,
		char *	prp,
		char *	dev,
		int	idx,
		BYTE *	data,
		int	fmt,
		int	len,
		double *	tstamp
	)

Retreives the last stored data set from disk for the given input parameters (extended call).

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. The extended call can also return the timestamp of the last stored data if required.

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.
idx	is the targeted array index (if the history element represents an array) identifying the beginning of the range of data to retrieve.
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.
tstamp	(out) will contain the TINE data timestamp of the last stored data if the call is successful and a non-NULL reference pointer is passed.

Returns

0 upon success, otherwise a TINE error code.

Referenced by GetLastStoredData().

GetStandardSpillOverSize()

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.

Returns

the additional spill over size configured (default 1000).

See also

SetStandardSpillOverSize

GetUseStandardHistoryFiles()

int GetUseStandardHistoryFiles

(

int

index

)

Returns TRUE of FALSE depending on whether the given history record index makes use of 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.

Parameters

index

is the history record index for which the setting is desired.

Returns

TRUE of FALSE depending on whether the given history record index makes use of the so-called 'standard' set of local history files.

SetHistoryFilesRepository()

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.

Parameters

path	is the desired history files repository location.

See also

GetHistoryFilesRepository()

SetHistoryStaticFilesRepository()

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.

Parameters

path	is the desired static history files repository location.

See also

GetHistoryStaticFilesRepository(), SetHistoryFilesRepository(), GetHistoryFilesRepository()

SetMaximumHistoryTableRecords()

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.

Parameters

value

is the desired maximum history table size (default is 100).

SetMinimumDiskSpaceInBlocks()

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.

Parameters

value

is the desired minimum free disk space (in blocks) to be maintained on the local history partition.

SetPointsOfInterestRangeFactor()

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.

Parameters

value

is the desired display range factor (default is 0.25).

SetPointsOfInterestToleranceFactor()

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.

Parameters

value

is the desired display range factor (default is 10).

SetStandardSpillOverSize()

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.

Parameters

value

is the desired additional spill over size (default 1000).

See also

GetStandardSpillOverSize

SetUseStandardHistoryFiles()

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.

Parameters

value

is the desired value of this setting (default: FALSE).

Variable Documentation

useMinimalStorage

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

useMonthlyHistoryFiles

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.