docs.intersystems.com
Home  /  Application Development: Core Topics  /  Orientation Guide for Server-Side Programming  /  Objects


Orientation Guide for Server-Side Programming
Objects
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This chapter discusses objects in InterSystems IRIS. It discusses the following topics:
The samples shown in this chapter are from the Samples-Data sample (https://github.com/intersystems/Samples-Data). InterSystems recommends that you create a dedicated namespace called SAMPLES (for example) and load samples into that namespace. For the general process, see Downloading Samples for Use with InterSystems IRIS.
Introduction to InterSystems IRIS Object Classes
InterSystems IRIS provides object technology by means of the following object classes: %Library.RegisteredObject, %Library.Persistent, and %Library.SerialObject.
The following figure shows the inheritance relationships among these classes, as well as some of their parameters and methods. The names of classes of the %Library package can be abbreviated, so that (for example) %Persistent is an abbreviation for %Library.Persistent. Here, the items in all capitals are parameters and the items that start with percent signs are methods.
In a typical class-based application, you define classes based on these classes (and on specialized system subclasses). All objects inherit directly or indirectly from one of these classes, and every object is one of the following types:
Note:
Via the classes %DynamicObject and %DynamicArray, InterSystems IRIS also provides the ability to work with objects and arrays that have no schema. These classes are not discussed in this book. For details, see Using JSON.
Basic Features of Object Classes
With the object classes, you can perform the following tasks, among others:
OREFs
The %New() method of an object class creates an internal, in-memory structure to contain the object’s data and returns an OREF (object reference) that points to that structure. An OREF is a special kind of value in ObjectScript. You should remember the following points:
Note:
For persistent classes, described in the next chapter, methods such as %OpenId() also return OREFs.
Stream Interface Classes
As noted earlier, InterSystems IRIS allocates a fixed amount of space to hold the results of string operations. If a string expression exceeds the amount of space allocated, a <MAXSTRING> error results. The limit is 3,641,144 characters.
If you need to pass a value whose length exceeds this limit, or you need a property whose value might exceed this limit, you use a stream. A stream is an object that can contain a single value whose size is larger than the string size limit. (Internally InterSystems IRIS creates and uses a temporary global to avoid the memory limitation.)
You can use stream fields with InterSystems SQL, with some restrictions. For details and a more complete introduction, see Defining and Using Classes; also see the InterSystems Class Reference for these classes.
Stream Classes
The main InterSystems IRIS stream classes use a common stream interface defined by the %Stream.Object class. You typically use streams as properties of other objects, and you save those objects. Stream data may be stored in either an external file or an InterSystems IRIS global, depending on the class you choose:
To work with a stream object, you use its methods. For example, you use the Write() method of these classes to add data to a stream, and you use Read() to read data from it. The stream interface includes other methods such as Rewind() and MoveTo().
Example
For example, the following code creates a global character stream and writes some data into it:
 Set mystream=##class(%Stream.GlobalCharacter).%New()
 Do mystream.Write("here is some text to store in the stream ")
 Do mystream.Write("here is some more text")
 Write "this stream has this many characters: ",mystream.Size,!
 Write "this stream has the following contents: ",!
 Write mystream.Read()
Collection Classes
When you need a container for sets of related values, you can use $LIST format lists and multidimensional arrays, as described earlier in this book.
If you prefer to work with classes, InterSystems IRIS provides list classes and array classes; these are called collections.
List and Array Classes for Use As Standalone Objects
To create list objects, you can use the following classes:
To manipulate a list object, use its methods. For example:
 Set Colors=##class(%Library.ListOfDataTypes).%New()
 Do Colors.Insert("Red")
 Do Colors.Insert("Green")
 Do Colors.Insert("Blue") 
 Write "Number of items in this list: ", Colors.Count()
 Write !, "Second item in the list: ", Colors.GetAt(2)
Similarly, to create array objects, you can use the following classes:
To manipulate an array object, use its methods. For example:
 Set ItemArray=##class(%Library.ArrayOfDataTypes).%New()
 Do ItemArray.SetAt("example item","alpha")
 Do ItemArray.SetAt("another item","beta")
 Do ItemArray.SetAt("yet another item","gamma")
 Do ItemArray.SetAt("still another item","omega")
 Write "Number of items in this array: ", ItemArray.Count()
 Write !, "Item that has the key gamma: ", ItemArray.GetAt("gamma")
List and Arrays as Properties
You can also define a property as a list or array.
To define a property as a list, use the following form:
Property MyProperty As list of Classname;
If Classname is a data type class, then InterSystems IRIS uses the interface provided by %Collection.ListOfDT. If Classname is an object class, then it uses the interface provided by %Collection.ListOfObj.
To define a property as an array, use the following form:
Property MyProperty As Array of Classname;
If Classname is a data type class, then InterSystems IRIS uses the interface provided by %Collection.ArrayOfDT. If Classname is an object class, then it uses the interface provided by %Collection.ArrayOfObj.
Useful ObjectScript Functions
ObjectScript provides the following functions for use with object classes:
For More Information
For more information on the topics covered in this chapter, see the following books: