OS/2 Professional/OS2PRO194.ISO/os2/prgramer/mltiscop/tutor.doc

Text File | 1989-07-28 | 40KB | 982 lines

           The Logitech MultiScope(tm) Trial Version Tutorial
          ====================================================

  This tutorial provides an overview of MultiScope features and commands
  you need to debug your program.  It discusses the basic strategies for
  debugging and provides a brief introduction to the debugging process.
  You will learn how to

    * Start the MultiScope debuggers.
    * Get on-line help.
    * Execute your program in steps.
    * Look at your program's modules.
    * Examine your program's source code.
    * Browse through your program's data structures.
    * Modify a variable.
    * View a graphic data representation.
    * Set simple and conditional breakpoints.
    * Look at your program's memory.


The Debugging Process
---------------------

 MultiScope is a programmer's tool that lets you find and diagnose
 programming errors.  Programmers usually follow three basic steps
 when debugging a program:

    * Finding an error.
    * Diagnosing an error.
    * Fixing an error.

 The first step in the debugging process is to find the errors in
 your program.  It is a common for beta testers or quality assurance
 personnel to test your program to help find errors.  The testers
 prepare "bug reports" detailing the program  errors.  However,
 diagnosing the problems that led to the errors is not always
 possible.

 The second step in the debugging process is diagnosing the cause of
 the error.  Errors are common during software development and may
 take many hours, and sometimes days, to properly diagnose.  Often
 errors happen the first time you test your program, but many times
 they arise only after repeated testing.  If your program terminates
 abnormally (crashes) diagnosing the cause of the crash can be
 difficult if not impossible.

 With MultiScope it is easy to find and diagnose errors because you can

    * Control the execution of your program.
    * Inspect your program in easy to understand views.
    * Pinpoint the location of errors at the source code level.

 The final step of the debugging process is fixing your program.
 Although MultiScope can make the first two steps of the debugging
 process easier, it cannot fix your program's errors.  How you fix
 these is up to you.

 The best way to learn how to use MultiScope is to jump right in and
 start debugging a program.  An example tutorial program has been
 provided for this tutorial.

 Note:  When you are instructed to "click" on an item in this tutorial,
 you should press and release the left mouse button on the indicated
 item.


1.  Your First Look at MultiScope
---------------------------------

 This section explains how to start the Run-Time Debugger, and get help.
 and quit the program.  To start the MultiScope Run-Time Debugger tutorial,
 follow steps 1 and 2.

 Step 1:  Move to the MultiScope trial version directory.  Before you
  can start the MultiScope debugger, you must move to the directory
  where your MultiScope program files reside.  From the OS/2 command
  line, type:

    C:
    CD \MSCOPE

  where C:\MSCOPE is the path and directory you specified during
  the installation of the trial version of MultiScope.

 Step 2:  Start the Run-Time Debugger tutorial.  To start the debugger
  and this tutorial, type

    MSDEMO

  The Presentation Manager Run-Time Debugger is then loaded.  Take
  a quick look  at Multiscope's default screen configuration on your
  screen. This screen, which can be customized, has 1 main window that
  contains 13 subwindows.  The main window's title bar reads "MultiScope
  Debugger".  Each of the subwindows is either open or identified by an
  icon at the bottom of the screen. The subwindow's title bar identifies
  the information the window contains.  For example, the Source window
  displays the source code of the program you are debugging.

 Step 3:  Look at the global menu bar.  Multiscope's global menu bar,
  located under the title bar of the main window, has these pull-down
  menus:  Program, Windows, Go, Setup, and Others.  Global menus contain
  commands that you can execute at any time in the debugging session with
  either the mouse or the keyboard.

 Step 4:  Open a global menu.  Move  the pointer to the Windows menu.
  Click to open the Windows menu.

  Notice that the menu commands are displayed on the left side and the
  corresponding accelerator keys on the right. Once a menu is open,
  you can select a command by clicking on it with the mouse or
  highlighting it with the arrow keys and pressing Enter.

 Step 5:  Close Windows menu.  Click outside the menu.

 Step 6:  Activate a window.   Press Ctrl-D to activate the Data window.
  To activate a window, press Ctrl plus the letter that corresponds with
  the window's name.

  Note:  The accelerator key for the Memory window is Ctrl-E.

 Step 7:  Open a local menu.  Under the title bar of each subwindow are
  the local menus.  Local menus are only available when that window is
  active. In this case the Data window is active, so the View, Watch, and
  Others menus are available.  Move the pointer to the View menu and
  click.

  To select a local menu command, click on it with the mouse or highlight
  it with the arrow keys and then press Enter.  Most local commands are
  available without opening the menu by using an accelerator key.  The
  accelerator keys for local commands are always Alt plus a letter, such
  as Alt-C to execute the Child/Contents command on the View menu.

 Step 8:  Close View menu.  Click the pointer outside the menu.

 Step 9:  Select the Data window.  Press Ctrl-D to activate the Data window.

 Step 10:  Get Help.  Press F1 to get help.  Since the Data window is
  active, the Help window displays the local index for that window.

 Step 11:  View Help.  Double-click the left mouse button on Child/Contents
  to view the Help screen for this command.

 Step 12:  Leave the local index.  Double-click the right mouse button to
  return to the local index.

 Step 13:  Leave Help.  Press F1 to exit from Help and return to
  MultiScope's main window.


  In summary, you can use MultiScope's interface effectively by following
  the basic keystroke and mouse guidelines shown below.

    * To execute global commands, press Ctrl plus a corresponding key or
      select the command from the global menu with the mouse or keyboard.

    * To execute local commands, press Alt plus a corresponding key or
      select the command from the local menu with the mouse or keyboard.

    * To execute Go commands, press the first letter of the Go command.

    * To execute certain commands quickly, for example, to get information
      about the Help index items, double-click the mouse.

    * To maximize or minimize a window, click on the appropriate icon in
      the window's upper right corner.


