Basic Concepts

Rapid Application Development Tools and Technologies

These tools and technologies include:
Cach Studio: An integrated development environment that supports the object-oriented approach to designing and building applications. With Studio you can define classes using several languages including Cach ObjectScript, Cach Basic, and MVBasic. Cach Terminal: A command-line interface to the Cach database. The Terminal allows you to open objects to execute their methods and view their data. You can also execute a number of commands and access a number of Cach utilities including the autopopulation utility.

 Zen: A framework for creating dynamic, data intensive, and richly interactive Web pages. You can create Zen pages using Cach Studio.
The System Management Portal: A browser-based interface for system management. Using the portal you can perform many tasks including defining, viewing, and accessing your data in a relational format. You can define your database tables and query your data using standard SQL. Cach Studio, Cach Terminal, and the System Management Portal, can all be launched from the Cach Cube. Simply click the cube and then click a tool on the the menu.

Cach Cube
The primary Cach interface on Microsoft Windows platforms is the Cach Cube.

From the Cach Cube, you can start all of the Cach configuration and management tools.
You can also invoke each Cube command from a shortcut or command line. When you click the Cach Cube, a menu appears with commands to use the Cach utilities and programming environments.

Cach Cube
Getting Started Displays links to tutorials, release notes, documentation etc. Start Cach Starts the default instance specified in the square brackets after the menu item, for example [CACHE]. If the Cach server is already started, this option appears dimmed it is unavailable. Stop Cach Shuts down or restarts the local Cach instance. If the Cach server is stopped, this option appears dimmedit is unavailable. Studio -Creates, edits, deletes, and compiles Cach class definitions, CSP (Cach Server Pages) pages, Cach Basic routines, and Cach ObjectScript routines. Terminal Invokes the command line interpreter in the Cach programming environment.

Cache Cube

Cach Cube System Management Portal- Performs common system management

tasks. Creates databases and namespaces, and adjusts all Cach configuration settings. Displays classes, globals, and routines, and functions for managing each. Displays tables and views, perform queries and SQL management functions.

Documentation- Displays Cach online documentation.

DeepSee- Invokes the InterSystems DeepSee login page. See the Overview of DeepSee guide for more information. Preferred Server [server name] Shows a list of remote servers and maintains server connections by using the Add/Edit command on the submenu. The preferred server appears in brackets and has a check mark next to it in the server list. About Displays Cach version and build information. Exit Removes the Cach Cube icon from the system tray; this does not stop Cach. elated information

 It refers to a logical entity that serves as a container for programs and data.

Namespace

a namespace allows you to collect objects from multiple databases into a single frame of reference so that they appear as if they were all stored together.
Users need only make a simple reference to a global no matter where it resides

namespace mapping specifies the globals database location.

Namespace Name
A namespace name can be up 31 characters long using a combination of letters, numbers, and the characters %, &, and $. It must be unique within the dataset (same rules as for a local variable).

The use of namespace is not case-sensitive, that is, letters can be uppercase or lowercase.
All namespaces are converted to uppercase internally.

Creating a Namespace
[Namespaces] Name=a,b,c Only the first field is required. If the other fields are not specified, they are set to the system default. From left to right: a: Default database name for globals. b: Default database name for routines and classes. If the database is not specified, it defaults to the globals database. c: Default database name for temporary storage. If the database is not specified, it defaults to CACHETEMP

Datasets
A logical entity that represents a directory name or directory and system name in Cach

Cach object model

The Cach object model defines the behavior and features of both persistent (database) objects as well as transient objects (those not stored). The Cach object model supports the following features: Persistence Objects can be stored within the Cach database or in an external database. Stored objects are simultaneously projected as relational tables and can be queried using standard SQL. The object model is rich enough to define the complete information required for complex database applications, such as indices, storage structure, integrity constraints, and so on. Properties Objects can contain both simple (literal) or objectvalued properties. Object-valued properties can be references to external objects or embedded objects. There are also a variety of relationship, collection, and stream properties. Custom data types Objects can use application-specific data types which are themselves defined as classes.

 Methods Objects have behavior associated with them. Polymorphism Applications can easily adapt to new circumstances by providing specialized implementations of operations. The runtime system automatically invokes the correct implementation based on object type. Inheritance Applications can reuse code by deriving new components from pre-existing classes. Each class describes an entity, such as a person, a record, or an account. An object is a specific instance of a class. An object can exist on disk, in memory, or in a client application.

Cach Objects Architecture

