Copyrights

Installation on Windows
Installation on Linux / FreeBSD
Installation on Mac OSX
Routine Editor, Global Editor and Control Center
How to Create and Compile a Routine
Hello, World!
Running a Routine
Debugging a Routine
How to Export and Import Routines
Development and Deploying of Matrix

Debugging a Routine

MiniM Debugging facility was embedded into MiniM Routine Editor. MiniMono Routine Editor has not this feature.

MiniM debugging protocol is protocol between MiniM process who is a debugger and common context of the MiniM Database Server and between debugger process and debugged process and does not leave server side. Debugger process is a server-side process of MiniM Routine Editor. In ordinal state it is ordinal rocess and in debugging state Routine Editor can switch his own process to debugger state. And, of course, MiniM Routine Editor can leave debugging state.

One debugger process can interact to only one debugging process.

MiniMono has some differences in architecture and have only one MUMPS job, so cannot run and debug any other MUMPS job.

Debugger process can attach to available (except self) MiniM process on the same MiniM instance, or turn server into special waiting state - when next MUMPS job will be run, server will stop this new process at first execution point and notify debugger process about successful attaching to new process. After this debugger process leave common waiting state of MiniM Database Server and will interact only with newly runned debugged process. Of course, only one debugger process can be in waiting state, but in debugging state can be several pairs of processes. And, developers must this understand, that debugged process can be debugged only by one debugger process.

Through the debugging MiniM Routine Editor interacts with own server-side MiniM process (own MUMPS job) and this job interacts with debugging process (other MUMPS job).

Debugger can deliver to debugged process set of breakpoints and queries about internal state of system variables and expressions. Debugged process accepts queries and return answers.

MiniM Routine Editor can be connected to any MiniM instance including different operating system and processor architecture.

To illustrate debugging of the MUMPS job, we will use special demo routine. First of all, connect MiniM Routine Editor to the MiniM Database Server and create this demo routine:

debugroutine
 w "This is routine to debug.",!
 n a=123,i
 w a,!
 f i=1:1:3 d
 . w $$func(i),!
 w "End of code.",!
 q
func(param)
 n ret=param+$i(query)
 q ret

In MiniM Routine Editor for Windows this looks like this:

At the next step click menu command Debug | Attach to Process:

This command will ask about way of attaching:

Now MiniM Routine Editor cann attach only by two ways: 1) to one of already running MUMPS job or to newly created, and here first alternative is attaching to one of available MiniM process. In this list of processes MiniM Routine Editor removes one, own server-side process.

All other alternatives here are attaching to newly created MiniM process:

Attach to Next MiniM Job

Debugger process will be pointed to any newly created MiniM process independently of the way this process will be run. At this option developer must run process self as hi needed.

Run MiniM Console with Option and Debug

The same as above, but MiniM Routine Editor will run MiniM process in console mode with optional parameters and attach to this process. Developer must understand that this way can work only if MiniM Routine Editor is from the same instance as currently used MiniM Database Server, becouse newly created process will be run locally.

Run MiniM Job with Option and Debug

The same as attaching to next job, but new job will be run by the JOB command with options.

Developer can debug server side of developed MUMPS application as is, and run MUMPS code from MWA, telnet, application based on the MiniM Server Connect or any other connection method will be developed in the future.

In the MiniM Database Server debugging is not dependent of special debugging information like in many other development tools where application must be compiled with debug info to enable debugging. Debugger in the MiniM Database Server requires only source intermediate code and does not ann to produced compiled bytecode any special debugging sections.

Let us select second option and run new MiniM process manually. MiniM Routine Editor at this step turn his server-side process into the debugger state and into waiting state for common MiniM context to wait next running job. Waiting screen will appear, and this screen may looks different in different operating systems:

After this we simply run new MiniM console manually:

Debugger process will automatically attached to this new process and stops them at first execution point. While debugged process in stopping state, he only waits commands from the debugger process and does not have any reactions to user input.

MiniM Routine Editor indicates this special state by showing warning:

Before developer continue execution, he can analize current execution state, change breakpoint set and watches list. Debugged process will continue only after Debug | Run command (F9).

