Introduction to Studio
Studio offers features that help you develop applications rapidly, in a single, integrated environment including:
-
An editor in which to create
-
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 ObjectScript, Basic, or MultiValue
-
-
Integrated syntax coloring and syntax checking for 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.
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 Studio) regardless of what platform and operating system that server is using.
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
Studio is a standard Windows application. It uses windows to display and allow the editing of aspects. The main components of the Studio user interface are shown below:
![generated description: studiodiagram](images/gstd_studiodiagram.png)
-
Editors: Class Editor for editing class definitions, Routine Editor for editing routines and include files, and CSP Editor for editing CSP definition text.
-
Class Browser window: for viewing existing classes.
-
Workspace window: three tabs let you display: the contents of the current project, all open windows, or the content of the current namespace.
-
Class Inspector window: for viewing and modifying keywords in a class definition.
-
Watch window: displays variables.
-
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, Studio contains wizards and templates for assisting with common tasks. These include:
-
Find in Files window: displays a search window.
-
Output window: displays output from the Caché server (such as messages generated during class compilation).
-
Code Snippets window: for viewing and dragging user-created code snippets.
-
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.
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
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 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 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 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 %FloatOpens in a new tab (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:
-
cache—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 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.
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 Studio to create and edit CSP classes in the same way as you would work with any other class definitions.
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. 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
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
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, Studio only allows source-level debugging of INT (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:
-
%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_Bindings 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, 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.
-
For an instance with minimal security, all users, including UnknownUser, have all privileges and access to all namespaces. 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.
-
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.
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.BaseOpens in a new tab class and implement the callback methods that you want. You can specify which Source Control class Studio should use by navigating to System Administration > Configuration > Additional Settings > Source Control on the Management Portal.
Refer to the %Studio.SourceControl.BaseOpens in a new tab class and the “Using Studio Source Control Hooks” appendix for more details.