Lund Software House AB SIMDEB User's Guide
Version 1.01

SIMDEB User's Guide for UNIX

by Per Holm
Version 1.0
August 1987
Lund Software House AB
Contents
                                                page
                                                
1.      Introduction                            3
2.      Linking and starting Simdeb             3
3.      A first example                         3
4.      Commands                                4
        4.1     Command syntax                  5
        4.2     Identifying program locations   6
        4.3     Variables and expressions       6
        4.4     Available commands              6


Other Web references

Plain text version of this Guide Help messages (Plain text)

Note: this text has been modified to make it agree with the Universite de Montreal environment, namely using the sim script instead of Lund's simcomp and simld.


1. Introduction

Simdeb is an interactive debugger for Simula programs. The debugger helps you to locate programming errors. By issuing debugger commands you can control the program execution (start, stop and resume execution) and interactively examine and modify values of variables. All commands work in terms of the source program, e.g. program locations are identified by line numbers or procedure/class names and variables are identified by name.

2. Linking and starting Simdeb

You do not have to compile your program in any special way in order to use Simdeb. All necessary information regarding the program is automatically saved in the attribute file. You must, however, use the d-option when compling or linking the program. Simdeb can receive control in three ways:

Example:	

	%sim -d  myprog
	Simdeb 0.3 starts execution
	&
	
or using seperate steps to compile and execute:
	
	%sim -d -nr  myprog
	%myprog -d
	Simdeb 0.3 starts execution
	&
The &-character after the Simdeb initial message is the Simdeb prompt. It indicates that Simdeb is ready to receive a command.
Example:	%myprog      (normal start, without -d)
	... program goes into infinite loop
	... press CTRL \
	Simdeb 0.3 entered because of a User Key Interrupt
	&

Example:	%myprog
	------------------------------------------------------------------
	Runtime error at line 32 of module MYPROG, block at line 2.
	Subscript out of range, too small.
	------------------------------------------------------------------
	Simdeb 0.3 entered because of a runtime error
	&

3. A first example

In this section, the use of some of the most common debugger commands is illustrated. Consider the following program, which is supposed to compute the frequency distribution of 25000 random numbers and to print the number of times that the least common and the most common of the numbers occur.

	begin
		integer array Freq(1:10);
		integer U,i,x,Min,Max;

		for i := 1 step 1 until 25000 do
		begin
			x := Randint(1,100,U);
			Freq(x) := Freq(x)+1;
		end;
		Min := Maxint;
		Max := Minint;
		for x := 1 step 1 until 10 do
		begin
			if Freq(x)Max then
				Max := Freq(x);
		end;
		Outtext("Min - max: ");
		Outint(Min,7); Outint(Max,7); Outimage;
	end
The file randtest.sim contains the program. Compile and link the program:
	%sim randtest

	Min - max:       0  25000
The result is obviously wrong. To pinpoint the error, compile the program together with Simdeb (use the d-option ), then start execution in Simdeb (d-option again):
	%sim -nr -d randtest
	%randtest -d
	Simdeb 0.3 starts execution
	&
To begin with, check if the frequency distribution in the array Freq has been computed correctly. Use the AT-command to set a breakpoint after the first for-loop. To find out exactly which line that is, first use the DISPLAY-command to display the source code.
	& DISPLAY 5:15	! display lines 5 through 15
		5:	for i := 1 step 1 until 25000 do
		6:	begin
		7:		x := Randint(1,100,U);
		8:		Freq(x) := Freq(x)+1;
		9:	end;
		10:	Min := Maxint;
		11:	Max := Minint;
		12:	for x := 1 step 1 until 10 do
		13:	begin
		14:		if Freq(x)
It is now obvious that Randint does not function as expected. The reason 
(and here we have to think instead of using the debugger) is that we 
have forgotten to initialize the random seed U. To correct the error, 
insert the following lines before the for-loop:

	Outtext("Enter random seed: "); Breakoutimage;
	U := Inint;
Compile and run the program again:
   %sim -d randtest

        Enter random seed: 12345
    ------------------------------------------------------------------
        Runtime error at line 10 of  module RANDTEST, block at line 1.
        Subscript out of range, too large.        
    ------------------------------------------------------------------
        Simdeb 0.3 entered because of a runtime error
        &

First, check where the error is, then check the value of the array index:
        & DISPLAY       ! 10 lines surrounding the current location
                6:      U := Inint;
                7:      for i := 1 step 1 until 25000 do
                8:      begin
                9:              x := Randint(1,100,U);
                10:             Freq(x) := Freq(x)+1;
                11:     end;
                12:     Min := Maxint;
                13:     Max := Minint;
                14:     for x := 1 step 1 until 10 do
                15:     begin
        & OUTPUT X
        X :     67
        &
