contact contact

B.08.20 / Release Notes / Language / External Class Files

External class files and Class Loader

  Eloquence B.08.20 introduces external class definitions (classes and its methods defined in a separate file). Classes and methods may be loaded automatically.

External classes

Classes can be defined in a program or in a separate program file (external classes). If defined in a separate file the following assumptions are made:
  • The main program segment is used to define the class (or multiple classes). Any statement besides a comment, OPTION BASE and a type definition results in a runtime error.

  • Any subroutines or functions in the file implement the methods for the class(es) defined in the main segment.

    Note: The bahavior of subroutines/functions included in that file not implementing member functions is undefined. They may be silently ignored or result in a runtime error in the future.

External classes may be loaded explicitly in the program with the LOAD CLASS statement:

LOAD CLASS "Customer"
The argument of the LOAD CLASS statement is the name and optionally path of a program file which implements a class as described above. If a class path is defined it is used to load the class defintion instead of the devail volume (MSI).

The program file is opened and classes defined in the main program segment are registered with Eloquence. Any member functions in that class are marked as loadable on demand and are read dynamically when needed.

A class read with the LOAD CLASS statement is subject to the usual type scoping rules. Unless defined as EXPORT it is only available in the current program segment (subroutine or function) and is discarded if the program segment is left.

Member functions for externally defined classes read with the LOAD CLASS statement are managed dynamically. They are loaded when used for the first time and deleted either along with the class or when they have not been used for some time.

Please note: Typically, a class path is defined to make loading of externally defined classes automatic.

The DEL CLASS statement is used to discard class definition and any member function of the specified class.

DEL CLASS Typename
The DEL CLASS argument is the type name as specified in the class definition. The class definition and any member function is deleted. In case the class is in use (an instance of that class exists) the deletion of the class is delayed until any instance is deleted.

It is expected that DEL CLASS is rarely useful in an applicstion.

Defining a Class Path

The Class Path is similar to the Program file path but affects the LOAD CLASS statement and autoloadinng of class methods.

A class path may be defined in the Eloquence config file, through the EQCLSPATH environment variable or by the application using the CLSPATH statement.

Eloquence config file

The CLSPATH config item may be used in the config file (eloq.config or .eloqrc) to specify a class path. For example,
CLSPATH ".:/opt/eloquence/8.2/share/prog"

The EQCLSPATH environment variable

The EQCLSPATH environment variable may be used to specify a path. If present, this pas precendence over a definition in the config file. For example,
export EQCLSPATH=.:/opt/eloquence/8.2/share/prog

The CLSPATH statement

The CLSPATH statement may be used to specify a path. This has precendence over a definition in the config file or the EQCLSPATH environment variable. For example,
CLSPATH ".:/opt/eloquence/8.2/share/prog"

On demand loading of classes and methods

Referencing an undefined class or method results in a runtime error. When using automatic code management class definitions and methods may be loaded on demand.

On-demand loading of classes is enabled by default. It may be configured in the Eloquence config file with the OPTION CLSLOAD.

If the option value is zero autoloading is disabled, otherwise enabled.

The language runtime will use the class apth (if defined) or the default volume label (MSI) to load classes and methods currently not present. Each class must be defined in a separate PROG file with a matching name. If a matching PROG file could not be found a runtime error is returned.

Code autoload makes use of the NLN mode. Any code segment loaded automatically is not renumbered but retains the original program line numbers.

Using a class path

A path affects the LOAD CLASS statement that is used to load a class definition from a program file (unless an absolute path or a volume label is specified). When a class path is defined it also enables autoloading of class definitions and methods. A reference to an undefined class will result in loading the class definition, calling a cals method not currently in memory will load the method from the class file.

The CLSPATH statement may be used by an application to specify a class path. This class path is active until another class path is assigned. An empty string may be used to specify an empty class path (and disable use of class path).

The CLSPATH$ function may be used to obtain the currently active class path. It returns an empty string if no class path is active.

The example below adds the "HOME"/cls directory as a first element of the class path and then loads the program file "START".


Loading classes automatically

If enabled, the language runtime will load class definitions and methods on demand. The .PROG file name must match the class name.

The example below demonstrates the use of autoloading of classes and methods.

--- Tsample.PROG ---
NEW A AS Tsample2
CALL A.Print

--- Tsample1.PROG ---
TYPE Tsample1
SUB Tsample1:Test
  PRINT "Tsample1: ";TYPEOF$(THIS)
SUB Tsample1:Print
  PRINT "Tsample1: ";TYPEOF$(THIS)
  PRINT "Iv=";.Iv

--- Tsample2.PROG ---
TYPE Tsample2 EXTENDS Tsample1
  DIM Sv$[10]
SUB Tsample2:Print
  PRINT "Tsample2: ";TYPEOF$(THIS)
  PRINT "Iv=";.Iv
  PRINT "Sv$=";.Sv$

Running the Tsample program causes the loading of the class definition Tsample2 which in turn will load the class definition Tsample1. It then prints the result below:

Tsample1: Tsample2
Tsample2: Tsample2
Iv= 1111
Since the Tsample2 class does not define a method Test it falls back to the Test method provided by the base class. However, since the type of the object is still Tsample2 this gets printed. Next, the appropriate Print method gets called. The class methods in this example are loaded as needed.

  Privacy | Webmaster | Terms of use | Impressum Revision:  2011-02-15  
  Copyright © 2012 Marxmeier Software AG