Data

This event is used to obtain Tag value changes asynchronously.

Only Tags that have been added will be monitored for Tag value changes. You can use the AddTag or AddTags method to add Tags.

See example: Read Tag values

Signature:

public delegate void ValuesChangedAllEventHandler(string[] Tags, object[] Values, bool[] Qualities, DateTime[] TimeStamps);

Parameters:

• Tags (string[]): List of Tags with new Tag Values
• Values (object[]): List of Values for the new Tag Values
• Qualities (bool[]): List of Qualities for the new Tag Values
• TimeStamps (DateTime[]): List of Timestamps for the new Tag Values

Use the LogIn method to set the username and password that is used when making API requests.

Related Information: Authentication

Signatures:

public void LogIn(string UserName, string Password)

Parameters:

• UserName (string): User username
• Password (string): User password

Example:

var oasData = new Data();
oasData.LogIn("api_username", "api_key");

Clear the user credentials.

Signatures:

public void LogOff()

Example:

var oasData = new Data();
oasData.LogIn("api_username", "api_key");

// perform some operations

// clear credentials
oasData.LogOff();

Add a redundant OAS instance IP or hostname to allow client side switchover when Tag Quality value is returned as Bad Quality. The same Tag name will be used, but the client will automatically try to connect to the alternative OAS instance given.

The backup logic operates at the Tag level. If only 1 Tag out of 10 tags is bad quality, then it will switch to the backup OAS node, but the remaining Tags will continue reading/writing on the original OAS node.

The Tag names and paths being monitored by the OAS data client must be the same on the Original and on the Revised OAS node.

If both the primary and backup servers return bad quality then the Tag's quality will also be set to bad quality.

You can only set one backup node for each primary OAS node.

Signatures:

public void AddBackupNetworkNode(string Original, string Revised)

Parameters:

• Original (string): Original network node IP or hostname
• Revised (string): Backup network node IP or hostname

Example:

var oasData = new Data();

// if a Tag on 192.168.10.10 fails, try the 192.168.10.20 server
var result = oasData.AddBackupNetworkNode("192.168.10.10", "192.168.10.20");

Get the current backup node set for a given OAS instance.

Signatures:

public string GetBackupNetworkNode(string Original)

Parameters:

• Original (string): Original network node IP or hostname

Returns:

• string: The node IP or host name

Example:

var oasData = new Data();
var result = oasData.GetBackupNetworkNode("192.168.10.10");

Remove the backup OAS node that has been set for the given primary OAS instance.

Signatures:

public void RemoveBackupNetworkNode(string Original)

Parameters:

• Original (string): Original network node IP or hostname

Example:

var oasData = new Data();
var result = oasData.RemoveBackupNetworkNode("192.168.10.10");

Add a network node alias to force Tags sourced from a given OAS node (the Original) to be sourced from a different OAS node (the Revised). This method is essentially a way for you to manually switch from one server to another.

This will force all Tags monitored by the primary to be switched to the backup.

The Tag names and paths being monitored by the OAS data client must be the same on the Original and on the Revised OAS node.

If both the primary and backup servers return bad quality then the Tag's quality will also be set to bad quality.

You can only set one backup node alias for each primary OAS node.

Signatures:

public void AddNetworkNodeAlias(string Original, string Revised)

Parameters:

• Original (string): Original network node IP or hostname
• Revised (string): Updated network node IP or hostname

Example:

var oasData = new Data();

// force all Tag monitoring from the 192.168.10.10 node to the 192.168.10.20 node
var result = oasData.AddNetworkNodeAlias("192.168.10.10", "192.168.10.20");

Get the current node alias set for a given OAS instance.

Signatures:

public string GetNetworkNodeAlias(string Original)

Parameters:

• Original (string): Original network node IP or hostname

Returns:

• string: The node IP or host name

Example:

var oasData = new Data();
var result = oasData.GetNetworkNodeAlias("192.168.10.10");

Remove the OAS node alias that has been set for the given primary OAS instance.

Signatures:

public void RemoveNetworkNodeAlias(string Original)

Parameters:

• Original (string): Original network node IP or hostname

Example:

var oasData = new Data();
var result = oasData.RemoveNetworkNodeAlias("192.168.10.10");

Add a Tag to be monitored asynchronously. Whenever the Tag's value changes, it will be included in the ValuesChangedAll event.

When adding a Tag you can use the full Tag path notation to monitor a Tag locally, over the network or using Live Data Cloud (LDC).

• Local: TagName.Value
• Remote: \192.168.10.10\TagName.Value
• LDC: \LDCHostingNameOrDomain\RemoteSCADAHosting.LDCAlias.TagName.Value

