Scope

(Engine-Level Function)

Description:	Performs a scope resolution and returns a reference to the requested member within a module or other object.
Returns:	Reference
Usage:	Script or steady state.
Function Groups:	Basic Module
Related to:	Variable \| ScopeLocal \| LocalScope
Format:	Scope(Object, Member[, ScopeLocal])
Parameters:

Object

Required. Any expression for the object value (module) where Member may be found.

Member

Required. Any text expression for the member name. This must be a simple variable or module.

ScopeLocal

Optional. A Boolean expression. Defaults to FALSE if missing, invalid or if a non-Boolean is provided.
If set TRUE then the call will not search up the scope tree for name matches.

Comments:

This function is the same as the '\' operator, when the '\' operator is used between two operands. (Object\Member). Unlike the backslash operator, the Scope function allows any text string to be used.
This function may be used as a value, or as an L-value (on the left hand side of an assignment). This function is used to reference one specific occurrence of a variable in a module, from another module.
If the final result is Invalid, this function looks for the presence of backslash (\) characters in the second parameter and parses the result.
When searching for a match, this function ignores variables with the PROTECTED attribute. That is, if such a variable is encountered the search will simply skip over it and continue. Detecting variables with the PROTECTED attribute requires use of the 'Variable' function.

If you can use LocalScope instead of Scope, then you should. For example, perhaps you have a tag widget and want to draw range bars based on RangeMin & RangeMax. If you use \Root\RangeMax, and for some reason the tag linked to the widget does not have a RangeMax, then the Scope operator will walk up the scope tree, perhaps finding a RangeMax variable in a parent tag. It is likely that you would rather have an Invalid in that case rather than some parent tag's range value, therefore it is better to do \Root.RangeMax.

Example 1:

  Scope(Code, "TagName");

Returns a reference to the given tag object.

Example 2:

Given the following tags:

MyContext
MyContext\IO_1
MyContext\Port1
MyContext\Port1\Driver1

If MyContext\IO_1 is configured to use MyContext\Port1\Driver1, the DeviceTag parameter will typically be set to "Port1\Driver1". The IO tag gets its driver tag as follows:

Scope(Root, DeviceTag);

That is, Scope(Root, "Port1\Driver1"); Operations inside the string other than backslashes are not supported. The local scope dot operator is not supported.

Using ScopeLocal. Given the following:

  Scope(Code, "MyService\Ready");

The Scope operation will never find a variable called "MyService\Ready" in Code, but could find a variable called MyService containing a service object, which itself contains a variable called Ready. This Scope() would return the value of that Ready variable.

If the MyService object does not contain a variable called Ready, but Code does contain a Ready variable, then Scope will return the value of Code's Ready variable, which may not be what is desired. If the ScopeLocal parameter is added and set to TRUE, then it will return Invalid because it will not scope up from MyService to the Ready variable in Code.