read Function

The read method allows retrieving the value and attributes of a property in a Desigo CC system.

Syntax

It is possible to get the value of a property of a system object. See the following syntax:

 

(one instruction)

read(<objectReference>, <propertyName>, <maxAge>);

 

It is also possible to define a BrowserObject data type by specifying the full CNS path of the concerned system object and then use this object in addition to the name of the property to get the property value. See the following syntax:

 

(two instructions)

var obj= new BrowserObject(<objectReference>);
read(obj, <propertyName>, <maxAge>);

 

The data necessary to get the data point name from the object reference in order to read the property value from IOWA is calculated only the first time a read operation is performed on the system object, so that any subsequent read operations on the same system object can reuse the same data.

Parameters Usage

Parameter

Type

Default

Use

Annotation

objectReference

String

BrowserObject

Point

-

Mandatory

CNS full path (reference to the system object location), from which a property will be read.

propertyName

String

-

Mandatory

Name of the property to read.

maxAge

Integer

-1

Optional

Condition for retrieving data from the field.

If the value from the field is older than this number in milliseconds, it will be retrieved again, and the most updated value will be provided.

If this parameter is -1 (default) means that the value will be always retrieved from the process image.

Result

  • If the read operation is successful, the read method returns the PropertyValue object that includes the attributes of the Value property and any relevant quality information (quality, qualityGood, and timestamp).
    Note that the same attributes are available in the callback of a subscription for each notified value.
  • If any errors occurred during the read operation, the read method returns the PropertyValue object with the error property that indicates the reason why the operation failed.

Error Handling

Errors can occur in case:

  • The object reference does not indicate an existing system object
  • The property does not exist or is not accessible
  • The read operation fails

Examples of Use

 

How to read a property and print to Console its attributes (value, qualityGood, quality, timestamp)

var finalResult = read("System1.ManagementView:ManagementView.FieldNetworks.net.Hardware.5800/5800-Test_device_5800.5800/0-Local_IO.5800/1-AO_1", "Present_Value");

 

console("{0}", finalResult.value);

 

var resultBool = read("System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_3.Item1", "BoolValue");

 

var finalResult = “”;

if (!resultBool.error)

    finalResult += "Bool = " + resultBool.value + "\n";

else

    finalResult += "Bool error (" + resultBool.error + ")\n";

 

console (finalResult);

 

var object = new BrowserObject("System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_3.Item1");

var resultFloat = read(object, "FloatValue");

 

var finalResult = “”;

if (!resultFloat.error)

    finalResult += "Float = " + resultFloat.value + "\n";

else

    finalResult += "Float error (" + resultFloat.error + ")\n";

 

console (finalResult);

 

var result = read("System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_3.BinaryInput1", "Value");

 

if (!result.error)

    console("Value = {0}\nQualityGood = {1}\nQuality = {2}\nTimestamp (UTC) = {3}", result.value.value, result.value.qualityGood, result.value.quality, result.value.timestamp);

else

    console("Read error: {0}", result.error);

 

console (finalResult);

 

If the result is valid, the output in the Console expander is similar to the following:

  • Value = True
  • QualityGood = True
  • Quality = 9.43954481896935E+18"
  • Timestamp (UTC) = 5/4/2015 2:04:13 PM

If the result is not valid (for example, the object is not found during the read operation), the output in the Console expander is similar to the following:

 

    Read error: Node not found

(System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_3.BinaryInput12)