Using Objects

Caché includes a full-featured, next-generation object database specifically designed to meet the needs of complex, transaction oriented applications.

The Caché Object Model includes the following features:

Classes — You can define classes that represent the state (data) and behavior (code) of your application components. Classes are used to create instances of objects as both runtime components and as items stored within the database.
Properties — Classes can include properties, which specify the data associated with each object instance. Properties can be simple literals (such as strings or integers), user-defined types (defined using data type classes), complex (or embedded) objects, collections, or references to other objects.
Relationships — Classes can define how instances of objects are related to one another. The system automatically provides navigational methods for relationships as well as referential integrity within the database.
Methods — Classes can define behavior by means of methods: executable code associated with an object. Object methods run within a Caché server process (though they can be invoked from a remote client). Object methods can be scripted using ObjectScript, SQL, or they can be generated using method generators, which are code that automatically creates customized methods according to user-defined rules.
Inheritance — By deriving new classes from existing ones, you can reuse previously written code as well as create specialized versions of classes.
Polymorphism — Caché supports complete object polymorphism. This means that applications can use a well-defined interface (a set of methods and properties provided by a superclass) and the system will automatically invoke the correct interface implementation based on the type of each object. This makes it much easier to develop flexible database applications.
Swizzling (also known as “lazy loading”) — Caché automatically swizzles (brings into memory from disk) any related persistent objects when they are referenced from other objects. This greatly simplifies working with complex data models.

For detailed information on how to use Objects in Caché, refer to Using Caché Objects.

Defining Classes

An object is an instance of a specific class. Within Caché you can define classes in several ways. For information on how to define classes refer to the following sections in Using Caché Objects:

Creating Object Instances

You can create an object instance by either creating a new instance using the New command or you can open a persistent object previously stored in the database using the OpenId command.

The New Command

The New command creates and returns a new instance of the specified class. For example:

person = New Sample.Person()
person.Name = "El Vez"
PrintLn person.Name

The name of the class (with an optional package name) follows the New command. There are parentheses following the class name. If you place an argument within these parentheses, then it will be passed to the constructor (%OnNew method) for the object.

The New command has exactly the same behavior as invoking the %New method in ObjectScript.

The OpenId Command

The OpenId command finds, opens, and returns an instance of a persistent class that is stored within the database using its unique object identifier value. For example:

person = OpenId Sample.Person(22)
PrintLn "Name: " & person.Name
PrintLn "Age: " & person.Age

The name of the class (with an optional package name) follows the OpenId command. There are parentheses following the class name within which contain arguments for the OpenId command. The OpenId command takes the following arguments:

id	Required. The object identifier value used to find the object.
concurrency	Optional. The concurrency setting used to open the object. Refer to Concurrency Settings for possible values.
error	Optional. A status code, passed by reference, that contains error information if the operation failed.

If the OpenId command cannot open the object, it will return a non-object (null string) value.

The OpenId command is polymorphic. If there are multiple types of objects within an extent (subclasses of the same persistent object stored together), then the OpenId command will return an instance of the object that corresponds to the given ID value.

The OpenId command has exactly the same behavior as invoking the %OpenId method in ObjectScript. For compatibility, there is also an Open with the same behavior as the %Open method in ObjectScript.

Object Life Cycle

An object instance is automatically destroyed when there are no longer an variables or object properties referring to it.

For example, in the following code, setting obj to an empty string ("") closes the object as there are no other references to it:

person = New Sample.Person()
person = ""

Properties, Methods, and Other Members

You can use the properties and methods of an object using dot syntax:

objref.Property
objref.Property = value
objref.Method()

If the value preceding the dot operator is not a valid object instance, then a runtime error will occur.

Using Properties

To get or set the value of a property, use the dot operator with a variable that refers to an object:

person = OpenId Sample.Person(22)
PrintLn person.Name
person.Name = "El Vez"
person = "" ' don't save changes...

You can follow object references using cascading dot syntax:

person = OpenId Sample.Person(22)
PrintLn person.Home.City
PrintLn person.Home.State

From within an instance method, you use the special variable, Me, to access other properties of the same object:

Method PrintOut() [language = basic]
{
     PrintLn Me.Name
}

Calling Instance Methods

To invoke an instance method, simply use the dot operator with a variable that refers to an object:

person = New Sample.Person()
PrintLn person.NinetyNine()

From within an instance method, you use the special variable, Me, to invoke other instance methods of the same object:

Method Test() [language = basic]
{
     Me.Test2()
}

Calling Class Methods

To call a class method (a method that can be invoked without having an object instance) use the following syntax:

"MyApp.MyClass".MyMethod(22)

The name of the class (and optional package name) is placed within "" and followed by the dot operator and the method.

When calling a method, arguments are optional; the parentheses are required. If you specify arguments they must match in number and in sequence the arguments in the class method definition.

To omit an argument value, you must specify an undefined variable. This is a significant difference between ObjectScript and Caché Basic. In ObjectScript a method with an omitted argument can be specified using a placeholder comma, as shown in the following example:

  ; ObjectScript example 
  SET tStatement = ##class(%SQL.Statement).%New(,"Sample")
  WRITE !,"Success"

In Caché Basic, you cannot use a placeholder comma; you must supply an undefined variable, as shown in the following example:

  ' Cache Basic example
  ERASE dummy
  tStatement = New %SQL.Statement(dummy,"Sample")
  PrintLn "Success"

In both languages, you do not have to specify trailing arguments. An undefined or omitted argument take the default value for that argument.

The With Statement

The With statement allows you to perform a series of statements on a specified object instance without requalifying the name of the object variable. For example:

person = OpenId Sample.Person(22)
With person
    PrintLn .Name
    PrintLn .SSN
    PrintLn .Home.City
End With

Me.%GetParameter("Parameter") Syntax

The obj.%GetParameter syntax allows for references to class parameters from within the methods of a class. For example, if a class definition include the following parameter and method:

Parameter MyParam = 22;

and the following method:

ClassMethod WriteMyParam() [ Language = basic ]
{
 Print Me.%GetParameter("MyParam")
}

Then the WriteMyParam method invokes the Print command with the value of the MyParam parameter as its argument.