cnsSubStr

Extracts parts of a CNS path.

Synopsis

string cnsSubStr(string cnsPath, int flags[, bool ]);

Parameters

Parameter Description
cnsPath CNS path which shall be parsed
flags

Defines which parts of the path shall be extracted. Multiple flags can be combined with binary OR. The following flags are available:

  • CNSSUB_SYS: The system name. If resolvePath is true and the view can be resolved, the system name will be taken from the existing view, otherwise it will be taken from the given path string.
  • CNSSUB_VIEW: If specified without other flags, the view name ("<view>"), otherwise the view path (".<view>:").
  • CNSSUB_PATH: The node path. If resolvePath is true and the path can be resolved, CNSSUB_PATH spans from after the view separator up to and including the last existing node. Otherwise, it spans from after the view separator up to and excluding the optional second view separator and the optional path separator directly before it (see examples).
  • CNSSUB_PARENT: Like CNSSUB_PATH, but without the last node. If CNSSUB_PATH only has a single node, this node will be returned.
  • CNSSUB_ROOT: The first node from CNSSUB_PATH.
  • CNSSUB_NODE: The last node from CNSSUB_PATH.
  • CNSSUB_TAIL: Everything after CNSSUB_PATH.
resolvePath Determines whether the path shall be resolved. If true and a view or node with the given path exists, the existing element will be used to determine the system name and to separate CNSSUB_PATH and CNSSUB_TAIL. If false or no element can be found the specified parts will be extracted by parsing the path string. Disabling path resolution is mainly useful when you already know whether the path exists, so that you can avoid the overhead of accessing CNS.

Return value

Returns TRUE if successful or FALSE in case of an error.

Errors

-

Description

This function extracts parts of a CNS path.

main()
{
  cnsSubStr("System1.View1:", CNSSUB_SYS); //"System1"
  cnsSubStr("System1.View1:", CNSSUB_VIEW); //"View1"
  cnsSubStr("System1.View1:", CNSSUB_SYSTEM | CNSSUB_VIEW); //"System1.View1:"
  cnsSubStr("System1.View1:", CNSSUB_VIEW | CNSSUB_PATH); //".View1:"
  cnsSubStr("System1.View1:", CNSSUB_PATH); //""
  cnsSubStr("System1.View1:", CNSSUB_TAIL); //""
  cnsSubStr("System1.View1:root", CNSSUB_PATH); //"root"
  cnsSubStr("System1.View1:root", CNSSUB_ROOT); //"root"
  cnsSubStr("System1.View1:root", CNSSUB_NODE); //"root"
  cnsSubStr("System1.View1:root", CNSSUB_PARENT); //"root"
  cnsSubStr("System1.View1:root", CNSSUB_VIEW | CNSSUB_PATH); //".View1:root"
  cnsSubStr("System1.View1:root", CNSSUB_SYS | CNSSUB_VIEW | CNSSUB_PATH); //"System1.View1:root"
  cnsSubStr("System1.View1:root", CNSSUB_TAIL); //""
  cnsSubStr(".View1:root.node1.node2", CNSSUB_PATH); //"root.node1.node2"
  cnsSubStr(".View1:root.node1.node2", CNSSUB_ROOT); //"root"
  cnsSubStr(".View1:root.node1.node2", CNSSUB_NODE); //"node2"
  cnsSubStr(".View1:root.node1.node2", CNSSUB_PARENT); //"root.node1"
  cnsSubStr(".View1:root.node1.node2", CNSSUB_VIEW | CNSSUB_PATH); //".View1:root.node1.node2"
  cnsSubStr(".View1:root.node1.node2", CNSSUB_TAIL); //""
  cnsSubStr(".View1:root.node1.node2.", CNSSUB_PATH); //"root.node1.node2"
  cnsSubStr(".View1:root.node1.node2.", CNSSUB_NODE); //"node2"
  cnsSubStr(".View1:root.node1.node2.", CNSSUB_TAIL); //"."
  cnsSubStr(".View1:root.node1.node2.:_online.._value", CNSSUB_PATH); //"root.node1.node2"
  cnsSubStr(".View1:root.node1.node2.:_online.._value", CNSSUB_NODE); //"node2"
  cnsSubStr(".View1:root.node1.node2.:_online.._value", CNSSUB_TAIL); //".:_online.._value"
  cnsSubStr(".View1:root.node1.node2.dpe1.dpe2:_online.._value", CNSSUB_PATH, false); //"root.node1.node2.dpe1.dpe2"
  cnsSubStr(".View1:root.node1.node2.dpe1.dpe2:_online.._value", CNSSUB_NODE, false); //"dpe2"
  cnsSubStr(".View1:root.node1.node2.dpe1.dpe2:_online.._value", CNSSUB_TAIL, false); //":_online.._value"

  // if ".View1:root.node1.node2" is an existing node,
  // but ".View1:root.node1.node2.dpe1" is not:
 
  cnsSubStr(".View1:root.node1.node2.dpe1.dpe2:_online.._value", CNSSUB_PATH, true); //"root.node1.node2"
  cnsSubStr(".View1:root.node1.node2.dpe1.dpe2:_online.._value", CNSSUB_NODE, true); //"node2"
  cnsSubStr(".View1:root.node1.node2.dpe1.dpe2:_online.._value", CNSSUB_TAIL, true); //".dpe1.dpe2:_online.._value"
}

Availability

UI, CTRL