2.  Customizing Your Screen
---------------------------

 Customizing your screen allows you to restore, resize, maximize, or
 move a window. For example, you may want to maximize the Source
 window to display more code or restore a window to view its
 contents, or change a window's background and text colors.

 Step 1:  Maximize the MultiScope window.  Click on the maximize icon
  (the up arrow) in the upper right corner of the main window.  The window
  expands and occupies the entire Presentation Manager screen.

 Step 2:  Restore an icon to a window.  Double-click on the Log window
  icon to restore (or open) the window from an icon. The Log window is
  restored, but you may need to resize it to see its contents.

 Step 3:  Resize a window.  Place the pointer over the left border of the
  Log window. The pointer changes into a two-way arrow that points either
  horizontally, vertically, or diagonally.  Click and drag the mouse to
  enlarge the window.  A shaded box marks the borders of the window and
  expands as you move your mouse. Release the mouse button to anchor the
  window at its new location.

 Step 4:  Move a window.  Position the pointer over the Log window's
 title bar. Press and hold the left mouse button.  Click and drag the
 mouse to move the window to a new location on the screen. Release
 the mouse button to set the window at its new location.

 Step 5:  Maximize a window.  Click on the maximize icon (the up arrow)
  in the upper right corner of the Log window.  The window expands and
  occupies MultiScope's entire main window.

 Step 6:  Minimize a window.  Click on the minimize icon (the down arrow)
 in the upper right corner of the Log window.  The window becomes an icon
 and is displayed at the bottom of the main window.

 Step 7:  Change a window's color.  Press Ctrl-S to make the Source window
  active if it is not already.  Press Ctrl-Keypad+, and the Source window's
  background color changes.  Press Ctrl-Keypad-, and the window returns to
  its original color.

  Pressing Ctrl-Keypad+ and Ctrl-Keypad- cycles the active window's
  background color through a set of color combinations.

  You can also change all the colors of a window with the Color Panel
  command in the global Setup menu.

 Step 8:  Change the text size in a window.  Press Ctrl-1, and the text
  in the Source window changes to a smaller font.  Press Ctrl-3, and the
  text becomes larger.  Press Ctrl-2, and the text returns to the original
  font size in between the two.

 Step 9:  (Optional) Save your screen configuration.  You can save the
  screen configuration now or wait until you have customized your screen
  before saving it. To save the screen configuration, select Save Setup
  from the global Setup menu.