This value is clearly outside the allowed index range 1:10. Looking at line 9, we find that we have written 1,100 as the limits for Randint, instead of the desired 1,10. When this error has been corrected, the program is correct.

4. Commands

4.1 Command syntax

A command is identified by a keyword, possibly followed by parameters. All keywords may be abbreviated, as long as the abbreviation is unique. The character % is used to separate a keyword or a parameter from an option. A command must be contained on one input line. More than one command may be given on one line, if the commands are separated by semicolons.

The character ! indicates a comment (the rest of the line is ignored by Simdeb).

Example:        
	  & AT 420 STOP
        & OUTPUT X,Y+2
        & HELP
        & !  THIS IS A COMMENT

4.2 Identifying program locations

A program location is identified either by its line number in the source program or by the name of a procedure or a class. In the latter case, the location is the first line of the body of the procedure or class. Some commands take a range of locations as parameter. The range can be specified in the following ways:
        <location>
        <first location> : <last location>
        <first location> , <number of lines>
The last line of a program module may be specified as *.
Example:        
        & DISPLAY 25:40 ! display source lines 25 through 40 of
					the current module
        & AT 120 STOP   ! set a breakpoint at line 120
        & AT FUNC STOP  ! set a breakpoint at the first line of the
					procedure FUNC
All program locations refer to Simdeb's "current module". When execution starts, the main program is the current module. If a procedure or class in another source module is called, this becomes the current module. The current module may also be explicitly set with the help of the Simdeb command MODULE (4.4.4).

4.3 Variables and expressions

A variable is identified by its name in the same way as in the source program. Only variables that are visible from the current program location, according to the normal Simula scope rules, may be accessed.
Example:
	& OUTPUT X
	& OUTPUT A(3,K)
An expression may be used to compute a value. The syntax for expressions follows the normal Simula rules. Hur med funktioner och new?
Example:
	& OUTPUT X+2*(Y+1)
	& OUTPUT PTR.SUM
	& OUTPUT X<2
	& OUTPUT TXT
	& OUTPUT TXT.GETCHAR='a'

4.4 Available commands

The following sections contain a description of all the available Simdeb commands. When a command may take alternative parameters, the alternatives are separated by vertical bars (|). Normal parentheses are used to group the alternatives. Optional parameters are enclosed in brackets ([ ]). Repetition is denoted by an ellipsis (…).

4.4.1 Controlling and monitoring execution

	AT  command [;command …]
Set a breakpoint. The commands are performed every time that the location is reached and about to be executed. The maximum number of breakpoints is 20. Notice that execution is not automatically halted at a breakpoint. However, the most common use of the AT-command is to introduce "stop points" into a program. In that case, the command should be a STOP-command (see below). More generally, the command may, be an arbitrary command. A useful feature is the conditional breakpoint, where the command is an IF-command.
	STOP
Execution is halted and new Simdeb commands are accepted. The message STOP AT is displayed. The STOP command is most useful when used as the command in an AT-command, but may also be used on its own, to find out where the program was interrupted.
	CTRL \      (user key interrupt)
This is a special command in the sense that it can be given at any time, even without the & prompt. An interrupt when the program is executing stops the program before the next line is executed. If the program is waiting for input from the terminal when it is interrupted, verkar inte fungera alls för närvarande.
	PROCEED
The execution of the program is started, or resumed after a breakpoint. PROCEED is not a valid command when Simdeb has been entered because of a runtime error.
	NEXT | STEP
Works as PROCEED, but execution is halted after one line of the program has been executed. If the line contains a procedure call or class new, the call will be followed (i.e. the next line will be the first line of the procedure or class). This is sometimes called "stepping into" procedures.
	LINE
As NEXT, but does not follow procedure calls or class new. This is sometimes called "stepping over" calls.
	DO  [(parameter list)]
Call a procedure (or perform a new on a class). The procedure or class must be visible from the current program location, and is executed in its context. When control reaches the final end of the procedure or class, it is returned to Simdeb. (Ska det vara sĆ?) The parameter list is a list of expressions. Procedures with name parameters or procedure parameters may not be called with a DO-command.
	BYE | QUIT | EXIT
Terminate execution. This command may not be abbreviated.
	BREAKS
List all breakpoints, with their associated command lists.
	REMOVE  (AT <location> | %ALL)
Remove all breakpoints at a specified location, or remove all breakpoints.
	TRACE  (ON [<range>] | OFF)
Each line that is about to be executed will be displayed. If a line number range is specified, only lines within the range will be traced.
	CHAIN
Print the dynamic chain of procedure and class calls, starting from the current program location.

