getProperties Function
The getProperties method allows retrieving the properties of a system object and any mapped properties associated to system objects with functions. The properties that will be returned are all the ones for which the user has appropriate read access rights, regardless of the display levels (DL0, DL1, and so on).
This function is useful when you want to read all the system object data using one instruction only, or if you want to check that a property exists before reading it.
This function can be invoked as follows:
- If you are only interested in the properties availability, you can just receive the list of properties.
- If you also want to get the properties values (instead of using the read method for each property), you can get the properties operating values.
Syntax
It is possible to retrieve the list of properties for a system object and, if required, also the properties values. See the following syntax:
getProperties(<objectReference>, <readValues>, <maxAge>)
Parameters Usage
Parameter | Type | Default | Use | Annotation |
objectReference | String | - | Mandatory | CNS full path (reference to the system object). |
readValues | Boolean | False | Optional | Whether the property value is retrieved. False means that only the list of properties for a system object is retrieved. |
maxAge | Integer | 0 | Optional | Condition for retrieving data from the field. The default value (0) means that the value will be always retrieved from the field. If the value from the field is older than this number of milliseconds, it will be retrieved again, and the most updated value will be provided. |
Result
- If the operation is successful, the
getPropertiesmethod returns an array of PropertyValue objects that includes any attributes of theValueproperty and any relevant quality information (quality,qualityGood, andtimestamp).
If<readValues>is False, the result will have null value. Any other properties (for example, descriptor, min, max, ...) are always available. - If any errors occurred during the operation, the
getPropertiesreturns the PropertyValue object with the error property that indicates the reason why the operation failed.
Error Handling
Errors can occur in case:
<objectReference>is invalid- The script ends with the following exception:
Node not found. <readValues>is not Boolean- The script ends with the following exception:
Invalid ReadValue. <maxAge>is not a numeric value- The script ends with the following exception:
Invalid Max Age.
Examples of Use
How to get all the properties for a system object, without properties values
var properties = getProperties("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.analog");
console("Received " + properties.length + " results");
properties.forEach(
function(property) {
console(property.descriptor + " value: " + property.value);
});
This invocation results in getting the properties, with no value. Trying to read the value will return a null result (SummaryStatus: null; Value: null).
How to get all the properties for a system object, including properties values
var properties = getProperties("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.analog", true);
console("Received " + properties.length + " results");
properties.forEach(
function(property) {
console(property.descriptor + " value: " + property.value.displayValue);
});
The output in the Console expander is:
Received 2 results
Summary Status value: Normal
Value value: null
How to get all the properties for a system object, including properties values and maxAge
var properties = getProperties("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.analog", true, 10000);
console("Received " + properties.length + " results");
properties.forEach(
function(property) {
console(property.descriptor + " value: " + property.value.displayValue);
});
The output in the Console expander is:
Received 2 results
Summary Status value: Normal
Value value: 0
If the value was retrieved from the field more than 10 seconds ago, it will be fetched again to get the most recent value.