WriteHistory

(Historian Manager Library)

Description: Interface to write tag history.
Returns: Numeric
Usage: Script Only.
Function Groups: Log
Related to: EditData | GetTagHistory
Format: \HistorianManager.WriteHistory(TagObj[, TimeStamp, Data, HistorianObj, BroadcastMode])
Parameters:  
TagObj
Required. The tag instance for which the data is to be written
TimeStamp
Optional UTC timestamp.
If invalid, a timestamp will be generated using the current time.
If the number of records to be written is 1 then this should be a simple value.
If several records are to be written, this should be a simple array having a size that matches the number of records.
Data
Optional data values to record.
If invalid, current values from TagObj will be used. Otherwise, this may be:
  • A simple value to log a single variable.
  • A simple array, the size of which must match the number of records to write if the number of variables for each record is 1. Otherwise, this must match the number of logged variables for each record.
  • If logging attribute data, this must be an array of Value and Value!, where Value! is a bitwise value specifying attributes such as Manual Data and Questionable. Refer to

Data from an I/O and Calculations tag will always include attribute data and must always be provided as an array of Value and Value!.

  • An array of arrays - to be used only if the number of logged variables for each record (NumLogVars) is > 1 and the number of records to record (NumRecords) is > 1. The containing array size must match NumLog Vars and the nested array size must match NumRecords. See examples.
HistorianObj
An optional instance of the Historian tag used to log this value. If invalid, TagObj\HistorianName will be used.
BroadcastMode
An optional Boolean value. If TRUE, then the history is automatically relayed to all Historian-potential servers. Defaults to FALSE.
Comments:

In order to ensure that the history is successfully written, this function must be called with the same data on all Historian-potential servers, (which can be done by calling it on all workstations,) unless BroadcastMode is TRUE, in which case it need only be called on exactly one workstation (any workstation).

Possible return values are as follows:

    -1 if the number of timestamps passed in does not match the number of data entries passed in.

     0 otherwise. This does not indicate that the data was written, just that the above condition on the parameters held true.

Examples:

Simple case:

\HistorianManager\WriteHistory(TagObj, TimestampInUTC, Value);

More complex use case:

Given a tag with two logged variables, defined as:

Value(5) 
Comment(6)
\HistorianManager\WriteHistory(TagObj, TimestampsInUTC, DataArray);

Note that, when building the array of arrays, the order is important. The values should correspond to the variable declared alphabetically by variable class type. Thus, Value(5) comes before Comment(6). See: Data Logged or Trended Variables in Tag Modules.