Signatures:

public void AddTag(string Tag)

Parameters:

• Tag (string): Tag path

Example:

var oasData = new Data();

// Subscribe to OAS value change events
oasData.ValuesChangedAll += OasData_ValuesChangedAll;

// Monitor Random tag value on localhost
oasData.AddTag("Random.Value");

// Monitor Ramp tag on OAS instance at 192.168.10.10
oasData.AddTag("\\192.168.10.10\Ramp.Value");

// Monitor Sine tag on OAS instance on Live Data Cloud alias EdgeNodeA
oasData.AddTag("\\192.168.10.100\RemoteSCADAHosting.EdgeNodeA.Sine.Value");


// Event handler
static void OasData_ValuesChangedAll(string[] Tags, object[] Values, bool[] Qualities, DateTime[] TimeStamps)
{
    Console.WriteLine("Values Changed Event Triggered:");
    for (int i = 0; i < Tags.Length; i++)
    {
        Console.WriteLine($"Tag: {Tags[i]}, Value: {Values[i]}, Quality: {Qualities[i]}, Timestamp: {TimeStamps[i]}");
    }
}

Add multiple Tags to be monitored asynchronously. Whenever a Tag's value changes, it will be included in the ValuesChangedAll event.

When adding Tags you can use the full Tag path notation to monitor Tags locally, over the network or using Live Data Cloud (LDC).

• Local: TagName.Value
• Remote: \192.168.10.10\TagName.Value
• LDC: \LDCHostingNameOrDomain\RemoteSCADAHosting.LDCAlias.TagName.Value

Signatures:

public void AddTags(string[] Tags)

Parameters:

• Tags (string[]): List of Tag paths

Example:

var oasData = new Data();

// Subscribe to OAS value change events
oasData.ValuesChangedAll += OasData_ValuesChangedAll;

// Monitor the following tags:
// - Random tag value on localhost
// - Ramp tag on OAS instance at 192.168.10.10
// - Sine tag on OAS instance with LDC alias EdgeNodeA (via LDC hosting node 192.168.10.100)
oasData.AddTags([
  "Random.Value",
  "\\192.168.10.10\Ramp.Value"
  "\\192.168.10.100\RemoteSCADAHosting.EdgeNodeA.Sine.Value"
]);


// Event handler
static void OasData_ValuesChangedAll(string[] Tags, object[] Values, bool[] Qualities, DateTime[] TimeStamps)
{
    Console.WriteLine("Values Changed Event Triggered:");
    for (int i = 0; i < Tags.Length; i++)
    {
        Console.WriteLine($"Tag: {Tags[i]}, Value: {Values[i]}, Quality: {Qualities[i]}, Timestamp: {TimeStamps[i]}");
    }
}

Remove all Tags from being monitored asynchronously.

Signatures:

public void RemoveAllTags()

Example:

var oasData = new Data();
oasData.RemoveAllTags();

Remove a specific Tag by its Tag path to stop monitoring it.

Signatures:

public void RemoveTag(string Tag)

Parameters:

• Tag (string): Tag path

Example:

var oasData = new Data();

// Assuming the Tags were added previously using AddTag or AddTags

oasData.RemoveTag("Random.Value");
oasData.RemoveTag("\\192.168.10.10\Ramp.Value");
oasData.RemoveTag("\\192.168.10.100\RemoteSCADAHosting.EdgeNodeA.Sine.Value");

Remove multiple Tags by their Tag path to stop monitoring them.

Signatures:

public void RemoveTags(string[] Tags)

Parameters:

• Tags (string[]): List of Tag paths

Example:

var oasData = new Data();

// Assuming the Tags were added previously using AddTag or AddTags

oasData.RemoveTags([
  "Random.Value",
  "\\192.168.10.10\Ramp.Value",
  "\\192.168.10.100\RemoteSCADAHosting.EdgeNodeA.Sine.Value"
]);

Write a Tag value asynchronously by Tag path.

If you provide the TimeStamp argument, the value will be written with the given timestamp. This allows you to backfill older data for alarm or data logging purposes. However, the current (real-time) value and timestamp will always be the most recent one.

The WriteUserName and WritePassword can be used to authenticate the destination OAS node with a different username and password if the client's default username and password does not allow for writing tags.

Signatures:

public void WriteTag(string Tag, object Value)
public void WriteTag(string Tag, object Value, DateTime TimeStamp)
public void WriteTag(string Tag, object Value, string WriteUserName, string WritePassword)
public void WriteTag(string Tag, object Value, DateTime TimeStamp, string WriteUserName, string WritePassword)

Parameters:

