Back to Contents

Built-in Classes

Summary:

See also: Variables, Functions.

Definition

Purpose:

A built-in class is a predefined object template that is provided by the runtime system.

Syntax:

package.classname

Notes:

  1. package is the name of the module the class comes from.
  2. classname is the name of the built-in class.

Usage:

A built-in class implements a set of methods to manage a specific domain. For example, the DomNode class provides methods to manipulate DOM nodes. Methods can be invoked like global functions, by passing parameters and/or returning values.

There are two kind of methods: Class Methods and Object Methods. You call Class Methods by using the class name as prefix; no object has to be created. Object Methods are called by specifying the object variable as the prefix; the object must exist. In both cases, you must use the period character as a separator. 

To handle an object in your program, you define a variable with the class identifier (package class path + class name):

01 DEFINE obj om.DomNode

Objects must be instantiated (created) before using them. You usually instantiate objects with a Class Method: 

01 DEFINE n om.DomDocument
02 LET n = om.DomDocument.create("Stock")

The object variable only contains the reference to an object. For example, when passed to a function, only the reference to the object is copied onto the stack.

When the object is created, you can call object methods by using the object variable as a prefix:

01 DISPLAY obj.getAttribute("name")

You do not have to destroy objects. This is done automatically by the runtime system for you, according to a reference counter.

01 MAIN
02    DEFINE d om.DomDocument
03    LET d = om.DomDocument.create("Stock")  -- Reference counter = 1
05 END MAIN  -- d is removed, reference counter = 0 => object is destroyed.

You can pass object variables to functions or return them from functions. In the following example, the function creates the object and returns its reference on the stack: 

01 FUNCTION createStockDomDocument( )
02    DEFINE d om.DomDocument
03    LET d = om.DomDocument.create("Stock")  -- Reference counter = 1
04    RETURN d
05 END FUNCTION  -- Reference counter is still 1 because d is on the stack

Another part of the program can get the result of that function and pass it as a parameter to another function:

01 MAIN
02    DEFINE x om.DomDocument
03    LET x = createStockDomDocument( )
04    CALL writeStockDomDocument( x )
05 END MAIN
06 
07 FUNCTION writeStockDomDocument( d )
08    DEFINE d om.DomDocument
09    DEFINE r om.DomNode
10    LET r = d.getDocumentElement()
11    CALL r.writeXml("Stock.xml")
12 END FUNCTION