Sheerpower®
A Guide to the Sheerpower Language


Previous Contents Index

2.4.3 TRACING APPLICATION LOGIC FLOW

FORMAT:


        TRACE ON|OFF 

EXAMPLE:

Copy and paste the example code below into a new program file in SPDEV (i.e. trace_on.spsrc) and then run the program from SPDEV.

Example 2-18 TRACE ON/OFF

debug on
trace on
do_totals 
trace off
stop
 
routine do_totals 
  print "Doing totals..." 
end routine
 
 
Doing totals... 

PURPOSE:

In complex applications, there is often a need to follow an application's program flow in order to figure out how the application works. This is also useful when debugging logic errors in an application.

DESCRIPTION:

TRACING is used to follow an application's logic flow. As each statement is executed, the trace window will display the label and line number and source line being executed.

To turn off tracing, just close the trace window. Typing in TRACE OFF in the console window will stop tracing, but leave the trace window open.

You can copy select or all of the text inside the trace window by highlighting the text with your mouse (CTRL/A will select all) and using CTRL/C to copy it.

In the console window toolbar, you can use the Trace icon to toggle the trace feature on or off.

The STATISTICS Features

STATISTICS records information on a program's execution. It records the time each program line takes to execute and the number of times the line is executed. The word "STATISTICS" can be abbreviated to "STATS" (STATS ON, STATS OFF, LIST STATS). This abbreviation will be used frequently in this Guide.

2.4.4 STATS ON

FORMAT:


        STATS ON 

EXAMPLE:

Example 2-19 STATS ON

  debug on
  stats on
  dim name$(5) 
  for i = 1 to 5 
    input 'Please enter your name': name$(i) 
    if  _exit  then exit for
    print 'Hello, '; name$(i); '!' 
  next i 
  end
  
  
Please enter your name? Tester 
Hello, Tester! 
Please enter your name? exit   <---- type in 'exit' and press [Enter]

PURPOSE:

STATS ON is used to turn on the statistics feature, which stores the execution time and count for each program line. Use STATS to tell if statements are being executed the correct number of times and which parts of a program are taking the most time. STATS is especially useful for speeding up a program's execution time.

DESCRIPTION:

STATS ON enables Sheerpower's statistics feature. Sheerpower begins recording statistics when program execution begins. The statistics feature remains enabled until the STATS OFF statement is executed.

STATS ON can be executed in immediate mode or in a program. If STATS ON is executed in immediate mode, DEBUG is automatically switched on. If STATS ON is executed in a program, and DEBUG is off, Sheerpower ignores the statement. When STATS ON is executed, any statistics previously recorded are lost.

2.4.5 STATS OFF

FORMAT:


        STATS OFF 

EXAMPLE:


        stats off 

PURPOSE:

STATS OFF is used to turn off the statistics feature.

DESCRIPTION:

STATS OFF turns off Sheerpower's statistics feature. STATS OFF can be executed in immediate mode or in a program. If STATS OFF is executed in a program and DEBUG is off, Sheerpower ignores the statement. STATS OFF leaves DEBUG on.

2.4.6 LIST STATS

FORMAT:


        LIST STATS [: routine_name, routine_name ,....] 

EXAMPLE:

To run this example, copy and paste the example code below into a new program file (e.g. list_stats_example.spsrc) in SPDEV and then run the program by clicking on the running man icon in the SPDEV toolbar.

Example 2-20 Listing statistics in DEBUG system

  debug on
  stats on
  dim name$(2) 
  for i = 1 to 2 
    input 'Please enter your name': name$(i) 
    if  _exit  then exit for
    print 'Hello, '; name$(i); '!' 
  next i 
  list stats
  end
  
 
// results in the Console Window 
Please enter your name? Tester <--- type a name in, press [Enter]
Hello, Tester! 
Please enter your name? Tester <--- type a name in, press [Enter]
Hello, Tester! 
 
Writing code runtime statistics to... 
  C:\SheerPower\Samples\list_stats_example_stats.txt 
Done. 