The class dictionary A repository of class definitions which is stored within a Cach database. The class dictionary is also used by the Cach SQL engine and is responsible for maintaining synchronized object and relational access to Cach data. The class compiler A set of programs that convert class definitions into executable code. The object runtime system A set of features built into the Cach virtual machine that support object operations (such as object instantiation, method invocation, and polymorphism) within a running program. The Cach class library A set of prebuilt classes that come with every Cach installation. This includes classes that are used to provide behaviors for user-defined classes (such as persistence or data types) as well as classes that are intended for direct use within applications (such as email classes).

 Every Cach namespace contains its own class dictionary which defines the available classes for that namespace. There is a special CACHELIB database, installed as part of Cach, that contains the definitions and executable code for the classes of the Cach class library.

These classes are referred to as system classes and all are part of packages whose names start with a % character, such as %Library.Persistent (the names of members of the %Library package can be abbreviated, so that %String is an abbreviation for %Library.String).
The class dictionary contains two distinct types of data:
Definition data The actual class definitions that users create. Compilation data Data generated as a result of compiling class definitions is also stored.

The class dictionary stores its data in a set of globals (persistent arrays) whose names start with ^odd.

Cach class library

The Cach class library contains a set of prebuilt classes. It is automatically installed with every Cach system within the CACHELIB database. You can view the contents of the Cach class library using the online class documentation system provided with Cach. The Cach class library contains a number of packages, each of which contains a family of classes.

Globals
Cach stores its data in multidimensional sparse arrays, known as globals. A global is a named multidimensional array that is stored within a physical Cach database. Within an application, the mapping of globals to physical databases is based on the current namespace

 There are two types of globals : An extended global reference This is a global located in a namespace other than the current namespace. A process-private global This is an array variable that is only accessible to the process that created it.

 The naming conventions for globals are: A global name begins with a caret character (^) prefix. This caret distinguishes a global from a local variable. The first character after the caret (^) prefix in a global name can be: A letter or the percent character (%) . % globals are typically stored within either the %SYS or %CACHELIB databases. The other characters of a global name may be letters, numbers, or the period (.) character. The percent (%) character cannot be used, except as the first character of a global name. The period (.) character cannot be used as the last character of a global name. A global name may be up to 31 characters long (exclusive of the caret character prefix). You can specify global names that are significantly longer, but Cach treats only the first 31 characters as significant.

Physical Structure of Globals

Globals are stored within physical files using a highly optimized structure. Globals are stored on disk within a series of data blocks; the size of each block (typically 8KB) is determined when the physical database is created. Cach maintains a sophisticated B-tree-like structure that uses a set of pointer blocks to link together related data blocks. Within data blocks, globals are stored sequentially

Routines
routine is the unit of execution in a Cach server. Routines are portable to all platforms supported by Cach and automatically shareable across a Cach environment

Create a Project
First, create a new project named Phone Book to manage the source files for the application, as follows: 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). 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.

 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.

Creating a class
Defining a New Class You can define this new Person class using Studio's New Class wizard by following these steps: Start the New Class wizard by selecting File > New > General tab. Select Cach Class Definition and click OK. On the first page of the New Class wizard, enter a package name, PhoneBook, a class name, Person, and click Next. 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 { }

Adding Properties
Add the Name and PhoneNumber properties to the definition of the Person class with the New Property wizard as follows: Select Class > Add > New Property to start the New Property wizard. 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; }

 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; }

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.

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: Click the Class Inspector and view Class keywords (make the left column header of the inspector display the word Class) In the Inspector, double-click the keyword Description. This opens an editor in which you can enter a description for your class, such as the following: Click OK when you are finished. Save your class and view the documentation again.

Introduction to Management Portal

There are four types of users for the portal Security Manager -View and edit list of users, roles, and other security tasks. Manager -Change system configuration and define backup sets. Operator - View system status pages and perform backups. Explorer (public user)- View home page, view classes, routines, and globals, and use SQL pages, provided the user has access to the appropriate resources

Portal Title Bar

The left side of the title bar displays the following information: Page name displays the name of the current portal page Licensee displays the value of the Customer Name field in the cache.key file Beneath the InterSystems logo are the following links: Home brings you to the System Management Portal [Home] page About displays system overview information Help opens the online documentation at an appropriate topic

 Feedback opens the Feedback page, which allows you to report problems or make enhancement requests specific to the SMP Help opens the online documentation at an appropriate topic Logout brings you to the Login page of the portal The upper right corner of the title bar displays the following information: Server name the name of the server running Cach Instance name the name of the Cach instance running on the server User name the name of the user logged into the portal