• Tag (string): Tag path
• Value (object): Tag value
• TimeStamp (DateTime): Tag value timestamp
• WriteUserName (string): Username for writing
• WritePassword (string): Password for writing

Example:

var oasData = new Data();

// write a tag using current DateTime
oasData.WriteTag("MyTag.Value", 123);

// write a tag using a given DateTime
oasData.WriteTag("MyTag.Value", 123, DateTime.Now);

// write a tag using a specific username/password
oasData.WriteTag("MyTag.Value", 123, "write_username", "write_password");

// write a tag using a specific username/password with DateTime
oasData.WriteTag("MyTag.Value", 123, DateTime.Now, "write_username", "write_password");

Write multiple Tag values asynchronously by their Tag paths.

Note that you do not need to add a Tag using AddTag or AddTags to be able to write to it.

If you provide the TimeStamps argument, the values will be written with the given timestamps. This allows you to backfill older data for alarm or data logging purposes. However, the current (real-time) value and timestamp of a Tag will always be the most recent one.

The WriteUserName and WritePassword can be used to authenticate the destination OAS node with a different username and password if the client's default username and password does not allow for writing tags.

Signatures:

public void WriteTags(string[] Tags, object[] Values)
public void WriteTags(string[] Tags, object[] Values, DateTime[] TimeStamps)
public void WriteTags(string[] Tags, object[] Values, string WriteUserName, string WritePassword)
public void WriteTags(string[] Tags, object[] Values, DateTime[] TimeStamps, string WriteUserName, string WritePassword)

Parameters:

• Tags (string[]): List of Tag paths
• Values (object[]): List of Tag values
• TimeStamps (DateTime[]): List of Tag value timestamps
• WriteUserName (string): Username for writing
• WritePassword (string): Password for writing

Example:

var oasData = new Data();

string[] tags = ["MyTag.Value", "MyOtherTag.Value", "MyBoolean.Value"];
object[] values = [123, 15.2, true];
DateTime[] timestamps = [DateTime.Now, DateTime.Now, DateTime.Now];

// write tags using current timestamps
oasData.WriteTags(tags, values);

// write tags using given timestamps
oasData.WriteTags(tags, values, timestamps);

// write tags using a specific username/password
oasData.WriteTags(tags, values, "write_username", "write_password");

// write tags using a specific username/password with timestamps
oasData.WriteTags(tags, values, timestamps, "write_username", "write_password");

Read multiple Tag values synchronously.

When using this method you do not need to add the Tags using AddTag or AddTags.

Signatures:

public object[] SyncReadTags(string[] Tags, ref int[] Errors, int Timeout = 10000)

Parameters:

• Tags (string[]): List of Tag paths
• Errors (ref int[]): List of error result codes for each item
• Timeout (int) (optional, default: 10000): The communications timeout in ms

Returns:

• object[]: Array of Tag values

Example:

var oasData = new Data();

// Define Tags to be read
string[] tags = ["Random.Value", "Ramp.Value", "Sine.Value", "InvalidTag"];

// Define result message variables
int[] errorResults = new int[tags.Length];

// Read Tag values
var values = oasData.SyncReadTags(tags, ref errorResults);

Write multiple Tag values synchronously.

When using this method you do not need to add the Tags using AddTag or AddTags.

The WriteUserName and WritePassword can be used to authenticate the destination OAS node with a different username and password if the client's default username and password does not allow for writing tags.

Signatures:

public int[] SyncWriteTags(string[] Tags, object[] Values)
public int[] SyncWriteTags(string[] Tags, object[] Values, string WriteUserName, string WritePassword)

Parameters:

• Tags (string[]): List of Tag paths
• Values (object[]): List of Tag values
• WriteUserName (string): Username for writing
• WritePassword (string): Password for writing

Returns:

• int[]: Result code for each Tag
  • 0: No error
  • 1: Service not reachable
  • 2: Mismatched Tags and Values array

Example:

var oasData = new Data();

string[] tags = ["MyTag.Value"];
object[] values = [123];

 // Write new Tag value
oasData.SyncWriteTags(tags, values);

Write multiple Tag values synchronously and then immediately read back the value to confirm. The deadband parameter allows you to specify the amount by which a value can be different when it is read to what was written. The timeout specifies how long to wait for a read after write before it times out.

When using this method you do not need to add the Tags using AddTag or AddTags.

The WriteUserName and WritePassword can be used to authenticate the destination OAS node with a different username and password if the client's default username and password does not allow for writing tags.

Signatures:

public int[] SyncWriteTagsWithConfirmation(string[] Tags, object[] Values, int Timeout = 10000, double FloatDeadband = 0.0001)
public int[] SyncWriteTagsWithConfirmation(string[] Tags, object[] Values, int Timeout, double FloatDeadband, string WriteUserName, string WritePassword)

Parameters:

• Tags (string[]): List of Tag paths
• Values (object[]): List of Tag values
• Timeout (int): Communication timeout in ms
• FloatDeadband (double): Deadband
• WriteUserName (string): Username for writing
• WritePassword (string): Password for writing

Returns:

• int[]: Result code for each Tag
  • 0: No error
  • 1: Service not reachable
  • 2: Value could not be set within the deadband for Double and Single values within the timeout period
  • 3: Mismatched Tags and Values array

Example:

var oasData = new Data();

// Define Tags to be read and written
string[] tags = ["MyTag.Value"];
object[] values = [123];

// Write new Tag value
var result = oasData.SyncWriteTagsWithConfirmation(tags, values);

for (var i = 0; i < tags.Length; i++)
{
    var resultMessage = result[i] switch
    {
        0 => "Success",
        1 => "OAS not reachable",
        2 => "Failed to write Tag",
        3 => "Tags and Values array must be the same length",
        _ => "Unknown error",
    };
    Console.WriteLine($"Tag: {tags[i]}, Value: {values[i]}, Result: {resultMessage}");
}

Write multiple Tag values by their Tag paths and wait for a result.

Note that you do not need to add a Tag using AddTag or AddTags to be able to write to it.

If you provide the TimeStamps argument, the values will be written with the given timestamps. This allows you to backfill older data for alarm or data logging purposes. However, the current (real-time) value and timestamp of a Tag will always be the most recent one.

The WriteUserName and WritePassword can be used to authenticate the destination OAS node with a different username and password if the client's default username and password does not allow for writing tags.

Signatures:

public int[] WriteTagsWithResults(string[] Tags, object[] Values)
public int[] WriteTagsWithResults(string[] Tags, object[] Values, DateTime[] TimeStamps)
public int[] WriteTagsWithResults(string[] Tags, object[] Values, string WriteUserName, string WritePassword)
public int[] WriteTagsWithResults(string[] Tags, object[] Values, DateTime[] TimeStamps, string WriteUserName, string WritePassword)

Parameters:

• Tags (string[]): List of Tag paths
• Values (object[]): List of Tag values
• TimeStamps (DateTime[]): List of Tag value timestamps
• WriteUserName (string): Username for writing
• WritePassword (string): Password for writing

Returns:

• int[]: Return value description
  • 0: Success
  • 1: Service Not Reachable
  • 2: OAS Version Needs to be Updated
  • 3: Function Not Supported with Legacy .NET Remoting
  • 4: Function Not Supported with Classic TCP
  • 5: OAS Engine Not in Runtime
  • 6: Timeout
  • 7: Invalid Security
  • 8: Tag Does Not Exist
  • 9: Invalid Tag Parameter
  • 10: Internal Exception
  • 11: Tag is Read Only
  • 12: Out of Range
  • 13: Bad Quality
  • 14: Skipped Due To Write Latest Value Only
  • 15: Write to Driver Interface Invalid Source
  • 16: Null Value Not Allowed
  • 17: Previous Value of Integer Not Available for Bit Write
  • 18: Memory Type Not Writable
  • 19: Value of False Disabled Write
  • 20: Failure
  • 21: Invalid Address
  • 22: Invalid License
  • 23: Offline or Not In Runtime
  • 24: Tag Parameter Not Writable
  • 25: Invalid Driver Interface

Example:

var oasData = new Data();

// Example: success
var result = oasData.WriteTags(["MyTag.Value", "MyOtherTag.Value", "MyBoolean.Value"], [123, 15.2, true]);
// result = [0, 0, 0]

// Example: invalid Tag
var result = oasData.WriteTags(["MyTag.Value", "MyOtherTag.Value", "InvalidTag"], [123, 15.2, true]);
// result = [0, 0, 5]

Read an OPC DA item on a given OAS instance.

Signatures:

public object[] ReadOPCItems(string NetworkNode, string[] OPCItems, ref int[] Errors, int Timeout = 10000)

Parameters:

• NetworkNode (string): OAS node IP or hostname
• OPCItems (string[]): List of OPC items
• Errors (ref int[]): List of error result codes for each item
• Timeout (int) (optional, default: 10000): The communications timeout in ms

Returns:

• object[]: List of values

Example:

var oasData = new Data();

string[] tags = ["EEI.OPCSimulator\\SimDevice.Ramp", "EEI.OPCSimulator\\SimDevice.Random", "InvalidTag"];
int[] errorResults = new int[tags.Length];