LIST STATS returns the code runtime statistics after a program has been run. There are two ways that you can use LIST STATS; one is by using it as a statement inside the program source code, or you can type in "LIST STATS" directly into the console window after the program has run (also after a HALT or BREAK in the program).

Note that both DEBUG ON and STATS ON must be in the code prior to LIST STATS.

When LIST STATS is executed, an output file is created containing the code runtime statistics. The file name will always be in the format shown below (where "program_name" is the name of the program) and will be stored in the same directory location as the source program file.


  [program_name]_stats.txt 

The stats output file will contain the file name, the date and time, and the statistics for each line in the program. Below is an example of the code runtime statistics contained in the file.


list stats
Sheerpower Code Runtime Statistics on 26-MAY-2017 15:34:43 
 
C:\SheerPower\Samples\list_stats_example_stats.spsrc 
 
1          0.00        stats on 
1          0.00        dim name$(2) 
1          0.00        for i = 1 to 2 
2          2.54        input 'Please enter your name': name$(i) 
2          0.00          if  _exit  then exit for 
2          0.00          print 'Hello, '; name$(i); '!' 
2          0.00        next i 
--- End of stats --- 

PURPOSE:

LIST STATS is used to display the statistics recorded by the STATISTICS feature.

DESCRIPTION:

LIST STATS lists each program line along with the number of times the line was executed and the execution time of each line.

The far left column lists the number of times each statement was executed. The next column gives the time each statement took to execute. The time is given in seconds and fractions of a second. (0.01 means the program line was executed in one-one hundredth of a second.) The last column lists the program itself. STATS must be ON for LIST STATS to be executed.

All the options available with the "LIST" statement are also available with LIST STATS. (See Section 2.3.3, LIST for more information.)

2.4.7 BREAK Statement

FORMAT:


        BREAK 

EXAMPLE:

Example 2-21 Using BREAK in DEBUG system

  debug on
  print '1', 
  print '2', 
  break
  print '3', 
  print '4', 
  print '5' 
  end
 
 
 
1                   2                   break at main.0003 
 

PURPOSE:

BREAK is used to stop program execution when DEBUG is ON. For instance, you might use BREAK to stop the program if a variable is assigned a wrong value.

DESCRIPTION:

The BREAK statement can be used anywhere in a program. The BREAK statement will not take effect unless DEBUG is turned on. If DEBUG is off, Sheerpower ignores any BREAK statements.

The HALT statement works the same way as the BREAK statement (see Section 2.3.4, HALT Statement) except that it always interrupts program execution.

When Sheerpower executes a BREAK statement, it interrupts program execution and prints a BREAK message. The BREAK message tells what line the break occurred in. Program execution can be continued with the GO or STEP commands.

2.4.8 STEP

FORMAT:


        STEP [number] 

EXAMPLE:

Example 2-22 Using STEP in Debug

  print '1', 
  print '2', 
  break
  print '3', 
  print '4', 
  print '5' 
  end
 
 
 
1                   2                   break at main.0003 
 
step 2 <--- type in a "2" and press [Enter] 
3                   4 

PURPOSE:

STEP is used to execute a specific number of program statements and then stop execution. That way, you can "step through" your program to find bugs.

DESCRIPTION:

STEP is used to step through a program to execute a specified number of program statements. DEBUG must be ON for the STEP command to take effect. If DEBUG is not on and the STEP command is given, Sheerpower ignores it. STEP must be given as a command. When the STEP command has been executed, Sheerpower issues a BREAK and prints the break message. Issuing the STEP command without a number causes Sheerpower to execute one program line.

Issuing the STEP command with a number causes Sheerpower to execute the number of program lines specified. Sheerpower begins executing program lines from the last line executed. It stops when the number of lines specified have been executed or when program execution ends.

You must start a program with RUN before you can use the STEP command. STEP is also used after a HALT or BREAK has executed.

Note: When you're in the Console window, you can use the [F2] key as a shortcut to issue the STEP command.

Two options to STEP are detailed below: STEP OVER and STEP OUT. STEP used alone effectively means STEP "INTO".


Previous Next Contents Index