Using Caché Objects - InterSystems Documentation

Using Caché Objects
Version 5.2
01 September 2006
InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Using Caché Objects
Caché Version 5.2 01 September 2006
Copyright © 2006 InterSystems Corporation.
All rights reserved.
This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from
the following sources: Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at
www.w3c.org. The primary document development tools were special-purpose XML-processing applications built
by InterSystems using Caché and Java.
The Caché product and its logos are registered trademarks of InterSystems Corporation.
The Ensemble product and its logos are registered trademarks of InterSystems Corporation.
The InterSystems name and logo are trademarks of InterSystems Corporation.
This document contains trade secret and confidential information which is the property of InterSystems Corporation,
One Memorial Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation
and maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any other
purpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system or
translated into any human or computer language, in any form, by any means, in whole or in part, without the express
prior written consent of InterSystems Corporation.
The copying, use and disposition of this document and the software programs described herein is prohibited except
to the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation covering
such programs and related documentation. InterSystems Corporation makes no representations and warranties
concerning such software programs other than those set forth in such standard software license agreement(s). In
addition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use of
such software programs is limited in the manner set forth in such standard software license agreement(s).
THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY
INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER
SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE
LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE
UPON REQUEST.
InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the
right, in its sole discretion and without notice, to make substitutions and modifications in the products and practices
described in this document.
Caché, InterSystems Caché, Caché SQL, Caché ObjectScript, Caché Object, Ensemble, InterSystems Ensemble,
Ensemble Object, and Ensemble Production are trademarks of InterSystems Corporation. All other brand or product
names used herein are trademarks or registered trademarks of their respective companies or organizations.
For Support questions about any InterSystems products, contact:
InterSystems Worldwide Customer Support
Tel: +1 617 621-0700
Fax: +1 617 374-9391
Email: support@InterSystems.com

Table of Contents
1 Introduction to Caché Objects ....................................................................................... 1
1.1 Caché Objects Architecture ...................................................................................... 2
1.2 Class Definitions and the Class Dictionary ............................................................. 3
1.2.1 Creating Class Definitions .............................................................................. 3
1.2.2 The Class Dictionary ...................................................................................... 3
1.3 The Caché Class Library .......................................................................................... 4
1.4 Development Tools .................................................................................................. 5
1.4.1 Caché Studio ................................................................................................... 5
1.4.2 Caché RoseLink ............................................................................................. 6
1.4.3 SQL-based Development ................................................................................ 6
1.4.4 XML-based Development .............................................................................. 6
1.5 Client Interoperability .............................................................................................. 6
1.5.1 Java ................................................................................................................. 6
1.5.2 ActiveX / COM / .net ...................................................................................... 7
1.5.3 Caché Server Pages ........................................................................................ 7
1.5.4 C++ ................................................................................................................. 7
1.5.5 XML ............................................................................................................... 8
1.5.6 The Caché SQL Gateway ............................................................................... 8
1.5.7 The Caché Activate ActiveX Gateway ............................................................ 8
2 Object-Oriented Database Development ....................................................................... 9
2.1 Classes and Objects .................................................................................................. 9
2.2 Abstraction and Modeling ...................................................................................... 10
2.3 Inheritance and Polymorphism .............................................................................. 10
2.4 Encapsulation ......................................................................................................... 11
2.5 Extensibility ........................................................................................................... 12
2.6 Object Persistence .................................................................................................. 12
2.7 Object Binding ....................................................................................................... 12
3 The Caché Object Model .............................................................................................. 13
3.1 Referring to an Object — OREF, OID, and ID ...................................................... 14
3.1.1 OID and ID Values ....................................................................................... 15
3.1.2 OREFs and Reference Counting .................................................................. 15
3.2 Types of Classes ..................................................................................................... 16
3.2.1 Transient Object Classes .............................................................................. 17
Using Caché Objects
iii

3.2.2 Persistent Object Classes .............................................................................. 17
3.2.3 Serial Object Classes .................................................................................... 18
3.2.4 Data Type Classes ......................................................................................... 20
3.3 Inheritance .............................................................................................................. 20
3.3.1 Multiple Inheritance ..................................................................................... 22
3.4 Class Compilation .................................................................................................. 22
4 Caché Classes ................................................................................................................. 25
4.1 Naming Conventions .............................................................................................. 26
4.1.1 General Identifier Rules ............................................................................... 26
4.1.2 Class Names ................................................................................................. 27
4.1.3 Class Member Names ................................................................................... 27
4.2 Class Keywords ...................................................................................................... 27
4.3 Class Parameters .................................................................................................... 28
5 Packages ......................................................................................................................... 31
5.1 Overview of Packages ............................................................................................ 31
5.2 Package Names ...................................................................................................... 32
5.3 Defining Packages .................................................................................................. 33
5.4 Using Packages ...................................................................................................... 33
5.4.1 The IMPORT Directive ................................................................................ 34
5.5 Packages and SQL ................................................................................................. 35
5.6 Built-in Packages ................................................................................................... 35
6 Methods .......................................................................................................................... 37
6.1 Method Arguments ................................................................................................. 37
6.1.1 Specifying Default Values ............................................................................ 38
6.1.2 Calling By Reference ................................................................................... 38
6.2 Method Return Values ............................................................................................ 39
6.3 Method Visibility ................................................................................................... 39
6.4 Method Language .................................................................................................. 40
6.5 Method Keywords .................................................................................................. 40
6.6 Instance and Class Methods ................................................................................... 42
6.7 Kinds of Methods ................................................................................................... 42
6.7.1 Code Methods ............................................................................................... 43
6.7.2 Expression Methods ..................................................................................... 43
6.7.3 Call Methods ................................................................................................ 44
6.7.4 Method Generators ....................................................................................... 44
iv
Using Caché Objects

7 Properties ....................................................................................................................... 45
7.1 Property Keywords ................................................................................................. 46
7.2 Property Visibility .................................................................................................. 47
7.3 Property Behavior .................................................................................................. 47
7.4 Property Accessors ................................................................................................. 49
7.5 Attribute Properties ................................................................................................ 50
7.5.1 Data Type Properties .................................................................................... 50
7.5.2 Object-Valued Properties .............................................................................. 51
7.5.3 Collection Properties .................................................................................... 51
7.5.4 Stream Properties ......................................................................................... 52
7.5.5 Multidimensional Properties ........................................................................ 52
8 Class Queries .................................................................................................................. 55
8.1 Query Basics .......................................................................................................... 56
8.1.1 The Structure of a Class Query .................................................................... 56
8.1.2 Query Keywords ........................................................................................... 56
8.1.3 Creating a Class Query Specification ........................................................... 57
8.2 User-Written Class Queries ................................................................................... 58
8.2.1 The querynameExecute Method ................................................................... 59
8.2.2 The querynameFetch Method ....................................................................... 60
8.2.3 The querynameClose Method ....................................................................... 62
9 Indices ............................................................................................................................. 63
9.1 Index Keywords ..................................................................................................... 63
9.2 Index Collation ....................................................................................................... 65
10 Using Objects with Caché ObjectScript .................................................................... 67
10.1 Executing Methods .............................................................................................. 67
10.1.1 About Return Values ................................................................................... 68
10.1.2 Executing Instance Methods ....................................................................... 68
10.1.3 Executing Class Methods ........................................................................... 69
10.1.4 Executing Methods Using In-Memory Instances ....................................... 69
10.1.5 Error Conditions ......................................................................................... 70
10.2 Creating New Objects .......................................................................................... 70
10.3 Opening Objects ................................................................................................... 71
10.4 Modifying Objects ............................................................................................... 71
10.4.1 Modifying Reference Properties ................................................................ 72
10.4.2 Modifying Embedded Object Properties .................................................... 73
10.4.3 Modifying List Properties .......................................................................... 75
Using Caché Objects
v

10.4.4 Modfiying Array Properties ........................................................................ 78
10.4.5 Modifying Stream Properties ..................................................................... 80
10.5 Saving Objects ..................................................................................................... 81
10.6 Deleting Objects ................................................................................................... 81
10.6.1 Deleting a Single Object ............................................................................. 82
10.6.2 Deleting All Objects in an Extent ............................................................... 82
10.7 Executing Queries ................................................................................................ 83
10.7.1 Query Metadata Methods ........................................................................... 83
10.7.2 Preparing Queries for Execution ................................................................ 84
10.7.3 Executing Queries ...................................................................................... 85
10.7.4 Processing Query Results ........................................................................... 85
10.7.5 Closing Queries .......................................................................................... 86
10.7.6 Example of Using a Class Query ............................................................... 86
11 Data Types .................................................................................................................... 89
11.1 Available Types .................................................................................................... 90
11.2 Operation .............................................................................................................. 91
11.2.1 Using Data Types in Classes ...................................................................... 91
11.2.2 Parameters .................................................................................................. 91
11.2.3 Keywords .................................................................................................... 93
11.2.4 Data Formats and Translation Methods ...................................................... 96
11.3 Enumerated Properties ......................................................................................... 97
12 Object Persistence ........................................................................................................ 99
12.1 The %Persistent Class .......................................................................................... 99
12.2 The Persistence Interface ................................................................................... 100
12.2.1 Saving Objects .......................................................................................... 100
12.2.2 Opening Objects ....................................................................................... 103
12.2.3 Deleting Objects ....................................................................................... 106
12.2.4 Testing if Objects Exist ............................................................................ 107
12.3 Object Extents .................................................................................................... 107
12.3.1 The Extent Query ..................................................................................... 108
12.4 Storage Definitions and Storage Classes ........................................................... 109
12.4.1 The %CacheStorage Storage Class .......................................................... 110
12.4.2 The %CacheSQLStorage Storage Class ................................................... 110
12.5 Schema Evolution .............................................................................................. 110
12.5.1 Resetting the Storage Definition .............................................................. 111
13 Objects and SQL ........................................................................................................ 113
vi
Using Caché Objects

13.1 Inheritance and SQL .......................................................................................... 113
13.1.1 How a Class is Projected to SQL ............................................................. 114
13.1.2 Naming Rules for Projected Classes ........................................................ 114
13.2 The Object-SQL Projection ............................................................................... 115
13.2.1 Identity (OIDs Projected to SQL) ............................................................ 115
13.2.2 Properties .................................................................................................. 116
13.2.3 Methods .................................................................................................... 122
13.2.4 SQL Triggers ............................................................................................ 122
13.2.5 Relationships ............................................................................................ 123
14 Relationships .............................................................................................................. 125
14.1 Relationship Basics ............................................................................................ 126
14.1.1 Relationship Keywords ............................................................................. 126
14.1.2 Defining a Relationship ............................................................................ 127
14.2 Dependent Relationships ................................................................................... 128
14.3 In-Memory Behavior of Relationships .............................................................. 129
14.4 Persistent Behavior of Relationships ................................................................. 131
14.4.1 Referential Integrity .................................................................................. 131
14.4.2 Persistent Behavior of Dependent Relationships ..................................... 131
15 Streams ....................................................................................................................... 133
15.1 Declaring Stream Properties .............................................................................. 133
15.1.1 Projecting Streams to ODBC ................................................................... 134
15.2 Using the Stream Interface ................................................................................. 134
15.2.1 Reading and Writing Stream Data ............................................................ 135
15.2.2 Copying Data between Streams ................................................................ 136
15.2.3 Inserting Stream Data ............................................................................... 136
15.2.4 Using Streams in Object Applications ...................................................... 137
15.3 Using Streams with SQL ................................................................................... 137
15.4 Streams and Visual Basic ................................................................................... 139
16 Class Projections ........................................................................................................ 141
16.1 Projection Definitions ........................................................................................ 141
16.1.1 Adding a Projection to a Class ................................................................. 141
16.2 Projection Classes .............................................................................................. 142
16.2.1 The Projection Interface ........................................................................... 142
16.2.2 The Standard Projection Classes .............................................................. 143
16.2.3 Creating a New Projection Class .............................................................. 144
Using Caché Objects
vii

17 Object Synchronization ............................................................................................. 145
17.1 About Updates .................................................................................................... 145
17.1.1 The GUID ................................................................................................. 146
17.1.2 How Updates Work ................................................................................... 146
17.1.3 The SyncSet and SyncTime Objects ........................................................ 147
17.2 Running an Update ............................................................................................ 150
17.2.1 Preparing for the Update .......................................................................... 150
17.2.2 The Update Itself ...................................................................................... 151
17.3 Other Topics ....................................................................................................... 153
17.3.1 Translating Between GUIDs and OIDs .................................................... 154
17.3.2 Manually Updating a SyncTime Table ..................................................... 154
18 Method Generators ................................................................................................... 155
18.1 Defining a Method Generator ............................................................................ 155
18.2 How Method Generators Work .......................................................................... 156
18.3 Method Generator Context ................................................................................. 157
18.4 Implementing Method Generators ..................................................................... 158
18.4.1 Method Generators for Other Languages ................................................. 159
18.4.2 Specifying CodeMode within a Method Generator ................................. 159
19 The Caché Data Population Utility .......................................................................... 161
19.1 Data Population Basics ...................................................................................... 161
19.1.1 Changes to the Class Definition ............................................................... 162
19.1.2 Populating Objects ................................................................................... 162
19.2 The POPSPEC Parameter .................................................................................. 163
19.2.1 Populating Embedded Objects ................................................................. 165
19.2.2 Populating Lists ........................................................................................ 165
19.2.3 Populating Arrays ..................................................................................... 166
19.2.4 Custom Populate Actions ......................................................................... 166
19.3 Details ................................................................................................................ 167
20 Using Callback Methods ........................................................................................... 169
20.1 %OnAddToSaveSet ............................................................................................ 170
20.2 %OnAfterSave ................................................................................................... 171
20.3 %OnBeforeSave ................................................................................................. 172
20.4 %OnClose .......................................................................................................... 172
20.5 %OnConstructClone .......................................................................................... 173
20.6 %OnDelete ......................................................................................................... 174
20.7 %OnDetermineClass .......................................................................................... 174
viii
Using Caché Objects

20.8 %OnNew ............................................................................................................ 175
20.9 %OnOpen ........................................................................................................... 175
20.10 %OnRollBack .................................................................................................. 176
20.11 %OnValidateObject .......................................................................................... 176
20.12 OnPopulate ....................................................................................................... 177
21 Object-Specific ObjectScript Features .................................................................... 179
21.1 .. Syntax ............................................................................................................. 179
21.2 ##Class Syntax ................................................................................................... 180
21.2.1 Invoking a Class Method .......................................................................... 180
21.2.2 Casting a Method ...................................................................................... 180
21.3 ##this Syntax ...................................................................................................... 181
21.4 ##super Syntax ................................................................................................... 183
21.5 i% Syntax ............................................................................... 184
22 Dynamic Dispatch ...................................................................................................... 187
22.1 How Dynamic Dispatch Happens ...................................................................... 187
22.2 Content of Methods Implementing Dynamic Dispatch ..................................... 188
22.2.1 Return Values ............................................................................................ 189
22.3 The Dynamic Dispatch Methods ........................................................................ 189
22.3.1 %DispatchMethod .................................................................................... 189
22.3.2 %DispatchClassMethod ........................................................................... 190
22.3.3 %DispatchGetProperty ............................................................................. 190
22.3.4 %DispatchSetProperty .............................................................................. 190
22.3.5 %DispatchSetMultidimProperty .............................................................. 191
22.3.6 %DispatchGetModified ............................................................................ 191
22.3.7 %DispatchSetModified ............................................................................ 191
23 Class Definition Classes ............................................................................................ 193
23.1 Browsing Class Definitions ............................................................................... 194
23.2 Altering Class Definitions .................................................................................. 195
24 Internet Classes .......................................................................................................... 197
24.1 Email .................................................................................................................. 197
24.1.1 Mail Messages .......................................................................................... 197
24.1.2 Sending Email .......................................................................................... 198
24.1.3 Receiving Email ....................................................................................... 198
24.2 FTP ..................................................................................................................... 199
24.3 HTTP .................................................................................................................. 199
Using Caché Objects
ix

24.4 URL Parsing ....................................................................................................... 199
Appendix A: Object Concurrency ................................................................................. 201
A.1 Object Concurrency Options ............................................................................... 201
A.2 Version Checking ................................................................................................ 203
Index ................................................................................................................................ 205
x
Using Caché Objects

List of Figures
Embeddable Objects ........................................................................................................... 19
Class Packages .................................................................................................................... 32
Property Behavior ............................................................................................................... 48
Two Unsynchronized Databases ....................................................................................... 147
Two Databases, Where One Has Been Synchronized to the Other .................................. 148
Two Synchronized Databases ........................................................................................... 149
Using Caché Objects
xi

List of Tables
Caché Class Library Packages .............................................................................................. 5
Class Identifier Lengths ...................................................................................................... 26
Collection Objects .............................................................................................................. 51
Caché Data Type Classes .................................................................................................... 90
Supported Parameters for System Data Type Classes ........................................................ 92
CLIENTDATATYPE Values ............................................................................................... 94
ODBCTYPE Values ............................................................................................................ 95
SQLCATEGORY Values .................................................................................................... 96
The Object-SQL Projection .............................................................................................. 115
Sample Projection of an Array Property ........................................................................... 119
Sample Projection of a List Property ................................................................................ 120
Projection Classes ............................................................................................................. 144
Objects Available to Method Generators .......................................................................... 157
xii
Using Caché Objects

1
Introduction to Caché Objects
This document provides an in-depth look at the details of Caché Objects.
If you are new to Caché Objects, you may find the Caché Web Applications Tutorial tutorial
to be a useful introduction.
Caché Objects is a set of technologies that give application developers the means to easily
create high performance, object-based, database applications.
The features of Caché Objects include:
• A powerful object model that includes inheritance, properties, methods, collections,
relationships, user-defined data types, and streams.
• A flexible object persistence mechanism that allows objects to be stored within the native
Caché database as well as external relational databases.
• Control over the database aspects of persistent classes including indices, constraints, and
referential integrity.
• An easy-to-use transaction and concurrency model that includes the ability to load objects
by navigation—simply referring to an object can “swizzle” it into memory from the
database.
• Automatic integration with Caché SQL via the Caché Unified Data Architecture.
• Interoperability with Java, C++, and ActiveX.
• Automatically-provided XML support.
• A powerful, multi-user object development environment: Caché Studio.
You can use Caché Objects in a myriad of ways including:
Using Caché Objects 1

Introduction to Caché Objects
• To define the database and/or business components of a transaction processing application.
• To create a Web-based user interface using Caché Server Pages.
• To define object-based stored procedures that are callable from ODBC or JDBC.
• To provide object/relational access to legacy applications.
1.1 Caché Objects Architecture
Caché Objects contains the following major components:
• The Class Dictionary—a repository of class definitions (often known as meta-data), each
of which describes a specific class. This repository is stored within a Caché database.
The Class Dictionary is also used by the Caché SQL Engine and is responsible for
maintaining synchronized object and relational access to Caché data.
• The Class Compiler—a set of programs that convert class definitions into executable
code.
• The Object Runtime System—a set of features built into the Caché virtual machine that
support object operations (such as object instantiation, method invocation, and polymorphism)
within a running program.
• The Caché Class Library—a set of pre-built classes that come with every Caché installation.
This includes classes that are used to provide behaviors for user-defined classes
(such as persistence or data types) as well as classes that are intended for direct use within
applications (such as e-mail classes).
• The various Language Bindings—a combination of code generators and runtime components
that provide external access to Caché objects. These bindings include the Caché
Java binding, the Caché ActiveX binding, and the Caché C++ binding.
• The various Gateways—server-side components that give Caché objects access to
external systems. These gateways include the Caché SQL Gateway and the Caché Activate
ActiveX Gateway.
2 Using Caché Objects

1.2 Class Definitions and the Class Dictionary
Every class has a definition that specifies what members (properties, methods, etc.) it contains
as well as class-wide characteristics (such as superclasses). These definitions are contained
within the Caché Dictionary, which is itself stored within the Caché database.
1.2.1 Creating Class Definitions
You can create class definitions in many ways:
• Using Caché Studio. The primary means of working with Caché class definitions is with
the Caché Studio Development Environment.
• Using XML. Class definitions have an external, XML-based representation. Typically
this format is used for storing class definitions externally (such as in source control systems),
deploying applications, or simply for sharing code. You can also create new class
definitions programatically by simply generating the appropriate XML class definition
file and loading it into a Caché system.
• Using an API. Caché includes a set of class definition classes that provide object access
to the Class Dictionary. You can use these to observe, modify, and create class definitions.
• Using SQL DDL. Any relational tables defined by DDL statements are automatically
converted to equivalent class definitions and placed within the Class Dictionary.
In addition, Caché includes a set of tools (such as the Caché RoseLink connection to the
Rational Rose modeling tool) as well as Wizards (such as the Caché Activate Wizard) that
automatically create class definitions.
1.2.2 The Class Dictionary
Class Definitions and the Class Dictionary
Every Caché namespace contains its own Class Dictionary which defines the available classes
for that namespace. There is a special “CACHELIB” namespace, installed as part of Caché,
that contains the definitions and executable code for the classes of the Caché Class Library.
These classes are referred to as system classes and all have names that start with a “%”
character. (Strictly speaking, they have package names that start with “%” ).
Every Caché namespace is automatically configured so that its Class Dictionary, in addition
to containing its own classes, has access to the system class definitions and code within the
CACHELIB namespace. By this mechanism, all namespaces can make direct use of the
classes in the Caché Class Library.
Using Caché Objects 3

Introduction to Caché Objects
The Class Dictionary contains two distinct types of data:
• Definition Data—the actual class definitions that users create.
• Compilation Data—data generated as a result of compiling class definitions is also stored.
This data includes the results of inheritance resolution; that is, it lists all the defined and
inherited members for a given class. The Class Compiler uses this to make other compilation
more efficient; applications can also use it (via the appropriate interface) to get
runtime information about class members.
The Class Dictionary stores its data in a set of globals (persistent arrays) whose names start
with ^odd. The structure of these arrays may change with new versions of Caché, so applications
should never directly observe or modify these structures.
1.3 The Caché Class Library
The Caché Class Library contains a set of pre-built classes. It is automatically installed with
every Caché system within the CACHELIB database. You can view the contents of the Caché
Class Library using the online class documentation system provided with Caché.
The Caché Class Library contains a number of packages, each of which contains a family of
classes. Some of these are internal and Caché Objects uses them as part of its implementation.
Other classes provide features which are designed for use in applications.
The main packages within the Caché Class Library include:
4 Using Caché Objects

Development Tools
Caché Class Library Packages
Package
%Activate
%Compiler
%CSP
%csr
%Library
%Net
%Projection
%SQL
%Studio
%SYSTEM
%XML
Description
Classes used by the Caché Activate ActiveX gateway.
Internal classes used by the Caché Class Compiler.
Classes used by Caché Server Pages.
A set of generated internal classes that implement the standard CSP
rules.
The core set of Caché “behavioral” classes (such as %Persistent). Also
includes the various data types, collections, and stream classes.
A set of classes providing various internet-related features (such as
e-mail, HTTP requests, etc.)
A set of projection classes that generate client-side code for user
classes.
Internal classes used by Caché SQL.
Internal classes used by Caché Studio.
The various System API classes accessible via the $System special
variable.
Classes used to provide XML and SAX support within Caché.
1.4 Development Tools
Caché includes a number of tools for developing object-based applications. In addition, it is
quite easy to use Caché with other development environments.
1.4.1 Caché Studio
Caché Studio is an integrated, visual development environment for creating Caché class
definitions. See the Caché Studio User's Guide for more details.
Using Caché Objects 5

Introduction to Caché Objects
1.4.2 Caché RoseLink
Caché RoseLink is an add-in for the popular Rational Rose modeling tool that creates Caché
class definitions from and displays existing classes as UML diagrams. This allows developers
to take advantage of the object-oriented power of UML without the headache of mapping to
relational tables.
1.4.3 SQL-based Development
It is possible to develop Caché applications using SQL-based tools, since Caché automatically
creates a class definition from any relational tables defined using SQL DDL statements. This
approach does not exploit the full power of objects because you are limited by what DDL
can express; however, it is useful for migrating legacy applications.
1.4.4 XML-based Development
It is possible to develop class definitions as XML documents and load them into Caché. You
can do this using either Caché's specific XML format for class definitions or you can use an
XML schema representation.
1.5 Client Interoperability
Caché Objects can communicate with a variety of environments:
1.5.1 Java
Caché gives you the ability to use Caché objects within a Java environment as native Java
classes. This gives Java-based applications direct, high-performance access to object and
relational data stored within Caché. It also provides Caché applications with the ability to
easily interoperate with Java.
Caché supports the following connectivity with Java:
• The Caché Java Binding—automatically exposes Caché classes as Java classes, complete
with automatically generated accessor methods and sophisticated data caching. The full
spectrum of object features are supported including custom data types, streams, collections,
queries, and relationships.
6 Using Caché Objects

• The Caché EJB Binding—a version of the Java Binding that automatically creates
Enterprise Java Bean components from Caché class definitions.
• The Caché JDBC Driver—a high performance, native JDBC driver that provides relational
access to data stored within a Caché database.
For more information, see Using Java with Caché.
1.5.2 ActiveX / COM / .net
Caché gives you the ability to use Caché objects within a COM-enabled environment such
as Windows or the .net framework. Caché objects are automatically projected as standard
COM components. This gives COM-based applications (such as Visual Basic) direct, highperformance
access to object and relational data stored within Caché. It also provides Caché
applications with the ability to easily interoperate with COM.
Caché supports the following connectivity with COM:
For more information, see Using ActiveX with Caché.
Client Interoperability
• The Caché ActiveX Binding—automatically exposes Caché classes as COM components,
complete with sophisticated data caching. The full spectrum of object features are supported
including custom data types, streams, collections, queries, and relationships.
• The Caché ODBC Driver—a high performance, ODBC driver that provides relational
access to data stored within a Caché database. This can be used with third-party control
that only support relational access.
1.5.3 Caché Server Pages
Using Caché Server Pages (CSP) you can easily create high-performance, object-based, web
applications.
For more information, see the Using Caché Server Pages (CSP).
1.5.4 C++
Caché gives you the ability to use Caché objects within C++-based applications. Caché objects
are projected as standard C++ components. The resulting C++ classes are portable across a
variety of operating systems and make use of the C++ standard library. This gives C++-based
applications direct, high-performance access to object and relational data stored within Caché.
It also provides Caché applications with the ability to easily interoperate with C++.
Using Caché Objects 7

Introduction to Caché Objects
Caché supports the following connectivity with C++:
• The Caché C++ Binding—automatically exposes Caché classes as COM components
classes complete with sophisticated data caching. The full spectrum of object features
are supported including custom data types, streams, collections, queries, and relationships.
• The Caché ODBC Driver—a high performance, ODBC driver that provides relational
access to data stored within a Caché database. This can be used within C++ applications
on a variety of platforms.
For more information, see Using C++ with Caché.
1.5.5 XML
Caché supports a rich variety of interconnectivity with XML including:
• The ability to bi-directionally project objects as XML documents.
• The ability to create class definitions from standard XML schemata and vice versa.
• The ability to easily create object-oriented, portable Web Services using SOAP.
• The ability to store class definitions as XML documents.
For more information, see Using XML with Caché.
1.5.6 The Caché SQL Gateway
The Caché SQL Gateway gives Caché applications ODBC-based access to data stored in
legacy relational databases. Specifically, the SQL Gateway works in conjunction with the
Caché object persistence mechanism to provide seamless object and SQL access to externally
stored relational data.
For more information see Using the Caché SQL Gateway.
1.5.7 The Caché Activate ActiveX Gateway
Caché Activate is an ActiveX gateway that lets Caché applications use ActiveX / COM
components within the Caché environment as if they were native components.
For more information see Using Caché Activate.
8 Using Caché Objects

2
Object-Oriented Database
Development
The use of object-oriented programming is widespread and growing. Most modern user
interface code is object based and a large amount of new business logic is also being implemented
as objects. Where there is a lag is within the database layer of applications. Most
databases rely on older methodologies (such as the ISAM and relational models). Caché
brings the power of object-oriented programming to the database.
In this chapter we will briefly discuss some of the key concepts of object-oriented programming
and how they relate to database application development.
2.1 Classes and Objects
A class is a template that describes the data and behavior of a specific entity within an
application. For example, your application may define a Car class that specifies the characteristics
shared by all cars within the application.
An object is a specific instance of a class. For example, a “1972 Dodge Dart” is a specific
instance of a Car.
Objects may exist in the memory of a specific process or session (similar to variables) where
they can be manipulated (data values changed, methods invoked). Objects can also be stored
in and retrieved from a database.
Using Caché Objects 9

Object-Oriented Database Development
Classes provide structure and organization to applications. In particular, classes make it
possible to divide the implementation of large applications among developers or teams of
developers with reasonable assurance that their work will function when later integrated.
An important feature of Caché is that new classes can be defined at runtime; that is, an
application can extend itself by creating and using new classes as it runs.
2.2 Abstraction and Modeling
Data abstraction is the process of taking the essential details of real-world entities (such as
employees, invoices, documents) and defining from them representations that can be used
within a software application.
Object modeling is the process of taking a data abstraction and representing it as a set of
classes, where each class defines the properties and behaviors of a specific entity. A set of
behaviors defined for a class is typically referred to as an “interface” .
Abstraction and modeling are at the heart of object-oriented programming. Using an object
model, you can define application components that are analogs of the real-world entities your
application works with. The beauty of an object model is that it is rich enough to model
complex entities in a natural way: a book with a set of related chapters, for example. Contrast
this with traditional relational database design where the data representation of real-world
entities must be constrained to fit into 2–dimensional tables and there is no mechanism for
associating behavior with data.
2.3 Inheritance and Polymorphism
Inheritance is the process of taking an existing class and specializing it (changing aspects of
its behavior) for new circumstances. Specifically this is done by specifying one or more super
classes when creating a new class. The new class will inherit all of the data and behavior of
its superclass. In addition the new class can add additional data and behavior or selectively
replace (override) the behaviors inherited from its super class.
Polymorphism is the ability to invoke the same method on objects of different types (but with
a common superclass). Each object executes its own specific implementation of the method.
This allows you to use new object types within existing applications without having to modify
the applications.
10 Using Caché Objects

Encapsulation
Caché exploits inheritance in several ways, including:
• Extents—persistent classes derived a common superclass are stored within a common
extent in the database. For example, you can store instances of Person as well as its subclass,
Student, in the same extent. When an application asks for a list of all persons, it
will get the persons as well as the students (since a student is a person). If the application
asks for students, then only student (with any additional properties they define) are
returned. This automatic behavior is difficult to achieve using the relational model.
• Method Generators—Caché includes the concept of method generators: methods that
are, in fact, programs that create method implementations. Using method generators it
is possible to create classes that automatically generate application-specific code for different
circumstances.
2.4 Encapsulation
Encapsulation refers to the process of keeping the external representation of an
entity—properties and methods—independent from the entity's actual implementation. The
idea is that users of an entity (such as other parts of an application) can make use of it without
knowledge of its internal workings and are immune from changes in its implementation.
Object-oriented programming simplifies the process of encapsulation through the use of
classes which, by definition, encapsulate behavior.
An object-oriented database extends this concept to data stored within a database in two
important ways:
1. Properties encapsulate data: it is possible to change the database while maintaining the
same property interface. For example, a property may be redefined to be no longer stored
but to be the result of a calculation performed on other properties. Users of such a property
would see no difference.
2. Methods encapsulate behavior: when a persistent object is loaded from the database it is
automatically associated with the methods defined for its class. You can change the
implementation of such methods independently of both the data in the database and any
users of these methods.
Using Caché Objects 11

Object-Oriented Database Development
2.5 Extensibility
One of the key features of object-oriented systems is that they are extensible: it is possible
to tailor their behavior for specific applications.
Typically such extensibility is achieved in the following ways:
• Type definition: You can define new data types that represent application-specific data.
• Event handling: An application can define a set of methods that are called when certain
events occur. By providing such methods, the behavior of an application can be modified
without having to change its core implementation.
• Subclassing: An application can adapt previously developed components for new uses
by creating subclasses of existing classes.
2.6 Object Persistence
Object persistence refers to the ability to store object instances within a database. Caché is
unique in that such object can be fully queried using native (i.e., direct against the data) SQL
queries.
Caché can store objects natively; that is, objects are not first converted into a relational representation.
Instead each persistent object has methods (generated automatically) that directly
store and load objects into the Caché data engine. The persistence model automatically
manages concurrency, transactions, and validation. In addition, Caché supports the idea of
Schema Evolution: if you change your data model, it is still possible to use previously stored
objects.
2.7 Object Binding
An object binding is a mechanism by which a Caché object can project itself as a native object
in a different environment. For example, Caché supports a Java binding by which any Caché
object can be used within a Java environment as if it were a native Java class. Bindings exist
for languages such as Java, C++, Perl, Python, XML, ActiveX, and the .net Managed Provider.
12 Using Caché Objects

