

StepView 
APL Debugger 

 

                                                          by Jim Weigang 




This disk contains the StepView full-screen APL debugger for STSC's 
APL*PLUS /PC and /386 systems.  The software and documentation is 
copyright 1989-1992 by Jim Weigang, who reserves all rights of ownership 
to the programs.  Unauthorized duplication, except as permitted below, 
is prohibited.  This software and documentation is supplied without 
representation or warranty of any kind.  The author assumes no 
responsibility and shall have no liability of any kind arising from the
use of this software or documentation. 


_Terms of License_   You may use this software on any computer, and you 
may modify it however you wish.  If you wish to give a copy of the
software to another person, you must abide by the following requirement: 

      You must supply the recipient with a complete copy of the original 
      (unmodified) software and complete on-line documentation,
      including the READ.ME file containing this notice. 

You may include modified versions of the software along with the 
original version, if you wish. 


_Price_   If you find yourself using this software more than a few times, 
please register your copy by sending a monetary contribution to the author: 

                   Jim Weigang 
                   68 Plateau Circle 
                   W. Springfield, MA   01089 

You may contribute any amount, whatever you think the software is worth. 
Your contribution will help defray the costs of producing the software 
and will inspire me to spend more time enhancing the debugger.  If you 
send me $30 or more ($40 outside the U.S.), I will send you a typeset 
copy of the documentation and register you to receive a copy of the next 
major release of StepView when it becomes available.  Thank you for your
cooperation. 

      If you have any comments, suggestions, or bug reports, please send 
them to the author at the address above.  For details on site-license
arrangements, please contact the author. 



Contents of Disk 
 
Two versions of the debugger are included on this disk.  One is for 
STSC's APL*PLUS /PC system (version 5 or later), and the other is for 
the APL*PLUS II /386 system.  (The APL programs are identical in the two 
versions, but the assembler subroutines are different.)  Following is a 
list of files on the accompanying disk: 

    DEBUG.AWS     - debugger for APL*PLUS /PC  (compacted version) 
    DEBUGS.AWS    - version with comments 
    DEBUG.ASF     - file containing the ]DEBUG command for /PC 

    DEBUG.WS      - debugger for APL*PLUS II /386 (includes comments) 
    DEBUG.SF      - file containing the ]DEBUG command for /386 

    READ.ME       - first page of documentation 
    DEBUG.TXT     - full documentation 

      In the DEBUG workspace for the /PC system, all comments have been
stripped and the programs have been "diamondized" to minimize memory 
requirements.  If you wish to examine or modify the programs, use the 
version in the DEBUGS workspace, which includes comments.  The DEBUG 
workspace for the /386 system includes comments, since memory is not as 
scarce when using this system. 



]DEBUG Command 
 
If you're using version 9 or later of the /PC system or version 3 or 
later of the /386 system, you can make the debugger a great deal more 
convenient to use by defining a user command to activate the debugger. 
To do so, install the command processor as directed in the APL*PLUS 
manual (if you haven't already), and execute the following statements to 
make the ]DEBUG command available: 

      ]UFILE lib DEBUG 
      ]UMAKE CMDDEBUG /F=UCMDS /NOCOMMENTS
      ]UCOPY lib DEBUG DEBUGDOC /F=UCMDS /R 
      ]UFILE [1] 

Replace "lib" with the number of the library in which the StepView files
are stored.  (If your UCMDS file is stored in a library other than the 
default library, you'll need to specify the library number in the /F= 
options.)  After executing these commands, you will be able to activate 
the debugger using the command "]DEBUG" and deactivate the debugger 
using "]DEBUG OFF".  There is no need to use a )COPY command before 
using ]DEBUG. 




Syntax:  DEBUG 'ON' 
         DEBUG 'OFF {ALL}' 


The DEBUG function is used to activate and deactivate StepView, a full- 
screen debugger that allows you to see your functions displayed on the 
screen while you step execution from one line to the next.  StepView 
reduces the need for paper listings when debugging and ensures that a 
current listing of your program is displayed at all times.

      To activate StepView, copy the contents of the DEBUG workspace
