Using Caché Basic
Using Objects
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
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.