Caché Programming Orientation Guide
Development Tools
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter introduces the tools you commonly use as a developer. It discusses the following:

Management Portal
The Management Portal is a browser-based tool that you can use to manage data and to configure Caché. System administrators use it later for other tasks.
Accessing the Portal
You can start the Management Portal in the following ways:
Important:
Microsoft Windows 2003 Users Trusted Site Security Setting — The first time you visit the Management Portal, you may receive a warning about the web site being blocked. When prompted, add the site to the Trusted sites zone. InterSystems also recommends you allow session cookies for portal procedures to function properly.
Enter a Caché username and password if prompted.
The chapter Useful Skills to Learn describes many tasks you perform within this tool.
Caché Studio
Caché Studio is a tool that you use to build and debug code in all languages that Caché supports. It runs on Windows-based operating systems. It can connect to any Caché server (compatible with the current version of Caché Studio) regardless of the platform and operating system of the server.
Starting Studio
To start Studio, select the InterSystems Launcher and then select Studio. Enter a Caché username and password if prompted.
Or use other options on the InterSystems Launcher to access remote systems. For details and additional options, see Using the Caché Studio.
You can open multiple Studios at the same time, which is useful if you are working in multiple namespaces.
Orientation
In Studio, you work within a single namespace at one time. To choose a namespace, select File > Change Namespace or press F4.
Studio displays all code to which this namespace has access; see What Is Accessible in Your Namespace,” earlier in this book. You cannot edit code that is stored in CACHELIB (which is read-only). Some classes provided by InterSystems are shipped in “deployed” mode, and you cannot see their internal details.
Documents (“Files”)
Studio manages units of code that it refers to as files; more accurately, they are simply documents, most of which are stored in the Caché databases used by the namespace that you are currently viewing. The Workspace window. displays names of documents and groups them as follows:
Studio provides syntax coloring and checking for each of these kinds of documents.
If you have multiple Studios at the same time, you can drag a document from one Studio to another. This action imports the document into the other Studio (which is typically using a different namespace).
Integration with Source Control
All routines and class definitions are stored in a Caché database, which is different from most development toolkits. Studio provides a set of source control hooks which InterSystems developers use and which you can also use. See Using Caché Studio.
When you have these configured for your source control system, you can work with other developers like this:
You might not need to use these source control hooks immediately, but you should be aware of them.
Other Environmental Options
It is useful to check the options used in Studio to see if they meet your current needs. Select Tools > Options. Some of the options include:
Terminal
The Terminal is a command-line interface for entering Caché commands and displaying current values. It is useful during learning, development, and debugging.
Starting the Terminal
To start the Terminal and use the local database, select the InterSystems Launcher and then select Terminal.
Orientation
In the Terminal, you work within a single namespace at one time. The prompt displayed in this window indicates the namespace in which you are currently working. For example:
USER>
To change to a new namespace, use the ZNSPACE command (which has a short form of ZN):
USER>ZN "SAMPLES"

SAMPLES>
Environmental Options
You may find it useful to set up the Terminal for yourself as follows:
Tip:
If you have multiple instances of Caché running on your machine, it is useful to customize the colors and fonts for the Terminal so that you can easily distinguish different Terminal windows. For example:
Using the Terminal
In the Terminal, you can enter most Caché commands (and you do not need to include a space at the start of a line). For example:
d ^myroutine
set dirname = "c:\test"
set obj=##class(Test.MyClass).%New()
write obj.Prop1
You cannot use labels, multiline constructs, or macros.
When you exit the Terminal, the system closes any open files and stops any foreground execution.
Common Keyboard Accelerators
It is useful to remember the basic keyboard accelerators:
System Qualifiers and Flags
There are system qualifiers and flags that affect the import of external sources into Caché, the compilation process, and the export of code to external destinations. These settings are saved in a system global for each namespace, but you can provide overrides as follows:
Viewing the Current Default Qualifiers and Flags
To see the current flags and qualifiers used in a namespace, use the following commands:
  DO $system.OBJ.ShowFlags()
 
and
  DO $system.OBJ.ShowQualifiers()
 
These methods also display help information for the flags and qualifiers.
Changing the Defaults
You can change the defaults for the namespace in which you are working. To do so, use $system.OBJ.SetFlags() and $system.OBJ.SetQualifiers(). For example:
 DO $system.OBJ.SetFlags("ck")  
 DO $SYSTEM.OBJ.SetQualifiers("/skipstorage")