4.4.2 Examining and modifying data

	OUTPUT (<expression>[%ALL] [,[%ALL] …] | %ALL)

Evaluate an expression and print its value. If %ALL is given without a preceding expression, the values of all the variables in the current block are printed. %ALL is explained below. The following table describes what is printed when the expression is of a specific type and kind.

Type or kind    Output

Arithmetic      The numeric value.
Boolean         TRUE or FALSE.
Character       The character, enclosed in quotes e.g. 'A'. A   
                non-printable character is  output as '!!', where    
                =Rank(character).
Text            POS=, LENGTH=, "text value"
Array           Number of indices, array bounds.
Array%ALL       All values of the array, in row-major order.
Ref             Qualification of the object and state of the object 
                (e.g. TERMINATED).
Ref%ALL         The values of all of the attributes of the object.
Procedure or class      
                The source line at which the procedure or class is 
                declared.

	INPUT   (:= | :-)  
Changes the value of the specified variable to that of the expression.

4.4.3 Displaying source code

        DISPLAY [<range>]
Print the source lines in the indicated range. If no range is given, 10 lines are displayed, starting with the next line to be displayed. The "next line" is initialized to the current program location—5 when a breakpoint is entered.

4.4.4 Changing the current module and viewpoint

    MODULE [<module name>]
Change Simdebęs current module (see 4.2). If no module name is specified, the name of the current module is displayed.
    VIEW [<expression> | %ENTRY | %RETURN | %PREVIOUS | %UP]
The point in the program from which Simdeb sees the variables is moved (when a breakpoint is reached, the viewpoint is the current program location). This makes it possible to examine and modify variables which are not visible from the current program point. There are several alternative parameters: <expression> The viewpoint is moved to inside the referenced object. The expression must be of type ref. %ENTRY The viewpoint is returned to the current program location. %RETURN If the current program location is inside a procedure or class, the viewpoint is moved to the point where the procedure or class was called. %PREVIOUS The viewpoint is returned to the point before the last VIEW command. %UP The viewpoint is moved to the statically enclosing block. The current viewpoint is printed.

4.4.5 Structured commands

        IF <boolean expression> THEN command [;command …]
If the boolean expression evaluates to true, the list of commands is executed. The IF-command is most often used to introduce conditional breakpoints, but can also be useful on its own, e.g. IF THIS INFILE==SYSIN THEN OUTPUT "Yes".
        WHILE <boolean expression> DO command [;command …]
Similar to the IF-command, but the list of commands is executed repeatedly as long as the boolean expression is true. To make the WHILE-command really useful, variables must be available to control the repetition. For this purpose, variables in the program may naturally be used, but this is often not possible. Instead, variables local to Simdeb can be used. Any variable whose name contains a $-character is local to Simdeb. Local variables are dynamically created when they are first referenced, and do not have any type. As an example, the WHILE-command can be used to traverse a Simset list H in the following way:
        & INPUT $R:-H.First; WHILE $R=/=none DO OUTPUT $R%ALL; INPUT
		$R:-$R.SUC
4.4.6 Redirecting output and input
        USE OUTPUT  [<file name>]
Simdeb output will be written to the file specified in the command. To redirect the output to the terminal, give the command USE OUTPUT without a file name.
        USE COMMAND [<file name>]
Simdeb input is read from the file specified in the command. When the end of the file is found, Simdeb will again request input from the terminal. To redirect the input to the terminal, give the command USE INPUT without a file name.

4.4.7 Miscellaneous

HELP [<command name>] Print a list of all available commands, or print information regarding the specified command. GUARD [<variable>] Set a "guard" on the specified variable. When the variable changes value, Simdeb is reentered (the value is tested before each line is executed). You "unguard" a variable by giving the command GUARD without any parameters. Only one variable may be guarded at the same time.
        FREQUENCY  [ON <range> | OFF]
This command is used to obtain a dynamic execution of a program, or part of a program. The command FREQUENCY ON orders Simdeb to start collecting statistics regarding the number of times each source line in the specified range is executed. This information can later be printed, together with a listing of the source program, with the command FREQUENCY (no parameters). The collection of statistics is halted with the command FREQUENCY OFF. Example of use:
        & AT * STOP
        & FREQUENCY ON 1:*
        & PROCEED
        …
        & USE OUTPUT "FREQTAB"
        & FREQUENCY
This will result in the execution frequency being printed on the file FREQTAB.
        TYPE 
Print the contents of the specified file on the terminal.
        XDEBUG
Enter the assembly level debugger. This feature is only useful when debugging user-written non-Simula routines.
        SHELL | CLI
Create and enter a new shell. Simdeb is reentered upon exit from the shell.