dpGetAllDescriptions()

Returns via dps all data points and via descriptions all descriptions that correspond to the descriptionFilter. You can also specify a dpeFilter. This means that only the data points containing the specified data point element are returned provided that the description of the data point element corresponds to the descriptionFilter.

The function replaces dpGetAllComments(), which is conserved for compatibility.

Synopsis

int dpGetAllDescriptions(dyn_string &dps, dyn_string &descriptions [, string descriptionFilter [, string dpeFilter [, int mode]]]);

Parameters

Parameter Description
dps Data points that correspond to the description filter (data points that contain the description used as description filter)and to the dpeFilter (the dpeFilter can be used to filter only data points containing a specific element).
descriptions Descriptions corresponding to the description filter.
descriptionFilter Pattern string for filtering the descriptions (for example,"Engine*", "*").
dpeFilter Pattern string for filtering data point elements (for example, dpeFilter = "*.para"). An empty dpe pattern ("") and a "*" are treated like ALL DPEs. Also queries on remote systems can be executed. The system is part of the dpeFilter (for example,"Sys23:*.**" - returns all aliases of a specific system. "*:*.**" again would return the aliases of all systems). Several systems can be defined with a list (for example, "Sys{1,2,3,45}:Ex*").
mode Mode of functionality. See also the description below.

Return Value

Return value is the number of descriptions that were found using the function. When you have specified , for example, the description filter "valve1" and three descriptions (three data points containing this description) were found the return value is 3. In the event of errors the return value is -1.

Errors

The function getLastError() can be used to return the last error. Possible errors are missing arguments in the function.

Description

Returns via dps all data points and via descriptions all descriptions that correspond to the descriptionFilter. You can also specify a dpe filter. This means that only the data points containing the specified data point element are returned provided that the description of the data point element corresponds to the descriptionFilter. The dpeFilter "*" means that all data points matching the description filter criteria are returned (no dpeFilter, all dpes are returned). If you want to filter out , for example, data points containing a "para" element use "*.para" as dpeFilter (see DP Selector).

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 dpGetAllDescriptions() 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 is returned. For the root DPE the DP name is returned.

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

Mode 1: Returns the description from the DPE. If no description exists, the description of the DPE from the master data point is linked with the description from the root element resp. the DP name (if no description exists on the root element): Description = root DP + " " + master DP. If no master DP or no description at the appropriate element exists, the DPE name (like mode 0) is returned.

Mode 2: Like mode 1, only the sequence is turned around: Description = master DPE + " " + root DP.

Mode 3: Returns the description of the DPE. If no description exists, the description becomes assembled from those at the items from the root: Description = root DP + " " + master DPE1 + " " + ... + master DPE. Exists no description on the master DP, the element name (mode -1) is taken. Taking a description from the element itself (not from the master DP), this description is valid in place of further recursion. Exists no master DP or no description at the appropriate element, the DPE name is taken (mode 0).

By default mode 1 is used.

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

Example

main()
{
  int number;
  dyn_string dps, comment;
  number = dpGetAllDescriptions(dps, comment, "*"); 
  /* returns all descriptions since the description filter is "*"
  */
  DebugN(number, dps, comment); 
  /* prints the number of found descriptions, list of the data
  points containing the searched description and a list of the
  descriptions */ 
}

Assignment

Data point function

Availability

CTRL