3
The Caché Object Model
The Caché object model defines the behavior and features of both persistent (database) objects
as well as transient objects (those not stored).
The Caché object model supports the following features:
• Persistence—Objects can be stored within the Caché database or in an external database.
Stored objects are simultaneously projected as relational tables and can be queried using
standard SQL.
The object model is rich enough to define the complete information required for complex
database applications (such as indices, storage structure, integrity constraints, etc.).
• Properties—Objects can contain both simple (literal) or object-valued properties. Objectvalued
properties can be references to external objects or embedded objects. There are
also a variety of relationship, collection, and stream properties.
• Custom Data Types—Objects can use application-specific data types which are themselves
defined as classes.
• Methods—Objects have behavior associated with them.
• Polymorphism—Applications can easily adapt to new circumstances by providing specialized
implementations of operations. The runtime system automatically invokes the
correct implementation based on object type.
• Inheritance—Applications can reuse code by deriving new components from pre-existing
classes.
Using Caché Objects 13

The Caché Object Model
Each class describes an entity, such as a person, a record, or an account. A class defines the
data (properties), behavior (methods), and additional characteristics (such as how a persistent
object is stored) for such an entity.
An object is a specific instance of a class. An object can exist on disk, in memory, or in a
client application.
3.1 Referring to an Object — OREF, OID, and ID
Within Caché, objects can either be on disk or in memory. An on-disk object is one that you
have stored in the database; an in-memory object is one that you have loaded from the database
and can manipulate. You can refer to an object in different ways, depending on whether it is
loaded or stored:
OREF
OID
An object reference. A value that refers to a specific, in-memory instance of an object.
An OREF refers to an in-memory version of an object. Each time an object is brought
into memory, it may have a different OREF value.
An object identifier. A value that uniquely identifies a specific instance of an object
stored in a database. An OID refers to an on-disk version of an object. An OID
uniquely identifies a persistent object that is stored in the database. Once an object
has received an OID value, that value does not change.
ID
An object identifier. A value that uniquely identifies a specific instance within a
particular extent. An ID refers to an on-disk version of an object. It does not include
any class-specific information.
You can use a persistent object's OID to locate the object and bring it into memory; similarly,
if you know a persistent object's extent, you can use its ID to locate it and bring it into
memory. Once in memory, the system assigns it an OREF value that the application can use
to refer to the object and access its contents. When a persistent object is stored in the database,
the values of any of its reference attributes (that is, references to other persistent objects) are
stored as OID values. For object attributes that do not have OIDs, the object's literal value is
stored along with the rest of the persistent object's state.
14 Using Caché Objects

Referring to an Object — OREF, OID, and ID
3.1.1 OID and ID Values
Caché makes a further distinction between a “universal” object identifier (OID) and a “local”
object identifier (ID). An OID value uniquely identifies any object stored in a database.
Specifically, an OID value contains a class name along with an ID value. An ID value uniquely
identifies an object belonging to a specific “extent” . An extent is a set of related objects,
such as all instances of a specific class or all instances of a class and its subclasses.
Caché provides two versions of methods that refer to persistent objects: one using OID and
the other using ID values. For example, using Caché ObjectScript you can open an object
instance using an OID value:
Set object = ##class(MyApp.Person).%Open(oid)
Or you can open it using an ID value:
Set object = ##class(MyApp.Person).%OpenId(id)
The ID versions have “Id” added to their name. In practice, applications most often use ID
values; there are few circumstances in which you need to locate an object in which you do
not know what extent (set of objects) an object belongs to.
Note that these two forms are also available in Caché Basic:
obj = Open MyApp.Person(oid)
obj = OpenId MyApp.Person(id)
3.1.2 OREFs and Reference Counting
References to in-memory objects (OREFs) automatically manage a reference count—the
number of items (variables or objects) currently referring to an object. Whenever you set a
variable or object property to refer to a object, the object's reference count is automatically
incremented. When a variable stops referring to an object (if it goes out of scope, is killed,
or is set to a new value) the reference count is decremented. When this count goes to 0, the
object is automatically destroyed (removed from memory) and its %OnClose method (if
present) is called.
For example, consider the following method:
Method Test()
{
Set person = ##class(Sample.Person).%OpenId(1)
}
Set person = ##class(Sample.Person).%OpenId(2)
Using Caché Objects 15

The Caché Object Model
This method creates an instance of Sample.Person and places a reference to it into the variable
person. Then it creates another instance of Sample.Person and replaces the value of person
with a reference to it. At this point, the first object is no longer referred to and is destroyed.
At the end of the method, person goes out of scope and the second object is destroyed.
You can test if a variable contains a valid OREF value using the ObjectScript $IsObject
function:
// Open an object that is in the database
Set obj = ##class(Sample.Person).%OpenId(1)
Write "Is (1) an object ",$IsObject(obj),!
// Open an object that is NOT in the database
Set obj = ##class(Sample.Person).%OpenId(-1)
Write "Is (-1) an object ",$IsObject(obj),!
3.2 Types of Classes
Caché supports a variety of class types for specialized behaviors. Classes are divided into
data type classes and object classes. Data type classes represent literal values such as strings,
integers, and dates; refer to the chapter on Data Types for more details. Data type classes are
used to create literal properties of other objects. They do not have properties and cannot be
instantiated.
Object classes may have properties and can be instantiated. Most object class are subclasses
of a system class called %RegisteredObject, which automatically provides much of an object's
basic behavior.
An object class has a rich set of default behaviors, which include the following:
• Its instantiation triggers the automatic allocation of system memory for its properties.
• Its instantiation triggers the automatic creation of a reference handle (OREF) for it.
• It supports polymorphism.
Object classes are further divided, according to their database behavior, into transient objects,
persistent objects, and serial objects. A transient object (derived directly from the
%RegisteredObject class) has no storage behavior; it exists only in memory. Persistent classes
(derived the the %Persistent class) can be independently stored in a database. Serial objects
(derived from the %SerialObject class) can be embedded within other objects; a serial object
can only be stored to the database when it is embedded within another, persistent object.
16 Using Caché Objects

Types of Classes
3.2.1 Transient Object Classes
Instantiations of classes derived from %RegisteredObject are known as registered or transient
objects. These objects have a full set of built-in methods for controlling their in-memory
behavior. (Most applications use persistent classes and embeddable classes rather than
inheriting directly from %RegisteredObject.)
Once you create an instance of a registered object, you can refer to it by its OREF (object
reference). This system assigned value is transient; the value exists only while the object is
in memory and is not guaranteed to be constant over different invocations.
Registered objects use system allocated memory to store their values, and they support
polymorphism.
3.2.2 Persistent Object Classes
Instantiations of classes derived from %Persistent are known as persistent objects; these
objects are registered objects that inherit from the %Persistent class and have their ClassType
keyword set to “persistent” . Persistent objects have the ability to store themselves into the
database.
Loading a persistent object into memory from the database does not load any other objects
that it refers to. As soon as a referenced object is referred to, however, it is automatically
brought into memory (this is known as “swizzling” or “lazy loading” ).
When a persistent object is used as a property, it is referred to as a “reference” property.
For example, if Doctor and Patient are persistent classes, you can define an attribute in the
Patient class that uses Doctor as its type:
Property TheDoc As Doctor;
The property, TheDoc, is a reference property. The first time this property is referenced:
Set doc = patient.TheDoc
the appropriate Doctor object is loaded from the database automatically. In this example, doc
will contain an OREF to the loaded Doctor object.
You can chain together as many references as you like within one expression:
Set location = patient.TheDoc.Hospital.Address.City
If any of the objects referenced in such an expression is missing (null), then the entire
expression will return a null value ("").
Using Caché Objects 17

The Caché Object Model
3.2.3 Serial Object Classes
Instantiations of classes derived from %SerialObject are known as serial or embeddable
objects; these objects are registered objects that inherit from the %SerialObject class and have
their ClassType keyword set to “serial” . These objects can exist independently in memory,
but, when stored to the database, can only exist as embedded within a persistent object.
The %SerialObject class provides an object with:
• The ability to produce a string representing the state of the object (that is, its current
property values). The creation of this string is known as serializing the object.
• The ability to be swizzled by using that serialized string. Like a persistent object, a serial
object can be used as a property type, but its on-disk behavior differs from that of a persistent
object. When used as a property, an embeddable class is known as an embedded
object.
Embedded objects have different in-memory and on-disk representations:
• In memory, an embedded object is represented as a separate object and is indistinguishable
from a reference to any other kind of object. The in-memory value of an embedded object
attribute is an OREF that refers to the object's in-memory representation.
• On disk, an embedded object property is stored as part of its containing object. A serial
object has no separate identity (OID) and cannot be referred to by other objects. The
values of the embedded object's properties are serialized and stored along with all of the
other object attributes.
The following diagram depicts an embeddable object as it exists in memory and on disk:
18 Using Caché Objects

Types of Classes
Embeddable Objects
Note:
Caché does not support polymorphic serial objects in persistent containers.
3.2.3.1 Embedded Objects in Memory and on Disk
When a new instance of an object containing an embedded object is created, the %New
method (or the analogous New command in Caché Basic) automatically creates an in-memory
instance of the object.
For example, consider an Address class:
Class MyApp.Address Extends %SerialObject [ClassType = serial]
{
Property Street As %String(MAXLEN=80);
Property City As %String(MINLEN=3);
Property State As %String(MINLEN=2);
}
Once defined, the Address class can be used as an embedded object attribute for a persistent
object class such as Patient:
Class MyApp.Patient Extends %Persistent [ClassType=persistent]
{
Property Name As %String;
Property Home As Address;
}
In memory, this Home property can be used as any other object-valued property:
// Open a persistent patient object
Set patient = ##class(MyApp.Patient).%OpenId(22)
// Get the patient's city and state from its Home address
Set city = patient.Home.City
Set state = patient.Home.State
Using Caché Objects 19

The Caché Object Model
3.2.4 Data Type Classes
Data type classes define and control literal values. Unlike object classes, data types do not
have any independent identity and can never be explicitly instantiated. Instead, they exist
only as properties of the objects that contain them. Data types classes cannot contain properties.
A data type is a class with its ClassType keyword set to “datatype” . A data type class may
implement a specific set of methods belonging to the data type interface. This interface
includes a number of operations designed for validation and SQL interoperability.
For example, the class Patient can define an attribute Name using the system-provided data
type %String:
Class MyApp.Patient Extends %Persistent [ClassType = persistent]
{
Property Name As %String;
}
Name exists as a value within a specific instance of a Patient object. You can only refer to it
as an attribute of the object:
Set name = pat.Name
When the object pat is destroyed, its Name property disappears along with the rest of its
properties (if any).
3.3 Inheritance
The Caché object model lets you extend (inherit from) existing classes by means of the Super
keyword. A class defined in this way is referred to as a subclass; the class or classes it is
derived from are referred to as superclasses.
In the Caché object model, a class definition has a Super keyword that indicates its list of
superclasses. Within a Caché Studio class definition this list is expressed using the “Extends”
keyword:
Class User.MyClass Extends %Persistent [ ClassType = persistent ]
{
}
Note:
The “Extends %Persistent” and the “ClassType = persistent” are both required in
the above definition.
20 Using Caché Objects

A class inherits all of the specifications of its superclasses, including properties, methods,
class parameters, applicable class keywords, 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) many of the characteristics of its inherited components.
In addition to a class inheriting methods from its superclasses, the class' properties inherit
additional methods from system property behavior classes and, in the case of a data type
attribute, from the data type class.
For example, if there is a class defined called Person:
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{
Property Name As %String;
Property DOB As %Date;
}
It's simple to derive a new class, Employee, from it:
Class MyApp.Employee Extends Person [ClassType = persistent]
{
Property Salary As %Integer;
Property Department As %String;
}
Inheritance
This definition establishes the Employee class as a subclass of the Person class. In addition
to its own class parameters, properties, and methods, the Employee class includes all of these
elements from the Person class.
Note:
A class does not inherit the value of its superclass' ClassType keyword. You must
explicitly specify this value in every subclass.
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 // results in "Groucho Marx"
We can also access Employee-specific attributes or methods:
Write x.Salary // results in 22000
Using Caché Objects 21

The Caché Object Model
3.3.1 Multiple Inheritance
By means of multiple inheritance, a class can inherit its behavior and class type from several
superclasses. To establish multiple inheritance, use the SUPER keyword and then the classes
from which the defined class inherits.
When you compile the class, the class compiler establishes values for the class' members
according to the list of superclasses; a class' members are its class parameters, methods, and
properties, but not its class keywords. If multiple superclasses have members with the same
name, a superclass listed later takes precedence.
Note that the override does not occur for class keywords. For these, the subclass inherits only
the keyword values of its first superclass.
For example, if class X inherits from classes A, B, and C, its definition includes:
Class X Extends (A, B, C) {
}
In this case, the values of class X's class parameter values, properties, and methods are
inherited from class A (the first superclass listed), then class B, and, finally, class C. If class
B has a class member with the same name as a member already inherited from class A, it
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.
3.4 Class Compilation
Caché class definitions are compiled into application routines by the Caché Class Compiler.
Classes cannot be used in an application before they are compiled.
The Caché Class Compiler differs from the compilers available with other programming
languages, such as C++ or Java, in two significant ways: first, the results of compilation are
placed into a shared repository (database), not a file system. Second, it automatically provides
support for persistent classes.
Specifically, the Class Compiler does the following:
1. It generates a list of dependencies—classes that must be compiled first. Depending on
the compile options used, any dependencies that have been modified since last being
compiled will also be compiled.
22 Using Caché Objects

2. It resolves inheritance—it determines which methods, properties, and other class members
are inherited from super classes. It stores this inheritance information into the Class
Dictionary for later reference.
3. For persistent and serial classes, it determines the storage structure needed to store objects
in the database and creates the necessary runtime information needed for the SQL representation
of the class.
4. It executes any method generators defined (or inherited) by the class.
5. It creates one or more routines that contain the runtime code for the class. The Class
Compiler will group methods according to language (Caché ObjectScript and Basic) and
generates separate routines, each containing methods of one language or the other.
If you specify the “Keep Generated Source” option with the Class Compiler, you can
view the source for the routines using the View Other command within Studio.
6. It compiles all of the generated routines into executable code.
7. It create a class descriptor. This is a special data structure (stored as a routine) that contains
all the runtime dispatch information needed to support a class (names of properties,
locations of methods, etc.).
There are several ways to invoke the Class Compiler:
• From within Caché Studio using the option in the Build menu.
• From the Caché command line (terminal) using the Compile method of the %SYSTEM.OBJ
object:
Do $System.OBJ.Compile("MyApp.MyClass")
Class Compilation
Note that if you use SQL DDL statements to create a table, the Class Compiler will be automatically
invoked to compile the persistent class corresponding to the table.
Using Caché Objects 23

4
Caché Classes
A class specification defines the contents and behavior of a class. This chapter describes the
details of Caché class definitions. A class definition is distinct from a compiled class that you
can instantiate at run time. A class definition consists of a number of elements, called members,
and associated values; the sum total of these defines the class.
The members of a class definition includes properties (which represent its state) and methods
(which is the code that implements its behavior); these are each discussed in their own subsequent
chapters, Methods and Properties. The class definition for a data type contains only
methods, since data type classes have only literal values (and do not have properties). There
are also other components to a class specification, including class parameters and class keywords
(see below).
The primary means for defining classes is the Caché Studio. Alternatively, you can define
classes programmatically using the Caché class definition classes or via an XML class definition
file. If you define an SQL table using SQL DDL statements, Caché creates a corresponding
class definition.
Each class definition specifies a number of members (and values for them):
• A unique class name (including the package the class belongs to).
• Methods—operations that may be carried out on or by a specific class or instance.
• Properties—the data associated with the instances of a class.
• Class Queries—filters used to find class instances that meet specific criteria.
• Indexes—storage structures that optimize access to frequently viewed data.
• Class Keywords—values that specify overall class behavior, such if a class is final or
abstract.
Using Caché Objects 25

Caché Classes
• Class Parameters—values that customize the behavior of a class at compile time, typically
through the use of method generators.
4.1 Naming Conventions
Class and class members (referred to as identifiers) follow specific naming conventions.
These are detailed in this section.
4.1.1 General Identifier Rules
Every identifier must be unique within its context (i.e., no two classes can have the same
name).
The maximum length of the various class identifiers are listed in the following table:
Class Identifier Lengths
Identifier
Package Name
Full Class Name
Class Name
Member Name
Limits
Each package name in a project must be different somewhere in
the first 189 characters from all other packages in the namespace.
The full name of a class includes the package name, the class
name, and the period separating the package name from the
class name. It must be shorter than 220 characters.
The length of a class name is not specified. For a given package
name, the maximum length can be inferred from the preceding
rules. Each class name within a package must be uniquely
distinguished from the others in the first 60 characters.
The name of a class member (property name, method name,
index name, and so on) cannot be longer than 31 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. On a Unicode system,
identifiers may contain Unicode characters.
26 Using Caché Objects

Certain identifiers start with the “%” character; this identifies a system item. For example,
many of the methods and packages provided with the Caché library start with the “%”
character.
4.1.2 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 a
Caché namespace. For details on packages, refer to 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.
4.1.3 Class Member Names
Class Keywords
Every class member (such as a property or method) must have a name that is unique within
its class. Further, a member of a persistent cannot use an SQL reserved word as its identifier;
it can define an alias, however, using the member's SQLName or SQLFieldName keyword
(as appropriate).
4.2 Class Keywords
A class definition includes a set of keywords whose values specify the overall behavior of
the class. Each keyword is optional and has a default value if not explicitly specified.
Abstract
ClassType
Specifies that you cannot create instances of this class; for data type classes, specifies
that the class cannot be used as a property type.
Specifies the behavior of the class. Available values are datatype, persistent, and
serial.
Using Caché Objects 27

Caché Classes
ClientDataType
Description
For a data type class, specifies the type when exposed via ActiveX or Java. There is
no default value. Data type classes must specify a client data type.
Specifies a description of the class. The description is displayed by the online class
documentation system. For an example refer to the description for the %Persistent
class.
Final
Specifies that the class is final; no classes can be derived from it.
SQLRowIdName
Specifies an alternate field name for the object row ID projected to SQL. By default
the row ID is called “ID” .
SQLTableName
Super
Specifies the table name used to identify the class in its SQL projection. By default,
Caché uses a class' name as the name of its SQL table.
Specifies one or more superclasses for the class (classes that the class extends). By
default, classes have no superclasses.
For a complete list of class keywords, refer to the Class Definition Reference.
4.3 Class Parameters
A class parameter defines a special constant value for all objects of a given class. When you
create a class definition (or at any point before compilation), you can set the values for its
class parameters. By default, the value of each parameter is the null string; to set a parameter's
value, you must explicitly provide a value for it. At compile-time, the value of the parameter
is established for all instances of a class. This value cannot be altered at run time.
Class parameters are typically used for the following purposes:
28 Using Caché Objects

• To provide parameterized values for method generator methods to use. A method generator
is a special type of method whose implementation is actually a short program that
is run at compile-time in order to generate the actual runtime code for the method. Many
method generators use class parameters as a way of controlling the behavior of method
generators.
• To customize the behavior of the various data type classes (such as providing validation
information).
• To define user-specific information about a class definition. A class parameter is simply
an arbitrary name/value pair; you can use it to store any information you like about a
class.
• To define a class-specific constant value.
A subclass can define additional class parameters. A subclass can also override the value of
an inherited class parameter. For instance, if a class property assigns a value to a data type
class parameter, then subclasses of the object's class inherit that property's assigned value.
For example, suppose class MyApp.A defines a parameter, XYZ with a value of 10:
Class MyApp.A
{
Parameter XYZ = 100;
}
A subclass, such as MyApp.B, can override the value of this parameter:
Class MyApp.A Extends MyApp.B
{
Parameter XYZ = 200;
}
Class parameters have a special behavior when used with data type classes. With data type
classes, class parameters are used to provide a way to customize the behavior of the data type.
When you define a property within a class, you specify the property's type using a data type
class and you can provide specific values for any parameters defined by the data type class.
For example, the %Integer data type class has a class parameter, MAXVAL, which specifies
the maximum valid value for a property of type %Integer. If you define a class with the
property NumKids as follows:
Property NumKids As %Integer(MAXVAL=10);
Class Parameters
This specifies that the MAXVAL parameter for the %Integer class will be set to 10 for the
NumKids property.
Using Caché Objects 29

Caché Classes
Internally, this works as follows: the validation methods for the standard data type classes
are all implemented as method generators and use their various class parameters to control
the generation of these validation methods. In this example, this property definition generates
content for a NumKidsIsValidDT method that tests whether the value of NumKids exceeds
10. Without the use of class parameters, creating this functionality would require the definition
of an IntegerLessThanTen class.
30 Using Caché Objects

5
Packages
Caché Objects supports “packages” ; a way to group related classes within a specific
namespace. Packages provide the following benefits:
• They give developers an easier way to build larger applications and to share code with
one another.
• They make it easier to avoid name conflicts between classes.
• They give a logical way to represent SQL schemas within the Object Dictionary in a
clean, simple way: A package corresponds to a schema.
5.1 Overview of Packages
A package is simply a way to group related classes under a common name. For example, an
application could have an “Accounting” system and an “Inventory” system. The classes
that make up these applications could be organized into an “Accounting” package and an
“Inventory” package:
Using Caché Objects 31

Packages
Class Packages
Any of these classes can be referred to using their full name (which consists of package and
classname):
Do ##class(Accounting.Invoice).Method()
Do ##class(Inventory.Item).Method()
If the package name can be determined from context (see below), then the package name can
be omitted:
Do ##class(Invoice).Method()
A package is simply a naming convention: it does not provide any fundamental capabilities
beyond how classes are named.
As with classes, a package definition exists within a Caché namespace. A package cannot
span namespaces. It will be possible, in a future version, to refer to packages in other
namespaces using subscript-level mapping.
5.2 Package Names
A package name is simply a string. It may contain “.” (period) characters but no other
punctuation. Although packages may contain “.” characters, there is no true hierarchy of
packages (the various Caché development tools do display packages as a hierarchy for convenience).
If you give a class the name “Test.Subtest.TestClass” , then this indicates that the
name of the class is “TestClass” and the name of the package is “Test.Subtest” (which is
mapped to the SQL schema “Test_TestClass” , as described below).
There are several limitations on the length and usage of package names:
• A package name (including “.” characters) is limited to 31 characters or less.
32 Using Caché Objects

• Within a namespace, each package name must be unique (regardless of case).
Defining Packages
• Within a package, each class name must be unique within its first 25 characters.
5.3 Defining Packages
Packages are implied by the name of the classes. An easy way to create a package is to use
the New Class Wizard (in the Caché Studio), which has a input box where you can type in
the name of the new package. (You can also browse from a list of current packages.)
When the last class in a package is deleted, the package is also automatically deleted.
Alternatively, you can simply create a class. When you do so, the package automatically is
defined. For example, to define a package, simply add the package name to the class name
in its definition:
Class Accounting.Invoice {
}
This defines a class called Invoice within the “Accounting” package.
Using the Caché Studio you can view and edit additional characteristics for a package, such
as its description, by right-clicking on the package name within the Project tab of the
Workspace window.
5.4 Using Packages
There are two ways to use class names:
• Use the fully-qualified name (i.e., Package.Class).
• Use just the simple (short) class name and let the class compiler resolve which package
it belongs to.
Using fully-qualified names is simple:
// create an instance of Lab.Patient
Set patient = ##class(Lab.Patient).%New()
Using Caché Objects 33

Packages
Letting the compiler resolve names requires the #IMPORT directive in .MAC code or within
a class definition. If no import is specified, “short” class names are assumed to be in the
“User” or “%Library” packages:
// create an instance of Person
Set person = ##class(Person).%New()
// this is the same as:
Set person = ##class(User.Person).%New()
5.4.1 The IMPORT Directive
The #IMPORT directive lets you specify a package to search in for a particular class; for
example:
#import Lab
// Look for "Patient" within Lab package.
Set patient = ##class(Patient).%New()
You may have any number of #IMPORT statements within a MAC routine:
#import Lab
#import Accounting
// Look for "Patient" within Lab & Accounting packages.
Set pat = ##class(Patient).%New()
// Look for "Invoice" within Lab & Accounting packages.
Set inv = ##class(Invoice).%New()
The order of #IMPORT statements does not matter; It is an error to use a short class that is
ambiguous. That is, if you have the same class name in two or more packages and import all
of them, you will get an error when the compiler attempts to resolve the package name. To
avoid this error, use full names.
The class keyword, IMPORT, works in the same way: it specifies which packages to use for
resolving class references within the class definition and also that an #IMPORT statement
should be placed in the generated code. Note that if you do not have any #IMPORT statements,
it is as if you had specified:
#import User
Once you have any #IMPORT statement, User is NOT automatically imported. Therefore,
you may have to specify:
#import MyPackage
#import User
34 Using Caché Objects

The reason for this logic is because there are cases where you may NOT want User to be
imported. Using the #IMPORT statement, you can do clever tricks:
#import Customer1
Do ##class(Application).Run()
Now change App.MAC to:
Packages and SQL
#import Customer2
Do ##class(Application).Run()
When you recompile App.MAC, you will be using the Application class for the “Customer2”
package. Such tricks require up-front planning: you have to consider code compatibility as
well as the effects on your storage structures.
5.5 Packages and SQL
Every package corresponds to an SQL schema. For instance, if a class is called Team.Player
(the Player class in the “Team” package), the corresponding table is “Team.Player” (the
Player table in the “Team” schema).
The default package is “User” , which corresponds to the “SQLUser” schema. Hence, a
class called User.Person corresponds to a table called SQLUser.Person.
If a package name contains periods, the corresponding table name uses an underscore in the
place of each. For example, the class MyTest.Test.MyClass (the MyClass class in the
“MyTest.Test” package) becomes the table MyTest_Test.MyClass (the MyClass table in the
“MyTest_Test” schema).
If an SQL table name is referenced without the schema name, the default schema name
(SQLUser) is used. For instance, the command:
Select ID, Name from Person
is the same as:
Select ID, Name from SQLUser.Person
5.6 Built-in Packages
For compatibility with earlier versions, there are two "built-in" packages:
Using Caché Objects 35

Packages
• “%Library” —any %class (without a package name) is implicitly part of the “%Library”
package.
• “User” —any non-% class name without a package is implicitly part of the “User”
package
36 Using Caché Objects

6
Methods
Methods are operations that are associated with and can be invoked upon an object. Methods
are executed within a Caché process; when you are using Caché object on a client (such as
a Java program), Caché automatically invokes methods within the appropriate server process.
Every method has a name, a formal argument specification, and an implementation (code).
A method name must be unique within its class.
Note:
The word “method” generally refers to instance methods, or methods that act on a
specific instance of a class. Caché also supports class methods (methods that do not
act on a specific instance).
6.1 Method Arguments
Methods operate on variables that they receive through their arguments. A method can take
any number of arguments. A method's definition specifies the arguments that it takes and
each argument's data type. You can also specify the default value for any missing argument.
Additionally, a method definition specifies which arguments are called by reference and
which are called by value. The default is to call an argument by value.
For instance, here is a Calculate method taking three arguments:
Method Calculate(count As %Integer, name, state As %String = "CA")
{
// ...
}
Using Caché Objects 37

Methods
where count and state are declared as %Integer and %String, respectively. By default, arguments
are of the %String data type, so that an argument of unspecified type is a %String. This is the
case for name in the above example. Generally it is a good idea to explicitly specify the data
type of of each method argument.
6.1.1 Specifying Default Values
To specify an argument's default value, set it equal to the desired value:
Method Test(flag As %Integer = 0)
{
}
When a method is invoked, it uses its default values (if specified) for any missing arguments.
6.1.2 Calling By Reference
By default, method arguments are passed by value. You can call an argument by reference
using the ByRef modifier:
/// Swap value of two integers
Method Swap(ByRef x As %Integer, ByRef y As %Integer)
{
Set temp = x
Set x = y
Set y = temp
}
You can also specify an argument whose value is returned by reference but has no incoming
value by using the Output modifier. This is equivalent to ByRef except that any incoming
argument values are ignored.
Method CreateObject(Output newobj As MyApp.MyClass) As %Status
{
Set newobj = ##class(MyApp.MyClass).%New()
Quit $$$OK
}
In Caché ObjectScript, when calling a method which has arguments that are passed by reference
(ByRef or Output), you must place a dot “.” before each of the arguments being called
by reference, such as:
Do obj.Swap(.arg1, .arg2)
You can pass both simple variables and OREFs (object references) by reference using this
syntax.
38 Using Caché Objects

Method Return Values
6.2 Method Return Values
Each method's definition specifies whether it returns a value and, if so, the return value's type.
The return type of a method is a class. If the return type is a data type class, then the method
returns a literal value (such as a number or string). Otherwise, the method returns a reference
(OREF) to an instance of a class.
The syntax for specifying a return type is:
Method MethodName() As ReturnType
{
}
where Method is the method and ReturnType specifies the name of the class that Method
returns.
For example, the following method returns an %Integer value:
Method Add(x As %Integer, y As %Integer) As %Integer
{
Quit x + y
}
An example of a method that creates and returns an object instance is:
Method FindPerson(id As %String) As Person
{
Set person = ##class(Person).%OpenId(id)
Quit person
}
6.3 Method Visibility
Instance methods can be either public or private. If private (specified with the PRIVATE
keyword), they can only be accessed by methods of any instance of the class to which they
belong; if public (the default), they can be accessed from any method or other call.
Class methods can only be public. A class method using the PRIVATE keyword is still
accessible from all methods or other calls; however, it does not appear in the generated Caché
Class Reference.
In Caché, private methods are inherited and visible to subclasses of the class that defines the
method. Other languages often call these protected methods.
Using Caché Objects 39

Methods
6.4 Method Language
You have the choice of implementation language when creating a method within Caché.
Currently, there are three options: “Cache” (Caché ObjectScript), “Basic” , and “Java” .
By default, a method uses the language specified by its class' Language keyword. You can
override this on a method-by-method basis using the method's Language keyword:
Class MyApp.Test {
/// A Basic method
Method TestB() As %Integer [ Language = basic]
{
'This is Basic
Print "This is a test"
Return 1
}
/// A Cache ObjectScript method
Method TestC() As %Integer [ Language = cache]
{
// This is Cache ObjectScript
Write "This is a test"
Quit 1
}
}
Within a class, it is possible to have methods implemented in different languages. All methods
interoperate regardless of implementation language.
Caché ObjectScript and Basic methods are compiled into executable Caché code; Java
methods are treated differently. When you create a Java representation of a class (using the
Caché Java Binding), all of its Java methods are generated directly within the Java source.
This means that all Java methods run within a native JVM and have access to the complete
Java environment.
6.5 Method Keywords
You can modify a method definition through the use of one or more method keywords. Each
keyword is optional and has a default value if not explicitly specified.
The major method keywords are:
40 Using Caché Objects

ClassMethod
Description
Method Keywords
Specifies that the method is a class method. By default, methods are instance methods.
Subclasses inherit and cannot modify the value of the ClassMethod keyword.
Provides an optional description of the method; Caché does not use this description.
By default methods have no description. Subclasses do not inherit the value of the
Description method keyword.
Final
Specifies that subclasses cannot override the method. By default, methods are not
final. The Final method keyword is inherited by subclasses.
Private
ReturnType
SQLProc
Specifies that the method can only be invoked by other methods of its class or subclasses.
(If a method is not private, there are no restrictions on where it can be
invoked.) Subclasses inherit the methods as private and can modify the value of the
keyword. By default, a method is public. (Note that other languages often use the
word “protected” to describe this kind of visibility and use “private” to prevent visibility
from subclasses.)
Specifies the data type of the value returned by a call to the method. Setting
ReturnType to an empty string ("") specifies that there is no return value.
The value of the ReturnType keyword is inherited by subclasses and can be modified
by subclasses. If you do override the value of the ReturnType keyword, you are limited
to changing it to a class that is a subclass of the original type.
By default, a method has no return value.
Specifies that the method is an SQL stored procedure. By default, a method has no
stored procedures. Stored procedures are inherited by subclasses.
Using Caché Objects 41

Methods
6.6 Instance and Class Methods
Generally, the term “method” refers to an instance method, which is a method that is invoked
from a specific instance of a class that performs some action related to that instance, such as
performing business logic, displaying information about the instance, and so on. For example,
suppose you have an instance of the Sample.Person class (included in the “Samples”
namespace) in memory called MyPerson; you can then invoke its instance methods, such as
its NinetyNine method (a example method that simply returns the value 99):
Set x = MyPerson.NinetyNine()
This line of code uses the NinetyNine method to set x equal to 99.
In addition to instance methods, Caché supports class methods. A class method is not necessarily
associated with a particular object and need not be invoked from an open object. As
such, you can invoke a class method in either of two ways:
• Without any object reference
• From a specific instance in order to act on one or more objects of the class
A class method can refer to other class methods, but cannot refer to any object properties or
instance methods. For example:
Set x = ##class(Invoice).%Open(oid)
Set x = ##class(Patient).%New()
The first example involves the %Open class method of the Invoice class, which takes the
OID of a particular instance, opens that instance, and returns a handle to it; the second
example uses the Patient class' the %New method to create a new Patient instance and return
a handle to it.
Class methods are important because you can invoke them without having an instance that
is already open. For example, you can use the %New and %OpenId class methods to create
or open an instance. Class methods are also useful for actions that involve multiple or all
instances of a class.
6.7 Kinds of Methods
Caché supports four types of methods:
42 Using Caché Objects