3.  Executing Your Program
--------------------------

 This section is your first chance to execute your program in the
 Run-Time Debugger.  You will begin by using the Find Procedure/Line
 command to locate a procedure and a line number in the Source window.
 Next, you will execute TUTOR to a selected line and look at TUTOR's
 output.  Finally, you will step through your program with the Go
 commands at the source and assembly level.


 3.1  Executing to a Selected Line
 ---------------------------------

 You can search for a procedure or a line number in your source code
 with the Find Procedure/Line command. This is the quickest way to find
 a procedure or line without scrolling through lines and lines of code.
 One reason you would move to a particular line is to execute
 to that line.

 Step 1:  Make the Source window active.  Press Ctrl-S to make the Source
  window active.

 Step 2:  Search for a line number.  From the local Find menu, select Find
  Procedure/Line. MultiScope prompts you with a dialog box.  Enter the line
  number.  Enter

    63

  The Source window updates and shows the code for line 63,  which is
  highlighted.

 Step 3:  Execute the program to the selected line.  Double-click on

    ChooseMe(1,"MultiScope",3);

  This selects this line and executes the application program to that
  line.  The screen displays the application's output for only a moment
  before returning to the debugger's screen.  In the next step, you will
  learn how to hold the Output screen open.

  The ">" symbol, which indicates that the program has executed to this
  line, is now displayed to the left of the selected line.

 Step 4:  Look at the output of the program.  Press Ctrl-O to view TUTOR's
  output. (You can also double-click on the output icon to view the output
  screen.)  The Output screen shows the application's output.  After a few
  seconds, the debugger screen reappears.


 3.2  Executing with Go Commands
 -------------------------------

 Go commands, found only in the Run-Time Debugger, let you step through
 your program and pass over sections of code.  These commands are useful,
 for example, when you want to go directly to the area of the program
 that you suspect contains bugs.  In this section, you will use the Go
 commands to execute TUTOR by stepping across and into a procedure call,
 and then returning from the call.


 3.2.1  Source Level Go Commands
 -------------------------------

 Step 1:  Step across a procedure call.  From the global Go menu, select
  Flat.  The current statement is a procedure call that TUTOR executes
  until the procedure call has returned.  The Source window's selected
  line advances one statement in the current module.

 Step 2:  Step into a procedure  call.  From the global Go menu, select
  Statement.  Statement is similar to Flat, but if the current statement
  is a call to a procedure, it stops your application at the entry of the
  called procedure.  The Source window displays the source code of the
  procedure.

 Step 3:  Return to the calling procedure.  From the global Go menu, select
  Return.  The Source window now shows the statement where the function
  returned.

  If you step into a procedure and realize it is not the procedure you
  wanted to step through, select Go Return.  At that point, MultiScope
  executes the rest of the procedure, but once it finishes that MultiScope
  stops execution at the return address of that procedure.


 3.2.2  Assembly Level Go Commands
 ---------------------------------

 Step 1:  Restore the Assembly window.  Double-click on the Assembly
  window's icon and resize the window so that its contents are visible.
  (If the Assembly icon is hidden, press Ctrl-A to make it active.)

 Step 2:  Execute for one assembly instruction.  From the global Go
  menu, select Assembly Trace.  Your program executes one assembly
  instruction.  The Assembly and Source windows update and show the
  current execution location.

 Step 3:  Execute to the next instruction.  From the global Go menu,
  select Assembly Next.  The application program executes to the next
  assembly instruction.

  Assembly Trace lets you step through the program's code at the assembly
  level instruction by instruction.  Assembly Next works the same way, but
  the debugger does not trace into procedure calls.  You could also think
  of Go Trace as an assembly version of Go Statement and Go Next as an
  assembly version of Go Flat.

 Step 4:  Minimize the Assembly window.  Click on the minimize icon
  (the down arrow) in the upper right corner of the Assembly window.
  This changes the Assembly window to an icon.  In most cases there is no
  reason to have the Assembly window open if you are working at the source
  level; therefore, you should minimize the Assembly window.

  Keep in mind that the Go commands are global; therefore, the Source or
  Assembly windows do not have to be active to execute a Go command.  This
  is helpful, for example, when you are stepping through your program and
  looking at the Data window to see the values of your variables change.


