dpGetDescription()

Synopsis

langString | dyn_langString dpGetDescription(string | dyn_string dp [, int mode]);

Parameters

Return Value

Description in all available languages or empty strings in all languages.

Errors

The errors can be retrieved with getLastError(). This includes missing arguments or when the data point does not exist.

Description

The function dpGetDescription() returns the description/descriptions for the data point element or data point dp. The descriptions can also be set with dpSetDescription().

The description is a property of the DPEs and not of the DPs. For a correct request of a DP with one level use: dpGetDescription("Valve17."). Essentially is the POINT after 17, which shows, that the request belongs to the first level!

Using DPs with more levels for a request, the example might look like this: dpGetDescription("Valve17.value.position"). This example queries the description of the data point element "position".

The mode of operation is controlled via a mode:

Config entry: dpGetDescriptionMode in [general] section, values 0, 1, 2, 3 (-1, -2), the mode can be overwritten by an optional parameter in the dpGetDescription() call in CTRL.

Mode -2 (internally): Returns only the description at the DPE, error, if none exists (as before).

Mode -1 (internally): Returns the description from the DPE. If no description exists, the element name resp. for the root DPE the DP name is returned.

Mode 0: Returns the description from the DPE. If no description exists, the DPE name (DP.EL1.EL2) is returned.

Mode 1: Returns the description of the datapoint element. If a description does not exist, the text "RootNode Description DP" and the description of the master datapoint element is returned for the ROOT DP. (Text: "RootNode Description DP" and the description of the master datapoint element).

For the other DPs, the datapoint name of the queried datapoint and the description of the DP element of the master datapoint are returned (DP name + description of the DP element of the master datapoint).

If a description does not exist for the DP element of the master datapoint either, the datapoint name or the DP element name is returned (depending on whether you query a datapoint or an element).

Mode 2: Returns the description of the datapoint element. If a description does not exist, the description of the master datapoint element and the text "RootNode Description DP" are returned for the root DP.

(the Description of the master datapoint element and the text "RootNode Description DP").

For the other DPs, the description of the DP element of the master datapoint and the datapoint name of the queried datapoint are returned (the description of the element of the master datapoint + DP name).

If a description does not exist for the DP element of the master datapoint either, the datapoint name or the DP element name is returned (depending on whether you query a datapoint or an element)..

Mode3: Returns the description of the datapoint element. If a description does not exist, the text "RootNode Description DP <ElementName>" and the description of the master datapoint element are returned for the ROOT DP.

(Text: "RootNode Description DP <ElementName>" and the description of the master datapoint element).

For the other DPs, the datapoint name and the datapoint element name of the queried datapoint and the description of the DP element of the master datapoint are returned (DPName +DPE name + description of the DP element of the master datapoint).

If a description does not exist for the DP element of the master datapoint either, the datapoint name or the DP element name is returned (depending on whether you query a datapoint or an element).

The mode 1 is used by default.

Delete description: Setting an empty description and a description exists on the master DP, the description is deleted physically on the DPE, but dpGetDescription() returns the calculated description.

Example

A new data point is created, a comment is written and read out again for checking.

main()
{
  dpCreate("number_1", "ExampleDP_Int"); //New DP
  dpSetDescription("number_1.", "Here is the comment");
  DebugN(dpGetDescription("number_1.")); //Output to Log
  Viewer
}

Assignment

Data point function

Availability

UI, CTRL