CONTROL
- Introduction to CTRL
  An introduction to the product's own programming language Control(CTRL).
- CONTROL Classes
- Types of Control Functions
  An overview of the types of functions distinguished within Control.
- Control graphics
- CONTROL Functions
  - Functions A
  - Functions B
  - Functions C
    - callFunction()
      Calls a specific function. The parameters of the called function are passed as parameters in callFunction().
    - captureScreen() - obsolete
      Returns an IDispatch (IPicture) image of the screen. (obsolete from version 3.5).
    - ceil()
      Rounds up to an integer.
    - certificateAcceptPermanently()
      The function marks the given digest as "permanently accepted" and stores this information on the hard disk.
    - certificateIsPermanentlyAccepted()
      The function certificateIsPermanentlyAccepted() returns TRUE if the given certificate was already permanently accepted, e.g. by the user.
    - changeLang()
      Function for switching the language at runtime in a user interface.
    - checkLicenseOption()
      The function checkLicenseOption() allows you to check the number of available licenses for the specified WinCC OA license option.
    - checkPassword()
      Checks the assignment of a password to the user id.
    - checkPattern()
      Compares a bit32/bit64 variable with a pattern.
    - checkQuery()
      Checks the syntax of a query.
    - checkScript()
      Checks the syntax of a script.
    - checkStringFormat()
      The function checks, wether the string 'value' is according the format in 'format' (for example, "%5.4f").
    - childPanel()
      Opens a child panel without connection to the Event Manager.
    - ChildPanelOn()
      Opens a child panel.
    - ChildPanelOnCentral()
      Opens a child panel centered in the calling parent panel.
    - ChildPanelOnCentralModal()
      Opens a modal child panel centered in the calling parent panel.
    - ChildPanelOnCentralModalReturn()
      Opens a modal child panel, with return value, centered in the calling parent panel.
    - ChildPanelOnCentralReturn()
      Opens a child panel with return value centered in the calling parent panel.
    - ChildPanelOnModal()
      Opens a modal child panel at the position x, y.
    - ChildPanelOnModalReturn()
      Opens a modal child panel with return values at the position x,y.
    - ChildPanelOnModule()
      Opens a child panel in an arbitrary module.
    - ChildPanelOnModuleCheckPos()
      Opens a child panel and also checks the validity of the position and size.
    - ChildPanelOnModuleModal()
      Opens a modal child panel in the module "ModuleName".
    - ChildPanelOnModuleModalReturn()
      Opens a modal child panel in the module "ModuleName" with a return value.
    - ChildPanelOnModuleReturn()
      Opens a child panel in the module "ModuleName" with return values.
    - ChildPanelOnParent()
      Opens a child panel in the specified panel.
    - ChildPanelOnParentModal()
      Opens a modal child panel in the specified panel.
    - ChildPanelOnParentModalReturn()
      Opens a modal child panel in the specified panel with return values.
    - ChildPanelOnParentReturn()
      Opens a child panel in the specified panel with return values.
    - ChildPanelOnRelativ()
      Opens a child panel relative to the calling object.
    - ChildPanelOnRelativModal()
      Opens a modal child panel relative to the calling object.
    - ChildPanelOnRelativModalReturn()
      Opens a modal child panel relative to the calling object, with a return value.
    - ChildPanelOnRelativReturn()
      Opens a child panel with a return value, relative to the calling object.
    - ChildPanelOnReturn()
      Opens a child panel with return values.
    - ChildPanelReturnValue()
      Opens a child panel of a particular type with a return value.
    - cnsAddNode
      Adds a new node to a tree or sub-tree.
    - cnsAddTree
      Allows to create a tree or sub-tree.
    - cnsAddObserver
      Registers the given function as CNS observer.
    - cnsChangeNodeData
      Changes the data point (element) and type of the given node.
    - cnsChangeNodeDisplayNames
      Changes the display name of the given node.
    - cnsChangeNodeName
      Changes the ID of the given node.
    - cnsChangeTree
      Replaces a tree or sub-tree with a new tree.
    - cnsChangeViewDisplayNames
      Changes the display name of the given tree.
    - cnsChangeViewName
      Changes the ID of the given view.
    - cnsChangeViewSeparators
      Changes the separators of the given view.
    - cnsCreateView
      Allows to create a new view.
    - cnsDeleteTree
      Allows to delete a tree, sub-tree or node.
    - cnsDeleteView
      Allows to delete a view (with all its trees).
    - cnsGetAccessRight
      Returns the AccessRight (value of the defined parameter "propertyKey") as UINT for the given node.
    - cnsGetChildren
      Returns the ID paths of all child element of a node.
    - cnsGetDisplayNames
      Returns the display names of a node.
    - cnsGetDisplayPath
      Returns the display name path of a node
    - cnsGetId
      Returns the linked data point and CNSDataIdentifierType of the given node.
    - cnsGetIdSet()
      Returns the names of data points linked to the matching nodes.
    - cnsGetNodesByData
      Looks for nodes that are linked to the given data point (element).
    - cnsGetNodesByName()
      Looks for ID paths of nodes that match the given criteria.
    - cnsGetOPCAccessRight
      Returns the OPC AccessLevel (value of the key OA:OPC) as UINT for the given node.
    - cnsGetParent
      Returns the path of the parent node.
    - cnsGetProperty
      Retrieves the key value from the property of the defined node.
    - cnsGetPropertyKeys
      Returns a list of all keys which are defined for the given node.
    - cnsGetRoot
      Returns the ID path of the root node of the tree which contains the given node.
    - cnsGetSystemNames
      Returns the display names of the given system.
    - cnsGetTrees
      Returns the ID paths of all trees of the given view.
    - cnsGetUserData
      Returns the user data stored in a node.
    - cnsGetViewDisplayNames
      Returns the display names of the given view.
    - cnsGetViewSeparators
      Returns the separators of the given view.
    - cnsGetViews
      Returns the paths of all views in the given system.
    - cnsRemoveObserver
      De-registers the given observer function.
    - cnsRemoveProperty
      Removes the key from the property of the given node.
    - cnsSetProperty
      Sets the properties for the given node as key/value pair.
    - cnsSetSystemNames
      Changes the display name of the given system.
    - cnsSetUserData
      Stores user data in a node.
    - cnsSubStr
      Extracts parts of a CNS path.
    - cns_checkId
      Checks whether the ID is valid.
    - cns_checkName
      Checks whether the given display name is valid.
    - cns_checkSeparator
      Checks if the separator is valid or not.
    - cns_createNodeType
      Creates a new node type.
    - cns_createTreeOrNode
      Creates a tree or a node and adds it to the given parent element.
    - cns_createView
      Creates a new view.
    - cns_createViewDp
      Creates a internal data point for the given view.
    - cns_deleteNodeType
      Deletes the given node type.
    - cns_deleteTreeOrNode
      Deletes the given tree or node.
    - cns_deleteView
      Deletes the given view.
    - cns_deleteViewDp
      Deletes the internal data point which is linked to the given view.
    - Common Name Service Control Functions
      The following control functions are provided for an easier use of the Common Name Service feature in scripts.
    - cns_getNodeIcon
      Returns the path of the icon defined for the given ID.
    - cns_getNodeTypeDisplayName
      Returns the display name of the given node type.
    - cns_getNodeTypeIcon
      Returns the icon path of the given node type.
    - cns_getNodeTypeValue
      Returns the value of the given node type.
    - cns_getNodeTypes
      Returns all existing node types.
    - cns_getReadableViews
      Returns a list with all views (for which the current permission is sufficient) of the given system.
    - cns_getViewPermission
      Returns the permission bits defined for the given view.
    - cns_isNode
      Checks whether the given ID path is a node.
    - cns_isTree
      Checks whether the given node ID is a tree or not.
    - cns_isView
      Checks whether the given ID is a view.
    - cns_nodeExists
      Checks if the given node exists.
    - cns_setNodeIcon
      Sets an icon for the given node.
    - cns_setNodeTypeDisplayName
      Sets the multilingual display name of a node type.
    - cns_setNodeTypeIcon
      Allows to set an icon for the given node type.
    - cns_setNodeTypeValue
      Sets the value of the given node type.
    - cns_setViewPermission
      Sets the permission for the given view.
    - cns_treeExists
      Checks whether the given tree exists.
    - cns_viewDpToName
      Returns the ID of the view which is linked to the given internal data point.
    - cns_viewExists
      Checks whether the given view exists or not.
    - cns_viewNameToDpName
      Returns the name of the internal data point linked to the given view.
    - cns_changeNodeTypeName
      Changes the ID of a node type.
    - cns_changeViewName
      Changes the ID of the given view.
    - clearLastError()
      Allows to clear the last error which has been raised in WinCC OA.
    - clearLogViewer()
      Allows to clear the log viewer by script.
    - closeDialog()
      Closes its own dialog for simple configuration.
    - closeProgressBar()
      The function closes the module for the progress bar.
    - colorDblsWritable()
      The function returns True when UI manager may change the colorDB.
    - colorEditor()
      Opens the color editor and writes the names of the color to colstr.
    - colorGet()
      A color scheme is a collection of colorDB files located in a subdirectory of proj_path/colorDB, for example, WinCC_OA_proj_path/colorDB/DayScheme/colors. Hence, the name of the schema is "DaySchema" - the name of the directory. The function colorGet() returns a blink or an RGB definition of a color from a desired colorDB file.
    - colorGetActiveScheme()
      A color scheme is a collection of colorDB files located in a subdirectory of proj_path/colorDB, for example, proj_path/colorDB/DayScheme/colors. Hence, the name of the schema is "DaySchema" - the name of the directory. The function colorGetActiveScheme returns the active color scheme.
    - colorGetAlias()
      A color scheme is a collection of colorDB files located in a subdirectory of proj_path/colorDB, for example, WinCC_OA_proj_path/colorDB/DayScheme/colors. Hence, the name of the schema is "DaySchema" - the name of the directory. The function colorGetAlias() returns the color name of an alias from a desired colorDB file.
    - colorRemove()
      A color scheme is a collection of colorDB files located in a subdirectory of proj_path/colorDB, for example, proj_path/colorDB/DayScheme/colors. Hence, the name of the schema is "DayScheme" - the name of the directory. The function "colorRemove" deletes a color or alias definition from a colorDB file.
    - colorSet()
      A color scheme is a collection of colorDB files located in a subdirectory of proj_path/colorDB, for example, WinCC_OA_proj_path/colorDB/DayScheme/colors. Hence, the name of the schema is "DaySchema" - the name of the directory. The function colorSet() specifies a color in the specified colorDB file.
    - colorSetActiveScheme ()
      A color scheme is a collection of colorDB files located in a subdirectory of proj_path/colorDB, for example, proj_path/colorDB/DayScheme/colors. Hence, the name of the schema is "DayScheme" - the name of the directory. The function colorSetActiveScheme sets the active color scheme.
    - colorSetAlias()
      A color scheme is a collection of colorDB files located in a subdirectory of proj_path/colorDB, for example, WinCC_OA_proj_path/colorDB/DayScheme/colors. Hence, the name of the schema is "DaySchema" - the name of the directory. The function colorSetAlias() specifies an alias for a color in a colorDB file.
    - colorToRgb()
      The function retrieves the RGB values from the given color.
    - commonConfirm()
      Causes an acknowledge all of all the panels in the module "modulName".
    - confirmMode()
      Switches the module to individual acknowledge mode.
    - connectedShapes()
      Sets graphics objects where the function dpConnect() is active to a particular color for a certain time. All graphics objects that are connected to DPs are therefore displayed.
    - constructor
      Instances a new object of type MindSphereAsset.
    - convManIdToInt()
      Returns an integer that corresponds to the ManagerIdentifier.
    - convManIntToName()
      Converts an integer, which corresponds to the manager identifier, to manager name.
    - copyAllFiles()
      Copies all the files of the specified directory to a new directory.
    - copyAllFilesRecursive()
      Copies files and subdirectories of a directory to a new directory.
    - copyFile()
      Copies the specified source file to the specified target file or to the specified directory.
    - cos()
      Calculates the cosine.
    - cosh()
      Returns the hyperbolic cosine of an angle.
    - createAnimation()
      With the function you can create more complex animations. To create an animation group, call this function.
    - createComObject()
      Creates a COM object (also without user interface (not ActiveX)).
    - createNotification()
      The function creates a notification.
    - createPanel()
      Creates an (empty) panel file in a defined size (width and height) named "filename".
    - createQRCodeFile()
      Creates a QR code file.
    - createSymbol()
      Adds a panel references in a panel or layout at a later time during run time. The function is identical to addSymbol() but prevents the triggering of the added objects initialize scripts.
    - createUuid()
      This function allows to create Universally Unique Identifiers (UUID).
    - crypt()
      Encrypts the transferred text.
    - cryptoHash()
      Allows to create a checksum for a string or blob element.
    - cssLengthToPixel()
      Calculates the lenght of a given font in pixel.
  - Functions D
  - Functions E
  - Functions F
  - Functions G
  - Functions H
  - Functions I
  - Functions J
  - Functions K
  - Functions L
  - Functions M
  - Functions N
  - Functions O
  - Functions P
  - Functions Q
  - Functions R
  - Functions S
  - Functions T
  - Functions U
  - Functions V
  - Functions W
  - Functions X
  - Functions Y
  - Functions Z
- CTRL Debugger
  With the CTRL Debugger you can debug the programming language Control.
- CtrlExtension
  The CtrlExtension allows the addition of custom C++ code.

cnsGetRoot

Returns the ID path of the root node of the tree which contains the given node.

Synopsis

bool cnsGetRoot(string cnsNodePath, string &cnsRootPath);

Parameters


Parameter	Description
cnsNodePath	The ID path of the node
cnsRootPath	Receives the ID path of the root node

Return value

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

Errors

Description

This function returns the ID path of the root node of the tree which contains the given node.

main()
{
  string rootPath;
  cnsGetRoot("System1.View1:A.B.C.D.e", rootPath);
  DebugN(rootPath);
}

Availability

UI, CTRL