4.  Viewing Data
----------------

 MultiScope's multiple windows provide numerous ways to view your program's
 data.  In this section, you will examine data by browsing through data
 structures, looking at arrays, and displaying a graphic data
 representation.

 This tutorial uses C language data structures to demonstrate data browsing.
 Other languages, such as Pascal and Modula-2, have similar structures, but
 the syntax is different.  Therefore, this section should be easy to follow
 if you are familiar with one of these languages.


 4.1  Looking at Variables
 -------------------------

 In this section, you will learn how to use the Module and the Call window
 commands to display global and local data in the Data window.


 4.1.1  Global Data
 ------------------

 MultiScope's Module window displays a list of the modules included in
 your program. The Module window's local commands let you display the
 module's source or data or both.

 Step 1:  View the module list.  Press Ctrl-M to make the Module window
  active.  The Module window displays a list of the modules in TUTOR.EXE.
  TUTOR is the selected module because the highlighter bar is on that
  item.

 Step 2:  Select another module.  Double-click on the module's name to
  select another module.  Double-click on LLRAS.  When you double-click
  on a module name, the Source and Data windows update and show the source
  code and global data for that module.

 Step 3:  Look at the global data in LLRAS.  Press Ctrl-D to make the Data
  window active.  Resize the Data window so that its contents are visible.
  The Data window now displays two variables, "llras" and "numList".  The
  current values and types of the variables are displayed.


 4.1.2  Local Data
 -----------------

 The call chain is the list of procedure calls that have been made in the
 current thread. The Call window displays the call chain and allows you to
 view the local data of procedure calls.

 Step 1:  Restore the Call window.  Double-click on the Call window icon.
  (If the icon is hidden,  press Ctrl-C to make it active.)

  The Call window shows that so far in the execution of the application
  program, the application's process (in the current thread) has called
  the procedure "main" of the module TUTOR.

 Step 2:  View the local data of a procedure in the call chain.  Double-
  click on "main" in the Call window.  The Source and Data windows update
  and show the text, local variables, and parameters of the procedure
  main.

  In the Data window, the names of all the variables declared in the
  procedure "main" are on the left.  Their values are displayed in the
  center, and their types are displayed on the right.

 Step 3:  Activate the Data window.  Press Ctrl-D to make the Data window
  active.


 4.2  Looking at Data Structures
 -------------------------------

 You can browse through your program's data structures by using several
 commands in the Data window.  You can follow pointers to examine child
 structures, look at fields in records, view arrays, and display a graphic
 representation of complex data structures.

 Step 1:  Select a module.  Let's take a closer look at the variable "llras"
  that you saw in the global data of the module LLRAS.  Double-click on the
  module name LLRAS to update both the Data and the Source window.

 Step 2:  Activate the Data window.  Press Ctrl-D to make the Data window
  active.  Notice that the variable "llras" is selected.

 Step 3:  Step into the data structure.  From the local View menu, select
  Child/Contents.  The Data window displays the fields in the record to
  which llras points.  The Data window's header shows the current path
  of the data display.

 Step 4:  Execute the Child/Contents command.  Double-click on the field
  "next" to execute the Child/Contents command.  The Data window updates
  and displays the fields of the next structure in the list.

 Step 5:  Execute the Parent command.  Double-click the right mouse button
  in the Data window to execute the Parent command.  The Data window updates
  and displays the parent record.

 Step 6:  Return to the top variable.  From the local View menu, select
  Variable Level to return to the top variable of the data.  The Data window
  updates and shows the original global variables of the LLRAS module.


 4.3  Looking at Arrays
 ----------------------

 You can use the Child/Contents and other commands, such as Right (next
 element) or Left (prev. element), to display the contents of an array.

 Step 1:  Look at the global data of another module.  Double-click on TUTOR
  in the Module window.  The Source and Data windows update to show TUTOR's
  source text and global data.

 Step 2:  Activate the Data window.  Press Ctrl-D to make the Data window
  active.

 Step 3:  View the array elements.  Double-click on "array" to execute the
  Child/Contents command and display the contents of the array.  The Data
  window shows the index numbers on the left and the element values on
  the right.  "array" is an array of records, so you must open a record to
  examine its fields.

 Step 4:  View the fields of the record.  Double-click on array element 1.
  The Data window shows the fields of element 1's record.

 Step 5:  View more of the array elements.  From the local View menu, select
  Right (next element).  The Data window shows the data in the next element
  in the array.

 Step 6:  Decrement the index.  From the local View menu, select Left
 (prev. element) to decrement the index and return to the previous index.
 The Right and Left commands are shortcuts for examining the contents of
 arrays to avoid going one level up, selecting another index, and then
 displaying the Child/Contents of that index.

 Step 7:  Select a specific index.  From the local View menu, select
  Specific Index.  MultiScope prompts you for a new value.

 Step 8:  Enter a new value.  Type 5 and press Enter.  The Data window
 updates and shows the fields of the fifth element in the array.

 Step 9:  Return to the variable declaration level.  From the local View
  menu, select Variable Level.  The Data window updates and displays the
  original list of global variables.


 4.4 Looking at a Graphic Data Representation
 --------------------------------------------

 Graphic data representation, just one of Multiscope's unique features,
 allows you to display complex data structures as a graph in a Presentation
 Manager window.  In the past you had to draw a graph of the data structure
 manually.  You no longer have to draw these graphs because MultiScope
 prepares a graph of a selected data structure for you.

 Step 1:  Select a module.  Double-click on the module name LLRAS to update
  both the Data and the Source window.

 Step 1:  Configure your screen.  Double-click on the Graphic Data icon to
  restore it.  (If the icon is hidden, press Ctrl-G to make it active.)
  Position both windows on the screen so that the Data window and the
  Graphic Data window are visible.

 Step 2:  Activate the Data window.  Press Ctrl-D to make the Data window
  active.

 Step 3:  Select a variable.  Select the variable "llras" by clicking on

    llras       0227:0FAEh  * ListOfList

 Step 4:  Display graphic representation.  From the local View menu, select
  Graphic Data Structure.  It takes a moment for MultiScope to lay out and
  draw the graph; the hourglass icon appears during this process.  When the
  graphic data structure appears, click on the maximize arrow in the Graphic
  Data window.  The graphic representation of the variable is displayed in
  the Graphic window.

  The variable "llras" is the top left node pointing to the first record
  of type ListOfList.  The "next" field in each record points to the next
  record of the same type (list of ListOfList).  The field "list" points
  down to another type of record (list of List).

 Step 4:  Zoom in on the graph.  Double-click the left mouse button inside
  a box in the Graphic Data window to zoom in on the area.  Zoom in until
  the structure is large enough for you to see the graph node comments
  inside each box.

 Step 5:  Zoom out.  From the local Zoom menu, select Zoom Out. The graph
  shrinks and shows more of the graph, but the detail inside the boxes may
  disappear.  You can also zoom out on an area by double-clicking the right
  mouse button inside a box in the Graphic Data window.

 Step 6:  Reset to initial position.  From the local Zoom menu, select Zoom
  Reset.  The Graphic Data window displays the original graph.

 Step 7:  Restore the Graph window to an icon.  Click on the minimize icon
  to restore the window.


 4.5  Looking at Memory Locations
 --------------------------------

 In this section, you will learn to use the Memory window to view the
 contents of memory in various formats.  Later in the tutorial, you will
 learn how to change the value of a memory location.

 Step 1:  Restore the Memory window.  Double-click on the Memory window
  icon to restore it.  (If the icon is hidden, press Ctrl-E to make it
  active.)  Resize it so that the contents are visible.

 Step 2:  Activate the Data window.  Press Ctrl-D to make the Data window
  active.

 Step 3:  Select a variable.  Select the variable "numList" in the Data
  window by clicking on the variable.  Notice that it is an integer with
  a value of 4.

 Step 4:  View the address of the selected variable.  From the local Others
  menu, select Data Address.  A message box displays the variable's address.
  Press Enter to clear the box.

  The Memory window updates and displays the memory locations around the
  address, formatted as two-byte hexadecimal numbers.

 Step 5:  Make the Memory window active.  Press Ctrl-E.  Notice that the
  selected location indicates the memory location of the variable "numList".

 Step 6:  Change the display format.  From the local View menu, select
  Integer.  The Memory window updates and displays memory in the Integer
  format.  Notice the integer value 4.


