This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

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)

Method Inventory (Including Private)

Properties (Including Private)

property Attached as %Boolean [ InitialExpression = 0 ];
Flag indicating whether we are Attached to a target.
Property methods: AttachedDisplayToLogical(), AttachedGet(), AttachedIsValid(), AttachedLogicalToDisplay(), AttachedNormalize(), AttachedSet()
property CmdId as %String;
Command ID of target process. Target waits for commands on this Event
Property methods: CmdIdDisplayToLogical(), CmdIdGet(), CmdIdIsValid(), CmdIdLogicalToDisplay(), CmdIdLogicalToOdbc(), CmdIdNormalize(), CmdIdSet()
property DebId as %String (TRUNCATE = 1);
Event id of this debugger instance
Property methods: DebIdDisplayToLogical(), DebIdGet(), DebIdIsValid(), DebIdLogicalToDisplay(), DebIdLogicalToOdbc(), DebIdNormalize(), DebIdSet()
property Dev as %String (TRUNCATE = 1);
Device for i/o redirecttion
Property methods: DevDisplayToLogical(), DevGet(), DevIsValid(), DevLogicalToDisplay(), DevLogicalToOdbc(), DevNormalize(), DevOpenDisplayToLogical(), DevOpenGet(), DevOpenIsValid(), DevOpenLogicalToDisplay(), DevOpenNormalize(), DevOpenSet(), DevSet()
property DevOpen as %Boolean [ InitialExpression = 0 ];
Flag indicating we have attempted to open an i/o device
Property methods: DevOpenDisplayToLogical(), DevOpenGet(), DevOpenIsValid(), DevOpenLogicalToDisplay(), DevOpenNormalize(), DevOpenSet()
property Job as %Integer;
Job number of target process
Property methods: JobDisplayToLogical(), JobGet(), JobIsValid(), JobLogicalToDisplay(), JobNormalize(), JobSet()
property Killtarget as %Boolean [ InitialExpression = 0 ];
Kill target on disconnect flag
Property methods: KilltargetDisplayToLogical(), KilltargetGet(), KilltargetIsValid(), KilltargetLogicalToDisplay(), KilltargetNormalize(), KilltargetSet()
property Location as %String (TRUNCATE = 0);
Current Location info for target process
Property methods: LocationDisplayToLogical(), LocationGet(), LocationIsValid(), LocationLogicalToDisplay(), LocationLogicalToOdbc(), LocationNormalize(), LocationSet()
property OutputToDebugDevice [ InitialExpression = 1 ];
This property can be used to disable outputing of device data by setting the value to 0
Property methods: OutputToDebugDeviceDisplayToLogical(), OutputToDebugDeviceGet(), OutputToDebugDeviceIsValid(), OutputToDebugDeviceLogicalToDisplay(), OutputToDebugDeviceLogicalToOdbc(), OutputToDebugDeviceNormalize(), OutputToDebugDeviceSet()
property Pid as %String (TRUNCATE = 1);
Process ID of target process
Property methods: PidDisplayToLogical(), PidGet(), PidIsValid(), PidLogicalToDisplay(), PidLogicalToOdbc(), PidNormalize(), PidSet()
property RsetVars as %ResultSet [ InitialExpression = 0 ];
Result set for Variables
Property methods: RsetVarsGet(), RsetVarsGetSwizzled(), RsetVarsIsValid(), RsetVarsNewObject(), RsetVarsSet()
property Sid as %String (TRUNCATE = 1);
Session ID of target process. Target signals on this Event.
Property methods: SidDisplayToLogical(), SidGet(), SidIsValid(), SidLogicalToDisplay(), SidLogicalToOdbc(), SidNormalize(), SidSet()
property Stack as %String (TRUNCATE = 0);
Current Stack info for target process
Property methods: StackDisplayToLogical(), StackGet(), StackIsValid(), StackLogicalToDisplay(), StackLogicalToOdbc(), StackNormalize(), StackSet(), StackVars()
property Stopped as %Boolean [ InitialExpression = 0 ];
Flag indicating if target is stopped
Property methods: StoppedDisplayToLogical(), StoppedGet(), StoppedIsValid(), StoppedLogicalToDisplay(), StoppedNormalize(), StoppedSet()
property atelierTrace as %Boolean [ InitialExpression = 0 ];
Set to non-zero if running under Atelier debugger
-1 means no trace
>0 is the Atelier trace node
Property methods: atelierTraceDisplayToLogical(), atelierTraceGet(), atelierTraceIsValid(), atelierTraceLogicalToDisplay(), atelierTraceNormalize(), atelierTraceSet()
property trace as %Boolean [ InitialExpression = 0 ];
Property methods: traceDisplayToLogical(), traceGet(), traceIsValid(), traceLogicalToDisplay(), traceNormalize(), traceSet()

