Methods - Stateless and Stateful Interface

Below are listed the SCI methods available in the API using the stateless interface, including the parameters and example code for each method.

CheckCredentials

Checks if security credentials are valid. Returns true if access to root ("/") object is granted for the given security credentials.

Table 1. CheckCredetials Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

//the following call return true if:
//profile exists and password is correct and profile has LIST access granted for root ("/") object
bool result = sli.CheckCredentials(new SecurityCredentials() { ProfileName = "so", Password = "inmation" });

CreateObject

Create an inmation object using the stateless interface

Table 2. CreateObject Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

parentPath

path of parent object as a string

items

list of objects to create, uses ObjectItem container class for inmation objects (properties for object set using PropertyItem container class for object properties)

timeout

Timeout in milliseconds (default 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

//First create path of the parent object
string path = "/";

//Then create name of the object
string name = "General";

//Define the object to create (in this case lets create new Profile)
ObjectItem obi = new ObjectItem(string.Empty);
obi.ClassType = SciModelClasses.MODEL_CLASS_PROFILE;
obi.ObjectType = SysObjectType.OT_OBJECT;
obi.Model = SciModelScope.MODEL_SCOPE_ACCESS;

//Define  manadatory property value
PropertyItem p1 = new PropertyItem();
p1.RelativePath = "ObjectName";
p1.Value = name;

//Define additional property (its not mandatory property)
PropertyItem p2 = new PropertyItem();
p2.RelativePath = "ObjectDescription";
p2.Value = "description";
obi.Properties = new List<PropertyItem> { p1, p2 };
List<ObjectItem> lioi = new List<ObjectItem> { obi };

//Now create the object

Result result = sli.CreateObject(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, lioi);

DeleteObject

Delete an inmation object using the stateless interface

Table 3. DeleteObject Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

item

Object to delete, instance of ObjectItem class including the path of the object

timeout

Timeout in milliseconds (default 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(
  new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 }
  );

//Now delete the object and all children
//Note that this also deletes all history data
Result result = sli.DeleteObject(
  new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
  new ObjectItem("/System/Core/Item1")
  );

DisableObject

Disable an inmation object using the stateless interface

Table 4. DisableObject Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

item

Object to disable, instance of ObjectItem class including the path of the object

timeout

Timeout in milliseconds (default 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(
  new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 }
  );

//now disable the object
Result result = sli.DisableObject(
  new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
  new ObjectItem("/System/Core/Item1")
  );

EnableObject

Enable an inmation object using the stateless interface

Table 5. EnableObject Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

item

Object to enable, instance of ObjectItem class including the path of the object

timeout

Timeout in milliseconds (default 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(
  new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 }
  );

//now enable the object
Result result = sli.EnableObject(
  new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
  new ObjectItem("/System/Core/Item1")
  );

Find

Calls a server side search for inmation objects

Table 6. Find Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

search

String to be searched for in object name or object path

model

SciModelScope class, define the model to search for objects in (I/O Model, KPI Model etc.)

dynonly

Set this to true, to find only objects with dynamic property (excludes static object types, like folders)

fullpath

Set this to true, if the search parameter contains a full path to an object

foundItems

List of found objects, list of ObjectItem containers

timeout

Timeout in milliseconds (default = 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig());

 //list of ObjectItem to store search results
List<ObjectItem> items;

//define parameters for Find method
string searchFor = "localhost";
SciModelScope scope = SciModelScope.MODEL_SCOPE_IO;
bool searchOnlyForDynamicObjects = false;
bool searchForFullPath = false;

//query for the objects
//note that properties of the object are not returned
//use GetObjectItem() or ReadValue() to request properties of the object
Result r1 = sli.Find(
  new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
  searchFor,
  scope,
  searchOnlyForDynamicObjects,
  searchForFullPath,
  out items);

if (r1.Succeeded())
{
  foreach (var item in items)
  {
    Console.WriteLine(item.TagName);
    Console.WriteLine(item.Path);
   }
}

GetChild

Retrieves the specified child object of a given parent

Table 7. GetChild Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

parentPath

Path of parent object, in string format

childName

Object name of child to fetch as a string

child

Fetched child object as an ObjectItem object

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

// set path to parent object
string parentPath = "/System/Core";

// set ObjectName of the child object string child
Name = "localhost";
ObjectItem child;

// request child object information
// note that properties of the object are not returned
// use GetObjectItem() or ReadValue() to request properties of the object
Result r1 = sli.GetChild(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, parentPath, childObjectName, out child);

GetChildren

Retrieve a list of children for a specified object

Table 8. GetChildren Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

parentPath

Path of parent object, in string format

children

Fetched children objects as a list of ObjectItem objects

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

// create the path to the parent object
string parentPath = "/System/Core";
List<ObjectItem> children;

// try to retrieve list of all children
var r1 = sli.GetChildren(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, parentPath, out children);

GetEventHistory

Retreives event history from the repository for specified time period using MongoDB query operators to filter results.

Table 9. GetEventHistory Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

start

Beginning of period to read as DateTime object

end

End of period to read as DateTime object

aeEventList

Retrieved events as List of AeEvent objects

eventDataFilter

MongoDB query operators to be applied. Instance of the FilterDescription class. Default is null - no filters applied

timeout

Timeout in milliseconds (default = 1000)

Example Code

// create the stateless call interface object
StatelessInterface sli = new StatelessInterface(tcpcfg);

// create list of event to generate
List<AeEvent> aeEventList = new List<AeEvent>();

// create a filter definition
FilterDefinition filter = new FilterDefinition();
filter.AddLogicalAndClause(MongoComparisonOperators.MCO_EQ, "datakey1", "value1");
filter.AddLogicalAndClause(MongoComparisonOperators.MCO_EQ, "datakey2", "value2");

// run api call
Result result = sli.GetEventHistory(credentials, DateTime.UtcNow - TimeSpan.FromHours(1), DateTime.UtcNow, out aeEventList, filter);

GetHistoricalFrame

Writes a list of object dynamic properties' values according to passed arguments

Table 10. GetHistoricalFrame Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

HistoryFrameItem

Container object hosting read parameters (including start and end parameters after a successfull call)

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

// set path to object
string path = "/System/Core/Item1";

// Container object hosting read parameters (including start and end parameters after a successfull call)  HistoryFrameItem item = new HistoryFrameItem();
item.Path = path;

// request start and end timestamps of historical data
Result result = sli.GetHistoricalFrame(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, item);

GetObjectItem

Retrieves a container object ObjectItem instance for an inmation object

Table 11. GetObjectItem Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

path

Path of the object you wish to get, in string format

fullGet

Set to true if all properties of the object should be retrieved in the same call

oItem

Fetched object as an instance of the ObjectItem class

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

//set path to object
string path = "/System/Core/localhost";

// set this to true, if all properties of the object should be fetched in the same call
bool fullGet = true;

// the object container
ObjectItem oItem;

// request object information
Result r1 = sli.GetObjectItem(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, fullGet, out oItem);

GetParent

Retrieves the parent object of a specified child object

Table 12. GetParent Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

path

Path of the child object who’s parent you wish to get, in string format

parent

Fetched parent object as an instance of the ObjectItem class

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig());