5.  Modifying Data
------------------

 This section explains how to modify a variable or a memory location in
 your program.  You will modify the value of the variable first with a
 constant, and then with an expression.


 5.1  Modifying a Variable
 -------------------------

 Step 1:  Make the Data window active.  Press Ctrl-D.

 Step 2:  Select a variable to modify.  Select the variable "numList" by
  clicking on it.

 Step 3:  Change the value of the variable.  From the local Others menu,
  select Modify Value.  MultiScope prompts you to enter an expression for
  the new value.

 Step 4:  Enter a new value.  Type

    123

  and press Enter.  The dialog box disappears, and the variable is updated
  with the new value.

 Step 5:  Replace the value of the variable with an expression.  Press
  Alt-M to open an Expression box.  Type the expression

    TUTOR.count * 3

 The value of "numList" is now 6, as shown in the Data window.


 5.2  Modifying Memory
 ---------------------

 Step 1:  Select the Memory window.  Press Ctrl-E to select the memory
  window without changing the current selection.  (The current selection
  is the memory location of the variable "numList".)

 Step 2:  Modify memory.  Press Alt-M for Modify.  Enter an expression
  for the new value.  Type

    TUTOR.count

  The selected memory location is updated and displays the value you
  entered - the value of the variable "count" in the TUTOR module
  (which is 2).

 Step 3:  Minimize the Memory window.  Click on the minimize icon.