Methods (Including Private)

private method %OnClose() as %Status
Inherited description: This callback method is invoked by the %Close() method to provide notification that the current object is being closed.

The return value of this method is ignored.

private method %OnNew(initval As %CacheString = "") as %Status
Inherited description: This callback method is invoked by the %New() method to provide notification that a new instance of an object is being created.

If this method returns an error then the object will not be created.

It is passed the arguments provided in the %New call. When customizing this method, override the arguments with whatever variables and types you expect to receive from %New(). For example, if you're going to call %New, passing 2 arguments, %OnNew's signature could be:

Method %OnNew(dob as %Date = "", name as %Name = "") as %Status If instead of returning a %Status code this returns an oref and this oref is a subclass of the current class then this oref will be the one returned to the caller of %New method.

method Attach(pid As %String = "") as %Integer
Attach to another process having process id of pid.

Fails if already attached (use Unattach() first),or if pid is invalid.

On successful completion, process is attached and a break issued. The process will be in break mode upon completion of its current operation.

method Break() as %Integer
Send a BREAK to the target process.

On successful completion, a break has been issued. The process will be in break mode upon completion of its current operation.

method ClearBreakpoints() as %Integer
method DBGCommand(cmd As %String, issys As %Integer = 0) as %Integer
Perform a debug command.
classmethod DebugStub(pWriteOutput)
System stub used by the debugger application

This class method is jobbed in order to start a target process.

The stub waits on the input event for the debugger to pass the name of the target routine to be executed.

When signalled, the stub then executes target routine

method DisableBreakpoint(routine As %String, offset As %Integer, counter As %Integer = 0) as %Integer
method DisableWatchpoint(variable As %String, counter As %Integer = 0) as %Integer
method Eval(expr As %String = "", ByRef result As %String) as %Integer
Evaluate and return the value of expression expr within the target process.
method EvalOref(oref As %String = "", ByRef vararray As %Binary) as %Integer
Evaluate and return the property/value pairs of variable which is an oref
method GetValue(Variable As %String = "", ByRef Value As %String, Lang As %Integer = 0) as %Integer
Gets the value of a variable
method Go() as %Integer
Continue the current process
method GoTo(tag As %String) as %Integer
Continue the current process at tag
method Interrupt() as %Integer
Interrupt the target process

The target process is sent a software interrupt. This causes the target to break. The next line of code will be executed when the target is resumed.

method IsStopped(timeout As %Integer = 1) as %Integer
Return true if the target is in break mode.
method Line() as %Integer
method LineIn() as %Integer
method LineOut() as %Integer
method LocalIO(port As %Integer, address As %String = "") as %Boolean
method RemoveBreakpoint(routine As %String, offset As %Integer) as %Integer
method RemoveWatchpoint(variable As %String) as %Integer
method Resume() as %Integer
Continue the current process without stepping on return
method SetBreakpoint(routine As %String, offset As %Integer, condition As %String = "") as %Integer
method SetValue(variable As %String = "", value As %String = "") as %Integer
Sets a variable to a value.
method SetWatchpoint(variable As %String, condition As %String = "") as %Integer
method StackVars(lev As %Integer, start As %String, ByRef vararray As %Binary) as %Integer
Get Stack info for target Show the call stack, state and variables using ^%STACK lev,start,.vararray,.next
method StartTarget(target As %String, pWriteOutput=1) as %Integer
Start a local debugging session on a new process. Job the cterm debug stub Start a cterm connected to the target Run DebugTarget to run the process

On exit from this routine, the target is in break mode waiting for a command

method Step() as %Integer
method StepIn() as %Integer
method StepOut() as %Integer
method Trace(pMsg As %String)
Log a trace if tracing enabled
method Unattach() as %Integer
Unattach from the current process, if any. Assumes the target has been stopped

Returns $$$OK if successful, $$$ERROR if nothing to detach from

method Write(data As %String) as %Integer
Write to the target process

Inherited Members

Inherited Methods (Including Private)

FeedbackOpens in a new window