RTDB Driver Command Classes

UpdateHistory

UpdateHistory is a command class to maintain timeseries history data, no base table. It is not stored anywhere. It lets user write, update, or delete values within a time range. Typical though process is:

Choose what to update: a Variable, or an equipment Path and Property.
Choose the time range ( StartTime to EndTime)
Give the values for that time range (StartTime and EndTime )
Choose whether existing data may be overwritten.
Submit the request. The history is updated

Parameters for procedure UpdateHistory:

Name	Type	Description	Options/values
Variable	positive integer (uint32)	Destination variable to update. If set, `Path`and `Property`are ignored	Variable's IDs
Path	GUID	Equipment instance. Used only when `Variable` is not set.
Property	text	Name of the historized equipment property. Used with `Path`.	Only historized properties on the path's equipment class
History	positive integer (uint32)	Target history table	Defaults to the variable's `TargetHistory` or the equipment property's target history. Falls back to `CurrentHistory`
Scenario	positive integer (uint32)	Scenario to update	If set, the history name becomes <History>_SC<ScenarioId>_COMB
ItemType	integer (int32)	Kind of item being updated.	See `ItemType` table below.
CallMode	integer (int32)	How the user made the selection.	See `CallMode` table below.
Function	integer (int32)	Operation to run	0 (none), 1 (get defaults), 2 (update), 3 (delete)
StartTime	DateTime	Start date time of the range.	UTC
EndTime	DateTime	End date time of the range	UTC
StartValue	Any value (object)	Value at the start time.
EndValue	Any value (object)	Value at the end time.
AllowOverwriting	boolean	Whether existing values may be overwritten	`true` or `false`
Comment	text	Comment stored with the update	The driver adds update information to it.

ItemType

General purpose application should pass this as zero (if “caller” is Vtrin, a correct item type must be passed)

Value	Name
1	`Area`
2	`StackedArea`
6	`StackedColumn`
7	`StackedColumnOrdered`
8	`ClusteredColumn`
9	`Trend`
10	`Marker`
11	`XYScatter`
13	`LineRegression`
14	`ColumnWithHStatus`
15	`HStatus`
20	`Separator`
21	`Info`
22	`Gannt`
23	`GanntStatus`
24	`Limit`

CallMode

This should usually be passed as 1 (C_VirtualHistoryUpdate::m_kSpan). The other values are mainly for special purposes for Vtrin user interface.

The value 3 (m_kPoint) can be used for management purposes. It is a so called pointwise update that can be used for inserting or updating or deleting a single history sample. The application must itself be aware of the effects of history compression of the resulted operation.

Value	Name
0	`None`
1	`SingleCell`
2	`SingleColumn`
195	`SingleRow`
4	`SingleRowList`
9	`Free`
10	`MultiColumn`
203	`MultiRow`
204	`MultiRowList`
137	`FreeWithRowHighlight`
140	`MultiRowListWithHighlight`

Examples of UpdateHistory usage

var uh = driver.Classes["UpdateHistory"].Instances.Add();
uh["History"] = driver.Classes["History"].Instances.GetInstanceByName(historyName);
uh.SetRawPropertyValue("Variable", variableId);
uh.SetRawPropertyValue("StartValue", 13.0);
uh.SetRawPropertyValue("EndValue", 13.0);
uh.SetRawPropertyValue("CallMode", 1);    // SingleCell
uh.SetRawPropertyValue("Function", 2);   // update function
uh.SetRawPropertyValue("ItemType", 9);   // Trend
uh.SetRawPropertyValue("StartTime", start);
uh.SetRawPropertyValue("EndTime", end);
uh.SetRawPropertyValue("Comment", "no comment");
uh.SetRawPropertyValue("AllowOverwriting", false);
uh.CommitChanges();

POST https://myhost/odata/UpdateHistory
Content-Type: application/json
{
  "Variable": <variable ID>,
  "Function": 2,
  "ItemType": 9,
  "CallMode": 1,
  "StartTime": "2025-01-01T00:00:00Z",
  "EndTime": "2025-01-01T06:00:00Z",
  "StartValue": 13.0,
  "EndValue": 13.0,
  "AllowOverwriting": false,
  "Comment": "From OData"
}

-- 1. Create a variable. The variable used in this example is "TestUpdateHistory".
-- 2. Save below SQL script to a file.
-- 3. Execute the sql-file using following command: 
--        praocurr <RTDB location> --vtrin -script MyScript.sql

INSERT INTO UpdateHistory([TGT:Variable], ItemType, CallMode, Function, AllowOverwriting, [TGT:History],  StartTime_UTC, EndTime_UTC, StartValue, EndValue) VALUES('TestUpdateHistory', 9, 1, 2, 1, 'CurrentHistory', { ts '2026-11-09 12:00:00.0000000'}, { ts '2026-11-09 13:00:00.0000000'}, '(Double)-1.5', '(Double)-1.5');

1. Create a variable
2. Right click it -> Send -> Trend
3. Highlight a range on the trend. This is for the time range, StartTime and EndTime
4. Choose the variable from the trend's list.
5. Assign StartValue and EndValue next to start's and end's date time.
6. Click commit
7. You may give comment and check "Allow overwriting the values after updating".
8. Click OK

(Not available yet)