Using Caché Studio

Version 2010.1
17 February 2010

InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Using Caché Studio
Caché Version 2010.1 17 February 2010
Copyright © 2010 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.

and

Caché WEBLINK, Distributed Cache Protocol, M/SQL, M/NET, and M/PACT are registered trademarks of InterSystems Corporation.

, , and

InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of InterSystems Corporation.

All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations.

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.

For Support questions about any InterSystems products, contact:

InterSystems Worldwide Customer Support

Tel: +1 617 621-0700
Fax: +1 617 374-9391
Email: [email protected]
 Table of Contents
About This Book .................................................................................................................................... 1
1 Introduction to Caché Studio ............................................................................................................ 3
1.1 Overview of the Studio Window ................................................................................................ 3
1.1.1 Running Studio from the Command Line ........................................................................ 4
1.2 Projects ....................................................................................................................................... 5
1.3 Class Definitions ........................................................................................................................ 5
1.3.1 Class Definitions as Text .................................................................................................. 6
1.4 CSP Files .................................................................................................................................... 8
1.5 Routine Editor ............................................................................................................................ 8
1.6 Multiple User Support ................................................................................................................ 8
1.7 Importing and Exporting Caché Documents Locally ................................................................. 9
1.8 Debugging .................................................................................................................................. 9
1.8.1 Debugging Object-Based Applications ............................................................................ 9
1.9 Integration with Caché Security ................................................................................................. 9
1.10 Source Control Hooks ............................................................................................................ 10
2 Building a Simple Application with Studio .................................................................................... 11
2.1 Creating a Project ..................................................................................................................... 11
2.2 Creating a Database .................................................................................................................. 12
2.2.1 Defining a New Class ..................................................................................................... 12
2.2.2 Adding Properties ........................................................................................................... 12
2.2.3 Saving and Compiling Your Class .................................................................................. 13
2.2.4 Viewing Documentation for Your Class ......................................................................... 13
2.3 Creating a Web User Interface using CSP ................................................................................ 13
2.3.1 Creating a CSP File ........................................................................................................ 13
2.3.2 Saving and Compiling Your CSP File ............................................................................ 15
2.3.3 Viewing Your Web Page ................................................................................................. 15
2.4 Creating a Web User Interface using Zen ................................................................................. 15
2.4.1 Making Your Class a Data Adaptor ................................................................................ 15
2.4.2 Creating a Zen Page ....................................................................................................... 16
2.4.3 Adding a Zen Form ........................................................................................................ 18
2.4.4 Adding Client-side Methods .......................................................................................... 19
2.4.5 Viewing the Database in a Table .................................................................................... 21
3 Creating Class Definitions ............................................................................................................... 23
3.1 Creating New Class Definitions ............................................................................................... 23
3.1.1 New Class Wizard .......................................................................................................... 23
3.1.2 Results of Running the New Class Wizard .................................................................... 26
3.2 Opening Class Definitions ....................................................................................................... 26
3.3 Editing Class Definitions ......................................................................................................... 26
3.4 Saving and Deleting Class Definitions ..................................................................................... 27
3.5 Compiling Class Definitions .................................................................................................... 27
3.5.1 Incremental Compilation ................................................................................................ 27
3.5.2 Compilation and In-Use Classes .................................................................................... 28
3.6 Renaming Class Definitions ..................................................................................................... 28
3.7 Class Inspector ......................................................................................................................... 28
3.7.1 Activating the Class Inspector ........................................................................................ 29
3.8 Class Browser ........................................................................................................................... 30

Using Caché Studio                                                                                                                                                                iii

 3.9 Superclass Browser and Derived Class Browser ...................................................................... 30
3.9.1 Superclass Browser ........................................................................................................ 30
3.9.2 Derived Class Browser ................................................................................................... 30
3.10 Package Information ............................................................................................................... 30
4 Adding Properties to a Class ............................................................................................................ 33
4.1 New Property Wizard ............................................................................................................... 33
4.1.1 Name and Description Page ........................................................................................... 33
4.1.2 Property Type Page ........................................................................................................ 34
4.1.3 Property Characteristics Page ........................................................................................ 34
4.1.4 Data Type Parameters Page ............................................................................................ 35
4.1.5 Property Accessors Page ................................................................................................ 35
4.1.6 Results of Running the New Property Wizard ............................................................... 35
5 Adding Methods to a Class .............................................................................................................. 37
5.1 New Method Wizard ................................................................................................................. 37
5.1.1 Name and Description Page ........................................................................................... 37
5.1.2 Method Signature Page .................................................................................................. 38
5.1.3 Method Characteristics Page .......................................................................................... 38
5.1.4 Implementation Page ...................................................................................................... 39
5.1.5 Results of Running the New Method Wizard ................................................................. 39
5.2 Overriding a Method ................................................................................................................ 39
6 Adding Class Parameters to a Class ............................................................................................... 41
6.1 New Class Parameter Wizard .................................................................................................. 41
7 Adding Relationships to a Class ...................................................................................................... 43
7.1 New Property Wizard to Create a Relationship Property ......................................................... 43
7.1.1 Name and Description Page ........................................................................................... 44
7.1.2 Property Type Page ........................................................................................................ 44
7.1.3 Relationship Characteristics Page .................................................................................. 44
7.1.4 Additional Changes ........................................................................................................ 45
7.1.5 Results of Creating a New Relationship with the New Property Wizard ....................... 45
8 Adding Queries to a Class ................................................................................................................ 47
8.1 New Query Wizard ................................................................................................................... 48
8.1.1 Name, Implementation, and Description Page ............................................................... 48
8.1.2 Input Parameters Page .................................................................................................... 48
8.1.3 Columns Page ................................................................................................................. 48
8.1.4 Conditions Page ............................................................................................................. 48
8.1.5 Order By Page ................................................................................................................ 49
8.1.6 Row Specification Page ................................................................................................. 49
8.1.7 Results of Running the New Query Wizard ................................................................... 49
9 Adding Indices to a Class ................................................................................................................. 51
9.1 New Index Wizard .................................................................................................................... 51
9.1.1 Name and Description Page ........................................................................................... 51
9.1.2 Index Type Page ............................................................................................................. 52
9.1.3 Index Properties Page ..................................................................................................... 52
9.1.4 Index Data Page ............................................................................................................. 53
9.1.5 Results of Running the New Index Wizard .................................................................... 53
9.2 Populating an Index .................................................................................................................. 53
10 Adding Projections to a Class ........................................................................................................ 55
10.1 New Projection Wizard ........................................................................................................... 56

iv                                                                                                                                                               Using Caché Studio

 10.1.1 Name and Description Page ......................................................................................... 56
10.1.2 Projection Type Page .................................................................................................... 57
10.1.3 Results of Running the New Projection Wizard ........................................................... 57
11 Adding XData Blocks to a Class .................................................................................................... 59
11.1 New XData Wizard ................................................................................................................. 59
12 Adding SQL Triggers and Foreign Keys to a Class ..................................................................... 61
12.1 SQL Aliases ............................................................................................................................ 61
12.2 SQL Stored Procedures .......................................................................................................... 61
12.2.1 Query-Based Stored Procedure .................................................................................... 61
12.2.2 Creating Method-Based Stored Procedure ................................................................... 62
12.3 Adding SQL Triggers to a Class ............................................................................................. 62
12.3.1 New SQL Trigger Wizard ............................................................................................ 63
12.4 Adding New SQL Foreign Keys to a Class ............................................................................ 64
12.4.1 New SQL Foreign Key Wizard .................................................................................... 64
13 Adding Storage Definitions to a Class .......................................................................................... 67
13.1 Adding Storage Definitions to a Class ................................................................................... 67
13.1.1 Using the New Storage Wizard .................................................................................... 68
13.2 Using the Class Inspector with Storage Definitions ............................................................... 69
13.3 Using the Class Editor with Storage Definitions ................................................................... 69
14 Working with CSP Files ................................................................................................................. 71
14.1 Sample CSP Page ................................................................................................................... 71
14.2 Creating a New CSP File ........................................................................................................ 72
14.2.1 Default.csp Template File ............................................................................................ 72
14.3 Editing a CSP File .................................................................................................................. 72
14.3.1 Insert Options ............................................................................................................... 72
14.4 Saving a CSP File ................................................................................................................... 73
14.5 Compiling a CSP File ............................................................................................................. 73
14.6 Viewing the Results of a CSP File .......................................................................................... 73
14.7 Viewing Syntax-Colored Source for Any URL ..................................................................... 73
15 Working with Routines ................................................................................................................... 75
15.1 Routine Editor ........................................................................................................................ 75
15.2 Routine Source Formats ......................................................................................................... 75
15.3 Creating a New Routine ......................................................................................................... 76
15.4 Opening an Existing Routine ................................................................................................. 76
15.5 Routine Template File ............................................................................................................ 76
15.6 Saving, Compiling, and Deleting Routines ............................................................................ 76
16 Using the Studio Debugger ............................................................................................................ 77
16.1 Sample Debugging Session: Debugging a Routine ................................................................ 77
16.2 Debugger Settings for the Current Project ............................................................................. 78
16.2.1 Debug Target ................................................................................................................ 78
16.2.2 Breakpoints .................................................................................................................. 79
16.3 Debug Menu ........................................................................................................................... 79
16.4 Watch Window ........................................................................................................................ 80
17 Using Studio Templates .................................................................................................................. 83
17.1 Using Studio Templates .......................................................................................................... 83
17.2 Standard Studio Templates ..................................................................................................... 84
17.2.1 Templates ..................................................................................................................... 84
17.2.2 Class Definition Templates .......................................................................................... 85

Using Caché Studio                                                                                                                                                                v

 17.2.3 Zen Templates .............................................................................................................. 85
17.2.4 Add-In Templates ......................................................................................................... 85
17.3 Making Your Own Studio Templates ...................................................................................... 86
17.3.1 Template Architecture .................................................................................................. 86
17.3.2 Default Template Timeout ............................................................................................ 87
17.3.3 Simple Text Templates ................................................................................................. 87
17.3.4 Interactive Studio Templates ........................................................................................ 89
17.3.5 New Document Studio Templates ................................................................................ 90
17.3.6 Add-in Studio Templates .............................................................................................. 91
18 Studio Menu Reference .................................................................................................................. 93
18.1 File Menu ............................................................................................................................... 93
18.2 Edit Menu ............................................................................................................................... 95
18.2.1 Basic Editing ................................................................................................................ 95
18.2.2 Find and Replace .......................................................................................................... 96
18.2.3 Bookmarks ................................................................................................................... 98
18.2.4 Advanced Editing ........................................................................................................ 98
18.3 View Menu ............................................................................................................................. 98
18.3.1 Toolbars ...................................................................................................................... 100
18.3.2 Customize Toolbars .................................................................................................... 101
18.4 Project Menu ........................................................................................................................ 101
18.4.1 Common Project Tasks ............................................................................................... 102
18.5 Class Menu ........................................................................................................................... 102
18.6 Build Menu ........................................................................................................................... 103
18.7 Debug Menu ......................................................................................................................... 103
18.8 Tools Menu ........................................................................................................................... 103
18.9 Utilities Menu ....................................................................................................................... 105
18.10 Window Menu .................................................................................................................... 105
18.11 Help Menu .......................................................................................................................... 105
18.12 Context Menus ................................................................................................................... 105
18.12.1 Editor Context Menu ................................................................................................ 105
18.12.2 Workspace Context Menu ........................................................................................ 106
18.12.3 Inspector Context Menu ........................................................................................... 106
18.12.4 Tab Context Menu .................................................................................................... 107
18.12.5 Window Display Context Menu ............................................................................... 107
18.13 Keyboard Accelerators ....................................................................................................... 107
18.13.1 Inserting MultiValue Characters ............................................................................. 113
18.14 Adding to a Studio Menu ................................................................................................... 113
19 Setting Studio Options ................................................................................................................. 115
19.1 Environment Options ............................................................................................................ 115
19.2 Editor Options ...................................................................................................................... 117
19.3 Compiler Options ................................................................................................................. 118
19.4 SQL Options ......................................................................................................................... 119
Appendix A:Using Studio Source Control Hooks ........................................................................... 121
A.1 Overview ............................................................................................................................... 121
A.2 Caché Documents .................................................................................................................. 121
A.2.1 Tools for Managing Documents and Files .................................................................. 122
A.2.2 Deciding How to Map Internal and External Names .................................................. 122
A.3 Creating and Activating a Source Control Class ................................................................... 122
A.3.1 Extending Studio ......................................................................................................... 123

vi                                                                                                                                                               Using Caché Studio

 A.3.2 Creating a Source Control Class ................................................................................. 123
A.3.3 Activating a Source Control Class ............................................................................... 123
A.4 Accessing Your Source Control System ................................................................................ 124
A.4.1 Example 1 .................................................................................................................... 124
A.4.2 Example 2 .................................................................................................................... 124
A.5 A Look at the Sample ............................................................................................................ 125
A.5.1 Introduction ................................................................................................................. 125
A.5.2 Global .......................................................................................................................... 126
A.5.3 Determining the External Names ................................................................................ 126
A.5.4 Synchronizing the Caché Document and the External File ........................................ 127
A.5.5 Controlling the Status of the Caché Document ........................................................... 128
A.5.6 Source Control Actions ............................................................................................... 128
A.5.7 Other Details ............................................................................................................... 129
Appendix B:Class Definition Syntax ................................................................................................ 131
B.1 Class Definition Example ...................................................................................................... 131
B.2 General Structure ................................................................................................................... 132
B.2.1 Generation and Format ................................................................................................ 132
B.2.2 Statements ................................................................................................................... 133
B.2.3 Comments .................................................................................................................... 135
B.2.4 Comments Used in the Class Reference ...................................................................... 136
B.3 Statements .............................................................................................................................. 136
B.3.1 Class Statement ........................................................................................................... 136
B.3.2 Parameter Statement .................................................................................................... 138
B.3.3 Property Statement ...................................................................................................... 139
B.3.4 Relationship Statement ................................................................................................ 141
B.3.5 Index Statement ........................................................................................................... 141
B.3.6 Method and ClassMethod Statements ......................................................................... 142
B.3.7 SQL Query Statement ................................................................................................. 144
B.3.8 Projection Statement .................................................................................................... 145
B.3.9 SQL Trigger Statement ................................................................................................ 145
B.3.10 SQL ForeignKey Statement ....................................................................................... 146
Appendix C:Frequently Asked Questions About Caché Studio .................................................... 149

Using Caché Studio                                                                                                                                                               vii

 List of Figures
Figure 1–1: Studio Components .............................................................................................................. 4
Figure 3–1: Class Inspector ................................................................................................................... 29
Figure 3–2: Package Settings dialog ..................................................................................................... 31
Figure 17–1: Example of an Interactive Template, the HTML Color Table ......................................... 84
Figure 18–1: Standard Toolbar ............................................................................................................ 100
Figure 18–2: Debug Toolbar ................................................................................................................ 101
Figure 18–3: Class Members Toolbar ................................................................................................. 101
Figure 18–4: BPL Toolbar ................................................................................................................... 101
Figure 18–5: Bookmarks Toolbar ........................................................................................................ 101

viii                                                                                                                                                              Using Caché Studio

 List of Tables
Table 10–1: Projection Classes .............................................................................................................. 55
Table 17–1: CSP Templates ................................................................................................................... 84
Table 17–2: Class Definition Templates ................................................................................................ 85
Table 17–3: Zen Templates .................................................................................................................... 85
Table 17–4: Add-Ins .............................................................................................................................. 86
Table 17–5: Studio Template Types ....................................................................................................... 88
Table II–1: Class Keywords ................................................................................................................. 137
Table II–2: Parameter Keywords ......................................................................................................... 139
Table II–3: Property Keywords ............................................................................................................ 139
Table II–4: Relationship Keywords ..................................................................................................... 141
Table II–5: Index Keywords ................................................................................................................ 142
Table II–6: Method Keywords ............................................................................................................. 143
Table II–7: SQL Query Keywords ....................................................................................................... 145
Table II–8: SQL Trigger Keywords ..................................................................................................... 146
Table II–9: SQL ForeignKey Keywords .............................................................................................. 147

Using Caché Studio                                                                                                                                                               ix

About This Book
This book describes how to use Caché Studio, Caché's visual, integrated, development environment for creating database
and Web applications, including syntax coloring, syntax checking, and debugging.
• Introduction to Caché Studio
• Building a Simple Application with Studio
• Creating Class Definitions
• Adding Properties to a Class
• Adding Methods to a Class
• Adding Class Parameters to a Class
• Adding Relationships to a Class
• Adding Queries to a Class
• Adding Indices to a Class
• Adding Projections to a Class
• Adding XData Blocks to a Class
• Adding SQL Triggers and Foreign Keys
• Adding Storage Definitions to a Class
• Working with CSP Files
• Working with Routines
• Using the Studio Debugger
• Using Studio Templates
• Studio Menu Reference
• Setting Studio Options
• Using Studio Source Control Hooks
• Class Definition Syntax
• Frequently Asked Questions About Caché Studio
• And a more detailed Table of Contents.

Using Caché Studio                                                                                                                                                                1

1
Introduction to Caché Studio
Caché Studio offers features that help you develop applications rapidly, in a single, integrated environment including:
• – Classes, including persistent, database classes and Web service classes
– Interactive Web pages using: CSP (Caché Server Pages) and Zen, XML, HTML, Javascript, cascading style sheets
(CSS)
– Routines using Caché ObjectScript, Basic, or MultiValue

• Integrated syntax coloring and syntax checking for Caché ObjectScript, Basic, Java, SQL, JavaScript, HTML, and
XML.
• Support for teams of developers working with a common repository of application source code.
• A graphical, source code debugger.
• The ability to organize application source code into projects.

Caché Studio is a client application, built using Caché objects, that runs on Windows-based operating systems. It can connect
to any Caché server (compatible with the current version of Caché Studio) regardless of what platform and operating system
that server is using.

Note: A Studio client must be running either the same version of Caché or a higher version than the Caché server that
it is connecting to. Example: Caché 2008.2 Studio can connect to a Caché 2008.2 (or earlier version) server. Caché
2008.1 Studio cannot connect to a Caché 2008.2 (or later) server. This applies also to maintenance releases.
Example: Caché 2008.2.1 Studio can connect to a Caché 2008.2.1 (or earlier maintenance release or version)
server. Caché 2008.2.0 Studio cannot connect to a Caché 2008.2.1 (or later maintenance release or version) server.

1.1 Overview of the Studio Window

Caché Studio is a standard Windows application. It uses windows to display and allow the editing of aspects. The main
components of the Caché Studio user interface are shown below:

Using Caché Studio                                                                                                                                                                3

Introduction to Caché Studio

Figure 1–1: Studio Components

1. Editors: Class Editorfor editing class definitions, Routine Editor for editing routines, and CSP Editor for editing CSP
definition text.
2. Workspace window: three tabs let you display: the contents of the current project, all open windows, or the content of
the current namespace.
3. Class Inspector window: for viewing and modifying keywords in a class definition.
4. Output window: displays output from the Caché server (such as messages generated during class compilation).

In addition to the windows displayed above, Caché Studio contains wizards and templates for assisting with common tasks.
These include:
• New Class wizard: defines a new class.
• Class member wizards that add members to class definitions for: properties, indexes, relationships, methods, parameters,
SQL triggers, queries, projections, storage, foreign keys, and XData blocks.
• Wizards that create classes from other technologies; from: Java classes and jar files, SML schema, SOAP client classes,
that provide access to COM objects, and DLL assembly files from .NET.
• HTML templates that add: colors, tables, tags, and scripts.
• CSP Form wizard: creates an HTML form bound to a Caché object in a CSP page.
• Zen templates that add: charts, tables, methods, and styles.

1.1.1 Running Studio from the Command Line

You can run Studio from the system's command line using the command Cstudio.exe (in the Cache bin directory). The
command and its parameters are case-sensitive

4                                                                                                                                                                Using Caché Studio

 Projects