into the active workspace and enter the statement DEBUG'ON'.  This
defines the StepView function and its subroutines in the workspace, and
programs the function keys for debugging operations.  The statement
DEBUG'OFF' deactivates StepView, erasing StepView and it subroutines,
restoring the original function key definitions, and turning off stops
and traces for functions that were debugged.  Using DEBUG'OFF ALL' turns
off stops and traces for all functions in the workspace, not just the
ones that were debugged.  (If you're using the command processor
version, use ]DEBUG to activate and ]DEBUG OFF to deactivate StepView,
and don't use )COPY first.  The command ]DEBUG OFF can be used whether
or not you have activated StepView and is a handy way of turning off all
stops and traces.)

      When StepView is activated, function keys are used to perform
various debugging operations.  Following is an introduction to the
operations and function keys.


_Redisplay_   The Redisplay key (which by default is assigned to F2)
displays the currently suspended function.  Press this key after your
program gets an error or reaches a stop set, and StepView will show you
where you are halted in the code.  The screen is split horizontally, and
the upper portion of the screen is used to display the function listing
and state indicator.  The lower portion of the screen is used for
scrolling and executing APL commands.  The function listing can be
erased by pressing Shift-F2.  Screen splitting and unsplitting is done
in a way that preserves the contents of the scrolling space, so you'll
be able to scroll back and see previous output as usual.

    . . . In the listing of your function, the current line (the line
          about to be executed) is shown in reverse video.  Stop sets in
          the function are indicated by an "s" to the left of the line
          number.  The function listing can be scrolled using the F3 and
          F4 function keys.


_Resume_   The Resume key (F9) executes the APL statement ->LC, which
restarts execution of your program.  When your program next stops, you
can update the display by pressing Redisplay (F2).  If you've put stop
sets on every line of your program, you can use F2 and F9 repeatedly to
step line by line through the program.  (See Step below.)


_Edit_   The Edit key (F6) places you in the full-screen editor with the
suspended function.  The cursor is placed on the current line of the
function.  When you exit the editor (with Ctrl-E), you can update the
function listing on the screen by pressing F2.

    . . . If you're using the Standard version of the APL*PLUS /PC
          system, the editor will clear the stop settings when you exit.
          The Set Stops key (Shift-F8) can be used to restore stops; it
          activates stops on all lines of the suspended function that
          contain an APL statement.  In the Extended /PC or APL*PLUS II
          /386 systems, the editor preserves stop settings and even can
          be used to change stop settings (using Ctrl-period).


_Copy Line_   The Copy Line key (Shift-F6) copies the current line of the
suspended function to the scrolling space, where you can modify and
execute it.  This is especially useful when you have to trace a single
statement by executing parts of the statement; it saves you from having
to retype portions of the line.


_Step_   The Step key (F10) is similar to pressing the Resume key (F9)
followed by the Redisplay (F2) key.  It advances execution of your
program to the next stop and automatically updates the display.  This is
the key that's most often used to step execution from one line to the
next.  However, it must not be used if your program is about to read
input from the keyboard.  In such cases, the Resume key (F9) should be
used instead.

    . . . The Step key performs two actions, one before restarting your
          program and one after the program stops.  If your program is
          going to read input, the input belongs between the two
          actions, and you can't put it there if you use Step.  If you
          press Step and your program reads input, it will read the
          second action statement as input, and you'll never get a
          chance to type anything.  Using Resume instead of Step allows
          you to enter the input after the first command.  Once you've
          given the input, you can press Redisplay to update the
          display, or you can just Step to the next line.


_Step Into_   The Step Into key (F8) activates stop settings for
subroutines used in a statement and then executes the statement, causing
you to begin debugging functions used in the statement.  The statement
can be either a statement that you enter or the current line in the
suspended function; the choice is determined by the line the cursor is
on when you press F8.  If you press F8 on a non-blank line, the
statement on that line is the one that's executed.  Otherwise, if you
press F8 on a blank line, the statement is the one about to be executed
in the suspended function.  Step Into activates stops for functions used
on this line and then executes a Step (F10) operation.

    . . . Step Into saves you from having to manually activate stop
          settings for programs you wish to debug.  To start the
          debugging process, enter a statement that runs your top-level
          function and press F8 (instead of Return) to execute the
          statement.  You'll halt on the first line of the top-level
          function; use the Step key to advance execution to the next
          line of this function.  If you see that the next line calls
          subroutines and you wish to debug these subroutines, use Step
          Into in place of Step.  This will cause stops to be activated
          for the subroutines and execution to halt on the first line of
          the first subroutine.