Kinds of Methods
• Code Methods
• Expression Methods
• Call Methods
• Method Generators
The various method types control how the Caché class compiler interprets the Implementation
of the method.
6.7.1 Code Methods
A code method is a method whose implementation is simply lines of code. This is the most
typical type of method and is the default.
For instance, the following method defines a Speak code method for the Dog class:
Class MyApp.Dog Extends %Persistent [ClassType = persistent]
{
Method Speak() As %String
{
Quit "Woof, Woof"
}
}
The method code can contain any valid Caché ObjectScript code (including embedded SQL
and embedded HTML) or Basic code (depending on the method's Language keyword).
Assuming dog refers to a Dog object, you could invoke this method as follows:
Write dog.Speak()
// yields: Woof, Woof
6.7.2 Expression Methods
An expression method is a method that may be replaced by the class compiler, in certain
circumstances, with a direct in-line substitution of a specified expression. Expression methods
are typically used for simple methods (such as those found in data type classes) that need
rapid execution speed.
For example, it is possible to convert the Speak method of the Dog class from the previous
example into an expression method:
Method Speak() As %String [CodeMode = expression]
{
"Woof, Woof"
}
Assuming dog refers to a Dog object, this method could be used as follows:
Using Caché Objects 43

Methods
Write dog.Speak()
Which could result in the following code being generated:
Write "Woof, Woof"
It is a good idea to give all formal variables of an expression method default values. This
prevents potential inline substitution problems caused by missing actual variables at runtime.
Note:
Caché does not allow macros or call-by-reference arguments within expression
methods.
6.7.3 Call Methods
A call method is a special mechanism to create method wrappers around existing Caché
routines. This is typically useful when migrating legacy code to object-based applications.
Defining a method as a call method indicates that a specified routine is called whenever the
method is invoked. The syntax for a call method is:
Method Call() [ CodeMode = call ]
{
Tag^Routine
}
where “Tag^Routine” specifies a tag name within a routine.
6.7.4 Method Generators
A method generator is actually a small program that is invoked by the Class Compiler during
class compilation. Its output is the actual runtime implementation of the method. Method
generators provide a means of inheriting methods that can produce high performance, specialized
code that is customized to the needs of the inheriting class or property. Within the Caché
library method generators are used extensively by the data type and storage classes.
For details refer to the Method Generators chapter.
44 Using Caché Objects

7
Properties
Properties are the class members that define the state of an object. The manner in which you
can access and manipulate the values of an object's properties depends on the object's class
definition. Formally, there are two kinds of properties:
• Attributes, which hold values
• Relationships, which hold associations between objects
Within Caché, attribute properties are simply referred to as “properties” while relationship
properties are referred to as “relationships.”
Many object languages such as Java and C++ do not have true properties, but rather private
variables manipulated by public accessor methods. In Caché, properties are different than
variables. There is a rich model for properties in which:
• Properties can be literal values, collections of literal values, streams, references to persistent
objects or embedded objects, or collections of references to persistent objects or
embedded objects.
• Properties automatically have a set of property methods supporting validation and storage.
• Properties can transparently invoke sophisticated translations and other advanced functionality
during data retrieval and storage.
• Properties automatically pull embedded and persistent objects into memory as soon as
they are referenced. This is called “swizzling” (sometimes referred to as “lazy loading”
).
Every property has a name, a type, an optional set of modifying keywords, and an optional
set of parameters for its type. A property name must be unique within its class.
Using Caché Objects 45

Properties
7.1 Property Keywords
You can modify a property definition through the use of one or more property keywords.
Each keyword is optional and has a default value if not explicitly specified.
The available property keywords include:
Calculated
Description
Specifies that the property has no in-memory storage allocated for it when the object
containing it is instantiated. By default, a property is not calculated. Subclasses inherit
the Calculated keyword and cannot override it.
Provides an optional description of the property; Caché does not use this description.
By default properties have no description. Subclasses do not inherit the value of the
Description property keyword.
Final
Specifies that subclasses cannot override the property. By default, properties are not
final. The Final property keyword is inherited by subclasses.
InitialExpression
Private
Required
Specifies an initial value for the property. By default, properties have no initial value.
Subclasses inherit the value of the InitialExpression keyword and can override it.
Specifies that the property is private. By default, properties are not private. Subclasses
inherit the value of the Private keyword and cannot override it.
Specifies that the property's value must be set before it can be stored to disk. By
default, properties are not required. Subclasses inherit the value of the Required
keyword and can override it.
46 Using Caché Objects

Transient
Property Visibility
Specifies that the property is not stored in the database. By default, properties are
not transient. Subclasses inherit the value of the Transient keyword and cannot
override it.
Type
Specifies the name of the class associated with the property, which can be a data type
class, a persistent class, or an embeddable class. By default, the type of a property is
%String. Subclasses inherit the value of the Type keyword.
7.2 Property Visibility
Properties may be specified as being public or private. If they are public, they can be accessed
anywhere. If they are private, they can only be accessed by instance methods of the object
to which they belong.
Note:
Methods which are declared as classmethods do NOT have access to properties
declared to be private, even if they have a reference to an object of the class they are
declared in. Private properties are only accessible from within instance methods of
the class..
In Caché, private properties are always inherited and visible to subclasses of the class that
defines the property. Other languages often call these protected properties.
7.3 Property Behavior
Properties have a number of methods associated with them automatically. These methods are
not inherited via standard inheritance. Rather, they use a special property behavior mechanism
to generate a series of methods for each property.
Each property inherits a set of methods from two places:
• A %Property class that provides certain built-in behavior, such as Get, Set, and validation
code.
• The data type class of the property's data type, if it is a data type property. Many of these
methods are method generators.
Using Caché Objects 47

Properties
Property Behavior
The property behavior classes are system classes. You cannot specify or modify property
behavior.
For example, if we define a class Person with three properties:
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{
Property Name As %String;
Property Age As %Integer;
Property DOB As %Date;
}
The compiled Person class has a set of methods automatically generated for each of its
properties. These methods are inherited from the system Property class as well as the data
type class associated with the property. The names of these generated methods are the property
name concatenated with the name of the method from the inherited class. For example, some
of the methods associated with the DOB property are:
Set x = person.DOBIsValid(person.DOB)
Write person.DOBLogicalToDisplay(person.DOB)
where IsValid is a method of the property class and LogicalToDisplay is a method of the
%Date data type class.
48 Using Caché Objects

Property Accessors
7.4 Property Accessors
The Caché dot syntax for referring to properties is an interface for a set of accessor methods
to retrieve and set values. For each property, whenever the code refers to oref.Prop (where
oref is an object and Prop is a property), it is executed as if a system-supplied PropGet or
PropSet method were invoked. For example:
Set person.DOB = x
acts as if the following method was called:
Do person.DOBSet(x)
while:
Write person.Name
acts like:
Write person.NameGet()
It is important to point out that in most cases, there are no actual PropGet and PropSet
methods; access for simple properties is implemented directly within the Caché virtual machine
for optimal performance. You can, however, provide PropGet and PropSet methods for a
specific property. In this case, these accessor methods will be invoked at runtime automatically.
Typically, every property has process-private, in-memory storage allocated for it. The systemprovided
property accessors use this storage directly. Note that this object storage is not held
in the local variable symbol table and is not affected by the Kill command.
If you need to access the in-memory stored value of a property from within an instance method
of an object, you can use the following in-memory value syntax:
Set i%Name = "Carl"
This directly sets “Carl” as the in-memory value of the property Name, bypassing the NameSet
accessor (if present).
Using Caché Objects 49

Properties
7.5 Attribute Properties
An attribute property is a value associated with a specific object (as opposed to a relationship
property which relates two or more objects). Such properties typically represent the state of
a specific object instance.
A property's type is determined by the class associated with the property (or by a keyword
in the case of collection and multidimensional properties). By default, properties use the
%String data type.
There are several types of attribute properties, including:
• Data Type Properties
• Object-Valued Properties
• Collection Properties
• Stream Properties
• Multidimensional properties
7.5.1 Data Type Properties
The simplest type of property is a data type property. This is a literal value whose behavior
is controlled by the data type class associated with the property.
For example, a class can define a Count property using the %Integer data type:
Property Count As %Integer;
Since %Integer is a data type class, Count is a data type property.
You can use data type parameters to place constraints on the allowed values of data type
properties. You can specify values for the data type class parameter as follows:
Property Count As %Integer(MAXVAL = 100);
To set a data type property value equal to the empty string, use code of the form:
Set object.Property = $C(0)
50 Using Caché Objects

Attribute Properties
CAUTION:
Do not set the property equal to the empty string using open- and close-quotes
(""), as this can result in values that are not valid or errors.
This is particularly significant if the application is using an external interface,
such as Java.
7.5.2 Object-Valued Properties
An object-valued property is a reference to another object, either embedded or persistent. In
either case, the value of the property is an OREF while in memory. On disk, a reference to a
persistent object becomes an OID, while an embedded object becomes a single serialized
string containing all of the embedded object's properties.
For instance, if an object-valued property, Doc, is of the type Doctor (where Doctor is either
a persistent object or an embeddable object), the definition of Doc is:
Property Doc As Doctor;
7.5.3 Collection Properties
A collection property is one that contains a group (or collection) of individual elements, all
of the same type. To specify a collection property, place the collection type at the start of the
property definition. Caché supports two kinds of collections, called List and Array collections..
The property type determines the contents of the collection. For example, the following code
defines a Colors property which is a list collection of %String values:
// Property Colors As List Of %String;
Property Colors As List Of %String; // the current syntax
Similarly, Caché supports object collections, as in the following Doctors property which is
an Array of references to Doctor objects:
Property Doctors As Array Of Doctor;
When you create a collection, Caché gives it a set of methods through a collection object.
Caché includes several kinds of collection objects, each one designed to operate on a different
kind of collection:
Collection Objects
Type
Data type
Object (persistent or embedded)
Array property
%ArrayOfDataTypes
%ArrayOfObjects
List property
%ListOfDataTypes
%ListOfObjects
Using Caché Objects 51

Properties
You can manipulate a collection property using the methods of the collection object associated
with it. For example, you can perform operations on the Colors property defined earlier, using
the methods provided by the %ListOfDataTypes class:
Do obj.Colors.Insert("Red")
Do obj.Colors.Insert("Green")
Do obj.Colors.Insert("Blue")
7.5.4 Stream Properties
Streams are used to create properties containing large (greater than 32K) amounts of character
or binary data. Binary streams contain the same sort of data as type %Binary, and can hold
large binary objects such as pictures. Character streams contain the same sort of data as type
%String, and are intended for storing large amounts of text. Stream data can be stored in either
an external file or a global, depending on how the property is defined. For example, the following
code defines a binary stream stored as a file, and a character stream stored as a global
(the LOCATION parameter is optional):
Property Image As %FileBinaryStream(LOCATION = "C:/Images");
Property Text As %GlobalCharacterStream(LOCATION = "^MyText");
Streams provide numerous methods for manipulating the data they contain. See the Streams
chapter for more detailed information.
7.5.5 Multidimensional Properties
Properties can be marked as being multidimensional. This gives the instance variable associated
to the property all the characteristics of an array node, upon which array operations like
$ORDER could work. For instance:
Property abc [ MultiDimensional ];
Property abc As %String [ MultiDimensional ];
The following are examples of available operations on abc:
Set x = $DATA(obj.abc)
Set x = $DATA(obj.abc(3))
Set x = $GET(obj.abc(3))
Set x = $ORDER(obj.abc("hello",3))
KILL obj.abc
The property behavior and data type classes are not used to generate methods for multidimensional
properties. Thus, a multidimensional property named Kids has no KidsGet, KidsSet,
or KidsLogicalToDisplay methods. There is no validation on setting a property value.
52 Using Caché Objects

Attribute Properties
Multidimensional properties cannot be exposed through ActiveX or Java. Multidimensional
properties cannot be stored in or exposed through SQL tables. Also, multidimensional properties
are transient, unless the application includes code to store their data.
Using Caché Objects 53

8
Class Queries
Class queries provides a tool to look up instances of a class that meet specified criteria. They
allow you to create named SQL statements that are part of a class structure so that applications
can have pre-defined lookups. For example, you can look up instances by some property,
such as by name, or provide a list of instances that meet a particular set of conditions, such
as all the flights from Paris to Madrid.
By creating a class query, you can avoid having to look up a particular object by its internal
ID. Instead, you can create a query that looks based on any class properties that you want.
These can even be specified from user input at runtime.
A class query can be either in SQL or Caché ObjectScript. To create a query, use the Caché
Studio and create one either by hand or using the New Query Wizard.
Class queries are designed for transparent use with the relational aspect of Caché classes. As
stated, they use SQL syntax. When the application invokes the query, it returns values in a
%Library.ResultSet object, which provides robust interface for processing data.
Class queries provide logical comparisons for data values. You can compare whether the
value is greater than, equal to, or less than a certain value and include only the objects with
values that pass the specified test. You can also compare whether the value starts with a certain
string and include these objects in the result set. A query can also perform multiple comparisons.
Because the comparisons support any combination of nested AND and OR operators,
you can require that an object meets one, some, or all of them in order to be added to the
result set.
Using Caché Objects 55

