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

BrowserObject

Point

-

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 getProperties method returns an array of PropertyValue objects that includes any attributes of the Value property and any relevant quality information (quality, qualityGood, and timestamp).
    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 getProperties returns 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 terminates with the following exception: Node not found.
  • <readValues> is not Boolean
    • The script terminates with the following exception: Invalid ReadValue.
  • <maxAge> is not a numeric value
    • The script terminates 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.