Defining and Compiling Classes

Object Classes

The phrase object class refers to any subclass of %RegisteredObjectOpens in a new tab. With an object class, you can create an instance of the class, specify properties of the instance, and invoke methods of the instance.

The generic term object refers to an instance of an object class.

There are three general categories of object classes:

• Transient object classes or registered object classes are subclasses of %RegisteredObjectOpens in a new tab but not of %PersistentOpens in a new tab or %SerialObjectOpens in a new tab (see the following bullets).

  For details, see Working with Registered Objects.

• Persistent classes are subclasses of %PersistentOpens in a new tab, which is a direct subclass of %RegisteredObjectOpens in a new tab. The %PersistentOpens in a new tab class includes the behavior of %RegisteredObjectOpens in a new tab and adds the ability to save objects to disk, reopen them, and so on.

  For details, see Introduction to Persistent Objects.

• Serial classes are subclasses of %SerialObjectOpens in a new tab, which is a direct subclass of %RegisteredObjectOpens in a new tab. The %SerialObjectOpens in a new tab class includes the behavior of %RegisteredObjectOpens in a new tab and adds the ability to create a string that represents the state of the object, for inclusion as a property within another object (usually either a transient object or a persistent object). The phrase serializing an object refers to the creation of this string.

  For details, see Defining and Using Object-Valued Properties.

The following figure shows the inheritance relationship among these three classes. The boxes list some of the methods defined in the classes:

Collection classes and stream classes are object classes with specialized behavior.

Data Type Classes

The phrase data type class refers to any class whose ClassType keyword equals datatype or any subclass of such a class. These classes are not object classes (a data type class cannot define properties, and you cannot create an instance of the class). The purpose of a data type class (more accurately a data type generator class) is to be used as the type of a property of an object class.

Choosing a Superclass

When you define a class, one of your earliest design decisions is choosing the class (or classes) which to base your class. If there is only a single superclass, include Extends followed by the superclass name, at the start of the class definition.

Class Demo.MyClass Extends Superclass 
{

//...

}

If there are multiple superclasses, specify them as a comma-separated list, enclosed in parentheses.

Class Demo.MyClass Extends (Superclass1, Superclass2, Superclass3) 
{

//...

}

It is not necessary to specify a superclass when you create a class. It is common to use %RegisteredObjectOpens in a new tab as the superclass even if the class does not represent any kind of object, because doing so gives your class access to many commonly used macros, but you can instead directly include the include files that contain them.

Include Files

When you create a class that does not extend %RegisteredObjectOpens in a new tab or any of its subclasses, you might want to include the following include files:

• %occStatus.inc, which defines macros to work with %StatusOpens in a new tab values.

• %occMessages.inc, which defines macros to work with messages.

  For details on the macros defined by these include files, see Using System-supplied Macros in Using ObjectScript.

If your class does extend %RegisteredObjectOpens in a new tab or any of its subclasses, these macros are available automatically.

You can also create your own include files and include them in class definitions as needed.

To include an include file at the beginning of a class definition, use syntax of the following form. Note that you must omit the .inc extension of the include file:

Include MyMacros

For example:

Include %occInclude

Class Classname 
{
}

To include multiple include files at the beginning of a class definition, use syntax of the following form:

Include (MyMacros, YourMacros) 

Note that this syntax does not have a leading pound sign (in contrast to the syntax required in a routine). Also, the Include directive is not case-sensitive, so you could use INCLUDE instead, for example. The include file name is case-sensitive.

See also #include in Using ObjectScript.

Specifying Class Keywords

In some cases, it is necessary to control details of the code generated by the class compiler. For one example, for a persistent class, you can specify an SQL table name, if you do not want to (or cannot) use the default table name. For another example, you can mark a class as final, so that subclasses of it cannot be created. The class definitions support a specific set of keywords for such purposes. If you need to specify class keywords, include them within square brackets after the superclass, as follows:

Class Demo.MyClass Extends Demo.MySuperclass [ Keyword1, Keyword2, ...]
{

//...

}

For example, the available class keywords include Abstract and Final. For an introduction, see Compiler Keywords. InterSystems IRIS also provides specific keywords for each kind of class member.

Introduction to Defining Class Parameters

A class parameter defines a constant value for all objects of a given class. To add a class parameter to a class definition, add an element like one of the following to the class:

Parameter PARAMNAME as Type;

Parameter PARAMNAME as Type = value;