Class Queries
8.1 Query Basics
The process for creating and using a class query is:
1. Define the query. The simplest way to do this is using the New Query Wizard in the
Caché Studio.
2. Invoke the query. This can be using the %New method of the %Library.ResultSet class
within server-based methods; using the Java or ActiveX result set classes that are part of
the Caché Java and ActiveX bindings, respectively; or as a OBDC or JDBC stored procedure.
3. Once the query has returned a %Library.ResultSet object (often known as a result set),
fetch data from it. (Further information on the result set processing is available in the
“Dynamic SQL” chapter of the Using Caché SQL guide.
4. When processing is complete, close the result set.
8.1.1 The Structure of a Class Query
The simplest query is of type %SQLQuery and simply contains an SQL SELECT statement.
Such a query performs all processing for the application. It is of the form:
Query QueryName(Parameter As %String) As %SQLQuery
{
SELECT MyProperty, MyOtherProperty FROM MyClass
WHERE (MyProperty = "Hello" AND MyOtherProperty = :Parameter)
ORDER BY MyProperty
}
You can also create a query of type %Query, which allows the application to perform its own
custom processing. Such a query is of the form:
8.1.2 Query Keywords
You can modify a query definition through the use of one or more query keywords. Each
keyword is optional and has a default value if not explicitly specified. The major query keywords
are:
Description
Provides an optional description of the query; Caché does not use this description.
By default, queries have no description.
56 Using Caché Objects

Query Basics
Final
Specifies that subclasses cannot override the query. By default, queries are not final.
SQLQuery
SQLProc
Specifies the code to execute when the query is run. Use this keyword if the query
uses SQL (that is, is not user-written).
Specifies that the query can also be accessed as an SQL stored procedure. By default,
a query is not projected as a stored procedure.
Type
Specifies whether the query contains SQL or Caché ObjectScript code. By default,
the query contains SQL code.
8.1.3 Creating a Class Query Specification
A query needs to contains information about its contents and the order of the fields returned
for each row of its results. To provide this information, user-written queries include what is
called a specification.
A specification has one or two parameters modifying the query. These parameters are:
• CONTAINID — This optional parameter specifies which field, if any, contains the ID
for a particular row.
• ROWSPEC — This parameter provides information on the names, data types, headings,
and order of the fields in each row of the query's result set.
8.1.3.1 About CONTAINID
CONTAINID should be set to the number of the column returning the ID (1, by default) or
to 0 if no column returns the ID. If you create a query using the New Query Wizard, then
Studio automatically assigns the appropriate value to CONTAINID, based on the order in
that wizard's Columns page.
Note:
Caché does not validate the value of CONTAINID. If you specify a non-valid value
for this parameter, Caché does not throw an error. This means that if your query
processing logic depends on this information, you may experience inconsistencies
if the CONTAINID parameter is set improperly.
Using Caché Objects 57

Class Queries
8.1.3.2 About ROWSPEC
A query's ROWSPEC provides information on the names, data types, headings, and order of
the fields in each row. It is a quoted and comma-separated list of variable names and data
types of the form:
ROWSPEC = "Var1:%Type1,Var2:%Type2[:OptionalDescription]"
The ROWSPEC specifies the order of fields as a comma-separated list. Each field's information
consists of a colon-separated list of its name, its data type (if it is different than the property's
assigned data type), and an optional heading. You can edit a ROWSPEC's code directly, or,
for an existing query, by viewing the query Class Inspector window, expanding the list of
parameters, and using the available dialog box.
The number of elements in the ROWSPEC must match the number of fields in the query.
Otherwise, Caché returns a “Cardinality Mismatch” error.
8.1.3.3 A Class Query Specification Example
The ByName query of the %Sample.Person sample class that comes with Caché has the following
signature:
Query ByName(name As %String = "")
As %SQLQuery(CONTAINID = 1,
ROWSPEC = "ID:%Integer,Name:%String(MAXLEN=30),DOB,SSN",
SELECTMODE = "RUNTIME")
[ SqlName = SP_Sample_By_Name, SqlProc ]
{
SELECT ID, Name, DOB, SSN
FROM Sample.Person
WHERE (Name %STARTSWITH :name)
ORDER BY Name
}
Here, the CONTAINID parameter specifies that the first field is the ID (the default), and the
first field specified in the SELECT statement is, respectively, ID. The ROWSPEC specifies
that the fields are ID (treated as an integer), Name, DOB, and SSN; similarly, the SELECT
statement contains the fields ID, Name, DOB, and SSN, in that order.
8.2 User-Written Class Queries
While simple %SQLQuery queries perform all result set management for you, this is not sufficient
for certain applications. For such situations, Caché allows you to write queries in
58 Using Caché Objects

Caché ObjectScript. These queries are processed using the same %Library.ResultSet interface
as queries written in SQL but are defined differently.
To define a Caché ObjectScript query, specify %Query for the query type and provide necessary
information for the related parameters (ROWSPEC and CONTAINID). For example, if a
Book class has Author and Title properties, you could define an All query (to list all books)
as follows:
Query All() As %Query(CONTAINID = 1, ROWSPEC = "Title:%String,Author:%String")
{
}
The actual query definition contains no other information, as the query processing code is
defined in three class methods that are associated with it. These methods are:
• querynameExecute — This method invokes the query. For queries that use the SELECT
command, this method also prepares the query for subsequent traversal and data retrieval.
• querynameFetch — Calling this method returns a row of the result set; each subsequent
call returns the next row.
• querynameClose — This method performs cleanup operations.
where queryname is the name of the query.
In addition, Caché automatically generates querynameGetInfo and querynameFetchRows
methods from the row specification and querynameFetch method respectively. Your application
does not call any of these methods directly — the %Library.ResultSet object uses them
to process query requests.
8.2.1 The querynameExecute Method
The querynameExecute method provides all of the setup needed to retrieve data. For queries
using SQL code, this typically includes declaring and opening a cursor. The
querynameExecute method returns status information and uses a %Binary variable passed
by reference as its first argument. This argument passes information between the query
methods and contains all information needed by the various query methods.
For example, if a query called ByName has no runtime parameters, the ByNameExecute
method has the following signature:
ClassMethod ByNameExecute(ByRef qHandle As %Binary) As %Status {
// query setup code here
Quit $$$OK
}
User-Written Class Queries
Using Caché Objects 59

Class Queries
If the query takes runtime parameters, they appear on the method argument list after the query
handle. For example, if the ByName query takes a name parameter, its signature is:
ClassMethod ByNameExecute(ByRef qHandle As %Binary, Name As %String)
As %Status
{
// query setup code here
Quit $$$OK
}
8.2.2 The querynameFetch Method
The querynameFetch method fetches a single row of data and formats it into $List format.
(If it is unable to fetch a row, it returns "" in lieu of data.)
If you create the query using the Wizard, it creates a method signature for you. The significant
elements of this signature are:
• The method's first argument, the qHandle variable, is of type %Binary, is defined in
querynameExecute, and is passed by reference.
• The method's second argument, the Row variable, is either a %List of column values
representing the current row being returned and "" if no row is returned. It is passed by
reference.
• The method's third argument, the AtEnd variable, is of type %Integer and indicates that
subsequent calls will not return a valid row. It is passed by reference.
• The method returns status information in a variable of type %Status.
8.2.2.1 The First Argument — The qHandle Variable
The first argument of a querynameFetch method is of type %Binary, is called qHandle, and
is passed by reference. It contains all information from querynameExecute needed by
querynameFetch and passes information from both methods to querynameClose.
8.2.2.2 The Second Argument — The Row Variable
The second argument of a querynameFetch method is of type %List, is called Row, and is
passed by reference. If the querynameFetch method can retrieve the next row's data, it sets
the row data variable to a list containing the active row's data. The value of each field is a
single element in that list. If no more rows can be returned (that is, the query has reached the
end of the rows), then the variable is set to "".
60 Using Caché Objects

The data in Row is the result of executing the query code. Usually, the data in Row is a simple
transformation of a row of the result set. This, however, need not be the case. The code may
perform arbitrary calculations on the result set data and return what it produces in Row. For
example, a call to querynameFetch might return only the first 50 rows of the result set and
convert the names to asterisks for privacy.
8.2.2.3 The Third Argument — The AtEnd Variable
The third argument of a querynameFetch method is of type %Integer, is called AtEnd, and
is passed by reference. If AtEnd equals 1, further calls to querynameFetch will not return
valid rows.
For example, if the ByNameFetch method uses embedded SQL to retrieve data, SQLCODE=100
indicates that no more data is available:
If SQLCODE = 100
{
Set Row = ""
Set AtEnd = 1
}
This is the simplest case, in which reaching the end of the result set causes the method to set
AtEnd to 1. The method's code could alternately perform any processing that its application
requires.
8.2.2.4 Content of the querynameFetch Method
The method code begins by performing tests to determine if it should return any more results.
Usually, if the next fetch should occur, it uses the class query's ROWSPEC specification to
perform processing; it then creates a %List object that is placed in the Row variable. If the
return code from the result set indicates that no more fetches should occur, set the value of
Row to ""; also, set the value of AtEnd to 1.
8.2.2.5 A Sample querynameFetch Signature
Continuing the ByName example, the ByNameFetch method would have the following signature:
ClassMethod ByNameFetch(ByRef qHandle As %Binary,
ByRef Row As %List, ByRef AtEnd As %Integer = 0)
As %Status [ PlaceAfter = ByNameExecute ]
{
// Method code
}
User-Written Class Queries
Using Caché Objects 61

Class Queries
8.2.2.6 A Note on Method Compilation Order
When Studio creates the querynameClose, querynameExecute, and querynameFetch
methods, the querynameFetch and querynameClose methods include syntax of the form:
[ PlaceAfter = querynameExecute ]
The PlaceAfter method keyword ensures proper cursor declaration. The ability to control
compilation order is an advanced feature that should be used with caution. InterSystems does
not recommend general use of this keyword.
8.2.3 The querynameClose Method
The querynameClose method cleans up after data retrieval has finished. Typically, this
includes removing variables from memory and closing cursors. The querynameClose method
returns status information. Its sole argument is the qHandle variable of type %Binary; this is
defined in querynameExecute and is passed by reference.
For example, the signature of a ByNameClose method might be:
ClassMethod ByNameClose(ByRef qHandle As %Binary) As %Status
[ PlaceAfter = ByNameExecute ] {
// query cleanup code here
}
62 Using Caché Objects

9
Indices
Indexes provide a mechanism for optimizing searches across the instances of a persistent
class; they define a specific sorted subset of commonly requested data associated with a class.
They are very helpful in reducing overhead for performance-critical searches.
Indexes automatically span the entire extent of the class in which they are defined. If a Person
class has a subclass Student, all indexes defined in Person contain both Person objects and
Student objects. Indexes defined in the Student class contain only Student objects.
Indexes can be sorted on one or more properties belonging to their class. This allows you a
great deal of specific control of the order in which results are returned. (See the Properties
keyword, below.)
In addition, indexes can store additional data that is frequently requested by queries based
on the sorted properties. By including additional data as part of an index, you can greatly
enhance the performance of the query that uses the index; when the query uses the index to
generate its result set, it can do so without accessing the main data storage facility. (See the
Data keyword below.)
For additional information on indices, refer to the Index chapter within Using Caché SQL.
9.1 Index Keywords
You can modify an index definition through the use of one or more index keywords. Each
keyword is optional and has a default value if not explicitly specified.
The available index keywords include:
Using Caché Objects 63

Indices
Data
Specifies additional properties to store in the index. By default, no additional data is
included.
Description
Extent
Provides an optional description of the index; Caché does not use this description.
By default, indexes have no description.
Specifies that the index identifies which objects belong to the extent of the class.
Extent indexes do not contain properties; they are strictly used to identify members
of the extent. By default, an index is not an extent index. If you are using bitmap
indices, there is no need to define an extent index: a bitmap extent index is automatically
maintained whenever any bitmap index is defined.
IDKey
Specifies a property or set of properties to use as the ID portion of the OID instead
of the default ID. An ID key must have unique values for each object in the class.
These values cannot change over the life of the objects. By default, an index is not
an ID key.
PrimaryKey
Properties
Specifies that this index is reported as the Primary Key to SQL. Any index defined
as a primary key must contain unique values for each object. By default, an index is
not a primary key.
Specifies the property or list of properties to include and sort upon in the index. An
index must include at least one property.
Type
Specifies whether this is a standard index (the default) or a bitmap index.
Unique
Specifies that each object has a unique value for the property or combination of
properties in the index. By default, an index is not constrained to unique values. You
cannot use the unique keyword with a bitmap index.
64 Using Caché Objects

Index Collation
9.2 Index Collation
Each property specified in the Attribute index keyword can also have an optional collation
type. If a collation type is specified for a property, the value of that property for each instance
is transformed in the specified way before the data is sorted and stored in the index. If no
collation is specified then the collation value of the property is used. This value is inherited
from the property's data type.
If the Unique, PrimaryKey, or IDKey index keyword is specified then property collations cannot
be overridden in an index. Furthermore, if IDKey is specified, the collation is always considered
to be EXACT (both in the index and for comparisons and ordering within SQL, for any of
the IDKey components).
For example, a collation transformation, such as SQLUPPER, that performs a conversion to
upper case makes searches using an index case insensitive.
You can override the collation used by a specific index within the index definition:
Index INDEXNAME On PROPERTYNAME As COLLATIONNAME;
where
• INDEXNAME is the name of index
• PROPERTYNAME is the property being indexed
• COLLATIONNAME is the type of collation being used for the index
Different properties can have different collation types. For example, in the following example
the F1 property uses SQLUPPER collation while F2 uses EXACT collation:
Index Index1 On (F1 As SQLUPPER, F2 AS EXACT);
InterSystems recommends the use of the following collation types:
• EXACT — Performs no translation. Not recommended for use if your string data contains
values in "canonical numeric" format (for example '123' or '-.57').
• SQLSTRING — Strips trailing whitespace (spaces, tabs, and so on), and adds one leading
blank space to the beginning of the string. It collates any value containing only whitespace
(spaces, tabs, and so on) as the SQL empty string.
• SQLUPPER — Converts all alphabetic characters to uppercase, strips trailing whitespace
(spaces, tabs, and so on), and adds one leading blank space to the beginning of the string.
Using Caché Objects 65

Indices
It collates any value containing only whitespace (spaces, tabs, and so on) as the SQL
empty string.
There are also a set of legacy collation types. These are not recommended for use with new
code, as they are provide continued support for legacy systems. They are:
• ALPHAUP — Removes all punctuation characters except question marks ( “” ) and
commas ( “,” ), and translates all the lowercase letters to uppercase. Used mostly for
mapping legacy globals.
• MINUS — Makes the value numeric and changes its sign.
• PLUS — Makes the value numeric.
• SPACE — Translates the value into a string. Replaced by SQLSTRING.
• STRING — Converts a logical value to upper case, strips all punctuation and white space
(except for commas), and adds one leading blank space to the beginning of the string. It
collates any value containing only whitespace (spaces, tabs, and so on) as the SQL empty
string. Replaced by SQLUPPER.
• UPPER — Translates all lower case letters into upper case letters. Used mostly for
mapping legacy globals — replaced by SQLUPPER.
66 Using Caché Objects

10
Using Objects with Caché
ObjectScript
This chapter is a guide to using objects within Caché ObjectScript programs. In addition to
simple method execution, other relevant operations include:
• Creating objects
• Opening objects
• Modifying objects
• Saving objects
• Deleting objects
• Executing queries
10.1 Executing Methods
Most actions, including creating and modifying objects, involves methods. Caché supports
two types of methods, instance methods and class methods. An instance method is invoked
from a specific instance of a class and performs some action related to that instance; a class
method is a method that can be invoked whether or not an object of its class is in memory.
Using Caché Objects 67

Using Objects with Caché ObjectScript
10.1.1 About Return Values
Some methods return a value when executed; others do not. If a method has a return value
and your application does not need it, you can invoke it using the syntax for methods that do
not return a value. To invoke a method without checking its return value, use the Do command;
to invoke a method and check use the Set command. Examples of invoking instance methods
each way appear in the section Executing Instance Methods; examples of invoking class
methods each way appear in the section Executing Class Methods.
10.1.2 Executing Instance Methods
To execute a instance method, you must first create (or open from the database) an instance
of an object.
To execute an instance method, use syntax similar to either of the following lines of code:
Do oref.MethodName(arglist)
Set value = oref.MethodName(arglist)
where oref is a reference to the relevant object that is already in memory (see the section
“Referring to an Object—OREFs and OIDs” in the chapter on the Caché object model for
more information on OREFs), MethodName is the name of the method to execute, and arglist
is the list of arguments passed to the method. value, in the second line of code, is a local
variable that receives the return value of the method.
For example, to execute the Admit method of a Patient object use the following code:
Do pat.Admit()
where pat is the OREF of the desired Patient object.
Similarly, to execute the SearchMedicalHistory method of a Patient object use the following
code:
Set result = pat.SearchMedicalHistory("MUMPS")
where pat is the OREF of the desired Patient object and result holds the value returned by
SearchMedicalHistory.
68 Using Caché Objects

Executing Methods
10.1.3 Executing Class Methods
You can execute a class method without having an object instance. You can also execute a
class method from a method of the same class. In this case, you can invoke the method as
you would an instance method.
To execute a class method, use the following syntax:
Do ##class(Classname).MethodName(arglist)
Set value = ##class(Classname).MethodName(arglist)
where classname is the name of the class with the relevant method,MethodName is the name
of the method to execute, and arglist is the list of arguments passed to the method. value, in
the second line of code, is a local variable that receives the return value of the method. The
class name may contain a package name; if omitted, the class compiler determines the correct
package name to use (this name resolution is explained in the Packages chapter).
For example, you can execute the PurgeAll method of the ReportCard class:
Do ##class(ReportCard).PurgeAll()
Or you can use a fully-qualified class name:
Do ##class(MyApp.ReportCard).PurgeAll()
Similarly, you can execute the Exists method of the %File class (which determines if a file
exists) using the following code:
Set exists = ##class(%File).Exists("\temp\file.txt")
where exists is a true (1) or false (0) value.
10.1.4 Executing Methods Using In-Memory Instances
If an instance of the class is in memory, you can execute a class or instance method using the
syntax that appears in either of the following lines of code:
Do oref.MethodName(arglist)
Set value = oref.MethodName(arglist)
where oref is the OREF of the relevant object, MethodName is the name of the method to
execute, and arglist is the list of arguments passed to the method. value, in the second line
of code, is a local variable that receives the return value of the method.
For example, you can also execute the PurgeAll instance method of the ReportCard class
using this syntax:
Using Caché Objects 69

Using Objects with Caché ObjectScript
Do rc.PurgeAll()
where rc is the OREF of a ReportCard object.
Similarly, you can execute the Exists class method of the %File class using the following
code:
Set exists = file.Exists("\temp\file.txt")
where exists is the return value and file is the OREF of any %File object.
10.1.5 Error Conditions
When invoking a class or instance method, a runtime error can occur under the following
conditions:
• If you attempt to invoke a private method from outside of the object (that is, not from
one of its other methods).
• If you invoke a method that is not defined for a class or an object instance.
• If you attempt to invoke a method for a class does not exist.
10.2 Creating New Objects
The general syntax for creating new object instances is to use the class method %New:
Set oref = ##class(Classname).%New()
where oref is the OREF of the new object and Classname is the name of the class to create.
Classname is case sensitive and may contain a package name.
For example, to create a new Person object, use the following code:
Set person = ##class(MyApp.Person).%New()
where person is the OREF of the new Person object.
You can pass an optional argument to the %New method. If present, this argument is passed
to the object's %OnNew method. The use of this argument depends on the implementation
of the specific class you are using.
70 Using Caché Objects

Opening Objects
10.3 Opening Objects
You can open an already-existing persistent object using the following syntax:
Set oref = ##class(Classname).%OpenId(id)
where oref is the OREF of the opened object, Classname is its class, and id is the object
identifier associated with the object you want to open. Classname is case sensitive.
For example, to open a Sample.Person object with ID 22, use the following code:
Set person = ##class(Sample.Person).%OpenId(22)
Write person.Name,!
where person is the new OREF of the Person object.
Alternately, you can open an object using its full OID value:
Set oref = ##class(Classname).%Open(oid)
where oref is the OREF of the opened object, Classname is its class, and oid is the complete
OID.
Typically, an application will use the %OpenId method.
Once you have opened an object, you can then view or modify its properties using methods
as described in the section “Executing Methods.”
10.4 Modifying Objects
Along with its methods, an object has properties, which define its state. Most properties hold
values, such as a person's name or date of birth; there are also properties called relationships,
which hold associations between objects.
The general syntax for modifying the state of a property (that is, the data that defines its value)
of an object is:
Set oref.PropertyName = value
where oref is the OREF of the specific object, PropertyName is the name of the property to
associate the data with, and value is the actual data.For example, to assign a value to the
Name property of a Person object, use the following code:
Using Caché Objects 71

Using Objects with Caché ObjectScript
Set person.Name = "Doe,Jane"
where person is the OREF of the Person object and “Doe,Jane” is the name you want to
assign to that person.
This general syntax works for any data type property. There is special syntax, described in
the sections below, for:
• reference properties
• embedded object properties
• collections–list properties and array properties
• streams
10.4.1 Modifying Reference Properties
The data stored in a reference property exists as an independent object that can be instantiated
separately from the object containing the reference. To establish the link between the two
objects, the referenced object must be associated with the other object's reference property
through a Caché ObjectScript call (see below). Once this link exists, you can either modify
the referenced object directly or use cascading dot syntax.
10.4.1.1 Associating an Object with a Reference Property
There are two ways to associate an object with a reference property: if the object is in memory,
you can use its OREF, or, if it exists on disk, you can use its object identifier (ID).
For a referenced object in memory, the syntax is:
Set oref.PropertyName = RefOref
where oref is the OREF of the specific object, PropertyName is the name of the property to
associate the data with, and RefOref is OREF of the referenced object. For example, to assign
a particular Person object as the owner in a Car object, use the following code:
Set car.Owner = person
where car is the OREF of the Car object and person is the OREF of the Person object.
If the referenced object has been stored to disk and has an ID value, you can use the following
syntax:
Do oref.PropertyNameSetObjectId(RefId)
72 Using Caché Objects

where oref is the OREF of the specific object, PropertyName is the name of the property to
associate the data with, and RefId is the ID of the referenced object. For every reference
property there are SetObject (using OID value) and SetObjectId (using ID value) methods.
For example, to assign a particular saved Person object as the owner in a Car object, use the
following code:
Do car.OwnerSetObjectId(PersonId)
where car is the OREF of the Car object and PersonId is the ID of the saved Person object.
10.4.1.2 Modifying Referenced Objects Using Cascading Dot Syntax
Once an object is associated with the reference, the properties within that object can be populated
or modified using cascading dot syntax as follows:
Set oref.PropertyName.RefPropertyName = value
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the reference property, RefPropertyName is the name of a data type property within
the referenced object to associate the data with, and value is the actual data. For example, to
set the value of the Name property of a Car object' s Owner property, use the following code:
Set car.Owner.Name = "Doe,Jane"
where car is the OREF of the Car object and “Doe,Jane” is the desired name.
If any of the values referred to within a cascading dot syntax expression is null (""), then the
entire expression evaluates to null. For example:
Set car.Owner = ""
Write car.Owner.Name // prints ""
Modifying Objects
10.4.2 Modifying Embedded Object Properties
The data stored in an embedded object property exists as part of a separate object in memory
but can only be stored as data embedded within a separate, persistent object. There are two
ways to modifying an embedded object property:
• Instantiate a new instance of the embedded object and associate that instance with the
embedded object property.
• Directly create and populate the embedded object property using cascading dot syntax.
Using Caché Objects 73

Using Objects with Caché ObjectScript
10.4.2.1 Associating an Object with an Embedded Object Property
One way to create an embedded object and populate its properties is to:
1. Instantiate a new instance of the embedded object using the class' %New method.
2. Associate the embedded object's OREF with a container object's property using the following
syntax:
Set oref.PropertyName = EmbeddedOref
where oref is the OREF of the specific object to associate the data with, PropertyName
is the name of the embedded object property, and EmbeddedOref is the OREF of the
object to embed.
3. Populate its properties using the general syntax for setting values.
Note:
Note that you can populate any of an object's properties before associating it with
its container object.
To instantiate a new instance of the embedded object, use its class' method for creating a new
method. For classes that inherit from %Persistent, this is a %New class method. For example,
to create a new Address object, use the following command:
Set address = ##class(Address).%New()
You can then associate it with the Home property of a Person object, use the following code:
Set person.Home = address
where address is the OREF of the new Address object and person is the OREF of the Person
object.
Setting the values for the embedded object's properties then requires only the basic syntax,
such as:
Set person.Home.State = "MA"
10.4.2.2 Modifying Embedded Objects Using Cascading Dot Syntax
You can also set the properties of the embedded object without explicitly instantiating it:
Set oref.PropertyName.EmbPropertyName = value
where oref is the OREF of the specific object to associate the data with,PropertyName is the
name of the embedded object property,EmbPropertyName is the name of the property within
the embedded object to associate the data with, and value is the actual data.
74 Using Caché Objects

For example, to populate the Home property of a Person object use the following code:
Set person.Home.Street = "One Memorial Drive"
Set person.Home.City = "Cambridge"
Set person.Home.State = "MA"
Set person.Home.Zip = 02142
Modifying Objects
where person is the OREF of the Person object and their home address is “One Memorial
Drive, Cambridge, MA 02142” .
Note:
Unlike reference properties, embedded object properties do not have to be associated
with an object before using cascading dot syntax to set property values. This code
works even if no object has been associated with the embedded object property.
10.4.3 Modifying List Properties
Lists are ordered collections of information. Each list element is identified by its position
(slot) in the list. You can set the value of a slot's data or insert data at a slot. If you set a new
value for a slot, that value is stored in the list. If you set the value for an already-existing slot,
the new data overwrites the previous data and the slot assignments are not modified. If you
insert data at an already-existing slot, the new list item increments the slot number of all
subsequent slots. (Inserting a new item in the second slot slides the data currently in the second
slot to the third slot, the object currently in the third slot to the fourth slot, and so on.)
There are two types of list properties: lists of data types and lists of objects. Lists of objects
can contain either embedded or persistent objects. These lists are populated in similar but
slightly different ways.
10.4.3.1 Populating Lists of Data Types
You can add data to the end of the list using the following syntax:
Do oref.PropertyName.Insert(data)
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the list property, and data is the actual data. For example, you can add the value
“yellow” to the end of a list of a person's favorite colors by using the following code:
Do person.FavoriteColors.Insert("yellow")
where person is the OREF of the Person object.
You can modify data at slot n using the following syntax:
Do oref.PropertyName.SetAt(data,n)
Using Caché Objects 75

Using Objects with Caché ObjectScript
where oref is the OREF of the specific object to associate the data with,PropertyName is the
name of the list property, and data is the actual data. For example, you can change a person's
favorite colors from “red” , “blue” , and “green” to “red” , “yellow” , and “green” using
the following code:
Do person.FavoriteColors.SetAt("yellow",2)
where person is the OREF of the Person object.
You can insert data into slot n using the following syntax:
Do oref.PropertyName.InsertAt(data,n)
where oref is the OREF of the specific object to associate the data with,PropertyName is the
name of the list property, and data is the actual data. Again, insert a new list item increments
the value of all previously-existing list items. For example, you can change a person's favorite
colors from “red” , “blue” , and “green” to “red” , “yellow” , “blue” , and “green” using
the following code:
Do person.FavoriteColors.InsertAt("yellow",2)
where person is the OREF of the Person object.
10.4.3.2 Populating Lists of Embedded Objects
You can populate a list of objects in several ways. You can create a new object, populate it,
then add it to the end of the list using the following syntax:
Do oref.PropertyName.Insert(ItemOref)
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the list property, and ItemOref is the OREF of the object. For example, you can add
a new vaccination record to a Patient object using the following code:
Do pat.Vaccination.Insert(vac)
where pat is the OREF of the Patient object and vac is the OREF of the Vaccination object.
You can create a new object, populate it, then change an existing slot n using the following
syntax:
Do oref.PropertyName.SetAt(ItemOref,n)
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the list property, and ItemOref is the OREF of the object. For example, you can
76 Using Caché Objects

change the second vaccination record associated with a Patient object using the following
code:
Do pat.Vaccination.SetAt(vac,2)
where pat is the OREF of the Patient object and vac is the OREF of the new Vaccination
object for slot 2.
You can create a new object, populate it, then insert it into slotnusing the following syntax:
Do oref.PropertyName.InsertAt(ItemOref,n)
where oref is the OREF of the specific object to associate the data with,PropertyName is the
name of the list property, and ItemOref is the OREF of the object. Again, insert a new list
item increments the value of all previously-existing list items. For example, you can add a
new vaccination record in the third slot of a Vaccination list of a Patient object using the
following code:
Do pat.Vaccination.InsertAt(vac,3)
where pat is the OREF of the Patient object and vac is the OREF of the Vaccination object.
10.4.3.3 Populating Lists of Persistent Objects
All of the syntax described for populating lists of embedded objects also applies for lists of
persistent objects if the objects are in memory. In addition, you can populate lists of persistent
objects with objects that are not in memory.
You can populate a list of objects in several ways. You can add an object to the end of the
list using the following syntax:
Do oref.PropertyName.InsertObject(itemoid)
where oref is the OREF of the specific object to associate the data with,PropertyName is the
name of the list property, and itemoid is the OID of the object. For example, you can add a
new dog to the list of pets owned by a person using the following code:
Do per.Pets.InsertObject(DogOid)
where per is the OREF of the Person object and DogOid is the OID of the Dog object.
You can add an object to slot n using the following syntax:
Do oref.PropertyName.SetObjectAt(ItemOid,n)
Modifying Objects
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the list property, and ItemOid is the OID of the object. For example, you can change
Using Caché Objects 77

Using Objects with Caché ObjectScript
the pet in the third slot in the list of pets owned by a person to a new dog using the following
code:
Do per.Pets.SetObjectAt(DogOid,3)
where per is the OREF of the Person object and DogOid is the OID of the Dog object.
You can insert an object into slot n using the following syntax:
Do oref.PropertyName.InsertObjectAt(ItemOid,n)
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the list property, and ItemOid is the OID of the object. Again, insert a new list item
increments the value of all previously-existing list items. For example, you can add a new
dog to the beginning of the list of pets owned by a person using the following code:
Do per.Pets.InsertObject(DogOid,1)
where per is the OREF of the Person object and DogOid is the OID of the Dog object.
10.4.3.4 Modifying Properties of Objects in Lists
Once an object has been associated with a particular slot, you can modify its properties as
follows:
Set oref.PropertyName.GetAt(n).ListPropertyName = data
where oref is the OREF of the object containing the list; PropertyName is the name of the
list property; the GetAt method finds and returns the value of the element specified by n; n
is the slot in the list containing the object to update; ListPropertyName is the property to
update; and data is the actual data to associate with the property.
For example, to set the name of a person' s second pet, use the following code:
Set per.Pets.GetAt(2).Name = "Rover"
where per is the OREF of the Person object and Rover is the name of the pet.
10.4.4 Modfiying Array Properties
Arrays are unordered collections of information (unlike lists, which are ordered). An array
consists of one or more name-value pairs, where the name of the element serves as a key and
the value is data associated with that key. There is no syntactic difference between adding a
new element and changing the data contained in an existing element.
78 Using Caché Objects

There are two types of array properties: arrays of data types and arrays of objects. Arrays of
objects can contain either embedded or persistent objects. These arrays are populated in
similar but slightly different ways.
10.4.4.1 Populating Arrays of Data Types
To add an element to an array of data types use the following syntax:
Do oref.PropertyName.SetAt(data,key)
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the list property, data is the actual data, and key is the key associated with the new
element.
For example, to add a new color to an array of RGB values accessed by color name in a
Palette object, use the following code:
Do palette.Colors.SetAt("255,0,0","red")
where palette is the OREF containing the array, Colors is the name of the array property, and
“red” is the key to access the value “255,0,0” .
10.4.4.2 Populating Arrays of Embedded Objects
To add an element to an array of embedded objects, create the new object, populate it, then
use the following syntax to add the object to the array:
Do oref.PropertyName.SetAt(ElementOref,key)
where oref is the OREF of the specific object to associate the data with,PropertyName is the
name of the list property,ElementOref is the OREF of the new element, and key is the key
associated with the new element. For example, to add a vaccination record accessed by date
to a Vaccination array in a Patient object, use the following code:
Do pat.Vaccination.SetAt(vac,"04/08/99")
where pat is the OREF of the Patient object and “04/08/99” is the key to access the Vaccination
object with the OREFvac.
10.4.4.3 Populating Arrays of Persistent Objects
Modifying Objects
The syntax described for populating arrays of embedded objects also applies to arrays of
persistent objects, if the objects are already in memory. In addition, you can populate arrays
of persistent objects with objects that are not in memory. Use the following syntax to add the
object to the array:
Using Caché Objects 79

Using Objects with Caché ObjectScript
Do oref.PropertyName.SetObjectAt(ElementOid,key)
where oref is the OREF of the specific object to associate the data with, PropertyName is the
name of the list property, ElementOid is the OID of the new element, and key is the key
associated with the new element. For example, to add a dog accessed by name to an array of
pets in a Person object, use the following code:
Do per.Pets.SetObjectAt(DogOid,"Rover")
where per is the OREF of the Person object and “Rover” is the key used to access the dog
with the OIDDogOid.
10.4.4.4 Modifying Properties of Objects in Arrays
Once an object has been added to an array, you can modify its properties as follows:
Set oref.PropertyName.GetAt(key).ArrayPropertyName = data
where oref is the OREF of the object containing the list, PropertyName is the name of the
array property, key identifies the object to update, ArrayPropertyName is the property to
update, and data is the actual data associated with the property. For example, to set the type
of Vaccination given to a patient on 02/23/98, use the following code:
Set pat.Vaccination.GetAt("02/23/98").Type = "Polio"
where pat is the OREF of the Patient object given a Polio vaccination on 2/23/98.
10.4.5 Modifying Stream Properties
To populate a stream property, use the following syntax:
Do oref.PropertyName.Write(data)
where oref is the OREF of the object containing the stream, PropertyName is the name of
the stream property, Write is a method of the Stream class, and data is the actual data associated
with the property. For example, to add a paragraph to a Note property of a Visit object,
use the following code:
Do visit.Note.Write(note)
where visit is the OREF of the Visit object and note is the data entered by the doctor at the
time of the visit.
80 Using Caché Objects

Saving Objects
10.5 Saving Objects
You can save any persistent object using the following syntax:
Do oref.%Save()
where oref is the object reference of the object to save.
The %Save method returns a status code which you can examine to determine the success
or failure of the save:
Set sc=oref.%Save()
where sc is the status code returned by %Save and oref is the object reference of the object
to save.
The $$$ISOK macro returns 1 if the save was successful and 0 if it failed. Alternately, the
$$$ISERR macro returns 1 if the save failed and 0 if the save was successful.
If the save failed, the DisplayError^%apiOBJ call in the Caché Object Utility Library displays
the text of the error message.
The following syntax saves the object represented by oref and display any error messages if
the save fails:
Set sc = oref.%Save()
If $$$ISERR(sc) {
Do $System.Status.DisplayError(sc)
}
For example, the following code saves a Person object with OREFper and displays any errors
occurring during the save:
Set sc = per.%Save()
If $$$ISERR(sc) {
Do $System.Status.DisplayError(sc)
}
10.6 Deleting Objects
You can either delete a single object or all objects within an extent.
Using Caché Objects 81

Using Objects with Caché ObjectScript
10.6.1 Deleting a Single Object
To delete an object from the database, use the %DeleteId method, which gives you the option
of preserving error information generated during the deletion:
Do ##class(Classname).%DeleteId(id)
Set sc = ##class(Classname).%DeleteId(id)
where classname is the class of the object to delete and id is the ID of the object to delete.
sc, in the second line of code, is a local variable where the method can return a status code
containing error information. For example, to delete an instance of Sample.Person object
from disk, use the following code:
Set sc = ##class(Sample.Person).%DeleteId(id)
where id is the ID of the Sample.Person object to delete and sc is the variable for status/error
information.
Alternately, you can delete an object using its OID using either syntax below:
Do ##class(Classname).%Delete(oid)
Set sc = ##class(Classname).%Delete(oid)
where classname is the class of the object to delete, oid is the OID of the object to delete,
and sc receives a status code.
For information on IDs, OIDs, and OREFs, see the section “Referring to an Object — OREF,
OID, and ID” in the chapter “The Caché Object Model.”
Note:
Deleting an object does not remove any instances of that object from memory. If an
object in memory is deleted, the last saved version is removed from the disk. The
object is not permanently destroyed until the in-memory version is closed without
being saved.
10.6.2 Deleting All Objects in an Extent
You can delete all instances of a class and its subclasses using the %DeleteExtent method,
which gives you the option of preserving error information generated during the deletion:
Do ##class(Classname).%DeleteExtent()
Set sc = ##class(Classname).%DeleteExtent()
where Classname is the name of the root class of the extent to delete. sc, in the second line
of code, is a local variable where the method can return a status code containing error infor-
82 Using Caché Objects

mation. Again, this method deletes all the instances of the specified class, as well as all
instances of its subclasses.
For example, to delete all Person objects (including all instances of subclasses of Person)
use the following code:
Do ##class(Person).%DeleteExtent()
The %DeleteExtent method will execute any %OnDelete callback methods, if present, for
each object it deletes.
You can also delete all instances of a class and its subclasses using the faster, but dangerous,
%KillExtent method:
Do ##class(Classname).%KillExtent()
Executing Queries
The %KillExtent method immediate kills all data associated with a class extent; no callbacks
are executed and no referential actions are performed. You should only use the %KillExtent
method on developmental systems on which you have no real data.
10.7 Executing Queries
Caché provides %ResultSet objects for executing queries and processing the results.
This involves several steps:
1. Preparing the query
2. Executing the query
3. Processing the query results
4. Closing the query
10.7.1 Query Metadata Methods
To use a query, associate it with a %ResultSet object and you can then manipulate in a number
of ways. The methods available for these operations are:
• ContainsId checks if the query returns object ID values. It returns an integer value
specifying the column number of the ID, if there is one; otherwise, it returns 0.
• GetParamCount returns an integer specifying the number of arguments that the query
takes.
Using Caché Objects 83

Using Objects with Caché ObjectScript
• GetParamName(n) returns a string specifying the name of the nth argument of the query.
• GetColumnCount returns an integer specifying the number of columns that the query
returns.
• GetColumnName(n) returns a string specifying the name of the nth column (field).
• GetColumnHeading(n) returns a string specifying the heading of the nth column (field).
10.7.2 Preparing Queries for Execution
To run a pre-defined class query, begin by instantiating a %ResultSet object as follows:
Set rset = ##class(%ResultSet).%New()
where rset is the OREF of the new %ResultSet object.
Having instantiated the %ResultSet object, the next task is to associate it with a particular
query in a particular class:
Set rset.ClassName = class
Set rset.QueryName = query
where rset is the OREF of the %ResultSet object, class is the name of the class containing
the query, and query is the name of the query to execute.
For example:
Set rset = ##class(%ResultSet).%New()
Set rset.ClassName = "Sample.Person"
Set rset.QueryName = "ByName"
Do rset.Execute()
While (rset.Next(.sc)) // go to the next row of the result set
{
If ($SYSTEM.Status.IsOK(sc)) // check if this succeeded without errors
{
Write rset.Data("Name"),! // perform busines logic
}
Else // if there was an error, break out of the While loop
{
Quit
}
}
If $SYSTEM.Status.IsError(sc) // if there was an error, process that
{
// perform error processing
}
You can also use the %ResultSet object to prepare a dynamic SQL statement using the Prepare
method:
84 Using Caché Objects

Set rset = ##class(%ResultSet).%New()
Do rset.Prepare("SELECT Name FROM Sample.Person WHERE Name %STARTSWITH 'A'")
Do rset.Execute()
While (rset.Next(.sc)) // go to the next row of the result set
{
If ($SYSTEM.Status.IsOK(sc)) // check if this succeeded without errors
{
Write rset.Data("Name"),! // perform busines logic
}
Else // if there was an error, break out of the While loop
{
Quit
}
}
If $SYSTEM.Status.IsError(sc) // if there was an error, process that
{
// perform error processing
}
Executing Queries
10.7.3 Executing Queries
To execute a query, use the following syntax:
Do rset.Execute(arglist)
where rset is the OREF of the %ResultSet object and arglist is a comma-delimited list of
arguments being passed to the query.
10.7.4 Processing Query Results
To access the first row of data, use the following syntax:
Do rset.Next()
where rset is the OREF of the %ResultSet object.
The Next method advances the Result Set cursor to the next row of the Result Set. It returns
0 when the cursor reaches the end of the Result Set (or if there is no data within the Result
Set). The following code checks if the result set has data and exits the method if it has no
data:
If ('rset.Next()) {
Quit
}
You can retrieve a column value for the current row using the Data property of the %ResultSet
object. Data is a multidimensional property subscripted by column name (You must make
sure that your query does not define two columns with the same name):
Using Caché Objects 85

Using Objects with Caché ObjectScript
Set code = rset.Data("Code")
You can also read data stored in the current row by specifying the column number as follows:
Set data = rset.GetData(n)
where data contains the data stored in column n.
Alternately, you can read data for a specific column name by using the GetDataByName
method:
Set data = rset.GetDataByName(fieldname)
where data contains the data in the column named fieldname. This is less efficient than using
the Data property as a method call is slower than a property reference.
Once all of the relevant data has been retrieved from one row, execute the Next method to
move to the next row of data. You can progress through each row, using GetData or
GetDataByName to retrieve the relevant data.
10.7.5 Closing Queries
Once you have processed all a result set's rows, close it as follows:
Do rset.Close()
Set sc = rset.Close()
sc, in the second line of code, is a local variable where the method can return a status code
containing error information.
The Close method releases any resources held by the %ResultSet object. Once the result set
is closed, you can use the %ResultSet object to run and process other queries by changing
the value of the ClassName and QueryName properties.
Calling the Close method is optional; when the %ResultSet object is destroyed (goes out of
scope) it will be automatically closed.
10.7.6 Example of Using a Class Query
The following code shows how to use a %ResultSet object to execute a class query and process
the results:
86 Using Caché Objects

Executing Queries
// Create a Result object for the Sample.Person:ByName query
Set rset = ##class(%ResultSet).%New("Sample.Person:ByName")
Set columns = rset.GetColumnCount()
// Execute the query
Set sc = rset.Execute("A")
// Now fetch the results
While (rset.Next()) {
Write "------------------------",!
// loop over columns
For col = 1:1:columns {
Write rset.GetColumnName(col),": "
Write rset.GetData(col),!
}
}
Do rset.Close()
You can also use the ActiveX and Java versions of the %ResultSet object to perform the same
operation from an ActiveX or Java applications.
Using Caché Objects 87

11
Data Types
Caché supports a number of data types for variables, where each data type is itself a class.
Each data type class represents a specific literal type, such as a string or integer. These data
type classes determine the behavior of both object properties and fields in relational tables.
Caché also allows you to create your own data types.
Data type classes provide the following features:
• They provide for SQL, ODBC, ActiveX, and Java interoperability by providing SQL
logical operation, client data type, and translation information.
• They provide validation for literal data values, which you can extend or customize by
using data type class parameters.
• They manage the translation of literal data for its stored (on disk), logical (in memory),
and display formats.
Data type classes differ from other classes in a number of ways:
• They cannot be instantiated or stored independently.
• They cannot contain properties.
• They support a specific set of methods (called the data type interface), which is described
below.
Using Caché Objects 89

Data Types
11.1 Available Types
Caché provides a library of the most common data types including strings, integer, floats,
timestamps and so on. These are:
Caché Data Type Classes
Class Name
%Binary
%Boolean
%Currency
%Date
%Float
%Integer
%List
%Name
%Numeric
%Status
%String
%Time
%TimeStamp
Holds
binary data
a boolean value
a currency value
a date
a floating point value
an integer
data in $List format
a name in the form “
Lastname,Firstname”
a numeric values of
varying precision
an error status code
a string
a time value
a value for a time and
date
Analogous SQL Type(s)
BINARY, BINARY VARYING, RAW, VBINARY
N/A
MONEY, SMALLMONEY
DATE
DOUBLE, DOUBLE PRECISION, FLOAT,
REAL
BIT, INT, INTEGER, SMALLINT, TINYINT
N/A
N/A
DEC, DECIMAL, NUMBER, NUMERIC
N/A
CHAR, CHAR VARYING, CHARACTER,
CHARACTER VARYING, NATIONAL CHAR,
NATIONAL CHAR VARYING, NATIONAL
CHARACTER, NATIONAL CHARACTER
VARYING, NATIONAL VARCHAR, NCHAR,
NVARCHAR, VARCHAR, VARCHAR2
TIME
TIMESTAMP
90 Using Caché Objects

Operation
11.2 Operation
This section describes the basic features and functionality of Caché data types.
11.2.1 Using Data Types in Classes
The principal function of data type classes is for specifying the types of properties within a
class. The basic definition format is:
Property City As %String;
Because data types are part of the %Library package, you can simply call them without
explicitly mentioning the package name.
11.2.1.1 Validation Functionality
Any property using a system data type (or a data type derived from a system data type) supports
data validation through a generated method associated with the property. The validation
method has a name of the form PropertyNameIsValidDT; for instance, an Age property of
type %Integer has an associated AgeIsValidDT method. The method checks the validity of
a value specified for the property.
11.2.2 Parameters
Data type classes support various parameters. These perform various actions and vary from
data type to data type. These parameters include:
• COLLATION — Specifies the manner in which property values are transformed for
indexing.
The allowable values for collation are discussed in the SQL Introduction.
• DISPLAYLIST — Used in conjunction with the VALUELIST parameter for enumerated
(multiple-choice) properties. DISPLAYLIST, if not null, represents the display values
for the property corresponding with the logical values listed in VALUELIST. The display
values are returned by the LogicalToDisplay method.
• FORMAT — Specifies the format for the data type's display value. The value of FORMAT
corresponds to the formatting option of the $FNUMBER function, which performs the
formatting.
Using Caché Objects 91

Data Types
• INDEXSUBSCRIPTS — If present, specifies the number of subscripts used by the
property in indices, using a comma as a delimiter in the property value; the %CacheStorage
class uses this number. A value of 2 specifies that the first comma piece of the property
value is stored as the first subscript and the second comma piece of the property value is
stored as the second subscript.
• MAXLEN — Specifies the maximum number of characters the string can contain
• MAXVAL — Specifies the maximum allowed logical value for the data type.
• MINLEN — Specifies the minimum number of characters the string can contain.
• MINVAL — Specifies the minimum allowed logical value for the data type.
• ODBCDELIMITER — Specifies the delimiter character used to construct a %List value
when it is projected via ODBC.
• PATTERN — Specifies a pattern that the string must match. The value of PATTERN
must be a valid Caché pattern-matching expression.
• SCALE — Specifies the number of digits following the decimal point.
• TRUNCATE — Specifies whether to truncate string to MAXLEN characters, where 1
is TRUE and 0 is FALSE.
• VALUELIST — Used for enumerated (multiple-choice) properties. VALUELIST is
either a null string (“”) or a delimiter-separated list (where the delimiter is the first character)
of logical values. If a non-null value is present, then the property is restricted to
values in the list, and the validation code simply checks to see if the value is in the list.
• XSDTYPE — Declares the XSD type used when projecting XML Schemas.
The supported parameters for each of the system data types are:
Supported Parameters for System Data Type Classes
Data Type Class
%Binary
Supported Parameters
MAXLEN, MINLEN
%Boolean
%Currency
%Date
%Float
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE,
VALUELIST, XSDTYPE
92 Using Caché Objects

Operation
Data Type Class
%Integer
%List
%Name
%Numeric
Supported Parameters
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST,
XSDTYPE
ODBCDELIMITER
COLLATION, INDEXSUBSCRIPTS, MAXLEN, XSDTYPE
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE,
VALUELIST
%Status
%String
%Time
%TimeStamp
COLLATION, DISPLAYLIST, MAXLEN, MINLEN, PATTERN,
TRUNCATE, VALUELIST, XSDTYPE
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST
DISPLAYLIST, MAXVAL, MINVAL, VALUELIST
11.2.3 Keywords
To provide interoperability with client systems, data type classes include the following class
keywords:
• CLIENTDATATYPE — Specifies the Java or ActiveX type used when the data type is
accessed via client applications. See CLIENTDATATYPE for the default for each data
type.
• ODBCTYPE — Specifies the ODBC type used when the data type is accessed via ODBC.
See SQL and ODBC Methods for the default for each data type.
• SQLCATEGORY — Specifies the SQL Category to use for the data type when the Caché
SQL engine performs operations upon it. See SQL and ODBC Methods for the default
for each data type.
11.2.3.1 CLIENTDATATYPE
To use Caché data with any client system (such as Java or ActiveX), the data needs to be in
a form that the client system can understand. To do this, Caché provides the CLIENT-
DATATYPE class keyword, which specifies format information for how Caché projects a
property to the client.
The table below contains a list of CLIENTDATATYPE values and which classes use them:
Using Caché Objects 93

Data Types
CLIENTDATATYPE Values
Value
BINARY
CURRENCY
DATE
DOUBLE
INTEGER
LIST
NUMERIC
VARCHAR
TIME
TIMESTAMP
Used for
%Binary (or any property requiring that there is no Unicode
conversion of data)
%Currency
%Date
%Float
%Boolean, %Integer
%List
%Numeric
%Name, %String
%Time
%TimeStamp
11.2.3.2 SQL and ODBC Methods
Data type classes include a number of methods and class keywords designed to support
interoperability with the Caché SQL relational database, as well as other relational databases.
The OdbcToLogical and LogicalToOdbc methods translate logical data values to and from
values used by the Caché SQL ODBC Interface. The ODBC value must match the ODBC
type specified by the data type class' ODBCTYPE class keyword.
The ODBCTYPE class keyword specifies the ODBC data type used when a property is projected
to ODBC. The definition of the data type class specifies this value. Overriding it prevents
a class from working properly with ODBC.
The following ODBCTYPE values are used for the Caché system data types:
94 Using Caché Objects

Operation
ODBCTYPE Values
Value
BINARY
CURRENCY
DATE
DOUBLE
INTEGER
NUMERIC
TIME
TIMESTAMP
VARCHAR
Caché Data Type
%Binary
%Currency
%Date
%Float
%Integer, %Boolean
%Numeric
%Time
%TimeStamp
%String, %List, %Name
11.2.3.3 The SQLCATEGORY Class Keyword
The SQLCATEGORY class keyword specifies the SQL Category that Caché SQL uses to
perform operations on the value of data of this data type. Operations controlled by the SQL-
CATEGORY include comparison operations (such as greater than, less than, or equal to);
other operations may also use it. The definition of the data type class specifies this value.
Overriding it prevents a class from working properly with SQL.
The following SQLCATEGORY values are used for the Caché system classes:
Using Caché Objects 95

Data Types
SQLCATEGORY Values
Value
CURRENCY
DATE
DOUBLE
INTEGER
NAME
NUMERIC
STRING
TIME
TIMESTAMP
Caché Data Type
%Currency
%Date
%Float
%Integer, %Boolean
%Name
%Numeric
%String, %Binary, %List
%Time
%TimeStamp
11.2.4 Data Formats and Translation Methods
When handling data, Caché uses a number of different formats, depending on the situation.
These have various purposes — such as for displaying data in a human-readable format or
for manipulating data programmatically. Caché data types automatically convert data among
these formats. If you create your own data type that is a subclass of a Caché data type, any
property using your data type automatically includes the methods for converting among the
various formats.
You only need to know about these formats and conversions between them if you are either
creating a data type not based on a system data type or performing non-standard data
manipulation.
The formats are:
• Display — The format in which data can be input and displayed. For instance, a date in
the form of “April 3, 1998” or “23 November, 1977.”
• Logical — The in-memory format of data, which is the format upon which operations
are performed. While dates have the display format described above, their logical format
is as an integer; for the sample dates above, their values in logical format are 57436 and
50000, respectively.
• Storage — The on-disk format of data — the format in which data is stored to the database.
Typically this is identical to the Logical format.
96 Using Caché Objects

• ODBC — The format in which data can be presented via ODBC or JDBC. This format
is used when data is exposed to ODBC/SQL. The available formats correspond to those
defined by ODBC.
If a property uses a system data type (or a data type derived from a system data type), the
property automatically includes methods for translation among the various data formats.
Though you do not use these methods directly, they serve as the basis for a data type's propertyspecific
methods (called property methods). They include:
• DisplayToLogical — converts a variety of display values into appropriate logical values.
• IsValidDT — performs data validation for the value associated with a property. The
method returns 1 as the first character if the value is valid and 0 as the first character if
it is not valid. When validation is enabled, the IsValidDT method is invoked automatically.
• LogicalToDisplay — converts a logical value to a display value.
• LogicalToOdbc — converts a logical value into an ODBC value (optional).
• LogicalToStorage — converts a logical value into a storage value (optional).
• OdbcToLogical — converts a logical value into a storage value (optional).
Enumerated Properties
• StorageToLogical — converts a database storage value into a logical value (optional).
11.3 Enumerated Properties
Properties can support multiple choice values, also known as enumerated values. To create
such a properties, there are two data type class parameters: VALUELIST and DISPLAYLIST.
To specify a list of valid values for a property, use its VALUELIST parameter. The form of
VALUELIST is a delimiter-separated list of logical values, where the delimiter is the first
character. For instance:
Property Color As %String(VALUELIST = ",red,green,blue");
In this example, VALUELIST specifies that valid possible values are “red” , “green” , and
“blue” , with a comma as its delimiter. Similarly,
Property Color As %String(VALUELIST = " red green blue");
specifies the same list, but with a space as its delimiter.
Using Caché Objects 97

Data Types
The property is restricted to values in the list, and the data type validation code simply checks
to see if the value is in the list. If no list is present, there are no special restrictions on values.
DISPLAYLIST is an additional list that, if present, represents the corresponding display values
to be returned by the property's LogicalToDisplay method.
This functionality works by convention: the data type class' LogicalToDisplay and IsValidDT
methods must first check for the presence of these class parameters and include code to process
these lists if present.
98 Using Caché Objects

12
Object Persistence
One of the most important features of Caché Objects is Object Persistence: the ability to store
and retrieve objects within a database.
Within Caché, object persistence is automatic and built-in: you do not need to write any
persistence code; you do not need to provide any object/relational “mapping” ; and you do
not have to bother with middleware and database connectivity tools.
Every persistent object is automatically projected as an SQL table. This is described in the
Objects and SQL chapter.
Caché provides two flavors of object identity that you can use identify persistent objects: ID
and OID. An ID is a simple literal value (by default, an integer) that is unique within a specific
extent of objects (say the set of all Person objects). An OID is more general: it also includes
the object's class name and is unique across a database of objects. In general practice, an
application never needs to use the OID value; the ID value is usually sufficient. Within this
chapter, we will use the ID variant of the various persistence methods (such as %OpenId)
for simplicity.
12.1 The %Persistent Class
Object persistence is provided by the %Persistent class, which defines the methods of the
Persistence Interface; and the Class Compiler, which manages Schema Evolution and SQL
Projection.
To be persistent, two things must be true about a class definition:
Using Caché Objects 99

Object Persistence
1. Its primary (first) superclass must either be %Persistent or some other persistent class,
and,
2. It must specify that its ClassType is persistent.
For example:
Class MyApp.MyClass Extends %Persistent [ClassType = persistent]
{
}
If you omit the ClassType = persistent or if %Persistent (or a subclass) is not the first
class in the superclass list, then your class will not be persistent.
12.2 The Persistence Interface
The %Persistent class defines a set of methods, known as the Persistence Interface, that provides
the means to work with object persistence. Among other things, the Persistence Interface
provides the ability to save objects to the database, load objects from the database, delete
objects, and test for existence. These are described in the following sections.
12.2.1 Saving Objects
To save a persistent object to the database, invoke its %Save method:
Set obj = ##class(MyApp.MyClass).%New()
Set obj.MyValue = 10
Set sc = obj.%Save()
The %Save method returns a %Status value that indicates whether the save operation succeeded
or failed (such as if it has invalid property values or violates a uniqueness constraint).
Calling %Save on an object automatically saves all modified objects that can be “reached”
from the object being saved: that is, all embedded objects, collections, streams, referenced
objects, and relationships involving the object are automatically saved if needed. The entire
save operation is carried out as one transaction: if any object fails to save, then the entire
transaction fails and rolls back (no changes are made to disk; all in-memory object values
are what they were prior to calling %Save).
When an object is saved for the first time, the %Save method automatically assigns it an
Object ID value (the ID is generated using the $Increment function unless the class is using
a user-provided Object ID based on property values using an idkey index) that is used to later
100 Using Caché Objects

find the object within the database. Once assigned, you cannot alter the Object ID value for
a specific object instance (even if it is a user-provided ID).
You can find the Object ID value for an object that has been saved using the %Id method:
// Open person "22"
Set person = ##class(Sample.Person).%OpenId(22)
Write "Object ID: ",person.%Id(),!
In more detail, the %Save method does the following:
The Persistence Interface
1. First it constructs a temporary structure known as a “SaveSet.” The SaveSet is simply
a graph containing references to every object that is reachable from the object being
saved. The purpose of the SaveSet is to make sure that save operations involving complex
sets of related objects are handled as efficiently as possible. The SaveSet also resolves
any save order dependencies among objects.
As each object is added to the SaveSet, its %OnAddToSaveSet callback method is
called, if present.
2. It then visits each object in the SaveSet in order and checks if they are modified (that is,
if any of their property values have been modified since the object was opened or last
saved). If an object has been modified, it will then be saved.
3. Before being saved, each modified object is validated (its property values are tested; its
%OnValidateObject method, if present, is called; and uniqueness constraints are tested);
if the object is valid, the save proceeds. If any object is invalid, then the call to %Save
fails and the current transaction is rolled back.
4. Before and after saving each object, the %OnBeforeSave and %OnAfterSave callback
methods are called, if present.
These callbacks are passed an Insert argument which indicates whether an object is being
inserted (saved for the first time) or updated.
If either of these callback methods fails (returns an error code) then the call to %Save
fails and the current transaction is rolled back.
If the current object is not modified, then %Save does not write it to disk; it returns success
because the object did not need to be saved and, therefore, there is no way that there could
have been a failure to save it. In fact, the return value of %Save indicates that the save
operation either did all that it was asked or it was unable to do as it was asked (and not
specifically whether or not anything was written to disk).
Using Caché Objects 101

Object Persistence
Note:
In a multiprocess environment, an application with improper concurrency controls
can use %Save in a way that results in unexpected behavior. For more information,
see the appendix “Object Concurrency Options.”
12.2.1.1 Saving Objects and Transactions
The %Save method automatically saves all the objects in its SaveSet as a single transaction.
If any of these objects fail to save, then the entire transaction is rolled back.
If you wish to save two or more unrelated objects as a single transaction, then you must
enclose the calls to %Save within an explicit transaction: that is, you must start the transaction
using the TSTART command and end it with the TCOMMIT command.
For example:
// start a transaction
TSTART
// save first object
Set sc = obj1.%Save()
// save second object (if first was save)
If ($$$ISOK(sc)) {
Set sc = obj2.%Save()
}
// if both saves are ok, commit the transaction
If ($$$ISOK(sc)) {
TCOMMIT
}
There are two things to note about this example:
1. The %Save method knows if it being called within an enclosing transaction (because
the system variable, $TLEVEL, will be greater than 0).
2. If any of the %Save methods within the transaction fails, the entire transaction is rolled
back (the TROLLBACK command is invoked). This means that an application must test
every call to %Save within a explicit transaction and if one fails, skip calling %Save on
the other objects and skip invoking the final TCOMMIT command.
If you are saving objects from Java, and wish to save multiple objects within the same transaction
(as in the above example) you can use the transactionStart and transactionCommit
methods of the Java Database class.
12.2.1.2 READONLY Objects
It is possible to define persistent objects that can be opened but not saved or deleted. To do
this set the READONLY parameter for the class to 1:
102 Using Caché Objects

The Persistence Interface
Parameter READONLY = 1;
This is only useful for cases where you have objects that are somehow mapped to preexisting
storage (such as existing globals or an external database). If you call the %Save method on
a READONLY object, it will always return an error code.
12.2.2 Opening Objects
You can open (load an object instance from disk into memory) an object using the %OpenId
method. The %OpenId method takes an ID value as input and returns a reference (OREF)
to an in-memory object or a null value ("") if it cannot find or otherwise open the object.
For example:
// Open person "10"
Set person = ##class(Sample.Person).%OpenId(10)
Write "Person: ",person,!
// should be an object reference
// Open person "-10"
Set person = ##class(Sample.Person).%OpenId(-10)
Write "Person: ",person,!
// should be a null string
Note that in Caché Basic, the OpenId command is equivalent to the %OpenId method:
person = OpenId Sample.Person(1)
PrintLn "Name: " & person.Name
The %OpenId method takes optional second and third arguments. The second argument is
the concurrency level (locking) used to open the object (see below). The third object is a
%Status value, passed by reference, that indicates whether the call succeeded or failed.
The %OpenId method calls the callback method %OnOpen if it is present. Note that the
%OnNew callback is not called when an object instance is opened from the database.
12.2.2.1 Polymorphism and %OpenId
The %OpenId method behaves polymorphically — that is, it may return different types of
objects depending on the ID value it is passed.
For example, the extent (set of) Sample.Person objects includes instances of Sample.Person
as well as instances of Sample.Employee (a subclass of Sample.Person). Calling %OpenId
for the Sample.Person class could return an instance of either Sample.Person or
Sample.Employee depending on what is stored within the database:
Using Caché Objects 103

Object Persistence
// Open person "10"
Set obj = ##class(Sample.Person).%OpenId(10)
Write obj.%ClassName(),!
// Sample.Person
// Open person "110"
Set obj = ##class(Sample.Person).%OpenId(110)
Write obj.%ClassName(),!
// Sample.Employee
Note that the %OpenId method for the Sample.Employee class will not return an object if
we try to open ID 10:
// Open employee "10"
Set obj = ##class(Sample.Employee).%OpenId(10)
Write $IsObject(obj),! // 0
// Open employee "110"
Set obj = ##class(Sample.Employee).%OpenId(110)
Write $IsObject(obj),! // 1
This is because the %OpenId method for the Sample.Employee will only return instances
of Sample.Employee (or its subclasses). In the above example, 10 refers to an instance of
Sample.Person and cannot be opened as a Sample.Employee object.
For more information on polymorphism and persistent objects see the section on Extents.
12.2.2.2 Multiple Calls to %OpenId
If %OpenId is called multiple times within a Caché process for a specific persistent object
ID, only one object instance is created in memory: all subsequent calls to %OpenId will
return a reference to the object already loaded into memory.
This is demonstrated in the following example:
' open and modify Person 1 in memory
personA = OpenId Sample.Person(1)
personA.Name = "Black,Jimmy Carl"
' open Person 1 "again"
personB = OpenId Sample.Person(1)
PrintLn "NameA: " & personA.Name
PrintLn "NameB: " & personB.Name
12.2.2.3 Swizzling
If you open (load into memory) an instance of persistent object, and use a persistent object
it references, then this referenced object is automatically opened. This process is referred to
as swizzling.
104 Using Caché Objects

For example, the following code opens an instance of Sample.Employee object and automatically
(swizzles) opens its related Sample.Company object by referring to it using dot syntax:
// Open employee "101"
Set emp = ##class(Sample.Employee).%OpenId(101)
// Automatically open Sample.Company by referring to it:
Write "Company: ",emp.Company.Name,!
When an object is swizzled, it is opened using the default concurrency value of Atomic (see
next section). If you wish to change the concurrency level of a swizzled object use the
%UpgradeConcurrency and %DowngradeConcurrency methods.
A swizzled object is removed from memory as soon as no objects or variables refer to it.
12.2.2.4 Concurrency
The %OpenId method takes an optional concurrency argument as input. This argument
specifies the concurrency level (type of locks) that should be used to open the object instance.
For more information on the possible object concurrency levels, refer to Object Concurrency.
If the %OpenId method is unable to acquire a lock on an object, it will fail.
You can raise or lower the current concurrency setting for an object using the %Persistent
class' %UpgradeConcurrency and %DowngradeConcurrency methods, respectively.
12.2.2.5 Reloading an Object from Disk
If you wish to reload an in-memory object with the values stored within the database, you
can use the %Reload method provided by the %Persistent class.
// Open person "1"
Set person = ##class(Sample.Person).%OpenId(1)
Write "Original value: ",person.Name,!
// modify the object
Set person.Name = "Black,Jimmy Carl"
Write "Modified value: ",person.Name,!
// Now reload the object from disk
Do person.%Reload()
Write "Reloaded value: ",person.Name,!
12.2.2.6 Reading Stored Values
The Persistence Interface
Suppose you have opened an instance of a persistent object, modified its properties, and then
wish to view the original value stored in the database before saving the object. The easiest
way to do this is to use an SQL statement (SQL is always executed against the database; not
against objects in memory).
Using Caché Objects 105

Object Persistence
For example:
// Open person "1"
Set person = ##class(Sample.Person).%OpenId(1)
Write "Original value: ",person.Name,!
// modify the object
Set person.Name = "Black,Jimmy Carl"
Write "Modified value: ",person.Name,!
// Now see what value is on disk
Set id = person.%Id()
&sql(SELECT Name INTO :name
FROM Sample.Person WHERE %ID = :id)
Write "Disk value: ",name,!
12.2.3 Deleting Objects
The Persistence Interface includes several methods for deleting objects from the database.
12.2.3.1 The %DeleteId Method
The %DeleteId method deletes a an object that is stored within a database:
Set sc = ##class(MyApp.MyClass).%DeleteId(id)
%DeleteId returns a %Status value indicating whether the object was deleted or not.
If present, %DeleteId will call the %OnDelete callback method before deleting the object.
%OnDelete returns a %Status value; if %OnDelete returns an error value, then the object
will not be deleted, the current transaction is rolled back, and %DeleteId returns an error
value.
Note that the %DeleteId method is a class method and has no effect on any object instances
that may be in memory.
12.2.3.2 The %DeleteExtent Method
The %DeleteExtent method deletes every object (and subclass of object) within its extent.
Specifically it iterates the entire extent of objects and then invokes the %DeleteId method
on each instance.
12.2.3.3 The %KillExtent Method
The %KillExtent method directly deletes the globals used to store an extent of objects. It
does not invoke the %DeleteId method and performs no referential integrity actions. This
method is simply intended to serve as a help to developers during the development process.
106 Using Caché Objects

Object Extents
(It is similar to the TRUNCATE TABLE command found in older relational database products).
CAUTION:
%KillExtent is intended for use only in a development environment and
should not be used in a live application. %KillExtent bypasses constraints
and user-implemented callbacks, potentially causing data integrity problems.
12.2.4 Testing if Objects Exist
There are two basic ways with which you can test if a specific object instance is stored within
the database.
The first way is to use the %ExistsId method provided by the %Persistent class. This is a
class method that takes an ID value and returns a true value (1) if the specified object is
present in the database and false (0) otherwise. For example:
Write ##class(Sample.Person).%ExistsId(1),! // should be 1
Write ##class(Sample.Person).%ExistsId(-1),! // should be 0
The other way is to use an SQL statement and test the value of SQLCODE:
&sql(SELECT %ID FROM Sample.Person WHERE %ID = '1')
Write SQLCODE,! // should be 0: success
&sql(SELECT %ID FROM Sample.Person WHERE %ID = '-1')
Write SQLCODE,! // should be 100: not found
12.3 Object Extents
A set of object instances of a similar type (class) stored within the database is referred to as
an extent.
For a single persistent class (with no subclasses), an extent is the same as a table in relational
database terms. For example, consider the persistent class MyApp.MyPerson:
Class MyApp.MyPerson Extends %Persistent [classtype = persistent]
{
Property Name As %String;
}
The set of all instances of MyApp.MyPerson stored within the database is the MyApp.MyPerson
extent. This is equivalent to a MyApp.MyPerson table with a Name column.
Extents become more interesting when we consider subclasses. An object extent includes all
instances of itself and any of its subclasses.
Using Caché Objects 107

Object Persistence
If a persistent class, B, is a subclass of another persistent class, A, then all of the stored
instances of B (as well as subclasses of B) belong to the superclass extent A as well as to the
subextent B.
The top-most class in a hierarchy of persistent classes (that is, the first superclass marked as
persistent) is referred to as a root class and defines the top-level extent. The root class defines
the primary storage used by all objects stored within the extent. If the root class specifies that
its instances will be stored within the global ^MyApp.Data, then all subclasses in this extent
are also stored there. Note that the root class of an extent can be marked as Abstract meaning
that there are no actual instances of this class stored within its extent.
An extent that includes objects of different subtypes is referred to as a multi-class extent.
Note that as far as persistence is concerned only the primary (first) superclass of an object
determines its type and what extent it belongs to.
Suppose we define the following persistent objects:
• MyApp.Person — a persistent class (directly derived from %Persistent).
• MyApp.Teacher — a persistent class derived from MyApp.Person.
• MyApp.Student — a persistent class derived from MyApp.Person.
• MyApp.GradStudent — a persistent class derived from MyApp.Student.
In this case, the root class is MyApp.Person as it is directly derived from %Persistent.
MyApp.Person defines the top-level extent MyApp.Person.
MyApp.Teacher defines the subextent MyApp.Teacher. All instances of MyApp.Teacher belong
the to top-level MyApp.Person extent as well as the MyApp.Teacher subextent.
Similarly, MyApp.Student defines the subextent MyApp.Student. All instances of MyApp.Student,
as well as its subclass MyApp.GradStudent, belong the to top-level MyApp.Person extent as
well as the MyApp.Student subextent.
MyApp.GradStudent is a subclass of MyApp.Student. It defines the subextent
MyApp.GradStudent. All instances of MyApp.GradStudent belong the to top-level MyApp.Person
extent, the MyApp.Student subextent, and the MyApp.GradStudent subextent.
12.3.1 The Extent Query
Every persistent class automatically includes a class query called Extent that provides a set
of all the object ID values within an object extent.
108 Using Caché Objects

For example, the following returns a set of all the object ID values for the Sample.Person
class:
Set rset = ##class(%ResultSet).%New("Sample.Person:Extent")
Do rset.Execute()
While (rset.Next()) {
Write rset.Data("ID"),!
}
The Sample.Person extent include all instances of Sample.Person as well as its subclass
Sample.Employee. If you want to only see the instances of Sample.Employee (and its subclasses)
then use its Extent query:
Set rset = ##class(%ResultSet).%New("Sample.Employee:Extent")
Do rset.Execute()
While (rset.Next()) {
Write rset.Data("ID"),!
}
The Extent query is equivalent to the following SQL query:
SELECT %ID FROM Sample.Person
Storage Definitions and Storage Classes
Note that you cannot rely on the order in which ID values are returned using either of these
method: Caché may determine that it is more efficient to use an index that is ordered using
some other property value to satisfy this request. You can add an ORDER BY %ID clause
to your SQL query if you need to.
12.4 Storage Definitions and Storage Classes
The %Persistent class provides the high-level interface for storing and retrieving objects in
the database. The actual work of storing and loading objects is performed by what is called
a storage class.
Every persistent (and serial) object uses a storage class to generate the actual methods used
to store, load, and delete objects in a database. These internal methods are referred to the
Storage Interface. The Storage Interface includes methods such as %LoadData, %SaveData,
and %DeleteData. Applications never call these methods directly, instead they are called at
the appropriate time by the methods of the Persistence Interface (such as %OpenId and
%Save).
Using Caché Objects 109

Object Persistence
The storage class used by a persistent class is specified by a Storage Definition. A storage
definition contains a set of keywords and values that define a storage class as well as additional
parameters used by the storage interface.
A persistent class may contain more than one storage definition but only one can be active
at a time. The active storage definition is specified using the class' StorageStrategy keyword.
By default, a persistent class has a single storage definition called “Default” .
12.4.1 The %CacheStorage Storage Class
%CacheStorage is the default storage class used by persistent objects. It automatically creates
and maintains a default storage structure for a persistent class.
Whenever you create a new persistent class, it will automatically use the %CacheStorage
storage class. The %CacheStorage class lets you control certain aspects of the storage structure
used for a class by means of the various keywords in the storage definition.
Refer to the Storage Keywords section of the Class Definition Reference for details on the
various storage keywords.
12.4.2 The %CacheSQLStorage Storage Class
The %CacheSQLStorage is a special storage class that uses generated SQL SELECT, INSERT,
UPDATE, and DELETE statements to provide object persistence.
The %CacheSQLStorage is typically used for:
• Mapping objects to preexisting global structures used by older applications.
• Storing objects within an external relational database using the SQL Gateway.
The %CacheSQLStorage is more limited than %CacheStorage. Specifically, it does not
automatically support Schema Evolution or multi-class extents.
12.5 Schema Evolution
The %CacheStorage storage class supports automatic schema evolution.
When you compile a persistent (or serial) class that uses the default %CacheStorage storage
class, the Class Compiler will analyze the properties defined by the class and automatically
add them
110 Using Caché Objects

If you would like to see schema evolution in action, then try the following:
Schema Evolution
1. Start Caché Studio and create a new persistent class with one or more properties in it.
2. Compile the class and then view the automatically generated storage definition (as XML
text) for the class using the View Storage command on the View menu. Alternatively, you
can see a more graphical representation of storage using the Class Inspector. Click on
Storage in the Inspector, click in “Default” in the list of Storage definitions, click on
Data Nodes in the keyword list, and click on the browse button (...) that appears. This
invokes a graphical storage editor.
Within the generated storage for your class, you will see the pseudo-property
%%CLASSNAME. This is a placeholder for the class name of any future subclasses you
may derive from your class and is used to tell the type of objects stored in the database.
For the root class of an extent, this value is always empty.
3. Add one or more new properties to your class and compile it again. Notice that these new
properties have been added to your storage definition automatically and in way that is
compatible to the previously existing storage.
12.5.1 Resetting the Storage Definition
During the development process, you may make many modifications to your persistent classes:
adding, modifying, and deleting properties. As a result, you may end up with a fairly convoluted
storage definition as the Class Compiler attempts to maintain a compatible structure
after each change. If you would like to have the Class Compiler regenerate a cleaner storage
structure, simply delete the storage definition for the class and recompile it.
You can do this as follows:
1. Open the class in Caché Studio,
2. Right-click on the default Storage definition in the Class Inspector,
3. Invoke the Delete command in the popup menu, and,
4. Compile the class. This will cause the Class Compiler to generate a new storage definition
for the class.
Using Caché Objects 111

13
Objects and SQL
A key aspect of Caché functionality is that it makes data visible both as objects and relational
tables: data that composes a set of class instances is projected as one or more relational tables.
In its relational form, this data is available for use with Caché SQL, which provides highperformance
relational access to the Caché data engine.
This chapter describes how objects are projected for SQL access; it assumes knowledge and
experience with SQL. For more information on classes and their definition, see the chapter
Classes.
The interconnection of Caché SQL and Caché objects allows your application to refer to a
class instantiation either as a particular object or as a part of a relational table. Generally, a
class definition's relational projection is a table: instantiations are rows within the table and
properties are columns within the table.
Note:
Certain features of a Caché class definition may not be accessible as both object and
relational features, due to the nature of the object and relational models (rather than
the limitations of Caché or any other tools).
13.1 Inheritance and SQL
Since inheritance is not part of the relational model, the Class Compiler projects a “flattened”
representation of the class as a relational table. The projected table contains all the appropriate
fields for the class, including those that are inherited. Hence, the projection of a subclass is
a table composed of:
Using Caché Objects 113

Objects and SQL
• All the columns in the projection of the superclass (that is, those based on all the properties
in its superclass' extent)
• Additional columns based on properties only in the subclass
• A subset of the rows in the superclass' table that consists only of the instances of the
subclass
For example, the projection of a persistent class called Sample.Employee that is derived from
the Sample.Person class is a table containing all the fields defined by both the
Sample.Employee and Sample.Person classes. This is illustrated in the following SQL queries.
First list all instances of Sample.Person and its properties:
SELECT * FROM Sample.Person
Now list all instances of Sample.Employee and its properties:
SELECT * FROM Sample.Employee
Typically, the table of a subclass has more columns and fewer rows than its parent. There
are more columns in the subclass since it usually adds additional properties when it extends
the parent class; there are often fewer rows since there are often fewer instances of the subclass
than the parent.
13.1.1 How a Class is Projected to SQL
To create a class that is automatically accessible from SQL, define it based on the %Persistent.
When you compile the class, the Caché Class Compiler automatically generates the runtime
information needed for relational access. The class' instances are then available as the rows
of a relational table.
13.1.2 Naming Rules for Projected Classes
Caché itself places no restrictions on class names. However, SQL tables cannot have names
that are SQL Reserved Words; hence, if you create a persistent class with a name that is a
reserved word, the Caché Class Compiler will generate an error message. In this case, you
must either rename the class or specify a table name for the projection that differs from the
class name; to do this, use the SQLTABLENAME keyword, which has the following syntax:
SQLTABLENAME = TableNameForSQL;
114 Using Caché Objects

The Object-SQL Projection
13.2 The Object-SQL Projection
This section describes the manner in which the various elements of a class are projected from
an object-based form to one that is SQL-based.
Fundamentally, a persistent Caché class is projected to a unique SQL table, where each of
its instances is projected as a row within that table. Other items are projected as listed below.
The Object-SQL Projection
From (Object Concept)...
Package
Class
OID
Data type property
Reference property
Embedded object
List property
Array property
Stream property
Index
Method
To (Relational Concept)...
Schema
Table
Identity field
Field
Reference field
Set of Fields
List field
Child table
BLOB
Index
Stored procedure (class methods only)
See the appropriate section below for more information on each individual topic.
You can also include SQL triggers in your classes; for information on their projection, see
the section on SQL Triggers below.
13.2.1 Identity (OIDs Projected to SQL)
Each object that inherits from %Persistent is uniquely identified by its OID (object identifier);
in the projection, each instance is uniquely identified by the value of its entry in the generated
identity (ID) column in the class' table. The value of the instance's entry in the identity column
is the same as that of the ID portion of its OID.
Using Caché Objects 115

Objects and SQL
The identity column has the name “ID” , unless the object has a property named “ID” ; in
that case, the identity column has “ID1” as its name. (If there are ID and ID1 properties, the
identity column has “ID2” as its name, and so on.)
13.2.1.1 ID Column Constraints
Though the ID appears as a column in the projection, there is no need to create an index based
on it, as it is already the IDKEY for the table; further, it has no equivalent property, so an index
created specifically for a class' SQL projection is not meaningful for the class itself.
Additionally, you cannot perform UPDATE or INSERT operations on it, since Caché generates
ID values automatically. For instance, here is the syntax to add a new instance of a
class through its projection (where the ID column is created from the class OID):
INSERT INTO PERSON (FNAME, LNAME)VALUES (:fname, :lname)
and not:
INSERT INTO PERSON (ID, FNAME, LNAME)VALUES (:id, :fname, :lname)
Because the ID field is handled automatically, you do not need to refer to it explicitly.
13.2.2 Properties
When projected, most properties appear in a relational table as columns (fields), where the
column takes its name from the property; the exception is arrays, which are projected as child
tables by default.
All a class' properties are projected, aside from the following exceptions:
• Transient properties
• Calculated properties
• Private properties
• Multidimensional properties
For information on managing the projection of transient or calculated properties, see Transient
and Calculated Properties.
116 Using Caché Objects

The Object-SQL Projection
13.2.2.1 Property Names and Column Names
If you want to give a property's projected column a different name, use the property keyword
SQLFIELDNAME. For instance, if there is a %String property called “select,” you would define
its projected name with the following syntax:
Property select As %String [ SqlFieldName = selectfield ];
If a property's name is an SQL reserved word, you need to specify a different name for its
projection.
13.2.2.2 Column Numbers for Properties
Caché automatically assigns a unique column number for each property. If you wish to control
column number assignments, you can specify the column for a property's projection. To do
this, use the property keyword SQLCOLUMNNUMBER, as in the following example:
Property RGBValue As %String [ SqlColumnNumber = 3 ];
The value you specify for SQLCOLUMNNUMBER must be an integer greater than 1 (one) and
specifies the property's column number in the projected table. If you use the
SQLCOLUMNNUMBER keyword without an argument, Caché assigns a column number that
is not preserved and that has no permanent position in the table's columns.
If any property has an SQL column number specified, then Caché assigns column numbers
for the other properties. The starting value for the assigned column numbers is the number
following the highest SQL column number specified.
The value of the SQLCOLUMNNUMBER keyword is inherited.
13.2.2.3 Data Type Properties
Data type properties are projected as fields using the property's SQL category (defined with
the SQLCATEGORY keyword) and any of its parameters. Both relational and object access
use the same data type classes, invoke the same data type methods to perform data validation
and conversions, and use data type parameter values in the same way. This is true for both
system-provided and user-written data type classes.
For example, the following property definition:
Property Name As %String(MAXLEN = 30);}
is projected as a field in a relational table containing a string with a maximum length of 30
characters.
Using Caché Objects 117

