Commits modified values to database. NOTES: 1. Data commit is allowed only for authorized and authenticated users using a secure connection. 2. Class instance specific permissions for the current user can be fetched using the '$ACR' special property with FetchClassData.
Name of class, which data to update.
List of properties to update, prefix with RAW: to update raw values.
(System.Object[]) List of instances to be updated. For each entry, use null to create a new instance. For updates and deletes, use either the instance id (to get it, fetch RAW:Id) or an ObjectRef string returned by $REF.
(System.Object[]) List of new values. If committing multiple instances, the list size should be multiple of properties.length. When given as null the instances are deleted.
(System.Object[]) List of old values or null. If committing multiple instances, the list size should be multiple of properties.length. Old values are used to check prevent conflicting changes (occuring for example when two users want to increase value by one at the same time).
Optionalcallback: TCallback<TCommitClassDataResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
// Examples:
try
{
// Insert three new class instances
const created = cDateTime.GetServerUTC();
const result1 = await connection.CommitClassData(
"Path_AnimalInPark", // class name
["RAW:Id", "Name", "RAW:Individuals", "RAW:Updated"], // properties to commit
[null, null, null], // class instance ids (null for new instances)
[ // In this example Id is given as null to be autogenerated by the server
[null, "Sheep", 3, created], // property values for the first instance
[null, "Pig", 2, created], // property values for the second instance
[null, "Wolf", 12, created] // property values for the third instance
],
null // old values (null for new instances)
);
checkCommitResultExample(result1);
// Store RAW:Id values of the new instances for further processing
const ids : Record<string, string> = {}; //Id by Name
for(const instance of result1)
{
if(Array.isArray(instance)) // Array expected for successful Commit
{// Zero index contains Id, index 1 contains Name
ids[instance[1] as string] = instance[0] as string;
}
else console.error("Error committing instance:", instance);
}
// Update class instances
const updated = cDateTime.GetServerUTC();
const result2 = await connection.CommitClassData(
"Path_AnimalInPark", // class name
["RAW:Individuals", "RAW:Updated"], // properties to commit
[ids["Sheep"], ids["Pig"], ids["Wolf"]], // class instance Ids
[
[2, updated], // new property values for the first instance
[1, updated], // new property values for the second instance
[15, updated] // new property values for the third instance
],
[// old values - if provided, commit fails if these do not match in the data source
[3, created], // old values for the first instance
[2, created], // old values for the second instance
[10, created] // old values for the third instance
]
);
checkCommitResultExample(result2);
// Delete two class instances
const result3 = await connection.CommitClassData(
"Path_AnimalInPark", // class name
[], // properties array should be empty
[ids["Sheep"], ids["Pig"]], // class instance Ids
null, // New values as null - means that the instances are deleted
null
);
checkCommitResultExample(result3);
}
catch(e)
{// General commit failure exception handler (NOTE: instances returned in the normal result set!)
console.error("Commit operation failed: ", e);
}
// Example commit result handler
function checkCommitResultExample(result : TCommitClassDataResult)
{
// Exceptions for individual instances returned as string, committed values returned in an array
let index = 0;
for(const entry of result)
{
index++;
if(typeof entry === "string") console.error("Commit for instance", index, "failed:", entry);
else if(Array.isArray(entry)) console.log("Commit for instance", index, "succeeded:", entry);
else if(entry === null) console.log("Commit for instance", index, "succeeded",
"(Null returned when deleting, or when the class implementation does not support return values.)");
}
}
Inserts/Modifies/Removes rows into a history table.
(System.Object[]) The timestamps of updates values.
(System.Object[]) Updates values; Set to null for rows that need to be removed.
(System.UInt64[]) Statuses of updates values.
Class to fetch data from, for example use "ProcessHistory" to access normal RTDB histories.
Property to provide values for X-axis, for example use "Time" together with "ProcessHistory".
Property to provide values for Y-axis, for example use "Value" together with "ProcessHistory".
Message that will be written to the HistoryUpdateLog, leave empty if not required.
The filtering mask for the fetch; If some rows are to be deleted, the time range must be specified.
(System.Object[]) Arguments to be used in place of possible ?-chars within the wherestring. For an ordinary where predicate targeting an id or class-instance reference property, a scalar ?-argument may be either the instance id or an ObjectRef string returned by $REF when the ObjectRef can be resolved to the property's id and the predicate uses a value comparison such as Id = ?. ObjectRef strings are not resolved to ids for pattern matching with LIKE or LIKEX.
Optionalcallback: TCallback<boolean>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Returns only when client has received all the events that have been triggered so far. Do not use unless you are sure you know what you are doing.
Optionalcallback: TCallback<boolean>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Executes a class bound command by name if driver defines one with security checking. The ExecuteClassBoundCommand call should be redirected to this routine by wrapper drivers that want to apply security checking.
Class name to perform the command on.
Name of the command to execute.
Command parameters.
(System.Object[]) Array of instance ids targeted by the command. Each value may be either the instance id or an ObjectRef string returned by $REF.
Optionalcallback: TCallback<unknown>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
(Server type: System.Object)
Fetches values for selected properties of class instances filtered by wherestr -argument. For list of classes, try querying with classname "Class", for list of class properties, try querying with classname "ClassProperty".
Name of the class, which values should be fetched.
List of properties to be fetched. Prefix property name with RAW: to get raw value instead of a pre-formatted value. Use null to get raw values of all properties as objects. Use $ACR to get permissions for accessing the instance. Use $REF to get an object reference string representing the instance. Prefix property name with VISIBLE: to get current visibility as boolean (true/false) determined by VisibilityRequirement property attribute.
(System.Int32) Maximum number of rows to fetch, use -1 for unlimited.
The where mask for the fetch.
A where mask is a clause specifying a criteria for the fetch. Only instances that meet the criteria are included in the result set. The criteria consists of predicates using class properties (defined in ClassProperty class), operators and comparison values.
An example: "Name LIKE 'SYS*' AND (Type = 1 OR Type = 3)"
(Include instances whose Name starts with the string 'SYS' and whose Type is either 1 or 3.)
The syntax resembles SQL, but is not SQL. The supported operators are =, !=, >, >=, < and <=. AND, OR, LIKE, IN, IS and ORDER BY are supported however IS is used for type checking, not for null checks (eg. Unit IS System.Int32) - null checks are done by just using null like any other value (eg. Unit=null). Wildcards for LIKE are * and ?. SQL injection attacks will not work as this is not SQL.
(System.Object[]) Arguments to be used in place of possible ?-chars within where string. For an ordinary where predicate targeting an id or class-instance reference property, a scalar ?-argument may be either the instance id or an ObjectRef string returned by $REF when the ObjectRef can be resolved to the property's id and the predicate uses a value comparison such as Id = ?. ObjectRef strings are not resolved to ids for pattern matching with LIKE or LIKEX.
Optionalcallback: TCallback<TFetchClassDataResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Example on fetching instance objects:
// Fetch instance objects (containing all properties)
try
{
const result1 = await connection.FetchClassData(
"Variable", // from Variable class
null, // fetch all properties
-1, // no fetch limit
"Name LIKE ? AND NOT Type = ?", // where string
["Sawtooth*", 210] // where string arguments
);
// Result data is an array of instance objects
const data1 = result1.Data as IClassInstance[];
for(const instance of data1)
{// Instance objects always contain only RAW values
console.log(
"Id:", instance.Id,
"Name:", instance.Name,
"Type:", instance.Type,
"Description:", instance.Description
);
}
}
catch(error) { console.error(error); }
Example on fetching specific properties (supporting server formatted values):
// Fetch specific properties
try
{
const result2 = await connection.FetchClassData(
"Variable",
["RAW:Id", "Name", "Type", "Description"], // properties
100, // fetch maximum 100 instances
"Name NOT LIKE ? AND Description NOT LIKE ? ORDER BY Type, Name",
["Sine*", "*Array*"]
);
// Result data is a flat array
const data2 = result2.Data as unknown[];
for(let i = 0;i < data2.length;i += 4) // step number of properties
{// Iterate instances
console.log(
"Id:", data2[i],
"Name:", data2[i + 1],
"Type:", data2[i + 2],
"Description:", data2[i + 3]
);
}
if(result2.Truncated) console.warn("Not all instances were returned, fetch limit reached.");
}
catch(error) { console.error(error); }
Fetches class instances filtered by wherestring -argument.
Name of the class, which instances should be fetched.
(System.Int32) Maximum number of instances to fetch, use -1 for unlimited.
The where mask for the fetch.
A where mask is a clause specifying a criteria for the fetch. Only instances that meet the criteria are included in the result set. The criteria consists of predicates using class properties (defined in ClassProperty class), operators and comparison values.
An example: "Name LIKE 'SYS*' AND (Type = 1 OR Type = 3)"
(Include instances whose Name starts with the string 'SYS' and whose Type is either 1 or 3.)
The syntax resembles SQL, but is not SQL. The supported operators are =, !=, >, >=, < and <=. AND, OR, LIKE, IN, IS and ORDER BY are supported however IS is used for type checking, not for null checks (eg. Unit IS System.Int32) - null checks are done by just using null like any other value (eg. Unit=null). Wildcards for LIKE are * and ?. SQL injection attacks will not work as this is not SQL.
(System.Object[]) Arguments to be used in place of possible ?-chars within where string. For an ordinary where predicate targeting an id or class-instance reference property, a scalar ?-argument may be either the instance id or an ObjectRef string returned by $REF when the ObjectRef can be resolved to the property's id and the predicate uses a value comparison such as Id = ?. ObjectRef strings are not resolved to ids for pattern matching with LIKE or LIKEX.
Optionalcallback: TCallback<TFetchClassInstancesResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
//Example:
try
{
const result = await connection.FetchClassInstances(
"Variable",
-1,
"Name LIKE ? ORDER BY Name",
["Sine*"]
);
for(const instance of result)
{// Loop through the instances
console.log(instance.Name, instance.Path, instance.Type);
}
}
catch(error) { console.error(error); }
Fetches information on specified equipment type.
Equipment type instance id or ObjectRef string returned by $REF.
Optionalcallback: TCallback<TFetchEquipmentInfoResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Class to fetch data from, use "ProcessHistory" to access normal RTDB histories. Three special classes $MERGE, $STACK and $CALC allow combining the results of previous FetchGraphData queries into one result. Prepending class name with ! tells the server not to send response to this query (userful with $MERGE, $STACK and $CALC).
Property to provide values for X-axis, use "Time" together with "ProcessHistory".
Property to provide values for Y-axis, use "Value" together with "ProcessHistory".
Optional filter to apply on data, eg. AVG1MIN to get one minute averages, see Vtrin documentation for further info on filters.
(System.Int32) Pixels on plot area in X-direction, only used with PLOT/PLOTM filters, otherwise ignored.
(System.Int32) Pixels on plot area in Y-direction, only used with PLOT/PLOTM filters, otherwise ignored.
(System.Int32) Maximum number of values to fetch.
The where mask for the fetch.
A where mask is a clause specifying a criteria for the fetch. Only instances that meet the criteria are included in the result set. The criteria consists of predicates using class properties (defined in ClassProperty class), operators and comparison values.
An example: "Name LIKE 'SYS*' AND (Type = 1 OR Type = 3)"
(Include instances whose Name starts with the string 'SYS' and whose Type is either 1 or 3.)
The syntax resembles SQL, but is not SQL. The supported operators are =, !=, >, >=, < and <=. AND, OR, LIKE, IN, IS and ORDER BY are supported however IS is used for type checking, not for null checks (eg. Unit IS System.Int32) - null checks are done by just using null like any other value (eg. Unit=null). Wildcards for LIKE are * and ?. SQL injection attacks will not work as this is not SQL.
Ignored if class is $MERGE or $STACK. The expression to be evaluated if class is $CALC.(System.Object[]) Arguments to be used in place of possible ?-chars within where string. List of previous call ids to be merged or stacked if class is $MERGE or $STACK. List of variable names and previous calls ids if class is $CALC. For an ordinary where predicate targeting an id or class-instance reference property, a scalar ?-argument may be either the instance id or an ObjectRef string returned by $REF when the ObjectRef can be resolved to the property's id and the predicate uses a value comparison such as Id = ?. ObjectRef strings are not resolved to ids for pattern matching with LIKE or LIKEX.
Optionalcallback: TCallback<TGraphData>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Fetches data for trend plotting or similar use. This function might change in future releases as there are plans to change graph fetching to subscription based model.
// Define a base time for period truncation (alignment)
const basetime = cDateTime.CreateLocal(2300, 1, 1, 0, 0, 0, 0, 0, false, connection);
// One day period
const oneday = cTimeSpan.FromDays(1, true);
// The beginning of the day based on current server UTC time
const today = oneday.TruncateTimeFloor(cDateTime.GetServerUTC(), basetime);
try
{
const result = await connection.FetchGraphDataEx(
"ProcessHistory", // Source class
"Time", // X values property
"Value", // Y values property
10000, // Maximum fetch size (sensibility limit)
"Avg1hour", // Filter: Calculate one hour averages from the source data
basetime, // Align filter periods to base time
"Variable = ? AND Time >= ? AND Time < ?", // ProcessHistory query
["Sine Float32", today.AddDays(-7), today] // Read values from last 7 days
);
const count = result[0].length; // Number of values returned
const xvalues = result[0]; // X values array at index 0
const yvalues = result[1]; // Y values array at index 1
const statuses = result[2]; // Status array at index 2
console.log(result[4].GraphInfo.Description); // Additional info at index 4
// ProcessHistory values
for(let i = 0;i < count;i++)
{
// Convert 64 bit integer value to UTC cDateTime object
const timestamp = new cDateTime(BigInt(xvalues[i] as string), false, false, connection);
const value = yvalues[i] as number;
// 64 status bits in hexadeximal string can be examined using cValueStatus
const status = new cValueStatus(statuses[i]);
console.log(
// Convert UTC to local time and format to human readable string
timestamp.ToLocal().ToString("F"), //e.g. "Sunday, September 16, 2018 8:00:00 PM"
// Format the Y value using 3 decimal accuracy
FormatNumber(value, 3),
// Check the status validity
status.Invalid ? "Invalid" : "",
status.Questionable ? "Questionable" : ""
);
}
}
catch(error) { console.error(error); }
Class to fetch data from, use "ProcessHistory" to access normal RTDB histories. Three special classes $MERGE, $STACK and $CALC allow combining the results of previous FetchGraphData queries into one result. Prepending class name with ! tells the server not to send response to this query (userful with $MERGE, $STACK and $CALC).
Property to provide values for X-axis, use "Time" together with "ProcessHistory".
Property to provide values for Y-axis, use "Value" together with "ProcessHistory".
(System.Int32) Maximum number of values to fetch.
Optional filter to apply on data, eg. AVG1MIN to get one minute averages, see Vtrin documentation for further info on filters.
(System.Nullable`1[[System.DateTime, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]) Base time for aligning filter time periods - ignored when no filter specified or the filter does not produce periodical values
The where mask for the fetch.
A where mask is a clause specifying a criteria for the fetch. Only instances that meet the criteria are included in the result set. The criteria consists of predicates using class properties (defined in ClassProperty class), operators and comparison values.
An example: "Name LIKE 'SYS*' AND (Type = 1 OR Type = 3)"
(Include instances whose Name starts with the string 'SYS' and whose Type is either 1 or 3.)
The syntax resembles SQL, but is not SQL. The supported operators are =, !=, >, >=, < and <=. AND, OR, LIKE, IN, IS and ORDER BY are supported however IS is used for type checking, not for null checks (eg. Unit IS System.Int32) - null checks are done by just using null like any other value (eg. Unit=null). Wildcards for LIKE are * and ?. SQL injection attacks will not work as this is not SQL.
Ignored if class is $MERGE or $STACK. The expression to be evaluated if class is $CALC.(System.Object[]) Arguments to be used in place of possible ?-chars within where string. List of previous call ids to be merged or stacked if class is $MERGE or $STACK. List of variable names and previous calls ids if class is $CALC. For an ordinary where predicate targeting an id or class-instance reference property, a scalar ?-argument may be either the instance id or an ObjectRef string returned by $REF when the ObjectRef can be resolved to the property's id and the predicate uses a value comparison such as Id = ?. ObjectRef strings are not resolved to ids for pattern matching with LIKE or LIKEX.
Optionalcallback: TCallback<TGraphData>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
$MERGE class allows merging multiple histories into one structure with interpolation. Useful for histories combining multiple sources, e.g. position combining both latitude and longitude.
$STACK class allows stacking multiple histories on top of each others, i.e. calculating sum of histories at all points. This is useful when rendering stacked graphs on low-powered devices.
$CALC class allows executing arbitrary mathematical expressions on histories on the server side. This is useful for offloading some heavy computation from client side to server.
All sources for $MERGE, $STACK and $CALC calls must precede the call in same multicall. They must also be either unconsumed (i.e. not returned by prepending class name with !) or restartable. Same source can not be included multiple times, even recursively.
// Queries need to be sent in a combined call!
const combined = connection.BeginCombined();
try
{
// Define two graph data fetches using the same time range
void combined.FetchGraphDataEx(
"ProcessHistory", "Time", "Value", 10000, "", null,
"Variable=? AND Time>=? AND Time<?",
["Sine Integer8", "2001-01-01 00:00:00", "2001-01-01 00:20:00"]
);
void combined.FetchGraphDataEx(
"ProcessHistory", "Time", "Value", 10000, "", null,
"Variable=? AND Time>=? AND Time<?",
["Sawtooth Integer8", "2001-01-01 00:00:00", "2001-01-01 00:20:00"]
);
// Create a MERGE fetch
const merge = combined.FetchGraphDataEx(
"$MERGE", null, null, 10000, "", null, "", combined.CallIds
);
combined.Send(); // Send queries to server
const data = await merge; // Wait for the reply
const xvalues = data[0] as string[];
const yvalues = data[1] as number[][];
const statuses = data[2] as string[];
for(let i = 0;i < xvalues.length;i++)
{
console.log(
// Time stamp
new cDateTime(BigInt(xvalues[i])).ToLocal().ToString(),
// The first item value
yvalues[i][0],
// The second item value
yvalues[i][1],
// Combined status
StatusToString(BigInt(statuses[i]), connection)
);
}
}
catch(error) { console.error(error); }
$STACK works in similar way.
Example of $CALC:
// Queries need to be sent in a combined call!
const combined = connection.BeginCombined();
try
{
// Define two graph data fetches using the same time range
void combined.FetchGraphDataEx(
"ProcessHistory", "Time", "Value", 10000, "", null,
"Variable=? AND Time>=? AND Time<?",
["Sine Integer8", "2001-01-01 00:00:00", "2001-01-01 00:20:00"]
);
void combined.FetchGraphDataEx(
"ProcessHistory", "Time", "Value", 10000, "", null,
"Variable=? AND Time>=? AND Time<?",
["Sawtooth Integer8", "2001-01-01 00:00:00", "2001-01-01 00:20:00"]
);
// Create a CALC fetch
const calc = combined.FetchGraphDataEx(
"$CALC", null, null, 10000, "", null,
"A + B * A", // The calculation expression
[
"A", combined.CallIds[0], // data for A from the first fetch
"B", combined.CallIds[1] // data for B from the second fetch
]
);
combined.Send(); // Send queries to server
const data = await calc; // Wait for the reply
const xvalues = data[0] as string[];
const yvalues = data[1] as number[];
const statuses = data[2] as string[];
for(let i = 0;i < xvalues.length;i++)
{
console.log(
// Time stamp of the calculated value
new cDateTime(BigInt(xvalues[i])).ToLocal().ToString(),
// The calculated value
yvalues[i],
// Calculated value status
StatusToString(BigInt(statuses[i]), connection)
);
}
}
catch(error) { console.error(error); }
Fetches NLS translations
Section to fetch language strings from.
Key within section or NULL.
SubKey within section/key or NULL.
Specifies what to do if translation is not found in desired language - should the fallback mechanism stop to english or return translation in any language.
Set true to include 'Standard' -section translations (containing strings like Ok, Cancel, Apply, Properties, ...).
(System.Int32) LanguageId to fetch language strings for or NULL to fetch for the strings for the currently active language. 32bit field, upper 16bits contains primary langid and lower 16bits sublangid.
Optionalcallback: TCallback<TFetchLanguageStringsResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
const entries = await connection.FetchLanguageStrings(
"Enums",
"Filter Functions",
null,
false,
false,
null,
);
for(const entry of entries)
{
console.log(entry.SubKey, entry.Text, entry.LongText);
}
Gets a list of formatted class property values from given raw values.
Name of the class
Names of the properties
(System.Object[]) RAW values of the properties. For direct scalar class-instance reference properties, the value may be an instance id or an ObjectRef string returned by $REF. For other properties, provide the native value expected by the property's converter.
Optionalcallback: TCallback<TGetFormattedValuesResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Gets a key that can be used to pass the session to another application.
Optionalcallback: TCallback<string>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Gets a list of values that can be used to fill a drop down or similar control when editing a value on a property of an instance.
Name of the class, which instance is being modified
Name of the property, which is being modified
What user has typed so far, or null. Can contain wildcards * and ?.
Values of other modified properties in the instance. For direct scalar class-instance reference properties, the value may be an instance id or an ObjectRef string returned by $REF. For other properties, provide the native value expected by the property's converter.
(System.Int32) Maximum number of values to fetch, -1 for unlimited. If the result set is truncated due to this limit, the 'Truncated' value of the result structure is set to true.
Optionalcallback: TCallback<TGetStandardValuesResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Allows admin user to impersonate some other user. The session is turned to be authenticated to given user irreversibly.
Optionalcallback: TCallback<boolean>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Fetches stored set of properties from underlying database. The callback gets an object containing the properties read from the database.
(System.Guid) Bag Id - Unique id for the property bag to fetch.
(System.Nullable`1[[System.Guid, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]) User Id, whose properties are to be fetched. Use null for current user.
(System.DateTime) Time of the property bag version to fetch.
Optionalcallback: TCallback<IPropertyBag>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
(Server type: ABB.Vtrin.cPropertyBag)
Sets the credentials that should be used when performing security checks for this frame. Only useful if passing multiple calls in the same frame. Supplying additional credentials may never give more access rights, only take some away.
(ABB.Vtrin.Drivers.cDriverSkeleton+cAccessInfo) Extra credentials to use when executing the consequtive calls in the same frame
Set true to persist the extra credentials until cleared with a second call to this function
Optionalcallback: TCallback<boolean>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Subscribes to listening changes of one or more instances. The callback providing an event object is called whenever change to subscribed instances is detected (until Unsubscribe is called). The callback function for this call will be called multiple times as long as unsubscribe is called.
Name of the class, which changes should be sent. Set to null to get changes of all non-expiration based classes. When null, the properties parameter is ignored.
List of properties to be sent for changed instances, prefix with RAW: to get raw value instead of a pre-formatted value. Set to null to get full instances instead of the values of selected properties. Using $ACR or RAW:$ACR will fetch the access control rights for the instance. Using $REF will return the object reference string representing the instance. Prefix property name with VISIBLE: to get current visibility as boolean (true/false) determined by VisibilityRequirement property attribute.
The where mask for the subscription.
A where mask is a clause specifying a criteria for the fetch. Only instances that meet the criteria are included in the result set. The criteria consists of predicates using class properties (defined in ClassProperty class), operators and comparison values.
An example: "Name LIKE 'SYS*' AND (Type = 1 OR Type = 3)"
(Include instances whose Name starts with the string 'SYS' and whose Type is either 1 or 3.)
The syntax resembles SQL, but is not SQL. The supported operators are =, !=, >, >=, < and <=. AND, OR, LIKE, IN, IS and ORDER BY are supported however IS is used for type checking, not for null checks (eg. Unit IS System.Int32) - null checks are done by just using null like any other value (eg. Unit=null). Wildcards for LIKE are * and ?. SQL injection attacks will not work as this is not SQL.
(System.Object[]) Arguments to be used in place of possible ?-chars within where string. For an ordinary where predicate targeting an id or class-instance reference property, a scalar ?-argument may be either the instance id or an ObjectRef string returned by $REF when the ObjectRef can be resolved to the property's id and the predicate uses a value comparison such as Id = ?. ObjectRef strings are not resolved to ids for pattern matching with LIKE or LIKEX.
Optionalcallback: TCallback<TSubscribeChangesResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Returns Call id to use for unsubscribing the changes later time. Example:
// Retrieve CurrentValueId for multiple Variables
const cvids = await connection.FetchClassData(
"Variable", ["RAW:CurrentValueId"], -1, "Name LIKE ?", ["Sawtooth *"]
);
// Create subscription to multiple CurrentValue instances
const subid = connection.SubscribeChanges(
// Data class
"CurrentValue",
// Subcribe to specific properties
["RAW:Id", "RAW:Time", "RAW:Value", "RAW:Status"],
// Include CurrentValues of all Sawtooth variables
"Id IN ?", [cvids.Data],
(event : TSubscribeChangesResult) =>
{// The callback called when the server sends a new data event
switch(event.Type)
{
case cChangeEventType.Insert: // <- New instance inserted
case cChangeEventType.Modify: // <- Existing instance updated
console.log("CurrentValue update",
"Id:", event.Values[0], // Values contains the requested properties
"Time:", new cDateTime(BigInt(event.Values[1] as string)).ToLocal().ToString(),
"Value:", event.Values[2],
"Status:", StatusToString(BigInt(event.Values[3] as string), connection)
);
break;
case cChangeEventType.Delete: // <- The CurrentValue instance was deleted
console.log("CurrentValue deleted", "Id:", event.Values[0]);
break;
case cChangeEventType.CacheInvalidated: // <- Cache on server invalidated
// Somewhat rare event, only relevant in some cases
console.warn("Cache invalidated - refetch all data!");
reinitialize();
break;
}
},
(err : string) => { console.error(err); } // <- Error handler
);
// Important: When subscription is no longer needed Unsubscribe should be called
async function dispose()
{
await connection.Unsubscribe(subid); // Unsubscribe using the subscription id
console.log("Unsubscribed", subid);
}
Subscribes to listening of connection health events. This is meaningful only if the server operates in 'gateway mode', meaning it is connected to another server, in which case these events provide information on that connection's (and any subconnections) health.
Optionalcallback: TCallback<TSubscribeConnectionHealthEventsResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Subscribes an equipment session. All the equipment and their properties are processed by the server and wanted property subscriptions are returned to the client by the server.
The definition of equipment(s) to use in the equipment session. See documentation for a detailed description of a equipment definition.
Optionalcallback: TCallback<unknown>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Subscribes to polling of a history value. The callback is called whenever change to target value is detected (until unsubscribe is called). Note that unlike with other calls, the callback function for this call will be called multiple times as long as unsubscribe is called.
Name of the class, which the fetch is to be executed on.
Name of the time property in the class defined by the classname.
Name of the value property in the class defined by the classname.
Optional filter to apply on data, eg. AVG1MIN to get one minute averages, see Vtrin documentation for further info on filters.
The where mask for the subsciption.
A where mask is a clause specifying a criteria for the fetch. Only instances that meet the criteria are included in the result set. The criteria consists of predicates using class properties (defined in ClassProperty class), operators and comparison values.
An example: "Name LIKE 'SYS*' AND (Type = 1 OR Type = 3)"
(Include instances whose Name starts with the string 'SYS' and whose Type is either 1 or 3.)
The syntax resembles SQL, but is not SQL. The supported operators are =, !=, >, >=, < and <=. AND, OR, LIKE, IN, IS and ORDER BY are supported however IS is used for type checking, not for null checks (eg. Unit IS System.Int32) - null checks are done by just using null like any other value (eg. Unit=null). Wildcards for LIKE are * and ?. SQL injection attacks will not work as this is not SQL.
(System.Object[]) Arguments to be used in place of possible ?-chars within where string. For an ordinary where predicate targeting an id or class-instance reference property, a scalar ?-argument may be either the instance id or an ObjectRef string returned by $REF when the ObjectRef can be resolved to the property's id and the predicate uses a value comparison such as Id = ?. ObjectRef strings are not resolved to ids for pattern matching with LIKE or LIKEX.
(System.Nullable1[[System.TimeSpan, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]) Interval to poll for new values. Default one minute. @param {unknown} timeshift (System.Nullable1[[ABB.Vtrin.cAdvancedTimeSpan, VtrinLib, Version=1.1.0.0, Culture=neutral, PublicKeyToken=null]]) TimeShift when fetching the values, relative to current time. Default 0.
(System.Nullable`1[[System.DateTime, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]) Basetime when fetching periodical data using filters. Default 2300-01-01.
Optionalcallback: TCallback<TSubscribeHistoryValueResult>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Returns Call id to use for unsubscribing the changes later time.
Subscribes a data push ability. Once subscribed, you can utilize web socket connection for pushing the values using the returned subscription id so that you only pass the data values in further calls.
Name of the target class, which will receive the data.
(System.Object) Target instance id, ObjectRef string returned by $REF, or supported instance name. Required for pushtype 1 (Update), 2 (ForceUpdate), and target-bound 3 (ProcessValue); unused for 0 (Insert) and class-level or multi-variable 3 operations. Pass null when unused.
List of properties to set.
(System.Int32) Type of push operation 0=Insert, 1=Update, 2=ForceUpdate, 3=ProcessValue.
Optionalcallback: TCallback<number>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
(Server type: System.Double)
Unsubscribes listening to changes that have been previously subscribed with Subscribe -call.
(System.Int64) Call id of subscription to cancel.
Optionalcallback: TCallback<boolean>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Store the subscription id when subcribing (example):
const subid = connection.SubscribeChanges(
"Path",
["RAW:Id", "Name", "Parent"],
"Name LIKE ?", ["Builtin.*"],
changehandler,
errorhandler
);
When the subscription is no longer needed call Unsubscribe with the subscription id (example):
async function dispose()
{
await connection.Unsubscribe(subid);
console.log("Unsubscribed", subid);
}
Writes a set of properties to underlying database. The call back gets boolean true on successful commit (there is no need to check the value as the exception callback will be fired on failure).
(ABB.Vtrin.cPropertyBag) PropertyBag containing the common properties to write.
(ABB.Vtrin.cPropertyBag) PropertyBag containing the user specific properties to write.
(System.Object) Bag Id - Unique id for the property bag.
(System.Nullable`1[[System.Guid, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]) User Id, whose properties are to be saved. Use null for current user.
Optionalcallback: TCallback<boolean>Function called when the requested operation is completed.
Optionalexceptionhandler: TExceptionFunction called in case the requested operation causes an error.
Server API Interface