Parameter PARAMNAME as Type [ Keywords ] = value;

Keywords represents any parameter keywords. For an introduction to keywords, see Compiler Keywords. For parameter keywords; see Parameter Keywords in the Class Definition Reference. These are optional.

Introduction to Defining Properties

An object class can include properties.

To add a property to a class definition, add an element like one of the following to the class:

Property PropName as Classname;

Property PropName as Classname [ Keywords ] ;

Property PropName as Classname(PARAM1=value,PARAM2=value) [ Keywords ] ;

Property PropName as Classname(PARAM1=value,PARAM2=value) ;

PropName is the name of the property, and Classname is an optional class name (if you omit this, the property is assumed to be of type %StringOpens in a new tab).

Keywords represents any property keywords. For an introduction to keywords, see Compiler Keywords. For property keywords; see Property Keywords in the Class Definition Reference. These are optional.

Depending on the class used by the property, you might also be able to specify property parameters, as shown in the third and fourth variations.

Notice that the property parameters, if included, are enclosed in parentheses and precede any property keywords. Also notice that the property keywords, if included, are enclosed in square brackets.

Introduction to Defining Methods

You can define two kinds of methods in InterSystems IRIS classes: class methods and instance methods.

To add a class method to a class definition, add an element like the following to the class:

ClassMethod MethodName(arguments) as Classname [ Keywords]
{
//method implementation
}

MethodName is the name of the method and arguments is a comma-separated list of arguments. Classname is an optional class name that represents the type of value (if any) returned by this method. Omit the As Classname part if the method does not return a value.

Keywords represents any method keywords. For an introduction to keywords, see Compiler Keywords. For method keywords, see Method Keywords in the Class Definition Reference. These are optional.

To add an instance method, use the same syntax with Method instead of ClassMethod:

Method MethodName(arguments) as Classname [ Keywords]
{
//method implementation
}

Instance methods are relevant only in object classes.

Rules for Class and Class Member Names

This section describes the rules for class and member names, such as maximum length, allowed characters, and so on. A full class name includes its package name.

Every identifier must be unique within its context (that is, no two classes can have the same name). InterSystems IRIS has the following limits on package, class, and member names:

• Each package name can have up to 189 unique characters.

• Each class name can have up to 60 unique characters.

• Each method and property name can have up to 180 unique characters. See Class Member Names for more details.

• The combined length of the name of a property and of any indices on the property should be no longer than 180 characters.

• The full name of each member (including the unqualified member name, the class name, the package name, and any separators) must be 220 characters or fewer.

• Each name can include Unicode characters.

Identifiers preserve case: you must exactly match the case of a name; at the same time, two classes cannot have names that differ only in case. For example, the identifiers id1 and ID1 are considered identical for purposes of uniqueness.

Identifiers must start with an alphabetic character, though they may contain numeric characters after the first position. Identifiers cannot contain spaces or punctuation characters with the exception of package names which may contain the . character.

Certain identifiers start with the % character; this identifies a system item. For example, many of the methods and packages provided with the InterSystems IRIS library start with the % character.

Member names can be delimited, which allows them to include characters that are otherwise not permitted. To create a delimited member name, use double quotes for the first and last characters of the name. For example:

Property "My Property" As %String;

For more details on system identifiers, see Rules and Guidelines for Identifiers.

Class Names

Every class has a name that uniquely identifies it. A full class name consists of two parts: a package name and a class name: the class name follows the final . character in the name. A class name must be unique within its package; a package name must be unique within an InterSystems IRIS namespace. For details on packages, see Packages.

Because persistent classes are automatically projected as SQL tables, a class definition must specify a table name that is not an SQL reserved word; if the name of a persistent class is an SQL reserved word, then the class definition must also specify a valid, non-reserved word value for its SQLTableName keyword.

Class Member Names

Every class member (such as a property or method) must have a name that is unique within its class and with a maximum length of 180 characters. Further, a member of a persistent cannot use an SQL reserved word as its identifier. It can define an alias, however, using the SQLName or SQLFieldName keyword of that member (as appropriate).

Use of Subclasses

You can use a subclass in any place in which you might use its superclass. For example, using the above defined Employee and Person classes, it is possible to open an Employee object and refer to it as a Person:

 Set x = ##class(MyApp.Person).%OpenId(id)
 Write x.Name

We can also access Employee-specific attributes or methods:

 Write x.Salary // displays the Salary property (only available in Employee instances)

Primary Superclass