functional areas
The portal is divided into three functional areas: System Administration System administration tasks Data Management Database management tasks Operations System operation tasks

Introduction to Management Portal

System Administration Menu Configuration Security Management Licencing Database Encryption

Configuration
Cach configuration is composed of system configuration information, namespaces, databases, operator task configurations, network connections, and other advanced settings.

Memory and Startup Settings

You can choose whether to configure memory automatically or manually. If you choose Automatically, the system allocates the amount of memory best suited to Cach given the available memory. If you choose Manually, you can specify how global buffer pool memory is allocated:
Memory allocated for Routine Cache (MB) System memory allocated and used for caching server code. Memory allocated for 2KB Database Cache (MB) System memory allocated and used for buffering data for legacy 2KB databases. Memory allocated for 8KB Database Cache (MB) System memory allocated and used for buffering data for 8KB databases

See the Memory Configuration section for details.

 You can set your Cach instance to start automatically when the system starts by selecting the Auto-start on System Boot check box. If you select the Enable Long Strings check box, Cach allocates a large string stack to handle long strings for each process. You can change the Superserver Port Number (TCP port used to accept incoming client requests) for this Cach instance. Click Save to save your modifications; restart Cach to activate them.

Namespaces
Cach comes with the following predefined namespaces: %SYS System management information and utilities. DOCBOOK Documentation. SAMPLES Sample code and applications. USER Empty at installation. Typically used for application development

Perform the following procedures for configuring namespaces

Create a Namespace Modify Default Database Mapping Add Global, Routine, and Package Mapping to a Namespace Delete a Namespace

Create New Namespace

Enter a Name for the namespace. Do not specify the following reserved system names: BIN, BROKER, DOCBOOK, DOCUMATIC, SYS. Select an existing database for the default mapping of this namespace, or click Create New Database Select the Create a default CSP application for this namespace check box if you are creating a CSP application that accesses this namespace. You can also Copy namespace mappings from an existing namespace. After entering the required information, click Save to add your namespace to the configuration

Modify Default Database Mapping

You can change the database to which your namespace is mapped without restarting Cach: Navigate to the [Home] > [Configuration] > [Namespaces] page to see a list of defined namespaces. Click Edit in the row of the namespace you wish to modify. Choose the Default Database for Globals, the Default Database for Routines, and the Default Database for Temporary Storage from the list of defined databases. Click Save

 In addition to having access to the globals and routines in the mapped database, you can also map globals, routines, and class packages from other databases on the same or different systems. This allows simple references to data which can exist anywhere and is the primary feature of a namespace. Click the appropriate choice to begin mapping: Global Mappings Routine Mappings Package Mappings Mapping Data to All Namespaces

 Sample Namespace Mapping Data and programs are stored in Cach databases, the physical storage locations, and referred to by namespaces, the logical references.

Delete a Namespace
You can delete a namespace, including all mappings associated with it: Navigate to the [Home] > [Configuration] > [Namespaces] page, and click Delete in the row of the namespace you want to delete. On the Delete Namespaces page, if you want to delete the CSP pages from the physical path, select the check box. To delete the namespace and associated mappings, click Perform Action Now.

Configuring Databases
A database is a cache.dat file you create using the Database Wizard. A Cach database holds data in multidimensional arrays called globals and executable content called routines, as well as class and table definitions. Globals and routines encompass such things as methods, classes, Web pages (CSP and HTML), SQL, BASIC, and JavaScript files. Cach databases dynamically expand as needed, though you can set a maximum limit. Cach automatically mounts the databases, which can grow to be 32 terabytes. Cach provides wizards for both local and remote database creation

Journal
Each instance of Cach keeps a journal. The journal is a set of files that keeps a timesequenced log of changes that have been made to the databases since the last backup. Cach transaction processing works with journaling to maintain the logical integrity of data. Backups and journaling are daily operations that allow you to recreate your database

Class Type
Class MyApp.MyClass [ClassType = persistent] { } datatype the class is a datatype class used to represent a literal value. persistent the class represents data to be stored within the database. serial the class represents data to be stored (in its serialized state) within another persistent object. stream the class represents streaming data. view the class is used to define an SQL view (see the ViewQuery keyword). An empty string, which indicates that this class has no specific type. Simple registered objects as well as abstract classes typically do not specify a class type.

 Specifies how this class is to be used. The class compiler uses the ClassType keyword to determine how to compile a class. For example, if ClassType is persistent, the class compiler additionally invokes the storage compiler to generate persistence code for a class. Unless explicitly defined, the value of ClassType is either the default value (NULL) or it is inherited from the primary superclass.