// set path to child object
string path = "/System/Core/localhost";
ObjectItem parent;

// request parent object information
// note that properties of the object are not returned
// use GetObjectItem() or ReadValue() to request properties of the object
Result r1 = sli.GetParent(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, out parent);

GetUserState

Reads the current value of an object’s user state

Table 13. GetUserState Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

path

Path of the object you wish to get, in string format

states

User states of the object as an instance of the ModUserState class

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

// set path to object
string path = "/System/Core/localhost";

// User states are stored in array instance of ModUserState class ModUserState[] states;
// request user state of the object
Result r1 = sli.GetUserState(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, out states);

ReadHistoricalData

Read History values for a specified time range

Table 14. ReadHistoricalData Parameters
Name Description

historicalData

Result set for the retrieved historical items as an instance of the HistoryResponse class

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

start

Beginning of period to read as DateTime object

end

End of period to read as DateTime object

forSteppedLine

ForSteppedLine parameter determines how intervals with no value will be treated during creation of BestFit aggregates (Default: False)

numberOfIntervals

Number of Intervals to be returned

items

Definition of the item for which history will be retrieved, instance of HistoricalDataItem class (containing path to item)

treatUncertainAsBad

Indicates how data with a StatusCode 'Uncertain' is treated with respect to Aggregate calculations (Default: True)

percentageBad

Indicates the minimum percentage of bad data in a given interval required for the StatusCode for to be set to Bad (Default: 100)

percentageGood

Indicates the minimum percentage of Good data in a given interval required for the StatusCode to be set to Good (Default: 100)

useSlopedExtrapolation

Indicates how the server interpolates data when no boundary value exists (Default: False)

rawBoundvalue