6.  Setting Breakpoints
-----------------------

 Breakpoints are set in your program's source code where you want the
 program's execution to stop.  You can then examine the variables and
 data structures in your program.

 Before you set a breakpoint, you must decide three things:  its location
 in the program, the circumstances that trigger it, and the result of
 triggering it.

 You may also assign a condition to a breakpoint on an expression, which
 is called a conditional breakpoint.  In this section, you will learn how
 to set both an unconditional and a conditional breakpoint.

 A breakpoint is either triggered always when an expression is true or
 when a pass count reaches its limit.  When a breakpoint is triggered,
 the execution of the program stops at that point.

 Breakpoints may be set in either the Source window or the Assembly
 window.  A breakpoint that is set so that it is always triggered when
 it is reached is called an unconditional breakpoint.

 Step 1:  Select the main module.  Double-click on the TUTOR entry
  in the module window to select the TUTOR module.

 Step 2:  Make the Source window active.  Press Ctrl-S.  The Source
  window displays the source code of the module TUTOR.  (Notice the
  header of the Source window.)

 Step 3: Search for a procedure. From the local Find menu, select Find
  Procedure.  MultiScope prompts you for the name of the procedure.
  Type

    BreakMe

  The Source window updates and displays the source code at the location
  of the procedure "BreakMe".

 Step 4:  Select another line.  Click on

    ++count;

 Step 5:  Set a breakpoint.  From the local Bpt menu, select Set
  Breakpoint.  An expression dialog box is displayed.  Press Enter to
  set an unconditional breakpoint.  An asterisk (*) appears to the left
  of the selected line to indicate the presence of a breakpoint.

 Step 6:  Execute the program to the set breakpoint.  From the global
  Go menu, select Breakpoint.  The program executes to the breakpoint.
  When the execution stops, the asterisk (*) is replaced by a number
  sign (#) indicating that the program stopped executing at the
  breakpoint.

 Step 7:  Clear the breakpoint.  From the local Bpt menu, select Clear
  Breakpoint to clear the breakpoint from the selected line.

 Step 8:  Set a conditional breakpoint at the same line.  From the local
  Bpt menu, select Set Breakpoint.  In the expression dialog box, type

    count > 5

 The expression "count > 5" is the breakpoint condition that stops the
 execution of the program when the value of the variable "count" becomes
 greater than 5.

 Step 9:  Execute the program until the breakpoint's condition becomes
  true.  From the global Go menu select Breakpoint.  The * becomes a #,
  indicating that the program stopped at the breakpoint.

  With a conditional breakpoint, the program stops only if the breakpoint
  is passed while the expression is true.  Here the program executes until
  the value of "count" is greater than 5.

 Step 10:  Check the breakpoint's condition.  Press Ctrl-D to make the Data
  window active.  Notice that the value of the variable "count" is greater
  than 5.

 Step 11:  Check the breakpoint's status.  Double-click on the Breakpoint
  icon to restore the window.  (If the icon is hidden, press Ctrl-B to
  make it active.)  Then resize it so that the contents are visible.  The
  Breakpoint window contains the list of all the breakpoints currently
  defined in your program.

  The breakpoint information is displays the module name, procedure name
  line number, address, limit, count, and expression of each breakpoint
  set in the program.

 Step 12:  Kill all breakpoints.  From the local Commands menu, select
  Kill All Breakpoints.  All the breakpoints are cleared from the program.

 Step 13:  Minimize the Breakpoint window.  Click on the minimize icon
  in the Breakpoint window.


7.  Looking at Threads
----------------------

 An OS/2 thread is a task that has its own stack and registers but
 shares its address space with other threads in a process.  The Thread
 window lists all of the threads in a process.  You can use the Thread
 window to examine a thread's status, registers, call chain, data, and
 current execution location.

 Step 1:  Restore the Thread window.  Double-click on the Thread window's
  icon.  (If the icon is hidden, press Ctrl-T to make it active.)  Resize
  it so that its contents are visible.

  The Thread window indicates that there are currently two threads running
  in the program.  Both are thawed and runnable.

 Step 2:  Restore the Register window.  Double-click on the Register
  window's icon to restore it.  (If the icon is hidden, press Ctrl-R
  to make it active.)  Then resize it so that the contents are visible.

 Step 3:  Set the screen.  Arrange the screen so that the Call, Thread,
  Register, Data, and Source windows are visible.

 Step 4:  Select a thread and update the Source, Data, Call, Register,
  and Assembly windows.  Double-click on thread number 2 in the Thread
  window.  The Source, Call, Data, and Register windows update and show
  the state of the execution thread.

 Step 5:  Determine what thread 1 was executing.  It is possible to update
  a window for another thread without updating all the other windows. For
  example, to display the source code where thread 1 executed, select
  thread 1 in the Thread window.  Press Alt-S.  The Source window updates
  and shows where thread 1 stopped executing.

 Step 6:  Minimize the Thread, Register, Data and Call windows.  Click on
  the minimize arrow in the Thread, Register, and Call windows.