Key Flags
The following table lists a few key flags, to highlight them and to give you a sense of what the flags do:
Flag Meaning Default
b Include subclasses and classes that reference the current class in SQL usage.
c Compile the class definitions after loading.
e Delete extent.
k Keep source. When this flag is set, source code of generated routines will be kept.
l Lock classes while compiling. X
r Recursive. Compile all the classes that are dependency predecessors.
u Update only. Skip compilation of classes that are already up-to-date.
Historical Note
Flags have been available for longer. They were modeled on UNIX® command-line parameters and thus are one- or two-character sequences. The qualifiers were added later, as a richer, more extensible set of controls. To preserve backward compatibility, the flag mechanism remains fully supported. In addition, there is an existing qualifier to match each existing flag, and you can use the two in the same specifier.
InterSystems Classes and Routines
In addition to the basic classes introduced earlier (such as %RegisteredObject and %Persistent), Caché provides a wide set of useful classes that can reduce your development time if you choose to use them. For example, there are classes you can use for tasks such as these:
Caché also provides routines for specific purposes (typically debugging or management), as well as language bindings and other tools. To find tools for a particular purpose, see the InterSystems Programming Tools Index.
InterSystems Class Reference (Documatic)
Caché provides a set of web pages called the InterSystems Class Reference or (informally) Documatic. These pages provide information on all classes provided by InterSystems, as well as all classes you create. The reference information shows the definitions of all class members, apart from their actual implementations. That is, you can see method signatures but not their internal definitions. It includes links between elements so that you can rapidly follow the logic of the code; in some cases, this is quicker than using Studio. There is also a search option.
Tip:
To locate classes quickly, see the InterSystems Programming Tools Index. This book is organized into high-level topics of interest to programmers and provides an extensive set of links to specific classes in the InterSystems Class Reference.
Accessing the InterSystems Class Reference
To view the InterSystems Class Reference, do any of the following:
A Quick Look at the InterSystems Class Reference
Note:
In these examples, to prevent confusion when you are reading this book online, the InterSystems Class Reference is shown with a gray background instead of the default color, which is white.
The following shows the left area, which you use for overall navigation:
Here you can do the following:
The next picture shows the reference page for %Library.String:
Notice the following:
The lower area of the reference page shows details for the class members as in the following example:
If you select the links in the method signature or in the comments, the system displays the referenced class.
Tools for Debugging
This section summarizes the main tools for debugging in Caché.
Also see the chapter Command-line Routine Debugging in Using Caché ObjectScript, which lists some additional tools.
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 either of the following ways:
For details, see Using the Studio Debugger in Using Caché Studio.
ZBREAK
Sometimes you have better control if you perform command-line debugging with the Caché Debugger and the ZBREAK command.
The Caché Debugger enables you to run debugging commands as if they were directly contained in your routine code. When you run the code, you can issue commands to test the conditions and the flow of processing within your application. Its major capabilities are:
For details, see Debugging with the Caché Debugger in Using Caché ObjectScript.
^%STACK
The ^%STACK routine lets you examine the process execution stack. You can use it to:
For details, see Using %STACK to Display the Stack in Using Caché ObjectScript.
Trace Statements
As with any programming language, you can edit the code to include statements that generate output about the current state of any variables of interest. In other languages, you might write output to the current device or print to a file, and you can do these things in Caché if desired.
Caché provides an alternative: set nodes of your own global. Use the $INCREMENT function to create a set of nodes that have integer keys. For example:
 if (myval=mytestval) {
    //do stuff
    set ^CacheTempUserMyTrace($increment(^CacheTempUserMyTrace))="main branch"
    } else {
        //do other stuff
        set ^CacheTempUserMyTrace($increment(^CacheTempUserMyTrace))="else branch"
        }
Another possibility is as follows:
 set ^CacheTempUserMyTrace($increment(^CacheTempUserMyTrace))=$LISTBUILD("message",data)
For your global, use a name of the form ^CacheTempUser*, which is written to the CACHETEMP database. Then if there is a transaction that gets rolled back, your global is not rolled back and thus contains an accurate record of the sequence of events.
Audit Log
When debugging code, sometimes it is useful to enable auditing and to view the audit log, if you have access to this administrative tool.
Caché allows you to monitor events and add entries to the audit database when those events occur. Auditable events fall into two categories:
For information on enabling auditing and viewing the audit log, see the chapter Auditing in the Caché Security Administration Guide.
System Logs
The system manager’s directory, typically installdir\mgr, contains several log files that may be helpful in debugging, including the console log (cconsole.log), System Monitor log (SystemMonitor.log), and initialization log (cboot.log). For information about these log files, see Monitoring Log Files in the Caché Monitoring Guide.
For More Information
For more information on the topics covered in this chapter, see the following: