Home > Class Reference > ENSLIB namespace > %Debugger.System


class %Debugger.System extends %Library.RegisteredObject

This class is used internally by InterSystems. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this class.

System Debugging in Caché

The Caché system debugger allows external debugging of processes via a set of debugging commands provided by the class %Debugger.System. The debugger may be used to attach to processes running Caché routines, or to start routines for debugging. In either case, the user must:

Any process executing Caché routines may be attached to by a user with suitable privileges.

Debugging methods are provided which allow the user to:

Commands may only be issued when the target is in break mode. Since the state of the target is uncertain following any debugger command, the method IsStopped() must be used to test if the process is in fact in break mode. After a process has been attached, this method must be called, and return successfully, following every debugger command, before another command may be issued. The exceptions are Unattach()(detach from a process and stop debugging), and Break() (break into a process which is executing under debugger control).

Location information is automatically returned whenever the process breaks. The property Location contains the raw location information. The methods GetOffset() and GetSource() may be used to obtain analysed location and source data.


Two terminal output windows may be started. One of the windows is started when processes are started by the debugger,and is the principle device for the process.

Another window may be started after any process is attached, which is the debug device for the process. All debugger output is displayed in this window.

Both of these windows are also available when debugging remote processes. In this case, the windows are started on the local platform.

Starting a routine

The Debugger provides a stub which is jobbed to create a debug process. This stub awaits debugger commands to open a terminal window, and execute the desired routine.

The method StartTarget(), which takes a routine name as an argument, uses this stub to begin debugging a routine. It jobs the stub to begin execution, starts the Cterm windows, attaches to the process, and signals what routine is to be run. Upon completion, the process is ready for debugging. Breakpoints may be set and the routine executed.

Attaching a process

Any process may be attached for debugging. The method Attach() takes a numeric process id as an argument. Upon successful completion, the target is ready to be debugged.

Remote Debugging

Remote and local debugging are identical, except for the sequence of commands required to open the Cterm windows. Since the Cterm windows are on the local platform, a separate %Debugger.System instance must be used on the local and remote platforms.

To start a process, the user follows this sequence:

Remember that upon successful completion of any command, the target may not be in break mode. The method IsStopped() must be explicitly invoked, and return a success code, before any new commands may be issued.

Property Inventory (Including Private)