Objects and SQL
13.2.2.4 Reference Properties
Reference properties (that is, references to other persistent objects) are projected as fields
containing the ID portion of the OID of the referenced object. For instance, suppose a customer
object has a Rep property that refers to a SalesRep object (who is the customer' s sales representative).
If a particular customer has a sales representative with an ID of 12, then the entry
in the Rep column for that customer is also 12. Since this value matches that of the particular
row of the ID column of the referenced object, you can use this value when performing any
joins or other processing.
Note that within Caché SQL you can use a special reference syntax to easily use such references
without cumbersome JOIN syntax. For example:
SELECT Company->Name FROM Sample.Employee ORDER BY Company->Name
13.2.2.5 Embedded Object Properties
An embedded object property is projected as multiple columns in the parent class' table. One
column in the projection contains the entire object in serialized form (including all delimiters
and control characters). The rest of the columns are each for one property of the object.
The name of the column for the object property is the same as that of the object property
itself. The other column names are made up of the name of the object property, an underscore,
and the property within the embedded object. For instance, suppose a class has a Home
property containing an embedded object of type Address; Home itself has properties that
include Street and Country. The projection of the embedded object then includes the columns
named “Home_Street” and “Home_Country” . (Note that the column names are derived
from the property, Home, and not the type, Address.)
For example, the sample class Sample.Person, includes a Home property which is an
embedded object of type Sample.Address. You can use the component fields of Home via
SQL as follows:
SELECT Name, Home_City, Home_State FROM Sample.Person
WHERE Home_City %STARTSWITH 'B'
ORDER BY Home_City
Embedded objects can also include other complex forms of data:
• The projection of a reference property includes a read-only field that includes the object
reference as described in “Reference Properties” .
• The projection of an array is as a single, non-editable column that is part of the class'
table.
118 Using Caché Objects

The Object-SQL Projection
• The projection of a list is as a list field as one of its projected fields; the list field is as
described in List Properties.
13.2.2.6 Array Properties
The projection of an array property is as a child table. The name of this child table is a concatenation
of the name of the class containing the array property and the name of the array
property itself (unless either the container class or array property have SQL names declared).
For example, a Person class with an array property called Siblings has a projection as a child
table called “Person_Siblings” .
The child table contains the following three columns:
• One contains the ID of each instance of the parent class; the name of this column is that
of the class containing the array (Person, in the example). Note that this column's values
are not unique to the child, but refer to the those that are unique to the parent.
• One contains the identifier for each array member; its name is always element_key.
• One contains array members for all the instances of the class; its name is that of array
property (Siblings, in the example).
Continuing the example of the Person class with an array property called Siblings, the projection
of Person includes a Person_Siblings child table with the following entries:
Sample Projection of an Array Property
Person (ID)
10
10
12
12
12
12
12
element_key
C
T
B
C
G
M
P
Siblings
Claudia
Tom
Bobby
Cindy
Greg
Marsha
Peter
If an instance of the parent class holds an empty collection (one that contains no elements),
that instance's ID does not appear in the child table, such as the instance above where ID
equals 11.
Using Caché Objects 119

Objects and SQL
Note:
There is no Siblings column in the parent table.
For the column(s) containing the array members, the number and contents of the column(s)
depend on the kind of array:
• The projection of an array of data type properties is a single column of data.
• The projection of an array of reference properties is a single column of object references.
• The projection of an array of embedded objects is as multiple columns in the child table.
The structure of these columns is as is described in the section Embedded Object Properties.
Together, the ID of each instance and the identifier of each array member comprise a unique
index for the child table. Also, if a parent instance has no array associated with it, it has no
associated entries in the child table.
13.2.2.7 List Properties
A list property is projected as a string in $LIST format, which means that all the elements
within the collection are concatenated and projected as a single string. For example, suppose
the Person class has a Cars list property, where Cars is a list of strings that are license plate
numbers. This property appears as a single column called Cars and might appear in the Person
projection as follows (looking at a partial view of the table):
Sample Projection of a List Property
ID
1
2
3
Cars
324WLI,395BCE
253COM
512SEL,710LRR,526SJL
The list field contains a string constructed by concatenating the individual elements of the
list:
New cars
&sql(SELECT Cars INTO :cars
FROM Person
WHERE ID = :id)
Given an id value of 1, cars has a value equivalent to a list based on the “324WLI” and “
395BCE” strings.
120 Using Caché Objects

If the list for a particular instance contains no elements, it is projected as an empty string (and
not an SQL NULL value).
13.2.2.8 Stream Properties
Both character stream properties and binary stream properties are projected as BLOBs (binary
large objects).
Refer to the chapter on Streams for more information.
13.2.2.9 Transient and Calculated Properties
Since transient and calculated properties are not stored on disk, by default, they have no SQL
projection.
For the projection to include these columns, use the SQLCOMPUTED keyword, which allows
you to specify the code that calculates the value of an SQL computed field for the property;
you can then add code to the property definition that calculates the value of the projected
field. A property projected as a computed field can provide parallel object and SQL functionality
through parallel computations.
There are two ways to include code for a property's SQL computed field:
• Write code that performs the calculations required to determine the computed field's
value and associate it with the SQLCOMPUTECODE keyword.
• Write code that performs the calculations required to determine the computed field's
value and place it in a class method. Call this class method both from the code associated
with the SQLCOMPUTECODE keyword (for the SQL projection) and from the property's
Get method (for the object itself).
With either approach, this code can include values based on other properties and systembased
values. It can invoke class methods and user-defined functions.
Two Types of Computed SQL Fields
The Object-SQL Projection
The kind of computed SQL field described above is only one of the two types of computed
SQL fields:
• Always Computed (described above) — The field value is not stored in the database, but
calculated when needed upon retrieval.
• Triggered Computed — The field value is stored in the database and is calculated upon
INSERT/UPDATE if needed.
Using Caché Objects 121

Objects and SQL
The way to determine if a field is Always Computed or Triggered Computed is by the
TRANSIENT and/or CALCULATED property keywords. If the property is transient or calculated,
and has SQLCOMPUTED, the compute type is Always. If the property is not transient, not
calculated, and has SQLCOMPUTED, the compute type is Triggered.
An Example
Suppose a class has a Name property of the form last,first. You might use the value stored
in this property to create the calculated fields FirstName and LastName (each containing the
first and last name, respectively). To do this, the code to set the value of the computed
LastName field would be:
Set {LastName}=##class(MyClass).GetLastName({Name})
where MyClass is the class being projected and GetLastName is a class method which has
the following code in it:
Quit $Piece(Name,",")
This code simply returns the first element in the Name property that appears before the “,”
delimiter.
13.2.3 Methods
A class' instance methods are only accessible via the object representation of a class, and not
via SQL. This is because an SQL query does not cause objects to be instantiated their (hence,
their methods are not accessible).
13.2.4 SQL Triggers
Because Caché SQL supports the use of triggers, any trigger associated with a class is included
as part of the class' SQL projection.
For more information on triggers, see the section Triggers in Using Caché SQL.
Triggers are code segments executed when specific events occur in Caché SQL. Caché supports
triggers based on the execution of INSERT, UPDATE, and DELETE commands. The
specified code will be executed either immediately before or immediately after the relevant
command is executed, depending on the trigger definition. Each event can have multiple
triggers as long as they are assigned an execution order.
Triggers are not fired by the persistence methods used by the default storage class,
%CacheStorage.
122 Using Caché Objects

Triggers are, however, fired by the persistence methods used by the legacy storage class,
%CacheSQLStorage as it uses SQL statements internally to implement its persistent behavior.
13.2.4.1 Trigger Keywords
The Object-SQL Projection
A class definition may include a list of trigger definitions. A trigger definition consists of the
following information:
Code
Event
Name
Order
Time
The Caché ObjectScript code to be executed when the specified trigger event occurs.
Triggers fully support all Caché ObjectScript functionality including embedded SQL
and object syntax.
The event with which this trigger is associated. Possible events include INSERT,
UPDATE, DELETE. Together with the Time value, this determines when a trigger
is invoked.
The name of the trigger. This must be unique within the extent of the trigger.
A number indicating the order in which trigger actions are to be carried out when
more than one trigger is defined for a specific event. If only one trigger is associated
with a specific event its order must be set to 1. If more than one trigger is associated
with a specific event, each must have a unique order value.
Together with the Event keyword, Time determines when a trigger is invoked. The
possible values of Time are BEFORE and AFTER.
13.2.5 Relationships
The SQL projection of a relationship depends on its cardinality value: The single-valued side
(ONE or PARENT) is projected as a simple designative reference field. For example, the
Employee table will have a field called TheCompany whose value is the ID of the related
Company:
Using Caché Objects 123

Objects and SQL
SELECT ID,Name,Title,TheCompany->Name
FROM Employee
ORDER BY Name
The multi-valued side is not projected as a field (Multi-valued relationships are state-less on
disk and SQL does not deal with in-memory objects). Instead, you must perform a simple
join based on the multi-valued side's ID value and the single-valued side's reference field:
SELECT c.Name, e.Name
FROM Company c, Employee e
WHERE e.TheCompany = c.ID
ORDER By 1,2
A single-valued relationship with cardinality of ONE is projected to SQL as a FOREIGNKEY
with NOACTION specified for UPDATE and DELETE.
If the cardinality of the single-valued relationship is PARENT then the table projected from
the class containing the relationship is “adopted” as a child table by the table projected from
the type class of the single-valued relationship.
124 Using Caché Objects

14
Relationships
A relationship is an association between two objects, each of a specific type; to create a
relationship between two objects, each must have a relationship property, which defines its
half of the relationship.
For example, a Company class may define a one-to-many relationship with an Employee
class. In this case, there may be zero or more Employee objects associated with each Company
object.
Caché relationships have the following characteristics:
• Relationships are binary, that is a relationship is defined either between two, and only
two, classes or between a class and itself).
• Relationships can only be defined for persistent classes.
• Relationships must be bi-directional, that is both sides of a relationship must be defined.
• Currently, Caché supports two types of relationship: one-to-many (independent) and
parent-to-children (dependent). One-to-one and many-to-many relationships are not
supported at this time.
• Relationships automatically provide referential integrity; unlike a reference (or objectvalued)
property, the value of the relationship is constrained to be correct (that is, there
are no dangling references).
• Relationships automatically manage their in-memory and on-disk behavior.
• Relationships provide superior scaling and concurrency over object collections.
• Relationships are visible to SQL as foreign keys. See the Object-SQL Projection for more
information on this topic.
Using Caché Objects 125