Types of Classes
Classes are divided into data type classes and object classes. Data type classes represent literal values such as strings, integers, and dates Data type classes are used to create literal properties of other objects. They do not have properties and cannot be instantiated

Object classes
Object classes may have properties and can be instantiated. Object classes are further divided, according to their database behavior, into transient objects, persistent objects, and serial objects. A transient object (derived directly from the %RegisteredObject class) has no storage behavior; it exists only in memory.

 Instantiations of classes derived from %RegisteredObject are known as registered or transient objects. These objects have a full set of built-in methods for controlling their in-memory behavior.

Persistent Object Classes

Instantiations of classes derived from %Persistent are known as persistent objects these objects are registered objects that inherit from the %Persistent class. Persistent objects have the ability to store themselves into the database. lazy loading : Loading a persistent object into memory from the database does not load any other objects that it refers to. As soon as a referenced object is referred to, however, it is automatically brought into memory; this is known as swizzling or lazy loading .

Serial Object Classes

Instantiations of classes derived from %SerialObject are known as serial or embeddable objects these objects are registered objects that inherit from the %SerialObject class. These objects can exist independently in memory, but, when stored to the database, can only exist as embedded within a persistent object.

Embedded objects
Embedded objects have different in-memory and ondisk representations. In memory, an embedded object is represented as a separate object. The in-memory value of an embedded object attribute is an OREF that refers to the objects in-memory representation. On disk, an embedded object property is stored as part of its containing object. A serial object has no separate identity (OID) and cannot be referred to by other objects. The values of the embedded objects properties are serialized and stored along with all of the other object attributes.

Address class
Class MyApp.Address Extends %SerialObject { Property Street As %String(MAXLEN=80); Property City As %String(MINLEN=3); Property State As %String(MINLEN=2); } Once defined, the Address class can be used as an embedded object attribute for a persistent object class such as Patient:

 Class MyApp.Patient Extends %Persistent { Property Name As %String; Property Home As Address; }

Data Type Classes

Data type classes define and control literal values. Unlike object classes, data types do not have any independent identity and can never be explicitly instantiated. Instead, they exist only as properties of the objects that contain them. Data type classes cannot contain properties. A data type is a class with its ClassType keyword set to datatype.

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.

 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 XMLenabled; 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.

 Zen DataModel-(optional) If checked, the class includes extends %ZEN.DataModel.Adaptor.

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)

 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.

Adding Properties to a Class

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

Using Class Editor

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

Using New Property Wizard

To open the New Property wizard, select Class > Add > New Property . Alternatively, rightclick 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. Students task: Explore Adding properties to a class

Class Compilation
Cach class definitions are compiled into application routines by the Cach class compiler. Classes cannot be used in an application before they are compiled. The Cach class compiler differs from the compilers available with other programming languages, such as C++ or Java, in two significant ways: first, the results of compilation are placed into a shared repository (database), not a file system. Second, it automatically provides support for persistent classes.

class compiler does the following:

It generates a list of dependencies Depending on the compile options used, any dependencies that have been modified since last being compiled will also be compiled. It resolves inheritance it determines which methods, properties, and other class members are inherited from superclasses. It stores this inheritance information into the class dictionary for later reference. For persistent and serial classes, it determines the storage structure needed to store objects in the database and creates the necessary runtime information needed for the SQL representation of the class. It executes any method generators defined (or inherited) by the class. It creates one or more routines that contain the runtime code for the class. The class compiler groups methods according to language (Cach ObjectScript and Basic) and generates separate routines, each containing methods of one language or the other. It compiles all of the generated routines into executable code. It creates a class descriptor. This is a special data structure (stored as a routine) that contains all the runtime dispatch information needed to support a class (names of properties, locations of methods, and so on).

Class Compilation
several ways to invoke the class compiler: From within Cach Studio using the option in the Build menu. From the Cach command line (in the Cach Terminal) using the Compile method of the %SYSTEM.OBJ object: Do $System.OBJ.Compile("MyApp.MyClass")

Unified Data Architecture

This table summarizes the mapping between the basic object-oriented features of Cach Objects and the relational features of SQL Tables. Unified Data Architecture Cach Objects SQL Tables Package Schema Class Table Object Instance Table Row Property Table Column Method Stored Procedure Relationship Foreign Key Embedded Object Column Subset