The leftmost superclass that a subclass extends is known as its primary superclass. A class inherits all the members of its primary superclass, including applicable class keywords, properties, methods, queries, indices, class parameters, and the parameters and keywords of the inherited properties and inherited methods. Except for items marked as Final, the subclass can override (but not delete) the characteristics of its inherited members.

Multiple Inheritance

By means of multiple inheritance, a class can inherit its behavior and class type from more than one superclass. To establish multiple inheritance, list multiple superclasses within parentheses. The leftmost superclass is the primary superclass.

For example, if class X inherits from classes A, B, and C, its definition includes:

Class X Extends (A, B, C) 
{
}

The default inheritance order for the class compiler is from left to right, which means that differences in member definitions among superclasses are resolved in favor of the leftmost superclass (in this case, A superseding B and C, and B superseding C.)

Specifically, for class X, the values of the class parameter values, properties, and methods are inherited from class A (the first superclass listed), then from class B, and, finally, from class C. X also inherits any class members from B that A has not defined, and any class members from C that neither A nor B has defined. If class B has a class member with the same name as a member already inherited from A, then X uses the value from A; similarly, if C has a member with the same name as one inherited from either A or B, the order of precedence is A, then B, then C.

Because left-to-right inheritance is the default, there is no need to specify this; hence, the previous example class definition is equivalent to the following:

Class X Extends (A, B, C) [ Inheritance = left ]
{
}

To specify right-to-left inheritance among superclasses, use the Inheritance keyword with a value of right:

Class X Extends (A, B, C) [ Inheritance = right ]
{
}

With right-to-left inheritance, if multiple superclasses have members with the same name, the superclass to the right takes precedence.

For example, in the case of class X inheriting from classes A, B, and C with right-to-left inheritance, if there is a conflict between a member inherited from class A and one from class B, the member from class B overrides (replaces) the previously inherited member; likewise for the members of class C in relation to those of classes A and B. The class keywords for class X come exclusively from class A. (This is why extending classes A and B — in that order — with left-to-right inheritance is not the same as extending classes B and A — in that order — with right-to-left inheritance; the keywords are inherited from the leftmost superclass in either definition, which makes the two cases different.)

Additional Topics

Also see %ClassName() and the Most Specific Type Class (MSTC).

Example

The following example shows a class definition with some commonly used keywords:

/// This sample persistent class represents a person.
Class MyApp.Person Extends %Persistent [ SqlTableName = MyAppPerson ]
{

/// Define a unique index for the SSN property.
Index SSNKey On SSN [ Unique ];

/// Name of the person.
Property Name As %String [ Required ];

/// Person's Social Security number.
Property SSN As %String(PATTERN = "3N1""-""2N1""-""4N") [ Required ];

}

This example shows the following keywords:

• For the class definition, the Extends keyword specifies the superclass (or superclasses) from which this class inherits.

  Note that the Extends keyword has a different name when you view the class in other ways; see the next section.

• For the class definition, the SqlTableName keyword determines the name of the associated table, if the default name is not to be used. This keyword is meaningful only for persistent classes, which are described later in this book.

• For the index definition, the Unique keyword causes InterSystems IRIS to enforce uniqueness on the property on which the index is based (SSN in this example).

• For the two properties, the Required keyword causes InterSystems IRIS to require non-null values for the properties.

PATTERN is not a keyword but instead is a property parameter; notice that PATTERN is enclosed in parentheses, rather than square brackets.

Apart from keywords related to storage (which are not generally documented), you can find details on the keywords in the Class Definition Reference. The reference information demonstrates the syntax that applies when you view a class in the usual edit mode.

Introduction to the Class Reference

The purpose of the Class Reference is to advertise, to other programmers, which parts of a class can be used, and how to use them. The following shows an example:

This reference information shows the definitions of class members, but not their actual implementations. For example, it shows method signatures but not their internal definitions. It includes links between elements so that you can rapidly follow the logic of the code. There is also a search option.

Creating Documentation to Include in the Class Reference

To create documentation to include in the Class Reference, create comments within the class definitions — specifically comments that start with ///. If you precede the class declaration with such comments, the comments are shown at the top of the page for the class. If you precede a given class member with such comments, the comments are shown after the generated information for that class member. Once you compile the class, you can view its generated class documentation the next time you open the Class Reference documentation. If you add no Class Reference comments, items that you add to a class or package appear appropriately in the lists of class or package contents, but without any explanatory text.