Relationships
14.1 Relationship Basics
The fundamental aspects of using relationships are relationship keywords and the action of
defining a relationship.
14.1.1 Relationship Keywords
There are three keywords or modifiers required to define a relationship property:
TYPE
The type (class name) of the related class. This must be a persistent class.
INVERSE
CARDINALITY
The name of the corresponding relationship property in the related class (the “other
side” of the relationship).
The cardinality of this side of the relationship. This is either “ONE” , “MANY” ,
“PARENT” , or “CHILDREN” — where the class' inverse has the complementary
cardinality, such as MANY with ONE or PARENT with CHILDREN
Because each relationship is defined using a relationship property, which is a particular kind
of property, some other property keywords are available for use in them, including
“DESCRIPTION” , “FINAL” , “REQUIRED” , “SQLFIELDNAME” and “PRIVATE” .
Some property keywords, such as “MULTIDIMENSIONAL” , do not apply. See the Property
Keywords section of the Class Definition Reference for more information.
14.1.1.1 About Cardinality
The value of “CARDINALITY” defines how the relationship “appears” from this side as
well as whether it is an independent relationship (ONE-MANY) or dependent relationship
(PARENT-CHILDREN).
For example, suppose we have a Book object that is related to MANY Chapter objects:
The relationship Book.Chapters has cardinality of MANY. Each Chapter is related to ONE
Book so the Chapter.Book relationship has cardinality of ONE.
In the case of a dependent relationship, such as an Invoice object with dependent LineItem
objects,
126 Using Caché Objects