MiniM Routine Editor in the debugging state indicates by blue dots on the gutter at left side of each editor all possible execution lines. In real MUMPS is line-oriented interpreter and execution can be passed to any existing line of any routine. Debugged process can execute only bytecode of compiled routines and this bytecode corresponds to intermediate code, so MiniM Routine Editor shows blue dots only in INT routines. Anyway developer can open and close routine editors, change breakpoints set, this breakpoints set changes will be delivered into debugger MUMPS job and still exists independently of open this routine or not. To prevent changes in source code after turning into debugging state MiniM Routine Editor switches all opened routine editors into ReadOnly state:

To set or remove breakpoint at line in routine, select routine and line and click command Debug | Toggle Breakpoint (F5). All lines with breakpoints MiniM Routine Editor highlights by red color. To illustrate debugging we toggle breakpoints at the following lines:

Watches are special expressions, mainly local variables, for viewing and understanding of currently debugged process. To add new watch click command Debug | Add Watch (Ctrl+F5):

If current active routine editor has selected text, this selection will be used instead of watch expression, otherwize MiniM Routine Editor asks about watch expression:

Different viewing styles are offered for different expression contents - list structures while view as is are not man-readable.

Some added watches can be the following:

Watch list can be updated only when debugged process is in stopped state and does not evaluates when debugged process runs.

After preparing debugging context we run debugged process by selecting command Debug | Run (F9). Other ways to run process are:

Step Over (F8)

This command runs debugged process to next line with skipping calling subroutines and functions which require new stack level. Execution goes over calls, FOR commands and others.

Step Into (F7)

This command runs debugged process to next line including calling subroutines and functions which require new stack level. Executions steps into subroutines, functions, DO commands.

Run to Cursor (F4)

This command runs debugged process until selected line or any other available breakpoint will reached.

Debug command Run (F9) runs debugged process until any available breakpoint will reached. We call this command and debugged process continues execution. Our MiniM console still wait input commands, we enter run debugged routine:

d ^debugroutine

Debugged process executes routine and stops at first breakpoint. MiniM Routine Editor updates watches list and highlights current execution line by blue color:

Next press F8 to execute one debugging step (step over) and process continues execution to one line:

Next press F8 to execute debugging step (step over) and debugged process executes current line with writing variable:

To view expression values see the watches list or simply select text in editor and point mouse to this selection. MiniM Routine Editor implements tooltip expression evaluation and will show in popup tooltip value of evaluated expression, of course, if this is valud MUMPS expression. MUMPS language is very powerful, however not all of character sequences are valid in MUMPS syntax.

Or simply point mouse pointer to character sequence which can be valid local variable name - this works as a magnifier: if mouse points to valid local variable, tooltip show expression value for this variable.

Note that specially for debugger MiniM supports special non-standard stack showing for zero stack level to indicate the way how this process was run. In our example top of stack was shown as XECUTE + CONSOLE. Other running methods can have other values.

Currently our code stay on the line which calls dotted code for the DO command. If we select command F8 (Step Over), debugger will continue execution until any dotted commands will be executed and execution continues at the line after current and on the same stack level. If we select comman F7 (Step Into), debugger will continue execution to any other line including new stack level. In our case we have breakpoint on the dotted line and this breakpoint must be reached anyway.

To step into body of the FOR command made by the DO command, we execute command F7:

Here we select expression of

i

$$func(i)

and point mouse to evaluate them:

Function $$func has side effect on $i(query) and on each evaluation variable "query" have new expression, this show that the MiniM Debugger is live debugger and evaluates real expressions in real process without emulations or imitations, and debugged process works as is:

After executing step-by-step lines of MUMPS commands we execute in the debugging process lines of debugged subroutine:

To switch debugged process to free execution state we can run Debug | Run (F9) command and debugged process will continue execution. But after this debugged process still in the debugging state and will stop on any existing breakpoint and debugger still in debugging state and will wait any notifications.

To end debugging MiniM Routine Editor can detach from debugged process by selecting command Debug | Detach:

After this command debugged process continues execution as is and debugger process turn out of the debug state.

Command Debug | Reset (Ctrl+F2) terminates debugged process independently of is debugged process in stopping state or in running state. Debugged process terminates and debugger process turn out of the debug state.

Command Debug | Pause is active only when debugged process stay in free running state and can stop execution at current execution point. This can break, for example, unpredictable cycles to view real execution context.

After end of debugging and detaching MniM Routine Editor continues execution in ordinal state and can be pointed to new MiniM process to debug. Debugged process forgets all breakpoints was used. MiniM Routine Editor stores breakpoints while running and on attaching to the next process will deliver breakpoints to this process.