cnsGetNodesByName()

Looks for ID paths of nodes that match the given criteria.

Synopsis

bool cnsGetNodesByName(string pattern, [string view,] int whichNames, int langIdx, int type, dyn_string &cnsPaths);

Parameters

Parameter Description
pattern

This pattern is checked against the ID path or display name path.

As of version 3.20, there is a new default behavior.

The wildcards *, ** and ? can be used depending on the config entry cnsUseDoubleAsterisk in the [general] section.

The config entry is set to 1 by default, which means that:

  • One asterisk * returns one level.
  • Two asterisks ** return all levels.
  • The question sign ? returns one character.

You can also activate the old behavior by setting the config entry to 0. This means that the wildcards * and ? can be used:

  • One asterisk * returns all levels.
  • The question sign ? returns one character.
view Restricts the search to the given view
whichNames

Defines whether to look for ID path, display name path or both. Furthermore, it is possible to define if case-sensitivity is enabled or not. Therefore, the following constants are available:

  • CNS_SEARCH_NAME - Search for ID path
  • CNS_SEARCH_DISPLAY_NAME - Search for display name path
  • CNS_SEARCH_ALL_NAMES - Search for ID path and display name path
  • CNS_SEARCH_CASE_INSENSITIVE - the search is case insensitive (both upper and lower case are searched).

These constants can be combined by using the pipe |.
langIdx

Defines in which language the name paths shall be matched.

  • CNS_SEARCH_ALL_LANGUAGES - all languages

This parameter is ignored if whichNames is not defined as CNS_SEARCH_ALL_NAMES or CNS_SEARCH_DISPLAY_NAMES
type

Limits the result to a matching CNSDataIdentifierType. The following constants are available:

  • CNS_DATATYPE_EMPTY - Type "Structure"
  • CNS_DATATYPE_DATAPOINT - Type "Data point"
  • CNS_DATATYPE_ALL_TYPES - All types
  • custom type, e.g.: 501
cnsPaths Receives the ID paths of the nodes which match the criteria.

Return value

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

Errors

-

Description

This function returns ID paths of nodes that match the given criteria.

This function returns ID paths of nodes that match the given search criteria ( "Node1" under View1, all languages are searched and the function searches for the structure type). Note that you have to specify a leading * for the search pattern in order to receive a result.

main()
{
  dyn_string dps;
  cnsGetNodesByName("*Node1", "System1.View1:", CNS_SEARCH_ALL_NAMES, CNS_SEARCH_ALL_LANGUAGES,CNS_DATATYPE_EMPTY, dps);
  DebugN(dps);
}

Returns all data point paths that match the search pattern (the path contains an 'o' and the search is case insensitive).

main()
{
  dyn_string nodes;
  cnsGetNodesByName("*o*", CNS_SEARCH_NAME | CNS_SEARCH_CASE_INSENSITIVE, CNS_SEARCH_ALL_LANGUAGES, CNS_DATATYPE_DATAPOINT, nodes);
  DebugN("Paths:", nodes);
}

Availability

UI, CTRL