_Step Out_   The Step Out key (F7) turns off stop settings for the 
suspended function and then executes a Step command, restarting 
execution.  Use this key when you're done debugging the suspended 
function.  However, this key, like all Step keys, must not be used if 
your program is going to read input before next stopping in immediate
execution mode.  If the suspended function will read input, turn stops 
off manually by executing ''STOP'fn', and use Resume to restart 
execution. 


_Help_   A Help key (F1) is provided to remind you of the function key 
definitions.  Press F1 to display the help screen; press any key to 
return to APL. 



Function Key Summary 
 
The following table summarizes the default function key definitions used 
by StepView.  See below for how to customize these key assignments. 

            F1 - Help                      F6 - Edit 
            F2 - Redisplay           Shift-F6 - Copy Line
      Shift-F2 - Undisplay                 F7 - Step Out
            F3 - Scroll Up                 F8 - Step Into
            F4 - Scroll Down         Shift-F8 - Set Stops
            F5 - (not used)                F9 - ->LC
                                          F10 - Step



Example

The following is an example of how StepView is used.


     MYPROG;X;V
[1]   Example program
[2]   X5
[3]   SUBROUTINE 
[4]   V 
[5]   'INPUT: ',V 
      

     SUBROUTINE 
[1]   'SUBR OUTPUT' 
[2]   'SECOND LINE' 
      

      )COPY DEBUG 
      DEBUG 'ON'      - Activate StepView.

      MYPROG   F8     - Activate stop settings for MYPROG and run it. 

      F10             - Step to the next line of MYPROG.
1 2 3 4 5             - Output from line [2]. 

      X              - While using StepView, you can examine or modify 
5                       variables used in the program. 

      F8              - Activate stop settings for subroutines called 
                        on line [3], then continue.  You will stop next
                        within the subroutine. 

      F10             - Step to the next line of the subroutine. 
SUBR OUTPUT 

      F7              - Turn off stop settings for the subroutine and 
SECOND LINE             continue.  You will stop next within MYPROG. 

      F9              - Press F9 instead of F10 when you see that your 
I TYPED THIS            function is about to read input. 

      F10             - Step to last statement.  The function listing is
INPUT: I TYPED THIS     is removed after executing this statement. 


To branch to a line other than the next line, execute a branch statement
and then press F2 to update the display.

      When MYPROG is done, the program listing is usually cleared off
the screen automatically; if not, press Shift-F2 to remove it.  When you
are done using StepView, use:

      DEBUG 'OFF'   or   ]DEBUG OFF

to clean up the workspace and restore the original function key
definitions. 



Customizing Key Assignments and Colors 
 
The function keys and screen attributes (colors) used by DEBUG can be 
changed easily by editing the DEBUG function.  The lines at the top of 
this program define the key numbers and colors; follow the instructions 
in the comments to change them.  (If you're using the /PC system, edit
the programs in the DEBUGS workspace.)  If you're using the ]DEBUG 
command, the edit the CMDDEBUG function instead of DEBUG.  The following 
sequence of commands can be used to edit CMDDEBUG and regenerate the 
package for ]DEBUG:

      ]UFILE lib DEBUG 
      ]UEDIT CMDDEBUG 
      ]USAVE CMDDEBUG /R
      ]UMAKE CMDDEBUG /N /F=UCMDS
      ]UFILE [1]

For "lib" in the first command, substitute the library in which the DEBUG
file is stored.  If your UCMDS file is stored in a directory other than
the current directory, you'll need to specify the library number in the
/F= option of the ]UMAKE command.  See the User Command Processor
chapter of the APL*PLUS reference manual for more information about
these commands.

      Your original function key definitions are saved in a file named