This argument takes effect only if the requested number of intervals is 1 (one), and it only affects the Raw aggregate. If this argument is true, bounding values are returned. The bounding values are defined by the OPC classic and OPC UA standards as closest values outside the requested interval, if the values at the exact start and end time of the intervals are absent

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
string itemPath = "/System/Core/Item1";

// Create item definition for history read call, contains path and aggregate that is used
HistoricalDataItem historyItem = new HistoricalDataItem(itemPath);
historyItem.Aggregates = new Aggregates[] {Aggregates.AGG_TYPE_INTERPOLATIVE};

HistoryResponse historyResponse;

// Read historical data
Result result = sli.ReadHistoricalData(
       out historyResponse,
       new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
       DateTime.UtcNow.AddDays(-1),
       DateTime.UtcNow,     //End time
       false,
       10,
       new HistoricalDataItem[] { historyItem },
       true,
       100,
       100,
       false
       false);

History calls made in system:inmation, using the SCI or otherwise, are compliant with the OPC UA Historical Access specification. For more information please refer to the OPC Foundation website.

ReadValue

Reads the value of an item using the stateless interface

Table 15. ReadValue Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

item

Object hosting the read parameters and the read value after a successful call, instance of the ReadItem class

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

// pass credentials of the system owner and read
Result result = sli.ReadValue(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, new ReadItem("/System/Core/Item1"));

RunScript

Run a Lua script in the context of a specific object in the tree. The script execution is similar to the script execution in Action Items, but the result of the script is returned in the ReadItem object and NOT written to the object. The path of the ReadItem is used for specifying the script context. The Lua script can use any Lua libraries available to the object provided in the script context.

Table 16. RunScript Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

script

Lua script to be run, defined as a string

items

List of ReadItem objects. Each ReadItem object in the list can contain a path that specifies script context. If multiple items are provided, the script will be executed on each of these context’s. The scripts results are returned in the ReadItem results. If no path is provided for a ReadItem, the script runs on system level.

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

// create the ReadItem container based on given object path
// it will be used for the script result
ReadItem readItem = new ReadItem("/System/INMWS011/Examples/DemoData/ProcessData/DC4711");
List<ReadItem> readItems = new List<ReadItem> { readItem };

// define lua script
string script = "return math.random";

// Run the script in the context of the objects provided in containers
// the script result will NOT be written to the object
Result result = sli.RunScript(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, script, readItems);

RunScript is particularly useful when you want to use functionality that is available in Lua but not the SCI, for example, the setreferences Lua function. To set a security reference on an object in the I/O Model the following example code can be used:

public void assignProfile(string path, string profilepath)
{
    ReadItem scriptcontext = new ReadItem(path);

    string scriptcode = "";
    scriptcode += "syslib.setreferences(syslib.getself(), " + Environment.NewLine;
    scriptcode += "   {" + Environment.NewLine;
    scriptcode += "      { " + Environment.NewLine;
    scriptcode += "         path='" + profilepath + "', " + Environment.NewLine;
    scriptcode += "         type = (syslib.model.codes.ReferenceType.SECURITY << 32) -- this is actually == 0, but it is here to show the principle" + Environment.NewLine;
    scriptcode += "                | syslib.model.flags.SecurityAttributes.INHERITABLE " + Environment.NewLine;
    scriptcode += "                | syslib.model.flags.SecurityAttributes.READ " + Environment.NewLine;
    scriptcode += "      }" + Environment.NewLine;
    scriptcode += "   })" + Environment.NewLine;

    // This overwrites the current profile assignments!!
    // if you want to add profiles, first use syslib.getreferences in the lua script above!
    Result res = insi.RunScript(creds, scriptcode, new List<ReadItem>() { scriptcontext });
}

References are a 64bit mask, upper 32bit contain the ReferenceType and lower 32bit contain the SecurityAttributes (only valid for security references).

SetEvent

Set an event or events to a source according to the OPC specification

Table 17. SetEvent Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

aeEventList

List of AeEvent objects. Each instance of the AeEvent class requires the event source path, message, severity code and timestamp to be defined. The event type and event state can also be defined (defaults are simple event type and enabled state respectively).

timeout

Timeout in milliseconds (default 1000)

Example Code

// create the stateless call interface object
StatelessInterface sli = new StatelessInterface(tcpcfg);

// events need to be written to object of type script events
string pathScriptEvents = "/System/CoreVM/Examples/DemoData/Events/ScriptEvent1";

// create list of event to generate
List<AeEvent> aeEventList = new List<AeEvent>();