Parameter Description
? Help info
/Servername=ServerName Connect to the server named ServerName.
/Server=cn_iptcp:127.0.0.1[1972]:: Connect to the server at ip address[[port, here
127.0.0.1[1972] server.
/Namespace=User Connect to the User namespacer. Server should
be defined.
/Project=MyProject Open project MyProject. Server and Namespace
should be defined
cn_iptcp://127.0.0.1:1972/User/test.int Load routine test.int. cn_iptcp is a case sensitive
protocol identifier.
/files="tag+1^myroutine.int",User.Class1.cls Open listed documents and set cursor in specified
position. Server and namespace should be defined
/pid=123 Attach to process. Server and Namespace should
be defined
/fastconnect=127.0.0.1[1972]:USER:_SYSTEM:SYS Connect without connection definition in registry
using ip address[[port]:USER:username:password

1.2 Projects
Caché Studio uses projects to organize application source code.
A project is a set of class definitions, CSP files, and routines. For example, you might create a Caché Studio project to
group all classes and CSP files for a single application.
You are always in a project, either one that you created or the default project that is created when you first open Studio
called Default_yourusername (a prefix of Default_ followed by your user name).
All files in a single project must be in the same namespace (and Caché server). Each class, CSP file, or routine can be
associated with any number of projects. Each namespace can contain any number of projects.
The project stores information such as the class hierarchy in a given Caché namespace, used when you edit classes or CSP
files. The project also stores debugging information (such as how to start the application you want to debug).

1.3 Class Definitions

A class definition defines a Caché class. A class definition consists of class members (such as properties and methods)
and other items, called keywords, each with associated values, that specify details of the class behavior.
Class definitions reside in a Caché database where they are stored in the class dictionary. A class definition can be compiled,
a process which creates executable code that can create objects instances based on the class definition. The source code for
the executable code created for a class consists of one or more Caché routines. These generated routines can also be viewed
in Caché Studio.

Using Caché Studio                                                                                                                                                                5

Introduction to Caché Studio

A class definition can be projected for use by other technologies. In the case of SQL and ActiveX, this projection is automatic.
In the case of Java (or C++) there is an additional compilation step in which a Java class is generated that corresponds to
the Caché class definition. For details, see the chapter “Adding Class Projections.”
Within Caché Studio, class definitions can be displayed and edited in a Class Editor window. Class definitions can also be
viewed in the Class Inspector window as keywords and their corresponding values in tables.

1.3.1 Class Definitions as Text

The following is an example of a class definition that defines a class containing one property and one method:
/// Definition of a simple persistent Person class
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{

/// The name of the Person

Property Name As %String;

/// A simple Print method

Method Print() As %Boolean
{
// Write out Person's Name
Write "Name is: ", ..Name
Quit 1
}

1.3.1.1 Class Information

A class definition starts with the declaration of the class name and any class-wide characteristics, such as:
Class MyApp.Student Extends Person
{

This example defines a class called MyApp.Student (with no properties, methods, or other members) that extends (is derived
from) the class MyApp.Person (since Student and Person are in the same package, we can omit MyApp from the Extends
statement). The { } (braces) enclose the definition of the class members (of which there are none in this example).
You can specify additional characteristics for this class by defining values for class keywords. This is done by placing a
list of keywords (possibly with values) in [ ] (brackets) immediately following the class declaration (after the class name
and superclass name (if any)).
For example, you can specify that the class as Final and the name of its corresponding SQL table as StudentTable.
Class MyApp.Student Extends Person [Final, SqlTableName=StudentTable]
{

You can also provide a description for this class by placing a description comment (identified by ///, three slashes) imme-
diately before the declaration of the class. This description is used when you view the class documentation via the Caché
online class reference. It may contain HTML markup. Example:
/// This is a simple Student class
/// It is derived from the Person class
Class MyApp.Student Extends Person
{
}

You can use the C-style //, two slashes, and /* */, begin with slash asterisk and end with asterisk slash, comments anywhere
in a class definition to comment out a section of the class definition.

6                                                                                                                                                                Using Caché Studio

 Class Definitions

1.3.1.2 Properties
You can define a property in a class definition using the Property keyword:
Class MyApp.Student Extends Person
{
Property GPA As %Float;
}

This example defines a property named GPA with type %Float (specified using As). The end of the property definition is
marked with a final semicolon (;).
As with the class declaration, you can add a description for this property using a preceding /// comment and we can specify
additional property keywords in [ ] brackets:
Class MyApp.Student Extends Person
{
/// Grade Point Average for the Student
Property GPA As %Float [ Required ];
}

If you want to specify parameter values for the property data type (parameters give you a way to customize the behavior
of a property), placed them in ( ), parentheses, as part of the type name. Note that the values for data type parameters are
treated as literal values; enclose strings in quotation marks.
Class MyApp.Student Extends Person
{
/// Grade Point Average for the Student
Property GPA As %Float(MINVAL=0.0, MAXVAL=5.0) [ Required ];
}

1.3.1.3 Methods
You can define a method in a class definition using the Method keyword:
Class MyApp.Student Extends Person
{
/// This method wastes count seconds.
Method WasteTime(count As %Integer=1) As %Boolean [Final]
{
// loop and sleep
For i = 1:1:count {
Write "."
Hang 1
}
Quit 1
}
}

The return type of the method is specified using As followed by a class name. The formal argument list follows the method
name and is enclosed in ( ) (parentheses). The implementation of the method is contained in { } (braces) following the
method declaration.
As with a property, you can use /// (three slashes) comments to specify a description (with HTML markup, if desired) and
additional keyword values are placed in [ ] (brackets).
You can specify the programming language for a method using the Language keyword. For example, the code below defines
a method in Basic:
/// Find the sum of numbers from 1 to <var>count</var>.
Method SumUp(count As %Integer) As %Integer [Language = basic]
{
total = 0
For i = 1 To count
total = total + i
Next

Return i
}

Using Caché Studio                                                                                                                                                                7

Introduction to Caché Studio

Use the Language keyword to specify one of the following languages:

• cache—Caché ObjectScript (the default if no language is specified). Refer to the book Using Caché ObjectScript for
more details.
• basic—Basic. Caché supports a variant of the BASIC programming language. Basic methods are compiled into
executable code that runs in the Caché virtual machine (in the same manner as Caché ObjectScript). Refer to Using
Basic for more details.
• java—Java. When you use the Caché Java Binding, Java methods become part of the automatically generated Java
classes and are compiled into executable Java code. Refer to Using Java with Caché for more details.

A single class can contain methods that use different languages. Or you can specify the default programming language for
an entire class using the class-level Language keyword.

1.4 CSP Files

A CSP (Caché Server Page) file is an HTML or XML text file containing CSP markup language. The CSP engine processes
a CSP file and generates from it a Caché class which is then used to respond to HTTP events and provide Web content.
If you prefer a more programmatic approach to Web development, you can also use Caché Studio to create and edit CSP
classes in the same way as you would work with any other class definitions.
Caché Studio displays CSP files in a CSP Editor window. This editor provides syntax coloring of HTML and XML as well
as many of the scripting languages that may be contained in a CSP file.
The CSP Editor provides commands for performing common CSP and HTML editing tasks such as inserting CSP markup
tags. Caché Studio also lets you view the results of a CSP file in a browser using the menu pick View > Web Page.

1.5 Routine Editor

Using the Routine Editor, you can directly create and edit the source for specific Caché routines in a syntax-coloring editor.

1.6 Multiple User Support

Caché Studio is an object-based, client/server application. The source files—class definitions, routines, and CSP files—that
you can create and edit with Studio are stored in a Caché server and are represented as objects.
When you save a source file from Studio, it is saved in the Caché server you are connected to. If a source file is modified
on the server while you are viewing it in Studio, you are notified and asked if you want to load the newer version.
Studio automatically detects when multiple users view the same source components simultaneously and manages access
concurrency. If you attempt to open a file that is being edited by another user, you are notified and asked if you want to
open the file in read-only mode.

8                                                                                                                                                                Using Caché Studio

 Importing and Exporting Caché Documents Locally

1.7 Importing and Exporting Caché Documents Locally

Normally any documents you work with in Studio (such as class definitions or routines) are stored in a Caché database
(which may be on a remote machine). You can import from and export to local files using Tools > Export and Tools > Import.
Class definitions and routines are stored in local files as XML documents.

1.8 Debugging
Caché Studio includes a source-level, GUI debugger. The debugger attaches (or starts up and attaches to) a target process
running on the same Caché server that Studio is connected to. The debugger controls this target process remotely and allows
you to watch variables, step through code, and set breakpoints.
You typically must have a project open in order to use the debugger; the project contains the information needed to start
the debug target (name of a routine, method, CSP page, Zen page, or client application). In addition, the project stores a
list of breakpoints set in a prior debugging session for subsequent reuse.
You may attach and break into a running process without having a project open. In this case Studio does not remember
breakpoint settings from previous sessions. See more about debugging in the chapter “ Using the Studio Debugger.”

1.8.1 Debugging Object-Based Applications

At this time, Caché Studio only allows source-level debugging of INT (Caché ObjectScript routine) and BAS (Basic routine)
files. To step through, or set breakpoints within classes or CSP pages, open the corresponding INT or BAS file and use the
debugging commands in it.
To make sure that the generated source code for a class is available, check the Keep Generated Source Code option,
on Tools > Options dialog, Compiler > General Flags tab.

1.9 Integration with Caché Security

Caché security features control both the use of Studio and the ability of Studio to connect to any Caché server. When you
start Studio, it presents a login screen; to use Studio, you must log in as a user who holds the following privileges:
• %Development:Use - Use permission on the %Development resource grants access to various development-related
resources.
• %Service_Object:Use - Use permission on the %Service_Object resource grants access to the %Service_Bind-
ings service, which controls access to Studio.

Also, you can only connect to a namespace if you have Read or Write permission for its default database.
The way in which a user is granted these various privileges depends on the instance’s security level:
• For an instance with minimal security, all users, including UnknownUser, have all privileges and access to all names-
paces. When presented with the Studio login screen, either leave the Username and Password fields blank or enter
“ _SYSTEM” and “SYS ” as the username-password pair.
• For an instance with normal security, you must be explicitly granted the specified privileges. This is established by
being assigned to a role or roles that holds these privileges.

Using Caché Studio                                                                                                                                                                9

Introduction to Caché Studio

• For an instance with locked-down security, the service that governs access to Studio (%Service_Bindings) is disabled
by default. By default, no user has access to Studio.

Note: Studio access may also be affected by any changes to default settings that have occurred since installation.

1.10 Source Control Hooks

Studio includes a mechanism for implementing custom hooks—code that is executed on the Caché server whenever a
document is loaded or saved. Typically these hooks are used to implement a connection to a source or revision control
system.
To define source control hooks, create a subclass of the %Studio.SourceControl.Base class and implement the callback
methods that you want. You can specify which Source Control class Studio should use from the [Home] > [Configuration]
> [Studio Source Control Settings] page of the System Management Portal.

Refer to the %Studio.SourceControl.Base class and the “Using Studio Source Control Hooks ” appendix for more details.

10                                                                                                                                                              Using Caché Studio

2
Building a Simple Application with Studio
This chapter contains a tutorial that illustrates some basic features of Caché Studio. The tutorial shows you how to create
a database application that is a phone book, containing names and phone numbers.
The phone book application consists of:
• A database in which you can store names and phone numbers.
• An interactive user interface on a Web page (an HTML form) that allows you to add new entries, search for entries,
and edit entries in the phone book.

The tutorial demonstrates how to use Studio to:

1. Create a Caché Project to manage the source code for the application.
2. Define the application's database using a persistent database class.
3. Create a Web-based (HTML) user interface for the application using Caché Server Pages (CSP).
4. Create a Web-based (HTML) user interface for the application using InterSystems Zen.

2.1 Creating a Project

First, create a new project named Phone Book to manage the source files for the application, as follows:
1. Start Caché Studio: Right-click the Caché cube and select Studio.
Studio connects to the local Caché server using the namespace used most recently by Studio (or the USER namespace
if this is the first time Studio is connecting).
2. If Studio is not connected to the namespace in which you want to work, connect to a different namespace using the
File > Change Namespace.

By default, Studio displays the Workspace window and creates a new project called Default_system. The Studio
Workspace window indicates the name of the current project as well as the server connection and namespace name.
The Workspace window should be displayed by default; if you don't see it, display it using the View > Workspace or
with the Alt-3 keyboard accelerator.

Using Caché Studio                                                                                                                                                              11

Building a Simple Application with Studio

3. To save the new project, use the File > Save Project As and enter Phone Book.

You can save this project to the Caché server at any time using the File > Save Project.

2.2 Creating a Database

The Phone Book application is a database containing people's names and phone numbers, stored using a set of persistent
objects. These objects are defined by a persistent class called Person. For sake of organization you can place this class in
a package called PhoneBook.
The persistent class Person contains two properties (or fields): Name and PhoneNumber.

2.2.1 Defining a New Class

You can define this new Person class using Studio's New Class wizard by following these steps:
1. Start the New Class wizard by selecting File > New > General tab.
2. Select Caché Class Definition and click OK.
3. On the first page of the New Class wizard, enter a package name, PhoneBook, a class name, Person, and click Next.
4. Select Persistent from the list of available class types and click Finish.

You see a Class Editor window containing the definition of your new class:
Class PhoneBook.Person Extends %Persistent
{
}

2.2.2 Adding Properties

Add the Name and PhoneNumber properties to the definition of the Person class with the New Property wizard as follows:
1. Select Class > Add > New Property to start the New Property wizard.
2. Enter a name for the new property, Name, and click Finish.

Your class definition includes a property definition:

Class PhoneBook.Person Extends %Persistent [ ClassType=Persistent ]
{
Property Name As %String;
}

12                                                                                                                                                              Using Caché Studio

 Creating a Web User Interface using CSP

Add a PhoneNumber property to the class definition in the same way as you did the Name property by running the New
Property wizard again. You could have also added this new property by copying, pasting, and modifying the Name property
directly into the Class Editor window. Items are indented to structure the code to improve readability. A plus/minus
expansion box is provided to the left of each item so that you can collapse sections of the code that you are not currently
looking at.
Class PhoneBook.Person Extends %Persistent [ ClassType=Persistent ]
{
Property Name As %String;
Property PhoneNumber As %String;
}

2.2.3 Saving and Compiling Your Class

Save this class definition to the database and compile it into executable code with Build > Compile or click the Compile icon
.
You now have a PhoneBook.Person class defined in your database.

2.2.4 Viewing Documentation for Your Class

View the automatically generated documentation for this class in the Caché online class reference with View > Show Class
Documentation. To enter descriptions for your class and properties so that they appear in the online documentation, you
can enter descriptions above class member declarations using /// (three slashes) or you can do the following:
1. Click the Class Inspector and view Class keywords (make the left column header of the inspector display the word
Class)

2. In the Inspector, double-click the keyword Description.

3. This opens an editor in which you can enter a description for your class, such as the following:

4. Click OK when you are finished.

5. Save your class and view the documentation again.

2.3 Creating a Web User Interface using CSP

The user interface of the Phone Book application is a Web page containing an HTML form that lets you edit and view data,
name and number, for a person in the database. You create this Web page using a CSP file that contains a form bound to
the persistent PhoneBook.Person class.

2.3.1 Creating a CSP File

You can create a CSP file in Studio using the Web Form wizard as follows:
1. Create a new CSP file by selecting File > New > CSP File tab > Caché Server Page.

Using Caché Studio                                                                                                                                                              13

Building a Simple Application with Studio

2. A CSP Editor window is displayed containing source for the new CSP page entitled Unititled.csp. Click File > Save. In
the Save As dialog, double-click /csp/user to open this directory, enter Person.csp, and click Save As.
3. In the editor window, position the cursor in the <BODY> section of the CSP source file. Delete the words “ My page
body.” Select Tools > Templates > Web Form Wizard.
4. Select the PhoneBook.Person class and click Next.
5. Click the Name and PhoneNumber properties from the list of available properties. They should appear in the Selected
Properties list.

6. Click Finish.

Studio displays the HTML source for a bound form in the CSP Editor window:
<html>
<head>

<!-- Put your page Title here -->

<title> Cache Server Page </title>

</head>

<body>
<!-- Put your page code here -->

<head>
<title>Cache Server Page - PhoneBook.Person (USER)</title>
</head>
<h1 align='center'>PhoneBook.Person</h1>
<!-- This function is needed by the search button on the form -->
<script language='javascript'>
<!--
function update(id)
{
#server(..formLoad(id))#;
return true;
}

// -->
</script>

<!-- use CSP:OBJECT tag to create a reference to an instance of the class -->
<csp:object name='objForm' classname='PhoneBook.Person' OBJID='#(%request.Get("OBJID"))#'>

<!-- use csp:search tag to create a javascript function to invoke a search page -->
<csp:search name='form_search' classname='PhoneBook.Person' where='%Id()' options='popup,nopredicates'

onselect='update'>

<form name='form' cspbind='objForm' cspjs='All' onsubmit='return form_validate();'>

<center>
<table cellpadding='3'>
<tr>
<td><b><div align='right'>Name:</div></b></td>
<td><input type='text' name='Name' cspbind='Name' size='50'></td>
</tr>
<tr>
<td><b><div align='right'>PhoneNumber:</div></b></td>
<td><input type='text' name='PhoneNumber' cspbind='PhoneNumber' size='50'></td>
</tr>
<tr>
<td> </td>
<td><input type='button' name='btnClear' value='Clear' onclick='form_new();'>
<input type='button' name='btnSave' value='Save' onclick='form_save();'>
<input type='button' name='btnSearch' value='Search' onclick='form_search();'></td>
</tr>
</table>
</center>
</form>
</body>
</html>

14                                                                                                                                                              Using Caché Studio

 Creating a Web User Interface using Zen

2.3.2 Saving and Compiling Your CSP File

You can save changes and compile the CSP file by choosing Build > Compile or Ctrl-F7 or the Compile icon .

2.3.3 Viewing Your Web Page

You can view the Web page in a browser by choosing View > Web Page or the Web Page icon .
The Web page that results from the previous steps looks like this:

To learn more about using CSP to create Web pages, see the book Using Caché Server Pages (CSP).

2.4 Creating a Web User Interface using Zen

Zen support several approaches to creating Web-based forms like the CSP form from the previous topic. In fact, the same
set of technologies provide the foundation for both CSP and Zen. Zen makes the development of fully-featured Web
applications easier while building on the client-server communication features that CSP provides. Their relationship is
explained further in the book Using Zen.
The tutorial in this topic guides you through creating a Zen page that can serve as a Web-based user interface to the project
you began in this chapter. The high-level steps are as follows:
1. Make your class a Zen data adaptor
2. Create a Zen page
3. Add a Zen form
4. Use the form to add database entries
5. Add a Zen table to display database entries

2.4.1 Making Your Class a Data Adaptor

This step takes the PhoneBook.Person class that you developed for the project you began in this chapter, and converts this
class to work as a Zen data adaptor. This is not the only way to work with Zen pages, but it is the quickest way build a Zen
user interface based on an existing class:
1. Open the PhoneBook.Person class.
2. Display the Studio Inspector window. In the left column header, choose Class from the drop-down list. An alphabetical
list of class keywords displays.

Using Caché Studio                                                                                                                                                              15

Building a Simple Application with Studio

3. Find the Super keyword and click on it to highlight it. The field currently holds the class name %Persistent. An ellipsis
button (...) appears at the right of this field. Click on it. This opens a dialog in which you can choose superclasses in
addition to %Persistent.

4. In the left-hand column of the dialog, navigate to the %ZEN.DataModel.Adaptor class and select it. At the center of the
dialog, click the > button. The %ZEN.DataModel.Adaptor class name now appears in the right-hand column underneath
%Persistent.

5. Click OK.
6. Save and compile the PhoneBook.Person class.

2.4.2 Creating a Zen Page

This step creates a Zen page class that you can edit to create the user interface for your project:
1.
Choose File > New or Ctrl-N or the New icon .
2. Select the Zen tab.
3. Click New Zen Page.
4. Click OK. The Zen Page Wizard displays:

16                                                                                                                                                              Using Caché Studio

 Creating a Web User Interface using Zen

Edit the dialog as follows:

• Enter the Package Name PhoneBook
• Enter the Class Name ZenPage
• Enter the Page Name My Telephone Book
• Click Next.

5. The wizard prompts you to select an initial page layout. Click Title Page. Then click Finish.
6. The Zen Page Wizard creates and displays a skeletal Zen page with pre-defined class parameters and the XML blocks
XData Style and XData Contents. You do not need to study this code in detail, but be aware of the location of XData
Contents in the class. You will be editing this XML block to add items to your new Zen page:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
<page xmlns="http://www.intersystems.com/zen" title="">
<html id="title">Title</html>
<vgroup width="100%">
<!-- put page contents here -->
</vgroup>
</page>
}

7.
Save and compile the class by choosing Build > Compile or Ctrl-F7 or the Compile icon .
8.
View the Web page by choosing View > Web Page or the View Web Page icon . At this point, the only item visible
in the browser is the text displayed by the <html> element:

If you examine the XData Contents block above, you will see that the <html> element provides an id="title"
attribute. id="title" refers to the style definition #title that appears in the XData Style block in the same Zen
page class. #title determines the background color, layout, and font choices that you see when you view the page.
The default XData Style block for the Title Page layout looks like this:

Using Caché Studio                                                                                                                                                              17

Building a Simple Application with Studio

XData Style
{
<style type="text/css">
/* style for title bar */
#title {
background: #C5D6D6;
color: black;
font-family: Verdana;
font-size: 1.5em;
font-weight: bold;
padding: 5px;
border-bottom: 1px solid black;
text-align: center;
}
</style>
}

9. Edit the text contents of the <html> element to provide a more meaningful title:
<html id="title">My Telephone Book</html>

10. Save and compile the class, then view the Web page. It should look like this:

2.4.3 Adding a Zen Form

Now that you have a Zen page class to work with, you can edit the XML elements in its XData Contents block to add items
to the display. In this exercise, you will begin by adding a form that allows you to add PhoneBook.Person objects to your
database:
1. In Studio, open the Zen page class.
2. Place <dataController> and <dynaForm> elements inside the main <vgroup> in XData Contents, exactly as shown in
the following example:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
<page xmlns="http://www.intersystems.com/zen" title="">
<html id="title">My Telephone Book</html>
<vgroup width="100%">
<dataController id="source" modelClass="PhoneBook.Person" modelId=""/>
<dynaForm id="MyForm" controllerId="source" />
</vgroup>
</page>
}

All you need to do is position the cursor between <vgroup> and </vgroup> and begin typing.
After you type the character < the Studio Assist feature prompts you to choose from a list of all elements. Typing <d
brings you to the part of the list that includes <dataController> and <dynaForm>. Double-click on one of the choices
to select it. Then type a space character and Studio Assist prompts you to choose from a list of attributes appropriate
for that element. You can continue in this manner until you have entered the entire line.
Alternatively, if you are viewing this document online, you may cut and paste the <dataController> and <dynaForm>
lines from the example above.
3. Provide two <button> elements in XData Contents, exactly as shown below:

18                                                                                                                                                              Using Caché Studio

 Creating a Web User Interface using Zen

XData Contents [XMLNamespace="http://www.intersystems.com/zen"]

{
<page xmlns="http://www.intersystems.com/zen" title="">
<html id="title">My Telephone Book</html>
<vgroup width="100%">
<dataController id="source" modelClass="PhoneBook.Person" modelId=""/>
<dynaForm id="MyForm" controllerId="source" />
<button caption="New" onclick="zenPage.newRecord();" />
<button caption="Save" onclick="zenPage.saveRecord();" />
</vgroup>
</page>
}

You can type the new elements, or if you are viewing this document online, for convenience you may cut and paste
the <button> lines from this example.
4. Save and compile the class, then view the Web page. It should look like this:

5. If you are curious about clicking the buttons New and Save, try it. An error message displays. Click OK to dismiss it.
To understand why you saw an error message when you clicked the buttons, look carefully at the values of the onclick
attribute for each <button> element in XData Contents. Each onclick value is a JavaScript expression that executes
automatically whenever the button is clicked.
In these examples, the onclick expression invokes a method that runs in JavaScript on the client. The special variable
zenPage indicates that the method is defined in the current Zen page class. The methods themselves are called
newRecord and saveRecord.
In order to make these onclick values work, you must create client-side JavaScript methods in the Zen page class. This
is quite simple to do using the Zen Method Wizard in Studio.

2.4.4 Adding Client-side Methods

In this step you add methods that create new objects and save them in response to button clicks. These methods permit you
to use your Zen form to populate your database with objects of the PhoneBook.Person class:
1. In Studio, open the Zen page class.
2. Position the cursor below the closing curly bracket of the XData Contents block, but before the closing curly bracket
for the Zen page class.
3. Choose Tools > Templates > Templates or press Ctrl-T to display the Studio Template dialog. Choose Zen Method Wizard.
Click OK. The following dialog displays:

Using Caché Studio                                                                                                                                                              19

Building a Simple Application with Studio

Edit the dialog as follows:

• Enter the Method Name newRecord
• Choose is an instance method
• Choose runs on the client
• Provide a Description as shown.
• Clear the Try/Catch check box.
• Click Finish. Your new method appears in the page class as follows:

/// Create a new instance of the controller object.

Method newRecord() [Language = JavaScript]
{
// TODO: implement
alert('Client Method');
}

4. Change the code within curly brackets so the method now looks like this:
/// Create a new instance of the controller object.
Method newRecord() [Language = JavaScript]
{
var controller = zenPage.getComponentById('source');
controller.createNewObject();
}

5. Repeat the above steps to add the saveRecord method. When using the Zen Method Wizard, enter values in the dialog
as follows:
• Enter the Method Name saveRecord
• Choose is an instance method
• Choose runs on the client
• Provide a Description.
• Clear the Try/Catch check box.
• Click Finish. Your new method appears in the page class.

Edit the new method so that it looks like this:

20                                                                                                                                                              Using Caché Studio

 Creating a Web User Interface using Zen

/// Save the current instance of the controller object.

Method saveRecord() [Language = JavaScript]
{
var form = zenPage.getComponentById('MyForm');
form.save();
}

6. Save and compile the class, then view the Web page.
7. Click the New button on the page. The Name and PhoneNumber fields become empty so that you can enter new
information for the next entry. After you have typed in each field, click the Save button. The new entry is saved in the
database.
8. Use New and Save repeatedly to add more entries.

2.4.5 Viewing the Database in a Table

Now that you have something in your database, you would like to be able to see it. In this step you will add a Zen table
that displays the saved objects from your database. You will then modify the saveRecord method so that it automatically
updates this table each time you click the Save button in the user interface:
1. In Studio, open the Zen page class.
2. Provide one <tablePane> element inside the main <vgroup> in XData Contents, exactly as shown below. You can type
the new element, or if you are viewing this document online, for convenience you may cut and paste the <tablePane>
lines from this example:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
<page xmlns="http://www.intersystems.com/zen" title="">
<html id="title">My Telephone Book</html>
<vgroup width="100%">
<dataController id="source" modelClass="PhoneBook.Person" modelId=""/>
<dynaForm id="MyForm" controllerId="source" />
<button caption="New" onclick="zenPage.newRecord();" />
<button caption="Save" onclick="zenPage.saveRecord();" />
<tablePane id="people"
sql="SELECT Name,PhoneNumber FROM PhoneBook.Person" />
</vgroup>
</page>
}

The <tablePane> sql attribute provides an SQL statement. SELECT lists the two properties from your PhoneBook.Person
class, and FROM provides the full package and class name. This SQL query provides the data for the <tablePane>.
3. Save and compile the class, then view the Web page.
4. Use New and Save to add more entries to the database.
5. Click the browser refresh button to view the updated table. The new entries are visible.
6. Remove the need for the user to refresh after each new entry, by refreshing the table automatically after each save. To
accomplish this, add two lines to the saveRecord method, so that it looks like this:
/// Save the current instance of the controller object.
Method saveRecord() [Language = JavaScript]
{
var form = zenPage.getComponentById('MyForm');
form.save();
var table = zenPage.getComponentById('people');
table.executeQuery();
}

7. Save and compile the class, then view the Web page. It should look like this:

Using Caché Studio                                                                                                                                                              21

Building a Simple Application with Studio

8. Use New and Save to add more entries to the database. Each time you click Save, the saveRecord method updates the
table so that the newest entry becomes visible.

To learn more about Zen, see the book Using Zen.

22                                                                                                                                                              Using Caché Studio

3
Creating Class Definitions
The Caché Studio lets you create and edit class definitions. A class definition specifies the contents of a particular class
including its members (such as methods and properties) and characteristics (such as superclasses).
With Studio you can work with class definitions with several tools:
• Wizards to quickly create classes and class members
• Class Inspector to view and edit class characteristics in a table
• Class Editor to directly edit the class definition. The Class Editor is a full-featured text editor that provides syntax
coloring, syntax checking, and code completion drop-down menus of available options.

You can use all of these techniques interchangeably; Studio automatically ensures that all of these representations are
synchronized.
This chapter discusses general aspects of creating class definitions. Most of the following chapters in this book describe
how to create class members, such as properties, methods, parameters, and so forth.

3.1 Creating New Class Definitions

You can create a new class definition in Studio by using the New Class wizard.

Note: You must have an open project before you can work with class definitions in the Caché Studio. When working
with class definitions, Studio performs numerous interactions with the Caché server (such as for providing lists
of classes, class compiling, etc.). Internally, Studio uses projects to manage the details of this server interaction.

3.1.1 New Class Wizard

To open the New Class wizard, select File > New and click New Class Definition.
The New Class wizard prompts you for information. Click Finish at any time (in this case, default values are provided for
any information you have not specified).

3.1.1.1 Name and Description Page

The New Class wizard prompts you for the following information (with the exception of class and package name, you can
later modify any of these values):

Using Caché Studio                                                                                                                                                              23

Creating Class Definitions

Package Name
Package to which the new class belongs. You can select an existing package name or enter a new name. If you
enter a new name, the new package is automatically created when you save your class definition.
For more information on packages see the chapter “Packages ” in Using Caché Objects.

Class Name
Name of your new class. This must be a valid class name and must not conflict with the name of a previously
defined class. Note that you cannot change this class name later.
For specifics of class naming conventions in Caché, see the section “Naming Conventions” in Using Caché
Objects.

Description
(optional) Description of the new class. This description is used when the class' documentation is displayed in the
online class library documentation.
A description may include HTML formatting tags. For more details see the section “Using HTML in Descriptions”
in the “ Class Definition Syntax ” appendix in this book.

3.1.1.2 Class Type Page

The New Class wizard asks you what type of class you would like to create. You can either extend (inherit from) a previously
defined class or create a new class by selecting one of the following options:

Persistent
Create a definition for a persistent class. Persistent objects can be stored in the database.

Serial
Create a definition for a serial class. Serial objects can be embedded in persistent objects to create complex data
types such as addresses.

Registered
Create a definition for a registered class. Registered objects are not stored in the database.

Abstract
Create a definition for an abstract class with no superclass.

Datatype
Create a definition for a data type class. A data type class is used to create user-defined data types.

CSP (used to process HTTP events)

Create a definition for a %CSP.Page class. A CSP class is used to create a CSP event handling class. This is a
programmatic way to create CSP Pages or to respond to HTTP events (for example, to create an XML server).

Extends
Extend an existing class: check Extends and enter (or choose from a list) the name of an existing superclass.

24                                                                                                                                                              Using Caché Studio

 Creating New Class Definitions

3.1.1.3 Data Type Class Characteristics Page

If you are creating a new data type class, the New Class wizard prompts for certain items particular to data type classes.
These include:

Client Data Type

The data type used by clients, such as Active X, to represent this data enter a client application.

ODBC Data Type

The data type used by ODBC or JDBC to represent this data type. Choose a type that corresponds to how you
want this data type to appear to ODBC/JDBC based applications.

SQL Category
The SQL Category used by the Caché SQL Engine when it performs logical operations on this data type.

3.1.1.4 Persistent, Serial, Registered Class Characteristics Page

If you are creating a new persistent or serial class, the New Class wizard prompts for certain items particular to persistent
or serial classes. These include:

Owner
(optional) For a persistent class, enter the SQL user name to be the owner of the new class. This user name controls
privileges when this class is used via SQL. If this field is left blank, then the default owner, _system, is used.

SQL Table Name

(optional) For a persistent class, enter a name to be used for the SQL table that corresponds to this class. If this
field is left blank, then the SQL table name is identical to the class name. If the class name is not a valid SQL
identifier, you must enter an SQL table name here.

XML Enabled
(optional) If selected, the class is XML-enabled; that is, it has the ability to project itself as an XML document. It
can also be used in Web Service methods. This is equivalent to adding the %XML.Adaptor class to the class'
superclass list.
For more information see Using XML with Caché as well as Using SOAP and Web Services with Caché.

Data Population
(optional) If you select this option, your new class supports automatic data population. This is equivalent to adding
the %Library.Populate class to the class' superclass list.
Automatic data population allows you to easily create random data with which you can test the operation of your
class. To populate a class, compile it and then execute the class' Populate method (inherited from the
%Library.Populate class). For example, using the Caché terminal:

Do ##class(MyApp.Person).Populate(100)

For more information see the chapter “Caché Data Population Utility ” in Using Caché Objects.

MultiValue Enabled
The created class inherits from %MV.Adaptor, such that the class uses MV storage and the data appears as a “file”
to MultiValue programs and queries.

Using Caché Studio                                                                                                                                                              25

Creating Class Definitions

3.1.1.5 CSP Class Characteristics Page

If you are creating a new CSP class, the New Class wizard prompts for the following value:

Content Type
Specifies what the content type served by this CSP class is. The available options are HTML or XML. This option
is used to set the value of the CONTENTTYPE parameter of the new class to text/html or text/xml respectively.
You can later change this to whatever value you want.

3.1.2 Results of Running the New Class Wizard

After running the New Class wizard, Studio displays a new Class Editor window. The Class Editor window contains your
new class definition. For example:
/// This is a Person class
class MyApp.Person extends %Persistent [ClassType = persistent]
{
}

You can save this class definition in the Caché database, add class members such as properties or methods, or edit the class
definition using the Class Inspector.

Note: By default, the New Class wizard creates classes that use Caché ObjectScript for method code. You can change
this default value to Basic with Tools > Options dialog, Environment, General tab.

3.2 Opening Class Definitions

You can open a previously saved class definition and display it in a Class Editor window by selecting the class in the Project
tab of the Workspace window and double-clicking it with the mouse.
If the class definition you want to open is not part of the current project, first add it to the current project using Project >
Add Class.

If the class definition you want to open is currently being edited by someone else, you are asked if you want to open the
class definition for read-only access.

3.3 Editing Class Definitions

You may modify any of the characteristics of a newly created or previously existing class definition (with the exception
of the class or package name). You can do this in two ways:
• Using the Class Inspector to change the value of a class or class member keyword.
• Changing a value in the class definition using the Class Editor.

For a list of class keywords and their meanings, see Caché Classes. For details on class definitions see the Class Definition
Language reference.

26                                                                                                                                                              Using Caché Studio

 Saving and Deleting Class Definitions

3.4 Saving and Deleting Class Definitions

If you have modified a class definition, save it to the Caché database in either of the following ways:
• Use File > Save to save the contents of the current window.
• Use Save Project to save all modified class definitions in the current project.

To delete a class definition, in the Workspace window, select a class and select Edit > Delete. The class and all of its generated
files are deleted.

3.5 Compiling Class Definitions

You can compile class definitions from Studio in these ways:
•
Using Build > Compile or the Compile icon, . This saves all modified class definitions and compiles the current class
definition (the one displayed in the active editor window).
• Using Build > Forced Compile . This saves all modified class definitions and forces the compilation the current class
definition: that is, the current class is compiled even if it has not been modified.
•
Using Build > Rebuild All or the Rebuild All icon, . This saves and compiles all open, modified class definitions.

Note: You can control how classes are compiled using options on Tools > Options dialog, Compiler tab).

3.5.1 Incremental Compilation

The Studio can do incremental compilation of classes. The feature is enabled with the Skip Related Up-to-date Classes
option. To find this option, open the Tools > Options dialog, Compiler, General Flags tab.
When enabled, if changes have been made to source code in one or more methods, only those methods are compiled with
Build > Compile. (Use Build > Rebuild All to override.) Any changes to the class interface (properties, method signatures,
etc.) or storage definition cause a full compilation.
Incremental compilation is typically much faster than a full compilation and speeds up the process of making incremental
changes to methods (application logic) during development.
Incremental compilation works as follows:
1. The Class Compiler finds all methods whose implementation has changed, places their runtime code into a new routine,
such as MyApp.MyClass.5.INT, and compiles this routine.
2. The Class Compiler then modifies the runtime class descriptor for the class to use the new implementations of the
compiled methods. When an application invokes one of these methods, the new code is dispatched to and executed.
3. The rest of the class definition (compiled meta-information, storage information for persistent classes, runtime SQL
information is left unchanged. Note that the previous implementation of the modified methods remains in the runtime
code but is not executed.

When a full (non-incremental) compilation is performed, all of the extra routines containing incrementally compiled
methods are removed. Perform a full compilation on all classes before deploying an application to avoid having extra routines.

Using Caché Studio                                                                                                                                                              27

Creating Class Definitions

3.5.2 Compilation and In-Use Classes

If you attempt to compile a class that has currently open instances, the default Caché behavior is for the compilation to fail
and to generate error number 5368, the text of which is “Objects of class '<classname>' are instantiated in <number-of-
processes> process(es).”
To correct this problem, either:
• Delete all instances of the class by invoking the KILL command on all open OREFs
• In Studio, select Tools > Options dialog, Compiler, General Flags tab and check the Compile in-use classes check box.

3.6 Renaming Class Definitions

Once you have created a class definition you cannot change its name. You can perform the equivalent of this operation by
creating a copy of the class with a new name as follows:
1. Select Tools > Copy Class.
2. Select the class you want to rename in the From field.
3. Enter the new class name in the To field.
4. Select any of the three options: Add new class to project, Replace instances of the class name,
or Copy Storage Definition.
5. Click OK.
6. You have a new Class Editor window containing a copy of the original class definition. Using the text editor, you can
make any additional changes you desire. You can save this new class definition when you like.
7. You can, if you want, delete the old class definition.

3.7 Class Inspector

The Class Inspector displays the current class definition in an editable table. The main components of the Class Inspector
are described below:

28                                                                                                                                                              Using Caché Studio

 Class Inspector

Figure 3–1: Class Inspector

1. Member Selector: Controls which set of keywords are displayed. You can choose to view either the Class-wide keywords
or the keywords for a specific class member (such as properties or methods).
2. Item Selector: Controls which specific class member is displayed (such as a particular property). The contents of the
list depend on the value of the Member Selector. Selecting (Summary) displays a list of all the members of the type
specified by the Member Selector.
3. Keywords: Lists the keywords for the current class or class member selected by the Member and Item Selectors.
Highlighting a keyword displays its description and allows editing (click Edit at the right of the value or directly edit
the value). Keywords whose value was set explicitly (not inherited or set by default) are shown in bold.
4. Values: Lists the values of keywords displayed in the keyword list. Values modified since the last time the class defi-
nition has been saved are displayed in blue.

3.7.1 Activating the Class Inspector

The Class Inspector displays current information when it is activated (it is gray when inactive). To activate the Class
Inspector:
1. Make sure that the current editor window contains a class definition (the Class Inspector does not work with Routines
or CSP files).
2. Click the Class Inspector

When the Class Inspector is activated its background turns white and its contents are updated to reflect the current class
definition. If you modify any keyword values using the inspector, the corresponding Class Editor window becomes inactive
(turn gray). When you are finished with the inspector, click the original Class Editor window. It becomes active and display
the result of the modifications you made using the Class Inspector.

Using Caché Studio                                                                                                                                                              29

Creating Class Definitions

If you right-click in the Class Inspector, it displays a popup menu allowing you to perform operations such as adding new
class members.

3.8 Class Browser

Studio includes a class browsing utility that lets you view all available classes arranged by class hierarchy. Within each
class you can view class members such as properties and methods, including those inherited from superclasses. The Class
Browser displays class members in a table. By click a column title, you can sort the class members by that column.
1. Open the Class Browser with Tools > Class Browser.
2. Right-click an item in the Class Browser and select whether to add it to the project, open it in the Class Editor, or view
documentation.

3.9 Superclass Browser and Derived Class Browser

Studio includes two additional browsers, one for listing all superclasses and one for listing derived classes from the current
class definition.

3.9.1 Superclass Browser

Open the Superclass Browser using Class > Superclasses to display an alphabetical list of all superclasses of the current
class.
Click a class and then click a button to either add it to the current project, open it in the Class Editor, or view documentation.

3.9.2 Derived Class Browser

Open the Derived Class Browser using Class > Derived Classes to display a list, in alphabetical order, of all the classes
derived from the current class definition.
Click a class and then click a button to either add it to the current project, open it in the Class Editor, or view documentation.

3.10 Package Information

Within Studio, you can view and edit information about a specific class package using the Package Settings dialog.
To open Package Information, in the Workspace window, in the Project tab, right-click the package name and select
Package Information.

30                                                                                                                                                              Using Caché Studio

 Package Information

Figure 3–2: Package Settings dialog

The Package Information window displays the following information:

Package Name Name of the package.

Description Description of the package
Owner SQL Owner name of this package. This is used to provide
Schema-wide privileges to the SQL representation of the package.
SQL Name Name of the SQL Schema used to represent the package
relationally.
Client Name Package name used for the generated projection of this package's
classes. For example, if this package contains a class named
bank.account, and you give it a client package name of
com.mycompany.bank. when the class is compiled, a Java projection
of this class is put into com.mycompany.bank.account.
Routine Prefix String that is used as a prefix for the routines generated from
classes in this package
Global Prefix String that is used as a prefix for the default global names used by
persistent classes in this package

For more information on class packages see the chapter “Packages” in Using Caché Objects.

Using Caché Studio                                                                                                                                                              31

4
Adding Properties to a Class
This chapter describes how to add properties in a class definition.
The data, or state, of an object is stored in it properties. Every class definition may contain zero or more property definitions.
You can add a new property to a class in two ways:
• Adding the property to the class definition in the Class Editor.
• Using the New Property wizard

To add a property using the Class Editor, position the cursor on a blank line in the Class Editor and enter a property decla-
ration:
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{
Property Name As %String;
Property Title As %String;
}

Alternatively, copy an existing property declaration, paste it into a new location, and edit it.
For details on property definitions see the “Class Definition Syntax ” appendix.

4.1 New Property Wizard

To open the New Property wizard, select Class > Add > New Property . Alternatively, right-click the Class Inspector and
select Add > New Property or, if only properties are displayed (Property heads the left column), right-click and select
New Property or select the New Property icon, from the toolbar.
The New Property wizard prompts you for information. Click Finish at any time; default values are provided for any
information you have not specified.

4.1.1 Name and Description Page

The New Property wizard prompts you for the following information (you can later modify any of these values):

Property Name
(required) Name of the new property. This name must be a valid property name and must not conflict with the
name of a previously defined property.

Using Caché Studio                                                                                                                                                              33

Adding Properties to a Class

For a general discussion on names see the chapter “Caché Classes ” in Using Caché Objects.

Description
(optional) Description of the new property. This description is used when the class' documentation is displayed
in the online class library documentation.
A description may include HTML formatting tags. For more details see “Using HTML in Descriptions ” in the
“ Class Definition Syntax” appendix.

4.1.2 Property Type Page

The New Property wizard asks you to select the property type: single-valued, a collection, a stream, or a relationship. You
can further refine each of these choices by specifying additional characteristics, such as data type.

Single Valued
A single-valued property is just that; it contains a single value. A single-valued property has a type associated
with it. This type is the name of a Caché class. If the class used as a type is a data type class, then the property is
a simple literal property; if it is a persistent class, then the property is a reference to an instance of that class; if it
is a serial class, then the property represents an embedded object.
You can enter a class name directly or choose from a list of available classes, including streams, using the Browse
button.
For a description of the basic data type classes provided with Caché, see the chapter “Data Types ” in Using Caché
Objects.

Collection
A collection property contains multiple values. There are two collection types, List (a simple, ordered list) and
Array (a simple dictionary with elements associated with key values). As with a single-valued property, a collection
property also has a data type. In this case, the data type specifies the type of the elements contained in the collection.

Relationship
A relationship property defines an association between two objects. For more details on relationships, see the
chapter “Adding Relationships to a Class ” in this book.

4.1.3 Property Characteristics Page

If you are adding a new property to a class definition for a persistent or serial object, the New Property wizard asks for
additional characteristics. These include:

Required
(optional) This is only relevant for persistent or serial classes. Specifies that this property is required (NOT NULL
in SQL terminology). For persistent or serial objects a required property must be given a value or any attempt to
save the object fails.

Indexed
(optional) This is only relevant for persistent classes. Specifies that an index should be created based on this
property. This is equivalent to creating an index based on this field.

34                                                                                                                                                              Using Caché Studio

 New Property Wizard

Unique
(optional) This is only relevant for persistent classes. Specifies that the value of this property must be unique in
the extent (set of all) objects of this class. This is equivalent to creating a unique index based on this field.

Calculated
(optional) A calculated property has no in-memory storage allocated for it when an object instance is created.
Instead, you must provide accessor (Get or Set) methods for the property. If you choose this option, the New
Property wizard can generate an empty Get accessor method for you.

SQL Field Name

(optional) In the case of a persistent class, this is the name that should be used for the SQL field that corresponds
to this property. By default (when this field is blank) the SQL field name is identical to the property name. Provide
an SQL field name if you want to use a different field name or if the property name is not a valid SQL identifier.

4.1.4 Data Type Parameters Page

Every property has a list of parameter values which is determined by the type of the property. The values of these parameters
control aspects of the property's behavior. Using the table displayed on the Parameters page of the New Property wizard
you can specify the value of particular parameters.

4.1.5 Property Accessors Page

You can override the Set method (used to set the value of a property) and Get method (used to retrieve the value of a
property) for a property by selecting the corresponding override check box. Choosing one of these options creates an empty
Set or Get method which you have to fill in later.

4.1.6 Results of Running the New Property Wizard

After running the New Property wizard the Class Editor window is updated to include the new property definition. For
example:
/// This is a Person class
Class MyApp.Person extends %Persistent [ClassType = persistent]
{
Property Name As %String;
}

If you want to make further modifications to this property you can do this using either the Class Editor or the Class
Inspector.

Using Caché Studio                                                                                                                                                              35

5
Adding Methods to a Class
This chapter discusses how to add and edit method definitions in a class definition.
The operations that are associated with an object and can be performed by it are referred to as methods. Every class definition
may contain zero or more methods.
You can add a new method to a class definition in two ways:
• Adding a method to the class definition using the Class Editor.
• Using the New Method wizard

To add a method using the Class Editor, position the cursor on a blank line in the Class Editor and enter a method declaration:
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{
Method NewMethod() As %String
{
Quit ""
}
}

Alternatively, you can do this by copying and pasting an existing method declaration and then editing it.
For details on method definitions see the Class Definition Syntax appendix.

5.1 New Method Wizard

You can invoke the New Method wizard using the Class > Add > New Method. Alternatively, right-click the Class Inspector
and select Add Method or select the New Method icon from the toolbar.
The New Method wizard prompts you for information. Click Finish at any time (default values are provided for any infor-
mation you have not specified).

5.1.1 Name and Description Page

The New Method wizard prompts you for the following information (you can later modify any of these values):

Method Name
(required) Name of the new method. This name must be a valid method name and must not conflict with the name
of a previously defined method.

Using Caché Studio                                                                                                                                                              37

Adding Methods to a Class

For a general discussion on names see the chapter “Caché Classes ” in Using Caché Objects.

Description
(optional) Description of the new method. This description is used when the class' documentation is displayed in
the online class library documentation.
A description may include HTML formatting tags. For more details see the section “Using HTML in Descriptions”
in the appendix “Class Definition Syntax ” in this book.

5.1.2 Method Signature Page

Every method has a signature that indicates its return type (if any) as well as its formal argument list (if any). For method
signature you may specify the following:

Return Type
(optional) Indicates the type of the value returned by this method. This type is the name of a Caché class. You can
type this name in directly or choose from a list of available classes using the Browse button.
For example, a method that returns a true (1) or false (0) value would have a return type of %Boolean. Leave this
field empty if your new method has no return value.
For a description of the basic data type classes provided with Caché see the chapter “Data Types” in Using Caché
Objects.

Arguments
(optional) Indicates the names, types, default values, and how data is passed (by reference or by value) for any
formal arguments. The arguments are displayed in order in a table. You can add a new item to the argument list
using Add located on the side of the table. This displays a popup dialog allowing you to specify the name of the
argument, its type, its optional default value, and whether it is passed by value or by reference. Using the other
buttons, you can remove and rearrange the order of items in the list.

5.1.3 Method Characteristics Page

You may specify additional characteristics for your method. These include:

Private
(optional) Indicates whether this method is public or private. Private methods may only be invoked from other
methods of the same class.

Final
(optional) Indicates whether this method is final. Final methods cannot be overridden by subclasses.

Class Method
(optional) Indicates that the new method is a class method (as opposed to an instance method). Class methods may
be invoked without having an object instance.

SQL Stored Procedure

(optional) Indicates that this method is accessible to an ODBC or JDBC client as a stored procedure. Only class
methods may be projected as SQL Stored Procedures.

38                                                                                                                                                              Using Caché Studio

 Overriding a Method

Language
Indicates the language used to create the method.

5.1.4 Implementation Page

If you want, you may enter the implementation (code) for the new method by typing lines of source code into the text editor
window. You can also enter this source code after running the wizard using the Class Editor.

5.1.5 Results of Running the New Method Wizard

After running the New Method wizard the Class Editor window is updated to include the new method definition. You can
edit it using either the Class Editor or the Class Inspector. For example:
/// This is a Person class
class MyApp.Person extends %Persistent [ClassType = persistent]
{
Method Print() As %Boolean
{
Write "Hello"
Quit 1
}
}

5.2 Overriding a Method

One of the powerful features of object-based development is that classes inherit methods from their superclasses. In some
cases, you may want to override, that is provide a new implementation for, a method inherited from a superclass.
Class > Override Method simplifies the process of overriding a specific method by displaying a list of all the methods defined
by superclasses that can be overridden by the current class.
For example, in a persistent class, you may want to override the default implementation of the %OnValidateObject method
provided by the %RegisteredObject class in order to specify custom validation that occurs when an instance of your class
is saved.
To do this, follow these steps:
1. Open (or create) a persistent class definition in Caché Studio.
2. Select Class > Override Method. This displays a dialog window containing a list of methods which you can override.
3. Select %OnValidateObject from the list and click OK button.

Your class definition should include a definition for an %OnValidateObject method:

class MyApp.Person extends %Persistent [ClassType = persistent]
{
// ...
Method %OnValidateObject() As %Status
{
}
}

At this point, you can use the Class Editor to add code to the body of the method.

Using Caché Studio                                                                                                                                                              39

6
Adding Class Parameters to a Class
A class parameter defines a 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.
You can add a class parameter to a class definition in two ways:
• Adding a class parameter to the class definition using the Class Editor.
• Using the New Class Parameter wizard.

To add a method using the Class Editor, position the cursor on a blank line in the Class Editor and enter a class parameter:
Parameter P1 = "x";

6.1 New Class Parameter Wizard

You can use the New Class Parameter Wizard to create a new class parameter. You can open the New Class Parameter
wizard using the Class > Add > New Class Parameter . Alternatively, right-click the Class Inspector and select Add New
Class Parameter or select the New Class Parameter icon on the toolbar.
The New Class Parameter wizard prompts you for information. Click Finish at any time (default values are provided for
any information you have not specified).
See for more information about class parameters see the chapter “Caché Classes ” in Using Caché Objects.
The New Class Parameter wizard prompts you for the following information (you can later modify any of these values):

Name
(required) Name of the class parameter. This name must be a valid parameter name and must not conflict with the
name of a previously defined parameter.
For a general discussion on names see the chapter “Caché Classes ” in Using Caché Objects.

Description
(optional) Description of the new class parameter. This description is used when the class' documentation is displayed
in the online class library documentation.

Using Caché Studio                                                                                                                                                              41

Adding Class Parameters to a Class

A description may include HTML formatting tags. For more details see the section “Using HTML in Descriptions”
in the “ Class Definition Syntax ” appendix.

Default
Default value for the class parameter. This will be the default value for this parameter for all instances of this
class.

42                                                                                                                                                              Using Caché Studio

7
Adding Relationships to a Class
A relationship is a special type of property that defines how two or more object instances are associated with each other.
For example, a Company class that represents a company could have a one-to-many relationship with an Employee class
that represents an employee (that is, each company may have one or more employees while each employee is associated
with a specific company).
A relationship differs from a property in that every relationship is two-sided: for every relationship definition there is a
corresponding inverse relationship that defines the other side.
For more information on relationships, see the chapter “Relationships ” in Using Caché Objects.
You can add a new relationship to a class definition in two ways:
• Adding a relationship to the class definition using the Class Editor.
• Using the New Property wizard

To add a relationship using the Class Editor, position the cursor on a blank line in the Class Editor and enter a relationship
declaration:
Class MyApp.Company Extends %Persistent [ClassType = persistent]
{
Relationship TheEmployees As Employee [cardinality=many, inverse=TheCompany];
}

A relationship definition must specify values for both the cardinality and inverse keywords.
As this relationship has two sides, also enter the inverse relationship in the class definition of Employee:
Class MyApp.Employee Extends %Persistent [ClassType = persistent]
{
Relationship TheCompany As Company [cardinality=one, inverse=TheEmployees];
}

If the two sides of the relationship do not correctly correspond to each other, there are errors when you try to compile.

7.1 New Property Wizard to Create a Relationship Property

You can use the New Property Wizard to create a new relationship property. To invoke this wizard, use Class > Add > New
Property. Alternatively, right-click the Class Inspector and select Add Property or select New Property on the toolbar.

The New Property wizard prompts you for information. The procedure is identical to creating a new, non-relationship
property except that you specify Relationship on the property type.

Using Caché Studio                                                                                                                                                              43

Adding Relationships to a Class

7.1.1 Name and Description Page

The New Property wizard prompts you for the following information (you can later modify any of these values):

Property Name
(required) Name of the relationship. This name must be a valid relationship (property) name and must not conflict
with the name of a previously defined relationship or property.
For a general discussion on names see the chapter “Caché Classes ” in Using Caché Objects.

Description
(optional) Description of the new relationship. This description is used when the class' documentation is displayed
in the online class library documentation.
A description may include HTML formatting tags. For more details see Using HTML in Descriptions in the Class
Definition Language reference.

7.1.2 Property Type Page

The New Property wizard asks you to choose from a variety of property types. Choose Relationship and enter the name
of the class on the inverse side of the relationship.

7.1.3 Relationship Characteristics Page

The New Property wizard asks for additional relationship characteristics. These include:
Cardinality

One: one other object

This relationship property refers to a single instance of the related object. The resulting property acts like a simple
reference field.

Many: many other objects

This relationship property refers to a one or more instances of the related object. The resulting property acts like
a collection of objects.

Parent: this object's parent

Identical to cardinality of one except that this is a dependent relationship and this property refers to the parent of
this object. Note: When you create a parent-child relationship, you are not given the option to create an index
because children aren't stored independently but within the parent; you can see that by looking at the global
structure. The children are indexed automatically by creating an extra subscript.

Children: the object's children

Identical to cardinality of many except that this is a dependent relationship and this property refers to a collection
of child objects.
Inverse:

This relationship property references objects of the following type

Select a class from the Browse button or enter a new class name for the inverse side of the relationship.

44                                                                                                                                                              Using Caché Studio

 New Property Wizard to Create a Relationship Property

The name of the corresponding property in the referenced class

Select a property from the class or enter a new property name for the inverse side of the relationship.

7.1.4 Additional Changes

Select any of the additional changes that you would like to implement:

Create a new class “<inverse class>”

This field is active if you entered a class name that does not exist for the inverse relationship on the last screen.
Check this to create the class in this package. The new class is added to the package. You must compile the new
class before you can compile the class that contains the relationship.

Create a new property “Parent ” in class “<inverse class> ”

This field is active if you entered a property that does not exist for the inverse relationship on the last screen. Check
this to create the property in the package and class named in the last screen. The new property is added to the
class. You must compile the class with this new property before you can compile the class that contains the rela-
tionship.

Modify property “Parent” of class “<inverse class> ”

This property is active if you entered a property that already exists for the inverse relationship on the last screen.
Check this to modify that property to be a relationship with this property.

Define an index for this relationship.

Check to define an index for this property. This is applicable only for One-To-Many relationships; it is disabled
for Parent-Child relationships

7.1.5 Results of Creating a New Relationship with the New Property Wizard
After creating a new relationship with the New Property wizard, the Class Editor window is updated to include the new
relationship definition. For example:
/// This is an Employee class
class MyApp.Employee extends %Persistent [ClassType = persistent]
{

/// We have a one-to-many relationship with Company

Relationship Company As Company [cardinality=one, inverse=Employees];
}

If you want to make further modifications to this relationship, you can do this using either the Class Editor or the Class
Inspector.
Additionally you can use the Modify Relationship wizard, which has the advantage of automatically determining the changes
required to the inverse of a relationship.
You can invoke the Modify Relationship wizard by following these steps:
1. Display the list of properties in the Class Inspector
2. Right-click the desired relationship in the list of properties and click Add/Modify Relationship command from the pop-
up menu.

Using Caché Studio                                                                                                                                                              45

8
Adding Queries to a Class
Caché class definitions may contain query definitions. Each query defines an instance of query interface: a set of methods
that can be called from a Caché %ResultSet object allowing you to iterate over a set of data.
You can use queries in the following ways:
• Via the %ResultSet class in server-based methods.
• Via the Java ResultSet class that is included with the Caché Java binding.
• Via the ActiveX ResultSet class that is included with the Caché ActiveX binding.
• As ODBC or JDBC stored procedures (if you specify that the query should be projected as an SQL stored procedure).

There are two kinds of queries:

• Those based on SQL statements (using the %SQLQuery class) and
• Those based on user-written code (using the %Query class).

The %SQLQuery class automatically provides an implementation of the query interface. The %Query class does not; the
query definition merely provides a query interface; you must write methods to implement the actual query functionality.
You can add a new query to a class definition in two ways:
• Edit the class definition using the Class Editor.
• Using the New Query wizard

To add a query using the Class Editor, position the cursor on a blank line in the Class Editor and enter a query declaration:
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{
Property Name As %String;

/// This query provides a list of persons ordered by Name.

Query ByName(ByVal name As %String) As %SQLQuery(CONTAINID = 1)
{
SELECT ID,Name FROM Person
WHERE (Name %STARTSWITH :name)
ORDER BY Name
}

Alternatively, you can copy and paste an existing query declaration and then edit it.
For a general introduction to queries, see the chapter “Queries ” of Using Caché Objects. For details on query definitions,
see the Class Definition Language reference.

Using Caché Studio                                                                                                                                                              47

Adding Queries to a Class

8.1 New Query Wizard

You can use the New Query wizard to add a new query to a class definition. You can open the New Query wizard using
Class > Add > New Query. Alternatively, right-click the Class Inspector and select Add Query or select the New Query icon,

, in the toolbar.
Click Finish at any time; default values are provided for any information you have not specified.

8.1.1 Name, Implementation, and Description Page

The New Query wizard prompts you for the following information (you can later modify any of these values):

Query Name
(required) Name of the new query. This name must be a valid query name and must not conflict with the name of
a previously defined query.
For a discussion of names, see the chapter “Caché Classes ” in Using Caché Objects.

Implementation
(required) You must specify if this query is based on an SQL statement (which the wizard generates for you) or
on user-written code (in which case you have to provide the code for the query implementation).

Description
(optional) Description of the new query. This description is used when the class documentation is displayed in the
online class library documentation.
A description may include HTML formatting tags. For more details see Using HTML in Descriptions in the Class
Definition Language reference.

8.1.2 Input Parameters Page

A query may take zero or more input parameters (arguments).
You can specify the names, types, default values, and how data is passed by value for these parameters. The arguments are
displayed in order in a table. You can add a new item to the argument list using the Add icon located on the side of the
table. This displays a popup dialog allowing you to specify the name of the argument, its type, its optional default value.
Using up, , and down arrows, , you can rearrange the order of items in the list.

8.1.3 Columns Page

For an SQL-based query, you must specify the object properties (columns) that you want included in the result set (this is
the SELECT clause of the generated SQL query).
To add a column to the query, select an item from the left-hand list of available properties and move it to the right-hand
list using the > (Move To) button.

8.1.4 Conditions Page

For an SQL-based query, you can specify conditions to restrict the result set (the SQL WHERE clause of the generated
SQL query).

48                                                                                                                                                              Using Caché Studio

 New Query Wizard

You can build a set of conditions by selecting values from the set of combo boxes. The expression box can contain an
expression (such as a literal value) or a query argument (as an SQL host variable with a prepended : colon character).

8.1.5 Order By Page

For an SQL-based query, you can specify any columns you want to use to sort the result set (the SQL ORDER BY clause
of the generated SQL query).

8.1.6 Row Specification Page

For a user-written query, you must specify the names and types of the columns that are to be returned by the query.
The wizard does not prompt for this information for SQL-based queries as the class compiler can determine it by examining
the SQL query.

8.1.7 Results of Running the New Query Wizard

After you run the New Query wizard, the Class Editor window is updated to include the new query definition. For example:
/// This is a Person class
class MyApp.Person extends %Persistent [ClassType = persistent]
{

Query ByName(ByVal name As %String) As %SQLQuery(CONTAINID = 1)

{
SELECT ID,Name FROM Person
WHERE (Name %STARTSWITH :name)
ORDER BY Name
}

If you want to make further modifications to this query you can do this using either the Class Editor or the Class Inspector.
If you specified a user-written query, the Class Editor contains both the new query definition as well as skeletons of the
query methods you are expected to implement:
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{
// ...

ClassMethod MyQueryClose(
ByRef qHandle As %Binary
) As %Status [ PlaceAfter = MyQueryExecute ]
{
Quit $$$OK
}

ClassMethod MyQueryExecute(
ByRef qHandle As %Binary,
ByVal aaa As %Library.String
) As %Status
{
Quit $$$OK
}

ClassMethod MyQueryFetch(
ByRef qHandle As %Binary,
ByRef Row As %List,
ByRef AtEnd As %Integer = 0
) As %Status [ PlaceAfter = MyQueryExecute ]
{
Quit $$$OK
}

Query MyQuery(
ByVal aaa As %Library.String
) As %Query(ROWSPEC = "C1,C2")
{

Using Caché Studio                                                                                                                                                              49

Adding Queries to a Class

50                                                                                                                                                              Using Caché Studio

9
Adding Indices to a Class
This chapter discusses how to add and edit index definitions to a persistent class definition.
An index definition instructs the Caché class compiler to create an index for one or more properties. Indices are typically
used to make SQL queries more efficient.
You can add an index to a class definition in two ways:
• Editing the class definition using the Class Editor.
• Using the New Index wizard

To add an index using the Class Editor, position the cursor on a blank line in the Class Editor and enter an index declaration:
Index NameIndex On Name;

Alternatively, copy and paste an existing index declaration and then edit it.
For details on index definitions see the Class Definition Language reference.

9.1 New Index Wizard

You can invoke the New Index wizard using the Class > Add > New Index. Alternatively, right-click the Class Inspector
and select Add Index or select the New Index icon, , from the toolbar.
The New Index wizard prompts you for information. To end, click Finish (default values are provided for any information
you have not specified).

9.1.1 Name and Description Page

The New Index wizard prompts you for the following information (you can later modify any of these values):

Index Name
(required) Name of the new index. This name must be a valid index name and must not conflict with the name of
a previously defined index.
For a discussion of valid names, see the chapter “ Caché Classes” in Using Caché Objects.

Using Caché Studio                                                                                                                                                              51

Adding Indices to a Class

Description
(optional) Description of the new index. This description is used when the class' documentation is displayed in
the online class library documentation.
A description can include HTML formatting tags. For details, see the section “Using HTML in Descriptions” in
the “Class Definition Syntax” appendix of this manual.

9.1.2 Index Type Page

Caché supports the following types of indices.

Normal Index
A normal index is used for indexing on property values. You can further qualify a normal index by selecting one
of the following:

Unique Index The set of properties associated with this index must have a combined value
that is unique in the extent of objects of this class.
IDKEY The set of properties associated with this index are used to create the Object
ID value used to store instances of this class in the database.You cannot modify
the values of properties that are part of an IDKEY definition once an object has
been saved. IDKEY implies that the property or properties are unique (as with
a Unique Index).
SQL Primary The set of properties associated is reported as the SQL Primary Key for the
Key SQL table projected for this class. This implies that the property or properties
are unique (as with a Unique Index).

Extent Index
An extent index is used to keep track of which objects belong to a specific class in a multiclass extent of objects.
It differs from a so-called normal index in that you cannot specify additional characteristics for it.
You can also select how the index is physically implemented in the database:

Standard Index
This index is a traditional cross-index on the specified property or properties.

Bitmap Index
A bitmap index uses a compressed representation of a set of object ID values that correspond to a given indexed
value. See Bitmap Indices in Using Caché SQL for more information.

Bitslice Index
A bitslice index is a specialized form of index that enables very fast evaluation of certain expressions, such as
sums and range conditions. Bitslice indices are currently automatically used in certain Cache SQL queries. Future
versions of Cache SQL will make further use of bitslice indices to optimize additional queries.

9.1.3 Index Properties Page

On the Index Properties page, you can enter a list of one or more properties on which the index is based. For each property
you can specify to override the default collation function used to transform values stored in the index as well as any
parameters for the collation function.

52                                                                                                                                                              Using Caché Studio

 Populating an Index

9.1.4 Index Data Page

On the Index Data page, elect to store a copy of the data for any properties in the index.
You cannot store copies of data values with a bitmap index.

9.1.5 Results of Running the New Index Wizard

After running the New Index wizard, the Class Editor window is updated to include the new index definition. For example:
/// This is a Person class
class MyApp.Person extends %Persistent [ClassType = persistent]
{

Property Name As %String;

Index NameIndex On Name;

}

You can edit the index definition with either the Class Editor or the Class Inspector.

9.2 Populating an Index

After you add an index definition to a class and compile, you can populate the index (place data into it) by using Rebuild
Indices, found in the Caché System Management Portal (Building Indices).

The Studio does not automatically place data into indices.

Using Caché Studio                                                                                                                                                              53

10
Adding Projections to a Class
This chapter discusses how to add projection definitions in a class definition.
A projection definition instructs the Caché class compiler to perform specified operations when a class definition is compiled
or removed. A projection defines the name of a projection class (derived from the %Projection.AbstractProjection class) that
implements methods that are called when a) the compilation of a class is complete and b) when a class definition is removed
(either because it is being deleted or because the class is about to be recompiled).
A class can contain any number of projection definitions. The actions for all of them are invoked when the class is compiled
(the order in which they are invoked is not defined).
Caché includes predefined projection classes that generate client code that allows access to a class from Java or an EJB
server. See the class in the class reference for definitions of parameters for each class.
To generate C++-related classes, use Tools > Generate C++ Projection or the cpp_generator command line interface. For
more information, see the chapter “Using the C++ Generator Program ” in Using C++ with Caché.
Table 10–1: Projection Classes

Class Description
%Projection.EJB 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.
%Projection.EJBFlexible Generates the appropriate external files required by a generic EJB Server for the Caché
EJB Binding for the associated class.
%Projection.EJBJBoss Generates a set of Enterprise Java Bean client classes to enable access to the class from
an JBoss EJB server. In addition, any other files, such as deployment descriptors are
created.
%Projection.EJBPramati Generates a set of Enterprise Java Bean client classes to enable access to the class from
an Pramati EJB server. In addition, any other files, such as deployment descriptors are
created.
%Projection.EJBWebLogic Generates a set of Enterprise Java Bean client classes to enable access to the class from
an WebLogic EJB server. In addition, any other files, such as deployment descriptors are
created.
%Projection.Java Generates a Java client class to enable access to the class from Java.
%Projection.Monitor Registers this class as a routine that works with Cache Monitor. Metadata is written to
Monitor.Application, Monitor.Alert, Monitor.Item and Monitor.ItemGroup. A new persistent class is
created called Monitor.Sample.

Using Caché Studio                                                                                                                                                              55

Adding Projections to a Class

Class Description
%Projection.MV Generates an MV class that enables access to the class from MV.
%Projection.StudioDocument Registers this class as a routine that works with Studio.
%Projection.XML Generates an XML class that enables access to the class from XML.
%Studio.Extension.Projection Projects the XData 'menu' block to the menu table.
%ZEN.Object.Projection Projection class used by %ZEN.Component.object classes. This is used to manage
post-compilation actions for Zen components.
%ZEN.PageProjection Projection class used by %ZEN.Component.page. Currently this does nothing.
%ZEN.Tempa
l te.Tempa
l teProe
j co
tin Projection class used by %ZEN.Templage.studioTemplate class.

You can also create your own projection classes and use them from Studio as you would any built-in projection class.
You can add a new projection to a class definition in two ways:
• Editing the class definition using the Class Editor.
• Using the New Projection wizard

To add a projection using the Class Editor, position the cursor at a blank line and enter a projection declaration:
Projection MyProjection As %Projection.XML;

Alternatively, you can copy and paste an existing projection declaration and then edit it.
For details on projection definitions, see the Class Definition Language reference.

10.1 New Projection Wizard

You can invoke the New Projection wizard using the Class > Add > New Projection and asking for a new Projection. Alter-
natively right-click in the Class Inspector and select New Projection.
The New Projection wizard displays pages prompting you for information about the new projection. To end, click Finish
(in this case, default values are provided for any information you have not specified).

10.1.1 Name and Description Page

The New Projection wizard prompts you for the following information (you can later modify any of these values):

Projection Name
(required) Name of the new projection. This name must be a valid projection name and must not conflict with the
name of a previously defined projection.

Description
(optional) Description of the new projection.

56                                                                                                                                                              Using Caché Studio

 New Projection Wizard

10.1.2 Projection Type Page

The projection type determines what actions happen when your class definition is compiled or removed. You can select
what kind of projection you would like to define:

Projection Type
Name of a projection class whose methods are executed when a class definition is compiled or removed.

Projection Parameters
A set of name-value pairs that control the behavior of the projection class. The list of available parameter names
is determined by the selected projection class.

10.1.3 Results of Running the New Projection Wizard

When you finish running the New Projection wizard, the Class Editor window is updated to include the new projection
definition. For example:
/// This is a Person class
class MyApp.Person extends %Persistent [ClassType = persistent]
{

Property Name As %String;

Projection JavaClient As %Projection.Java;

}

To edit this projection definition, use either the Class Editor or the Class Inspector.

Using Caché Studio                                                                                                                                                              57

11
Adding XData Blocks to a Class
An XData block is a block of XML code that you can add to your class definition.
You can add an XData block to a class definition in two ways:
• Editing the class definition using the Class Editor.
• Using the XData wizard

To add an XData block using the Class Editor, position the cursor at a blank line and enter an XData declaration:
XData ProductionDefinition
{
<Production>
<ActorPoolSize2/ActorPoolSize>
</Production>
}

Alternatively, you can copy and paste an existing XData block and then edit it.

11.1 New XData Wizard

You can invoke the New Projection wizard using the Class > Add > New XData. Alternatively, right-click in the Class
Inspector and select Add Projection.
The New XData wizard displays a single page prompting you for a name for the XData block and a description. To end,
click Finish. Add XML code into the Class Editor window to complete the XData block.
The New XData wizard prompts you for the following information (you can later modify any of these values):

XData Name
(required) Name of the new XData. This name must be a valid name and must not conflict with the name of a
previously defined XData.

Description
(optional) Description of the new XData.

Using Caché Studio                                                                                                                                                              59

12
Adding SQL Triggers and Foreign Keys
to a Class
Every persistent Caché class is automatically projected as an SQL table. This chapter discusses how you can use Studio
with those parts of a class definition that control its SQL behavior.

12.1 SQL Aliases

You can give classes as well as most class members an alternate name for use by SQL. This is useful because:
• There is a long list of SQL reserved words that cannot be used as identifiers.
• Caché does not support the underscore character in class or class member names.

To specify an SQL table name for a class, view the Class information in the Class Inspector and edit the value for the
SqlTableName keyword.

To specify an SQL name for a class member, select the desired property in the Class Inspector and edit the value for its
appropriate SQL name keyword (such as SqlFieldName for properties and SqlName for indices).

12.2 SQL Stored Procedures

An SQL Stored procedure is a Caché method or class query than can be invoked from an ODBC or JDBC client as a stored
procedure.
Caché supports two styles of SQL stored procedure: those based on class queries and that return a result set; and those
based on class methods and that do not return a result set.

12.2.1 Query-Based Stored Procedure

To create an SQL stored procedure that returns a result set, add a query definition to a class definition and then set the
query's SqlProc keyword to true. Do this as follows:
1. Create a query in a class definition using the New Query wizard with Class > Add > New Query.
2. Using the Class Inspector, set the value of the query definition keyword SqlProc to True.

Using Caché Studio                                                                                                                                                              61

Adding SQL Triggers and Foreign Keys to a Class

You should end up with something similar to:

Class Employee Extends %Persistent [ClassType = Persistent]
{

/// A class query listing employees by name.

Query ListEmployees() As %SQLQuery(CONTAINID = "1") [SqlProc]
{
SELECT ID,Name
FROM Employee
ORDER BY Name
}
}

You can invoke this stored procedure from an ODBC or JDBC client using a CALL statement:
CALL Employee_ListEmployees()

Following this call, the ODBC or JDBC application can fetch the contents of the result set returned by the class query.
Note that you can use this same technique with query definitions that are based on custom-written code; you are not limited
to defining stored procedures solely based on SQL statements.

12.2.2 Creating Method-Based Stored Procedure

To create an SQL stored procedure that does not return a result set, add a class method to a class definition and then set the
method's keyword SqlProc to True. Do this as follows:
1. Create a class method in a class definition using the New Method wizard.
2. Using the Class Inspector, set the value of method's keyword SqlProc to True.

You should end up with something similar to:

Class Employee Extends %Persistent [ClassType = Persistent]
{

ClassMethod Authenticate(
ctx As %SQLProcContext,
name As %String,
ByRef approval As %Integer
) [SqlProc]
{
// ...
Quit
}

Note that the first argument of a method used as an SQL stored procedure is an instance of a %SQLProcContext object. For
more information, see the chapter “Defining and Using Stored Procedures ” in Using Caché SQL.
You can invoke this stored procedure from an ODBC client using a CALL statement:
CALL Employee_Authenticate('Elvis')

To invoke this stored procedure from a JDBC client, you can use the following code:
prepareCall("{? = call Employee_Authenticate(?)}")

12.3 Adding SQL Triggers to a Class

An SQL trigger is code that is fired by the SQL Engine in response to certain events.
Note that SQL triggers are not fired during object persistence (unless you are using %CacheSQLStorage storage class).

62                                                                                                                                                              Using Caché Studio

 Adding SQL Triggers to a Class

You can add an SQL trigger to a class definition in two ways:

• Editing the class definition using the Class Editor.
• Using the New SQL Trigger wizard

To add an SQL trigger using the Class Editor, position the cursor on a blank line in the Class Editor and enter a trigger
declaration:
Class MyApp.Company Extends %Persistent [ClassType = persistent]
{

/// This trigger updates the Log table for every insert
Trigger LogEvent [ Event = INSERT ]
{
// ...
}

12.3.1 New SQL Trigger Wizard

You can use the New Trigger wizard to create a new SQL trigger. You can open the New SQL Trigger wizard using Class
> Add > New SQL Trigger. Alternatively, right-click in the Class Inspector and select Add SQL Trigger .

The New SQL Trigger wizard prompts you for information. Click Finish at any time (default values are provided for any
information you have not specified).

12.3.1.1 Name and Description Page

The New SQL Trigger wizard prompts you for the following information (you can later modify any of these values):

Trigger Name
(required) Name of the trigger. This name must be a valid trigger name and must not conflict with the name of a
previously defined trigger.

Description
(optional) Description of the new trigger. This description is used when the class' documentation is displayed in
the online class library documentation.

12.3.1.2 Trigger Event Page

The New SQL Trigger wizard asks you to indicate when you want the new trigger to be fired by specifying the event and
time for the trigger.

Event Type
This specifies which SQL event fires the trigger. The choices are Insert (when a new row is inserted), Update
(when a row is updated), or Delete (when a row is deleted).

Event Time
This specifies when the trigger is fired. The choices are Before or After the event occurs.

12.3.1.3 Trigger Code

The New SQL Trigger wizard lets you enter the source code for the trigger if you want.

Using Caché Studio                                                                                                                                                              63

Adding SQL Triggers and Foreign Keys to a Class

12.3.1.4 Results of Running the New SQL Trigger Wizard

After you finish using the New SQL Trigger wizard, the Class Editor window is updated to include text for the new trigger
definition.
If you want to edit this trigger you can do this using either the Class Editor or the Class Inspector.

12.4 Adding New SQL Foreign Keys to a Class

An SQL foreign key defines an integrity constraint between one or more fields in a table and a key (unique index) in another
table.
Object applications typically do not use foreign keys; they instead use relationships which offer better object-based navigation.
Relationships automatically impose integrity constraints (for both SQL and object access) that are equivalent to manually
defining foreign key definitions.
Typically you use foreign key definitions in applications that are originally purely relational in nature.
You can add an SQL foreign key to a class definition in two ways:
• Editing the class definition using the Class Editor.
• Using the New SQL Foreign Key wizard

To add an SQL foreign key using the Class Editor, position the cursor on a blank line in the Class Editor and enter a foreign
key declaration:
Class MyApp.Company Extends %Persistent [ClassType = persistent]
{

Property State As %String;

ForeignKey StateFKey(State) References StateTable(StateKey);

12.4.1 New SQL Foreign Key Wizard

Open the New SQL Foreign Key wizard using the Class > Add > New Foreign Key. Alternatively you can right-click the
Class Inspector and selecting Add Foreign Key or select the New Foreign Key icon, , from the toolbar.
The New SQL Foreign Key wizard prompts you for information. When you have filled in the required information, click
Finish (default values are provided for any information you have not specified).

12.4.1.1 Name and Description Page

The New SQL Foreign Key wizard prompts you for the following information (you can later modify any of these values):

Foreign Key Name

(required) Name of the foreign key. This name must be a valid foreign key name and must not conflict with the
name of previously defined foreign key.
For a general discussion on names see the chapter “Caché Classes ” in Using Caché Objects.

64                                                                                                                                                              Using Caché Studio

 Adding New SQL Foreign Keys to a Class

Description
(optional) Description of the new foreign key. This description is used when the class' documentation is displayed
in the online class library documentation.
A description can include HTML formatting tags. For more details see Using HTML in Descriptions in the Class
Definition Language reference.

12.4.1.2 Attributes Page

The second page asks you to select one or more properties of the class that you want constrained by the foreign key.

12.4.1.3 Key Construction Page

The third page asks you to select both the class and a key (unique index) in that class that specify the values used to constrain
the foreign key properties.

12.4.1.4 Results of Running the New SQL Foreign Key Wizard

After running the New SQL Foreign Key wizard, the Class Editor window is updated to include the new foreign key defi-
nition.
If you want to make further modifications to this foreign key you can do this using either the Class Editor or the Class
Inspector.

Using Caché Studio                                                                                                                                                              65

13
Adding Storage Definitions to a Class
The physical storage used by a persistent or serial class is specified by means of a storage definition. You can use Studio
to view and edit such storage definitions.

Note: Storage definitions are a fairly advanced feature of Caché objects. In most cases, you do not need to work with
storage definitions; the Caché class compiler automatically creates and manages storage definitions for persistent
objects.
If you use storage definitions, you typically work with them in the following cases:
• You need detailed control over the storage used by a persistent object, perhaps for performance tuning.
• You are mapping an object definition on top of a preexisting data structure.

A class can have any number of storage definitions, though only one can be used at one time. A new class does not have
a storage definition until either you first a) save and compile the class, or, b) you explicitly add one. You can add a new
storage definition to a class using Class > Add > New Storage.

Note: Compiling a class automatically generates its storage definition. Only persistent and serial classes have storage
definitions.

Within Studio, you can view and edit the storage definition(s) for a class in two different ways:
• Visually, using the Storage Inspector in the Class Inspector window: select Storage in the Class Inspector and click
the desired storage definition.
• Textually, using the Class Editor window: use View > View Storage to display the storage definition in the body of the
class definition.

These techniques are described in the following sections.

13.1 Adding Storage Definitions to a Class

You can add a new storage definition to a class definition in two ways:
• Adding a storage definition to the class definition using the Class Editor (this assumes you have used View > View
Storage to display the storage definition).

• Using the New Storage wizard.

Using Caché Studio                                                                                                                                                              67

Adding Storage Definitions to a Class

13.1.1 Using the New Storage Wizard

You can use the New Storage wizard to add a new storage definition to a class definition. You can start the New Storage
wizard using Class > Add > New Storage. Alternatively, right-click in the Class Inspector and selecting Add > New Storage
or select the New Storage icon, , from the toolbar.
The New Storage wizard prompts you for information. Click Finish at any time (in this case, default values are provided
for any information you have not specified).

13.1.1.1 Name,Type, Description Page

The New Storage wizard prompts you for the following information (you can later modify any of these values):

Storage Name
(required) Name of the new storage definition. This name must be a valid class member name and must not conflict
with the name of a previously defined storage definition.

Storage Type
(required) Type of storage used by this storage definition. The type specifies which storage class is responsible
for implementing the storage interface for this class. The choices are:
• Caché Storage—this storage definition is based on the %CacheStorage class. This is the default storage type
used for new persistent classes.
• Caché SQL Storage—this storage definition is based on the %CacheSQLStorage class. This storage type uses
SQL statements to perform storage operations. This storage type is used for mapping objects to existing data
structures or to talk to remote RDBMS via the Caché SQL Gateway.
• Custom Storage—this storage definition is based on a user-defined storage class.

Description
(optional) Description of the new storage definition.
A description can include HTML formatting tags. For more details see Using HTML in Descriptions in the Class
Definition Language reference.

13.1.1.2 Global Characteristics of a %CacheStorage Definition Page

For a %CacheStorage storage definition, the New Storage wizard lets you specify some characteristics of the globals (per-
sistent multidimensional arrays) used to store the data and indices for the persistent class. These characteristics include:

DataLocation
Name of the global as well as any leading subscripts used to store instances of the persistent class. For example,
to specify that data should be stored in the global ^data, enter ^data in this field. To specify that data should be
stored in the global subnode ^data("main"), enter ^data("main").

IndexLocation
Name of the global as well as any leading subscripts used to store index entries for the persistent class. By default,
indices are stored in the Index Reference global with an additional subscript based on the Index name. You can
override this on an index-by-index basis.

68                                                                                                                                                              Using Caché Studio

 Using the Class Inspector with Storage Definitions

IdLocation
Name of the global as well as any leading subscripts used to contain the default object ID counter. The object ID
counter is used to maintain the ID number of the next object instance of this type.

13.2 Using the Class Inspector with Storage Definitions

You can use the Class Inspector to visually view and edit a class' storage definition. The Class Inspector displays a list of
storage definitions in the same way that it displays methods or properties.
To view an existing storage definition in the Class Inspector:
1. Click the Class Inspector
2. Select Storage in the Inspector's Member list pull-down.
3. Double-click a storage definition.

At this point, the Class Inspector displays storage keywords along with their values.

Data Nodes
Represents the set of data mappings used by the %CacheStorage storage class. The Data Nodes editor, which you
can invoke by double-clicking on the Data Nodes keyword, allows you to view and edit the set of data node
specifications for the storage definition: that is, you can directly specify how your class' properties are stored in
global nodes.

SQL Storage Map

Represents the set of data mappings used by the %CacheSQLStorage storage class. The SQL Storage Map editor,
which you can invoke by double-clicking the SQL Storage Map keyword, allows you to view and edit the set
of mappings used to map object properties to existing data structures.

13.3 Using the Class Editor with Storage Definitions

You can use the Class Editor to view and edit a class' storage definition. To display a class' storage definition(s) use View
> View Storage. This toggles the display of storage information in the current Class Editor window.

A storage definition is displayed as an in-line XML island in the body of the class definition using the same XML elements
that are used in the external, XML-representation of a class definition.
For example, suppose you have a simple persistent MyApp.Person class:
/// A simple persistent class
Class MyApp.Person Extends %Persistent [ ClassType = persistent ]
{
Property Name As %String;
Property City As %String;
}

After compiling this class (to ensure that the class compiler has created a storage definition for it), you can display its
storage definition using the View > View Storage. This results in following display in the Class Editor window:
/// A simple persistent class
Class MyApp.Person Extends %Persistent [ ClassType = persistent ]
{

Using Caché Studio                                                                                                                                                              69

Adding Storage Definitions to a Class

Property Name As %String;

Property City As %String;

<Storage name="Default">
<Data name="PersonDefaultData">
<Value name="1">
<Value>City</Value>
</Value>
<Value name="2">
<Value>Name</Value>
</Value>
</Data>
<DataLocation>^MyApp.PersonD</DataLocation>
<DefaultData>PersonDefaultData</DefaultData>
<IdLocation>^MyApp.PersonD</IdLocation>
<IndexLocation>^MyApp.PersonI</IndexLocation>
<Type>%Library.CacheStorage</Type>
</Storage>
}

The XML storage definition includes all the defined storage keywords and their corresponding values represented as XML
elements.
You can directly edit this definition in the Class Editor as you would any other part of the class definition. If you enter
invalid XML syntax the editor colors it as an error.
The storage definition can be useful in cases where you need to do simple or repetitive modifications.
For example, suppose you want to change the name of a property City to HomeCity, while preserving the physical storage
layout (that is, you want the new property name to access the values stored with the old name). You can do this using the
Class Editor as follows:
1. Load the class definition into a Studio Class Editor window and display its storage.
2. Use the Editor's Replace command to replace all occurrences of the property City with HomeCity. You must be careful
to only change those occurrences of City that represent the property name (such as in the property definition, method
code, descriptions, and in the body of the storage definition); do not replace the values of any class definition keywords.
3. Save and recompile the class definition.

70                                                                                                                                                              Using Caché Studio

14
Working with CSP Files
A CSP (Caché Server Page) file is a text file containing HTML, XML, or CSP markup commands. This file is stored on a
Caché server machine and is compiled, by the CSP Engine, into an executable class that can process HTTP events sent
from a browser.
You can use Caché Studio to create and edit CSP files in the same way you would work with class definitions or routines.
CSP files are displayed in the Studio syntax-coloring editor allowing you to quickly spot errors in HTML as well as in any
embedded server-side scripts.

14.1 Sample CSP Page

To create a simple CSP page with Caché Studio, perform the following steps:
1. Start Studio and create a new Project in the SAMPLES namespace.
2. Create a new CSP file (with File > New > CSP File tab > Caché Server Page) .
3. Studio creates a new CSP Editor window containing a new CSP file named Untitled.csp.
Replace the contents of the editor window with:
<HTML>
<HEAD>
<TITLE>Sample Page</TITLE>
</HEAD>
<BODY>
My Sample CSP Page.
</BODY>
</HTML>

4. Save the page with File > Save. The Save As dialog appears. Within the dialog, double-click the CSP application
/csp/samples (this is the directory in which we are going to save this CSP page) and then enter Sample.csp in the Filename
box. Click Save As.
5. Compile the page with Build > Compile .
6. View the resulting Web page from a browser with View > Web Page.

At this point, you should see a very simple Web page containing the words My Sample CSP Page in your browser.
To make this example more interesting, we can add an SQL query to the page that executes when the page is requested:
1. Position the cursor in the CSP Editor window at the start of the blank line after My Sample CSP Page.
2. Select Insert > SQL Query. In the dialog that appears enter the following SQL query:

Using Caché Studio                                                                                                                                                              71

Working with CSP Files

SELECT Name,SSN FROM Sample.Person ORDER BY Name

3. Check Create HTML Table and click OK.

4. Save and recompile the page with Build > Compile.
5. View the resulting Web page from a browser with View > Web Page .

Now your CSP page displays a list of names and social security numbers in an HTML table.

14.2 Creating a New CSP File

To create a new CSP file, select File > New > CSP File tab > Caché Server Page. This creates a new CSP file named Untitled.csp.
When you save this file for the first time, you are asked for a file name. If this file is part of a CSP application, create a
folder with an application name, in which to put your new file.
The file name, which must have a .csp extension, is used for both saving a physical source file on the Caché server as well
as in a URL requesting this page. The application name also determines the URL used to request the CSP page as well as
other characteristics.
For more information on CSP files and applications, see the Caché Server Pages documentation.

14.2.1 Default.csp Template File

When you create a new CSP file in Studio, it opens a new CSP Editor window and copies into it the contents of a CSP
template file. You can edit or replace this template file in order to customize how Studio creates new CSP files. This file
is a text file called Default.csp and is located in the same directory as the Studio executable file. For a default installation,
this is the /cachesys/bin directory.

14.3 Editing a CSP File

You can edit a CSP file in the same way you would edit any other document in Caché Studio.

14.3.1 Insert Options

The Studio includes dialogs, a wizard, and templates to assist with editing CSP files. These dialogs are available under the
Insert menu and are described in the table below.

The templates are in theCSP/samples directory in the installation directory . To view a sample, open a file in Studio, such
as zipcode.csp and then select View > Web Page. The Web Form Wizard is available in the Tools > Templates > Templates
menu.

72                                                                                                                                                              Using Caché Studio

 Saving a CSP File

Insert Menu Action

Option
Class Inserts a <csp:CLASS> tag at the current cursor location.
Loop Inserts a <csp:LOOP> tag at the current cursor location.
While Inserts a <csp:WHILE> tag at the current cursor location.
Method Inserts a Caché objects method (in a <SCRIPT> tag) at the current cursor location
Object Inserts a <csp:OBJECT> tag at the current cursor location.
Query Inserts a <csp:QUERY> tag at the current cursor location.
SQL Query Inserts an SQL query (in a <SCRIPT> tag) at the current cursor location.

14.4 Saving a CSP File

Save a CSP file using the File > Save. This sends the source of the CSP file back to the Caché server (which could be on a
remote machine) and save it on the server's local file system in the appropriate directory (specified by the Caché server's
CSP application settings).

14.5 Compiling a CSP File

Compile a CSP file using Build > Compile. Compiling a CSP File is a multi-step process: first the CSP file is fed through
the CSP engine and converted into a Caché class (derived from the %CSP.Page class). Then this generated class is compiled
into one or more routines that contain executable code.
Sometimes it is easier to debug or understand a CSP file by looking at the code generated for it. You can use Studio to view
the class generated for a CSP file, as well as the routine(s) generated from this class by opening them with File > Open or
View > Other.

14.6 Viewing the Results of a CSP File

You can view the results of a CSP file in a browser by using View > Web Page. This launches your default browser with
the URL for the current CSP page. You can also use this command when editing a %CSP.Page class.
You can modify the server address portion of the URL used to display a CSP page in a specific project. To do this, select
Project > Settings and edit the value of the WEB Server field.

14.7 Viewing Syntax-Colored Source for Any URL

As an aid to debugging Web applications, Caché Studio lets you request a Web page from a URL and display its HTML
source in a syntax coloring window. This can help you spot errors in Web pages more easily than viewing the rendered
HTML in a browser.

Using Caché Studio                                                                                                                                                              73

Working with CSP Files

You can open a URL Viewer window using the File > Open URL and entering a URL in the resulting dialog.
To try this with a CSP sample page, do the following:
1. Select File > Open URL.
2. If you have a Web server on your local system, enter http://localhost/csp/samples/custom.csp
If you do not have a Web Server on your local system, use the test HTTP server on the 8972 port (or the port number
your system is configured for): http://localhost:8972/csp/samples/custom.csp

At this point, you sees the HTML returned by the custom.csp page displayed in a syntax-coloring window.

Note: You can use the URL viewer to view syntax-colored source for any Web page on the internet.

74                                                                                                                                                              Using Caché Studio

15
Working with Routines
A routine is the unit of execution in a Caché server; all application logic running on a Caché server is executed by invoking
routines and entry points in routines. Routines are executed in a virtual machine that is built into the Caché server environment.
Routines are portable to all platforms supported by Caché and automatically shareable across a Caché environment.

15.1 Routine Editor

Using the Routine Editor, you can directly create and edit the source for routines. When class definitions are compiled, the
class compiler generates a set of routines containing the implementation for the class. If you check to Keep Generated
Source Code (on the Tools > Options dialog, Compiler, General Flags tab), you can view and edit this generated source code
as well.
The Routine Editor uses syntax coloring and indicates syntax errors with a wavy red line.

15.2 Routine Source Formats

There are several kinds of routine source formats (files) in Caché. The Routine Editor provides syntax coloring and
checking for each of these formats. The formats include:
• BAS - Basic source files with a .bas extension
• MAC - Macro source files with a .mac extension, processed by the Caché macro preprocessor to resolve macros,
embedded SQL statements, and embedded HTML, which results in an .int file.
• INT - Intermediate source files, which are compiled directly into executable Caché object (OBJ) code.
• INC - Include files. Not routines per se, .inc files contain macro definitions that can be included by .mac routines.

By default, when you create a new Caché ObjectScript routine, it is saved as a .mac routine. Select File > Save As to save
this as a different type of routine (changing the extension from .mac to .inc for example).
Select View > View Other to display .int code corresponding to a given .mac file and vice versa.

Using Caché Studio                                                                                                                                                              75

Working with Routines

15.3 Creating a New Routine

To create a new routine, select File > New. A dialog displays the templates you can choose from. You can choose either a
Caché ObjectScript routine or a Caché Basic routine. This opens a new Routine Editor window with a default name, such
as Untitled. You can later save this with a different name with File > Save As.

15.4 Opening an Existing Routine

Open an existing routine with File > Open . In the drop-down list of Files of Type , select the file extension of interest (such
as .mac, .int, or All Files) and select a routine.
When you attempt to open a previously saved routine, the Open dialog uses wildcard matching (using the * (asterisk to
match any number of any character) and ? (question mark to match a single character) to display a list of available routines.
The routine type - BAS, MAC, INT, or INC - is used as a file extension for purposes of wildcard matching.

15.5 Routine Template File

When you create a new routine in Studio, it opens a new Routine Editor window and copies into it the contents of a Routine
template file. You can edit or replace this template file in order to customize how Studio creates new routines. This file is
a text file called Default.mac and is located in the same directory as the Studio executable file.

15.6 Saving, Compiling, and Deleting Routines

You can save routines to the database using the File > Save or File > Save As. By default, saving a routine also causes it to
be compiled. You can change this behavior with options available from Tools > Options dialog, Compiler, Behavior.
To compile a routine directly, use Build > Compile (which also causes it to be saved).
To delete a routine, in a Workspace window, highlight the routine and select Edit > Delete. The routine and any generated
files are deleted.

76                                                                                                                                                              Using Caché Studio

16
Using the Studio Debugger
The Caché Studio debugger lets you step through the execution of programs running on a Caché server. Programs that can
be debugged include INT files, BAS files, MAC files, methods within CLS files, CSP classes responding to HTTP requests,
server-side methods invoked from Java or ActiveX clients, or server-hosted applications. To step through, or set breakpoints
within classes or CSP pages, open the corresponding INT or BAS file and use the debugging commands in it. To view INT
source code files, go to the Tools > Options dialog, Compiler, General Flags tab and enable the Keep Generated Source
Code option.

You can connect the debugger to a target process in one of the following ways:
• Define a debug target (name of program, routine, or Zen or CSP page to debug) for the current project using Project
> Settings > Debugging > Debug Target (or Debug > Debug Target). Then select Debug > Go to start the target program
and connect to its server process.
• Select Debug > Attach and choose a running process on a Caché server.

Sometimes using command-line debugging with the zbreak command can give you better control. For more information
on zbreak, see the chapter “Command-Line Routine Debugging ” in Using Caché ObjectScript.

16.1 Sample Debugging Session: Debugging a Routine

The following example demonstrates how to debug a Caché routine.
1. Start Studio and select File > New Project to create a new project called Project1.
2. Create a new routine by clicking File > New > General tab > Caché ObjectScript Routine.
3. Enter code for this routine:
MyTest ; MyTest.MAC

Main() PUBLIC {
Set a = 10
For i = 1:1:10 {
Set b = i
Write b," "
}
}

4. Save and compile the new routine as MyTest.MAC using File > Save As.
5. Define a debug target for the project by selecting the Debug > Debug Target tab, selecting Class Method or Caché
Routine, and entering the name of the entry point in your new routine, Main^MyTest.

Using Caché Studio                                                                                                                                                              77

Using the Studio Debugger

6. Set a breakpoint in the routine: Position the cursor anywhere on the line Set a = 10 and press F9, the Toggle
Breakpoint key. A breakpoint indicator appears in the left margin, .
7. Select Debug > Go to begin debugging. When the debugger stops at your breakpoint, the next command to be executed
is outlined with a yellow box. The INT file opens in a new window (if you enabled the Keep Generated Source
Code option, on the Tools > Options dialog, Compiler, General Flags tab).

8. Enter b and a (as Watch points) into the Watch window (View > Watch) so that you can watch the values.
9. Step through execution of the program by repeatedly selecting Debug > Step Into (F11) and notice the b value change.

You can stop debugging by stepping to the end of the program or by selecting Debug > Stop.

16.2 Debugger Settings for the Current Project

Some debug settings are defined and stored in the current project. These include:
• Debug Target
• Breakpoints

16.2.1 Debug Target

A debug target tells Studio what process you want to debug.
To specify a debug target for a project, select Project > Settings > Debugging > Debug Target or select Debug > Debug Target.
Choose one of the following, which is started when you select Debug > Go. You can also set a debug target by placing the
cursor next to an item in a editor window, right-clicking, and selecting Set xxxx as debug target.

Class Method or Caché Routine

The routine (and tag), class, or method that you want to debug when Debug > Go is executed. For example, enter
Test^MyRoutine() to begin execution at the tag Test in the routine MyRoutine. Or enter the name of a class
method to execute, such as ##class(MyApp.Person).Test(1).

ZEN and CSP Page (URL, CSP or class)

The Zen or CSP page to be accessed when you invoke Debug > Go. The debugger connects to the Caché server
process that is servicing the CSP page's HTTP request. Use this option for debugging CSP applications, for
example, to step through the code for the Test.csp page, enter /csp/user/Test.csp as a debug target.

78                                                                                                                                                              Using Caché Studio

 Debug Menu

16.2.2 Breakpoints
A project maintains a list of breakpoints that you set with F9. When you start debugging a project's debug target (with
Debug > Go), the breakpoints defined by the project are set in the target process.

To view breakpoints, select Debug > Breakpoints > View Breakpoints. To add and remove breakpoints, place the cursor at
the breakpoint location and select Debug > Breakpoints > Toggle Breakpoint or F9. You can also add or remove breakpoints
using Project > Settings > Debugging > Breakpoints.

Note: 20 is the maximum number of breakpoints that can exist in a routine. If more than 20 breakpoints are set, the
Debugger displays <ROUTINELOAD>^%Debugger.System.1 and halts debugging.

16.3 Debug Menu

Debug menu options are described below:

Attach Displays a list of processes currently running on the Caché

server and lets you attach to one to debug.
If you select a process and click OK, Studio breaks into the
selected target process and allows you to start debugging it.
If you generated source for the current routine executing in
the target process, the source is displayed in an editor window.
If you later terminate debugging with Debug > Stop, the target
process resumes executing.

Go If you are not currently debugging, Go starts the target specified

by the Project's debug target.
(f you haven't set a target, you are asked for one. A debug
target is the name of routine or method to execute; you can
set this using theDebug Target dialog.
Once the target is started, it runs untilthe first breakpoint. If
you did not set any breakpoints in your application, it runs to
completion without stopping.

Restart Halts execution of the target process, restarts it, and resumes
debugging (as if the Go command was used).

Stop Stops debugging and either halts the target process or

detaches from it. If the target process was running and
attached to with Attach, then the target process continues
running. If the target process was started as a result of the Go
command, then it is terminated.

Break Pauses execution of the target process (that is, if the debugger
is attached to a target process that is currently running, not
stopped).

Interrupt Interrupts execution of the current command.

Using Caché Studio                                                                                                                                                              79

Using the Studio Debugger

Step Into Executes the current command in the target process and stops
on the next command, stepping into any function calls or
loop bodies.

Step Over Execute the current command in the target process and stops
on the next command. The debugger steps over any function
calls or code blocks (such as loops) it encounters; it stops on
the command following the function call or code block.

Step Out Advances the execution of the target process by leaving or

stepping out of the current code block or function and stops
on the next command at this outer level..

Run To Cursor Available only for documents containing INT routines.

Starts execution of the target process and stops when it
reaches the line on which the cursor is currently located. This
is equivalent to setting a breakpoint at the current line in the
editor window, executing the Go command, and clearing the
breakpoint when the program halts.

Watch Toggles Watch window Display.

Breakpoints Toggle Breakpoints Sets or clears a breakpoint on the current
line in the current document. View Breakpoints: Opens the
Breakpoints dialog with which you can list, add, and remove
breakpoints.
Debug Target Enter a debug target – a method, routine, Zen page, or CSP
page. See also “Debug Target”

16.4 Watch Window

The Watch Window displays a table in which you can watch the values of variables and simple expressions. All variables
and expressions listed in the Watch Window (called watch points) are evaluated after each debugger operation (such as
Step Over) and their resulting values are displayed in the second column of the Watch Window. If the value of a variable
or expression changes after a debugger operation, it is displayed in red. If a variable in the watch list is undefined when it
is evaluated then the value is displayed as: <UNDEFINED>. Similarly, any expression whose result is an error displays an
error message for its value.
To add a variable or expression to the Watch Window, double-click an empty cell in the first column and enter the variable
or expression. Alternatively you can use your mouse to highlight text in an editor window, drag it over an empty cell in
the Watch Window and drop it. You can edit the contents of the Watch Window by double-clicking on a variable or
expression and typing.
The following are examples of variables and expressions you could enter into the Watch Window:
• a
• a + 10
• a(10,10)
• $L(a)
• person.Name

80                                                                                                                                                              Using Caché Studio

 Watch Window

You can also change the value of a variable in the target process by entering a new value in the Value column of the Watch
Window.

Using Caché Studio                                                                                                                                                              81

17
Using Studio Templates
This chapter describes how to use Caché Studio Templates.
Templates are a repeatable way to insert functionality into Studio editor windows. There are three types of templates:
• Text Template—(what is meant by the word Template) A simple text template inserts generated text into a document.
An interactive text templateincludes user input. An example would be a Studio template inserts a block of standard
HTML into a CSP file. To access text templates, select Tools > Templates > Templates....
• New Document Template—Creates a new document window in Studio.
New Document Templates constitute the list of new document types displayed by the File > New menu. To create a
new document template, create either a simple or interactive text template with a Mode attribute of new.
• Add-in Template—Creates a new tool in Studio. An Add-in Template differs from a Text Template in that it does not
inject text into a document and does not require an open document.
Add-ins are available using Tools > Add-ins. For information on using the SOAP Web client wizard, see Using SOAP
and Web Services with Caché. For information on using the XML Schema Wizard, see the appendix “Using the XML
Schema Wizard” in Using XML with Caché.

Studio comes with a set of Caché-supplied standard Studio templates. In addition, you can create your own custom templates
using CSP.

Note: To ensure that Studio templates open quickly, disable the automatic detection of proxy settings in Internet Explorer.
1. Open Internet Explorer and click Tools > Internet Options and the Connections tab.
2. Click LAN Settings and uncheck any checked boxes. Make sure nothing on this page is checked and then
click OK twice to close the Internet Options dialog.

17.1 Using Studio Templates

You can open a template using Tools > Templates, as well as with the right-click menu in the editor window. You can open
a template by selecting it from the list of recently-used templates (showing on the right-walk menu under the word Tem-
plates...) or from the Studio Template list, accessed with (Tools > Templates > Templates), which lists available templates.
Each template is associated with one or more document types; only templates associated with the current window's document
type are shown in the Template list.
There are two styles of template; simple and interactive. A simple template inserts text at the cursor point with no further
user interaction. An interactive template displays one or more screens soliciting additional information, like a wizard.

Using Caché Studio                                                                                                                                                              83

Using Studio Templates

Any text that is highlighted when you open a template is replaced by the template. Many templates use the currently high-
lighted text as input to the template program.

17.2 Standard Studio Templates

Studio comes with a set of templates. You can see a list of all the system-supplied templates in Studio, in the $SYS
namespace, Workspace window, Namespace tab, under CSP files. To see templates usable in the current document, use
Tools > Templates > Templates. These templates are described below.

Note: By default, Studio templates use a session timeout of 90 seconds. If you are entering data into a Studio template,
the session ends after 90 seconds of no user input. For more information, see the section “Default Timeout ”
below.

17.2.1 Templates
This section contains three tables defining the templates available in Studio for use with CSP or Zen:
Table 17–1: CSP Templates

Template Description
HTML Color Select to insert an HTML color value string (such as #F0F0F0) at the cursor point.
HTML Input Select to insert an HTML input control at the cursor point.
HTML Script Select to insert a <SCRIPT> tag at the cursor point, with the specified language and
content.
HTML Table Select to insert an HTML table at the cursor point with the specified characteristics.
Select Preview to display a preview window.
HTML Tag Select to insert an HTML tag at the cursor point, selected from a list with specified
attributes. Or if you highlight an existing HTML tag and then invoke the template, you
can edit the displayed attribute values.

Figure 17–1: Example of an Interactive Template, the HTML Color Table

84                                                                                                                                                              Using Caché Studio

 Standard Studio Templates

17.2.2 Class Definition Templates

Many of the CSP templates are available for use in class definitions (they can be useful in &html<> blocks). In addition,
the following templates are available:
Table 17–2: Class Definition Templates

Template Description
SQL Statement Select to insert code for a specified SQL Statement at the cursor point. Select Preview
to see test results of the table (using data in the database) in a popup preview window.
You can specify whether the template returns only the SQL text, an embedded SQL
cursor based on the SQL text, or a %ResultSet object based on the SQL text.
Web Form Wizard Select to open a Wizard with which you can create a CSP form, specifying class
members and a table style for the form to use. (See Building a Simple Application
with Studio for an example.

17.2.3 Zen Templates

You can use the following wizards (also called templates) in Zen classes. For detailed information on using these wizards,
see Zen Wizards in Using Zen and the chapters referenced in the table below for select templates.
Table 17–3: Zen Templates

Template Description
Zen Chart Template Select to insert a Zen chart definition within an Xdata block of a Zen page class,
selecting type, style, and attributes. For more information see the chapter “Zen
Charts” of Using Zen Components.
Zen Element Select to insert a Zen element within an Xdata block of a Zen page class. You can
Template insert and edit built-in, custom, or composite Zen components or create a new Zen
component. For more information, see the chapter “Zen Layout ” in Using Zen.
Zen Method Select to insert a method. The wizard lets you select a scope, either instance or class,
Template a location where the method will execute, a name, and whether to add a try/catch
error processing template. You can further edit it in the Studio editor.
Zen Style Template Select to insert a CSS style declaration within an Xdata Style block of a Zen class.
A table displays the CSS style declarations defined by Zen components. You can
select one and override it within your page by editing details. For more information,
see the chapter “Zen Style” in Using Zen.
Zen TablePane Select to insert a new Zen tablePane definition within an Xdata block of a Zen page
Template class. Select the source of the query or table for this tablePane and then adjust
properties as desired. For more information, see the chapter “Zen Style” in Using
Zen.

17.2.4 Add-In Templates

The Tools > Add-Ins menu contains a list of wizards with which you can add items to your project. The menu contains the
following add-ins.

Using Caché Studio                                                                                                                                                              85

Using Studio Templates

Table 17–4: Add-Ins

Add-In Function For More Information

.Net Gateway Wizard Imports a DLL assembly file from .NET and Using the Object Gateway for
create a set of corresponding classes. .NET
Activate Wizard Creates Caché classes which provide you with The Caché Activate Wizard in
access to COM objects from within Caché. Using the Caché ActiveX Gateway
Java Gateway Imports a class file or a jar file from Java and Using the Java Gateway in the
Wizard creates a set of corresponding classes. Ensemble documentation set
SOAP Client Wizard Reads a WSDL (Web Services Description Using SOAP and Web Services
Language) document and creates one or more with Caché
SOAP client classes.
XML Schema wizard Reads an XML schema and creates a set of “Using the XML Schema Wizard ”
corresponding classes. in Using Caché with XML.
XSL Translate Transforms an XML file using a specified XSL “Performing XSLT
Wizard stylesheet. Transformations” in Using Caché
with XML

17.3 Making Your Own Studio Templates

You can create any of the following types of templates:
• Simple Text Templates insert text at the current cursor location.
• Interactive Text Templates provide an interactive dialog that request information and then insert text at the current
cursor location.
• Add-in Templates provide tools for general use in Studio.
• New Document Templates appear in the Studio New Document dialog and create new documents.

Note: You should have some familiarity with CSP development before attempting to create Studio templates.

17.3.1 Template Architecture

Studio Templates are created and implemented using Caché Server Pages (CSP); each template is one or more server pages
that run on a Caché server. When you invoke a template, Studio creates a window containing a browser and makes an
HTTP request (via the built-in Caché simple HTTP server) to the CSP page associated with the template. The CSP page
can either:
1. Return HTML containing an interactive form that solicits additional input from the user, or
2. Return XML containing the text to be inserted at the cursor point in Studio. (All Text and New Document Templates
do this as their final step; Simple Templates, with no user interface, implement only this step; Add-in Templates do
not insert text into a document.)

To make it easier to develop templates, Caché includes a set of custom CSP tags that perform all the basic operations of
templates. These tags are described in the following sections.

86                                                                                                                                                              Using Caché Studio

 Making Your Own Studio Templates

The power of templates comes from the fact that they are running on a Caché server and have the entire power of Caché
at their disposal. Therefore, for example, templates can perform sophisticated database operations.
When invoking a template, Studio passes parameters to the server, where they are accessible, in the %request object. These
parameters (which are case-sensitive) include:
• Project Name—the name of the current Studio project.
• Namespace—the name of the namespace Studio is connected to.
• User Name—the name of the current Studio user.
• Document Name—the name of the current Studio document, if any.
• SelectedText—the current selected text in the current document, if any.

Give each template a unique name (unless you are replacing an existing template with a new one).

17.3.2 Default Template Timeout

A session timeout is the amount of time in which a session stays open without any input from a user. At the end of this
time of no user input, CSP closes the session.
Templates created in Studio are stored in either of the CSP applications, /isc/studio/usertemplates (which appear on the
Tools > Templates menu) or /isc/studio/templates (which appear on the Tools > Templates > Templates menu). By default,
both of these applications have default session timeouts of 90 seconds. In the System Management Portal, on the CSP
Application options page for each of these applications, you can enter a number in the Default Timeout setting, but the
number has no effect on the hard-coded session timeout of 90 seconds. This is intentional to prevent inactive Studio templates
from retaining system licenses.

17.3.3 Simple Text Templates

A simple template is a single CSP page that returns a block of text that is inserted into the current document at the cursor
point. The CSP page contains the special Studio CSP tag: <csp:StudioSimpleTemplate>.

17.3.3.1 Creating a Simple Studio Template

To create a simple Studio template, start Studio and do the following:
1. Create a new CSP page with File > New > Caché Server Page.
2. Replace the contents of the document with the following. (The name of the new template is MyTemplate.)
<csp:StudioSimpleTemplate name="MyTemplate" type="CSP">
SOME TEXT!

3. Save and compile this CSP document with Build > Compile. It does not matter what file name you use for the CSP
document or which namespace or CSP application you store it in.
To make a Studio template accessible to all namespaces, save it in the %SYS namespace in /isc/studio/usertemplates.

You have now defined a template called MyTemplate (its name is specified by the name attribute of the <csp:StudioSim-
pleTemplate> tag). When you are in an open CSP page in the Studio Editor, select Tools > Templates > MyTemplate, and
the text SOME TEXT! is inserted into the page.
The Template dialog lists templates whose type matches the document type from which you invoked the Template dialog.
In our example, the MyTemplate template has a type of CSP. When you are in a CSP page in the Studio Editor, it appears
on the Tools > Templates list.

Using Caché Studio                                                                                                                                                              87

Using Studio Templates

You can also edit the type attribute, a comma-separated list of document types, to specify the document types the template
can be called from. The list of types includes:
Table 17–5: Studio Template Types

Template Type Template is available when your current document is a

CSP CSP document
CSR CSR document
MAC MAC routine
INT INT routine
INC INC file
BAS BASIC script
CLS Class Definition document

17.3.3.2 Testing a Simple Studio Template

To test a simple text template:
1. Open an existing (or create a new) CSP page in Studio (you can use any CSP application directory). While you can
continue to use the namespace in which you created the template, you probably want to connect to the namespace
where you normally work.
2. Position the cursor in the CSP document editor window and select Tools > Template > Templates.
3. You see your new template in the list. Select it and click OK.

The body of the simple template is inserted at the cursor location. For example:
<html>
<body>
SOME TEXT!
</body>
</html>

17.3.3.3 Adding Logic to a Simple Studio Template

• Embedded expressions using #( )# syntax.
• Line of code contained in a <script runat=”server”> tag.

For example, we could create a simple template that returns the current date and time (using the $ZDT function) in an
HTML <B> (boldface) tag:
<csp:StudioSimpleTemplate name="Now" type="CSP">
<B>#($ZDT($H,3))#</B>

17.3.3.4 Troubleshooting a Simple Studio Template

If you have problems developing a custom template, one way to debug it is to view your template CSP page in a browser
with View > Web Page while editing your CSP. Use a browser capable of displaying XML text; the value returned by a
template is wrapped in XML.
For example, you can display the output of the template defined earlier in this section by entering a URL in a browser (or
using File > Open URL), such as:
http://localhost:8972/csp/user/MyTemplate.csp

88                                                                                                                                                              Using Caché Studio

 Making Your Own Studio Templates

This results in the following XML response:

<?xml version="1.0"?>
<template>
<![CDATA[BODY##www.intersystems.com:template_delimiter##
SOME TEXT!##www.intersystems.com:template_delimiter##]]>
</template>

The response is contained in a <template> element. The body of the response is delimited using the
##www.intersystems.com:template_delimiter## delimiter.

17.3.4 Interactive Studio Templates

An interactive template is a set of one or more CSP files that display a dialog window (using HTML) requesting user input.
The interactive template's final page inserts a block of text into the current document at the cursor point, as a simple template
does.
When you select an interactive template, Studio displays a dialog window containing a Web browser. The first page (or
pages) of an interactive template returns an HTML form that solicits user input.
The first page of an interactive template starts with the <csp:StudioInteractiveTemplate> tag. The attributes of this tag are
identical to those of the simple template tag. The final page (the one returning output to Studio) starts with the <csp:Studio-
GenerateTemplate> tag. Any intermediate pages (perhaps you are creating a multiple page wizard) do not need any special
tags. The penultimate page contains a SUBMIT button that invokes the final page.
For example, suppose you want to create an interactive template, MyScript, that solicits script content and script type
from a user and inserts a <script> tag into a CSP document. The first page, MyScript.csp, contains a simple HTML form:
<csp:StudioInteractiveTemplate name="MyScript" type="CSP">
<HTML>
<BODY>
<FORM NAME="form" ACTION="MyScript2.csp">
Language:
<SELECT NAME="language">
<OPTION VALUE="CACHE" SELECTED>CACHE
<OPTION VALUE="JavaScript">JavaScript
</SELECT>
<BR>
Script: <TEXTAREA NAME="script" ROWS="10" COLS="40"></TEXTAREA>
<BR>
<INPUT TYPE="submit" VALUE="OK" NAME="submit">
</FORM>
</BODY>
</HTML>

1. A <csp:StudioInteractiveTemplate> tag specifying that this is an interactive template as well as the template's name
and type.
2. An HTML form whose ACTION attribute links it to the final page of the template, MyScript2.csp (see below).
3. A SELECT control for specifying a script language.
4. A TEXTAREA control for entering the contents of the script.
5. A SUBMIT button that submits the contents of the form to the MyScript2.csp page.

The final template page, MyScript2.csp, uses the values submitted from the form to create a response that is sent back to
Studio:

Using Caché Studio                                                                                                                                                              89

Using Studio Templates

<csp:StudioGenerateTemplate>
<SCRIPT LANGUAGE="CACHE" RUNAT="SERVER">
Write "<SCRIPT"
Write " LANGUAGE=""",$G(%request.Data("language",1)),""""
If ($G(%request.Data("language",1))="CACHE") {
Write " RUNAT=""SERVER"""
}
Write ">",!
Write $G(%request.Data("script",1)),!
Write "<","/SCRIPT>",!
</SCRIPT>

This page starts with a <csp:StudioGenerateTemplate> tag and then includes Caché ObjectScript code that sends back a
SCRIPT tag (with appropriate attributes) to Studio. To test this, create a new CSP page and select Tools > Templates >
MyScript. Enter some Caché ObjectScript in the script box and click Ok. Script tags with your script are entered automatically
into your new CSP page.

17.3.5 New Document Studio Templates

You can create a new document template by adding a mode attribute, with value of new, to either the <csp:StudioSim-
pleTemplate> or <csp:StudioInteractiveTemplate> tags.
Any template whose mode is new, appears, by name, in the New Document dialog (invoked by File > New). The results
of the template are written into a newly created document.
For example, to create a new document template that creates new CSP pages, make a CSP file similar to this:
<csp:StudioSimpleTemplate name="MyCSPPage" type="CSP" mode="new">
<HTML>
<HEAD>
</HEAD>
<BODY BGCOLOR="FFDDFF">
<H1>New CSP Page</H1>
</BODY>
</HTML>

After saving this CSP file (you can save it under any CSP application) and compiling it, it appears in the Studio New dialog
as MyCSPPage When selected, a new, untitled CSP document is created with the following contents:
<HTML>
<HEAD>
</HEAD>
<BODY BGCOLOR="FFDDFF">
<H1>New CSP Page</H1>
</BODY>
</HTML>

You can create more sophisticated New Document Templates by adding logic or by using an interactive template, as
described above for Text Templates.

17.3.5.1 New Class Definition Templates

If you are creating a New Document Template that creates a new class definition, you must perform an extra step in your
template code: you tell Studio of the name of the new class so that it can create the correct internal data structures for the
new class definition. This information is returned from the Template to Studio via data in the %session object's Data
property stored under the subscripts Template and CLASS. At some point, your template should contain code similar to
this:
<SCRIPT LANGUAGE="CACHE" RUNAT="SERVER">
Set %session.Data("Template","CLASS") = classname
</SCRIPT>

90                                                                                                                                                              Using Caché Studio

 Making Your Own Studio Templates

17.3.6 Add-in Studio Templates

You can create an add-in template by adding a mode attribute, with value of addin, to either the <csp:StudioSimpleTem-
plate> or <csp:StudioInteractiveTemplate> tags.
Any template whose mode is addin, appears, by name, in the Add-in dialog (invoked by the Tools > Add-in).
You can create Add-in Templates in the same manner as described above for Text Templates.
When invoking an add-in, Studio passes parameters to the server, where they are accessible, in the %request object. These
parameters (which are case-sensitive) include the following:
• Project Name—the name of the current Studio project.
• Namespace—the name of the namespace Studio is connected to.
• User Name—the name of the current Studio user.
• Document Name—the name of the current Studio document, if any.
• SelectedText—the current selected text in the current document, if any.
• Language —COS language mode.
• Document Namespace—the namespace that the document belongs to (which might be different from the current
namespace.

17.3.6.1 Adding Items to a Project

From an Add-in Template, you can instruct Studio to add one or more items to the current project by using the inherited
method, AddToProject, on the final page of the Add-in Template.
For example, the following adds a class, MyApp.MyClass, to the current project:
<SCRIPT LANGUAGE="CACHE" RUNAT="SERVER">
Do ..AddToProject("MyApp.MyClass.CLS") // note .CLS extension
</SCRIPT>

Note that when adding an item to a project in this way, you must append the type of item (.CLS, .CSP, .MAC, and so on)
to the item name. Also note that the item must exist before you add it to a project; adding a class to a project does not
automatically create such a class (but, perhaps, your Add-in Template does this using the %Dictionary class provided in
the class library).

Using Caché Studio                                                                                                                                                              91

18
Studio Menu Reference
This chapter describes menu and keyboard options available from the Caché Studio menus. The menus are:
• File
• Edit
• View
• Project
• Class
• Build
• Debug
• Tools
• Utilities
• Window
• Help
• Context Menus
• Studio Editor Keyboard Accelerators

18.1 File Menu

The File menu contains options for opening and saving documents and projects. See also the section “Keyboard Accelerators.”

New Studio Use to connect to a different Caché server.

Change Namespace Use to change to a different namespace.

Using Caché Studio                                                                                                                                                              93

Studio Menu Reference

New Use to create a new document (such as class definition, routine,

or CSP file) in an editor window. Document types are grouped
under three tabs:
• General- for creating a new Caché ObjectScript routine,
Caché Basic routine, Caché class definition (with the New
Class wizard), or a Caché MultiValue routine.
• - for creating a new Caché Server Page, XML file,
CSP File
JavaScript file, or cascading style sheet (CSS) file
• Zen— for creating a new Zen application, component, page,
or report. (For details, see Zen Wizards in Using Zen.
• Custom- for creating a Web service class. For details on
Web services, see Web service

Open Opens an existing item from the current Caché namespace

and server.
If the item is in use by another user, you can open it for Read
Only access.
Studio allows you to edit class definitions, routines, and CSP
files only from the current server and namespace. To open an
item from a different server or namespace, useFile > Change
Namespace to change to a different namespace or switch to a
different server. Use File > New Studio to open a second Studio
window.
If you select an item and right-click Delete, the item and all
subitems are deleted. Examples: if you select an .INT file, both
.INT and .OBJ files are deleted. If you select a .cls file, all
associated .INT and .OBJ files are deleted also.

Open URL Displays HTML source in an editor. This is useful when you
are developing a Web-based application to view progress.
Close Closes the current editor.

Save Saves the contents of the current editor.

Save As Saves the contents of the current editor with a name that you
specify.

Save All Saves the contents of all open windows.

New Project Creates a new project in the current Caché server and
namespace.
Open Project Opens an existing project in the current Caché server and
namespace.
To open a project from a different server or namespace, use
File > Change Namespace to change to a different namespace or
switch to a different server. Use File > New Studio to open a
project in a second Studio window.

94                                                                                                                                                              Using Caché Studio

 Edit Menu

Save Project Saves setting for the current project. It does not save any
modified documents belonging to the project.
Save Project As Saves the current project with a name you specify.
Close Project Closes the current project.
Clone Ensemble only. Creates a clone of the current BPL or DTL
document and requests a document name.

Print Prints the current document.

Print Preview Displays the document as it will look when printed.

Print Setup Opens the Print Setup dialog with which you can set how
documents are printed.
Recent Files Lists recently used files.
Recent Projects Lists recently used projects.
Exit Ends the current Studio session.

18.2 Edit Menu

The Edit menu contains editing and navigation options. Most of the options have keyboard shortcuts; see the section
“Keyboard Accelerators.”.

18.2.1 Basic Editing

Undo Reverses the last action.

Note that changes made to classes with the Class Inspector cannot be
reversed using Undo.

Redo Reverses the most recent Undo.

Cut Deletes the current text selection and copies it to the clipboard.

Copy Copies the current text selection to the clipboard.

Paste Inserts the contents of the clipboard at the current cursor location.

Delete Deletes the current text selection without copying it to the clipboard. If
you highlight an item in the Workspace window, the item and any of its
generated files are deleted.
Select All Selects all the contents of the current document.

Using Caché Studio                                                                                                                                                              95

Studio Menu Reference

18.2.2 Find and Replace

96                                                                                                                                                              Using Caché Studio

 Edit Menu

Find Searches for text in the current document.You can use wildcard matching
with the * (asterisk to match any number of any character) and ?
(question mark to match a single character).
Find In Files Searches for text in multiple files on the Caché server. Enter a string to
search for, select the type of file to search (such as .cls for class defini-
tions), and click Find.
Studio searches the selected files in the current Caché namespace and
returns a list of all (up to the first 500) files that contain the search string.
Double-click an item in the search results to open the file and display
the item, marked by the cursor.
Note that Find in Files searches stored data; it does not search modified
open documents. If you search only in the current project and the current
project is either a new project or a modified project, you are prompted
to save the project. If you refuse, Find in Files is canceled.
The Filter field can contain the elements in the list below. You can use
SQL AND and OR logical operators to enter more than one filter. For
example, Type=5 AND Modified>01/01/08. The contents of the Filter
field forms part of an SQL WHERE clause. The fields come from the
%Studio.OpenDialogItems class.

• IsTrue=1 or 0 - True (1) is this is a document, false (0) if it is a

directory.
• Name=file name - Enter a file name to search within selected files.
• Characters=number of characters - Filters for documents of a
certain size. Can include SQL relational operators.
• Type=# - Type is followed by an integer which filters according
to file type list, shown in %Studio.OpenDialogItems.Type. This can filter
to a finer degree than the file type field. To search for only .mac files,
for example, enter Type=5.
• Modified=last modified timestamp - Can include SQL relational
operators.
• Generated=1 or 0 - True (1) is this is a generated document, false
(0) if it is a user-created document.
• Description=description - Enter a description to search for within
files.

Cancel Cancels a running Find in Files search or a class compilation.

Replace Replaces one text string with another in the current document.

Go To Moves the cursor to a location in the current document, specified as

either a line number or (for routines and class definitions) a tag or class
member.
Bookmarks See “Bookmarks” below.
Next Error Moves the cursor to the next error in a CSP file.
Previous Error Moves the cursor to the previous error in a CSP file.

Using Caché Studio                                                                                                                                                              97

Studio Menu Reference

Next Warning Moves the cursor to the next warning in a file.

Previous Moves the cursor to the previous warning in a file.

18.2.3 Bookmarks
You can use bookmarks to keep track of locations in your application source. Bookmarks are stored on the local machine
in which Studio is running; they are not shared among multiple users. The bookmark options are:

Toggle Bookmark Adds or removes a bookmark at the current line in the current
document.

Clear Bookmarks Removes all bookmarks defined for the current document.

Next Bookmark Moves the cursor to the next bookmark in the current document.

Previous Bookmark Moves the cursor to the previous bookmark in the current document.

18.2.4 Advanced Editing

The Advanced Editing option displays when you are in an ObjectScript routine.

Expand Commands Replaces all abbreviated Caché ObjectScript commands contained in the currently
selected text with their full names. For example, the following code:
S x = 10

Is replaced with:
Set x = 10

Compress Replaces all Caché ObjectScript commands contained in the currently selected text
Commands with their abbreviated versions. For example:
Set x = 10

Would be replaced with:

S x = 10

18.3 View Menu

The View menu contains options that control what is displayed. Which options are shown on this menu depends on where
your cursor is. See also the section “Keyboard Accelerators.”

98                                                                                                                                                              Using Caché Studio

 View Menu

Workspace Shows or hides the Workspace window. The Workspace window

has three tabs:
• Project - Displays the contents of the current project.
• Windows - Displays a list of all current windows.
• Namespace - Displays the contents of the current namespace.

Inspector Shows or hides the Inspector. The Inspector displays class

definitions in an editable table. Some aspects of class definitions
can be changed in a file only; some can be changed in a file or in
the Inspector; and some can be edited only in the Inspector.

Output Shows or hides the Output window. The Output window displays
output from the server (such as error messages resulting from
compilation). You can enter COS commands into this window; they
are executed on the server.

Watch Shows or hides the Watch window. The Watch window displays
watch points when debugging.
Toolbars Lets you select Studio toolbars to show or hide.

Full Screen Expands Studio to occupy the full screen.

Text Size Lets you Increase, return to Normal, or Decrease text size of text
in Studio.
Toggle Special Characters Toggles the display of spaces, tabs, and end-of-line characters in
the Studio Editor window.

Reload If a document is active, reloads the saved version of current

document. If the Workspace window is active, reloads the window
or project. If the Workspace window, Namespace tab is active
reloads the subtree parent of the selected item; highlight topmost
level to reload the entire tree.

View Other Code Displays any source code generated by the compiler, such as .INT
and .MAC files, related to the position of the cursor. This option
works only if the current window has one or more source files
currently generated for it.
View Other Documents Displays other documents related to the current document. In some
situations,View Other Code results in the same behavior as View Other
Documents.

View Storage Available only for persistent and serial class definitions.
Toggles the display of a persistent (or serial) class storage definition
in the current editor window. A class storage definition is displayed
as an XML island in the body of the class definition and can be
edited in the same way as any other text.

Using Caché Studio                                                                                                                                                              99

Studio Menu Reference

Web Page Available only when in a CSP file.

Opens your default Web browser and displays the current CSP file,
so that you can see how your CSP pages will look as you develop
Web applications.
You can change the network address portion of the URL used with
Project > Settings. The default value is http://localhost:8972.

Expand Code Available only in some files. Displays complete code in text editor
window.
Contract Code Available only in some files. Contracts some code sections in text
editor window. Click the plus icon to expand a section.
Show Class Documentation Available only in class definition files or when a class is selected.
Displays online documentation for the current class derived from
the (saved) descriptions of class members.
Language Mode Available only when you are in a source code file, such as .INT or
.MAC.
Select from a list of Caché language versions as appropriate for
your site.

18.3.1 Toolbars
The Toolbars menu lets you toggle the display of toolbars and lets you customize toolbars.

Standard Toggles display of the Standard toolbar.

Debug Toggles display of the Debug toolbar.
Members Toggles display of the class Members toolbar.
Status Bar Toggles display of the status bar at the bottom of the Studio window. From left to
right, this bar shows a status message and the location of the cursor by line and
column. The four buttons on the right, if highlighted, show that the Caps Lock key
is on, that the Num Lock key is on, that the Insert key is on (Overwrite), and that the
current file is a read-only file.
Bookmark Toggles of the Bookmark toolbar.
Customize Opens the Customize dialog.

Toolbars, displaying text labels are shown below. To display text labels in Studio, choose View > Toolbars > Customize,
the Toolbars tab. Select a toolbar and select Show text tabels. (If a toolbar is already selected, uncheck the toolbar, recheck
the toolbar, and check Show text labels.)
Figure 18–1: Standard Toolbar

100                                                                                                                                                            Using Caché Studio

 Project Menu

Figure 18–2: Debug Toolbar

Figure 18–3: Class Members Toolbar

The BPL toolbar is only applicable in Ensemble.

Figure 18–4: BPL Toolbar

Figure 18–5: Bookmarks Toolbar

18.3.2 Customize Toolbars

The Customize menu consists of four tabs for customizing parts of the Studio interface, Commands, Toolbars, Tools, and
Options.

Commands Lists menus and all commands on Studio menus. Drag a command and drop it
into an open toolbar. To remove a command from a toolbar, drag it off the toolbar.
Toolbars Select check boxes to display toolbars. Toolbars can include text labels if you
select Show text labels. The Menu Bar cannot be unchecked. Click New to create a
new toolbar.
Tools Adds menu items to the Studio Tools menu. Specify an item name, it's command,
any arguments, and it's initial directory.
Options Select check boxes to turn on the display of screen tips, screen tips including
shortcut keys, and large icons.

18.4 Project Menu

The Project menu contains options for working with projects.

Using Caché Studio                                                                                                                                                            101

Studio Menu Reference

Add Item Adds the item in the current editor window to the current project.
Remove Item Removes the item in the current editor window from the current project.
Settings Select to edit settings for the current project:
• General: HTTP Address used by Studio to set Web pages for this project: Set URL
location for Web pages for this project. Defines: Define a macro that is applied when
you compile the project. You can define a debug macro which can be tested by other
macros and turns on additional checking in the code. For example, debug=1 defines
the macro $$$debug to be 1.
• Debugging: Set Debug target and Breakpoints. See the chapter “ Using the Studio
Debugger” for details.

18.4.1 Common Project Tasks

To delete a project, click File > Open Project and right-click the project that you want to delete.
To import a project, click Tools > Import Local and select the xml file that contains the project.
To export a project, open the project, click Tools > Export, select Export Current Project, browse to the output directory,
and enter a file name.

18.5 Class Menu

The Class menu contains options for editing class definitions and is available only when you are in a class definition file.
The class options are arranged in an Add submenu and an Override dialog. The options include:

Add Select one of: New Property, New Method, New Class Parameter, New Query, New Index, New
SQL Trigger, New Foreign Key, New Storage, New Projection, or New XData Opens a wizard for
the item and inserts an item definition into the current class definition. See separate
chapters in this book for details on options for each of these class members.
Override Opens a window that lists items that the current class inherits, from which you select.
Then it inserts an override definition into the current class definition. Items listed include
Properties, Methods, Parameters, Queries, SQL Triggers, and XData routines.

Superclasses Lists superclasses of the current class alphabetically. You can pick from these to Add to
Project, Show Documentation, or Open.

Derived Classes Lists classes derived from the current class (subclasses). You can pick from these to Add
to Project, Show Documentation, or Open.

Create Subclass Displays the New Class Wizard. A class created using this option becomes a derived
class of the class in the current window and inherits its members, including properties,
methods, class parameters, applicable class keywords, and the parameters and keywords
of the inherited properties and inherited methods.

A projection automatically creates related files for other languages when you compile a class. For example, adding a Pro-
jection of type %Projection.Java generates a new Java class when it compiles so that you can use your class from a Java
application.

102                                                                                                                                                            Using Caché Studio

 Build Menu

18.6 Build Menu

The Build menu contains options for compiling and building applications. The behavior of the Build options is controlled
by the Compile settings in the Studio Options dialog.
The build options include:

Compile Compiles the contents of the current window. Uses settings of the
Compiler tab from Tools > Options. Any messages from the compiler
are displayed in the Output Window.
If Skip Related Up-to-date Classes is enabled then:
• The current class definition is only compiled if it has been modi-
fied.
• If possible, Studio performs an incremental compile; if the only
change to a class definition is in the implementation of one or
more methods then only these methods are compiled.

Compile with Options Use to select options for this session only or to change the default
compile options. Default options can also be set with the Tools >
Options, Compiler tab

Forced Compile Unconditionally compiles a complete (non-incremental) compile

regardless of whether or not the current class definition has been
modified. This option is only relevant for class definitions; if the
current window does not contain a class definition then this option
has the same effect as Compile.

Rebuild All Compiles all the components in the current project whether or not
they have been modified from the last compile.

18.7 Debug Menu

The Debug menu contains debugging options. To see the Debug Menu options, see the section “Debug Menu ” in the
chapter “Using the Studio Debugging .” See also the section “Keyboard Accelerators.”

18.8 Tools Menu

The Tools menu contains miscellaneous options.
The tools options include:

Class Browser Opens the Studio Class Browser. The Class Browser displays a list of all classes
in the current namespace as well as their members (defined and inherited).

Using Caché Studio                                                                                                                                                            103

Studio Menu Reference

Show Plan for SQL Opens dialog for an SQL statement. An SQL statement selected in the active
Statement document is displayed and editable in the dialog. Clicking Show Plan displays the
query execution plan in a web page.
Source Control Lets you choose from a list of available Source Control classes. A source control
class defines a set of server-side methods that are called by Studio when it per-
forms certain actions, such as loading and saving documents to the database.
For more information see the section on “Source Control Hooks”.

Templates Displays a list of Studio Templates. A template injects a stream of text at the current
cursor location. Studio provides templates. In addition, you can create your own.
For more information see the chapter on “ Studio Templates” .

Add-Ins Contains a list of wizards that help you add items to an open Studio file or connect
to existing files using standard formats. The wizards are the .NET Gateway Wizard,
the Activate Wizard, the Java Gateway Wizard, the SOAP Client Wizard, the XML
Schema Wizard, and the XSL Transform Wizard. For more on these wizards, see
the section “Add-In Templates”.
Export Exports one or more items (class definitions, projects, routines) to either a local
file or a file on the server system.
Export Special Export RO, the format created with the %RO utility.
Import Remote Lets you import an item from a remote file (that is; a file that is on the same machine
as the server that Studio is connected to). All imported items are placed into new
document windows.
You can use this option to import a project, class definition, or routines from either
XML, or .RTN (%RO Routine format files).
The Import Remote option displays a dialog that lists all the items contained in the
file from which you can select. You can also specify whether the imported items
should be added to the current project and if they should be compiled.

Import Local Lets you import an item from a local file (that is a file on the same machine as
Studio). All imported items are placed into new document windows.
You can use this option to import a project, class definition, or routines from either
XML, or .RTN (%RO Routine format files).
The Import Local option displays a dialog that lists all the items contained in the
file. You can select which items you want to import. You can also specify whether
the imported items should be added to the current project and if they should be
compiled.

Compare Compares an open file to one that you select with Browse.You must have specified
an external compare tool with the Compare setting in Options > Environment > General.
Copy Class Creates a copy of an existing class with a new name.
Generate C++ Projection Creates C++-related files when this class is compiled so you can use this class
from a C++ application. For more information, see the chapter Using the C++
Binding in the book Using C++ with Caché.
Options Lets you set Studio options. For details on options see the chapter “Studio
Options.”

104                                                                                                                                                            Using Caché Studio

 Utilities Menu

18.9 Utilities Menu

The Utilities menu contains links to resources outside of Studio, such as:
• System Management Portal
• Telnet
• Ensemble Management (available only if Ensemble is installed)

18.10 Window Menu

The Window menu contains standard window options for manipulating the windows in Studio.

18.11 Help Menu

The Help menu contains options for accessing online Help.
The help options include:

Studio Documentation Displays the table of contents for Studio documentation.

Studio Commands Displays the list of Studio options and short descriptions.
Online Documentation Displays the home page of the Caché Online Documentation.
ObjectScript Reference Displays the Caché ObjectScript online reference.
SQL Reference Displays the Caché SQL online reference.
Class Definition Syntax Displays the online reference for class definition syntax.
InterSystems on the Web Provides links to useful pages on the InterSystems Web Site.
About Studio Displays version information about Studio.

18.12 Context Menus

Right-clicking areas in Studio displays different context menu. These include those described in the following sections.

18.12.1 Editor Context Menu

Right-clicking in the Studio Editor window displays a context menu. Within this context menu are many items available
from the main menu, such as Copy, Paste, Add, Toggle Breakpoint. There are also additional options that are not available
from the main menu. These include:

Using Caché Studio                                                                                                                                                            105

Studio Menu Reference

Help The Help option displays context-sensitive help for selected syntactical elements. To
use, right-click text and select Help.
For example, if you right-click the word Do in Caché ObjectScript code and select Help
, the reference page for the Do command is displayed in your browser.

Set Syntax Color Displays a dialog in which you can choose the color used to display a specific syntactical
element.
To use, right-click text and select Set Syntax Color.

Goto <TAG> Available when editing an ObjectScript routine. Lets you jump to the code that defines
the ObjectScript tag.
To use, in an ObjectScript routine, right-click a tag and select Goto <TAG> . If the right-
clicked tag is defined in another routine, Studio automatically opens this routine.

Set current item as Sets the current item as the debug target.
debug target

18.12.2 Workspace Context Menu

Right-clicking the Workspace window displays a context menu. Which menu is displayed depends on the cursor location.
Different context menus are displayed if the cursor is on a package, a class, a CSP file, and so on. This table below shows
items on the Workspace Package context menu not available on the menu bar.

Add Adds a class selected from the displayed list to the

current package.
Remove Package “name” Removes the current package from this project.
Compile Package “name” Compiles the current package.
Delete Package “name” Deletes the current package.
Export Exports the current package to an xml file. (To import
a package, select Tools > Import and select an xml
file.)

18.12.3 Inspector Context Menu

Right-clicking the Inspector window displays a context menu with the following items (if they are applicable to the current
document in the editor window):

106                                                                                                                                                            Using Caché Studio

 Keyboard Accelerators

Add Adds a member selected from the displayed list to

the current class definition.
Override Opens a window that lists items inherited by the
current class, from which you select. An override
definition is inserted into the current class definition
window.
Reset to Default Resets selected item to default.
Delete Deletes the displayed item.
Locate Available when a class member is displayed. Displays
the member is the editor window.
Show Inherited Members Toggles the inclusion of inherited members in the
window display.
Show Headers Toggles the display of the column headers, Name
and Value, in the Inspector window.

18.12.4 Tab Context Menu

Right-clicking the tabs header displays a context menu with these items:

Close Closes the current tab.

Close All But This Closes all tabs except the current tab.
Close All Closes all tabs.

18.12.5 Window Display Context Menu

Right-clicking a window where no other context menus apply shows the generic window context menu:

Floating Disconnects the selected window from a fixed

location; that is, it can be dragged freely to a desired
locaiton.
Docking Glues the selected window to a default location.
Hide Conceals the selected window.

18.13 Keyboard Accelerators

This section lists Studio's keyboard accelerators—combinations of keys that, when pressed, perform a Studio function.
These are listed in the following table.

block of text
In the following table a block of text means a number of whole lines. To select a block of text, put the caret at the
start of the first line, press Shift, and click the down arrow till all of the relevant lines are highlighted. The caret
will be at the start of the line beneath the last whole line.

Using Caché Studio                                                                                                                                                            107

Studio Menu Reference

Accelerator Action
General
F1 Context Help
F4 Change Namespace or Connection
F8 Toggles Full Screen Display of Studio
Ctrl+N New Document
Ctrl+O Open Document
Ctrl+Shift+O Open Project
Ctrl+P Print
Opens the Print dialog. If text is selected, Selection is checked.

Ctrl+S Save
Ctrl+Shift+I Export
Ctrl+I Import Local
Display
Ctrl++ Expand All
Expands all sections that can be expanded.

Ctrl+- Collapse All

Collapses all sections that can be collapsed.

Ctrl+W Show Class Browser

Ctrl+Shift+V View Other
Opens documents related to the current document, such as MAC or INT routines.

Alt+1 Toggles Inspector Window Display

Alt+2 Toggles Output Window Display
The Output window has tabs for Result and Find in Files.

Alt+3 Toggles Workspace Window

Alt+4 Toggles Watch Window Display
Ctrl+Alt++ Increase Font
(Press Ctrl and Alt and the equal sign key — here called the plus sign.)
Ctrl+Alt+- Decrease Font
(Press Ctrl and Alt and the minus key.)
Ctrl+Alt+Space Toggles display of Whitespace Symbols, spaces, newlines, and tabs
Ctrl+B Toggle Bracket Matching
Turns bracket matching on and off for the current window.

108                                                                                                                                                            Using Caché Studio

 Keyboard Accelerators

Accelerator Action
Ctrl+Shift+N Toggles Line Numbers Display.
Ctrl+Tab Next Window
Ctrl+Shift+Tab Previous Window
Navigation
Home Go To Beginning of Line
Subsequent presses hops the caret between the beginning of the line and the
beginning of text on the line.

Ctrl+Home Go To Beginning of Document

End Go To End of Line
Ctrl+End Go To End of Document
Page Up Page Up
Page Down Page Down
Ctrl+Page Up Go To Top of Visible Page
Ctrl+Page Down Go To Bottom of Visible Page
Ctrl+  Scroll Down
Ctrl+  Scroll Up
Ctrl+G Goto
Ctrl+Shift+G or F12 Goto Documentation for Tag
Ctrl+F3 Go To Next Error
Ctrl+Shift+F3 Go To Previous Error
Alt+F3 Go to Next Warning
Alt+Shift+F3 Go to Previous Warning
Ctrl+] Go To Bracket
Moves the cursor between the innermost pair of brackets (or parentheses or
braces). Pairs of all three kinds (one of each) can be highlighted if they are
nested. This accelerator works only if bracket matching is turned on (see Ctrl+B).

Editing
Insert Toggle Insert/Overwrite Mode
Toggles between Insert mode (new characters are inserted when typing) and
Overwrite mode (new characters replace existing characters when typing).

Ctrl+Delete Delete Next Word or to End of Word

If caret is at the start of a word, deletes the word. If caret is in the middle of a
word, deletes from the caret to the end of word.

Using Caché Studio                                                                                                                                                            109

Studio Menu Reference

Accelerator Action
Ctrl+Backspace or Delete Previous Word or to Start of Word
Ctrl+Shift+Delete
If the caret is at the end of a word, deletes the word. If caret is in the middle of
a word, deletes from caret to start of word.

Ctrl+Shift+L Delete Line

Ctrl+C or Ctrl+Insert Copy
Shift+Delete or Ctrl+X Cut
Ctrl+L Cut Line
Ctrl+V or Shift+Insert Paste
Ctrl+A Select All
Ctrl+Y or Ctrl+Shift+Z Redo
Ctrl+Z Undo
Ctrl+Space Show Popup
If the cursor is in an appropriate location, this displays the Studio Assist popup,
which shows options available for this location (such as classes, methods,
properties, and so on, as appropriate).

Ctrl+~ Toggle Tab Expansion

Toggles whether tabs or spaces are entered when you press Tab.

Ctrl+U Uppercase Selection

Ctrl+Shift+U Lowercase Selection
Ctrl+Alt+O Toggles the Delay Parsing option.
Ctrl+Alt+U Titlecase (Initial Caps) Selection
Ctrl+{ Insert Open and Close Braces
Ctrl+< Inserts Angle Brackets
Ctrl+/ Block Comment (in Objectscript Routines)
Pressing Ctrl+/ while a block of text is selected “comments ” the block of text;
that is, adds #; (pound semi-colon) to the start of each line.

Ctrl+Shift+/ Block Uncomment (in Objectscript Routines)

Pressing Ctrl+Shift+/ while a block of text is selected “uncomments ” the block
of text (removes the #; from the start of each line).

Ctrl+E In an ObjectScript document, commands in a selection are replaced with their

full names.
Ctrl+Shift+E Compress Commands
In an ObjectScript document, commands in a selection are replaced with their
abbreviated names.

110                                                                                                                                                            Using Caché Studio

 Keyboard Accelerators

Accelerator Action
Tab Block Indent
With no selection, pressing Tab inserts a tab. With a block of text selected,
pressing Tab indents the block a tab's width. If tab expansion is turned on, these
add spaces instead of a tab. If selection is not whole lines, text is replaced by
a tab.

Shift+Tab Block Outdent

With a block of text selected, pressing Shift+Tab outdents the block a tab's width
(removes a tab's width of space from the start of each line). If selection is not
whole lines, the selection is replaced by a tab.

Ctrl+. Insert Dots

With a block of text selected, Insert dots at the start of each line (after leading
white space). Lines must start with leading whitespace. This is for use in block
structuring with leading periods with argumentless DO commands.

Ctrl+Shift+. Remove Dots

Remove leading dots from the start of the selected block of text (for use in block
structuring with leading periods with argumentless DO commands).

Find and Replace

Ctrl+F Find
F3 Find Next
Shift+F3 Find Previous
Ctrl+Shift+F Find in Files
Ctrl+H Replace
F8 Replace and Find Next
Shift+F8 Replace and Find Previous
Ctrl+F8 Replace All
Bookmarks
Ctrl+F2 Toggle Bookmark on Current Line
F2 Go to Next Bookmark
Shift+F2 Go to Previous Bookmark
Ctrl+Shift+F2 Clear All Bookmarks
Build and Compile
F7 Rebuilds All Documents in Project
Ctrl+F7 Compile Active Document
Ctrl+Shift+F7 Compile with Options
Debugging

Using Caché Studio                                                                                                                                                            111

Studio Menu Reference

Accelerator Action
Ctrl+Alt+L Toggle Studio Debug Logging
Turns logging on or off. If on, information is sent to the file
/cacheinstall/bin/CD###.log for Studio debugging purposes. This file can become
very large. Use carefully. For details, see “Logging” in Using Caché Direct.

Ctrl+Shift+A Debug Attach

Attach the debugger to a process.

F9 Debug Toggle Breakpoint on Current Line

F5 Debug Start
Ctrl+Shift+F5 Debug Restart
Ctrl+F10 Debug Run to Cursor
Resumes program execution and pauses at the cursor line or a breakpoint.

F11 Debug Step Into

From a break or an interrupt, step into the next loop.

Shift+F11 Debug Step Out

Step out of the current process.

F10 Debug Step Over

Skip over the next process.

Shift+F5 Debug Stop

Templates
Ctrl+Shift+1 - Ctrl+Shift+9 Open Template
Can be used as accelerators for Studio Templates. To set an accelerator, add
an attribute in the form accelerator="#" to the template (in either the
csp:StudioInteractiveTemplate tag or the csp:StudioSimpleTemplate tag). This
sets an accelerator of Ctrl+Shift+# for the template. The number (#) can be 0-9.

Ctrl+T Open Templates

Wizards: Arguments for New Method wizard and Parameters for New Query wizard
Alt+A Add

Alt+R Remove

Alt+U Up

Alt+D Down

112                                                                                                                                                            Using Caché Studio

 Adding to a Studio Menu

18.13.1 Inserting MultiValue Characters

You can insert the following four MultiValue characters by pressing Ctrl+M and then pressing one of the characters shown
in the table below.

Ctrl+M [ Insert MultiValue textmark.

Press Ctrl+M, then [.

Ctrl+M ] Insert MultiValue subvaluemark.

Press Ctrl+M, then ].

Ctrl+M \ Insert MultiValue valuemark.

Press Ctrl+M, then \.

Ctrl+M ^ Insert MultiValue attributemark.

Press Ctrl+M, then ^.

18.14 Adding to a Studio Menu

To add a menu item to a Studio menu,
1. In the Studio toolbar, right-click the menu name and select Customize.
2. Click the Tools tab, add the.exe file.

Using Caché Studio                                                                                                                                                            113

19
Setting Studio Options
You can modify the behavior of aspects of Caché Studio by selecting Tools > Options.
The options dialog contains tabs described in the following sections.

19.1 Environment Options

These options control the Studio environment:

General
Preferred Language: Sets the default language version used to create new classes.
Items shown in recently used lists: Specifies the number of items displayed in the most recently used file list (under
the File menu).
Open File Added to Project: If enabled, adding a file to the current project automatically opens the file in Studio.
Tabbed Document Selector: If enabled, displays a tab for each open document. You can choose whether the row
displays on the top of bottom of the Studio window.
When connected show documents from last time: If selected, when you start Studio all documents that were open
the last time you were in the current namespace are reopened.
Hide Find and Replace window after operation complete: If selected, the Find and Replace dialog exits when it
completes it task.
Compare: Select a document to compare this document to using Tools > Compare.

Font
Specifies the typeface and size of the fonts used in the following windows and print. Each can use any Windows
font but it is limited to a single typeface and size: Editor Window, Output Window, Print, Workspace, Inspector.

Documentation and Proxy

HTTP Address used to serve on-line documentation: Specify Automatic or HTTP Address from where Studio should
fetch on-line documentation.
Templates and add-ins will use Proxy server for 'CACHE': Specify a server address and port if templates and add-
ins, if needed.

Using Caché Studio                                                                                                                                                            115

Setting Studio Options

Class
Expert Mode: Displays all class attribute values, including usually hidden ones, in both the Inspector and the Class
Definition windows.
Multiline Method Argument: If selected, method arguments are displayed in the class editor one per line. Note that
if Multiline Method Argument is enabled and you use Find in Files and then click a line in the Find in Files output
of a file that has multiline method arguments, the cursor may go to the wrong line number. Disable Multiline
Method Arguments if this is a problem.
Option explicit:
If selected, you see a syntax error if you refer to a variable that hasn't been declared. (Select this
and Studio Assist to display undeclared local variables when entering a #DIM statement in a method.)
Show internal class members in Studio Assist: If selected, Studio Assist lists class members marked as internal.
Track variables: If selected, a green wavy underline indicates any questionable use of a variable—specifically: A
variable is used that has no value, was never created, or has already been killed. Or a variable is given a value,
but never used or killed before being used.
Open class in contracted view:If selected, by default a class opens with all collapsible sections contracted (as
though Ctrl+- had been pressed). If not selected, a class opens with collapsible sections open (as though Ctrl++
had been pressed).
Show storage by default: If enabled, storage is shown by default in open class definitions.

Advanced
Auto Save prevents you from losing changes to Studio documents on a software or system failure. By default,
Auto Save is enabled and saves every 5 minutes. It saves any document that is open and has been modified since
the last save into a file that is a text representation of the document, C:\Documents and Settings\<username>\Local
Settings\Temp\CST*.tmp. If you subsequently save (or close) the document, this .tmp file is deleted. If Studio
crashes, the next time that Studio is opened, you get a message telling you that the temporary file exists. If you
open this temporary document, you can paste the relevant portions into a Studio document.
Server status check timerdetermines how often Studio checks to see if open documents and/or the open project
changed on the Server outside of this Studio process. If Studio is the active application, it uses the first setting,
Studio is active application (2–60 sec). If Studio is running in the background, it uses the second setting: Studio is
background application (30–600 sec).

Automatically reload document when it is modified on the server and it has not been edited in Studio:If selected
and you have a document open in an editor, but have not yet edited it, and someone else saves a new version to
the server, the file in your window is automatically updated. This setting can be enabled on a namespace basis
using a global: Set ^SYS("Studio","Reload")=1 (or 0 to turn off).
Clear undo stack on document reload: If selected, the list of previous actions used when you select Undo or Redo
is emptied. If not selected, the list is maintained and your last action of “reload ” is added to the list.
Show generated documents in Namespace tree: If selected, the namespace window in workspace shows generated
files. If not selected, generated files are not displayed.
Use INT as default for COS: If selected, when you select File > New > Caché Objectscript Routine, an INT file is
opened. If not selected, a MAC file is opened.
Pass credentials to View Web Page: If selected, Studio checks your permissions when you select View Web
Page.

Export flags:Enter flags that you want to use when exporting files. See the article InterSystems Product Miscellanyfor
more information.

116                                                                                                                                                            Using Caché Studio

 Editor Options

19.2 Editor Options

The editor options allow you to control the behavior of the Studio text editor. These options include:

Syntax Check and Assist

Enable Syntax Checking: If enabled, syntax errors are highlighted. You can specify when syntax checking should
be performed - either on each change (each character that you type or erase) (Syntax Check on Change) or when
the cursor leaves the current line (Syntax Check on Leave Line).You can specify whether you also want the errors
to be underlined with a wavy red line (Underline Errors).
Parsing delay. Check if parsing slow. Uncheck if line flashing. If Syntax Check on Change and Parsing delay are
both enabled and you are entering text faster than the parser can reparse, the text flashes between black and the
parsed color. If the text is flashing, disable Parsing Delay by unchecking this option or pressing Ctrl+Alt+O. Response
may slow slightly since every keystroke causes a reparse, but the flashing stops. This switch needs to be set at the
start of each Studio session.
Enable Bracket Matching: If enabled, pairs of matching brackets enclosing the current cursor point are bolded.
Depending on the language you are in, brackets include [ ] square brackets, ( ) parentheses, and < > angle brackets.
Note that for Enable Bracket Matching to work, Enable Syntax Checking must be checked. Bracket Matching Line
LimitLimits the number of lines to search above and below the caret position to locate a matching bracket (as an
unlimited search in a long file would slow the editor down significantly).
Studio Assist: Enables code completion. As you are entering Caché ObjectScript code, a drop-down menu is
displayed showing available options for what you can enter next. If you type a package name, available classes
are listed. If you type a class, available methods are listed. If you type a method, available arguments are listed.
Available options may be listed in other locations as well, such as with #dim declarations.
To display undeclared local variables when entering a #DIM statement, you must be in a method, and you must
have selected Studio Assist and Option Explicit. To be listed, a variable must not begin with %, must not be a
parameter or in the public list, and must not have been declared already. ))
If you type $$$, available macros are listed as follows: User-defined macros are listed if they are defined in the
current file and if they are defined in an include file and, within the include file, they are preceded by a line
beginning with three slashes, ///. System-defined macros are listed if the current file is a class file.
Following a partial member name, Studio displays a list of matching members as follows: If the partial entry begins
with double-quotes, the popup contain only members whose names must be quoted in the program; that is, they
contain spaces or other non-alphanumeric characters. If the partial entry does NOT begin with double-quotes, the
popup contains only members whose names do not need to be quoted. If Studio Assist is triggered directly after
a period, the popup contains all member names.

Colors
The Studio syntax checker uses a different coloring scheme for each language it supports. This option lets you
specify the colors used to highlight syntactic elements when Studio syntax coloring is enabled.
To change the color used by the Studio Editor for a specific syntax element do the following in the Options dialog
Appearance tab:
1. Select a language (such as Caché ObjectScript) from the available options
2. Select a syntax element (such as comments)
3. Select the desired foreground (and background color if you must!) color
4. Click Apply to use the new color scheme.

Using Caché Studio                                                                                                                                                            117

Setting Studio Options

Reset reverts the selected syntax element to its default color.

Reset All reverts all syntax colors to their default values.

Note: You can also change the color for a particular syntax element by right-clicking it in the editor window
and selecting Set Syntax Color.

Keyword Expansion Case

This feature only applies to Caché ObjectScript routines.
Specifies the case (Use Current Case, Uppercase, Lowercase, or Mixed Case) used to expand ObjectScript commands
when you select Edit > Advanced > Expand Commands. Set this option, highlight the code you want to expand,
then select Edit > Advanced > Expand Commands. This also applies if you are compressing commands.

Indentation
Defines characteristics of automatic indentation.
• Basic: If enabled, if a line begins with a tab, a space, or any combination of spaces and tabs, when you press
Enter, the next line is started automatically with the same combination of spaces and tabs.
• User-defined ('/t' for tab)

: If enabled, you can specify any characters that you would like to be automatically entered at the start of each
subsequent line. For example, if you enter the set of characters \t.#/; (tab, dot, pound, slash, semi-colon)
and if a line begins with any of these characters or any combination of these characters, when you press Enter,
the next line is started automatically with the same combination of characters.
• None: No automatic indentation is provided.

View
Controls the display of some items.
• Show Special Characters: If enabled, the editor displays newline and tab characters using special symbols.
• Show Line Numbers: If enabled, the editor displays line numbers.
• Tab Size: Specifies the size of a tab by number of spaces.
• Convert tabs to spaces: If enabled, the editor converts tabs to spaces.
• Cloudy background color for generated files:If enabled, the editor displays generated files with a greyed
background color to differentiate them from user-created files.

19.3 Compiler Options

These options affect how Studio compiles your code.

Flags and Optimization

This page includes Compile Flags and Optimization Level.

Compile Flags
Keep Generated Source Code: If enabled, specifies that the compiler should not delete any intermediate source
code (routines) that it creates as a consequence of compiling.

118                                                                                                                                                            Using Caché Studio

 SQL Options

Compile Dependent Classes: If enabled, the compiler compiles all of a class' dependent subclasses.
Skip Related Up-to-date Classes: If enabled, this sets the
“Do not compile up-to-date classes” flag and the compiler
does not compile related classes that have not been modified since their last compilation. The class that is current
in the editor is always, however, recompiled.
Compile In-use Classes: If enabled, the compiler compiles a class even if there currently are instances of the class
in active use.
Flags: Enter any flags that you want to use.

Optimization Level
• No optimization:Recommended during development. It does not recompile dependent classes and it keeps a
strong correspondence between source and object code so it is easier to read and debug. Default.
• Optimize properties: Optimizes any reference to ..property to the instance variable reference (for simple
properties described by datatypes where the get/set method is not overridden).
• Optimize within class and calls to library classes: Optimizes classes, as well as calls to system (% ) classes (as
code may be extracted and moved during the process). Note that incremental compile no longer works for
optimized classes.

Behavior
Compile INT on Save: If enabled, an INT routine is compiled when it is saved. If not enabled, only the source code
is saved. Note that if the source code does not match the compiled object code, errors generated when running the
object code may reference source lines that do not correspond to the error.
Compile MAC on Save: If enabled, a MAC routine is compiled when it is saved. If not enabled, only the source
code is saved. Note that if the source code does not match the compiled object code, errors generated when running
the object code may reference source lines that do not correspond to the error.
Before Compile: You can choose a default behavior of Studio when you select Compile. Before compiling, Studio
will automatically save all modified documents, prompt to save modified documents, or do not save modified doc-
uments.

19.4 SQL Options

Use these options if you primarily use Studio to create classes that map onto existing legacy data.

Legacy Mode: Enable Legacy SQL Mode For Classes

If enabled, the other default settings on this tab are enabled. This option effects only how Studio wizards operate;
it has nothing to do with the runtime behavior of applications.
Default Storage Type: Specifies the storage class used when the New Class wizard creates a new class.
Default $Piece Separator: Specifies the default data delimiter used when defining a mapping to legacy data structures.

Default Collation: Specifies the default index collation used when defining a mapping to legacy data structures.
Private Row ID: Specifies whether new classes should have their SqlRowIdPrivate flag set by default.
Automatically Generate Row ID: Automatically creates a row id field when mapping data to existing storage
structures.

Using Caché Studio                                                                                                                                                            119

A
Using Studio Source Control Hooks
This appendix describes how to connect Caché Studio to a third-party source control system to place Caché code into source
control. It describes how you can add source control to your Caché development projects. It discusses the following topics:
• The Overview provides a summary of how to place Caché code under source control.
• An introduction to Caché documents (class definitions, routines, and CSP files), tools that Caché provides to manage
documents and files, and some issues to consider when mapping Caché documents to XML files
• How to create and activate a source control class, in general
• How to execute the functions or methods of your source control software
• A look at the source control sample provided in the SAMPLES namespace

A.1 Overview
To place a Caché development project under souce control, you do the following:
• Represent units of code as XML files and write them to a document system. Caché considers a class definition, a routine,
or a CSP file as a single unit called a document.
• Place the XML files under source control.
• Ensure that the XML files are kept synchronized with the Caché documents (and vice versa), and make sure that both
are kept in the appropriate read-write state.
• Ensure that you can perform source control activities from within Studio.
• Ensure that Studio always has the same information that the source control system has as to whether a document has
been checked out, and, if checked out, by whom.

A.2 Caché Documents

A Caché document is a class definition, a routine, or a CSP file. Caché records information about each Caché document,
such as whether it has changed since the last compilation. Your source control system will treat each Caché document as
a separate unit.
In Caché, you work within one namespace at a time. The same will be true for your source control system.

Using Caché Studio                                                                                                                                                            121

Using Studio Source Control Hooks

A.2.1 Tools for Managing Documents and Files

Caché provides the following tools for managing Caché documents and external files:
• The %Studio.Extension.Base and %Studio.SourceControl.Base classes provide methods for basic document management.
You can extend one of these classes to add menu items that act on Caché documents. These classes are discussed
“ Creating and Activating a Source Control Class” .
• The $system.OBJ.Export function exports a Caché document to an XML file in the external document system. This
XML file contains all the information needed to reconstruct the Caché document. For example, for a class document,
the corresponding XML file is a text representation of the entire class definition, which includes all code, properties,
comments, and so on.
• The $system.OBJ.Load function loads an external XML file and overwrites the corresponding Caché document, if
one exists.
• The %RoutineMgr.TS class method returns the timestamp for a Caché document. This method also returns, by reference,
the compile time for the Caché document, as the second argument.

A.2.2 Deciding How to Map Internal and External Names

Each document has two names:
• An internal name, the name you use in the Open dialog box in Studio.
• An external name, which should be the complete external file name, including path. Because of differences between
supported Caché platforms, it is not possible to provide a meaningful default.

You will need to set up a bidirectional mapping between the internal names and the external names. In practice, deciding
how to do this may be one of the most challenging parts of creating a source control interface. This mapping is customer-
specific and should be considered carefully.
Generally you would like the source control tool to group similar items. For example, the sample uses the following
directory structure:
• Class files are in the cls subdirectory, which contains subdirectories corresponding to the package hierarchy of the
classes.
• .INT routines are in the int subdirectory.
• .MAC routines are in the mac subdirectory.
• CSP files are in the csp subdirectory, which contains subdirectories corresponding to the package hierarchy of the CSP
files.

For example, the external name for the class MyApp.Addresses.HomeAddress is

C:\sources\cls\MyApp\Addresses/HomeAddress.xml.

This approach might be problematic if you had large numbers of routines. In such a case, you might prefer to group routines
into subdirectories in some manner, perhaps by function.

A.3 Creating and Activating a Source Control Class

This section describes the basic requirements for creating and activating a source control class.

122                                                                                                                                                            Using Caché Studio

 Creating and Activating a Source Control Class

A.3.1 Extending Studio

Caché provides classes that you can use to add menu items to Studio. To add a source control menu to Studio, you would
use either %Studio.Extension.Base or %Studio.SourceControl.Base.
The %Studio.Extension.Base class provides the following methods, which all use the internal name of the Caché document:
• Empty Login and Logout methods that you can implement as needed. The variable $username records the current
user. (In the Login method, the Username argument is provided for backward compatibility; it is recommended that
you use the variable $username instead.)
• Basic methods to indicate the status of a given Caché document: GetStatus and IsInSourceControl. You implement
these methods as needed.
• Callback methods that are executed when a user in Studio performs some action on a Caché document. These methods
include OnBeforeLoad, OnAfterLoad, OnBeforeCompile, OnAfterCompile, and so on.

• An XDATA block named Menu that defines an additional menu for Studio: Source Control. By default, this menu
contains the menu items Check In, Check Out, Undo Check Out, Get Latest, and Add To Source Control. This XDATA
block also defines additional menu items for the context menu in Studio.
All these menu items call methods also defined in this class.
• Methods named CheckIn, CheckOut, UndoCheckOut, GetLatest, and AddToSourceControl, which do nothing by default.

To extend Studio, you define a new class that extends one of these classes. As you see in a “ Activating a Source Control
Class” , the System Management Portal provides a way to indicate which extension class is currently active in a given
namespace. If an extension class is active in a given namespace, and if that class defines an XDATA menu block, those
menu items are added to Studio.

A.3.2 Creating a Source Control Class

To create a source control class, do the following:
1. Create a subclass of %Studio.Extension.Base or %Studio.SourceControl.Base.
2. If you started with %Studio.Extension.Base, create an XDATA block named Menu in your subclass. (Copy and paste
from %Studio.SourceControl.Base to start this.)
3. Implement the methods of this class as needed: AddToSourceControl, CheckIn, CheckOut, and so on. These
methods would typically do the following, at a minimum:
• If appropriate, import or export the Caché document to XML.
• Call the appropriate function or method of your source control software, to act on the XML file.
• Update internal information in Caché about the status of the given file.
• Control whether the Caché document is editable.

The details depend upon the source control system. The sample demonstrates some useful techniques.
4. Implement the GetStatus method of your source control class. This is required. You might also need to implement
the IsInSourceControl method, if the default implementation is not suitable.

A.3.3 Activating a Source Control Class

To activate a source control class for a given namespace, do the following:

Using Caché Studio                                                                                                                                                            123

Using Studio Source Control Hooks

1. Use the System Management Portal to specify which extension class, if any, Studio should use for a given namespace.
To specify the class to use:
a. Navigate to the [Home] > [Configuration] > [Studio Source Control Settings] page of the System Management Portal.
b. On the left, click the namespace to which this setting should apply.
c. Click the name of the extension class to use (or click NONE) and click OK.
This list includes all compiled subclasses of %Studio.Extension.Base.

2. If Studio is currently open, close it and reopen it, or switch to another namespace and then switch back.

A.4 Accessing Your Source Control System

The API for your source control system provides methods or functions to perform source control activities such as checking
files out. Your source control class will need to make the appropriate calls to this API, and the Caché server will need to
be able to locate the shared library or other file that defines the API itself.
If the source control system provides a COM interface, you can generate a set of Caché wrapper classes that you can use
to call methods in that interface. To do so, you use the Caché Activate Wizard in Studio. Given an interface and the name
of the package to contain the classes, the wizard generates the classes. For information, see Using the Caché ActiveX
Gateway.
Also, it is important to remember that Caché will execute the source control commands on the Caché server. This means
that your XML files will be on the Caché server, and your file mapping must work on the operating system used on that
server.

A.4.1 Example 1
For the following fragment, we have used the Caché Activate Wizard to generate wrapper methods for the API for VSS.
Then we can include code like the following within your source control methods:
do ..VSSFile.CheckIn(..VSSFile.LocalSpec,Description)

The details depend on the source control software, its API, and your needs.

A.4.2 Example 2
The following fragment uses a Windows command-line interface to check out a file. In this example, the source control
system is Perforce:
/// Check this routine/class/csp file out of source control.
Method CheckOut(IntName As %String, Description As %String) As %Status
{
Set file=..ExternalName(IntName)
If file="" Quit $$$OK
//...
Set cmd="p4 edit """_file_""""

#; execute the actual command

Set sc=..RunCmd(cmd)
If $$$ISERR(sc) Quit sc

#; If the file still does not exist or

#; if it is not writable then checkout failed
If '##class(%File).Exists(file)||(##class(%File).ReadOnly(file)) {
Quit $$$ERROR($$$GeneralError,
"Failure: '"_IntName_"' not writeable in file sys")

124                                                                                                                                                            Using Caché Studio

 A Look at the Sample

#; make sure we have latest version

Set sc=..OnBeforeLoad(IntName)
If $$$ISERR(sc) Quit sc

//...
Quit sc
}

In this example, RunCmd is another method, which executes the given command and does some generic error checking.
Also, this CheckOut method calls the OnBeforeLoad method, which ensures that the Caché document and the external
XML file are synchronized.

A.5 A Look at the Sample

The SAMPLES namespace provides a sample source control class, Studio.SourceControl.Example. This section shows how
this sample works. The following topics are discussed:
• An introduction to the sample and its assumptions
• The global in which Studio.SourceControl.Example records needed information
• How the class determines the external names of the Caché documents, which are used as the XML file names
• How the class synchronizes the Caché document and the corresponding XML file
• How the class implements the required GetStatus method, which ensures that the Caché document is read-only when
appropriate
• Details of the actual source control methods in the class
• Other notes about this class

Note: The class in your SAMPLES namespace could be slightly different from the examples shown here. In particular,
some of the line breaks have been adjusted for readability in this document.

A.5.1 Introduction
Studio.SourceControl.Example is a partial example that does not make any calls to a source control system. It simply
maintains external XML files that such a system would use. Despite this simplification, however, the sample demonstrates
all the following:
• Establishing and maintaining a relationship between each Caché document and a corresponding external file.
• Keeping Caché up-to-date with the status of each file.
• Appropriately controlling the read-write state of each Caché document.
• Defining methods to check files in and out.

Note that the sample does not modify the read-write state of the external files; the source control system would be respon-
sible for that. Also, the sample implements only the Check In and Check Out methods.
To try this example in the SAMPLES namespace, do the following:
1. Use the System Management Portal to enable this source control class (Studio.SourceControl.Example), as described
earlier in “ Activating a Source Control Class.”

Using Caché Studio                                                                                                                                                            125

Using Studio Source Control Hooks

2. In the Studio Workspace window, double-click a Caché document. Notice a message like the following in the Output
window:
File C:\sources\cls\User\LotteryUser.xml not found, skipping import

3. Edit the document (for example by adding a comment).

4. Click File —> Save. You will see a message like the following in the Output window:
Exported 'User.LotteryActivity.CLS' to file
'C:\sources\cls\User\LotteryActivity.xml'

At this step, you have implicitly added the Caché document to the source control system.
5. Try to make another edit. The Studio displays a dialog box that asks if you want to check the file out. Click No. Notice
that the Caché document remains read-only.
6. Click Source Control —> Check Out and then click Yes. You can now edit the Caché document.
7. Click Source Control —> Check In and then click Yes. The Caché document is now read-only again.

Other menu items on the Source Control menu do nothing, because the sample implements only the Check In and Check
Out methods.

A.5.2 Global
The Studio.SourceControl.Example sample uses a global to record any needed persistent information. Methods in this class
maintain and use the ^MySourceControl global, which has the following structure:

Node Contents
^MySourceControl("base") The absolute path of the directory that will
store the XML files. The default is C:\sources\
^MySourceControl(0,IntName), where IntName is the The date and time when the corresponding
internal name of a Caché file external file was last modified
^MySourceControl(1,IntName) The date and time when this Caché
document was last modified
^MySourceControl(2,IntName) The name of the user who has this Caché
document checked out, if any

This global is purely a sample and is used only by this class.

A.5.3 Determining the External Names

If you enable the Studio.SourceControl.Example class, it maintains external XML files that correspond to any Caché document
that you load or create. It writes these files to the directory C:\sources\ by default, as described in “Deciding How to Map
Internal and External Names.” For example, the external name for the class MyApp.Addresses.HomeAddress is
C:\sources\cls\MyApp\Addresses/HomeAddress.xml.

Within the sample, the ExternalName method determines the external file name for any Caché document. This method is
as follows:

126                                                                                                                                                            Using Caché Studio

 A Look at the Sample

Method ExternalName(IntName As %String) As %String

{
Set name=$piece(IntName,".",1,$length(IntName,".")-1)
Set ext=$zconvert($piece(IntName,".",$length(IntName,".")),"l")
If name="" Quit ""
Set filename=ext_"\"_$translate(name,".","\")_".xml"
Quit $get(^MySourceControl("base"),"C:\sources\")_filename
}

The sample is suitable only for Windows, of course. The implementation of this method would need to be different on
UNIX® or VMS.

A.5.4 Synchronizing the Caché Document and the External File

Two methods are responsible for ensuring that the Caché document and the corresponding XML file are kept synchronized
with each other:
• Studio calls the OnBeforeLoad method immediately before loading any Caché document into the work space.
• Studio calls the OnAfterSave method immediately after saving any Caché document.

In the sample, the OnBeforeLoad method is as follows:

Method OnBeforeLoad(IntName As %String) As %Status
{
Set filename=..ExternalName(IntName)
If filename="" Quit $$$OK

#; If no file then skip the import

If '##class(%File).Exists(filename) {
Write !,"File ",filename," not found, skipping import"
Quit $$$OK
}

#; If the timestamp on the file is the same as the last time

#; it was imported, then do nothing
If ##class(%File).GetFileDateModified(filename)=
$get(^MySourceControl(0,IntName)) {
Quit $$$OK
}

#; Call the function to do the load

Set sc=$system.OBJ.Load(filename,"-l-d")
If $$$ISOK(sc) {
Write !,"Imported '",IntName,"' from file '",filename,"'"
Set ^MySourceControl(0,IntName)=##class(%File).GetFileDateModified(filename)
Set ^MySourceControl(1,IntName)=##class(%RoutineMgr).TS(IntName)
} Else {
Do DecomposeStatus^%apiOBJ(sc,.errors,"d")
}
Quit sc
}

Note:
• The method checks to see whether the external file exists yet. If the external file exists, the method compares its time
stamp to the time stamp of the Caché document. If the external file is more recent than the Caché document, the method
loads it.
It is not strictly necessary to check the time stamps; this method could load the external document every time. The
check is performed because it offers a performance improvement.
• The method sets the relevant nodes of the ^MySourceControl global.

The OnAfterSave method is analogous, as you can see in the sample itself.

Note: Not only does Studio call these methods automatically as noted above, we will call these methods whenever we
need to ensure that the Caché document and the external document are synchronized.

Using Caché Studio                                                                                                                                                            127

Using Studio Source Control Hooks

A.5.5 Controlling the Status of the Caché Document

The GetStatus method of your source control class is responsible for returning information about the status of the given
Caché document. This method has the following signature:
Method GetStatus(IntName As %String,
ByRef IsInSourceControl As %Boolean,
ByRef Editable As %Boolean,
ByRef IsCheckedOut As %Boolean,
ByRef UserCheckedOut As %String) As %Status

Studio calls this method at various times when you work with a Caché document. It uses this method to determine if a
Caché document is read-only, for example. When you implement a source control class, you must implement this method
appropriately.
In the sample, this method is implemented as follows:
Method GetStatus(IntName As %String,
ByRef IsInSourceControl As %Boolean,
ByRef Editable As %Boolean,
ByRef IsCheckedOut As %Boolean,
ByRef UserCheckedOut As %String) As %Status
{
Set Editable=0,IsCheckedOut=0,UserCheckedOut=""
Set filename=..ExternalName(IntName)
Set IsInSourceControl=(filename'=""&&(##class(%document).Exists(filename)))
If 'IsInSourceControl Set Editable=1 Quit $$$OK

If $data(^MySourceControl(2,IntName))
{Set IsCheckedOut=1
Set UserCheckedOut=$listget(^MySourceControl(2,IntName))}

If IsCheckedOut,UserCheckedOut=..Username Set Editable=1

Quit ..OnBeforeLoad(IntName)
}

Here is how this method works:

1. It first initializes all the arguments that it returns by reference.
2. The method then checks to see whether the external document exists yet; if it does not, the Caché document should be
editable.
3. The method then checks the ^MySourceControl global to see if anyone has checked this document out. If so, and
if that user is the current user, the document is editable. If the document is checked out to a different user, it is uneditable
to the current user.
4. Finally, the method calls the OnBeforeLoad method, which was described earlier in this document. This step ensures
that the Caché document and the external XML file are synchronized and that the relevant nodes of the
^MySourceControl global get set.

A.5.6 Source Control Actions

The sample implements methods for the two most basic source actions: check in and check out.
The CheckIn method is as follows:

128                                                                                                                                                            Using Caché Studio

 A Look at the Sample

Method CheckIn(IntName As %String, Description As %String) As %Status

{
#; See if we have it checked out
If '$data(^MySourceControl(2,IntName)) {
Quit $$$ERROR($$$GeneralError,"You cannot check in an item
you have not checked out")
}
If $listget(^MySourceControl(2,IntName))'=..Username {
Quit $$$ERROR($$$GeneralError,"User '"_
$listget(^MySourceControl(2,IntName))_"'has this item checked out")
}

#; Write out the latest version

Set sc=..OnAfterSave(IntName)
If $$$ISERR(sc) Quit sc

#; Remove the global to show that we have checked it in

Kill ^MySourceControl(2,IntName)
Quit $$$OK
}

Notes:
• This method uses the ^MySourceControl global to see whether the current user can actually check this Caché
document in.
• If the user can check the document out, the method does the following:
– The method calls OnAfterSave to make sure that the Caché document and the external document are synchronized.
– The method kills the appropriate node of the ^MySourceControl global to indicate that the document is now
checked in.

The CheckOut method is analogous.

These methods could be extended to include the appropriate calls to a third-party source control system.

A.5.7 Other Details

By default, the method IsInSourceControl calls the GetStatus method and gets the needed information from there.
In the sample, the method IsInSourceControl returns true for all internal names; recall that all documents are assumed to
be under source control.
A class definition can be changed when you compile it, because compilation can update the storage information. Accordingly,
the sample implements the OnAfterCompile method. This method just calls the OnAfterSave method, because it needs
the same logic as that method provides; specifically, it needs to check whether the Caché document has changed and if so,
save the XML file again.

Using Caché Studio                                                                                                                                                            129

B
Class Definition Syntax
This appendix describes the syntax of how to create class definitions in Studio.
This appendix covers how to define each of the following:
• Class
• ClassMethod
• ForeignKey
• Index
• Method
• Class Parameter
• Projection
• Property
• Storage
• Query
• Relationship
• SQL Trigger
• XData

B.1 Class Definition Example

The following is a complete definition of a sample class demonstrating many of the elements of the class definition language:
/// This sample persistent class represents an employee.
Class MyApp.Employee Extends %Persistent [ ClassType = persistent ]
{
/// Project this class as a Java class
Projection Java As %Projection.Java;

/// A user-defined class parameter

Parameter APPNAME = "My Application";

/// An index on Name

Index NameIndex On Name;

/// An index on Title and Salary

Index TSIndex On (Title,Salary);

Using Caché Studio                                                                                                                                                            131

Class Definition Syntax

/// The company this employee works for.

Relationship Company As Company [ Cardinality = one, Inverse = Employees ];

/// The employee's name.

Property Name As %String(MAXLEN = "50", POPSPEC = "Name()");

/// A character stream containing notes about this employee.

Property Notes As %CharacterStream;

/// The employee's current salary.

Property Salary As %Integer(MAXVAL = "100000", MINVAL = "0");

/// The employee's job title.

Property Title As %String(MAXLEN = "50", POPSPEC = "Title()");

/// Prints the properties <property>Name</property> and

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

/// A class query listing employees by name.

Query ByName() As %SQLQuery(CONTAINID = "1")
{
SELECT ID,Name
FROM Employee
ORDER BY Name
}

With View > View Storage, you can also display the storage definition for a persistent class definition. (A storage definition
specifies the physical structure used to store a class in a database.) The storage definition is displayed as an XML island
(a block of XML) in the class definition.

B.2 General Structure

A class definition in Studio is a text representation of a class definition in the Caché database.
A class definition consists of a class statement, declaring the name of the class and its characteristics, and one or more
statements that define members of the class.
For example, here is the definition of a simple, persistent class containing two properties:
Class MyApp.Person Extends %Persistent [ClassType = persistent]
{
Property Name As %String;
Property Home As Address;
}

B.2.1 Generation and Format

A Studio class definition is only one of many possible representations of a class definition. The class definition language
is used only within Caché Studio; the exact text of a class definition is not saved in the database. Whenever you open an
existing class definition, Studio regenerates the class definition text display from the underlying class definition in the
database. When it regenerates text, Studio may rearrange the display of some of the class metadata.

B.2.1.1 White Space

Extraneous white space characters (tabs and spaces) are ignored (and may be removed by Studio) in class definition state-
ments. White space characters in the body of method, query, trigger definitions, and quoted keyword values are retained.

132                                                                                                                                                            Using Caché Studio

 General Structure

B.2.1.2 Case
When a class definition is regenerated, the class definition language might change the case of certain class metadata to a
customary case (such as lowercase to uppercase). Certain keywords, the names of members, and any implementation code
which are sensitive to case are not changed by Studio.

B.2.2 Statements
A class definition statement defines the characteristics of a class or a member of a class. Each statement consists of the
following parts:
• Description (optional)
• Declaration (required)
• Keyword List (optional)
• Body (optional)

These are described below.

For example, the following statement defines a method:
/// This method returns 1 if successful.
Method Test() [ Private ]
{
Write 1
}

In this case, the description consists of “This method returns 1 if successful. ”; the declaration consists of Method Test();
the keyword list contains Private and the body contains Write 1.

B.2.2.1 Description
A description is a special type of comment that precedes a class or class member and specifies the value of the Description
keyword for the class or class member.
A description is indicated using three slashes, (///). Text between /// and the end of the line is included in the description.
For example, here is a property with a description:
/// This property represents a Name
Property Name As %String;

If a class definition is closed and reopened, descriptions separated by white space are concatenated, thus:
/// This is line one

/// This is line two

Method x()
{
}

becomes:
/// This is line one
/// This is line two
Method x()
{
}

and is placed immediately before the element to which they relate when the class definition is regenerated.
A description must be placed outside of any statement. A description at the very end of a document (with no member defi-
nition following it) is not associated with any member definition and is lost when the document is saved or regenerated.

Using Caché Studio                                                                                                                                                            133

Class Definition Syntax

Using HTML in Descriptions

Caché uses descriptions to create documentation for the class in its online class reference (samples:%XML.Adaptor,
%UnitTest.TestCase). You can use HTML tags to format the description. In addition to standard HTML, the online reference
recognizes the following tags: CLASS, METHOD, PROPERTY, PARAMETER, QUERY, and EXAMPLE. CLASS,
METHOD, and PROPERTY are described here. See the documentation for %CSP:Documatic for details of the others.
CLASS
Use to tag class names. If the class exists, the contents are displayed as a hyperlink to the class' documentation. For example:
/// This uses the <CLASS>Person</CLASS> class.
Method x()
{
}

METHOD
Use to tag method names. If the method exists, the contents are displayed as a hyperlink to the method's documentation.
For example:
/// This is identical to the <METHOD>Unique</METHOD> method.
Method x()
{
}

PROPERTY
Use to tag property names. If the property exists, the contents are displayed as a hyperlink to the property's documentation.
For example:
/// This uses the value of the <PROPERTY>State</PROPERTY> property.
Method x()
{
}

Here is a multi-line description using HTML markup:

/// The <METHOD>Factorial</METHOD> method returns the factorial
/// of the value specified by <VAR>x</VAR>.
ClassMethod Factorial(x As %Integer) As %Integer
{
If (x > 1) {
Quit x * (..Factorial(x - 1))
}
Else {
Quit x
}
}

B.2.2.2 Statement Declaration

A statement's declaration states the kind of class or class member the statement is defining. Every declaration starts with
one of the following words. These words are not case-sensitive but the Studio Editor changes any variations in case back
to that displayed above, initial capital.
• Class
• ClassMethod
• ForeignKey
• Index
• Method
• Parameter
• Projection

134                                                                                                                                                            Using Caché Studio

 General Structure

• Property
• Query
• Relationship
• Trigger
• XData

The class or class member type is followed by an identifier that specifies the name of the class or class member, such as
Class Manager. Depending on the statement type there can be additional specifications, such as the data type of a property
or the value of a parameter.

B.2.2.3 Statement Keyword List

An optional keyword list immediately follows the statement declaration. It consists of a list of keywords, which can have
values, contained in matching square brackets ([ ]), separated by commas. A keyword is assigned a value using the equals
(=) character:
Property X As %Integer [ Final, Required, SqlFieldName = _x ];

If a keyword has a boolean value (true or false), the presence of the keyword indicates a true value; you do not have to
specify a value using =. A false value is indicated by placing the word Not immediately before the keyword:
Property X As %Integer [ Final, Not Required ];

If a keyword value is an identifier (such as a property name), you can place the identifier directly after the = (white space
is ignored). If the value is not an identifier, you must enclose it in quotation marks:
Property Colors As %String [ SqlListDelimiter = "," ];

If a keyword value consists of a list of values, enclose the entire list in matching parentheses, ( ), and delimit list items with
commas (,).
Method Z() [ Final, PlaceAfter = (X, Y), Private ]
{
}

B.2.2.4 Statement Body

The statement body is defines larger blocks of multiline content, such as a method implementation, and is enclosed in
matching braces { }:
Method FullName() As %String
{
Quit ..FirstName _ "," _ ..LastName
}

If a statement has no body, terminate the statement with a ; (semi-colon):

Property Name As %String;

B.2.3 Comments
The class definition language supports both // and /* style comments. Any text between /* and */ is ignored. Any text
between // and the end of the line is ignored.
Note that commented-out sections of class definitions are stored in the database when a class definition is saved.
Here are some examples of comments in a class definition:

Using Caché Studio                                                                                                                                                            135

Class Definition Syntax

/* I am not sure if anyone uses these properties!

Property Name As %String;
Property Title As %String;
*/

Property SSN As %String; // I left this one alone

B.2.4 Comments Used in the Class Reference

There is a special use of the // comment that is used to create documentation in the Class Reference for each class that you
create; that is, a comment that begins with three slashes, ///, which occurs just before a statement declaration. The content
of the comment are put into the Description property of the class and can be edited in the Inspector.
///Adds two integers
ClassMethod Add(
arg1 As %Integer,
arg2 As %Integer) As %Integer
{
quit arg1 + arg2
}

Click View > Show Class Documentation to see the documentation for this class. Example:

Comments that begin with /// that are within the body of a class member definition are not put into the Class Reference.

Note: The description line for a class declaration cannot begin with either a single or a double slash. If you do either of
these, the class declaration is marked as an error from the start of the description line to the last bracket of the
class declaration; in other words, the entire file is marked as in error, underlined with red wavy lines, with red
arrows in the left column.
The description line for a class member declaration cannot begin with a single slash. If you do this, the class
member declaration is marked as an error from the start of the description line to the last bracket of the class
declaration; in other words, the declaration is marked as in error, underlined with red wavy lines, with red arrows
in the left column.

B.3 Statements
The following sections describe class definition statements in more detail.

B.3.1 Class Statement

A Class statement defines a class and specifies class-wide keyword values. Only one class declaration is allowed in a Studio
class definition.

B.3.1.1 Extends Clause

A Class statement can include an optional Extends clause that specifies the superclasses used by the class. This is equivalent
to setting the value of the class' Super keyword.

136                                                                                                                                                            Using Caché Studio

 Statements

Class Cow Extends Mammal

{
}

If a class has multiple superclasses, place their names in () (parentheses) and separate them with , (comma):
Class Platypus Extends (Mammal, Reptile)
{
}

B.3.1.2 Keyword List

A Class statement can include an optional keyword list:
Class Dodo Extends Bird [ Abstract, Final ]
{
}

The following table displays the keywords that can appear in the optional keyword list. Do not provide a value for keywords
marked as Boolean:
Table II–1: Class Keywords

Keyword Possible Values and Purpose

Abstract Boolean. Specifies that you cannot create instances of an Abstract class.
ClassType DataType | Persistent | Serial | Stream | View
ClientDataType Object Data type. Bigint | Binarystream | Boolean | Characterstream | Currentcy | Date
| Decimal | Double | Fdate | Ftimestamp | Handle | Integer | List | Longvarchar | Numeric
| Status | Time | Timestamp | Varchar
ClientName String. Lets you define an alternate name for a class when it is projected to a client
language.
CompileAfter Class name. Compile this class after the specified classes.
DdlAllowed Boolean. Specifies that DDL statements are allowed to alter this class.
DependsOn List of classes. Specifies other classes that must be compiled and runnable before this
class can be compiled
Final Boolean. Specifies that this class cannot have subclasses.
Hidden Boolean. Specifies that this class is not displayed in the Class Reference.
Import One or more package names, set in the Class Inspector. Specifies classes that you want
to import from.
IncludeCode One or more include file names, set in the Class Inspector. Specifies files that are included
during compilation.
IncludeGenerator One or more include file names, set in the Class Inspector. Specifies files that are included
during compilation of this class' generator methods.
Language CACHE | BASIC. Specifies language used to implement methods for this class; can be
overridden within an individual method.
OdbcType ODBC Data type. Bigint | Bit | Date | Double | Integer | Longvarbinary | Longvarchar |
Numeric | Resultset | Smallint | Struct | Time | Timestamp | Tinyint | Varbinary | Varchar
Owner User Name. Specifies owner of a persistent class.
ProcedureBlock Boolean. Specifies that each ObjectScript method in this class is a procedure block.

Using Caché Studio                                                                                                                                                            137

Class Definition Syntax

Keyword Possible Values and Purpose

ServerOnly 0 | 1 | empty. Specifies that a class will not be projected to a Java or C++ client.
SoapBindingStyle Document | rpc. Specifies the binding style (document or rpc) or SOAP invocation
mechanism used by Web methods defined in this class.
SoapBodyUse Encoded | literal. Specifies the encoding (encoded or literal) used by the inputs and
outputs of Web methods defined in this class.
SqlCategory SQL Category Name. Date | Double | Integer | Name | Numeric | String | Time | Timestamp
SqlRowIdName SQL Identifier. Field name for ID column.
SqlRowIdPrivate Boolean. Specifies that ID column is projected as a hidden field.
SqlTableName SQL Identifier. Table name used to identify the class in its SQL projection.
StorageStrategy Name of Storage Definition; used to define the storage structure used by a persistent
class.
ViewQuery SQL statement. SQL Query for a view definition class.

B.3.1.3 Class Statement Body

The body of a Class statement consists of zero or more statements defining members of the class:
Class Cow Extends Mammal
{
Property Food As Cud;

Method Eat(amount As Cud)

{
Set ..Food = ..Food + amount
}
}

B.3.2 Parameter Statement

The Parameter statement defines (or overrides) a class parameter.
A default value for the parameter can be specified using an = clause:
Parameter AUTHOR = "ELVIS";

The Parameter statement has no body.

B.3.2.1 Parameter Keyword List

A Parameter statement can include an optional keyword list:
Parameter ANSWER [ Final ] = "African Swallow";

The following table displays the keywords that can appear in the optional keyword list. You do not provide a value for
keywords marked as Boolean:

138                                                                                                                                                            Using Caché Studio

 Statements

Table II–2: Parameter Keywords

Keyword Possible Values

Abstract Boolean. Specifies that this is an abstract parameter.
Constraint String. Specifies a user interface constraint for the parameter.
Final Boolean. If present, specifies that subclasses cannot override the definition of
this parameter.
Flag Enum | List | Edit | Empty | Sys. Modifies the user interface type (in Studio) for
this parameter. This is useful for classes that you intend to subclass.
Internal Boolean. Specifies that this parameter should not be displayed in the class
documentation.

B.3.3 Property Statement

The Property statement defines (or overrides) a property for a class. The property type is specified with an As clause and
a class name:
Property Boardwalk As %String;

To define a collection property (which can be a list or an array) use the following syntax:
Property Aliases As List Of %String;

If you want to define a relationship property, use the Relationship statement.

B.3.3.1 Property Parameters

A Property statement can define values for one or more property parameters. The list of available parameters depends on
the type of property.
A parameter list is a comma-separated list of parameter names and values, enclosed in () (parentheses). All parameter values
are treated as strings and must be enclosed in matching quotation marks (""):
Property SALARY As %Integer(MINVAL = "0", MAXVAL = "1000000");

B.3.3.2 Property Keyword List

A Property statement can include an optional keyword list:
Property SecretName As %String(MAXLEN = "20") [ Private, Required ];

The following table displays the keywords that can appear in the optional keyword list. Do not provide a value for keywords
marked as Boolean:
Table II–3: Property Keywords

Keyword Possible Values

Calculated Boolean. If present, specifies that the property has no in-memory
storage allocated for it when the object containing it is instantiated.
ClientName String. Lets you define an alternate name for a property when it
is projected to a client language.

Using Caché Studio                                                                                                                                                            139

Class Definition Syntax

Keyword Possible Values

Final Boolean. If present, specifies that subclasses cannot override the
definition of this property..
Identity Boolean. For a persistent object, specifies that a property
corresponds to an identity column in the corresponding SQL table.
InitialExpression Value expression. Specifies an initial value for the property, which
can either be a constant or a Caché ObjectScript expression
Internal Boolean. Specifies that this property should not be displayed in
the class documentation.
Inverse Property name. Specifies the inverse side of a relationship.
Multidimensional Boolean. If present, specifies that a property has the
characteristics of a multidimensional array.
Private Boolean. If present, specifies that the property can only be used
by instance methods of this class (or its subclasses).
ReadOnly Boolean. For a persistent object, specifies that a property is
read-only, which limits the number of ways its value can be set.
Required Boolean. If present, In a persistent class, specifies that the
property's value must be given a value before it can be stored to
disk.
SqlCollation Deprecated. Use the COLLATION data type parameter to override
the collation for a property.
SqlColumnNumber Integer. Sets the SQL Column Number for this property. Provided
for legacy application support.
SqlComputeCode Caché ObjectScript code that evaluates to a computed field value.
SqlComputed Boolean. Specifies that this is a computed field.
SqlComputeOnChange Property name. Specifies fields upon which this field calculation
depends.
SqlFieldName SQL Identifier. In a persistent class, in an SQL projection, specifies
the column name that identifies this property. By default, the SQL
column name is the same as the property name.
SqlListDelimiter Delimiter. Specifies the delimiter character used within SQL for
lists.
SqlListType List | Delimited | Subnode. SqlListType controls how the values
of a field are represented in memory in SQL, and how they stored
on disk.
Transient Boolean. If present in a persistent class, specifies that the property
is not stored in the database.

140                                                                                                                                                            Using Caché Studio

 Statements

B.3.4 Relationship Statement

The Relationship statement defines a relationship property for a class. It is similar to the Property statement. The type (a
class name) for the relationship is required and specified using an As clause. The other required relationship attributes,
Cardinality and Inverse, are specified in the keyword list:
Relationship Chapter As Chapter [Inverse = Book, Cardinality = Many];

You can use any of property keywords in a Relationship keyword list. You can also specify property parameters as you
would with a Property statement.

B.3.4.1 Relationship Keyword List

A Relationship statement must include a keyword list that contains Cardinality and Inverse. It can include any other
keywords allowed in a Property statement keyword list:
Relationship Doctor As Doctor [Inverse = Patients, Cardinality = One, Required];

The following table displays the required keywords. See the Property Keyword List for the other allowed keywords. :
Table II–4: Relationship Keywords

Keyword Possible Values

Cardinality One | Children | Many | Parent
Inverse Property Name

B.3.5 Index Statement

The Index statement defines an index for a persistent class. Its declaration contains the name of the index followed by an
On clause containing a list of one or more properties contained in the index. An Index statement has no body:
Index SalaryIndex On Salary;

If an index is on multiple properties, place the properties in a list using ( ), parentheses. The order of the property names
in the list determines the order in which the properties are used (as subscripts) in the index.
Index NameIndex On (LastName,FirstName);

B.3.5.1 Index Keyword List

A Index statement can include a keyword list:
Index SSNIndex On SSN [ Unique ];

The following table displays the optional keywords. Do not provide a value for keywords marked as Boolean:

Using Caché Studio                                                                                                                                                            141

Class Definition Syntax

Table II–5: Index Keywords

Keyword Possible Values

Data List of property names
Final Boolean. If present, specifies that the index is final and cannot override the
implementation of the index.
IdKey Boolean
PrimaryKey Boolean
SqlName SQL Identifier
Type Bitmap | Bitslice | Index | Key
Unique Boolean

B.3.6 Method and ClassMethod Statements

The Method statement defines (or overrides) an instance method for a class. The ClassMethod statement defines a class
method; that is, a method that can be executed with no instances of the class in existence. In every other respect, these
statements are identical.
Here is an example of an instance method:
/// Print this object instance to the console
Method Print() [ Final ]
{
Write "Name: ", ..Name, !
}

Here is an example of a class method:

/// Print any object instance to the console given its id
ClassMethod PrintObject(id As %String) [ Final ]
{
Set obj = ..%OpenId(id)

If (obj '= "") {

Write "Name: ", obj.Name, !
Set obj = ""
}
}

B.3.6.1 Method Arguments

The Method declaration includes its formal specification (FormalSpec); that is, a list of its formal arguments, if any. This
list consists of one or more comma-separated argument names, their types (a Caché class name), and, optionally, their
default values. The ByRef modifier indicates an argument that is called by reference. You can also specify an argument
whose value is returned by reference but has no incoming value by using the Output modifier.
Below is a method defined to take three arguments. The first is a string, the second is called by reference, and the third is
an integer with a default value of 0:
Method Test(a1 As %String, ByRef a2 As %String, a3 As %Integer = 0)
{
}

B.3.6.2 As Clause
A Method statement can include an As clause that specifies the method's return type; this is equivalent to setting the value
of the method's ReturnType keyword:

142                                                                                                                                                            Using Caché Studio

 Statements

Method IsOK() As %Boolean

{
Quit 1
}

The return type is the name of another Caché class. If the As clause is omitted then the method is defined as returning no
value:
Method Hello()
{
Write "Hello"
}

B.3.6.3 Method Keyword List

A Method statement can include a keyword list:
Method Hello() [ Final, Private ]
{
Write "Hello"
}

The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked
as Boolean:
Table II–6: Method Keywords

Keyword Possible Values

Abstract Boolean. Specifies that this is an abstract method.
ClientName String
CodeMode call | code | expression | objectgenerator
ExternalProcName String
Final Boolean. If present, specifies that the method is final and
cannot be overridden in a subclass.
GenerateAfter List of method names
Internal Boolean
Language CACHE | BASIC | JAVA | JAVASCRIPT | MVBASIC |
TSQL
NotForProperty Boolean
PlaceAfter List of method names
Private Boolean
ProcedureBlock Boolean
PublicList List of one or more variable names
ReturnResultsets Boolean
ServerOnly 0 | 1 | empty
SoapAction String. Unique URI that identifies the intent of the SOAP
request | empty
SoapBindingStyle document | rpc
SoapBodyUse encoded | literal

Using Caché Studio                                                                                                                                                            143

Class Definition Syntax

Keyword Possible Values

SoapMessageName Any identifier that is valid in XML
SoapNameSpace Namespace URI
SoapTypeNameSpace Namespace URI
SqlName SQL Identifier
SqlProc Boolean
WebMethod Boolean
ZenMethod Boolean

B.3.6.4 Method Statement Body

The body of a Method statement contains the implementation code for the method (this is the value of the method's
Implementation keyword). You must be careful to match all { } (braces) characters contained in the implementation code.
A Method statement can contain code in different programming languages (currently supported: Caché ObjectScript,
BASIC, Java, Javascript, MVBASIC, TSQL). A method uses the language specified by its class' Language keyword. A
method definition can override the specified class language by using the method's Language keyword.
By default a method is assumed to use Caché ObjectScript (which is also the default for classes):
Method Hello()
{
Write "Hello"
}

To change the method to Basic, specify the Language keyword:

Method Hello() [ Language = Basic ]
{
Print "Hello"
}

Note that this Basic method does not work unless it is running on a version of Caché that supports Basic.

B.3.7 SQL Query Statement

The Query statement defines an SQL query for a class:
Query ByName(name As %String) As %SQLQuery(CONTAINID = "1")
{
SELECT ID,Name
FROM Employee
WHERE Name %STARTSWITH :name
ORDER BY Name
}

The declaration of a Query contains the name of the query and its argument list. The argument list is specified in the same
manner as the Method statement.
A Query contains an As clause that specifies the name of the class used to provided the query interface methods. The class
name in the As clause can contain parameter values in the same manner as the Property statement.
The body of a Query statement is assumed to be SQL text used to define the query. A user-defined query (of type %Query)
does not require a body, but it does require you to specify its ROWSPEC parameter:
Query Custom() As %Query(ROWSPEC = "Name,Title")
{
}

144                                                                                                                                                            Using Caché Studio

 Statements

B.3.7.1 SQL Query Keyword List

A Query can include a keyword list:
Query Roster() As %SQLQuery() [ Private ]
{
SELECT Name
FROM ClubMember
}

The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked
as Boolean:
Table II–7: SQL Query Keywords

Keyword Possible Values

ClientName String
Final Boolean. If present, specifies that subclasses
cannot override the definition of the query.
Internal Boolean
Private Boolean
SoapBindingStyle document | rpc
SoapNameSpace Namespace URI
SqlName SQL Identifier
SqlProc Boolean
SqlView SQL Identifier
SqlViewName SQL Identifier
WebMethod Boolean

B.3.8 Projection Statement

The Projection statement defines (or overrides) a class projection. The type (a class name) for the property is specified
using an As clause:
Projection JavaClient As %Projection.Java;

B.3.8.1 Projection Parameters

A Projection statement can define values for one or more projection parameters. The list of available parameters depends
on the type (class) of the projection.
A parameter list is a comma-separated list of parameter names and their corresponding values. All parameter values are
treated as strings and must be enclosed in matching quotation marks (""):
Projection JavaClient As %Projection.Java(LOCATION="c:\java");

B.3.9 SQL Trigger Statement

The Trigger statement defines an SQL Trigger for a persistent class. Its declaration contains the name of the trigger.
The body of a Trigger contains the code.

Using Caché Studio                                                                                                                                                            145

Class Definition Syntax

Trigger OnInsert [ Event = INSERT ]

{
// trigger code
}

B.3.9.1 SQL Trigger Keyword List

A Trigger statement can include an optional keyword list:
Trigger OnDelete [ Event = DELETE, TIME = AFTER ]
{
// trigger code
}

The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked
as Boolean:
Table II–8: SQL Trigger Keywords

Keyword Possible Values

Event DELETE | INSERT | UPDATE | INSERT/UPDATE | INSERT/DELETE |
UPDATE/DELETE | INSERT/UPDATE/DELETE
Final Boolean. If present, specifies that subclasses cannot override the definition of
the SQL trigger.
Foreach row | statement
Internal Boolean
Language cache | tsql
NewTable String
OldTable String
Order Integer
SqlName SQL Identifier
Time AFTER | BEFORE
UpdateColumnList Null or a comma-delimited list of one or more column names.

B.3.10 SQL ForeignKey Statement

The ForeignKey statement defines an SQL Foreign Key for a persistent class:
ForeignKey FKey1(StateName) References StateTable(StateKey);

The declaration consists of the word ForeignKey followed by the name of the foreign key and a list of properties constrained
by the foreign key in matching ( ) characters.
The required References clause specifies the name of the class the foreign key references as well as the name of a key
(unique index) in the referenced class.
The ForeignKey statement has no body.

B.3.10.1 SQL ForeignKey Keyword List

A ForeignKey statement can include an optional keyword list:
ForeignKey FKey1(StateName) References StateTable(StateKey) [SqlName = _fkey1];

146                                                                                                                                                            Using Caché Studio

 Statements

The following table displays the keywords that can appear in the keyword list. Do not provide a value for keywords marked
as Boolean:
Table II–9: SQL ForeignKey Keywords

Keyword Possible Values

Internal Boolean
OnDelete cascade | noaction | setdefault | setnull | empty
OnUpdate cascade | noaction | setdefault | setnull | empty
SqlName SQL Identifier

Using Caché Studio                                                                                                                                                            147

C
Frequently Asked Questions About Caché
Studio
A Question and Answer Set about Caché Studio.

Projects
What is a project?

A project is a collection of class definitions, routines, and/or CSP files that you can group together for the sake of convenience.
Using projects gives you an easy way to return to your work when you start a Studio session. For example, you can place
all the classes related to an application, or part of an application, in a project. When you start Studio, open this project and
the Project tab of the Workspace window displays all the classes in a convenient list.
You can also export and import entire projects to and from a single external file making it easy to save or pass around
application code.

How do I add an item to a project?

There are two ways to add items to a the current project.

• Before opening one or more items (with File > Open), select the Add to Project check box in the Open dialog.
• To add the item in the current editor window to the current project, select Project > Add Item.

Can I add something from another namespace to my project?

No. A project can only contain items that are visible to the current Caché namespace.

Can an item belong to multiple projects?

Yes. A project is a specified set of items (class definitions, routines, and CSP files) that you choose to group together. The
items themselves have no link back to the projects they may belong to. There is no limit to how many projects an item can
belong to.

Using Caché Studio                                                                                                                                                            149

Frequently Asked Questions About Caché Studio

What if I don't want to use projects?

You are not required to use projects with Studio; you can completely ignore them if you like. To ignore projects, do not
add any items to the default project and ignore the prompt asking you if you want to save your project when you exit Studio.

Can I export a project?

Yes. Select Tools > Export > Export Project. Enter a file name and press OK. This exports the entire contents of the current
project (including the project definition) to a single XML file.

How do I delete a project?

Select File > Open to list all your projects. Right-click a project and select Delete.
Note that you can use File > Open to delete any type of item on the server in this way.

Opening Files
How do I open a class definition?

To open an existing class definition (that is, one saved on the Caché server), do the following:
1. Make sure you are connected to the Caché namespace and server containing the class definition.
2. Select File > Open.
3. In the Open dialog, make sure that class definitions are listed by selecting Class Definitions (.CLS) or All in
the File Types combo box.
4. Package names are listed in the file list as folders. Click a package name to list all the classes (or sub-packages) within
the package. Double-click a class name to open it.
5. Alternatively, you can enter the name of the class you want directly into the filename edit box with a .cls extension
(such as Sample.Person.cls) and click Open.

How do I open a routine?

To open an existing routine (that is, one saved in the Caché server), do the following:
1. Make sure you are connected to the Caché namespace and server containing the routine.
2. Select File > Open.
3. In the Open dialog, make sure that routines are listed by selecting either MAC routines (.MAC), INT routines
(.INT), or All in the File Types combo box. Double-click a routine name.
4. Alternatively, you can enter a routine name with extension directly into the filename edit box (such as MyRoutine.MAC)
and click Open.

150                                                                                                                                                            Using Caché Studio

 Frequently Asked Questions About Caché Studio

How do I open a CSP file?

You can open a CSP file in the same way that you open a class definition or a routine. The main difference is that the Open
dialog lists CSP Applications (for example, /csp/samples) as folders; click the name of an application to see the CSP pages
within it.

What does the Show System check box in the Open dialog do?

If the Show System check box is selected, then the File > Open dialog lists system items (items whose names start with the
% character and are stored in the %CACHELIB database) along with items in the current namespace.

Can I use pattern matching in the File > Open dialog?

Yes. You can use the “*” character as a wildcard to match any number of any character as you can in a standard File >
Open dialog. You can use file extensions to filter certain items; for example, “*.cls” lists all Class Definitions in the selected
package. You can use the “ ?” character to match any character. Note that these are Windows pattern matching conventions,
not Caché pattern matching.

How do I open a routine from a different namespace?

The Studio File > Open dialog lists items from only the current namespace and server. To open a routine from a different
namespace or server:
1. Select File > Change Namespace.
2. Open the desired routine.

Can I open a % class?

Yes. You can list % classes (classes whose package name starts with a % character and are stored within the %CACHELIB
database) from the File > Open dialog by selecting the Show System check box at the bottom.
Studio opens % classes as read-only if you open them while connected to a namespace other than %CACHELIB.

What does File > Connect do?

Studio maintains a connection to a specific Caché namespace and server. It uses this connection to provide a list of classes
(such as for specifying property types, super classes, etc.). It also uses this connection for debugging. File > Connect lets
you connect to a different server.

Debugging
How do I start the debugger?

You can connect the debugger to a target process in of the following ways:
• Define a “ debugging target” (name of program or routine to debug) for the current project with Project > Settings.
Then select Debug > Go to start the target program and connect to its server process.
• Select Debug > Attach to select from a list of running processes on a Caché server to connect to.

Using Caché Studio                                                                                                                                                            151

Frequently Asked Questions About Caché Studio

For more details refer to the chapter “Using the Studio Debugger ” in this book.

How can I debug a class?

The Caché Studio debugger lets you step through the execution of programs running on a Caché server. These programs
can include INT files, MAC files, methods within CLS files, CSP classes responding to HTTP requests, server-side methods
invoked from Java or ActiveX clients, or server-hosted applications.
1. To view the INT file during debugging and to save the INT for further review later, set the Keep Generated Source
Code option before you compile your class, located on the Tools > Options > Compiler > General Flags page.

2. Set a breakpoint at the desired location in a class method (or any of the other files mentioned above) by pressing F9
(toggles breakpoint) on the desired source line.
3. Set a debug target to specify where you want the debugger to begin code execution using Debug > Debug Target. Enter
the name of the class and the method that you want to step through.
4. Start the debugger with F5 or Debug > Go.

Can I watch variables?

Yes. While debugging, enter a variable name (or an expression) in the left-hand column of the Studio Watch Window.
Each time the debugger pauses, the variable or expression is reevaluated.

Editing
What do the different colors in the editor mean? Can I change the colors in the editor?

The Studio uses colors to differentiate the syntax elements of a given language.
You can change the colors used for the various syntax elements as follows:
1. Select Tools > Options > Editor > Colors.
2. Select a language.
3. Select an element (comment, variable, etc.)—the list of available elements depends on the selected language.
4. Select Foreground and Background colors and click OK.

Why is there a wavy, red line underneath my code?

The wavy, red line indicates that the underlined code (or possibly code before it) contains syntax errors.

Does Studio support Kanji and Chinese characters?

Yes. Studio has complete support for Unicode and Kanji characters.

Does Studio support Hebrew and Arabic characters?

Yes. The Studio Editor supports Hebrew and Arabic characters, as well as bidirectional editing.

152                                                                                                                                                            Using Caché Studio

 Frequently Asked Questions About Caché Studio

Importing Files
Can I import class definitions or routines from external files?

Yes. Select Tools > Import.

What is the difference between Local and Remote files?

Studio is a client/server application; the Studio itself runs on a client system and talks to a server. The server can either be
on the same machine or on a remote machine. The Studio uses the terms “ Local” and “Remote ” to refer to operating
system files (such as when you are importing or exporting) that are stored on the client and server systems, respectively.
If both the client and server are on the same system then there is no difference between Local and Remote.

Printing
Can I print from Studio?

Yes. Select File > Print or File > Print Preview.

Templates
What is a Template?

Templates are a mechanism for creating user-defined Studio add-ins.

A template is a small program that injects a useful code fragment into the current document at the current cursor point.
Templates can use Caché Server Pages to present a sophisticated user interface within a pop-up browser hosted by Studio.
To find out more, refer to the chapter “Using Studio Templates ” in this book.

Is there a list of available Templates?

Yes. Select Tools > Templates > Templates.

Can I create a new Template?

Yes. You can use Studio to create new Templates. See the chapter “Using Studio Templates ” in this book.

Multiuser Support
Does Studio support development by multiple users?

Yes. You can do this in several ways:

• Set up a common Caché server system and have all developers store their code on it.

Using Caché Studio                                                                                                                                                            153

Frequently Asked Questions About Caché Studio

• Use local Caché servers (on the developer's system) and store source code in a source control system as exported XML
files.

What happens if I try to open a class (or routine) that someone else is editing?

Studio displays a dialog stating that the class (or routine) is in use by someone else and asks you if you want to open it in
read-only mode.

What if someone wants to edit a super class of a class that I am working on?

Studio does not prevent another developer from modifying the super class of a class you are working on.
While Studio could take out locks on all subclasses whenever a class is opened for editing, in practice this would be
annoying and unwieldy. Instead, a development team needs to work out rules and procedures for defining and modifying
super classes. This is similar to how development teams in other languages (say Java) usually work with class definitions
in source control systems.

Classes
How do I create a new class?

Use the New command in the File menu and ask for a new Class Definition. This invokes the New Class Wizard.
For more details, see the chapter Class Definitions in this book.

Can I see the source code generated for my class?

Yes. You can see all the source code generated by the Class Compiler with View > View Other Code (available when the
current window contains a class definition).
Make sure that the Keep Generated Source Code option is set before you compile your class. This option is located on the
Tools > Options > Compiler > General Flags page.

When I try to compile my class, the Studio says it is up to date and does not need to be compiled. Can I force a
compile to happen?

Yes. Turn off the Skip related up-to-date classes option. This option is located on the Tools > Options > Compiler > General
Flags page.

Routines
How do I create an INT routine?

Create a new Caché ObjectScript routine using the New command in the File menu and then save the new routine using a
name with a .INT extension. You can create an include (.INC) file in the same fashion.

154                                                                                                                                                            Using Caché Studio

 Frequently Asked Questions About Caché Studio

SQL
How do I define an SQL View?

Studio does not include a mechanism for defining SQL views. To do this, as well as other SQL tasks, use the Caché System
Management Portal.

Source Control
Does Studio integrate with external Source Control systems?

Yes. The procedure is:

1. Create a subclass of the system-supplied class %Studio.SourceControl.Base where you implement the methods to
interact with your source-control system. The class that you create is called from Studio in response to particular events
and then performs the actions that you have specified.
2. In the System Management Portal, go to the Studio Source Control Settings page ([Home] > [Configuration] > [Studio
Source Control Settings]), select the site-specific source-control class from the list, and click OK.

At this point, Studio has been configured to interact with the source-control system. When Studio attempts to open a document,
prior to opening it, the OnBeforeLoad method of your source-control class is invoked; typically, this method checks the
timestamp on a file representation of the document and, if it is newer in the file, the method calls a Caché function to import
this into the current namespace. This makes sure that the user is seeing the most up-to-date version of the file.
If you modify the file and save it, then Studio calls the OnAfterSave method of the source-control class, which typically
exports this document to the filesystem. (This keeps these files in sync with the routines, classes, etc. that are in Caché.)
When you attempt to modify a document, Studio attempts to get a lock on it, which also triggers a call to a source control
method GetStatus. If the file is locked in source control, Studio can then ask if you want to check it out. This triggers a
call to the CheckOut method which performs the actions required the item out.
%Studio.SourceControl.Base and %Studio.Extension.Base provide a set of methods that allow you to create interactions
between Studio and your source-control system that are as simple or complex as you choose.

Can I create my own hooks?

Yes. You can define hooks—code that is executed whenever items are saved to or loaded from the server. For details see
the appendix “Using Studio Source Control Hooks”.

Compatibility
Can I connect a Studio client to any Caché server?

A Studio client must be either the same version or a higher version than the Caché server that it is connecting to. Example:
Caché 2008.2 Studio can connect to a Caché 2008.2 server or an earlier server. Caché 2008.1 Studio cannot connect to a
Caché 2008.2 (or later) server. To put it another way, Studio works with any server (including UNIX® or OpenVMS
servers) that has the same or lower version of Caché than Studio itself (as long as the server is running Caché v5.1 or
higher).

Using Caché Studio                                                                                                                                                            155

Frequently Asked Questions About Caché Studio

Can I run Studio on Linux?

The Studio client only runs on Windows platforms. You can use a Windows-client to talk to any server. You can also use
a partition manager, such as VMWARE, to run both Windows and Linux partitions on your development system and run
Studio in the Windows partition with Caché running in the Linux partition. The only trick is to configure your networking
so that the Windows partition can talk to the Linux partition via TCP/IP. Studio can also run under Windows on an Intel-
based Macintosh.

Studio Implementation
Why doesn't Studio use the licensed components of Microsoft Visual Studio?

There are several reasons why we built Caché Studio from the “ground up” instead of licensing or extending Visual Studio:
• The Caché Studio editor uses advanced parsing technology not available within the Microsoft Studio framework.
• Microsoft cannot guarantee the compatibility of future versions of Visual Studio.

Why wasn't the Studio interface developed using Java?

At this time, the only way to get acceptable performance for the Studio editor is to use direct calls to the Windows API.
While there are syntax-coloring editors developed using Java they do not offer the sophisticated multi-language parsing
used by Studio and they typically require very high performance computers for decent performance.

156                                                                                                                                                            Using Caché Studio