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 | - | 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 theValue
property and any relevant quality information (quality
,qualityGood
, andtimestamp
).
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)