Paths

To refer to an AspenTech Inmation object (for example with Lua or a WebStudio compilation) the full unique path to the object is used.

The path of an AspenTech 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 I/O item “Int1” is located in the Matrikon.OPC.Simulation server namespace and has the path:

/IO-Home/Matrikon^.OPC^.Simulation^.1/SimulationItems/Random/Int1

The reasons for the '^' character will be explained in the section on Problematic Object Names below.

To quickly access the full path of an Object in the tree, select the item and in the Object Lens panel, click on the expand button (the triangle beneath the item’s icon) to reveal the advanced properties including the item’s Path.

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

Problematic Object Names

The forward slash character (/) is used in item paths to separate the components of the path. If a path is used to address a property of an object (see below), the dot (.) is used to separate the property name from the object path. Both characters (slash and dot) can be used in object names, which could cause ambiguity with paths to other objects or their properties.

For example, the I/O model tree shown on the right contains four Data Holder items which all have potentially the same item path:

/IO-Home/Paths Documentation/Process/Data/Holder

Here, the presence of forward slash characters in item names creates ambiguity with item paths, and therefore needs to 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 or dots in tag-names, any forward slashes or dots that are part of a tag-name need to be escaped by a preceding caret character.

Here are the paths for the various Data Holder items in the tree above:

  • The Data Holder object with the name “Process/Data/Holder”, is uniquely identified in the system with the path:

    /IO-Home/Paths Documentation/Process^/Data^/Holder

    The unique path is created by the system and can be viewed in the expanded Header of the Object Lens.

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

    /IO-Home/Paths Documentation/Process^/Data/Holder

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

    /IO-Home/Paths Documentation/Process/Data^/Holder

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

    /IO-Home/Paths Documentation/Process/Data/Holder

These unambiguous paths can therefore be used to access objects using Lua.

Copying a full path of an object via the object’s context menu will give you the unique full path automatically.

Escaping the Caret Symbol

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:

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

/IO-Home/Paths Documentation/Process/Data^^^/Holder

As before, there is a caret preceding the caret in the object’s name and finally a caret preceding the forward slash in the object’s name.

Avoiding ambiguous paths

The syslib.joinpath function can be used to let the system take care of escaping problematic characters in object names:

local path = syslib.joinpath("/", "IO-Home", "Paths Documentation", "Process/Data", "Holder")
-- path = "/IO-Home/Paths Documentation/Process^/Data/Holder"

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:

/IO-Home/Paths Documentation/Process/Data/Holder.ObjectName or

/IO-Home/Paths Documentation/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:

/IO-Home/Paths Documentation/Process/Data/Holder.OpcRangeHigh

will also access the property, even without knowing the Limits property compound part of the path. AspenTech Inmation allows for this “flat” property browsing for all objects in the system and applies to the Lua and WebStudio compilation functionality also.

Property Values

All properties in AspenTech 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 Data section of the documentation) but the same VQT can be retrieved or set for all object properties.

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

v,q,t = syslib.getvalue("/IO-Home/Paths Documentation/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 = syslib.getvalue("/IO-Home/Paths Documentation/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 syslib.setvalue function, a "0" quality value (good) and the current time as default timestamp is used unless otherwise specified.

syslib.setvalue("/IO-Home/Paths Documentation/Process/Data/Holder.ArchiveOptions.StorageStrategy", 1)

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

syslib.setvalue("/IO-Home/Paths Documentation/Process/Data/Holder.ArchiveOptions.StorageStrategy", 1, 0, 1573039440769)

Relative Paths

A relative path is a path that does not start with the '/' character. 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 command syslib.getvalue("Ref1") will return the value of the object reference "Ref1", (presuming the object executing the Lua script has a configured reference named "Ref1")

When using the syslib.getvalue function, specifying the path to an object will automatically try to retrieve the dynamic value of the object. If the object doesn’t support a dynamic value (for example, a Folder object) then an error will be returned saying that the path could not be resolved.

A relative path that starts with "." will reference the properties of the object executing the Lua script. For example, the following command:

syslib.getvalue(".ObjectName")

will return the ObjectName property of the "self" object. A relative path that starts with "./" will reference children of the self object. Or if the "./" is followed by a "." character and a property name, then the property of the "self" object is referenced. For example:

syslib.getvalue("./.ObjectName")

and

syslib.getvalue(".ObjectName")

both return the object name of the "self" object.

Just entering "./" as the relative path will return the dynamic value of the "self" object. For example:

syslib.getvalue("./")

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.

To reference the "Test Item" from a script in "Read Data" the following relative path can be used:

syslib.getvalue("../Test Item")

To reference the Items in the "Plant1 Data" folder from "Read Data", the following relative path can be used:

syslib.getvalue("../../Plant1 Data/Flow")

To reference the Items in the "Lab Results" folder from "Read Data", the following relative path can be used:

syslib.getvalue("../../../Results/Lab Results/Density")

The same is true for resolving property values for other objects in the tree. The following command:

syslib.getvalue("../.ObjectName")

will return the object name of the parent object.

To get the object description of parent of the parent you can use following command:

syslib.getvalue("../../.ObjectDescription")

or the Engineering Unit or the "Density" Item in the "Lab Results" folder:

syslib.getvalue("../../../Results/Lab Results/Density.OpcEngUnit")

Path Specification

A path specification, named pathspec, is a value that identifies an AspenTech Inmation object or property. Many functions in the 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 AspenTech Inmation object id (as returned by the :guid() object method) or property id (as returned by syslib.getpropertyid)

  • A Lua AspenTech Inmation object (as returned from syslib.createobject or syslib.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.

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

Store Specification

A storespec is a valid objspec of a data store.

Iterating an Object’s Children

The following function returns a table containing the paths of an object’s children. It takes as parameters the parent object and a boolean value stating if the iteration is done recursively or not. If it is false, only the paths of the direct children are returned.

local get_child_paths = function (object, recursively)
  local paths = {}
  if object ~= nil then
    local children = {}
    if not recursively then
      children = object:children()
    else
      -- find all the objects that contain the path of the given object in their path
      -- "object" will be included too in the resulting table
      children = syslib.findobjects(object:path(), 0, false, true)

      table.sort(children, function(a, b) return a:path() < b:path() end)
      table.remove(children, 1) -- remove "object"
    end

    for c = 1, #children do
      table.insert(paths, children[c]:path())
    end
  end

  return paths
end

local obj = syslib.getobject("/IO-Home")
return get_child_paths(obj, true)