DEBUG ["message string" | messageStringVariable]

When your Resampling Stats program is running in normal mode or is running at full speed in debug mode and encounters a DEBUG command, Statistics101 will print the message string to the Output Window, then enter its debug step mode and wait for you to continue debugging the program. At this point you can single-step through your program using the toolbar's Step button or the Run menu's Step item. You can also continue the program running at full speed from where it left off using the toolbar's Continue button or by selecting the Run menu's "Debug mode" item.

DEBUG commands can be placed anywhere in your Resampling Stats program. You can put as many DEBUG commands in your program as you need to debug it.

If you are already in Debug step mode, the DEBUG command has no effect when you step through it.

If you want to exit debug mode without running the program to completion, click on the Abort button or use the Run menu's "Abort" command.

If you want to have your program run until some condition occurs and then have it go into debug mode, you can use either of two subroutines that are available in the Statistics101 "lib" directory. The two subroutines are named DEBUG_AT and DEBUG_IF.

  • DEBUG_AT uses a counter and enters debug mode when the counter value becomes equal to that of a given variable. DEBUG_AT increments the counter automatically. Therefore if you use more than one invocation of DEBUG_AT, each should have its own counter.

  • DEBUG_IF uses a test and enters debug mode when the test evaluates to true.

You insert an invocation of either of the subroutines at points in your program where you want to enter debug mode when the desired condition occurs. After you complete debugging, you remove the subroutine invocations. Here are two schematic examples using the subroutines:

INCLUDE "lib/debugCommands.txt"
. . .
FOREACH n 1,1000
   . . .
   DEBUG_AT 25 n
   . . .
END
...

The above example will enter debug mode when n becomes equal to 25.

The next example uses DEBUG_IF in two places in the same loop to enter debug mode when two different conditions are satisfied. 

INCLUDE "lib/debugCommands.txt"
. . .
REPEAT 1000
   . . .
   DEBUG_IF vec1 LE vec2
   . . .
   DEBUG_IF vec3 BTW vec4 vec5
   . . .
END

The first DEBUG_IF enters debug mode when vec1 is "less than or equal to" vec2. The second enters debug mode when vec3 is "between" vec4 and vec5.

For this subroutine you must use alphabetic abbreviations for the test operators instead of the actual operators themselves. Here is the list of abbreviations:

ABBREV    Test
   EQ     =
   LT     <
   GT     >
   NE     <>
   LE     <=
   GE     >=
   MO     memberOf
   NMO    notMemberOf
   BTW    between
   NBTW   notBetween



For more information on using the debugger, see the appendix, Using the Debugger. Make sure you read the section "Debugging with Breakpoints" in that appendix. You might find it preferable to use breakpoints as described there rather than the DEBUG command. Breakpoints are much easier to use.

Here's an example using DEBUG inside a loop where the DEBUG will be executed only after the program has looped a given number of times. On the 500th loop, the DEBUG command will be executed and the program will go into debug step mode. The commands in red were added to cause this behavior.

NAME 1 heads
NAME 2 tails
COPY (heads tails) coin
NAME 1000 rptCount
COPY 0 loopCounter
REPEAT rptCount
   ADD 1 loopCounter loopCounter
   IF loopCounter = 500 
      DEBUG
   END
   SAMPLE 4 coin trial
   COUNT trial = heads headCount
   SCORE headCount results
END
COUNT results = 3 successes
DIVIDE successes rptCount probabilityOf3HeadsOutOf4
PRINT probabilityOf3HeadsOutOf4

You can accomplish the same thing more simply by using the DEBUG_AT subroutine discussed at left:

INCLUDE "lib\debugCommands.txt"
NAME 1 heads
NAME 2 tails
COPY (heads tails) coin
NAME 1000 rptCount
COPY 0 loopCounter
REPEAT rptCount
   DEBUG_AT 500 loopCounter
   SAMPLE 4 coin trial
   COUNT trial = heads headCount
   SCORE headCount results
END
COUNT results = 3 successes
DIVIDE successes rptCount probabilityOf3HeadsOutOf4
PRINT probabilityOf3HeadsOutOf4

You can also use the DEBUG command with its optional message string to report an error in your program or subroutine. For example:

'Computes the factorial of the first
'element of the input vector and returns
'it in the result vector. 
'number must be between zero and 170
'(inclusive).
NEWCMD FACTORIAL1 number result ?"Computes factorial of number."
   IF number = 0
      COPY 1 result
   ELSEIF number > 0
      PRODUCT number,1 result
   ELSE
      DEBUG "Error while computing factorial. Number must be positive."
   END
END

If this subroutine is invoked with a negative number, its DEBUG command will print the error message to the Output Window, then the program will enter debug mode.

You can build a more complex error message using the STRING command:

STRING "Error: argument of Factorial is " number " which is negative. Number must be positive." errorMessage

DEBUG errorMessage

Substituting these two lines for the single DEBUG line in the FACTORIAL1 subroutine above produces an error message that looks like this:

Error: argument of Factorial is -3.0 which is negative. Number must be positive.