8.  Executing Your Program to the End
-------------------------------------

 In the final step of the Run-Time Debugger tutorial, you will execute
 TUTOR.EXE to the end, look at its output, and exit the debugger.

 Step 1:  Execute the program to the end.  From the global Go menu, select
  End Program.  TUTOR executes until it terminates.  A message box is
  displayed indicating that the program ended.  Press Enter to clear the
  message.

 Step 2:  Look at your program's output.  Press Ctrl-O to display the
  Output screen.

 Step 3:  Exit from the debugger.   From the global Program menu, select
  Exit.  MultiScope exits and returns control to OS/2.



Get the Most from MultiScope
============================

 Logitech's MultiScope Debugger offers you the most advanced features
 available in any debugging tool.  This sophisticated program is a
 significant step forward in debugger technology that will make your
 debugging chores much easier. MultiScope is the only debugger
 designed to take full advantage of all the extra functionality of the
 high-powered OS/2 operating environment.

 Use MultiScope to debug the most commonly used OS/2 languages.  Because
 it is so well integrated with OS/2, MultiScope lets you debug even the
 most complex programs quickly and effortlessly.  We've built in both
 run-time and post-mortem debugging options to handle any debugging
 situation: you can examine your program both during and after a run-time
 exception.  You have never before used a tool that provides such a clear
 vision of your program's inner workings.

 MultiScope uses either a Presentation Manager or an OS/2 text mode
 user interface to provide you with the perfect interface for your
 requirements.   Both execution modes are compatible with the Common
 User Access of the IBM Systems Application Architecture for maximum
 ease or learning and use.

 Logitech has created the debugger that finally has the muscle and
 functionality to really get the job done.

* Debug Multiple Languages:

  o IBM C/2
  o IBM Pascal/2
  o IBM Macro Assembler/2
  o Microsoft C
  o Microsoft Pascal
  o Microsoft Assembler
  o Logitech Modula OS/2

* Two Debugging Options:

  o Runtime
     MultiScope allows you to monitor the execution of a program
     with conditional or unconditional breakpoints, and memory or
     symbolic watchdogs.  While you are stepping in your program
     execution, MultiScope allows you to modify memory or data
     contents, suspend or resume thread execution.

  o Post-Mortem
     This debugging mode gives all the MultiScope debugging power
     for examining a program after the occurrence of an OS/2
     protection trap, stack overflow or other run-time exception.

* Graphical Representation:
  Only the Logitech MultiScope Debugger permits the graphical
  representation of your program's data structures.  This feature,
  which operates under Presentation Manager, allows you to explore
  your dynamically allocated data structures and their internal
  relationships.

* Maximum Performance In Two Modes:

  o Presentation Manager Mode
     MultiScope takes full advantage of Presentation Manager's
     graphics, multiple fonts, overlapping windows and standard
     user interface.

  o OS/2 Text Mode
     MultiScope offers a text mode user interface with a very
     easy-to-use windowing system for the EGA and VGA graphic
     adaptors.  This execution mode is the perfect solution for
     debugging Presentation Manager applications.

  Pull down menus that respond to single-key commands make your
  debugging faster and easier.  Create your own custom configuration
  of these windows to see exactly what you need.  Reduced currently
  unused windows to icons for easy recall.


* MultiScope gives you 13 different views into your program:

  o Source View
     Look at source code, set breakpoints, find symbols

  o Data View
     Display and modify local and global symbolic data,
     records, arrays, and set watchpoints

  o Graphic View
     In Presentation Manager mode, see a graphic representation
     of any selected data structure

  o Assembly View
     See the assembly decode of the program, complete with the
     display of corresponding source lines and local and global
     data

  o Thread View
     Observe threads belonging to your application, and suspend
     threads, resume threads, update views according to new threads

  o Breakpoint View
     Display the current breakpoint locations, count and limit

  o Watch View
     Display the current watch variables or memory location

  o Register View
     Display and modify the current value of the CPU registers

  o Output View
     Examine the application screen

  o Module View
     Choose between different data object modules of the
     application and view the corresponding source or data

  o Call View
     Display the source position, local data and parameters of a
     particular call

  o Memory View
     Display raw memory in various formats: byte, char, text,
     unsigned word, signed word, address, double word, real, etc;
     modify memory contents; set watchpoints

  o Log View
     Log debugger events


* MultiScope allows you to execute your program until:

  o the next conditional breakpoint is true
  o the next high level instruction
  o the next line
  o the next assembly instruction
  o the return from the current procedure
  o the next call from a current procedure
  o the next child process load
  o an OS/2 protection violation or other runtime exception

* Evaluate Expressions
  MultiScope allows you to evaluate C, Pascal and Modula-2
  expressions using symbols defined in your program.

* Function Calls
  MultiScope is the only OS/2 debugger which can execute calls to your
  own code during the debugging session.  Use your own procedures to
  print out data structures, or experiment with calls with different
  parameter values.

* Child Process Debugging
  When your program executes another program, MultiScope allows you to
  continue debugging the old process.

* Dynamic Link Libraries
  The full power of MultiScope is available for debugging your dynamic
  link libraries.

* Remote and Dual Monitor Debugging:

  o Remote:
     MultiScope allows you to debug a program executing on another
     computer through a serial line.  This feature allows your
     application to keep all the resources of the computer for its
     execution.

  o Dual Monitor:
     MultiScope allows you to use a second monochrome monitor for
     the display of debugger views while your program is executing.

* System Requirements

  o IBM XT/286, AT, PS/2 model 50, 60, 70, 80 or 100% compatibles
  o OS/2 Standard Edition 1.1 or Extended Edition 1.1
  o One high density diskette drive and hard disk


For More Information on MultiScope
==================================

For more information on MultiScope, please contact:

        Logitech, Inc.
        Attn: Susanne Gahnstedt
        6505 Kaiser Drive
        Fremont, CA 94555

        Tel: [phone]

        Fax: [phone]


----------------------------------------------------------------------

Copyright (C) 1989 Logitech, Inc.  All rights reserved.
Logitech and MultiScope are trademarks of Logitech, Inc.
All other trademarks are the property of their respective owners.