var values = oasData.ReadOPCItems("localhost", tags, ref errorResults);

// values = [40, 94, null]; 
// errorResults = [0, 0, 2];

Read an OPC DA item on a given OAS LDC edge node.

Signatures:

public object[] ReadOPCItemsFromRemoteSCADAHost(string NetworkNode, string RemoteSCADAHostingName, string[] OPCItems, ref int[] Errors, int Timeout = 10000)

Parameters:

• NetworkNode (string): OAS node IP or hostname
• RemoteSCADAHostingName (string): Registered Live Data Cloud hosting name
• OPCItems (string[]): List of OPC items
• Errors (ref int[]): List of error result codes for each item
• Timeout (int) (optional, default: 10000): The communications timeout in ms

Returns:

• object[]: List of values

Example:

var oasData = new Data();

string[] tags = ["EEI.OPCSimulator\\SimDevice.Ramp", "EEI.OPCSimulator\\SimDevice.Random", "InvalidTag"];
int[] errorResults = new int[tags.Length];

var values = oasData.ReadOPCItemsFromRemoteSCADAHost("hostingNodeDomainOrIP.com", "EdgeNodeA", tags, ref errorResults);

// values = [40, 94, null]; 
// errorResults = [0, 0, 2];

Write one or more OPC DA Items on a given OAS instance.

Signatures:

public int[] WriteOPCItems(string NetworkNode, string[] OPCItems, object[] WriteValues, int Timeout = 10000)

Parameters:

• NetworkNode (string): OAS node IP or hostname
• OPCItems (string[]): List of OPC items
• WriteValues (object[]): List of values to write
• Timeout (int) (optional, default: 10000): The communications timeout in ms

Returns:

• int[]: array of result codes for each OPC item
  • 0: No error
  • 1: Error writing OPC items
  • 2: Mismatched OPCItems and WriteValues array

Example:

var oasData = new Data();

string[] tags = ["OPCSystems.NET\\Local.MyTag.Value"];
object[] values = [123];

var results = oasData.WriteOPCItems("localhost", tags, values);

// results = [0]

Write one or more OPC DA Items on a given OAS LDC edge node.

Signatures:

public int[] WriteOPCItemsFromRemoteSCADAHost(string NetworkNode, string RemoteSCADAHostingName, string[] OPCItems, object[] WriteValues, int Timeout = 10000)

Parameters:

• NetworkNode (string): OAS node IP or hostname
• RemoteSCADAHostingName (string): Registered Live Data Cloud hosting name
• OPCItems (string[]): List of OPC items
• WriteValues (object[]): List of values
• Timeout (int) (optional, default: 10000): The communications timeout in ms

Returns:

• int[]: array of result codes for each OPC item
  • 0: No error
  • 1: Error writing OPC items
  • 2: Mismatched OPCItems and WriteValues array

Example:

var oasData = new Data();

string[] tags = ["OPCSystems.NET\\Local.MyTag.Value"];
object[] values = [123];

var results = oasData.WriteOPCItemsFromRemoteSCADAHost("hostingNodeDomainOrIP.com", "EdgeNodeA", tags, values);

// results = [0]

Write one or more OPC DA Items on a given OAS LDC edge node without confirmation. This is a non-blocking call.

Signatures:

public int[] WriteOPCItemsFromRemoteSCADAHostWithoutResults(string NetworkNode, string RemoteSCADAHostingName, string[] OPCItems, object[] WriteValues)

Parameters:

• NetworkNode (string): OAS node IP or hostname
• RemoteSCADAHostingName (string): Registered Live Data Cloud hosting name
• OPCItems (string[]): List of OPC items
• WriteValues (object[]): List of values

Returns:

• int[]: Always returns null

Example:

var oasData = new Data();

string[] tags = ["OPCSystems.NET\\Local.MyTag.Value"];
object[] values = [123];

asData.WriteOPCItemsFromRemoteSCADAHostWithoutResults("hostingNodeDomainOrIP.com", "EdgeNodeA", tags, values);

Write one or more OPC DA Items on a given OAS instance without confirmation.

Signatures:

public void WriteOPCItemsWithoutResults(string NetworkNode, string[] OPCItems, object[] WriteValues)

Parameters:

• NetworkNode (string): OAS node IP or hostname
• OPCItems (string[]): List of OPC items
• WriteValues (object[]): List of values

Example:

var oasData = new Data();

string[] tags = ["OPCSystems.NET\\Local.MyTag.Value"];
object[] values = [123];

oasData.WriteOPCItemsWithoutResults("localhost", tags, values);