Using InterSystems Development Environments — Atelier and Studio
Class Definition Syntax
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Search:    

This appendix describes the syntax of how to create class definitions in Studio.

This appendix covers how to define each of the following:
Class Definition Example
The following is a complete definition of a sample class demonstrating many of the elements of the class definition language:
/// This sample persistent class represents an employee.
Class MyApp.Employee Extends %Persistent 
{
/// Project this class as a Java class
Projection Java As %Projection.Java;

/// A user-defined class parameter
Parameter APPNAME = "My Application";

/// An index on Name
Index NameIndex On Name;

/// An index on Title and Salary
Index TSIndex On (Title,Salary);

/// The company this employee works for.
Relationship Company As Company [ Cardinality = one, Inverse = Employees ];

/// The employee's name.
Property Name As %String(MAXLEN = "50", POPSPEC = "Name()");

/// A character stream containing notes about this employee.
Property Notes As %CharacterStream;

/// The employee's current salary.
Property Salary As %Integer(MAXVAL = "100000", MINVAL = "0");

/// The employee's job title.
Property Title As %String(MAXLEN = "50", POPSPEC = "Title()");

/// Prints the properties <property>Name</property> and
/// <property>Title</property> to the console.
Method Print()
{
    Write !,"Name: ", ..Name, ?30, "Title: ", ..Title
    Quit
}

/// A class query listing employees by name.
Query ByName() As %SQLQuery(CONTAINID = "1")
{
    SELECT ID,Name
    FROM Employee
    ORDER BY Name
}

}
The storage definition is displayed as an XML island (a block of XML) in the class definition. (A storage definition specifies the physical structure used to store a class in a database.)
General Structure
A class definition in Studio is a text representation of a class definition in the Caché database.
A class definition consists of a class statement, declaring the name of the class and its characteristics, and one or more statements that define members of the class.
For example, here is the definition of a simple, persistent class containing two properties:
Class MyApp.Person Extends %Persistent 
{
Property Name As %String;
Property Home As Address;
}
Generation and Format
A Studio class definition is only one of many possible representations of a class definition. The class definition language is used only within Caché Studio; the exact text of a class definition is not saved in the database. Whenever you open an existing class definition, Studio regenerates the class definition text display from the underlying class definition in the database. When it regenerates text, Studio may rearrange the display of some of the class metadata.
White Space
Extraneous white space characters (tabs and spaces) are ignored (and may be removed by Studio) in class definition statements. White space characters in the body of method, query, trigger definitions, and quoted keyword values are retained.
Case
When a class definition is regenerated, the class definition language might change the case of certain class metadata to a customary case (such as lowercase to uppercase). Certain keywords, the names of members, and any implementation code which are sensitive to case are not changed by Studio.
Statements
A class definition statement defines the characteristics of a class or a member of a class. Each statement consists of the following parts:
These are described below.
For example, the following statement defines a method:
/// This method returns 1 if successful.
Method Test() [ Private ]
{
    Write 1
}
In this case, the description consists of “This method returns 1 if successful.”; the declaration consists of Method Test(); the keyword list contains Private and the body contains Write 1.
Description
A description is a special type of comment that precedes a class or class member and specifies the value of the Description keyword for the class or class member.
A description is indicated using three slashes, (///). Text between /// and the end of the line is included in the description.
For example, here is a property with a description:
/// This property represents a Name
Property Name As %String;
If a class definition is closed and reopened, descriptions separated by white space are concatenated, thus:
/// This is line one

/// This is line two
Method x()
{
}
becomes:
/// This is line one
/// This is line two
Method x()
{
}
and is placed immediately before the element to which they relate when the class definition is regenerated.
A description must be placed outside of any statement. A description at the very end of a document (with no member definition following it) is not associated with any member definition and is lost when the document is saved or regenerated.
Using HTML in Descriptions
Caché uses descriptions to create documentation for the class in its online class reference (samples:%XML.Adaptor, %UnitTest.TestCase). You can use HTML tags to format the description. In addition to standard HTML, the online reference recognizes the following tags: CLASS, METHOD, PROPERTY, PARAMETER, QUERY, and EXAMPLE. CLASS, METHOD, and PROPERTY are described here. See the documentation for %CSP:Documatic for details of the others.
CLASS
Use to tag class names. If the class exists, the contents are displayed as a hyperlink to the class' documentation. For example:
/// This uses the <CLASS>Person</CLASS> class.
Method x()
{
}
METHOD
Use to tag method names. If the method exists, the contents are displayed as a hyperlink to the method's documentation. For example:
/// This is identical to the <METHOD>Unique</METHOD> method.
Method x()
{
}
PROPERTY
Use to tag property names. If the property exists, the contents are displayed as a hyperlink to the property's documentation. For example:
/// This uses the value of the <PROPERTY>State</PROPERTY> property.
Method x()
{
}
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>.
ClassMethod Factorial(x As %Integer) As %Integer
{
    If (x > 1) {
        Quit x * (..Factorial(x - 1))
    }
    Else {
        Quit x
    }
}
Statement Declaration
A statement's declaration states the kind of class or class member the statement is defining. Every declaration starts with one of the following words. These words are not case-sensitive but the Studio Editor changes any variations in case back to that displayed above, initial capital.
The class or class member type is followed by an identifier that specifies the name of the class or class member, such as Class Manager. Depending on the statement type there can be additional specifications, such as the data type of a property or the value of a parameter.
Statement Keyword List
An optional keyword list immediately follows the statement declaration. It consists of a list of keywords, which can have values, contained in matching square brackets ([ ]), separated by commas. A keyword is assigned a value using the equals (=) character:
Property X As %Integer [ Final, Required, SqlFieldName = _x ];
If a keyword has a boolean value (true or false), the presence of the keyword indicates a true value; you do not have to specify a value using =. A false value is indicated by placing the word Not immediately before the keyword:
Property X As %Integer [ Final, Not Required ];
If a keyword value is an identifier (such as a property name), you can place the identifier directly after the = (white space is ignored). If the value is not an identifier, you must enclose it in quotation marks:
Property Colors As %String [ SqlListDelimiter = "," ];
If a keyword value consists of a list of values, enclose the entire list in matching parentheses, ( ), and delimit list items with commas (,).
Method Z() [ Final, PlaceAfter = (X, Y), Private ]
{
}
Statement Body
The statement body is defines larger blocks of multiline content, such as a method implementation, and is enclosed in matching braces { }:
Method FullName() As %String
{
    Quit ..FirstName _ "," _ ..LastName
}
If a statement has no body, terminate the statement with a ; (semi-colon):
Property Name As %String;
Comments
The class definition language supports both // and /* style comments. Any text between /* and */ is ignored. Any text between // and the end of the line is ignored.
Note that commented-out sections of class definitions are stored in the database when a class definition is saved.
Here are some examples of comments in a class definition:
/* I am not sure if anyone uses these properties!
Property Name As %String;
Property Title As %String;
*/

Property SSN As %String;   // I left this one alone
Comments Used in the Intersystems Class Reference
There is a special use of the // comment that is used to create documentation in the Intersystems Class Reference for each class that you create; that is, a comment that begins with three slashes, ///, which occurs just before a statement declaration. The content of the comment are put into the Description property of the class and can be edited in the Inspector.
///Adds two integers
ClassMethod Add(
        arg1 As %Integer,
        arg2 As %Integer) As %Integer
{
        quit arg1 + arg2
}
Select View > Show Class Documentation to see the documentation for this class. Example:
Comments that begin with /// that are within the body of a class member definition are not put into the Intersystems Class Reference.
Note:
The description line for a class declaration cannot begin with either a single or a double slash. If you do either of these, the class declaration is marked as an error from the start of the description line to the last bracket of the class declaration; in other words, the entire file is marked as in error, underlined with red wavy lines, with red arrows in the left column.
The description line for a class member declaration cannot begin with a single slash. If you do this, the class member declaration is marked as an error from the start of the description line to the last bracket of the class declaration; in other words, the declaration is marked as in error, underlined with red wavy lines, with red arrows in the left column.
Statements
The following sections describe class definition statements in more detail.
Class Statement
A Class statement defines a class and specifies class-wide keyword values. Only one class declaration is allowed in a Studio class definition.
Extends Clause
A Class statement can include an optional Extends clause that specifies the superclasses used by the class. This is equivalent to setting the value of the class' Super keyword.
Class Cow Extends Mammal
{
}
If a class has multiple superclasses, place their names in () (parentheses) and separate them with , (comma):
Class Platypus Extends (Mammal, Reptile)
{
}
Keyword List
A Class statement can include an optional keyword list:
Class Dodo Extends Bird [ Abstract, Final ]
{
}
The following table displays the keywords that can appear in the optional keyword list. Do not provide a value for keywords marked as Boolean:
Class Keywords
Keyword Possible Values and Purpose
Abstract Boolean. Specifies that you cannot create instances of an Abstract class.
ClassType DataType | Persistent | Serial | Stream | View
ClientDataType Object Data type. Bigint | Binarystream | Boolean | Characterstream | Currentcy | Date | Decimal | Double | Fdate | Ftimestamp | Handle | Integer | List | Longvarchar | Numeric | Status | Time | Timestamp | Varchar
ClientName String. Lets you define an alternate name for a class when it is projected to a client language.
CompileAfter Class name. Compile this class after the specified classes.
DdlAllowed Boolean. Specifies that DDL statements are allowed to alter this class.
DependsOn List of classes. Specifies other classes that must be compiled and runnable before this class can be compiled
Final Boolean. Specifies that this class cannot have subclasses.
Hidden Boolean. Specifies that this class is not displayed in the Intersystems Class Reference.
Import One or more package names, set in the Class Inspector. Specifies classes that you want to import from.
IncludeCode One or more include file names, set in the Class Inspector. Specifies files that are included during compilation.
IncludeGenerator One or more include file names, set in the Class Inspector. Specifies files that are included during compilation of this class' generator methods.
Language CACHE | BASIC. Specifies language used to implement methods for this class; can be overridden within an individual method.
OdbcType ODBC Data type. Bigint | Bit | Date | Double | Integer | Longvarbinary | Longvarchar | Numeric | Resultset | Smallint | Struct | Time | Timestamp | Tinyint | Varbinary | Varchar
Owner Username. Specifies owner of a persistent class.
ProcedureBlock Boolean. Specifies that each ObjectScript method in this class is a procedure block.
ServerOnly 0 | 1 | empty. Specifies that a class will not be projected to a Java or C++ client.
SoapBindingStyle Document | rpc. Specifies the binding style (document or rpc) or SOAP invocation mechanism used by Web methods defined in this class.
SoapBodyUse Encoded | literal. Specifies the encoding (encoded or literal) used by the inputs and outputs of Web methods defined in this class.
SqlCategory SQL Category Name. Date | Double | Integer | Name | Numeric | String | Time | Timestamp
SqlRowIdName SQL Identifier. Field name for ID column.
SqlRowIdPrivate Boolean. Specifies that ID column is projected as a hidden field.
SqlTableName SQL Identifier. Table name used to identify the class in its SQL projection.
StorageStrategy Name of Storage Definition; used to define the storage structure used by a persistent class.
ViewQuery SQL statement. SQL Query for a view definition class.
Class Statement Body
The body of a Class statement consists of zero or more statements defining members of the class:
Class Cow Extends Mammal
{
Property Food As Cud;

Method Eat(amount As Cud)
{
    Set ..Food = ..Food + amount
}
}
Parameter Statement
The Parameter statement defines (or overrides) a class parameter.
A default value for the parameter can be specified using an = clause:
Parameter AUTHOR = "ELVIS";
The Parameter statement has no body.
Parameter Keyword List
A Parameter statement can include an optional keyword list:
Parameter ANSWER [ Final ] = "African Swallow";
The following table displays the keywords that can appear in the optional keyword list. You do not provide a value for keywords marked as Boolean:
Parameter Keywords
Keyword Possible Values
Abstract Boolean. Specifies that this is an abstract parameter.
Constraint String. Specifies a user interface constraint for the parameter.
Final Boolean. If present, specifies that subclasses cannot override the definition of this parameter.
Flag Enum | List | Edit | Empty | Sys. Modifies the user interface type (in Studio) for this parameter. This is useful for classes that you intend to subclass.
Internal Boolean. Specifies that this parameter should not be displayed in the class documentation.
Property Statement
The Property statement defines (or overrides) a property for a class. The property type is specified with an As clause and a class name:
Property Boardwalk As %String;
To define a collection property (which can be a list or an array) use the following syntax:
Property Aliases As List Of %String;
If you want to define a relationship property, use the Relationship statement.
Property Parameters
A Property statement can define values for one or more property parameters. The list of available parameters depends on the type of property.
A parameter list is a comma-separated list of parameter names and values, enclosed in () (parentheses). All parameter values are treated as strings and must be enclosed in matching quotation marks (""):
Property SALARY As %Integer(MINVAL = "0", MAXVAL = "1000000");
Property Keyword List
A Property statement can include an optional keyword list:
Property SecretName As %String(MAXLEN = "20") [ Private, Required ];
The following table displays the keywords that can appear in the optional keyword list. Do not provide a value for keywords marked as Boolean:
Property Keywords
Keyword Possible Values
Calculated Boolean. If present, specifies that the property has no in-memory storage allocated for it when the object containing it is instantiated.
ClientName String. Lets you define an alternate name for a property when it is projected to a client language.
Final Boolean. If present, specifies that subclasses cannot override the definition of this property..
Identity Boolean. For a persistent object, specifies that a property corresponds to an identity column in the corresponding SQL table.
InitialExpression Value expression. Specifies an initial value for the property, which can either be a constant or a Caché ObjectScript expression
Internal Boolean. Specifies that this property should not be displayed in the class documentation.
Inverse Property name. Specifies the inverse side of a relationship.
Multidimensional Boolean. If present, specifies that a property has the characteristics of a multidimensional array.
Private Boolean. If present, specifies that the property can only be used by instance methods of this class (or its subclasses).
ReadOnly Boolean. For a persistent object, specifies that a property is read-only, which limits the number of ways its value can be set.
Required Boolean. If present, In a persistent class, specifies that the property's value must be given a value before it can be stored to disk.
SqlCollation Deprecated. Use the COLLATION data type parameter to override the collation for a property.
SqlColumnNumber Integer. Sets the SQL Column Number for this property. Provided for legacy application support.
SqlComputeCode Caché ObjectScript code that evaluates to a computed field value.
SqlComputed Boolean. Specifies that this is a computed field.
SqlComputeOnChange Property name. Specifies fields upon which this field calculation depends.
SqlFieldName SQL Identifier. In a persistent class, in an SQL projection, specifies the column name that identifies this property. By default, the SQL column name is the same as the property name.
SqlListDelimiter Delimiter. Specifies the delimiter character used within SQL for lists.
SqlListType List | Delimited | Subnode. SqlListType controls how the values of a field are represented in memory in SQL, and how they stored on disk.
Transient Boolean. If present in a persistent class, specifies that the property is not stored in the database.
Relationship Statement
The Relationship statement defines a relationship property for a class. It is similar to the Property statement. The type (a class name) for the relationship is required and specified using an As clause. The other required relationship attributes, Cardinality and Inverse, are specified in the keyword list:
Relationship Chapter As Chapter [Inverse = Book, Cardinality = Many];
You can use any of property keywords in a Relationship keyword list. You can also specify property parameters as you would with a Property statement.
Relationship Keyword List
A Relationship statement must include a keyword list that contains Cardinality and Inverse. It can include any other keywords allowed in a Property statement keyword list:
Relationship Doctor As Doctor [Inverse = Patients, Cardinality = One, Required];
The following table displays the required keywords. See the Property Keyword List for the other allowed keywords. :
Relationship Keywords
Keyword Possible Values
Cardinality One | Children | Many | Parent
Inverse Property Name
Index Statement
The Index statement defines an index for a persistent class. Its declaration contains the name of the index followed by an On clause containing a list of one or more properties contained in the index. An Index statement has no body:
Index SalaryIndex On Salary;
If an index is on multiple properties, place the properties in a list using ( ), parentheses. The order of the property names in the list determines the order in which the properties are used (as subscripts) in the index.
Index NameIndex On (LastName,FirstName);
Index Keyword List
A Index statement can include a keyword list:
Index SSNIndex On SSN [ Unique ];
The following table displays the optional keywords. Do not provide a value for keywords marked as Boolean:
Index Keywords
Keyword Possible Values
Data List of property names
IdKey Boolean
PrimaryKey Boolean
SqlName SQL Identifier
Type Bitmap | Bitslice | Index | Key
Unique Boolean
Method and ClassMethod Statements
The Method statement defines (or overrides) an instance method for a class. The ClassMethod statement defines a class method; that is, a method that can be executed with no instances of the class in existence. In every other respect, these statements are identical.
Here is an example of an instance method:
/// Print this object instance to the console
Method Print() [ Final ]
{
    Write "Name: ", ..Name, !
}
Here is an example of a class method:
/// Print any object instance to the console given its id
ClassMethod PrintObject(id As %String) [ Final ]
{
    Set obj = ..%OpenId(id)

    If (obj '= "") {
        Write "Name: ", obj.Name, !
        Set obj = ""
    }
}
Method Arguments
The Method declaration includes its formal specification (FormalSpec); that is, a list of its formal arguments, if any. This list consists of one or more comma-separated argument names, their types (a Caché class name), and, optionally, their default values. The ByRef modifier indicates an argument that is called by reference. You can also specify an argument whose value is returned by reference but has no incoming value by using the Output modifier.
Below is a method defined to take three arguments. The first is a string, the second is called by reference, and the third is an integer with a default value of 0:
Method Test(a1 As %String, ByRef a2 As %String, a3 As %Integer = 0)
{
}
As Clause
A Method statement can include an As clause that specifies the method's return type; this is equivalent to setting the value of the method's ReturnType keyword:
Method IsOK() As %Boolean
{
    Quit 1
}
The return type is the name of another Caché class. If the As clause is omitted then the method is defined as returning no value:
Method Hello()
{
    Write "Hello"
}
Method Keyword List
A Method statement can include a keyword list:
Method Hello() [ Final, Private ]
{
    Write "Hello"
}
The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked as Boolean:
Method Keywords
Keyword Possible Values
Abstract Boolean. Specifies that this is an abstract method.
ClientName String
CodeMode call | code | expression | objectgenerator
ExternalProcName String
Final Boolean. If present, specifies that the method is final and cannot be overridden in a subclass.
GenerateAfter List of method names
Internal Boolean
Language CACHE | BASIC | JAVA | JAVASCRIPT | MVBASIC | TSQL
PlaceAfter List of method names
Private Boolean
ProcedureBlock Boolean
PublicList List of one or more variable names
ReturnResultsets Boolean
ServerOnly 0 | 1 | empty
SoapAction String. Unique URI that identifies the intent of the SOAP request | empty
SoapBindingStyle document | rpc
SoapBodyUse encoded | literal
SoapMessageName Any identifier that is valid in XML
SoapNameSpace Namespace URI
SoapTypeNameSpace Namespace URI
SqlName SQL Identifier
SqlProc Boolean
WebMethod Boolean
ZenMethod Boolean
Method Statement Body
The body of a Method statement contains the implementation code for the method (this is the value of the method's Implementation keyword). You must be careful to match all { } (braces) characters contained in the implementation code.
A Method statement can contain code in different programming languages (currently supported: Caché ObjectScript, BASIC, Java, JavaScript, MVBASIC, TSQL). A method uses the language specified by its class' Language keyword. A method definition can override the specified class language by using the method's Language keyword.
By default a method is assumed to use Caché ObjectScript (which is also the default for classes):
Method Hello()
{
    Write "Hello"
}
To change the method to Basic, specify the Language keyword:
Method Hello() [ Language = Basic ]
{
    Print "Hello"
}
Note that this Basic method does not work unless it is running on a version of Caché that supports Basic.
SQL Query Statement
The Query statement defines an SQL query for a class:
Query ByName(name As %String) As %SQLQuery(CONTAINID = "1")
{
    SELECT ID,Name
    FROM Employee
    WHERE Name %STARTSWITH :name
    ORDER BY Name
}
The declaration of a Query contains the name of the query and its argument list. The argument list is specified in the same manner as the Method statement.
A Query contains an As clause that specifies the name of the class used to provided the query interface methods. The class name in the As clause can contain parameter values in the same manner as the Property statement.
The body of a Query statement is assumed to be SQL text used to define the query. A user-defined query (of type %Query) does not require a body, but it does require you to specify its ROWSPEC parameter:
Query Custom() As %Query(ROWSPEC = "Name,Title")
{
}
SQL Query Keyword List
A Query can include a keyword list:
Query Roster() As %SQLQuery() [ Private ]
{
    SELECT Name
    FROM ClubMember
}
The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked as Boolean:
SQL Query Keywords
Keyword Possible Values
ClientName String
Final Boolean. If present, specifies that subclasses cannot override the definition of the query.
Internal Boolean
Private Boolean
SoapBindingStyle document | rpc
SoapNameSpace Namespace URI
SqlName SQL Identifier
SqlProc Boolean
SqlView SQL Identifier
SqlViewName SQL Identifier
WebMethod Boolean
Projection Statement
The Projection statement defines (or overrides) a class projection. The type (a class name) for the property is specified using an As clause:
Projection JavaClient As %Projection.Java;
Projection Parameters
A Projection statement can define values for one or more projection parameters. The list of available parameters depends on the type (class) of the projection.
A parameter list is a comma-separated list of parameter names and their corresponding values. All parameter values are treated as strings and must be enclosed in matching quotation marks (""):
Projection JavaClient As %Projection.Java(ROOTDIR = "<cachesys>\dev\tutorials\java");
SQL Trigger Statement
The Trigger statement defines an SQL Trigger for a persistent class. Its declaration contains the name of the trigger.
The body of a Trigger contains the code.
Trigger OnInsert [ Event = INSERT ]
{
    // trigger code
}
SQL Trigger Keyword List
A Trigger statement can include an optional keyword list:
Trigger OnDelete [ Event = DELETE, TIME = AFTER ]
{
    // trigger code
}
The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked as Boolean:
SQL Trigger Keywords
Keyword Possible Values
Event DELETE | INSERT | UPDATE | INSERT/UPDATE | INSERT/DELETE | UPDATE/DELETE | INSERT/UPDATE/DELETE
Final Boolean. If present, specifies that subclasses cannot override the definition of the SQL trigger.
Foreach row | statement
Internal Boolean
Language cache | tsql
NewTable String
OldTable String
Order Integer
SqlName SQL Identifier
Time AFTER | BEFORE
UpdateColumnList Null or a comma-delimited list of one or more column names. TSQL only.
SQL ForeignKey Statement
The ForeignKey statement defines an SQL Foreign Key for a persistent class:
ForeignKey FKey1(StateName) References StateTable(StateKey);
The declaration consists of the word ForeignKey followed by the name of the foreign key and a list of properties constrained by the foreign key in matching ( ) characters.
The required References clause specifies the name of the class the foreign key references as well as the name of a key (unique index) in the referenced class.
The ForeignKey statement has no body.
SQL ForeignKey Keyword List
A ForeignKey statement can include an optional keyword list:
ForeignKey FKey1(StateName) References StateTable(StateKey) [SqlName = _fkey1];
The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked as Boolean:
SQL ForeignKey Keywords
Keyword Possible Values
Internal Boolean
OnDelete cascade | noaction | setdefault | setnull | empty
OnUpdate cascade | noaction | setdefault | setnull | empty
SqlName SQL Identifier