STEPVIEW.KEY which is stored in the root directory of the default drive.
This file is erased when StepView is deactivated.  The name and
subdirectory of this file can be customized by editing CMDDEBUG.



Limitations

If you load another workspace while using StepView, the StepView
function and its subroutines will no longer be defined, but your
function keys will still be programmed to call StepView.  You should
copy the DEBUG workspace and execute either DEBUG'ON' or DEBUG'OFF'.
(Or execute ]DEBUG or ]DEBUG OFF without copying the workspace.)

      Because StepView uses the WINDOW setting to determine if it has
split the screen, StepView may not be usable with programs that alter
WINDOW.  If you manually reset the window during a StepView session
(for example, by pressing Ctrl-Esc), the program listing will be left on
the screen even if you press Undisplay (Shift-F2).  You can manually
remove it, if you wish, by deleting the lines with Alt-F4.

      Special care must be taken with programs that read input from the
user or generate graphic output.  When you see that your program is
about to read input from the keyboard (by any means, including  and 
input, WIN, INKEY, and ARBIN) use the Resume key, rather than Step
(or Step Out or Step In), to advance execution.  If you use a Step key,
your program will read as input the statement used to update the
function listing.  Using the Resume key instead of Step will allow you
to enter the input.  Afterwards, you can use Redisplay to update the
function listing.

      If your program generates graphic output, be careful not to stop
at a point in the program where the screen is in graphics mode.  Doing
so will produce (at best) garbled graphic output.  This problem can be
avoided by turning off stop settings between where the program switches
into graphics mode and where it returns to text mode.

      At present, StepView assumes that the screen size is 25 lines by
80 columns.  If you're using a larger screen, StepView will use only the
upper-left 25 lines and 80 columns.

      The variable names used within the StepView function block access
to certain functions in the workspace, preventing you from debugging
such functions.  You can avoid this problem by not using one-letter
function names or by changing the names of variables within the
STEPVIEWSRC function.

      Certain degenerate programs, such as locked functions, cannot be
debugged using StepView.  Programs that set SA generally cannot be
debugged because the stop action prevents you from halting in immediate
execution mode.  Modify such programs temporarily to not use or localize
SA.



Change Log


Version 1.3:

- pressing Shift-F8 (activate stops) now updates the function display to
show the stops

- executing ]DEBUG OFF clears the function listing from the screen 

- turning off StepView with ]DEBUG OFF now turns off stops and traces
for only those functions that were debugged (that is, those for which
StepView activated stops).  This is done to prevent ]DEBUG OFF from
taking "several minutes" when done in a workspace containing "several
thousand" functions, as reported by Dick Bowman.  ]DEBUG OFF ALL can be
used to turn off stops and traces for all functions in the workspace.
Also, if ]DEBUG OFF is used without previously activating StepView, the
effect is the same as ]DEBUG OFF ALL.

- when you press F6 to edit a function, a null character is inserted in
the input buffer to handle the case where an edit session for that
function already exists.  In effect, the null answers "no" to the
question "Create duplicate session?"  Thus, F6 will put you into an
existing edit session if one already exists.  After making this change,
I discovered that the null character makes the /PC standard system's
editor think you've made changes in the edit session, so you get a "Lose
all changes?" prompt on Ctrl-Q.  In the next release, I'll make the
program skip the null if you're using the /PC standard system.


Version 1.4:

- line-drawing characters were eliminated from the help screen.  Attributes
alone are used to distinguish the title and footer lines.  This allows more 
room for text.

- in /386 and Extended /PC, the debug window is removed from the screen
using a block delete instead of a series of line deletions.  This is
faster.  Unfortunately, the tag-clearing operation used in this method
is not available in versions 1 and 2 of the /386 system or in versions 8
and 9 of the /PC Extended system.  The old technique is preserved in the
comments between lines L8: and L9:.  If you are using one of these older
systems, edit the STEPVIEWSRC function and follow the instructions in
the comments between L8: and L9:

- null is no longer pushed onto the input when you press F6 to edit a 
function in the Standard System.  See comment above.  

