References to parts

This section describes a set of rules that determine how EGL identifies the part to which a name refers. These rules are important in the following situations:

A second set of rules determine how EGL resolves variable references. For details, see References to variables and constants.

Basic visibility rules

In the simplest case, you define parts one after the next in a single package, without declaring one part within another. The following list omits many details, but shows a series of parts that are at the same hierarchical level:

   Function:  Function01
   Function:  Function02
   Function:  Function03
   Record:    Record01

Parts at the same level are available to one another. Function01, for example, can invoke one or both of the other functions; and Record01 can be used as a typedef for variables in each of the three functions.

In most cases, a part cannot nest another part. The exceptions are as follows:

A program, library, or pageHandler can nest functions, but even then, the inclusion must be direct; a function cannot nest another function
A form group can nest forms

An example with nested parts is as follows:

   Program:  Program01
     Function:  Function01
     Function:  Function02
   Function:  Function03
   Record:    Record01

Parts at the top level are available to every other part in the package. However, the nested parts (Function01 and Function02) are available only to a subset of parts in the package:

They are available to each other.
They are available to the nesting part and to functions that are used by the nesting part at run time. If Function01 invokes Function03, for example, Function03 can invoke Function02 because Function03 is used in Program01.

Finally, if your code includes text or print forms, a use declaration is necessary to access the form group that includes those forms. A use declaration is also desirable when accessing data tables or libraries. For additional information, see Use declaration.

Additional visibility rules

Most development efforts have parts that are shared across more than one package. These rules are in effect:

Any part in the file can reference parts from other packages, so long as the accessed parts have these characteristics:
- Are top-level parts
- Are not declared as private
- Are either in the same project as the referencing part or are in a project listed in the EGL build path of the referencing project
You can provide access in these ways:
- You can qualify the part name with the package name, in which case no import statement is needed in your source file. If a package name is my.package, for example, and a part name is myPart, you can reference the part as follows:
```
  my.package.myPart
```
- You can use import statements, which provide the following benefits:
  - Import statements make it possible for you to avoid qualifying the names of the imported parts, unless use a package name to avoid an ambiguous reference.
  - Import statements provide a way to document what packages are used in the source code.

Part-name resolution

To resolve a part reference, EGL conducts a search that includes one to many steps. The following statements apply at each step:

The search ends successfully if a uniquely named part is found
The search ends with an error if two same-named parts are found.

These situations are possible:

The part reference is qualified with a package name; in this case, the search always includes only one step
The part reference is not qualified with a package name and is not a function invocation
The part reference is not qualified with a package name and is a function invocation

The next statements are rarely important, but could apply in either of the last two situations:

The property containerContextDependent in the referencing function may be set to yes. You set that property to extend the name space used to resolve references, as described in containerContextDependent.
If one of your functions is visible to the program or page handler and has a name that is identical to the name of an EGL system function, your function is referenced rather than the system function.

Part-name resolution when the package name is specified

As noted earlier, you can specify the name of a package when referencing a part, as in the example my.package.myPart. The current project is considered, as are any projects listed in the EGL build path.

If the reference is from a part that is inside the same package, the following statements apply:

The package name is valid but unnecessary
The part name is resolved even if the part is declared as private

Part-name resolution (other than function invocation) when the package name is not specified

If a part references a part other than a function and does not specify a package name, the steps in the search order are as follows:

Search the parts nested in the same container as the one in which the referencing part is nested.
Search the parts that were explicitly imported in the file where the referencing part resides. The current project is considered, as are any projects listed in the EGL build path.
Each import statement in this case explicitly references a particular part in a particular package. The part named in such an explicit-type import statement acts as an override of the same-named part in the current package.

If you have identically named packages in two different projects, a given explicit-type import statement uses the EGL build path to do a first-found search, stopping when the required part is found. (The part must be unique to a package in a given project.) The presence of a same-named package in two different projects is not an error, but creates a confusing situation and is not recommended.

An error occurs if you have two explicit-type import statements that name the same part.
Search the top-level parts that are in the same package as the referencing part. The current project is considered, as are any projects listed in the EGL build path. Finding two parts of the same name causes an error.
Search other imported parts. The current project is considered, as are any projects listed in the EGL build path.
Each import statement in this case references all parts in a given package and is called a wild-card import statement.

If you have identically named packages in two different projects, a given wild-card import statement uses the EGL build path to do a first-found search, stopping when the required part is found. (The part must be unique to a package in a given project.)

If more than one wild-card import statement retrieves the same-named part, an error occurs.

Function invocation when the package name is not specified

If a part invokes a function and does not specify a package name, the steps in the search order are as follows:

Search the functions nested in the same container as the one in which the invoker is nested.
Search the functions residing in the libraries specified in the container's use declarations.
Continue the search only with functions that are being included in the container at generation time. (To include functions other than those nested in the same container or residing in a library, set the container property includeReferencedFunctions to yes.)
The search of the included functions occurs as follows:
1. Search the parts that were explicitly imported in the file where the container resides. The current project is considered, as are any projects listed in the EGL build path.
  Each import statement in this case explicitly references a particular part in a particular package. The part named in such an explicit-type import statement acts as an override of the same-named part in the current package.
  
  If you have identically named packages in two different projects, a given explicit-type import statement uses the EGL build path to do a first-found search, stopping when the required function is found. (The function must be unique to a package in a given project.) The presence of a same-named package in two different projects is not an error, but creates a confusing situation and is not recommended.
  
  An error occurs if you have two explicit-type import statements that name the same part.
2. Search the top-level functions in the same package as the container. The current project is considered, as are any projects listed in the EGL build path. An error occurs if the search finds two parts of the same name.
3. Search other imported parts. The current project is considered, as are any projects listed in the EGL build path.
  Each import statement in this case references all parts in a given package and is called a wild-card import statement.
  
  If you have identically named packages in two different projects, a given wild-card import statement uses the EGL build path to do a first-found search, stopping when the required part is found. (The part must be unique to a package in a given project.)
  
  If more than one wild-card import statement retrieves the same-named part, an error occurs.

Program invocation

When a program is invoked on a call or transfer statement, the argument list of the invoker must match the parameter list of the invoked program. A mismatch of argument and parameter causes an error.