Using InterSystems Development Environments — Atelier and Studio
Introduction to Caché Studio
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Caché Studio offers features that help you develop applications rapidly, in a single, integrated environment including:

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é 2015.1 Studio can connect to a Caché 2015.1 (or earlier version) server. Caché 2014.1 Studio cannot connect to a Caché 2015.1 (or later) server. This applies also to maintenance releases. Example: Caché 2014.1.2 Studio can connect to a Caché 2014.1.1 (or earlier maintenance release or version) server. Caché 2014.1.0 Studio cannot connect to a Caché 2014.1.1 (or later maintenance release or version) server.
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:
Studio Components
  1. Editors: Class Editor for editing class definitions, Routine Editor for editing routines and include files, and CSP Editor for editing CSP definition text.
  2. Class Browser window: for viewing existing classes.
  3. Workspace window: three tabs let you display: the contents of the current project, all open windows, or the content of the current namespace.
  4. Class Inspector window: for viewing and modifying keywords in a class definition.
  5. Watch window: displays variables.
  6. Title Bar: displays ConnectionName/Namespace@UserName - ProjectName.prj – Studio – ActiveDocument. If the active document is maximized, the name shows in square brackets.
In addition to the windows displayed above, Caché Studio contains wizards and templates for assisting with common tasks. These include:
Running Studio from the Command Line
You can run Studio from the system's command line using the command Cstudio.exe (in the Caché bin directory). The command and its parameters are case-sensitive.
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].
/Namespace=User Connect to the User namespace. You must also define a server.
/Project=MyProject Open project MyProject. You must also define a server and a namespace.
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. You must also define a server and a namespace.
/pid=123 Attach to process. You must also define a server and a namespace.
/fastconnect=127.0.0.1[1972]:USER:_SYSTEM:SYS Connect without connection definition in registry using ip address[port]:USER:username:password
Projects
Caché Studio uses projects to organize application source code.
A project is a set of class definitions, CSP files, routines, and include files. 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 username).
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).
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 object 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.
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.
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
{

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

}
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) immediately 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.
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 ];
}
Methods
You can define a method in a class definition using the Method keyword:
Class MyApp.Student Extends Person
{
/// This method wastes <varname>count</varname> 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
}
Use the Language keyword to specify one of the following languages:
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.
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.
Routine Editor
Using the Routine Editor, you can directly create and edit the source for specific Caché routines in a syntax-coloring editor. You also use the Routine Editor to edit include files.
Multiple User Support
Caché Studio is an object-based, client/server application. The source files—class definitions, routines, include files, 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.
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.
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.”
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.
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:
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, described in the list below. To change the Studio authentication settings, use the Allowed Authentication Modes check boxes on the Edit Service page for the %Service_Bindings service.
Note:
Studio access may also be affected by any changes to default settings that have occurred since installation.
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] > [Source Control Settings] page of the Management Portal. (Navigate System Administration > Configuration > Advanced Settings > Source Control.)
Refer to the %Studio.SourceControl.Base class and the Using Studio Source Control Hooks appendix for more details.