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 InterSystems IRIS
Overview
The 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 ObjectScript routines, or to start routines for debugging. In
either case, the user must:
Start a target process, specifying what routine it is to
execute (optional)
Attach to the target process
Issue commands to the target process to control its execution
Any process
executing routines may be attached to by a user
with suitable privileges.
Debugging methods are provided
which allow the user to:
Attach to the process and put it in break mode
Control execution (break, step, step into, step out, continue)
Set and clear breakpoints and watchpoints
View current location and stack information
View and set variables, evaluate expressions, and execute COS
commands
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.
Terminals
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:
(Local platform) Start the cterm via Cterm(),
using the output port information returned from StartTargetRemote()
(Remote platform) Attach the target stub via DebugTarget()
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.
private method %OnClose() as %Status [ Language = objectscript ]
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 %RawString = "") as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
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 [ Language = objectscript ]
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 [ Language = objectscript ]
method DBGCommand(cmd As %String, issys As %Integer = 0) as %Integer [ Language = objectscript ]
Perform a debug command.
classmethod DebugStub(pWriteOutput) [ Language = objectscript ]
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 [ Language = objectscript ]
method DisableWatchpoint(variable As %String, counter As %Integer = 0) as %Integer [ Language = objectscript ]
method Eval(expr As %String = "", ByRef result As %String) as %Integer [ Language = objectscript ]
Evaluate and return the value of expression
expr within the target process.
method EvalOref(oref As %String = "", ByRef vararray As %Binary) as %Integer [ Language = objectscript ]
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 [ Language = objectscript ]
Gets the value of a variable
method Go() as %Integer [ Language = objectscript ]
Continue the current process
method GoTo(tag As %String) as %Integer [ Language = objectscript ]
Continue the current process at tag
method Interrupt() as %Integer [ Language = objectscript ]
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 [ Language = objectscript ]
Return true if the target is in break mode.
method Line() as %Integer [ Language = objectscript ]
method LineIn() as %Integer [ Language = objectscript ]
method LineOut() as %Integer [ Language = objectscript ]
method LocalIO(port As %Integer, address As %String = "127.0.0.1") as %Boolean [ Language = objectscript ]
method RemoveBreakpoint(routine As %String, offset As %Integer) as %Integer [ Language = objectscript ]
method RemoveWatchpoint(variable As %String) as %Integer [ Language = objectscript ]
method Resume() as %Integer [ Language = objectscript ]
Continue the current process without stepping on return
method SetBreakpoint(routine As %String, offset As %Integer, condition As %String = "") as %Integer [ Language = objectscript ]
method SetValue(variable As %String = "", value As %String = "") as %Integer [ Language = objectscript ]
Sets a variable to a value.
method SetWatchpoint(variable As %String, condition As %String = "") as %Integer [ Language = objectscript ]
