Paths

To access an inmation object (with Lua or the SCI for example) the full unique path to the object is used. The I/O Model tree structure has the System as the top object in the hierarchy with the Core object below it. Connector and Relay objects are always situated beneath a Core object in the hierarchy (Connectors can be beneath Relays too but that means they are ultimately beneath a Core object). Datasources (such as OPC servers) are always situated beneath a Connector object. Other data processing objects (Action Items, Generic Items, Folders and Data Holders) or I/O items can exist in various locations in the I/O tree depending on their function. The path of an inmation object is constructed from its name and the names of its preceding parent objects. The hierarchical levels of the objects are separated by a forward slash. For example, in the tree structure shown below the selected I/O item “Int1”is located in the Matrikon.OPC.Simulation server namespace and has the path: “/System/Core/Local Connector/Matrikon.OPC.Simulation.1/SimulationItems/Random/Int1”.

Path to Object in I/O Model
Figure 1. Path to Object in I/O Model

To quickly access the full path of an Object in the tree, select the item and in the object properties panel header, hover over the item’s icon and click on the plus sign to reveal the advanced properties including Item Path.

Path - Advanced Properties
Figure 2. Path - Advanced Properties

To quickly copy the path to the clipboard, right-click on the item and select Copy full path from the context menu.

Context Menu - Copy Full Path
Figure 3. Context Menu - Copy Full Path

Disambiguation of Item Paths

The forward slash character is used in item paths to separate components of the path. However, the names of certain objects in the tree might also contain forward slash characters that could cause ambiguity in the paths to different objects. For example, the I/O model tree shown below contains four Data Holder items which all have potentially the same item path:

/System/Core/Process/Data/Holder

Ambiguous Item Paths
Figure 4. Ambiguous Item Paths

The presence of forward slash characters in item tag-names creates ambiguity with item paths that must be resolved in some way by the system to uniquely identify objects in the tree. In these cases, the caret escape character (^) should be used to distinguish between forward slashes in tag-names and those in item paths. If an item path contains forward slash characters in tag-names, the entire item path should be preceded by a caret (^) escape character. Thereafter, any forward slashes that are part of a tag-name are also preceded by a caret character. For example, the Data Holder object in the tree above with the tag-name “Process/Data/Holder” is uniquely identified in the system with the path:

^/System/Core/Process^/Data^/Holder

The unique path is created by the system and can be viewed in the advanced header of the Object Properties panel:

Unique Object Path
Figure 5. Advanced Header - Unique Object Path

For the other objects in namespace, the “Holder” item in the “Process/Data” folder has the unique path:

^/System/Core/Process^/Data/Holder

The “Data/Holder” item in the “Process” folder has the unique path:

^/System/Core/Process/Data^/Holder

Finally, the “Holder” item in the “Data” Folder (which itself is in the “Process” folder) has the unique “straight” path, containing no carets:

/System/Core/Process/Data/Holder

These unambiguous paths can therefore be used to access objects using Lua or the SCI. If no ambiguity exists in the namespace, (for example, if only one of the above Holder items is present) the simple path (i.e. no carets) can be used to access the object. If an object has a tag-name that itself contains a caret character, then this can be escaped using the caret character too. For example, in the situation below:

Ambiguous Item Path Containing Caret
Figure 6. Ambiguous Item Path Containing Caret

The object “Data^/Holder” contains a caret AND a forward slash in the Object Name. Therefore, the unique unambiguous path to this object is:

^/System/Core/Process/Data^^^/Holder

As before, there is a caret preceding the whole path, a caret preceding the caret in the object’s name and finally a caret preceding the forward slash in the object’s name. This can be retrieved from the advanced header of the Object Properties panel:

Unique Object Path
Figure 7. Advanced Header - Unique Object Path

Copying a full path of an object via the context menu or from the object properties panel will give you the unique full path automatically.

Properties

Once a full path to an object is established then the value of that object and any of its properties are accessible. To access an object’s properties, use the dot syntax followed by the property name. For example:

/System/Core/Process/Data/Holder.ObjectName or

/System/Core/Process/Data/Holder.Limits.OpcRangeHigh