// declare event and add to list
AeEvent event1 = new AeEvent(pathScriptEvents, "Message 1", 500, DateTime.UtcNow, EventNewState.OPC_CONDITION_ACTIVE);
event1.AddEventData("datakey1", "value1");
event1.AddEventData("datakey2", "value2");
aeEventList.Add(event1);

// Run SetEvents call
Result result = sli.SetEvents(credentials, aeEventList);

UpdateObject

Update inmation objects using the stateless interface

Table 18. UpdateObject Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

oItem

Object to be updated, instance of the ObjectItem class containing path of update object and properties to update

timeout

Timeout in milliseconds (default = 1000)

Example Code:

// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

// create the object item container object based on given path
string path = "/System/Core/Item1";
ObjectItem oItem = new ObjectItem(path);

// Prepare data to modify "ObjectDescription"
string relativePath1 = "ObjectDescription";
PropertyItem property1 = new PropertyItem() { RelativePath = ".ObjectDescription", Value = "TestObject" }

// Add "PropertyItem" to "Properties" collection of the "ObjectItem"
oItem.Properties.Add(property1);

// Now update the object
Result result = sli.UpdateObject(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, oItem);

UpdateProperty

Updates a list of properties according to passed arguments

Table 19. UpdateProperty Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

item

Property to be updated, instance of the UpdatePropertyItem class

timeout

Timeout in milliseconds (default = 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

//First create the "ClassDefinition" object for the selected class type
ClassDefinition classDefinitionef = new ClassDefinition(SciModelClasses.MODEL_CLASS_GENITEM);

//Then create "PropertyDefinition" object for selected property. Use relative path as a parameter.
PropertyDefinition propertyDefinition = classDefinitionef.GetPropertyDefinition("ObjectDescription");

//Then create "UpdatePropertyItem" object
UpdatePropertyItem property = new UpdatePropertyItem();

//Set "PropertyDefinition" property
property.PropertyDefinition = propertyDefinition;

//Set path to the object containing the property which will be updated
property.Path = "/System/Core/Item1";

//Set new property value
property.Value = "New description";

//Now update property
Result rs = sli.UpdateProperty(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, property);

WriteHistoricalData

Writes a list of object dynamic properties' values according to passed arguments

Table 20. WriteHistoricalData Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

items

List of items containing VQT data, instances of the HistoryWriteItem class

timeout

Timeout in milliseconds (default = 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

string itemPath = "/System/Core/h";

//Create item containing all data needed
HistoryWriteItem witem = new HistoryWriteItem();

//Set item path
witem.Path = itemPath;

//Prepare list of values to write
List<VQT> list = new List<VQT>();

VQT v1 = new VQT();
v1.Value = EmptyValue.Value;
v1.Timestamp = DateTime.UtcNow.AddSeconds(-10);
v1.QualityMask = QualityMaskCodes.GoodNoData; list.Add(v1);

VQT v2 = new VQT();
v2.Value = EmptyValue.Value;
v2.Timestamp = DateTime.UtcNow.AddSeconds(-5);
v2.QualityMask = QualityMaskCodes.Bad; list.Add(v2);

VQT v3 = new VQT();
v3.Value = 44; v3.Timestamp = DateTime.UtcNow;
v3.QualityMask = QualityMaskCodes.Good; list.Add(v3);
witem.Values = list;

//now write historical data
Result re = sli.WriteHistoricalData(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, new List<HistoryWriteItem> { witem }, 1000);

WriteValue

Write values to an object using the stateless interface

Table 21. WriteValue Parameters
Name Description

credentials

Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class

item

Specific write parameters for the item. instance of the WriteItem class containing path and value

mode

Write mode specification

packDelay

Number of writes to group

suppressAuditWrite

Set to false to prevent creation of log entry for the write

enforceDa20Write

Set to true to force a write command using the OPC DA 2.0 specification

timeout

Timeout in milliseconds (default = 1000)

Example Code:

//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });

//Create the write item container object based on given object path.
//Note that no property is indicated in the path, because this method
//is only used to modify a value of the ItemValue property.
//Note that the value to be written is also passed here.
string path = "/System/CoreVM/Examples/DemoData/ProcessValues/Static";

WriteItem writeItem = new WriteItem(22, path);

//now write the value to the item
Result result = sli.WriteValue(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, writeItem);
//now write quality and timestamp with empty value
writeItem = new WriteItem(EmptyValue.Value, QualityMaskCodes.Uncertain, DateTime.UtcNow, path);
result = sli.WriteValue(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, writeItem);