Compiling Classes

Caché class definitions are compiled into application routines by the class compiler. Classes cannot be used in an application before they are compiled.

The class compiler differs from the compilers available with other programming languages, such as C++ or Java, in two significant ways: first, the results of compilation are placed into a shared repository (database), not a file system. Second, it automatically provides support for persistent classes.

Specifically, the class compiler does the following:

It generates a list of dependencies — classes that must be compiled first. Depending on the compile options used, any dependencies that have been modified since last being compiled will also be compiled.
It resolves inheritance — it determines which methods, properties, and other class members are inherited from superclasses. It stores this inheritance information into the class dictionary for later reference.
For persistent and serial classes, it determines the storage structure needed to store objects in the database and creates the necessary runtime information needed for the SQL representation of the class.
It executes any method generators defined (or inherited) by the class.
It creates one or more routines that contain the runtime code for the class. The class compiler groups methods according to language (ObjectScript and Basic) and generates separate routines, each containing methods of one language or the other.
If you specify the Keep Generated Source option with the class compiler, you can view the source for the routines using the View Other Code command (from the View menu) within Studio.
It compiles all of the generated routines into executable code.
It creates a class descriptor. This is a special data structure (stored as a routine) that contains all the runtime dispatch information needed to support a class (names of properties, locations of methods, and so on).

Invoking the Class Compiler

There are several ways to invoke the class compiler:

From within Studio using the option in the Build menu.
From the Caché command line (in the Terminal) using the Compile() method of the %SYSTEM.OBJOpens in a new tab object:
```
 Do $System.OBJ.Compile("MyApp.MyClass")
```

If you use SQL DDL statements to create a table, the class compiler is automatically invoked to compile the persistent class that corresponds to the table.

Class Compiler Notes

Compilation Order

When you compile a class, Caché also recompiles other classes if the class that you are compiling contains information about dependencies. For example, the system compiles any subclasses of the class. On some occasions, you may need to control the order in which the classes are compiled. To do so, use the System, DependsOn, and CompileAfter keywords. For details, see the Caché Class Definition Reference.

To find the classes that the compiler will recompile when you compile a given class, use the $SYSTEM.OBJ.GetDependencies() method. For example:

SAMPLES>d $system.OBJ.GetDependencies("Sample.Address",.included)
 
SAMPLES>zw included
included("SOAP.Demo.LookupCity")=""
included("SOAP.DemoProxy.LookupCity")=""
included("Sample.Address")=""
included("Sample.Customer")=""
included("Sample.Employee")=""
included("Sample.Person")=""
included("Sample.Vendor")=""

The signature of this method is as follows:

classmethod GetDependencies(ByRef class As %String, Output included As %String, qspec As %String) as %Status

Where:

class is either a single class name (as in the example), a comma-separated list of class names, or a multidimensional array of class names. (If it is a multidimensional array, be sure to pass this argument by reference.) It can also include wildcards.
included is a multidimensional array of the names of the classes that will be compiled when class is compiled.
qspec is a string of compiler flags and qualifiers. See the next subsection. If you omit this, the method considers the current compiler flags and qualifiers.

Viewing Class Compiler Flags and Qualifiers

The Compile() method also allows you to supply flags and qualifiers that affect the result. Their position in the argument list is described in the explanation of the Compile() method. To view the applicable flags, execute the command:

 Do $System.OBJ.ShowFlags()

This produces the following output:

    b - Include sub classes.
    c - Compile. Compile the class definition(s) after loading.
    d - Display. This flag is set by default.
    e - Delete extent.
    h - Generate help.
    i - Validate XML export format against schema on Load.
    k - Keep source.  When this flag is set, source code of
        generated routines will be kept.
    l - Lock classes while compiling.  This flag is set by default.
    p - Percent.  Include classes with names of the form %*.
    r - Recursive.  Compile all the classes that are dependency predecessors.
    s - Process system messages or application messages.
    u - Update only.  Skip compilation of classes that are already up-to-date.
    y - Include classes that are related to the current class in the way that
        they either reference to or are referenced by the current class in SQL usage.

These flags are deprecated a, f, g, o, q, v
Default flags for this namespace =dil
You may change the default flags with the SetFlags(flags,system) classmethod.

To view the full list of qualifiers, along with their description, type, and any associated values, execute the command:

 Do $System.OBJ.ShowQualifiers()

Qualifier information displays in a format similar to one of the following:

            Name: /checkschema
    Description: Validate imported XML files against the schema definition.
           Type: logical
           Flag: i
  Default Value: 1

           Name: /checksysutd
    Description: Check system classes for up-to-dateness
           Type: logical
  Default Value: 0

           Name: /checkuptodate
    Description: Skip classes or expanded classes that are up-to-date.
           Type: enum
           Flag: ll
      Enum List: none,all,expandedonly,0,1
  Default Value: expandedonly
  Present Value: all
  Negated Value: none

Compiling Classes that Include Bitmap Indices

When compiling a class that contains a bitmap index, the class compiler generates a bitmap extent index if no bitmap extent index is defined for that class. Special care is required when adding a bitmap index to a class on a production system. For more information, see the section “Generating a Bitmap Extent Index” in the “Defining and Building Indices” chapter of Caché SQL Optimization Guide.

Compiling When There Are Existing Instances of a Class in Memory

If the compiler is called while an instance of the class being compiled is open, there is no error. The already open instance continues to use its existing code. If another instance is opened after compilation, it uses the newly compiled code.