You can extend any existing Class Reference comments by modifying the class definition. The syntax rules for Class Reference comments are strict:

• All Class Reference comments that describe a class or class member must appear in a consecutive block immediately before the declaration of the item that they describe.

• Each line in the block of comments must start with three slashes: ///

  Tip:

  Note that, by default, the presentation combines the text of all the /// lines and treats the result as single paragraph. You can insert HTML line breaks (<br>). Or you can use HTML formatting (such as <p> and </p>), as discussed in the subsection.

• The three slashes must begin at the first (left-most) position in the line.

• No blank lines are allowed within Class Reference comments.

• No blank lines are allowed between the last line of the Class Reference comments and the declaration for the item that they describe.

• The length of the Class Reference comment (all lines combined) must be less than the string length limit (which is extremely long). See String Length Limit in the Orientation Guide for Server-Side Programming.

Class Reference comments allow plain text, plus any standard HTML element and a small number of specialized elements.

Using HTML Markup in Class Documentation

You can use HTML tags within the comments in a class. In your markup, adhere to as strict an HTML standard as you can, for example XHTML, so that any browser can display the result. Note that the %CSP.DocumaticOpens in a new tab class generates a complete HTML page, and the class documentation is contained within the <body> element on that page. Therefore, do not include the HTML tags <html>, <body>, <head>, or <meta> in your markup; these tags will all be ignored. Also, the class name is displayed as a <h1> heading, so if you use headings, use <h2> and lower headings. Because search engines favor HTML pages that have exactly one <h1>, if you include <h1> within your markup, that heading is converted to <h2>.

In addition to standard HTML, you can use the following tags: <CLASS>, <METHOD>, <PROPERTY>, <PARAMETER>, <QUERY>, and <EXAMPLE>. (As with standard HTML tags, the names of these tags are not case-sensitive.) The most commonly used tags are described here. See the documentation for %CSP.DocumaticOpens in a new tab for details of the others.

<CLASS>

Use to tag class names. If the class exists, the contents are displayed as a link to the class' documentation. For example:

/// This uses the <CLASS>MyApp.MyClass</CLASS> class.

<EXAMPLE>

Use to tag programming examples. This tag affects the appearance of the text. Note that each /// line becomes a separate line in the example (in contrast to the usual case, where the lines are combined into a single paragraph). For example:

/// <EXAMPLE>
/// set o=..%New()
/// set o.MyProperty=42
/// set o.OtherProp="abc"
/// do o.WriteSummary()
/// </EXAMPLE>

<METHOD>

Use to tag method names. If the method exists, the contents are displayed as a link to the method's documentation. For example:

/// This is identical to the <METHOD>Unique</METHOD> method.

<PROPERTY>,

Use to tag property names. If the property exists, the contents are displayed as a link to the property's documentation. For example:

/// This uses the value of the <PROPERTY>State</PROPERTY> property.

Here is a multi-line description using HTML markup:

/// The <METHOD>Factorial</METHOD> method returns the factorial
/// of the value specified by <VAR>x</VAR>.

Invoking the Class Compiler

You can compile classes using an IDE (as documented elsewhere), and you can compile them in the Terminal. In the latter case, using the Compile() method of the %SYSTEM.OBJOpens in a new tab object:

 Do $System.OBJ.Compile("MyApp.MyClass")

Class Compiler Notes

Compilation Order

When you compile a class, the system 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 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:

TESTNAMESPACE>d $system.OBJ.GetDependencies("Sample.Address",.included)
 
TESTNAMESPACE>zw included
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. 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:

See $system.OBJ.ShowQualifiers() for comprehensive list of qualifiers as flags have been superseded
by qualifiers
 
    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 - Show hidden classes.
    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.
    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, l, n, o, q, v
Default flags for this namespace
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

While many options can be specified by means of either flags or qualifiers, InterSystems recommends using qualifiers, as they are the newer mechanism. For more information, see Flags and Qualifiers.

About Deployed Mode

When a class is in deployed mode, its method and trigger definitions have been removed. (Note that if the class is a data type class, its method definitions are retained because they may be needed at runtime by cached queries.)

You cannot export or compile a class that is deployed mode, but you can compile its subclasses (if they are not in deployed mode).

There is no way to reverse or undo deployment of a class. You can, however, replace the class by importing the definition from a file using the Management Portal, if you previously saved it to disk. (This is useful if you accidentally put one of your classes into deployed mode prematurely.)