Relationship Basics
the relationship Invoice.Items has cardinality of CHILDREN because Items is a collection of
children from the point of view of Invoice. LineItem.TheInvoice has cardinality of PARENT
because TheInvoice refers to the parent of this LineItem.
The cardinality value of a relationship must correspond to the cardinality value of the inverse
relationship as defined in the following table:
ONE
MANY
PARENT
CHILDREN
MANY
ONE
CHILDREN
PARENT
14.1.2 Defining a Relationship
To create a relationship, there are a pair of complementary relationship properties. In the
Caché Studio you can define a relationship property using the New Property Wizard and
checking the Relationship option. See the Relationships section of the Studio documentation
for details.
When you define a relationship property, Studio automatically creates the inverse relationship
property in the associated class.
You can also define a relationship property directly in Studio. The syntax is:
Relationship Name As Type
[Inverse = related_class,
Cardinality = cardinality_type
where
• “TYPE” , “INVERSE” and “CARDINALITY” are required.
• related_class specifies the other half of the relationship and must be a persistent class.
• cardinality_type, the value of cardinality, indicates the complementary cardinality of
related_class (and can have a value of ONE, MANY, PARENT, or CHILDREN).
For example, here are the definitions of two related classes, Company and Employee. Company
is:
Using Caché Objects 127

Relationships
Class MyApp.Company Extends %Persistent [ClassType = persistent]
{
Property Name As %String;
/// a Company has MANY Employees
Relationship Employees As Employee [Inverse = TheCompany, Cardinality = MANY];
}
and Employee:
class MyApp.Employee Extends %Persistent [ClassType = persistent]
{
Property Name As %String;
Property Title As %String;
/// an Employee has ONE Company
Relationship TheCompany As Company [inverse = Employees, cardinality = ONE];
}
14.2 Dependent Relationships
A dependent relationship, defined by having cardinality of PARENT on one side and CHIL-
DREN on the other, has the following additional characteristics:
• The existence of the child objects is dependent on the parent; if a parent object is deleted
then all of its children are automatically deleted.
• Once associated with a particular parent object, a child object can never be associated
with a different parent. This is because the persistent ID value of the child object is based
in part on the parent's persistent ID.
• As much as possible, instances of child objects are clustered with parent objects on disk
making disk access as optimal as possible (few page accesses are required to retrieve the
children for a parent).
• A dependent relationship is projected to SQL as a parent-child table.
• The two classes are linked at compile time, as opposed to a ONE-MANY relationship,
where the classes are compiled independently. Consequently, parent/child relationships
may only be defined between two different classes. The two sides of a dependent relationship
cannot be defined within a single class, or within a base class and its derived class.
For example, here are the definitions for two related dependent classes, Invoice and LineItem.
Invoice is:
128 Using Caché Objects

An Invoice class
class MyApp.Invoice Extends %Persistent [ClassType = persistent]
{
Property CustomerName As %String;
/// an Invoice has CHILDREN that are LineItems
Relationship Items As LineItem [inverse = TheInvoice, cardinality = CHILDREN];
}
and LineItem:
/// A LineItem class
class MyApp.LineItem Extends %Persistent [ClassType = persistent]
{
Property Product As %String;
Property Quantity As %Integer;
In-Memory Behavior of Relationships
/// a LineItem has a PARENT that is an Invoice
Relationship TheInvoice As Invoice [inverse = Items, cardinality = PARENT];
}
14.3 In-Memory Behavior of Relationships
Programmatically, relationships behave as properties. Single-valued relationships (cardinality
of “ONE” or “PARENT” ) behave like atomic (non-collection) reference properties. Multivalued
relationships (cardinality of “MANY” or “CHILDREN” ) are instances of the
%RelationshipObject class which has a collection-like interface.
For example, you could use the Company and Employee objects defined above in the following
way:
// create a new instance of Company
Set company = ##class(Company).%New()
Set company.Name = "Chiaroscuro LLC"
// create a new instance of Employee
Set emp = ##class(Employee).%New()
Set emp.Name = "Weiss,Melanie"
Set emp.Title = "CEO"
// Now associate Employee with Company
Set emp.TheCompany = company
// Save the Company (this will save emp as well)
Do company.%Save()
// Close the newly created objects
Do company.%Close()
Do employee.%Close()
Relationships are fully bi-directional in memory; any operation on one side is immediately
visible on the other side. Hence, the code above is equivalent to the following, which instead
operates on the company:
Using Caché Objects 129

Relationships
Do company.Employees.Insert(emp)
Write emp.TheCompany.Name
// this will print out "Chiaroscuro LLC"
You can load relationships from disk and use them as you would any other property. When
you refer to a related object from the ONE side, the related object is automatically swizzled
into memory in the same way as a reference (object-valued) property. When you refer to a
related object from the MANY side, the related objects are not swizzled immediately; instead
a transient %RelationshipObject collection object is created. As soon as any methods are called
on this collection, it builds a list containing the ID values of the objects within the relationship.
It is only when you refer to one of the objects within this collection that the actual related
object is swizzled into memory.
Here is an example that displays all Employee objects related to a specific Company:
// open an instance of Company
Set company = ##class(Company).%OpenId(id)
// iterate over the employees; print their names
Set key = ""
Do {
Set employee = company.Employees.GetNext(.key)
If (employee '= "") {
Write employee.Name,!
}
} While (key '= "")
In this example, closing company removes the Company object and all of its related Employee
objects from memory. Note, however, that every Employee object contained in the relationship
will be swizzled into memory by the time the loop completes. To reduce the amount of
memory that this operation uses—perhaps there are thousands of Employee objects—then
modify the loop to “unswizzle” the Employee object after displaying the name, by calling
the %UnSwizzleAt method:
Do {
Set employee = company.Employees.GetNext(.key)
If (employee '= "") {
Write employee.Name,!
// remove employee from memory
Do company.Employees.%UnSwizzleAt(key)
}
} While (key '= "")
130 Using Caché Objects

14.4 Persistent Behavior of Relationships
Though there are two sides to every relationship, only one side actually has its relationshiprelated
information stored to disk. This is the single-valued side, the PARENT or ONE of
the relationship.
When you open an instance of the multi-valued side of a relationship, Caché treats its relationship
property as a standard object reference; it opens and swizzles into memory the
PARENT or ONE object. When you open an instance of the single-valued side of a relationship,
Caché uses a query to locate and create a list of all the relevant CHILDREN or MANY
instances; to improve performance of this operation, on the multi-valued side, create an index
on the relationship property. This also improves performance of the Execute, Fetch, and
Close methods. When defining a relationship property, Studio asks if you want such an index.
14.4.1 Referential Integrity
Relationships maintain referential integrity by enforcing constraints and invoking referential
actions. When a relationship is saved, Caché checks for the existence of the target of its reference.
If the target does not exist, then Caché returns an error and the save operation fails.
When an object is deleted and there are objects related to it, the related objects are deleted
(parent/child cardinality) or the delete operation fails (one/many cardinality).
14.4.2 Persistent Behavior of Dependent Relationships
With parent/child relationships, deleting the parent kills the children. Further, the storage of
children is subordinate to that of the parent, in a structure similar to the following:
^Inv(1)
^Inv(1, "invoice", 1)
^Inv(1, "invoice", 2)
^Inv(1, "invoice", 3)
...
Persistent Behavior of Relationships
Again, by associating the storage nodes of the CHILDREN with that of their PARENT, as
is depicted above, Caché can read and write more quickly.
Using Caché Objects 131

15
Streams
Streams are used to create properties containing large (greater than 32K) amounts of data.
Caché contains several stream classes that provide access to different data sources using a
common stream interface defined by the %Stream.Object class. Streams are implemented via
a family of classes that include the following members:
• %Stream.Object — the base class for all stream classes.
• %Library.AbstractStream — base class for all streams that can be used as object properties.
• %Library.GlobalCharacterStream — class for character streams stored in global nodes.
• %Library.GlobalBinaryStream — class for binary streams stored in global nodes.
• %Library.FileCharacterStream — class for character streams stored in an external file.
• %Library.FileBinaryStream — class for binary streams stored in an external file.
• %Library.File — class for manipulating external files as streams.
15.1 Declaring Stream Properties
Caché supports both binary streams and character streams. Binary streams contain the same
sort of data as type %Binary, and are intended for very large binary objects such as pictures.
Similarly, character streams contain the same sort of data as type %String, and are intended
for storing large amounts of text. Character streams, like strings, may undergo a UNICODE
translation within client applications.
Using Caché Objects 133

Streams
Stream data may be stored in either an external file or a Caché global, depending on how the
stream property is defined. The %FileCharacterStream and %FileBinaryStream classes are
used for streams stored as external files, while %GlobalCharacterStream and
%GlobalBinaryStream are used for streams stored as globals. All four classes can use the
optional LOCATION parameter to specify a default storage location.
In the following example, the JournalEntry class contains four stream properties (one for each
of the four basic stream classes), and specifies a default storage location for two of them:
Class testPkg.JournalEntry Extends %Persistent
{
Property DailyText As %FileCharacterStream;
Property DailyImage As %FileBinaryStream(LOCATION = "C:/Images");
Property Text As %GlobalCharacterStream(LOCATION = "^MyText");
Property Picture As %GlobalBinaryStream;
}
In this example, data for DailyImage will be stored in a file (with an automatically generated
name) in the C:/Images directory, while the data for the Text property will be stored in a global
named ^MyText.
15.1.1 Projecting Streams to ODBC
Streams are projected to ODBC as BLOBs. Their ODBC type is LONG VARCHAR (or
LONG VARBINARY). The ODBC driver/server uses a special protocol to read/write BLOBs.
Typically you have to write BLOB applications by hand, since the standard reporting tools
do not support them.
15.2 Using the Stream Interface
All streams inherit a set of methods and properties used to manipulate the data they contain.
Some commonly used methods include the following:
• Read — Read a specified number of characters starting at the current position in the
stream.
• Write — Append data to the stream, starting at the current position. Overwrites existing
data if the position is not set to the end of the stream.
• Rewind — Move to the beginning of the stream.
• MoveTo — Move to a given position in the stream.
• MoveToEnd — Move to the end of the stream.
134 Using Caché Objects

• CopyFrom — Copy the contents of a source stream into this stream.
• NewFileName — Specify a filename for a %FileCharacterStream or %FileBinaryStream
property.
Commonly used properties include the following:
• %Location — The default storage location (directory or global) where the stream will
store its persistent data. If no location is declared for a stream, the %Location for globals
will default to ^ooClassNameS, and the %Location for files will default to the current
Caché directory.
• AtEnd — Set to true when a Read encounters the end of the data source.
• Id — The unique identifier for an instance of a stream within the extent specified by
%Location.
• Size — The current size of the stream (in bytes or characters, depending on the type of
stream).
The following sections provide concrete examples using these methods and properties. For
detailed information on individual Stream methods and properties, see the Class Reference
entries for the classes listed at the beginning of this chapter.
15.2.1 Reading and Writing Stream Data
At the core of the Stream interface are the methods Read, Write, and Rewind and the properties
AtEnd and Size.
The following example reads data from the Person.Memo stream and writes it to the console,
100 characters at a time. The value of len is passed by reference, and is reset to 100 before
each Read. The Read method attempts to read the number of characters specified by len,
and then sets it to the actual number of characters read:
Do person.Memo.Rewind()
While (person.Memo.AtEnd = 0) {
Set len = 100
Write person.Memo.Read(.len)
}
Similarly, you can write data into the stream:
Do person.Memo.Write("This is some text. ")
Do person.Memo.Write("This is some more text.")
Using the Stream Interface
Using Caché Objects 135

Streams
15.2.2 Copying Data between Streams
All streams contain a CopyFrom method which allows one stream to fill itself from another
stream. This can be used, for example, to copy data from a file into a stream property:
// open a text file using a %Library.File stream
Set file = ##class(%File).%New("\data\textfile.txt")
Do file.Open("RU") ; same flags as OPEN command--use "U" for streams
// Open a Person object containing a Memo stream
// and copy the file into Memo
Set person = ##class(Person).%New()
Do person.Memo.CopyFrom(file)
// save the person object and close it, then close the file
Do person.%Save()
Do person.%Close()
Do file.%Close()
15.2.3 Inserting Stream Data
Streams have both a temporary and a permanent storage location. All inserts go into the
temporary storage area, which is only made permanent when you save the stream. If you start
inserting into a stream, then decide that you want to abandon the insert, the data stored in the
permanent location will not be altered.
If you create a stream, start inserting, then do some reading you can call MoveToEnd and
then continue appending to the temporary stream data. However after you save the stream,
the data is moved to the permanent storage location. If you then reload the stream and start
inserting, it will insert into the temporary storage area, rather than appending to the permanently
stored data.
If this is the behavior you want you will need to create a temporary stream, for example:
Set test = ##class(Test).%OpenId(5)
Set tmpstream = ##class(%GlobalCharacterStream).%New()
Do tmpstream.CopyFrom(test.text)
Do tmpstream.MoveToEnd()
Do tmpstream.Write("append text")
Set test.text = tmpstream
Do tmpstream.%Close()
// Now do whatever you want with the test object
In this example, we create a temporary stream of the required type, then copy from the stream
stored in the Test object, which will put this data in the temporary storage area of our new
stream. Then we append to this stream and put its oref into the Test object and close it to keep
the reference counts correct.
136 Using Caché Objects

Using Streams with SQL
15.2.4 Using Streams in Object Applications
Stream properties are manipulated via a transient object that is created by the object that owns
the stream property. Streams act as literal values (think of them as large strings). Two object
instances cannot refer to the same stream.
In the following example, a long memo is created and then written to the console:
// create object and stream
Set p = ##class(Person).%New()
Set p.Name = "Mo"
Do p.Memo.Write("This is part one of a long memo")
// ...
Do p.Memo.Write("This is part 10000 of a long memo")
Do p.%Save()
Do p.%Close()
// read object and stream
Set p = ##class(Person).%Open(oid)
Do p.Memo.Rewind() // not required first time
// write contents of stream to console, 100 characters at a time
While (p.Memo.AtEnd = 0) {
Set len = 100
Write p.Memo.Read(.len)
}
Do p.%Close()
15.3 Using Streams with SQL
Stream fields have the following restrictions within SQL:
• You cannot index on a stream value.
• You cannot use a stream value in a WHERE clause.
• You cannot UPDATE/INSERT multiple rows containing a stream; you must do it row
by row.
Within embedded SQL you can read a stream as follows:
• Select the stream:
&sql(SELECT Memo FROM Person INTO :memo WHERE ID = 1)
This will fetch the stream's ID value into memo.
• Open a %Stream.Object object from this ID value:
Using Caché Objects 137

Streams
Set stream=##class(%Stream.Object).%Open(memo)
Since the %Open method is fully polymorphic, the actual type of stream returned by
%Open depends on what type is stored with the Person object
• Read and process the stream data, closing the stream when done:
Write stream.Read(100)
Do stream.%Close()
Writing a stream is similar. There are several ways to do this. In the first, we get an oref value
and use it to insert the stream into the table:
//Create a stream and write data to it
Set stream = ##class(%GlobalCharacterStream).%New()
Do stream.Write("Do re mi fa sol...")
//Save the stream, record the stream oref in the %qstrhandle
//structure, and turn the stream into a string representation
//of an oref:
Do stream.SaveStream()
Set %qstrhandle(1,stream) = stream
Set stream = stream_""
//INSERT this string-oref value into the table, closing the
//stream when done:
&sql(INSERT INTO Person (Name,Memo) VALUES (:name, :stream))
Kill %qstrhandle(1,stream)
The second approach is similar, but uses %qacn instead of 1 in the %qstrhandle array. There
is no need to save the stream before passing the oref. The filer will actually look for
%qstrhandle($g(%qacn,1),stream)
//Create a stream and write data to it
Set stream = ##class(%GlobalCharacterStream).%New()
Do stream.Write("Do re mi fa sol...")
//Record the stream oref in the %qstrhandle structure, and
//turn the stream into a string representation of an oref.
Set %qacn=100
Set %qstrhandle(%qacn,stream) = stream
Set stream = stream_""
//INSERT this string-oref value into the table, closing
//the stream when we are done:
&sql(INSERT INTO Person (Name,Memo) VALUES (:name, :stream))
Kill %qstrhandle(%qacn,stream)
You can also insert a literal value directly into the table:
//Define the literal value and write it into the table
Set stream = "Do re mi fa sol..."
&sql(INSERT INTO Person (Name,Memo) VALUES (:name, :stream))
Kill %qstrhandle(1,stream)
138 Using Caché Objects

Streams and Visual Basic
15.4 Streams and Visual Basic
To make it easy to use streams efficiently within Visual Basic applications, the Caché ActiveX
Binding projects stream properties using two special ActiveX stream objects:
CacheActiveX.CharStream and CacheActiveX.BinaryStream. From your Visual Basic application
you simply make calls to the methods provided by these objects.
For example, suppose you have a Person object containing a character stream property, Memo.
In addition to the standard stream methods Read and Write, you can use the client-side
method Data, which will fetch the entire stream in one operation:
' Visual Basic code
Dim person As Object
Dim memo As String1
' Open a Person object and copy its memo into a local variable
Set person=Factory.OpenId(id)
memo=person.Memo.Data
The GetPicture method is a similar mechanism that efficiently copies binary data containing
a bitmap image into a picture control. For example, if the Person object has a binary stream
property, Picture, containing a bitmap image (such as a .jpg or .png file), you can display this
image in Visual Basic as follows:
' Visual Basic code
Dim person As Object
Dim memo As String
' Open a Person object and show its picture in an Image control
Set person=Factory.OpenId(id)
Image1.Picture = person.Picture.GetPicture
The SetPicture method can be used to copy an image in the other direction, from an Image
control to a binary stream property:
' Visual Basic code
person.Picture.SetPicture Image1.Picture
Using Caché Objects 139

16
Class Projections
Class projections provide a way to extend the behavior of the Caché Class Compiler. A class
projection associates a class definition with a projection class. A projection class (derived
from the %Projection.AbstractProjection class) provides methods that are invoked by the Class
Compiler when it compiles and removes a class definition.
Projection classes are used by Caché to automatically generate additional code when a class
is compiled as well as perform needed cleanup when a class is deleted. The projection
mechanism is used by the Java, EJB, and C++ projections (hence the origin of the term
“projection” ) to automatically generate the necessary client binding code (Java or C++)
whenever a class is compiled.
16.1 Projection Definitions
Every class definition may optionally include one or more projection definitions. Each definition
has a unique name and specifies the projection class to be used for the projection as
well as parameter values that are passed to the projection methods (allowing each projection
to have customized behavior).
16.1.1 Adding a Projection to a Class
You can associate a projection with a class by adding a projection definition to its class definition.
In Caché Studio you can do this using the Projection statement within a class definition:
Using Caché Objects 141

Class Projections
class MyApp.Person extends %Persistent [ClassType = persistent]
{
Projection JavaClient As %Projection.Java(ROOTDIR="c:\java");
}
This example defines a projection named “JavaClient” that will use the %Projection.Java
projection class. When the methods of the projection class are called they will be passed the
value of the ROOTDIR parameter.
Note that if you omit the ROOTDIR parameter, your Java or C++ classes will be created
under the default directory specified by your Caché configuration. To set this default directory,
go to the Advanced Settings page of the Portal ([Home] > [Configuration] > [Advanced Settings]);
in the Projections category, for setting you want, click Contents; on the Configuration Settings
page that appears ([Home] > [Configuration] > [Advanced Settings] > [Configuration Settings]),
click Add New Item to display a page where you can specify the default directory for a
namespace.
A class may have any number of uniquely named projections. In the case of multiple projections,
the methods of each projection class will be invoked when a class is compiled or deleted.
The order in which multiple projections are handled is undefined.
16.2 Projection Classes
The behavior of a projection is provided by its corresponding projection class. The projection
class implements a set of methods (the projection interface, q.v.) that are called in response
to certain events during a class' life-cycle.
16.2.1 The Projection Interface
Every projection class implements the projection interface. This interface consists of the
following methods:
CreateProjection
The CreateProjection method is a class method that is invoked by the Class Compiler
after it completes the compilation of a class definition. This method is passed the
name of the class being compiled as well as an array containing the parameter values
(subscripted by parameter name) defined for the projection.
142 Using Caché Objects

RemoveProjection
The RemoveProjection method is a class method that is invoked when either 1) a
class definition is deleted or 2) at the start of a recompilation of the class. This method
is passed the name of the class being removed, an array containing the parameter
values (subscripted by parameter name) defined for the projection, and a flag indicating
whether the method is being called as part of a recompilation or because the class
definition is being deleted.
When a class definition containing a projection is compiled the following events occur:
1. If the class has been compiled previously, it will be “uncompiled” before the new
compile begins (that is, all the results of the previous compilation are removed). At this
time, the compiler invokes the RemoveProjection method for every projection with a
flag indicating that a recompilation is about to occur.
Note that you cannot call methods of the associated class from within the
RemoveProjection method as the class will not exist at this point.
Also note that if you add a new projection definition to a class that had been previously
compiled (without the projection) then the compiler will call the RemoveProjection
method on the next compilation even though the CreateProjection method has never
been called. Implementors of the RemoveProjection method have to plan for this possibility.
2. After the class is completely compiled (i.e., it is ready for use), the compiler will invoke
the CreateProjection method for every projection.
When a class definition is deleted, the RemoveProjection method is invoked for every projection
with a flag indicating that a deletion has occurred.
16.2.2 The Standard Projection Classes
Projection Classes
In order to easily provide additional services (such as Java support) Caché provides the following
projection classes as part of its standard class library:
Using Caché Objects 143

Class Projections
Projection Classes
Class
%Projection.Java
%Projection.CPP
%Projection.EJB
%Projection.WebService
Description
Generates a Java client class to enable access to the class
from Java.
Generates a C++ client class to enable access to the class
from C++.
Generates a set of Enterprise Java Bean client classes to
enable access to the class from an EJB server. In addition,
any other files, such as deployment descriptors are created.
Generates a set of auxiliary Caché class that implement the
SOAP interface for a class.
16.2.3 Creating a New Projection Class
You can create a new projection class by deriving a new subclass of the
%Projection.AbstractProjection class, implementing the projection interface methods, and
defining any class parameters you require:
Class MyApp.MyProjection Extends %Projection.AbstractProjection
{
Parameter MYPARM;
/// This method is invoked when a class is compiled
ClassMethod CreateProjection(cls As %String, ByRef params)
{
}
/// This method is invoked when a class is 'uncompiled'
ClassMethod RemoveProjection(cls As %String, ByRef params, deleted as %Boolean)
{
}
}
144 Using Caché Objects

17
Object Synchronization
Object synchronization is a feature of Caché objects that allows “occasionally connected”
systems to synchronize databases. By this process, each database updates its objects. Object
synchronization offers complementary functionality to Caché system tools that provide high
availability and shadowing. Object synchronization is not designed to provide support for
real-time updates; rather, it is most useful for a system that needs updates at discrete intervals.
For example, a typical object synchronization application would be in an environment where
there is a master copy of a database on a central server and secondary copies on client
machines. Consider the case of a sales database, where each sales representative has a copy
of the database on a laptop computer. When Mary, a sales representative, is off site, she makes
updates to her copy of the database. When she connects her machine to the network, the
central and remote copies of the database are synchronized. This can occur hourly, daily, or
at any interval.
This chapter includes the following sections:
• About Updates
• Running an Update
• Other Topics
17.1 About Updates
Object synchronization between two databases involves updating each of them with data
from the other. However, Caché does not support bidirectional synchronization as such.
Using Caché Objects 145

Object Synchronization
Rather, updates from one database are posted to the other; then updates are posted in the
opposite direction. For a typical application, if there is a main database and one or more local
databases (as in the previous sales database example), it is recommended that updates are
from the local to the main database first, and then from the main database to the local one.
For object synchronization, the idea of client and server is by convention only. For any two
databases, you can perform bidirectional updates; if there are more than two databases, you
can choose what scheme you use to update all of them (such as local databases synchronizing
with a main database independently).
This section addresses the following topics:
• The GUID
• How updates work
• The SyncSet and SyncTime objects
17.1.1 The GUID
To ensure that updates work properly, each object in a database should be uniquely distinguishable.
To provide this functionality, Caché gives each individual object instance a GUID
— a Globally Unique ID. The GUID makes each object universally unique.
The GUID is optionally created, based on the value of the GUIDENABLED parameter. If
GUIDENABLED has a value of 1, then a GUID is assigned to each new object instance.
Consider the following example. Two databases are synchronized and each has the same set
of objects in it. After synchronization, each database has a new object added to it. If the two
objects share a common GUID, object synchronization considers them the same object in
two different states; if each has its own GUID, object synchronization considers them to be
different objects.
17.1.2 How Updates Work
Each update from one database to another is sent as a set of transactions. This ensures that
all interdependent objects are updated together. The content of each transaction depends on
the contents of the journal for the “source” database. The update can include one or more
transactions, up to all transactions that have occurred since the last synchronization.
Resolution of the following conditions is the responsibility of the application:
• If two instances that share a unique key have different GUIDs. This requires determining
if the two records describe a single object or two unique objects.
146 Using Caché Objects

About Updates
• If two changes require reconciliation. This requires determining if the two changes were
to a common property or to non-intersecting sets of properties.
17.1.3 The SyncSet and SyncTime Objects
When two databases are to be synchronized, each has transactions in it that the other lacks.
This is illustrated in the following diagram:
Two Unsynchronized Databases
Here, database A and database B have been synchronized at transaction 536 for database A
and transaction 112 for database B. The subsequent transactions for each database need to
be updated from each to the other. To do this, Caché uses what is called a SyncSet object.
This object contains a list of transactions that are used to update a database. For example,
when synchronizing database B to database A, the default contents of the SyncSet object are
transactions 547, 555, 562, and 569. Analogously, when synchronizing database B to database
A, the default contents of the SyncSet object are transactions 117, 124, 130, and 136. (The
transactions do not use a continuous set of numbers, because each transaction encapsulates
multiple inserts, updates, and deletes — which themselves use the intermediate numbers.)
Each database holds a record of its synchronization history with the other. This record is
called a SyncTime table. For database, its contents are of the form:
Database Namespace Last Transaction Sent Last Transaction Received
------------------------------------------------------------------------------
B User 536 112
Using Caché Objects 147

Object Synchronization
Note:
The numbers associated with each transaction do not provide any form of a timestamp.
Rather, they indicate the sequence of filing for transactions within an individual
database.
Once synchronization of database A with database B is completed, the two databases might
appear as follows:
Two Databases, Where One Has Been Synchronized to the Other
Because the transactions are being added to database B, they result in new transaction numbers
in that database.
Analogously, the synchronization of database B with database A results in 117, 124, 130,
and 136 being added to database A (and receiving new transaction numbers there):
148 Using Caché Objects

About Updates
Two Synchronized Databases
Note that database B's transactions that have come from database A (140 through 162) are
not updated back to database A. This is because the update from B to A uses a special feature
that is part of the synchronization functionality. It works as follows:
1. Each transaction in a database is labeled with what can be called “a database of origin.”
In this example, database B's transaction 140 would be marked as originating in database
A, while its transaction 136 would be marked as originating in itself (database B).
2. The SyncSet.AddTransactions method, which bundles a set of transactions for synchronization,
allows you to exclude transactions that originate in a particular database. Hence,
when updating from B to A, AddTransactions excludes all transactions which originate
in database A — since those have already been added to the transaction list for database
B.
Using Caché Objects 149

Object Synchronization
This functionality prevents creating infinite loops in which two databases continually update
each other with the same set of transactions.
17.2 Running an Update
This process involves preparing for the update and then running the update itself.
17.2.1 Preparing for the Update
Object synchronization requires that the sites have data with matching sets of GUIDs. If you
are starting with an already-existing database that does not yet have GUIDs assigned for its
records, you need to assign a GUID to each instance (record) in the database, and then make
sure there are matching copies of the database on each site. In detail, the process is:
1. For each class being synchronized, set the value of the OBJJOURNAL parameter to 1 or
2. This activates the logging of filing operations (that is, insert, update, or delete) within
each transaction; this information is stored in the ^OBJ.JournalT global.
If OBJJOURNAL equals 1, then the property values that are changed in filing operations
are stored in the system journal file; during synchronization, data that needs to be synchronized
is retrieved from that file.
If OBJJOURNAL equals 2, then the property values that are changed in filing operations
are stored in the ^OBJ.Journal global; during synchronization, data that needs to be
synchronized is retrieved from that global. Note that storing information in the global
increases the size of the database very quickly.
2. For each class being synchronized, set the value of its GUIDENABLED parameter to 1;
this tells Caché to allow the class to be stored with GUIDs. You can do this in Studio,
adding the following line to the class definition:
Parameter GUIDENABLED = 1;
Note that if this value is not set, the synchronization does not work properly. Also, you
must set GUIDENABLED for serial classes, but not for embedded objects.
3. For each class being synchronized, give each object instance its own GUID by running
the AssignGUID method:
Set Status = ##Class(%Library.GUID).AssignGUID(classname,displayoutput)
where
150 Using Caché Objects

• classname is a quoted string the name of class whose instances are receiving GUIDs,
such as "Sample.Person".
• displayoutput is an integer where zero specifies that no output is displayed and a nonzero
value specifies that output is displayed.
and where the method returns a %Status value.
4. Recompile the class.
5. Put a copy of the database on each site.
Running an Update
17.2.2 The Update Itself
This involves updating one database from another. The database providing the updates is
known as the “source database” ; the database receiving the updates is known as the “target
database.” To perform the actual synchronization, the process is:
1. Each time you wish to synchronize the two databases, go to the instance with the source
database. On the source database, create a new SyncSet using the %New method of the
%SYNC.SyncSet class:
Set SrcSyncSet = ##class(%SYNC.SyncSet).%New("unique_value")
The integer argument to %New, unique_value, should be an easily identified, unique
value. This ensures that each addition to the transaction log on each site can be differentiated
from the others.
2. Once you have created the SyncSet, you can invoke the AddTransactions method of
the SyncSet class:
Do SrcSyncSet.AddTransactions(FirstTransaction,LastTransaction,ExcludedDB)
where
• FirstTransaction is the first transaction number to synchronize.
• LastTransaction is the last transaction number to synchronize.
• ExcludedDB specifies a namespace within a database whose transactions are not
included in the SyncSet.
This method collects the synchronization data and puts it in a global, ready for export.
If you wish to simply synchronize all transactions since the last synchronization, invoke
the method in the following form:
Using Caché Objects 151

Object Synchronization
Do SrcSyncSet.AddTransactions(,,ExcludedDB)
This gets all transactions, beginning with the first unsynchronized transaction to the most
recent transaction. The method uses information in the SyncTime table to determine the
values.
ExcludedDB is a $List assembled from the code:
Set ExcludedDB = $ListBuild(##class(%SYS.System).InstanceGUID(),$ZUtil(5))
where
• ##class(%SYS.System).InstanceGUID() returns the value of the GUID that has
been established for the local Caché instance.
• $ZUtil(5) returns the value of the current namespace for the local Caché instance.
3. After running AddTransactions, run the ErrCount method to determine how many
errors were encountered. If there have been errors, the SyncSet.Errors query provides
more detailed information.
4. Export the data to a local file using the ExportFile method:
Do SrcSyncSet.ExportFile(file,displaymode,bUpdate)
where
• file is the file to which the transactions are being exported; it is a name with a relative
or absolute path.
• displaymode specifies whether or not output appears for the method's actions, where
“d” specifies that output appears and “-d” specifies that it is silent.
• bUpdate is a boolean that specifies whether or not the SyncTime table is updated
(where the default is 1, meaning True). It may be helpful to explicitly set this to 0 at
this point, and then set it to 1 after the source receives assurance that the target has
indeed received the data and performed the synchronization.
5. Move the exported file from the source database's machine to the target database's machine.
You can do this using various facilities available within Caché, such as Web services.
6. Create a SyncSet object on the target machine using the SyncSet.%New method. Use
the same value for the argument of %New as on the source machine — this is what
identifies the source of the synchronized transactions.
7. Read the SyncSet object into the Caché instance on the target machine using the Import
method:
152 Using Caché Objects

Set Status = TargetSyncSet.Import(file,lastSync,maxTS,displaymode,errorlog,diag)
where
• file is the file containing the data for import.
• lastSync is the last synchronized transaction number (default from synctime table).
• maxTS is the last transaction number in the SyncSet object.
• displaymode specifies whether or not output appears for the method's actions, where
“d” specifies that output appears and “-d” specifies that it is silent.
• errorlog provides a repository for any error information (and is called by reference
to provide information for the application).
• diag provides more detailed diagnostic information about what is happening when
importing
This method puts data into the target database. It behaves as follows:
a. If the method detects that the object has been modified on both the source and target
databases since the last synchronization, it invokes the
%ResolveConcurrencyConflict callback method; like other callback methods, the
content of %ResolveConcurrencyConflict is user-supplied. (Note that this can
occur if either the two changes both modified a common property or they were to
non-intersecting sets of properties.) If the %ResolveConcurrencyConflict method
is not implemented, then the conflict remains unresolved.
b. If, after the Import method executes, there are unsuccessfully resolved conflicts,
these remain in the SyncSet object as unresolved items. It is the responsibility of the
application programmer to take the appropriate action regarding the remaining conflicts;
this may involve resolution, leaving the items in an unresolved state, etc.
If this process completes, the Import method returns success.
Other Topics
8. Once the first database updates the second database, perform the same process in the
other direction so that the second database can update the first one.
17.3 Other Topics
This section addresses other actions related to object synchronization. These include:
Using Caché Objects 153

Object Synchronization
• Translating between GUIDs and OIDs
• Manually updating a SyncTime table
17.3.1 Translating Between GUIDs and OIDs
If you have the GUID or OID for an object and wish to ascertain its OID or GUID, there are
two methods available for this operation:
• %GUID.%GUIDFind(guid) is a class method of the %GUID class that takes a GUID
of an object instance and returns the OID associated with that instance.
• %Persistent.%GUID(oid) is a class method of the %Persistent class that takes an OID
of an object instance and returns the GUID associated with that instance; the method can
only be run if the class' GUIDENABLED parameter is TRUE. This method dispatches
polymorphically and determines the most-specific-type class if the OID does not contain
that information. If the instance has no GUID, the method returns an empty string.
17.3.2 Manually Updating a SyncTime Table
To perform a manual update on the SyncTime table for a database, invoke the SetlTrn method,
which sets the last transaction number:
Set Status=##class(%SyncTime).SetlTrn(syncSYSID, syncNSID, ltrn)
where
• syncSYSID is the ID of the source database's system. If the %occTransaction.inc header
file is included, this value is available through the $$$txSIDlocal macro.
• syncNSID is the ID of the relevant namespace. The $ZUtil(5) function returns the value
of the current namespace.
• ltrn is the last transaction number to be updated. You can get this value by invoking the
SyncSet's GetLastTransaction method.
154 Using Caché Objects

18
Method Generators
A powerful feature of Caché Object is the ability to define method generators: small programs
that are invoked by the Class Compiler to generate the runtime code for a method.
Method generators are used extensively within the Caché Class Library. For example, most
of the methods of the %Persistent class are implemented as method generators. This makes
it possible to give each persistent class customized storage code, instead of less efficient,
generic code. Most of the Caché data type class methods are also implemented as method
generators. Again, this gives these classes the ability to provide custom implementations that
depend on the context in which they are used.
You can use method generators within your own applications. A common usage is to define
one or more “utility” superclasses that provide specialized methods for the subclasses that
use them. The method generators within these utility classes create special code based on the
definition (properties, methods, parameter values, etc.) of the class that uses them. Good
examples of this technique are the %Populate and %XML.Adaptor classes provided within the
Caché library.
18.1 Defining a Method Generator
A method generator is simply a method of a Caché class that has its CodeMode keyword set
to “objectgenerator” :
Using Caché Objects 155

Method Generators
Class MyApp.MyClass Extends %RegisteredObject
{
Method MyMethod() [ CodeMode = objectgenerator ]
{
Do %code.WriteLine(" Write """ _ %class.Name _ """")
Do %code.WriteLine(" Quit")
Quit $$$OK
}
}
When the class MyApp.MyClass is compiled, it ends up with a MyMethod method with the
following implementation:
Write "MyApp.MyClass"
Quit
Note:
The value of CodeMode in the previous example is “objectgenerator” , since this
method generator uses the preferred, object-based, method generator mechanism.
Prior to version 5 of Caché, there was a different preferred mechanism, in which the
value of CodeMode was “generator” . While the older mechanism is preserved for
compatibility, new applications should use “objectgenerator” .
18.2 How Method Generators Work
The operation of a method generator is straightforward. When you compile a class definition,
the Class Compiler does the following:
1. It resolves inheritance for the class (builds a list of all inherited members).
2. It makes a list of all methods specified as method generators (by looking at the CodeMode
keyword of each method).
3. It gathers the code from all method generators, copies it into one or more temporary
routines, and compiles them (this makes it possible to execute the method generator code).
4. It creates a set of transient objects that represent the definition of the class being compiled.
These objects are made available to the method generator code.
5. It executes the code for every method generator.
If present, the compiler will arrange the order in which it invokes the method generators
by looking at the value of the GenerateAfter keyword for each of the methods. This
keyword gives you some control in cases where there may be compiler timing dependencies
among methods.
156 Using Caché Objects

Method Generator Context
6. It copies the results of each method generator (lines of code plus any changes to other
method keywords) into the compiled class structure (used to generate the actual code for
the class).
Note that the original method signature (arguments and return type), as well as any method
keyword values, are used for the generated method. If you specify a method generator
as having a return type of %Integer, then the actual method will have a return type of
%Integer.
7. It generates the executable code for the class by combining the code generated by the
method generators along with the code from all the non-method generator methods.
18.3 Method Generator Context
The key to implementing method generators is understanding the context in which method
generator code is executed. As described in the previous section, the class compiler invokes
the method generator code at the point after it has resolved class inheritance but before it has
generated code for the class. When it invokes method generator code, the class compiler
creates the following object instances and makes them available to the method generator
code:
Objects Available to Method Generators
Object
%code
%class
%method
%compiledclass
%compiledmethod
Description
An instance of the %Stream.MethodGenerator class. This is a
stream into which you write the code for method.
An instance of the %Dictionary.ClassDefinition class. It contains
the original definition of the class being compiled.
An instance of the %Dictionary.MethodDefinition class. It contains
the original definition of the method being compiled.
An instance of the %Dictionary.CompiledClass class. It contains
the compiled definition of the class being compiled. It contains
information about the class after inheritance has been resolved
(such as the list of all properties and methods, including those
inherited from superclasses).
An instance of the %Dictionary.CompiledMethod class. It contains
the compiled definition of the method being generated.
Using Caché Objects 157

Method Generators
In addition to these objects, an array variable, %parameter, is provided. This array contains
the values of any class parameters indexed by parameter name. For example,
%parameter("MYPARM"), contains the value of the MYPARM class parameter for the current
class. This variable is provided as an easier alternative to using the list of parameter definitions
available via the %class object.
18.4 Implementing Method Generators
To implement a method generator, do the following:
1. Define a method and set its CodeMode keyword to “objectgenerator” .
2. In the body of the method, write code that will generate the actual method code when
the class is compiled. This code will used the %code object to write out the code. It will
most likely use the other available objects as inputs to decide what code to generate.
The following is an example of a method generator that creates a method that lists the names
of all the properties of the class it belongs to:
ClassMethod ListProperties() [ CodeMode = objectgenerator ]
{
For i = 1:1:%compiledclass.Properties.Count() {
Set prop = %compiledclass.Properties.GetAt(i).Name
Do %code.WriteLine(" Write """ _ prop _ """,!")
}
Do %code.WriteLine(" Quit")
Quit $$$OK
}
This generator will create a method with an implementation similar to:
Write "Name",!
Write "SSN",!
Quit
Note the following about the method generator code:
1. It uses the WriteLine method of the %code object to write lines of code to a stream
containing the actual implementation for the method. (You can also use the Write method
to write text without an end-of-line character).
2. Each line of generated code has a leading space character. This is required as Caché
ObjectScript does not allow commands within the first space of a line. This would not
be the case if our method generator is creating Basic or Java code.
158 Using Caché Objects

Implementing Method Generators
3. As the lines of generated code appear within strings, you have to be very careful about
escaping quotation mark characters by doubling them up ("").
4. To find the list of properties for the class, it uses the %compiledclass object. It could use
the %class object, but then it would only list properties defined within the class being
compiled; it would not list inherited methods.
5. It returns a status code of $$$OK, indicating that the method generator ran successfully.
This return value has nothing to do with the actual implementation of the method.
18.4.1 Method Generators for Other Languages
At this time, method generators are implemented using Caché ObjectScript.
You can, however, generate code for different languages by setting the Language keyword
to the desired language. The available choices are “cache” , “basic” , and “java” . (A Java
method only appears in the Java class projected for this class definition).
For example, the following is the stub of a method generator that generates Java code for a
Java-projected class:
Method JavaStub() As %Integer [ CodeMode = objectgenerator, Language = java ]
{
// WriteLine statements with Java code to be generated
}
18.4.2 Specifying CodeMode within a Method Generator
By default, a method generator will create a “code” method (that is, the CodeMode keyword
for the generated method is set to “code” ). You can change this using the CodeMode property
of the %code object.
For example, the following method generator will generate an ObjectScript expression method:
Method Double(%val As %Integer) As %Integer [ CodeMode = objectgenerator ]
{
Set %code.CodeMode = "expression"
Do %code.WriteLine("%val * 2")
}
Using Caché Objects 159

19
The Caché Data Population Utility
Caché includes a utility for creating random test data for persistent classes. The creation of
such data is known as data population; the utility for doing this, known as the Caché populate
utility, is useful for testing persistent classes before deploying them within a real application.
It is especially helpful when testing how various parts of an application will function when
they are working against a large set of data.
The populate utility takes its name from its principal element — the %Populate class, which
is part of the Caché class library. Classes that inherit from %Populate contain a method called
Populate, which allows you to generate and save class instances containing random data
values. You can also customize the behavior of the %Populate class to provide data for your
application's needs.
Along with the %Populate class, the populate utility uses %PopulateUtils. %Populate provides
the interface to the utility, while %PopulateUtils is a helper class.
19.1 Data Population Basics
It is quite simple to populate a class with test data:
1. Include the populate utility functionality as part of the class definition by making
%Populate one of its superclasses.
2. Compile the class.
3. Invoke the populate utility, which creates test data.
Using Caché Objects 161

The Caché Data Population Utility
19.1.1 Changes to the Class Definition
To use the populate utility, simply add %Populate to the end of a class' list of superclasses,
so that it inherits the interface methods. For example, if a class inherits directly from
%Persistent, its new superclass list would be:
Class MyApp.MyClass Extends (%Persistent,%Populate) ...
Do not use %Populate as a primary superclass; that is do not list it as the first class in the
superclass list.
When using the New Class Wizard within the Caché Studio, you can specify that a new class
supports “automatic data population” . This is equivalent to adding the %Populate class to
the superclass list.
Once you have changed the class definition, re-compile the class so that you can populate
instances with data.
19.1.2 Populating Objects
To create new instances of a class and populate them with dummy data, simply run the
Populate class method inherited from the %Populate class at the command line in the Caché
terminal:
Do ##class(Person).Populate()
By default, Populate creates 10 new objects, populates their literal properties with random
data, and saves them in the database. It also populates reference properties if the referenced
class contains any objects, collections of data types, collections of persistent objects, and
indexes defined for the class.
If you prefer, you can specify the number of objects to create:
Do ##class(Person).Populate(num)
where num is the number of objects that you want.
Note:
After using the populate utility to create sample data, you must manually delete the
class extent (set of all object instances) in order to have an empty set of objects. You
can do this using either the %DeleteExtent() method (safe) or the %KillExtent()
method (fast) of the persistent interface. For more information, see the section
Deleting Objects in the chapter “Object Persistence.”
162 Using Caché Objects

Unless otherwise configured, Caché uses random data to populate the class. In cases with
defined constraints, such as a minimum or maximum length, some of the generated data may
not pass validation, so that individual objects will not be saved. In these situations, Populate
may create fewer than the specified number of objects. To allow you to check this, Populate
returns the number of objects actually populated:
Set objs = ##class(Person).Populate(100)
// objs is set to the number of objects created.
// objs will be less than or equal to 100
The populate utility is aware of the MAXVAL and MINVAL parameters and automatically
creates data that obeys these conditions for properties of type %Integer.
19.1.2.1 Object-valued Properties
The populate utility can automatically generate values for object-valued properties —
embedded objects as well as references to other persistent objects. This allows you to test or
demonstrate more complex objects and classes.
To enable population for these properties:
1. Include %Populate among the superclasses of the referenced class.
2. Create one or more instances of the referenced class.
The POPSPEC Parameter
This ensures that there are valid objects for the object-valued properties to point to.
19.2 The POPSPEC Parameter
The populate utility can provide data for properties containing embedded objects, lists, arrays,
and combinations of these with object-valued properties; it also allows you to customize the
data of certain data type properties.
To perform this kind of data population, provide a value for a property's POPSPEC parameter
by having it reference a method for generating data. If POPSPEC has a value, then the
Populate method invokes the referenced method to generate a value for the property. This
method can be user-provided or one of the methods of the %PopulateUtils class (provided
within the Caché library). Methods of %PopulateUtils provide data such as the names of
people, states, countries, or street address in the United States. Refer to the class' documentation
for a complete list of available methods.
To use POPSPEC, set its value as part of a property definition, as follows:
Using Caché Objects 163

The Caché Data Population Utility
Property PropertyName As %String(POPSPEC = "MethodToInvoke()");
where PropertyName is the property for which you are generating data and MethodToInvoke
is the method that Populate will call to generate the data.
For example, to specify that a property is the name of a city in the United States, add the
following POPSPEC parameter value to its definition:
Property City As %String(POPSPEC = "USCity()");
When you run the Populate method, it will invoke the USCity method of the %PopulateUtils
class to generate a random city name for this property.
The value of the POPSPEC parameter is a string specifying a method name in one of the
following ways:
• POPSPEC = “Method()” — Populate invokes the method “Method” from the
%PopulateUtils class.
• POPSPEC = “.Method()” — Populate invokes the method “Method” from the current
object instance (the one being populated).
• POPSPEC = “##class(Class).Method()” — Populate invokes the method “Method”
from the “Class” class.
Where applicable, you can include parameter values within the parentheses following the
method name. If you are specifying a string value, use two pairs (““””) of quotation marks
around the value that you specify.
Property Name As %String(POPSPEC = ".MyName(""X"")");
For example, suppose a class definition contains the following code:
Property PName As %String(POPSPEC = "PName:Name(""F"")");
Property Code As %String(POPSPEC = ".MakeCode()");
Property SSN As %String(POPSPEC = "##class(MyApp.Utils).MakeSSN()");
Property Number As %Integer;
Populate generates values for the PName property by calling the method:
Set .. PName = ##class(%PopulateUtils).Name("F")
Populate generates values for the Code property by calling the local class' MakeCode method:
Set ..Code = obj.MakeCode()
where obj is the current object instance being created. (This assumes that you have defined
a MakeCode method in the class.)
164 Using Caché Objects

Populate generates values for the SSN property by calling the MakeSSN method of the
MyApp.Utils class:
Set ..SSN = ##class(MyApp.Utils).MakeSSN()
Populate generates values for the Number that are random integers.
The POPSPEC Parameter
Note:
There is also a POPSPEC parameter defined at the class level that controls data
population for an entire class. This is an older mechanism (included for compatibility)
that is replaced by the property-specific POPSPEC parameter.
19.2.1 Populating Embedded Objects
The Populate method creates data for an embedded object by calling its PopulateSerial
method (which is generated by the %Populate class). This is done by default as long as the
embedded object inherits from the %Populate class and is equivalent to:
Property Home As Address(POPSPEC="##class(Address).PopulateSerial()");
19.2.2 Populating Lists
To populate a list, the syntax for setting the value of POPSPEC is:
Property PropName As TypeName (POPSPEC="MethodName:MaxNo") [Collection= list];
where PropName is a list of type TypeName; MethodName is the populating method for the
property; and MaxNospecifies the maximum number of elements in the list. If maxnum is not
specified, it defaults to 10.
The value ofMethodName depends on the type of list:
• Lists of data types typically use the %PopulateUtils method corresponding to their data
type.
• Lists of persistent objects should use an empty value for MethodName to take advantage
of the default automatic reference population (as occurs for simple, non-collection reference
properties).
• Lists of embedded objects must use the PopulateSerial method.
In the following example, there are lists of several types of data. Colors is a list of strings,
Kids is a list of references to persistent objects, and Addresses is a list of embedded objects:
Using Caché Objects 165

The Caché Data Population Utility
Property Colors As %String(POPSPEC="ValueList("",Red,Green,Blue"")")
[Collection = list];
Property Kids As Person(POPSPEC=":5")
[Collection = list];
Property Addresses As Address(POPSPEC=":3")
[Collection = list];
Note:
In Studio, each property definition needs to appear on a single line.
For the Colors property, the Populate method generates data using the ValueList method of
the PopulateUtils class, and follows basic POPSPEC syntax. For the Kids property, there is
no specified method, which results in automatically generated references. For the Addresses
property, there is
19.2.3 Populating Arrays
To populate an array, the syntax for setting the value of POPSPEC is:
Property Prop As TypeNm (POPSPEC="MethodNm:MaxNo:KeySpec") [Collection= array];
where Prop is an array of type TypeNm; MethodNm is the populating method for the property;
MaxNospecifies the maximum number of elements in the list; and KeySpec is the populating
method used to generate the key for each element of an array. If MaxNo is not specified, it
defaults to 10. If KeySpec is not specified, it defaults to String.
In the following example, there are arrays of several types of data and different kinds of keys
being generated as well:
Property Tix As %Integer(POPSPEC="Integer():20:Date()") [Collection = array];
Property Reviews As Review(POPSPEC=":3:Date()") [Collection = array];
Property Actors As Actor(POPSPEC=":15:Name()") [Collection = array];
The Attendance property has its data generated using the ValueList method of the PopulateUtils
class; its keys are generated using the Date method of the PopulateUtils class. The Tix property
has no specified method, which results in automatically generated references , and has its
keys also generated using the Date method. The Actors property has no specified method,
which results in automatically generated references, and has its keys generated using the
Name method of the PopulateUtils class.
19.2.4 Custom Populate Actions
To perform custom actions with the Populate method, use the OnPopulate callback method.
166 Using Caché Objects

Details
19.3 Details
This section describes how %Populate works internally. The %Populate class contains two
method generators: Populate and PopulateSerial. Each persistent or serial class inheriting
from %Populate has one or the other of these two methods included in it (as appropriate).
We will describe only the Populate method here. The Populate method is a loop, that is
repeated for each of the requested number of objects.
Inside the loop, the code:
• Creates a new object
• Sets values for its properties
• Saves and closes the object
A simple property with no overriding POPSPEC parameter has a value generated using code
with the form:
Set obj.Description = ##class(%PopulateUtils).String(50)
While using a library method from %PopulateUtils via a “Name:Name()” specification would
generate:
Set obj.Name = ##class(%PopulateUtils).Name()
An embedded Home property might create code like:
Do obj.HomeSetObject(obj.Home.PopulateSerial())
The generator loops through all the properties of the class, and creates code for some of the
properties, as follows:
• It checks if the property is private, is calculated, is a collection, or has an initial expression
(in that order). If any of these are true, the generator exits.
• If the property is has a POPSPEC override, the generator uses that and then exits.
• If the property is a reference, on the first time through the loop, the generator builds a
list of random IDs, takes one from the list, and then exits. For the subsequent passes, the
generator simply takes an ID from the list and then exits.
• If the property name either “Name” , “SSN” , “Company” , “Title” , “Phone” , or
“Zip” , the generator then uses the corresponding library method “Name” , “SSN” ,
“Company” , “Title” , “USPhone” , or “USZip” . It then exits.
Using Caché Objects 167

The Caché Data Population Utility
• If the property type is %String, %Integer, %Date, or %Name, the generator then uses the
corresponding library method “String(MAXLEN)” , “Integer(MINVAL,MAXVAL)”
, “Date” , or “Name” . It then quits.
• Otherwise, the generator sets the property's value to “” .
Refer to the %PopulateUtils class for a list of available methods.
168 Using Caché Objects

20
Using Callback Methods
Callback methods are called by system methods to allow additional user written processing
during specific events. To distinguish these types of methods, they are given names of the
form %OnEvent or OnEvent, where Event describes the event that triggers the callback.
If an event supports a callback method, the method controlling the event automatically executes
the callback method it if it exists. You should never explicitly execute callback methods.
Caché supports the following callback methods:
• %OnAddToSaveSet
• %OnAfterSave
• %OnBeforeSave
• %OnClose
• %OnConstructClone
• %OnDelete
• %OnDetermineClass
• %OnNew
• %OnOpen
• %OnRollBack
• %OnValidateObject
• OnPopulate
Using Caché Objects 169

Using Callback Methods
Since different types of classes support different events, not all callback methods are available
to all classes. For example, callback methods triggered by saving or deleting an object cannot
be accessed by registered objects since these objects cannot be saved or deleted.
With the exception of %OnDetermineClass, these methods can be used to perform any
processing desired at the relevant event.
%OnDetermineClass is a special case. When %Open or %Delete is given a partially-formed
OID, it calls the %OnDetermineClass method, if the user has provided one, to obtain the
actual class name. If %OnDetermineClass indicates the object belongs to a different class,
%Open or %Delete will dispatch to the new class' %Open or %Delete method. If there is
no %OnDetermineClass method, %Open and %Delete simply assume the current class is
the correct class.
20.1 %OnAddToSaveSet
This instance method is called by the %AddToSaveSet method. The %AddToSaveSet
method itself is called on an object whose %Save method has been invoked, as well as all
other objects referenced by that object that have been loaded into memory. %AddToSaveSet
can also be invoked directly from %OnAddToSaveSet. If %OnAddToSaveSet modifies
another object, then it is the responsibility of %OnAddToSaveSet to invoke %AddToSaveSet
on that modified object.
When you invoke %Save on an object, called, for example, MyPerson, Caché generates a
list of objects that MyPerson references. A SaveSet is the list of objects consisting of the
object to be saved and all the objects that it references. In the example, the SaveSet might
include referenced objects MySpouse, MyDoctor, and so on.
The syntax of %OnAddToSaveSet is:
ReturnValue %OnAddToSaveSet(SaveDepth As %Integer, Insert As %Integer,
CallCount As %Integer)
where:
170 Using Caché Objects

%OnAfterSave
ReturnValue
SaveDepth
Insert
CallCount
A %Status code, where an error code causes the save to fail and the
transaction to be rolled back.
An integer value passed in from %AddToSaveSet that represents
the internal state of SaveSet construction. If you use
%OnAddToSaveSet to add any other records to the SaveSet, pass
this value to %AddToSaveSet without change.
A flag indicating if the object being saved is being inserted into the
extent (1) or that it is already part of the extent (0).
The number of times that %OnAddToSaveSet has been called for
this object. Due to the networked nature of object references it is
possible that %AddToSaveSet can be invoked on the same object
multiple times.
You can update objects, create new objects, delete objects and ask objects to include themselves
in the current SaveSet by calling %AddToSaveSet. If you modify the current instance
or any of its descendants, you must let the system know that you have done this by calling
%AddToSaveSet for the modified instance(s) and passing a value of 1 for the method's
Refresh argument.
None of the modification restrictions imposed on %OnAfterSave, %OnBeforeSave, or
%OnValidateObject are in place for %OnAddToSaveSet.
If you delete an object using %OnAddToSaveSet, you need to call %RemoveFromSaveSet
to clean up any dangling references to it.
This method is available to the %Library.RegisteredObject class and its subclasses.
20.2 %OnAfterSave
This instance method is called by the %Save method just after an object is saved. This method
allows you to perform actions outside the scope of the object being saved, such as queueing
a later notification action; an example of this is a bank using the deposit in excess of a certain
amount to cause it to send the customer an explanation of its deposit policies.
Its syntax is:
ReturnValue %OnAfterSave(Insert as Boolean)
where:
Using Caché Objects 171

Using Callback Methods
ReturnValue
Insert
A %Status code, where returning a failure status from %OnAfterSave
causes %Save to fail and ultimately roll back the transaction.
A flag indicating if the object being saved is being inserted into the
extent (1) or that it is already part of the extent (0).
This method is available to the %Library.Persistent class and its subclasses.
20.3 %OnBeforeSave
This instance method is called by the %Save method just before an object is saved. This
method allows you to request user confirmation before completing an action and can also
serve to ensure the validity of an instance's data and relationships prior to saving the instance
to disk.
Its syntax is:
ReturnValue %OnBeforeSave(Insert as Boolean)
where:
ReturnValue
Insert
A %Status code, where an error code causes the save to fail.
A flag indicating if the object being saved is being inserted into the
extent (1) or that it is already part of the extent (0).
This method is available to the %Library.Persistent class and its subclasses.
20.4 %OnClose
This instance method is called by the %Close method just before an object is closed. One
use of this method is to release resources that Caché does not directly control, but are logically
related to the application, such when an object represents a communication device and closing
the object invokes the %OnClose code to drop the connection.
172 Using Caché Objects

%OnConstructClone
Its syntax is:
ReturnValue %OnClose()
where:
ReturnValue
A %Status code. The return value is not used by %Close.
This method is available to the %Library.RegisteredObject class and its subclasses.
20.5 %OnConstructClone
This instance method is called by the %ConstructClone method immediately after the
structures have been allocated for the cloned object and all the data has been copied into it.
The method allows you to perform any additional actions related to the cloned object, such
as taking out a lock or resetting any of the clone's property values.
Its syntax is:
ReturnValue %OnConstructClone(Object As %RegisteredObject, Deep As
%Boolean)
where:
ReturnValue
Object
Deep
A %Status code, where an error code prevents the clone from being
created.
The OREF of the object that was cloned.
How “deep” the cloning process is, where 0 specifies that the clone
points to the same related objects as the original; 1 causes objects
related to the object being cloned to also be cloned, so that the clone
gets its own set of related objects.
This method is available to the %Library.RegisteredObject class and its subclasses.
Using Caché Objects 173

Using Callback Methods
20.6 %OnDelete
This class method is called by the %Delete method just before an object is deleted. This
method can be used to ensure that deleting an object does corrupt data integrity, such as by
ensuring that an object designed to contain other objects is only deleted when it is empty.
Its syntax is:
ReturnValue %OnDelete(OID AS %ObjectIdentity)
where:
ReturnValue
OID
A %Status code, where an error code stops the deletion.
An object identifier for the object being deleted.
This method is available to the %Library.Persistent class and its subclasses.
20.7 %OnDetermineClass
This class method is called by the %Delete, %Oid, and %Open methods when one of these
receives a partially-formed OID as an argument. The purpose of %OnDetermineClass is to
supply a class name to its calling method.
Its syntax is:
ReturnValue %OnDetermineClass(OID As %ObjectIdentity, ByRef Class As
%String)
where:
ReturnValue
OID
Class
A %Status code, where behavior depends on the calling routine. If
invoked by %Open, the attempt to open the object fails, no OREF is
returned, and the error status is passed back to the caller. If invoked
by %Delete, the attempt to delete the object fails.
The instance with the partially-formed name
A string in which the name of the instance's class is placed.
This method is available to the %Library.Persistent class and its subclasses.
174 Using Caché Objects

%OnNew
20.8 %OnNew
This instance method is called by the %New method at the point when all the storage for an
object has been allocated and properties with initial values have had their values set. This
method allows you to pass initialization information to a new instance, such as the location
where an object resides on disk or a unique identifier.
Its syntax is:
ReturnValue %OnNew(InitialValue As %CacheString)
where:
ReturnValue
InitialValue
A %Status code, where an error stops the creation of the object.
A string that the method uses in setting up the object.
This method is available to the %Library.RegisteredObject class and its subclasses.
20.9 %OnOpen
This instance method is called by the %Open method just before an object is opened. It
allows you to verify the state of an instance compared to any relevant entities; for instance,
you can use the method also to ensure the function of an object's real-world analog.
Its syntax is:
ReturnValue %OnOpen()
where:
ReturnValue
A %Status code, where an error stops the opening of the object.
This method is available to the %Library.Persistent class and its subclasses.
Using Caché Objects 175

Using Callback Methods
20.10 %OnRollBack
This instance method is called by the %Save method if an object cannot be saved. This
method holds code that performs rollback-related actions on objects other than the one being
rolled back. At the time when this method is invoked, the state of the object may be inconsistent
with other objects; you can use %OnRollBack to correct this condition.
Its syntax is:
ReturnValue %OnRollBack()
where:
ReturnValue
A %Status code, where an error stops the rollback operation.
This method is available to the %Library.Persistent class and its subclasses.
20.11 %OnValidateObject
This instance method is called by the %ValidateObject method just after all validation has
occurred. This allows you to perform content-dependent validation, such as where valid values
for one property vary according to the value of another property.
Its syntax is:
ReturnValue %OnValidateObject()
where:
ReturnValue
A %Status code, where an error causes the validation to fail.
This method is available to the %Library.RegisteredObject class and its subclasses.
176 Using Caché Objects

OnPopulate
20.12 OnPopulate
This instance method is called by the Populate method after assigning values to an object's
properties but before the object is saved to disk. This method provides additional control over
the generated data. If an OnPopulate method exists, then the Populate method calls it for
each object that it generates.
Its syntax is:
ReturnValue %OnPopulate()
where:
ReturnValue
A %Status code, where a failure status causes the instance being
populated to be discarded.
For example, if you have a stream property, Memo, and wish to assign a value to it when
populating, you can provide an OnPopulate method:
Method OnPopulate() As %Status
{
Do ..Memo.Write("Default value");
QUIT $$$OK
}
This method is available to the %Library.Populate class and its subclasses. See the chapter
The Caché Data Population Utility for more information on data population generally.
Using Caché Objects 177

21
Object-Specific ObjectScript
Features
ObjectScript includes a number of features that provide special functionality within object
methods. These are:
• .. Syntax — For accessing a property or calling a method of the current object
• ##Class Syntax — For invoking a class method or for casting an object reference as
another class to call a method
• ##this Syntax — For getting a handle to the OREF of the current instance, such as for
passing it to another class or for another class to refer to the current instance's members.
• ##super Syntax — For invoking a superclass method from within a subclass method
• i% Syntax — For referencing an instance variable from within its own
Get or Set accessor method, or bypassing its Get or Set method
21.1 .. Syntax
The .. syntax provides a mechanism for referencing another method or property of the current
object. For example, suppose there is a Bricks property of type %Integer:
Property Bricks As %Integer;
A CountBricks method can then refer to Bricks with .. syntax:
Using Caché Objects 179

Object-Specific ObjectScript Features
Method CountBricks()
{
Write "There are ",..Bricks," bricks.",!
}
Similarly, a WallCheck method can refer to CountBricks and Bricks with .. syntax:
Method WallCheck()
{
Do ..CountBricks()
If ..Bricks < 100 {
Write "Your wall will be small."
}
}
21.2 ##Class Syntax
The ##class syntax allows you to:
• Invoke a class method when there is no existing or open instance of a class.
• Cast a method from one class as a method from another.
Note:
##class is case insensitive.
21.2.1 Invoking a Class Method
To invoke a class method, the syntax is either of the following:
>Do ##class(Package.Class).Method(Args)
>Set localname = ##class(Package.Class).Method(Args)
It is also valid to use ##class as part of an expression, as in
Write ##class(Class).Method(args)*2
without setting a variable equal to the return value.
A frequent use of this syntax is in the creation of new instances:
>Set LocalInstance = ##class(Package.Class).%New()
21.2.2 Casting a Method
To cast a method of one class as a method of another class, the syntax is either of the following:
180 Using Caché Objects

##this Syntax
>Do ##class(Package.Class1)Class2Instance.Method(Args)
>Set localname = ##class(Package.Class1)Class2Instance.Method(Args)
You can cast both class methods and instance methods.
For example, suppose that two classes, MyClass.Up and MyClass.Down, both have Go methods.
The code of MyClass.Up.Go is:
Method Go()
{
Write "Go up.",!
}
and the code of MyClass.Down.Go is:
Method Go()
{
Write "Go down.",!
}
You can then create an instance of MyClass.Up and use it to invoke the MyClass.Down.Go
method:
>Set LocalInstance = ##class(MyClass.Up).%New()
>Do ##class(MyClass.Down)LocalInstance.Go()
Go down.
It is also valid to use ##class as part of an expression, as in
Write ##class(Class).Method(args)*2
without setting a variable equal to the return value.
A more generic way to refer to other methods are the $ZObjMethod and $ZObjClassMethod
functions, which are for instance and class methods, respectively. These provide a mechanism
for referring to packages, classes, and methods programmatically.
21.3 ##this Syntax
The ##this syntax provides a handle to the OREF of the current instance, such as for passing
it to another class or for another class to refer to the current instance's members. When an
instance refers to its own members, the .. syntax is preferred.
Note:
##this is case sensitive and must be in all lowercase.
Using Caché Objects 181

Object-Specific ObjectScript Features
For example, suppose there is an application with an Accounting.Order class and an
Accounting.Utils class. The Accounting.Order.CalcTax method calls the
Accounting.Utils.GetTaxRate and Accounting.Utils.GetTaxableSubtotal methods, passing the
current instance's city and state values to GetTaxRate and passing the list of items ordered
and relevant tax-related information to GetTaxableSubtotal. CalcTax then uses the values
returned to calculate the sales tax for the order. Hence, its code is something like:
Method CalcTax() As %Numeric
{
Set TaxRate = ##Class(Accounting.Utils).GetTaxRate(##this)
Write "The tax rate for ",..City,", ",..State," is ",TaxRate*100,"%",!
Set TaxableSubtotal = ##class(Accounting.Utils).GetTaxableSubTotal(##this)
Write "The taxable subtotal for this order is $",TaxableSubtotal,!
Set Tax = TaxableSubtotal * TaxRate
Write "The tax for this order is $",Tax,!
}
The first line of the method uses the ##Class syntax (described above) to invoke the other
class' method; it passes the current object to that method using the ##this syntax. The second
line of the method uses the .. syntax (also described above) to get the values of the instance's
City and State properties. The action on the third line is similar to that on the first line.
The Accounting.Utils class' GetTaxRate method can then use the handle to the passed-in
instance to get handles to various properties — for both getting and setting their values:
ClassMethod GetTaxRate(OrderBeingProcessed As Accounting.CustOrder) As %Numeric
{
Set LocalCity = OrderBeingProcessed.City
Set LocalState = OrderBeingProcessed.State
// code to determine tax rate based on location and set
// the value of OrderBeingProcessed.TaxRate accordingly
Quit OrderBeingProcessed.TaxRate
}
The GetTaxableSubtotal method also uses the handle to the instance to look at its properties
and set the value of its TaxableSubtotal property.
Hence, the output at the Caché terminal from invoking the CalcTax method for MyOrder
instance of the Accounting.Order class would be something like:
>Do MyOrder.CalcTax()
The tax rate for Cambridge, MA is 5%
The taxable subtotal for this order is $79.82
The tax for this order is $3.99
182 Using Caché Objects

##super Syntax
21.4 ##super Syntax
Suppose that a subclass method overrides a superclass method. From within the subclass
method, you can use the ##super() syntax to invoke the overridden superclass method.
Note:
##super is case sensitive and must be in all lowercase.
For example, suppose that the class MyClass.Down extends MyClass.Up and overrides the
Simple class method. If the code for MyClass.Up.Simple is:
ClassMethod Simple()
{
Write "Superclass.",!
}
and the code for MyClass.Down.Simple is:
ClassMethod Simple()
{
Write "Subclass.",!
Do ##super()
}
then the output for subclass method, MyClass.Down.Simple, is:
>Do ##Class(MyClass.Down).Simple()
Subclass.
Superclass.
>
##super also works with methods that accept arguments. For example, if the code for
MyClass.Up.SelfAdd is:
ClassMethod SelfAdd(Arg)
{
Write Arg,!
Write Arg + Arg
Quit
}
then its output is:
>Do ##Class(MyClass.Up).SelfAdd(2)
2
4
>
If the code for MyClass.Down.SelfAdd is:
Using Caché Objects 183

Object-Specific ObjectScript Features
ClassMethod SelfAdd(Arg1 As %Integer)
{
Do ##super(Arg1)
Write !
Write Arg1 + Arg1 + Arg1
Quit
}
then its output is:
>Do ##Class(MyClass.Down).SelfAdd(2)
2
4
8
>
A more generic way to refer to other methods are the $ZObjMethod and $ZObjClassMethod
functions, which are for instance and class methods, respectively. These provide a mechanism
for referring to packages, classes, and methods programmatically.
21.5 i% Syntax
When you instantiate a class with a persistent property, Caché creates what is called an
instance variable, which holds the property's value. When you set or refer to a property value,
Caché invokes what are called “Get” and “Set” accessor methods, which ultimately refer
to the instance variable. The accessor methods have names of the form Get
and Set, where is the name of property being accessed.
For example, if a class contains an LName property of type %String:
Property LName As %String;
then displaying the property's value for a particular instance
> Write MyClass.Up.LName
Pepperidge
actually goes through the MyClass.Up.LNameGet accessor method to get the value from
the property's instance variable.
Similarly, the typical call to set a property's value:
>Set MyClass.Up.LName = "Blutarsky"
actually invokes the MyClass.Up.LNameSet method, passing in the new value to set the
value of the instance variable and, thereby, that of LName.
184 Using Caché Objects

You can override a property's default accessor methods. In the last screen of the New Property
Wizard in the Studio, you can select the check boxes for creating a custom Get method, Set,
or both; if so the Studio creates signatures for the custom methods. Within the custom methods,
you can perform any special processing that your application requires.
Invoking a Set method from within a Set method creates a recursive series of references that
results in a stack overflow; likewise for Get methods. To avoid this situation, Caché provides
a mechanism for working with a property's instance value that circumvents the accessor
methods. This mechanism refers to a property's instance variable directly by using syntax of
i%, where is the name of property being accessed.
For example, to directly set the value of the LName instance variable, the “i%” syntax is:
Set i%LName = "Blutarsky"
i% Syntax
This directly sets “Blutarsky” as the value of the instance variable LName, bypassing the
LNameSet accessor. The advantage of this mechanism is that it gives you direct control over
the instance variable's value. This must be used with caution and only under appropriate circumstances,
since the ability to circumvent any checking done in the property's Set method
can result in properties containing non-valid values.
Using Caché Objects 185

22
Dynamic Dispatch
Caché classes can include support for what is called “dynamic dispatch.” If dynamic dispatch
is in use and a program references a property or method that is not part of the class definition,
then a method (called a “dispatch method” ) is called that attempts to resolve the undefined
method or property. For example, dynamic dispatch can return a value for a property that is
not defined or it can invoke a method for a method that isn't implemented. The dispatch destination
is dynamic in that it does not appear in the class descriptor and is not resolved until
runtime.
22.1 How Dynamic Dispatch Happens
Caché makes a number of dispatch methods available that you can implement. Each of these
methods attempts to resolve an element that is missing under different circumstances.
If you implement a dispatch method, it has the following effects:
• During application execution, if Caché encounters an element that is not part of the
compiled class, it invokes the dispatch method to try to resolve the encountered element.
• The application code that uses the class does not do anything special to make this happen.
Caché automatically checks for the existence of the dispatch method and, if that method
is present, invokes it.
Using Caché Objects 187

Dynamic Dispatch
22.2 Content of Methods Implementing Dynamic
Dispatch
As the application developer, you have control over the content of dispatch methods. The
code within them can be whatever is required to implement the methods or properties that
the class is attempting to resolve.
Code for dynamic dispatch might include attempts to locate a method based on other classes
in the same extent, package, database, on the same file system, or by any other criteria. If a
dispatch method provides a general case, it is recommended that the method also create some
kind of log for this action, so that there is a record of any continued operation that includes
this general resolution.
For example, the following implementation of %DispatchClassMethod allows the application
user to invoke a method to perform whatever action was intended:
ClassMethod %DispatchClassMethod(Class As %String, Method As %String, args...)
{
WRITE "The application has attempted to invoke the following method: ",!,!
WRITE Class,".",Method,!,!
WRITE "This method does not exist.",!
WRITE "Enter the name of the class and method to call",!
WRITE "or press Enter for both to exit the application.",!,!
READ "Class name (in the form 'Package.Class'): ",ClassName,!
READ "Method name: ",MethodName,!
}
IF ClassName = "" && MethodName = "" {
// return a null string to the caller if a return value is expected
QUIT:$QUIT "" QUIT
} ELSE {
// checking $QUIT ensures that a value is returned
// if and only if it is expected
IF $QUIT {
QUIT $ZOBJCLASSMETHOD(ClassName, MethodName, args...)
} ELSE {
DO $ZOBJCLASSMETHOD(ClassName, MethodName, args...)
QUIT
}
}
By including this method in a class that is a secondary superclass of all classes in an application,
you can establish application-wide handling of calls to non-existent class methods.
188 Using Caché Objects

The Dynamic Dispatch Methods
22.2.1 Return Values
None of the dispatch methods have specified return values. This is because each should provide
output that is of the same type of the call that originally created the need for the dispatch.
If the dispatch method cannot resolve the method or property, it can use $ZUTIL(96,3) to
throw a or error —
or whatever else may be appropriate.
22.3 The Dynamic Dispatch Methods
The following methods may be implemented to resolve unknown methods and properties:
• %DispatchMethod
• %DispatchClassMethod
• %DispatchGetProperty
• %DispatchSetProperty
• %DispatchSetMultidimProperty
• %DispatchGetModified
• %DispatchSetModified
22.3.1 %DispatchMethod
This method implements an unknown method call. Its syntax is:
Method %DispatchMethod(Method As %String, Args...)
where its first argument is the name of the referenced method and the second argument is an
array that holds all the arguments passed to the original method. Since the number of arguments
and their types can vary depending on the method being resolved, the code in
%DispatchMethod needs to handle them correctly (since the class compiler can not make
any assumptions about the type). The Args... syntax handles this flexibly.
Because %DispatchMethod attempts to resolve any unknown instance method associated
with the class, it has no specified return value; if successful, it returns a value whose type is
determined by the method being resolved and whether the caller expects a return value.
Using Caché Objects 189

Dynamic Dispatch
%DispatchMethod can also resolve an unknown multidimensional property reference —
that is, to get the value of a property. However, only direct multidimensional property references
are supported for dynamic dispatch. $DATA, $ORDER, and $QUERY are not supported,
nor is a SET command with a list of variables.
22.3.2 %DispatchClassMethod
This method implements an unknown class method call. Its syntax is:
ClassMethod %DispatchClassMethod(Class As %String, Method As %String, Args...)
where its first two arguments are the name of the referenced class and the name of the referenced
method. Its third argument is an array that holds all the arguments passed to the original
method. Since the number of arguments and their types can vary depending on the method
being resolved, the code in %DispatchClassMethod needs to handle them correctly (since
the class compiler can not make any assumptions about the type). The Args... syntax handles
this flexibly.
Because %DispatchClassMethod attempts to resolve any unknown class method associated
with the class, it has no specified return value; if successful, it returns a value whose type is
determined by the method being resolved and whether the caller expects a return value.
22.3.3 %DispatchGetProperty
This method gets the value of an unknown property. Its syntax is:
Method %DispatchGetProperty(Property As %String)
where its argument is the referenced property. Because %DispatchGetProperty attempts
to resolve any unknown property associated with the class, it has no specified return value;
if successful, it returns a value whose type is that of the property being resolved
22.3.4 %DispatchSetProperty
This method sets the value of an unknown property. Its syntax is:
Method %DispatchSetProperty(Property As %String, Value)
where its arguments are the name of the referenced property and the value that was being
attempted to be assigned to it.
190 Using Caché Objects

The Dynamic Dispatch Methods
22.3.5 %DispatchSetMultidimProperty
This method sets the value of an unknown multidimensional property. Its syntax is:
Method %DispatchSetMultidimProperty(Property As %String, Value, Subs...)
where its first two arguments are the name of the referenced property and the value that was
being attempted to be assigned to it. The third argument, Subs, is an array that contains the
subscript values. Subs has an integer value that specifies the number of subscripts, Subs(1)
has the value of the first subscript, Subs(2) has the value of the second, and so on. If no subscripts
are given, then Subs is undefined.
Only direct multidimensional property references are supported for dynamic dispatch. $DATA,
$ORDER, and $QUERY are not supported, nor is a SET command with a list of variables.
Note:
Note that there is no %DispatchGetMultidimProperty dispatch method. This is
because a multidimensional property reference is identical to a method call. Thus,
such a reference invokes %DispatchMethod, which must include code to differentiate
between method names and multidimensional property names.
22.3.6 %DispatchGetModified
This method gets the value of the modified flag for an unknown property. Its syntax is:
Method %DispatchGetModified(Property As %String)
where its argument is the name of the referenced property.
22.3.7 %DispatchSetModified
This method sets the value of the modified flag for an unknown property. Its syntax is:
Method %DispatchSetModified(Property As %String, Value)
where its arguments are the name of the referenced property and the value to set for its
modified flag.
Using Caché Objects 191

23
Class Definition Classes
The Caché Library includes a number of class definition classes that provide object access
to the Caché Unified Dictionary. Using these classes you can programmatically examine
class definitions, modify class definitions, create new classes, and even write programs that
automatically generate documentation. These classes are contained within a “%Dictionary”
package.
Note:
There is an older set of class definitions classes defined within the “%Library”
package. These are maintained for compatibility with existing applications. New
code should make use of the classes within the “%Dictionary” package. Make sure
that you specify the correct package name when using these classes or you may
inadvertently use the wrong class.
There are two parallel sets of class definition classes: those that represent defined classes and
those that represent compiled classes.
A defined class definition represents the definition of a specific class. It includes only information
defined by that class; it does not include information inherited from superclasses. In
addition to providing information about classes in the dictionary, these classes can be used
to programmatically alter or create new class definitions.
A compiled class definition includes all of the class members that are inherited from super
classes. A compiled class definition object can only be instantiated from a class that has been
compiled. You cannot save a compiled class definition.
This chapter discusses defined class definitions exclusively, though the operation of the
compiled class definitions is similar.
The family of class definition classes that represent defined classes includes:
Using Caché Objects 193

Class Definition Classes
Class
%Dictionary.AbstractDefinition
%Dictionary.ClassDefinition
%Dictionary.ForeignKeyDefinition
%Dictionary.IndexDefinition
%Dictionary.MethodDefinition
%Dictionary.ParameterDefinition
%Dictionary.PropertyDefinition
%Dictionary.QueryDefinition
%Dictionary.TriggerDefinition
Description
Abstract base class for all class definition classes.
Represents a class definition. Contains class keywords
as well as collections containing class member
definitions.
Represents a foreign key definition within a class.
Represents an index definition within a class.
Represents a method definition within a class.
Represents a parameter definition within a class.
Represents a property definition within a class.
Represents a query definition within a class.
Represents an SQL trigger definition within a class.
23.1 Browsing Class Definitions
You can use the class definition classes to browse through the class definitions within the
Caché dictionary using the same techniques you would use in a database application: you
can use the %ResultSet object to iterate over sets of classes and you can instantiate persistent
objects that represent specific class definitions.
For example, from within a Caché process you can get a list of all classes defined within the
dictionary for the current namespace by using the %Dictionary.ClassDefinition:Summary
query:
Set result = ##class(%ResultSet).%New("%Dictionary.ClassDefinition:Summary")
Do result.Execute()
While (result.Next()) {
Write result.Data("Name"),!
}
You can just as easily invoke this query from an ActiveX or Java client using the client
ResultSet object.
This %Dictionary.ClassDefinition:ClassInfo query will return all of the classes visible
from the current namespace (including classes in the system library). You can filter out
unwanted classes using the various columns returned by the
%Dictionary.ClassDefinition:Summary query.
194 Using Caché Objects

You can get detailed information about a specific class definition by opening a
%Dictionary.ClassDefinition object for the class and observing its properties. The ID used to
store %Dictionary.ClassDefinition objects is the class name:
Set cdef = ##class(%Dictionary.ClassDefinition).%OpenId("Sample.Person")
Write cdef.Name,!
// get list of properties
Set count = cdef.Properties.Count()
For i = 1:1:count {
Write cdef.Properties.GetAt(i).Name,!
}
Altering Class Definitions
You can also do this easily from an ActiveX or Java client. Note that you must fully-qualify
class names with their package name or the call to %OpenId will fail.
23.2 Altering Class Definitions
You can modify an existing class definition by opening a %Dictionary.ClassDefinition object,
making the desired changes, and saving it using the %Save method.
You can create a new class by creating a new %Dictionary.ClassDefinition object, filling in its
properties and saving it. When you create %Dictionary.ClassDefinition object you must pass
the name of the class via the %New command. When you want to add a member to the class
(such as a property or method) you must create the corresponding definition class (passing
its %New command a string containing "classname.membername") and add the object to the
appropriate collection within the %Dictionary.ClassDefinition object.
For example:
Set cdef = ##class(%Dictionary.ClassDefinition).%New("MyApp.MyClass")
If %SYSTEM.Status.IsError(cdef) {
Do DecomposeStatus^%apiOBJ(%objlasterror,.Err)
Write !, Err(Err)
}
Set cdef.ClassType = "persistent"
Set cdef.Super = "%Persistent,%Populate"
// add a Name property
Set pdef = ##class(%Dictionary.PropertyDefinition).%New("MyClass:Name")
If %SYSTEM.Status.IsError(pdef) {
Do DecomposeStatus^%apiOBJ(%objlasterror,.Err)
Write !,Err(Err)
}
Do cdef.Properties.Insert(pdef)
Set pdef.Type="%String"
// save the class definition object
Do cdef.%Save()
Using Caché Objects 195

24
Internet Classes
The Caché class library includes classes that provide an easy-to-use interface for a number
of useful Internet protocols. Using these classes your applications can:
• Send and receive email messages using the SMTP and POP protocols.
• Send and receive files using the FTP protocol.
• Make HTTP requests to an external HTTP Server.
• Parse URL strings into constituent pieces.
This chapter describes the these classes. You can also refer to the documentation for the
specific classes.
24.1 Email
Basically, email (electronic mail) works by sending messages (which have a specific format)
across the internet using a set of standard protocols. Caché provides classes that support two
of these protocols (SMTP and POP3). In addition, Caché provides a class, %Net.MailMessage,
that represents an object version of an email message.
24.1.1 Mail Messages
The %Net.MailMessage class is used to represent email messages for both sending and
receiving email. It contains properties that correspond to the various parts of an email message.
These properties are divided into those that represent the header (whom the message is
Using Caché Objects 197

Internet Classes
addressed to , its subject, etc.) and those that represent the content or body of the message.
The content properties are inherited from the %Net.MailMessagePart class.
24.1.1.1 Message Headers
The header information of the %Net.MailMessage class includes the following:
• To—the list of email addresses this message will be sent (or was sent) to.
• From—the email address this message is sent from. When sending email, your application
must provide a value for this property.
• Date—the date that this message was retrieved as reported by the mail server.
• Subject—a string containing the subject for this message.
• Sender—the actual sender of the message as reported by the mail server.
• Cc—the list of carbon copy addresses this message will be sent (or was sent) to.
24.1.1.2 Message Content
The content of an email message can vary from a simple block of text to complex data represented
using MIME.
24.1.2 Sending Email
Caché supports sending email messages using SMTP (Simple Mail Transport Protocol).
24.1.3 Receiving Email
A Caché application can download and process email messages from a mail server using the
POP3 protocol.
Note:
Caché is not and does not contain a mail server. In order to process in-coming email
messages within Caché you must have a running mail server. What Caché provides
is the ability to connect to and interact with a mail server using the POP3 protocol.
The interface for interacting with a mail server is provided by the %Net.FetchMailProtocol
class. This abstract class includes a set of protocol-neutral methods for interacting with a mail
server. Actual communication with a mail server using a specific protocol is provided by a
subclass of %Net.FetchMailProtocol. Caché supports the POP3 protocol (the only one supported
at this time) using the %Net.POP3 class.
198 Using Caché Objects

FTP
24.2 FTP
Caché includes a class, %Net.FtpSession, for establishing a session with an FTP (File Transfer
Protocol) server from within Caché and download and uploading files.
24.3 HTTP
Caché includes a class, %Net.HttpRequest, for making HTTP (Hyper Text Transport Protocol)
requests from within a Caché application. The response to such a request is wrapped within
a %Net.HttpResponse object.
24.4 URL Parsing
Caché includes a utility class, %Net.URLParser, for parsing URL strings into their component
parts.
This class is quite simple, it contains one class method, Parse, that takes a string containing
a URL value and returns, by reference, an array containing the parts of the URL subscripted
by part name. For example:
Set url = "http://www.intersys.com/main.cspQUERY=abc#anchor"
Do ##class(%Net.URLParser).Parse(url,.components)
Upon return, components will contain an array of the parts of this URL:
Element
components(“scheme”)
components(“netloc”)
components(“path”)
components(“query”)
components(“fragment”)
Value
http:
www.intersys.com
/main.csp
QUERY=abc
anchor
Description
The transport scheme specified by
this URL.
The network address of the URL.
The file path of the URL.
The query string associated with
the URL.
The fragment (following the #
character) for the URL.
Using Caché Objects 199

Internet Classes
For more information refer to the documentation for the %Net.URLParser class.
200 Using Caché Objects

A
Object Concurrency
This appendix provides information on:
• Object concurrency options
• Version checking
A.1 Object Concurrency Options
Many of the methods of the %Persistent class allow you to specify an optional concurrency
setting in order to determine how locks are used for concurrency control.
The possible concurrency settings are:
Setting
0
Meaning
No Locking
Description
No locks are used.
Using Caché Objects 201

Object Concurrency
Setting
1
2
3
4
Meaning
Atomic
Shared
Shared /
Retained
Exclusive
Description
When an object is loaded, the %LoadData method
creates a shared lock for the object, provided that the
object occupies more than one storage node in the
database. No locks are held for objects stored in a single
node. %LoadData releases the lock after it finishes
loading the object. When an object is initially saved to the
database (inserted), %SaveData holds an exclusive lock
during the save, provided that the object occupies more
than one storage node in the database. %SaveData holds
no locks for objects stored in a single node. When a
previously saved object is saved to the database
(updated), %SaveData holds an exclusive lock during the
save.
When an object is loaded, the %LoadData method
creates a shared lock for the object. %LoadData releases
the lock after it finishes loading the object.When an object
is initially saved to the database (inserted), %SaveData
holds an exclusive lock during the save, provided that the
object occupies more than one storage node in the
database. %SaveData holds no locks for objects stored
in a single node.When a previously saved object is saved
to the database (updated), %SaveData holds an exclusive
lock during the course of the save.
A shared lock is acquired either when an existing object
is opened or when a new object is initially saved to the
database (inserted); the lock is released when the object
is destructed. Additionally, when an object is initially saved
to the database, %SaveData holds an exclusive lock
during the save, provided the object occupies more than
one storage node in the database.
An exclusive lock is acquired either when an existing
object is opened or when a new object is initially saved
to the database (inserted); the lock is released when the
object is destructed.
It is important to set concurrency options at an appropriate level for your application. Consider
the following scenario:
1. Process A opens an object.
2. Process B deletes that object from disk.
202 Using Caché Objects

Version Checking
3. Process A saves the object using %Save and receives a success status.
Examining the data on disk shows that the object was not written to disk.
This is an example of concurrent operations that occurred without adequate concurrency
control. In this example, Process B should not have been allowed to delete the object if Process
A really intended to write the object back to disk. Since Process A did not modify the object,
no physical write occurred and unexpected results were observed. Had Process A modified
the object, then %Save would have succeeded as before but the object would have been
written to disk. These inconsistent results are just one example of allowing concurrent access
without adequate controls in place at the application level. (The inconsistent behavior
exhibited by a successful call to %Save and the object not appearing on disk is not a bug in
%Save. It is a concurrency failure which, by definition, will leave the database in an inconsistent
state.)
The solution to this problem is to have Process A open the object with concurrency 3 or 4;
in this case, Process B would then either have been denied access (failed with a concurrency
violation) or would have had to wait until Process A released the object.
A.2 Version Checking
Caché implements version checking using a class parameter called VERSIONPROPERTY.
All persistent classes have this parameter. When defining a persistent class, the procedure
for enabling version checking is:
1. Create a property of type %Integer that holds the updatable version number for each
instance of the class.
2. Set the value of the property's InitialExpression keyword to 0.
3. Set the value of VERSIONPROPERTY to the name of that property. The value of
VERSIONPROPERTY cannot be changed to a different property by a subclass.
This incorporates version checking into updates to instances of the class.
When version checking is implemented, the property specified by VERSIONPROPERTY is
automatically incremented each time an instance of the class is updated (either by objects or
SQL). Prior to incrementing the property, Caché compares its in-memory value to its stored
value. If they are different, then a concurrency conflict is indicated and an error is returned;
if they are the same, then the property is incremented and saved.
Using Caché Objects 203

Object Concurrency
Note:
You can use this set of features to implement optimistic concurrency.
To implement a concurrency check in an SQL update statement for a class where
VERSIONPROPERTY refers to a property called InstanceVersion, the code would be something
like:
SELECT InstanceVersion,Name,SpecialRelevantField,%ID
FROM my_table
WHERE %ID = :myid
// Application performs operations on the selected row
UPDATE my_table
SET SpecialRelevantField = :newMoreSpecialValue
WHERE %ID = :myid AND InstanceVersion = :myversion
where myversion is the value of the version property selected with the original data.
204 Using Caché Objects

Index
A
accessor methods, 184
E
Extent, Object, 107
S
SaveSet (Objects), 101
Swizzling, 17
Using Caché Objects 205