The second example shows the full path to the High EU Range property (all Limit properties are located in the Limits property compound) however, the property can also be accessed without knowing the full path. For example, the following path:

/System/Core/Process/Data/Holder.OpcRangeHigh

will also access link to the property, even without knowing the Limits property compound part of the path. system:inmation allows for this “flat” property browsing for all objects in the system and applies to the Lua and SCI functionality also.

Property Values

All properties in inmation have a Value, Quality and Timestamp (VQT). This is particularly pertinent for the dynamic value of objects (explained in more detail in the VQT Logic section of the documentation) but the same VQT can be retrieved or set for all object properties.

If the inmation.getvalue function is used, the VQT for the property can be retrieved. For example:

v,q,t = inmation.getvalue("/System/Core/Process/Data/Holder.ObjectName")

In this example, the q value "0" is returned along with a timestamp t corresponding to the last change to the property value (this could also be the timestamp for the creation of the object if the property in question was configured by the user at object creation).

For some properties the value, quality and timestamp are optionally set to "nil". A "nil" value will therefore be returned when the V, Q, or T for the property is retrieved. For example, this is the case for the quality and timestamp for property values that have not been previously set or configured by the user (upon object creation for example). Consider the following example:

v,q,t = inmation.getvalue("/System/Core/Process/Data/Holder.ObjectDescription")

If the ObjectDescription for the object has not been previously configured, the v, q, t would respectively be:

v = ""
q = nil
t = nil

When setting a property value with Lua using the inmation.setvalue function, a "0" quality value (good) and the current time as default timestamp is used unless otherwise specified.

inmation.setvalue("/System/Core/Process/Data/Holder.ArchiveOptions.StorageStrategy", 1)

To specify the quality and timestamp, the optional inmation.setvalue arguments can be used.

inmation.setvalue("/System/Core/Process/Data/Holder.ArchiveOptions.StorageStrategy", 1, 0, 1573039440769)

Relative Paths

A relative path is a path that does not start with the '/' character or the "^/" character sequence. It will be resolved relative to the object that is executing the Lua script (the "self" object). A relative path that doesn’t start with the '.' character is automatically resolved as an object reference. For example, the following command: inmation.getvalue("Ref1") will return the value of the object reference "Ref1", (presuming the object executing the Lua script has a configured reference named "Ref1")

A relative path that starts with "." will reference the properties of object executing the Lua script. For example, the following command: inmation.getvalue(".ObjectName") will return the ObjectName property of the "self" object. A relative path that starts with "./" will reference children of the self object.

Starting a relative path with "../" allows to reference objects or properties higher up in the hierarchy. For example, the "Read Data" ActionItem in the I/O model below can reference other objects in the tree using relative paths.

Relative Paths Example
Figure 8. Relative Paths Example

To reference the "Test Item" from a script in "Read Data" the following relative path can be used: inmation.getvalue("../Test Item") To reference the Items in the "Plant1 Data" folder from "Read Data", the following relative path can be used: inmation.getvalue("../../Plant1 Data/Flow") To reference the Items in the "Lab Results" folder from "Read Data", the following relative path can be used: inmation.getvalue("../../../Results/Lab Results/Density")

Path Specification

An inmation path specification, named the pathspec, is a value that identifies an inmation object or property. Many functions in the inmation Lua library use a pathspec as an argument for the function to identify the object or property they operate on.

A pathspec can be:

  • An integral number, denoting an object, object ID or property id

  • A Lua inmation object (as returned from inmation.createobject or inmation.getobject)

  • A string holding an absolute or relative path to an object or property

If a pathspec cannot be resolved, a Lua error is raised.

Object Specification

An objspec is a pathspec, subject to the following restriction: it can only refer to an object, whereas a pathspec can refer to an object and to a property. Where an objspec is expected, a path that is a pathspec referring to a property would not be valid.

For example, a pathspec like "a/b.c" can successfully refer to an object with path "a/b", and also to an object with path "a/b.c" (where "b.c" is the name of the object). An objspec like "a/b.c" can only refer to an object with path "a/b.c" (where "b.c" is the name of the object).

In the Lua API, `objspec`s are typically expected by functions that work with objects rather than properties.