home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 5 / 05.iso / a / a009 / 5.ddi / DOC.LIF / DEBUGGER.DOC next >
Encoding:
Text File  |  1991-04-14  |  172.1 KB  |  6,007 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.                                       
  13.                                       
  14.                             The Clipper Debugger
  15.                                 Version 5.01
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.      The Clipper Debugger
  73.  
  74.         Copyright (C) 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991
  75.         Nantucket Corporation.
  76.         All Rights Reserved.  
  77.         
  78.         No part of this publication may be reproduced, transmitted,
  79.         transcribed, stored in a retrieval system, or translated into
  80.         any other language or computer language in whole or in part,
  81.         in any form or by any means, whether it be electronic,
  82.         mechanical, magnetic, optical, manual or otherwise, without
  83.         prior written consent of Nantucket Corporation, 12555 W.
  84.         Jefferson Blvd., Suite 300, Los Angeles, California 90066.
  85.         
  86.         Clipper 5.0 user documentation is printed in the U.S.A. 
  87.         Nantucket believes that the user documentation (both printed
  88.         and online) accompanying the program contains the necessary
  89.         information to utilize the program.  However, Nantucket
  90.         reserves the right to make revisions and/or periodic changes
  91.         to the user documentation content without the direct or
  92.         inferred obligation of Nantucket to notify any person of such
  93.         revisions or changes.  Except for the limited warranty set
  94.         forth in the applicable Nantucket Software License Agreement
  95.         accompanying this product, the user documentation is provided
  96.         "as is."  Nantucket makes no other warranty, express or
  97.         implied, with respect to the software and/or user
  98.         documentation, and specifically disclaims the implied
  99.         warranties of merchantability and fitness for a particular
  100.         purpose.  Nantucket does not warrant that the software and/or
  101.         user documentation will meet your requirements or that the
  102.         operation/use of the software and/or user documentation will
  103.         be uninterrupted or error free.  You are solely responsible
  104.         for the selection of the software and/or user documentation to
  105.         achieve your intended results and for the results actually
  106.         obtained.  Except as specifically set forth in the applicable
  107.         Nantucket Software License Agreement accompanying this
  108.         product, Nantucket does not assume responsibility for the use
  109.         of the software and/or user documentation. 
  110.         
  111.         The software contains valuable copyrights, trade secrets and
  112.         proprietary information all of which are reserved by Nantucket
  113.         and subject only to the license granted herein.  Unauthorized
  114.         use of the documentation or the software can result in civil
  115.         damages and criminal prosecution.  Please refer to the
  116.         applicable Nantucket Software License Agreement accompanying
  117.         this product for additional information.
  118.         
  119.      Copyright, Trademark and Service Mark Notices
  120.  
  121.         Nantucket (R), the Nantucket logo, and Clipper (R) are
  122.         registered trademarks of Nantucket Corporation.  Nantucket
  123.         News (TM) is a trademark of Nantucket Corporation.  Nantucket
  124.         Support (sm) is a service mark of Nantucket Corporation.  The
  125.         Guide To Clipper (R) is a product of Nantucket Corporation.
  126.         
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.         dBASE (R), dBASE III (R), dBASE IV (R) and Ashton-Tate (R) are
  140.         registered trademarks of Ashton-Tate Corporation.  dBASE III
  141.         PLUS (TM) is a trademark of Ashton-Tate Corporation.
  142.         IBM (R), PC-DOS (R) and PC-AT (R) are registered trademarks of
  143.         International Business Machines Corporation.
  144.         Intel (R) is a registered trademark of Intel Corporation.
  145.         Microsoft (R) is a registered trademark of Microsoft
  146.         Corporation.
  147.         Microsoft (R) C Runtime Library Routines, (C) Microsoft
  148.         Corporation 1984, 1985, 1986, 1987.  All Rights Reserved.
  149.         MS-DOS (R) is a registered trademark of Microsoft Corporation.
  150.         MASM (TM) is a trademark of Microsoft Corporation.
  151.         The Norton Instant Access Engine (TM) is a trademark of Peter
  152.         Norton Computing Incorporated.
  153.         .RTLINK (TM), (C) Pocket Soft, Inc., 1988, 1989.  .RTLink is a
  154.         trademark of Pocket Soft Inc.
  155.         
  156.         Trademarks of other companies mentioned in this documentation
  157.         appear for identification purposes only.
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.      Credits
  207.  
  208.         Software Development
  209.         
  210.           Architect
  211.             Richard McConnell
  212.           
  213.           Primary Developers 
  214.             Dennis L. Dias
  215.             Basil Hosmer
  216.             Richard McConnell
  217.           
  218.           Key Contributors
  219.             Brian Russell (architecture and implementation)
  220.             Eric Jakstadt (linker)
  221.             Corey Schwartz (debugger)
  222.             Leonard Zerman (install system)
  223.  
  224.         Documentation 
  225.  
  226.             Christopher White
  227.             Deborah Ridolfo
  228.             Debby Moody
  229.             Savannah Brentnall
  230.             
  231.           Key Contributors
  232.             Charles R. Gehman (desktop publishing) 
  233.  
  234.           Administration
  235.             Dana Wood
  236.  
  237.         Software Test
  238.  
  239.             Phil Usher
  240.             Ed Bell
  241.             Tom Chang
  242.             Woon L. Leong
  243.             Tim Wong
  244.             Fred Ho
  245.             Jon Rognerud
  246.  
  247.      Special thanks to the beta test sites and documentation reviewers
  248.      whose efforts and patience helped make Clipper 5.01 a reality.
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.      ==================================================================
  274.                              Table of Contents
  275.  
  276.      ------------------------------------------------------------------
  277.  
  278.           Chapter 1:  Introduction to the Debugger............1-1
  279.           
  280.           Chapter 2:  Starting the Debugger...................2-1
  281.           
  282.           Chapter 3:  The Debugger Display....................3-1
  283.           
  284.           Chapter 4:  Debugging a Program.....................4-1
  285.           
  286.           Chapter 5:  Command Reference.......................5-1
  287.           
  288.           Glossary
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.      ==================================================================
  341.      Chapter 1:  Introduction to the Debugger
  342.  
  343.      ------------------------------------------------------------------
  344.  
  345.           In This Chapter                   1-1
  346.           
  347.           What is a Debugger?               1-1
  348.           
  349.           Symbols and Conventions           1-2
  350.           
  351.           System Requirements               1-2
  352.           
  353.           What does The Clipper
  354.           Debugger do?                      1-2
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.          Chapter 1 -- Introduction to the Debugger
  407.  
  408.          Welcome to The Clipper Debugger.  Although you may already be
  409.          familiar with the process of debugging a compiled
  410.          application, we recommend that you take the time to read this
  411.          chapter.  The terms used throughout this manual are explained
  412.          here, together with a list of requirements for using the
  413.          Debugger and descriptions of some of the most commonly used
  414.          features.  
  415.  
  416.  
  417.       -----------------------------------------------------------------
  418.       In This Chapter
  419.  
  420.          This chapter provides a brief overview of the Debugger and
  421.          explains some of its most powerful features.  The following
  422.          topics are covered:
  423.  
  424.          *  What is a Debugger?
  425.  
  426.          *  Symbols and conventions
  427.  
  428.          *  System requirements
  429.  
  430.          *  What does The Clipper Debugger do?
  431.  
  432.  
  433.       -----------------------------------------------------------------
  434.       What is a Debugger?
  435.  
  436.          Once you have finished writing a program, it must be tested
  437.          to make sure there are no errors.  Some errors will be
  438.          spotted by the compiler or linker; in these cases,
  439.          corrections can be made without having to actually execute
  440.          the program.
  441.  
  442.          It is not at all unusual for a program to contain errors
  443.          which can only be spotted while the program is running.  This
  444.          is where a debugger becomes useful.  As its name suggests, a
  445.          Debugger is a tool that helps you track down and remove
  446.          errors (bugs) from your source code.
  447.  
  448.          The Clipper Debugger allows you to look at your source code
  449.          while your program is running.  Whenever you notice an error,
  450.          simply edit the code, re-compile, re-link, and try again. 
  451.          You may need to perform these steps several times.
  452.  
  453.          Other features of the Debugger include watching the values of
  454.          variables and expressions as your program executes, examining
  455.          database (.dbf) files and executing your program slowly, a
  456.          line at a time.
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.                                                    Introduction    1-1
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.       -----------------------------------------------------------------
  474.       Symbols and Conventions
  475.  
  476.          In order to specify commands in a general way, certain
  477.          symbols are used to identify special behavior.  For example,
  478.          keywords and metasymbols in square brackets are optional. 
  479.          The following table shows a list of symbols used throughout
  480.          this manual:
  481.  
  482.          Table 1-1: Symbols
  483.          --------------------------------------------------------------
  484.          Symbol   Description
  485.          --------------------------------------------------------------
  486.          < >      Indicates an item that is entered by the user
  487.          [ ]      Indicates an optional item or list
  488.           |       Indicates two or more mutually exclusive options
  489.          --------------------------------------------------------------
  490.  
  491.  
  492.       -----------------------------------------------------------------
  493.       System Requirements
  494.  
  495.          *  At least one disk drive
  496.  
  497.          *  512K of RAM memory
  498.  
  499.          *  Clipper 5.0
  500.  
  501.          *  DOS version 2.0 or greater
  502.  
  503.          The Debugger will work on any IBM PC or compatible.  At least
  504.          one disk drive is needed for installation, and a hard disk is
  505.          recommended.  Your computer should have at least 512K of
  506.          memory, but 640K or more is preferred for best results.  The
  507.          operating system must be DOS version 2.0 or higher.
  508.  
  509.  
  510.       -----------------------------------------------------------------
  511.       What does The Clipper Debugger do?
  512.  
  513.          There are certain features in The Clipper Debugger that you
  514.          will find yourself using over and over again.  This section
  515.          is intended as a quick guide to each of these features; more
  516.          detailed explanations can be found in Chapter 3, The Debugger
  517.          Display and Chapter 5, Command Reference.
  518.  
  519.  
  520.          --------------------------------------------------------------
  521.          Trace Source Code Line by Line
  522.  
  523.          When you run a program from within the Debugger, the source
  524.          code is displayed inside a window called the Code Window.  A
  525.          horizontal Execution Bar highlights each line of code as it
  526.          is executed, allowing you to see the progress of your
  527.  
  528.  
  529.  
  530.  
  531.  
  532.                                                    Introduction    1-2
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.          application.  This can often help eliminate logic or looping
  541.          errors.  The speed of the display can be controlled to suit
  542.          your needs.
  543.  
  544.  
  545.          --------------------------------------------------------------
  546.          Inspect the Values of Variables and Expressions
  547.  
  548.          While debugging your application, you may want to examine a
  549.          memory or field variable.  This is called inspecting a
  550.          variable.  Using a highlight bar, the Debugger allows you to
  551.          select from a list of variables and enter a new value for
  552.          your selection.  This value is then assigned to the variable
  553.          you selected.
  554.  
  555.          In addition, any valid expression can be inspected.  This
  556.          includes Clipper functions, code blocks, macro expressions
  557.          and user-defined functions.  In these cases, the specified
  558.          code is actually executed, and the return value displayed. 
  559.  
  560.  
  561.          --------------------------------------------------------------
  562.          Create New Variables
  563.  
  564.          Often, an error in your application is caused by the failure
  565.          to create a particular variable.  Using the ?|?? command and
  566.          the := operator, the Debugger allows you to create a new
  567.          PRIVATE variable and assign it a value.  You can then
  568.          continue debugging, and correct the error on your next
  569.          edit/compile/link cycle.
  570.  
  571.  
  572.          --------------------------------------------------------------
  573.          Execute Linked Procedures and Functions
  574.  
  575.          Any procedure or function which has been compiled and linked
  576.          with your application can be executed during a debugging
  577.          session.  This provides an easy way to extend the
  578.          functionality of the Debugger: simply write a function to
  579.          perform the desired action, re-compile, re-link, and execute.
  580.  
  581.  
  582.          --------------------------------------------------------------
  583.          Inspect Work Areas and Set Values
  584.  
  585.          There may be times when you need to examine the structure of
  586.          a database (.dbf) file.  The Debugger uses the View Workareas
  587.          Window to provide this information.  The names of the
  588.          databases open in each work area are shown on the left pane
  589.          of the window with the currently selected file enclosed in
  590.          angle brackets (< >).  The work area flag settings and file
  591.          structure for the highlighted filename appear on the right.
  592.  
  593.          There is a similar window called the View Sets Window that
  594.          allows you to inspect and change the status of Clipper SET
  595.          commands.
  596.  
  597.  
  598.  
  599.                                                    Introduction    1-3
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.      ==================================================================
  608.      Chapter 2:  Starting the Debugger
  609.  
  610.      ------------------------------------------------------------------
  611.  
  612.           In This Chapter                   2-1
  613.           
  614.           Preparing your Programs for
  615.           Debugging                         2-1
  616.           
  617.           Invoking the Debugger             2-4
  618.           
  619.           How the Debugger Searches
  620.           for Files                         2-7
  621.           
  622.           Using a Script File               2-7
  623.           
  624.           Getting Help                      2-8
  625.           
  626.           Leaving the Debugger              2-9
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.          Chapter 2 -- Starting the Debugger
  674.  
  675.          In order to debug an application, you must first create your
  676.          executable (.EXE) file using the compiler option for
  677.          debugging.  You can then invoke the Debugger and begin the
  678.          debugging session.  Some parts of your application may
  679.          require source code changes in order to be properly debugged;
  680.          each of these changes is explained here.
  681.  
  682.  
  683.       -----------------------------------------------------------------
  684.       In This Chapter
  685.  
  686.          This chapter explains the compilation process, necessary
  687.          program changes and some techniques to increase debugging
  688.          speed.  The following topics are covered:
  689.  
  690.          *  Preparing your programs for debugging
  691.  
  692.          *  Invoking the Debugger
  693.  
  694.          *  How the Debugger searches for files
  695.  
  696.          *  Using a script file
  697.  
  698.          *  Getting help
  699.  
  700.          *  Leaving the Debugger
  701.  
  702.  
  703.       -----------------------------------------------------------------
  704.       Preparing Your Programs for Debugging
  705.  
  706.          To take full advantage of the features offered by The Clipper
  707.          Debugger, there are certain changes you may want to make to
  708.          your source code.  This section describes these changes,
  709.          together with an explanation of the compilation process.
  710.  
  711.  
  712.       Compiling Your Source Code
  713.  
  714.          The first step in debugging an application with the Debugger
  715.          is to compile using the /B compiler option.  This option
  716.          tells the compiler to include debugging information in the
  717.          object (.OBJ) file.  For example:
  718.  
  719.          CLIPPER MainProg /B
  720.          
  721.          In this example, all programs called by MainProg.prg are also
  722.          compiled with the /B option.  If, however, you have used
  723.          (.clp) files or have compiled each program in your
  724.          application separately, you must specify the /B option every
  725.          time you invoke the compiler.  During the debugging session,
  726.          any subsidiary programs which have been compiled without this
  727.          option are ignored.
  728.  
  729.  
  730.  
  731.  
  732.                                           Starting the Debugger    2-1
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.          --------------------------------------------------------------
  741.          Warning
  742.  
  743.          In order to use The Clipper Debugger, your application must
  744.          be compiled with Clipper 5.0.
  745.          --------------------------------------------------------------
  746.  
  747.  
  748.       Programming Considerations
  749.  
  750.          Certain parts of your code present special problems when
  751.          debugging.  This section explains the techniques for
  752.          debugging multi-statement command-lines, header files,
  753.          manifest constants, pseudo-functions, code blocks and macros.
  754.  
  755.  
  756.          --------------------------------------------------------------
  757.          Multi-statement Command-lines
  758.  
  759.          Clipper 5.0 allows you to place more than one program
  760.          statement on a single line.  For example:
  761.  
  762.          nNewPage = (nLineNo > 55); ReportPage(nNewPage)
  763.          
  764.          When you use Uparrow or Dnarrow in the Code Window, the
  765.          cursor moves up and down one complete line at a time.  This
  766.          is true regardless of how many statements are on the line in
  767.          question.  In the above example, the Debugger does not allow
  768.          you to "step" through the first and second statements
  769.          independently, nor does it allow you to set a Breakpoint at
  770.          either statement.  The entire line is treated as a single
  771.          entity.
  772.  
  773.          The code in the above example should be broken up into two
  774.          lines, as follows:
  775.  
  776.          nNewPage = (nLineNo > 55)
  777.          ReportPage(nNewPage)
  778.          
  779.          This makes debugging easier, and also makes the code more
  780.          readable.
  781.  
  782.  
  783.          --------------------------------------------------------------
  784.          Header Files
  785.  
  786.          Header files are files which are referenced using the
  787.          #include pre-processor directive.  They typically contain
  788.          manifest constant and pseudo-function definitions, but can
  789.          also contain program source code.
  790.  
  791.          To view a header file, press Alt-F to access the File menu,
  792.          and select the Open option.  A dialog box is displayed and
  793.          you are asked to enter the name of the file you want to
  794.  
  795.  
  796.  
  797.  
  798.  
  799.                                           Starting the Debugger    2-2
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.          view.  Simply enter the name of the header file and its
  808.          extension, and press Return.  The code for the specified
  809.          header file appears in the Code Window.
  810.  
  811.  
  812.          --------------------------------------------------------------
  813.          Manifest Constants and Pseudo-functions
  814.  
  815.          Constants and pseudo-functions defined with the #define
  816.          pre-processor directive cannot be inspected in the same way
  817.          as variables and expressions.  As their name suggests,
  818.          pre-processor directives are instructions to the
  819.          pre-processor and do not exist at runtime.  If you compile a
  820.          program using the /P compiler option, a file with a (.ppo)
  821.          extension is produced.  This file shows the pre-processor
  822.          output, and can be viewed using the Preprocessed Code option
  823.          on the Options menu.  When this menu option is selected
  824.          (indicated by a check mark) each line of source code is
  825.          displayed in the Code Window with the output from the
  826.          pre-processor shown underneath.
  827.  
  828.  
  829.          --------------------------------------------------------------
  830.          Code Blocks
  831.  
  832.          A code block contains executable program code which is
  833.          treated by Clipper 5.0 as data and can be passed as a
  834.          parameter to other programs.  This program code is compiled
  835.          at compile-time, and inspecting the code block only reveals
  836.          its name, not the actual code.  However, code blocks can be
  837.          executed from within the Debugger as follows:
  838.  
  839.          > ? EVAL(bMyBlock) <Return>
  840.          
  841.          This example, when entered in the Command Window, causes the
  842.          code block bMyBlock to be evaluated.  Any code within
  843.          bMyBlock is executed and displayed accordingly.
  844.  
  845.          When "stepping" through a piece of code containing a code
  846.          block, the Execution Bar moves to the line of code where the
  847.          block was created each time the code block is evaluated. 
  848.          This allows you to see the contents of the block (which are
  849.          unavailable during normal inspection), and occurs regardless
  850.          of whether the block was declared in the current routine.
  851.  
  852.  
  853.          --------------------------------------------------------------
  854.          Macro Substitution
  855.  
  856.          The Debugger treats macros as ordinary character strings.  As
  857.          such, they can be inspected or viewed using the ?|??
  858.          command.  For example:
  859.  
  860.          > ? ¯oVar <Return>
  861.          
  862.  
  863.  
  864.  
  865.  
  866.                                           Starting the Debugger    2-3
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.          displays the contents of the expanded macro variable
  875.          macroVar.
  876.  
  877.          If the macro variable refers to a code block, the ?|??
  878.          command merely displays the code block symbol: "{||...}." 
  879.          Since the code contained within the code block was compiled
  880.          at compile-time, it is not available to The Clipper Debugger.
  881.  
  882.  
  883.       -----------------------------------------------------------------
  884.       Invoking the Debugger
  885.  
  886.          There are several ways to invoke the Debugger, each of which
  887.          is discussed below.  All of the methods require that the
  888.          application be compiled with the /B option--debugging is not
  889.          possible otherwise.
  890.          
  891.          
  892.       From DOS
  893.  
  894.          To invoke the Debugger from the DOS prompt, use the following
  895.          syntax:
  896.  
  897.          CLD [[/43 | /50 | /S] [@<scriptFile>]
  898.             <exeFile> [<argument list>]]
  899.          
  900.          CLD.EXE is The Clipper Debugger executable file.  If you
  901.          installed the Clipper 5.0 development system using the
  902.          default configuration, CLD.EXE is located in the
  903.          \CLIPPER5\BIN directory and your DOS PATH should be altered
  904.          accordingly.
  905.  
  906.          /43 | /50 | /S specifies the screen mode used by the
  907.          Debugger.  These three options are mutually exclusive and, if
  908.          more than one is specified, CLD.EXE uses the last one that
  909.          occurs on the command-line.  The default screen mode is 25
  910.          lines, with the Debugger using the entire screen.
  911.  
  912.          /43 specifies 43 line mode and is available on EGA monitors
  913.          only.
  914.  
  915.          /50 specifies 50 line mode and is available on EGA and VGA
  916.          monitors only.
  917.  
  918.          /S is available on EGA and VGA monitors only.  This option
  919.          splits the screen between your application and the Debugger,
  920.          allowing you to view the application and the Debugger
  921.          simultaneously.  On a VGA monitor /S uses 50 line mode, and
  922.          on an EGA monitor it uses 43 line mode.  In split screen
  923.          mode, the top 25 lines of the screen are used by your
  924.          application, and the remaining lines are used for the
  925.          Debugger display.  In this mode, you cannot move or size
  926.          windows in the Debugger.
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.                                           Starting the Debugger    2-4
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.          <scriptFile> is the name of a script file with a default
  942.          extension of (.cld).  CLD searches for the specified
  943.          <scriptFile> in the current directory and then searches the
  944.          DOS PATH.  A script file is simply an ASCII text file
  945.          containing one or more Debugger commands, with each command
  946.          appearing on a separate line.  When the Debugger is invoked
  947.          with a script file, each command in the file is executed
  948.          automatically after the <exeFile> file is loaded.
  949.  
  950.          In addition to any script file called for on the CLD
  951.          command-line, the Debugger automatically searches for a
  952.          script file with the name Init.cld.  If a file by this name
  953.          is located in the current directory or anywhere in the DOS
  954.          PATH, the Debugger executes it as a script file.  If both
  955.          Init.cld and a command-line script file are present, Init.cld
  956.          is executed first followed by the command-line script file.
  957.  
  958.          <exeFile> is the name of the executable (.EXE) file you want
  959.          to debug.  CLD searches for the <exeFile> in the current
  960.          directory only--the DOS PATH is not searched.  If this file
  961.          has not been compiled using the /B compiler option to embed
  962.          debugging information, debugging is not possible.
  963.  
  964.          <argument list> is the argument list for <exeFile>.
  965.  
  966.          Note that with the exception of the argument list, all other
  967.          CLD arguments must come before the executable filename on the
  968.          command-line.  If no command-line arguments are specified,
  969.          CLD displays a brief help screen.
  970.          
  971.          
  972.       Linking the Debugger
  973.  
  974.          Under certain circumstances, you may want to link the
  975.          Debugger into your application.  Doing this would allow you,
  976.          for example, to debug a program at a customer's site in the
  977.          event that an unforeseen problem occurred after the
  978.          application was already in the field.
  979.  
  980.          The Debugger library, CLD.LIB, must be linked into your
  981.          program as an object file as in the following example:
  982.  
  983.          C>RTLINK FI Myprog, \CLIPPER5\LIB\CLD.LIB <Return>
  984.          
  985.          Again, your program must be compiled with the /B option. 
  986.          When the Debugger is linked into a program in this manner, it
  987.          does not come up automatically but must be invoked.
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.                                           Starting the Debugger    2-5
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.          --------------------------------------------------------------
  1009.          Invoking with Alt-D
  1010.  
  1011.          When an application is linked with CLD.LIB as one of the
  1012.          object files, the Debugger is enabled and can be invoked by
  1013.          pressing Alt-D while the application is running.  Doing this
  1014.          invokes the Debugger with the Execution Bar positioned on the
  1015.          current line of executing code.
  1016.  
  1017.  
  1018.       Using ALTD()
  1019.  
  1020.          The ALTD() function serves two purposes: it allows you to
  1021.          control whether or not the Debugger is enabled or disabled,
  1022.          and it allows you to invoke the Debugger if it is enabled. 
  1023.          ALTD() can be used regardless of whether the Debugger is
  1024.          invoked using the CLD command-line or using Alt-D.
  1025.  
  1026.          When it appears in a program compiled with the /B option,
  1027.          ALTD() used with no arguments acts like a Breakpoint by
  1028.          stopping the application and giving control to the Debugger.
  1029.  
  1030.          ALTD(0) temporarily disables the Debugger so that any code
  1031.          following the function call is executed as if the Debugger
  1032.          were not present.  When the Debugger is disabled, all
  1033.          Breakpoints and Tracepoints are ignored and even calls to
  1034.          ALTD() and pressing Alt-D will not invoke the Debugger while
  1035.          it is disabled.
  1036.  
  1037.          ALTD(1) is used to enable the Debugger again.  Note that for
  1038.          programs compiled with /B, the default state for the Debugger
  1039.          is enabled.
  1040.  
  1041.          For applications that are linked with CLD.LIB, you can use
  1042.          ALTD() to prevent the user for inadvertently invoking the
  1043.          Debugger.  By including code similar to the following at the
  1044.          beginning of the main program, the ability to invoke the
  1045.          Debugger is controlled by the presence a command-line
  1046.          parameter:
  1047.  
  1048.          PARAMETERS dBug
  1049.          
  1050.          IF dBug != NIL
  1051.            ALTD(1)            // Invoke Debugger with ALTD() or Alt-D
  1052.          ELSE
  1053.            ALTD(0)            // Debugger cannot be invoked
  1054.          ENDIF
  1055.          
  1056.          Using the code shown above, the Debugger is disabled unless
  1057.          the application is invoked with an argument.  Even though the
  1058.          program may contain calls to ALTD() and the user may press
  1059.          Alt-D, the Debugger cannot be invoked unless the application
  1060.          command-line argument is specified.  If your application
  1061.          accepts other arguments, use dBug as the last one in the
  1062.          list.
  1063.  
  1064.  
  1065.  
  1066.  
  1067.                                           Starting the Debugger    2-6
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.       -----------------------------------------------------------------
  1077.       How the Debugger Searches for Files
  1078.  
  1079.          When you make a file open request to the Debugger, you may
  1080.          specify the drive, directory and file extension explicitly as
  1081.          part of the filename.  Otherwise, the Debugger makes certain
  1082.          assumptions about the filename and location.
  1083.  
  1084.          Depending on the context of the file open request, the
  1085.          default file extension supplied by the Debugger varies.  For
  1086.          example, when the request is for a script file the Debugger
  1087.          assumes a (.cld) extension and for a pre-processed output
  1088.          file the default extension is (.ppo).  Default file
  1089.          extensions are supplied only when you do not specify an
  1090.          explicit file extension.
  1091.  
  1092.          If no explicit file location (i.e., drive or directory) is
  1093.          specified or if the file location cannot be obtained from the
  1094.          application, the Debugger looks for the file in the current
  1095.          directory.   Then, with the exception of the .EXE file, the
  1096.          Debugger searches the DOS PATH--the Debugger searches for the
  1097.          executable file in the current directory only.  Only after
  1098.          these locations are exhausted will an error message be
  1099.          displayed indicating that the file could not be found.
  1100.  
  1101.  
  1102.       -----------------------------------------------------------------
  1103.       Using a Script File
  1104.  
  1105.          The Debugger allows you to record commands in a script file
  1106.          and execute the commands directly from the file.  A script
  1107.          file is simply an ASCII text file that can be created and
  1108.          edited using any word processor.  The file consists of one or
  1109.          more Debugger commands, with each command on a new line in
  1110.          the file and has a default extension of (.cld).
  1111.  
  1112.          Some programs may require several debug/edit/compile/link
  1113.          cycles in order to trace persistent errors.  Recording
  1114.          repetitive commands in a script file eliminates the amount of
  1115.          typing necessary to reach the same position in your
  1116.          application each time.  For example, the following script
  1117.          file sets a Breakpoint at the first call to the function
  1118.          ViewData(), designates the variables lMadeChanges and
  1119.          lSaveChanges as Watchpoints, and specifies nFieldNum and
  1120.          nFileArea as Tracepoints:
  1121.  
  1122.          BP ViewData
  1123.          WP lMadeChanges
  1124.          WP lSaveChanges
  1125.          TP nFieldNum
  1126.          TP nFileArea
  1127.          
  1128.          Another advantage to using script files is to record
  1129.          preferred Debugger settings so that you do not have to set
  1130.          them each time you debug.  The easiest way to record option
  1131.  
  1132.  
  1133.  
  1134.                                           Starting the Debugger    2-7
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.          settings in a script file is to set them using the Debugger
  1143.          menus.  Then, select the Save Settings option from the
  1144.          Options menu and enter a filename when prompted.  The script
  1145.          file is saved to disk and can be used or modified at any
  1146.          time.
  1147.  
  1148.          The settings that you can save in this way include most
  1149.          Options menu settings, the Monitor menu settings, and case
  1150.          sensitivity and Callstack status.  As an alternative to
  1151.          setting the options and saving them to a script file using
  1152.          the Options menu, you can include the appropriate menu
  1153.          commands in any script file.  Menu commands are formed using
  1154.          the menu name followed by the first word of the menu option
  1155.          you want to set.  Any necessary arguments are placed at the
  1156.          end of the command.  An example of some menu command settings
  1157.          recorded in a script file follows:
  1158.  
  1159.          Locate Case
  1160.          Monitor Local
  1161.          View Callstack
  1162.          Options Line
  1163.          Options Tab 3
  1164.          
  1165.          When the Debugger is active, you can execute a script file
  1166.          with the View Restore option in the Options menu or with the
  1167.          INPUT command as in the following example:
  1168.  
  1169.          > INPUT MyScript <Return>
  1170.          
  1171.          You can also execute a script file from the Debugger
  1172.          command-line as in the following example:
  1173.  
  1174.          C>CLD @MyScript MainProg <Return>
  1175.          
  1176.          Each time the Debugger is invoked, it automatically searches
  1177.          for a script file with the name Init.cld.  If a file by this
  1178.          name is located in the current directory or anywhere in the
  1179.          DOS PATH, the Debugger executes it as a script file.  If both
  1180.          Init.cld and a command-line script file are present, Init.cld
  1181.          is executed first followed by the command-line script file.
  1182.  
  1183.  
  1184.       -----------------------------------------------------------------
  1185.       Getting Help
  1186.  
  1187.          The Clipper Debugger offers on-line help in the form of the
  1188.          Help Window, which is divided into two panes: the left pane
  1189.          contains a list of topics for which help is available, and
  1190.          the right pane contains the help text for the currently
  1191.          highlighted topic.  You can activate the Help Window by using
  1192.          the Help menu, pressing F1, or entering the HELP command.
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.                                           Starting the Debugger    2-8
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.          There are several main topics of discussion in the Help
  1210.          Window including About Help, Keys, Windows, Menus, and
  1211.          Commands.  When the Help Window is first activated, one of
  1212.          these topics is highlighted on the left, and the text on the
  1213.          right discusses the topic.
  1214.  
  1215.          To get help on a particular topic, highlight it using Uparrow
  1216.          or DnArrow.  As the highlight moves, the associated help text
  1217.          on the right changes to reflect the current topic.
  1218.  
  1219.          If the indicator at the bottom right of the window shows more
  1220.          than one page of information, use PgUp and PgDn to scroll the
  1221.          help text.
  1222.  
  1223.          Press Esc to remove the Help Window and continue debugging.
  1224.  
  1225.          For more information on the Help Window, see Chapter 3, The
  1226.          Debugger Display.
  1227.  
  1228.  
  1229.       -----------------------------------------------------------------
  1230.       Leaving the Debugger
  1231.  
  1232.          When you have finished your debugging session, select the
  1233.          Exit option from the File menu, press Alt-X, or enter the
  1234.          QUIT command.  The Debugger automatically closes all files
  1235.          and returns you to the DOS prompt.
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.                                           Starting the Debugger    2-9
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.      ==================================================================
  1277.      Chapter 3:  The Debugger Display
  1278.  
  1279.      ------------------------------------------------------------------
  1280.  
  1281.           In This Chapter                   3-1
  1282.           
  1283.           The Debugger Windows              3-1
  1284.           
  1285.           Dialog Boxes                      3-11
  1286.           
  1287.           The Debugger Menus                3-11
  1288.           
  1289.           The Function Keys                 3-28
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.          Chapter 3 -- The Debugger Display
  1343.  
  1344.          Before you can make full use of The Clipper Debugger, you
  1345.          must be familiar with the various windows, menus and function
  1346.          keys on which the debugging environment is based.  This
  1347.          chapter provides an explanation and illustration of each of
  1348.          these components.
  1349.  
  1350.  
  1351.       -----------------------------------------------------------------
  1352.       In This Chapter
  1353.  
  1354.          This chapter describes each of the windows, boxes, menus and
  1355.          keys that constitute the main display.  The topics covered
  1356.          are:
  1357.  
  1358.          *  The Debugger windows
  1359.  
  1360.          *  Dialog boxes
  1361.  
  1362.          *  The Debugger menus
  1363.  
  1364.          *  Function keys
  1365.  
  1366.  
  1367.       -----------------------------------------------------------------
  1368.       The Debugger Windows
  1369.  
  1370.          The Debugger display is based on a series of windows, each
  1371.          with a unique purpose.  The following table gives the name
  1372.          and a brief description of each of these windows:
  1373.  
  1374.          Table 3-1: The Debugger Windows
  1375.          --------------------------------------------------------------
  1376.          Window Name             Purpose
  1377.          --------------------------------------------------------------
  1378.          Callstack Window        Display the Callstack
  1379.          Code Window             Display program code
  1380.          Command Window          Display commands and their results
  1381.          Help Window             Display help information
  1382.          Monitor Window          Display monitored variables
  1383.          Set Color Window        Display and modify color settings
  1384.          View Sets Window        Display and modify SET values
  1385.          View Work Area Window   Display work area and (.dbf)
  1386.                                  information
  1387.          Watch Window            Display Watchpoints and Tracepoints
  1388.          --------------------------------------------------------------
  1389.          
  1390.          Windows are used to display program code, enter commands and
  1391.          offer help.  The following sections explain the various
  1392.          windows and their functions.
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.                                            The Debugger Display    3-1
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.       Window Operations
  1410.  
  1411.          This section describes the general behavior of windows that
  1412.          appear on the main Debugger screen (i.e., Code, Command,
  1413.          Monitor, Watch, and Callstack), including the processes of
  1414.          sizing and moving between windows.
  1415.  
  1416.  
  1417.          --------------------------------------------------------------
  1418.          Navigating Between Windows
  1419.  
  1420.          Of all the windows on the main screen, one is said to be the
  1421.          active window and the rest are inactive.  When you select a
  1422.          window, you make it the active window.  The active window is
  1423.          indicated by a highlighted border; inactive windows have a
  1424.          single-line border.  To move back and forth between windows,
  1425.          use Tab and Shift-Tab.
  1426.  
  1427.          Tab selects the next window on the screen.  Shift-Tab selects
  1428.          the previous window.  These keystrokes are equivalent to the
  1429.          Next and Prev selections in the Windows menu.  The order of
  1430.          the windows is as follows: Code, Monitor, Watch, Callstack,
  1431.          Command.
  1432.  
  1433.          When a window is active, any valid keystrokes affect only
  1434.          that window.  For example, when the Monitor Window is active,
  1435.          pressing Dnarrow moves the highlight bar to the next variable
  1436.          in the list of monitored variables, but does not affect the
  1437.          cursor or highlight bar in any other window.
  1438.  
  1439.          The exception to this rule is that a command can be typed and
  1440.          executed from any active window.  For example if you type
  1441.          "LIST BP" while the Code Window is active, the command will
  1442.          appear in the Command Window next to the > prompt as you are
  1443.          typing.  As soon as you press Return, the command will be
  1444.          executed and the result displayed in the Command Window. 
  1445.          Furthermore, Return always executes the command pending in
  1446.          the Command Window (if any), taking precedence over the
  1447.          normal operation of the Return key for the active window.
  1448.  
  1449.  
  1450.          --------------------------------------------------------------
  1451.          Iconizing
  1452.  
  1453.          Any window on the screen can be effectively put out of sight
  1454.          without actually closing the window.  For example, if the
  1455.          Callstack Window is open and you are not interested in its
  1456.          contents for the moment, you could shrink it down so small
  1457.          that only the window name would be visible.
  1458.  
  1459.          This process, called iconizing, is accomplished by selecting
  1460.          the Window:Iconize menu option.  The active window is
  1461.          replaced by an icon (its name), and you can no longer see the
  1462.          contents of the window.  When a window is iconized, certain
  1463.          window operations, such as sizing, are not available.
  1464.  
  1465.  
  1466.  
  1467.  
  1468.                                            The Debugger Display    3-2
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.          --------------------------------------------------------------
  1477.          Zooming
  1478.  
  1479.          To zoom the active window to full screen, simply press F2. 
  1480.          When a window is zoomed, other window operations such as
  1481.          moving and sizing are not allowed.
  1482.  
  1483.          F2 acts as a toggle between the full screen and window
  1484.          display modes so that when the active window is zoomed to
  1485.          full screen, pressing F2 resumes the original window
  1486.          display.  F2 is equivalent to the Windows:Zoom menu option.  
  1487.  
  1488.  
  1489.          --------------------------------------------------------------
  1490.          Sizing
  1491.  
  1492.          The height and width of all Debugger windows is determined by
  1493.          the display mode and which windows are open at any given
  1494.          time.  The size of a window, however, can be changed to suit
  1495.          your particular needs.  The following table lists some
  1496.          shortcut keys for changing the height of a window:
  1497.  
  1498.          Table 3-2: Sizing Windows
  1499.          --------------------------------------------------------------
  1500.          Key      Action
  1501.          --------------------------------------------------------------
  1502.          Alt-G    Grow active window by one line
  1503.          Alt-S    Shrink active window by one line
  1504.          Alt-D    Shrink Command Window by one line
  1505.          Alt-U    Grow Command Window by one line
  1506.          --------------------------------------------------------------
  1507.          
  1508.          The Windows:Size menu option allows you to change both the
  1509.          height and the width of the active window.  When you select
  1510.          this option, the border of the active window changes to a
  1511.          different pattern and the cursor keys are used to change the
  1512.          size of the window.  Return completes the sizing.
  1513.  
  1514.          --------------------------------------------------------------
  1515.          Note
  1516.  
  1517.          Windows cannot be sized if you are running the Debugger in
  1518.          split screen mode.
  1519.          --------------------------------------------------------------
  1520.  
  1521.  
  1522.          --------------------------------------------------------------
  1523.          Moving
  1524.  
  1525.          The location of all Debugger windows is determined by the
  1526.          display mode and which windows are open at any given time and
  1527.          can be changed to suit your particular needs.
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.                                            The Debugger Display    3-3
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.          The Windows:Move menu option allows you to move the active
  1544.          window around on the screen.  When you select this option,
  1545.          the border of the active window changes to a different
  1546.          pattern and the cursor keys are used to move the window. 
  1547.          Return completes the move.
  1548.  
  1549.          --------------------------------------------------------------
  1550.          Note
  1551.  
  1552.          Windows cannot be moved if you are running the Debugger in
  1553.          split screen mode.
  1554.          --------------------------------------------------------------
  1555.  
  1556.  
  1557.          --------------------------------------------------------------
  1558.          Tiling Windows
  1559.  
  1560.          The Windows:Tile option is a quick way to clean up the
  1561.          screen.  This option restores each window on the screen to
  1562.          its default location and size.  Any windows that have been
  1563.          zoomed or iconized are also restored to the original window
  1564.          display mode.
  1565.  
  1566.  
  1567.       The Code Window
  1568.  
  1569.          The Code Window is located underneath the Menu Bar, and is
  1570.          used to display program code and header (.ch) files. 
  1571.          Pre-processed output can be displayed beneath program code on
  1572.          a line-by-line basis using the Options:Preprocessed Code menu
  1573.          option.  The name of the file currently being displayed is
  1574.          shown at the top of the window.
  1575.  
  1576.          The Code Window is initially set to display a certain number
  1577.          of lines, but can be sized to display fewer or more lines
  1578.          (see Sizing Windows in this chapter for more information). 
  1579.          The minimum number of display lines is zero, and the initial
  1580.          and maximum number of lines depend on the display mode.
  1581.  
  1582.          Inside the Code Window is a highlight bar called the
  1583.          Execution Bar which is positioned on the line of code about
  1584.          to be executed.  The Execution Bar moves as execution
  1585.          continues.
  1586.  
  1587.          When the Code Window is active, the cursor appears in the
  1588.          window to indicate your current position in the file being
  1589.          viewed.  Initially the cursor and Execution Bar appear on the
  1590.          same line, but the cursor can be moved up and down using the
  1591.          cursor keys.  The cursor is used to show the result of Locate
  1592.          menu selections, to mark (or delete) a line of code as a
  1593.          Breakpoint, and to tell the Run:To Cursor menu option where
  1594.          to stop.
  1595.  
  1596.          To navigate within the Code Window, use the keys shown in the
  1597.          table below:
  1598.  
  1599.  
  1600.  
  1601.  
  1602.                                            The Debugger Display    3-4
  1603.  
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.          Table 3-3: Code Window Active Keys
  1611.          --------------------------------------------------------------
  1612.          Key                  Action
  1613.          --------------------------------------------------------------
  1614.          Uparrow/Ctrl-E       Move cursor up one line
  1615.          Dnarrow/Ctrl-X       Move cursor down one line
  1616.          Leftarrow/Ctrl-S     Pan left one character
  1617.          Rightarrow/Ctrl-D    Pan right one character
  1618.          Home/Ctrl-A          Pan left one screen
  1619.          End/Ctrl-F           Pan right one screen
  1620.          PgUp/Ctrl-R          Scroll window contents up
  1621.          PgDn/Ctrl-C          Scroll window contents down
  1622.          Ctrl-PgUp            Move cursor to first line
  1623.          Ctrl-PgDn            Move cursor to last line
  1624.          Return               Execute pending command
  1625.          Tab                  Activate next window
  1626.          Shift-Tab            Activate previous window
  1627.          F2                   Toggle full screen/window display
  1628.          --------------------------------------------------------------
  1629.  
  1630.  
  1631.       The Command Window
  1632.  
  1633.          The Command Window displayed at the bottom of the screen
  1634.          displays the Debugger commands that you enter.  The output of
  1635.          Debugger commands (if any) is also displayed in this window
  1636.          directly underneath the command.  Commands are entered by
  1637.          typing the command and pressing Return to execute it (see
  1638.          Chapter 5, Command Reference for a list of commands).
  1639.  
  1640.          The Command Window is like most other Debugger windows in
  1641.          that it can be sized, moved, and zoomed to full screen when
  1642.          it is the active window (see Sizing Windows in this chapter
  1643.          for more information).  The window is made active by
  1644.          selecting it with Tab or Shift-Tab.  When the Command Window
  1645.          is active, its border is highlighted.
  1646.  
  1647.          Note, however, that the Command Window does not have to be
  1648.          active in order to enter commands.  Commands are entered in
  1649.          the same manner no matter what window happens to be active at
  1650.          the time, and the command appears in the Command Window next
  1651.          to the greater than (>) prompt as you are typing.  The
  1652.          following table gives a summary of keys that are available
  1653.          when the Command Window is active:
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.                                            The Debugger Display    3-5
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.          Table 3-4: Command Window Active Keys
  1678.          --------------------------------------------------------------
  1679.          Key                  Action
  1680.          --------------------------------------------------------------
  1681.          Uparrow/Ctrl-E       Move cursor to previous line in history
  1682.          Dnarrow/Ctrl-X       Move cursor to next line in history
  1683.          Leftarrow/Ctrl-S     Move cursor one character to the left
  1684.          Rightarrow/Ctrl-D    Move cursor one character to the right
  1685.          Home/Ctrl-A          Move cursor to the beginning of line
  1686.          End/Ctrl-F           Move cursor to the end of line
  1687.          Ins/Ctrl-V           Toggle the insert mode on or off
  1688.          Del/Ctrl-G           Delete character under cursor
  1689.          Backspace/Ctrl-H     Delete character to the left of cursor
  1690.          Esc                  Clear command line
  1691.          Return               Execute pending command
  1692.          Tab                  Activate next window
  1693.          Shift-Tab            Activate previous window
  1694.          F2                   Toggle full screen/window display
  1695.          --------------------------------------------------------------
  1696.  
  1697.  
  1698.          --------------------------------------------------------------
  1699.          History
  1700.  
  1701.          The commands that you enter are saved in a history buffer
  1702.          where they can be accessed when the Command Window is
  1703.          active.  Use Uparrow to move to the previous command and
  1704.          Dnarrow to move to the next one.  F2 zooms the Command Window
  1705.          to full screen, allowing you to see more commands at one
  1706.          time.  When a command is displayed next to the > prompt in
  1707.          the Command Window, it can be edited and executed just as if
  1708.          you had typed it.
  1709.  
  1710.  
  1711.          --------------------------------------------------------------
  1712.          Overwrite and Insert Modes
  1713.  
  1714.          When the Command Window is active, there are two data entry
  1715.          modes: Overwrite and Insert.  Overwrite mode (the default) is
  1716.          indicated by the underscore cursor and causes any characters
  1717.          typed to overwrite existing characters.  To toggle between
  1718.          Overwrite and Insert mode, press Ins.  The cursor changes to
  1719.          a block and new characters are inserted to the right of the
  1720.          cursor position.
  1721.  
  1722.  
  1723.       The Watch Window
  1724.  
  1725.          The Watch Window is displayed at the top of the screen,
  1726.          underneath the Menu Bar and above the Code Window.  It
  1727.          appears whenever a Watchpoint or Tracepoint is created.  In
  1728.          this window, the number and name of each Watchpoint and
  1729.          Tracepoint is displayed along with its data type, value, and
  1730.          storage class (e.g., LOCAL).  Watchpoints and Tracepoints are
  1731.          indicated by the words "wp" or "tp."
  1732.  
  1733.  
  1734.  
  1735.  
  1736.                                            The Debugger Display    3-6
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.          When the Watch Window is active, you can inspect the value of
  1745.          almost any variable or expression that appears in the window
  1746.          by highlighting it and pressing Return.  This action opens a
  1747.          dialog box in which you can inspect (and edit) the value. 
  1748.          Pressing Return takes you back to the Watch Window.
  1749.  
  1750.          Code blocks and objects, however, cannot be inspected and
  1751.          inspecting an array is slightly more complicated.  To inspect
  1752.          an array, highlight the array name and select it with
  1753.          Return.  When the dialog box appears, you can either enter
  1754.          array values or press Return again to inspect each element of
  1755.          the array in another dialog box.
  1756.  
  1757.          In this dialog box, Uparrow and Dnarrow move the highlight
  1758.          bar and Return enters the edit mode for the current value. 
  1759.          After making changes, press Return again to leave the edit
  1760.          mode.  When you are finished making changes, press Esc twice
  1761.          to return to the Watch Window and the changes you have made
  1762.          to the array will be saved.
  1763.  
  1764.          The following table summarizes the keys that are available
  1765.          when the Watch Window is active:
  1766.  
  1767.          Table 3-5: Watch and Monitor Window Active Keys
  1768.          --------------------------------------------------------------
  1769.          Key               Action
  1770.          --------------------------------------------------------------
  1771.          Uparrow/Ctrl-E    Move highlight bar up one line
  1772.          Dnarrow/Ctrl-X    Move highlight bar down one line
  1773.          PgUp/Ctrl-R       Scroll window contents up
  1774.          PgDn/Ctrl-C       Scroll window contents down
  1775.          Ctrl-PgUp         Move highlight bar to first line
  1776.          Ctrl-PgDn         Move highlight bar to last line
  1777.          Return            Execute pending command or change selected
  1778.                            item
  1779.          Tab               Activate next window
  1780.          Shift-Tab         Activate previous window
  1781.          F2                Toggle full screen/window display
  1782.          --------------------------------------------------------------
  1783.          
  1784.          See also: Point:Watchpoint, Point:Tracepoint, DELETE, LIST,
  1785.          TP, WP
  1786.  
  1787.  
  1788.       The Monitor Window
  1789.  
  1790.          The Monitor Window is similar to the Watch Window except that
  1791.          it is used to monitor variables of a particular storage class
  1792.          rather than variables that are set as Watchpoints and
  1793.          Tracepoints.  The Monitor Window appears on the screen only
  1794.          when one or more of the storage classes in the Monitor menu
  1795.          is turned ON (indicated by a check mark next to the storage
  1796.          class).
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.                                            The Debugger Display    3-7
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.          If the Callstack window is active, the Monitor window
  1812.          displays variables at the point of the activation level
  1813.          represented by the highlight bar in the Callstack.
  1814.  
  1815.          In this window, each variable name that is being monitored is
  1816.          displayed along with its storage class, data type, and
  1817.          value.  By default, the variables are grouped by storage
  1818.          class.  If Monitor:Sort is ON (indicated by a check mark
  1819.          beside the menu option), variables listed in the Monitor
  1820.          window are displayed in alphabetical order by variable name.
  1821.  
  1822.          When the Monitor Window is active, you can change the value
  1823.          of almost any variable in the window by highlighting it and
  1824.          pressing Return.  Editing variables in this window is
  1825.          identical to the method described above for the Watch Window
  1826.          and with the same exceptions--code blocks and objects cannot
  1827.          be edited and editing array values is slightly more
  1828.          complicated than other data types.  The keys for this window
  1829.          are the same as for the Watch Window and are summarized in
  1830.          Table 3-5.
  1831.  
  1832.          See also: Monitor:Local, Monitor:Private, Monitor:Public,
  1833.          Monitor:Static, Monitor:Sort
  1834.  
  1835.  
  1836.       The Callstack Window
  1837.  
  1838.          The Callstack Window appears on the right-hand side of the
  1839.          screen and contains the names of all pending activations. 
  1840.          This list is called the Callstack.  The current activation is
  1841.          always at the top of the Callstack.
  1842.  
  1843.          To open the Callstack Window, select the View:Callstack menu
  1844.          option or use the CALLSTACK command.  To select the window,
  1845.          press Tab or Shift-Tab until it is highlighted.  The
  1846.          following is a list of keys available when the Callstack
  1847.          Window is active:
  1848.  
  1849.          Table 3-6: Callstack Window Active Keys
  1850.          --------------------------------------------------------------
  1851.          Key               Action
  1852.          --------------------------------------------------------------
  1853.          Uparrow/Ctrl-E    Move highlight bar up one line
  1854.          Dnarrow/Ctrl-X    Move highlight bar down one line
  1855.          PgUp/Ctrl-R       Scroll window contents up
  1856.          PgDn/Ctrl-C       Scroll window contents down
  1857.          Ctrl-PgUp         Move highlight bar to first line
  1858.          Ctrl-PgDn         Move highlight bar to last line
  1859.          Return            Execute pending command
  1860.          Tab               Activate next window
  1861.          Shift-Tab         Activate previous window
  1862.          F2                Toggle full screen/window display
  1863.          --------------------------------------------------------------
  1864.          
  1865.          See also: View:Callstack, CALLSTACK
  1866.  
  1867.  
  1868.  
  1869.  
  1870.                                            The Debugger Display    3-8
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.       The Help Window
  1879.  
  1880.          The Debugger offers on-line help in the form of a Help
  1881.          Window, which is divided into two panes: the left pane
  1882.          contains a list of topics for which help is available, and
  1883.          the right pane contains the help text for the currently
  1884.          highlighted topic.  You can activate the Help Window by using
  1885.          the Help menu, pressing F1, or entering the HELP command.
  1886.          
  1887.          There are several main topics of discussion in the Help
  1888.          Window and when the window is first activated, one of these
  1889.          topics is highlighted on the left with its associated help
  1890.          text displayed on the right.  The following table summarizes
  1891.          the keys used to navigate within the Help Window:
  1892.  
  1893.          Table 3-7: Help Window Active Keys
  1894.          --------------------------------------------------------------
  1895.          Key               Action
  1896.          --------------------------------------------------------------
  1897.          Uparrow/Ctrl-E    Move highlight bar up one line
  1898.          Dnarrow/Ctrl-X    Move highlight bar down one line
  1899.          PgUp/Ctrl-R       Scroll window contents up
  1900.          PgDn/Ctrl-C       Scroll window contents down
  1901.          Esc               Leave Help Window
  1902.          --------------------------------------------------------------
  1903.          
  1904.          See also: F1, Help:Commands, Help:Keys, Help:Menus,
  1905.          Help:Windows, HELP
  1906.  
  1907.  
  1908.       The View Sets Window
  1909.  
  1910.          To activate the View Sets Window, select the View:Sets menu
  1911.          option.  When this window is active, you can view and change
  1912.          the status of the Clipper system settings.
  1913.  
  1914.          Uparrow and Dnarrow move the highlight up and down in the
  1915.          list of settings.  To change a setting, highlight it and
  1916.          press Return.  After changing the value, press Return again
  1917.          and move on to the next setting.
  1918.  
  1919.          To close the View Sets Window and continue debugging, press
  1920.          Esc.  The new settings are saved and take effect immediately
  1921.          in your program.
  1922.  
  1923.          See also: View:Sets
  1924.  
  1925.  
  1926.       The View Workareas Window
  1927.  
  1928.          To activate the View Workareas Window, select the
  1929.          View:Workareas menu option or press F6.  This window is
  1930.          divided into three panes called Area, Status, and Structure. 
  1931.          The Tab and Shift-Tab keys move back and forth between window
  1932.          panes.
  1933.  
  1934.  
  1935.  
  1936.  
  1937.                                            The Debugger Display    3-9
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.          The Area pane displays the alias name for each open database
  1946.          file, with the active file displayed in angle brackets. 
  1947.          Uparrow and Dnarrow are used to move the highlight up and
  1948.          down in the Area window pane.  Information regarding the
  1949.          currently highlighted file is shown in the other two window
  1950.          panes.
  1951.  
  1952.          The Status pane shows the status of most work area flag
  1953.          settings with information regarding the selected database
  1954.          file underneath.  When this pane is active, the alias name is
  1955.          highlighted and Uparrow and Dnarrow are used to move the
  1956.          highlight.  The database information is in the form of an
  1957.          outline that can be expanded and collapsed by pressing
  1958.          Return.  For instance, if you highlight Current Record and
  1959.          press Return the value of each field in the current record is
  1960.          displayed underneath.  Similarly, expanding the Workarea
  1961.          Information heading displays additional work area settings
  1962.          that are not shown at the top of the window pane.
  1963.  
  1964.          Finally, the Structure pane lists the structure of the
  1965.          selected database file.  When this window pane is active,
  1966.          Uparrow and Dnarrow move the highlight from field to field
  1967.          allowing you to scroll through the file structure.
  1968.  
  1969.          To close the View Workareas Window and continue debugging,
  1970.          press Esc.
  1971.  
  1972.          See also: F6, View:Workareas
  1973.  
  1974.  
  1975.       The Set Colors Window
  1976.  
  1977.          To activate the Set Colors Window, select the Options:Colors
  1978.          menu option.  When this window is active, you can view and
  1979.          change the status of the Debugger color settings.
  1980.  
  1981.          Uparrow and Dnarrow move the highlight up and down in the
  1982.          list of color settings.  To change a setting, highlight it
  1983.          and press Return.  Each setting is a foreground/background
  1984.          color string enclosed in double quotes (see SETCOLOR() in the
  1985.          Reference book for a list of colors).  After changing the
  1986.          value, press Return again and move on to the next setting.
  1987.  
  1988.          To close the Set Colors Window and continue debugging, press
  1989.          Esc.  The new colors will take effect immediately but will be
  1990.          lost as soon as you exit the Debugger.  To save the new
  1991.          colors in a script file for future use, select the
  1992.          Options:Save Settings menu option.
  1993.  
  1994.          See also: Options:Colors, Options:Restore Settings,
  1995.          Options:Save Settings
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.                                           The Debugger Display    3-10
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.       -----------------------------------------------------------------
  2013.       Dialog Boxes
  2014.  
  2015.          Several menu options and window selections require that you
  2016.          enter further information before continuing.  Menu options
  2017.          that require more input are always indicated by an ellipsis
  2018.          (...) to the right of the option name.  Some examples of
  2019.          window selections that require additional information are
  2020.          items in the Monitor and Watch windows.  Anytime more
  2021.          information is required to proceed, a dialog box is displayed
  2022.          to prompt you.
  2023.  
  2024.          The following table summarizes the keys that are available
  2025.          when a dialog box is open:
  2026.  
  2027.          Table 3-8: Dialog Box Active Keys
  2028.          --------------------------------------------------------------
  2029.          Key                  Action
  2030.          --------------------------------------------------------------
  2031.          Leftarrow/Ctrl-S     Move cursor one character to the left
  2032.          Rightarrow/Ctrl-D    Move cursor one character to the right
  2033.          Home/Ctrl-A          Move cursor to the beginning of line
  2034.          End/Ctrl-F           Move cursor to the end of line
  2035.          Ins/Ctrl-V           Toggle the insert mode on or off
  2036.          Del/Ctrl-G           Delete character under cursor
  2037.          Backspace/Ctrl-H     Delete character to the left of cursor
  2038.          Esc                  Close dialog box without executing
  2039.          Return               Execute and close dialog box
  2040.          --------------------------------------------------------------
  2041.          
  2042.          Dialog boxes are also used if you enter an incomplete
  2043.          command.  For example, FIND with no search string opens a
  2044.          dialog box to ask for the search string.
  2045.  
  2046.  
  2047.       -----------------------------------------------------------------
  2048.       The Debugger Menus
  2049.  
  2050.          The following section contains a description of the menus
  2051.          available in The Clipper Debugger.  Many of the options on
  2052.          these menus can also be accessed by using function keys or
  2053.          commands; in such cases, the appropriate command or function
  2054.          key is mentioned in the description of the menu option.
  2055.  
  2056.  
  2057.       The Menu Bar
  2058.  
  2059.          Menu selections appear on the Menu Bar at the top of the
  2060.          screen.  Each of these menus contains a group of similar,
  2061.          commonly used options.  For example, the Find, Next, Previous
  2062.          and Goto Line options are found on the Locate menu.
  2063.  
  2064.          Although each of these options has an associated command that
  2065.          performs the same function (in the above example: FIND, NEXT,
  2066.          PREV and GOTO), the menu system provides a quick way for the
  2067.          beginner to learn how to use the Debugger.
  2068.  
  2069.  
  2070.  
  2071.                                           The Debugger Display    3-11
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.       Menu Operations
  2080.  
  2081.          This section describes the process of accessing menus and
  2082.          selecting particular menu options.  Also included are tables
  2083.          of menu system active keys.
  2084.  
  2085.  
  2086.          --------------------------------------------------------------
  2087.          Accessing a Menu
  2088.  
  2089.          To access a menu, hold down the Alt key and press the first
  2090.          letter of the menu name.  For example, to access the View
  2091.          menu, press Alt-V.  To cancel a menu, press Esc.
  2092.  
  2093.          Whenever a menu is displayed on the screen, the other menus
  2094.          can be accessed by using Leftarrow and Rightarrow (as shown
  2095.          in the table below).  If you are positioned at the first item
  2096.          on the Menu Bar--the File menu--pressing Leftarrow causes the
  2097.          cursor to "wrap-around" and display the last item--the Help
  2098.          menu.  The reverse is true if you press Rightarrow from the
  2099.          last item.
  2100.  
  2101.          Table 3-9: Menu Access Keys
  2102.          --------------------------------------------------------------
  2103.          Key                        Action
  2104.          --------------------------------------------------------------
  2105.          Alt-<Menu first letter>    Activate designated menu
  2106.          Leftarrow/Ctrl-S           Activate menu to the left; wrap if
  2107.                                     on first menu
  2108.          Rightarrow/Ctrl-D          Activate menu to the right; wrap
  2109.                                     if on last menu
  2110.          Esc                        Close menu
  2111.          --------------------------------------------------------------
  2112.  
  2113.  
  2114.          --------------------------------------------------------------
  2115.          Selecting a Menu Option
  2116.  
  2117.          Once inside a menu, Uparrow and Dnarrow move the highlight
  2118.          bar up and down the list of options.  To select an option,
  2119.          highlight it and press Return.
  2120.  
  2121.          When selecting a menu option, pressing Uparrow on the first
  2122.          option causes the highlight bar to wrap-around to the last
  2123.          option; the reverse is true if you press Dnarrow on the last
  2124.          option.  The following table lists the active keys within a
  2125.          menu:
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.                                           The Debugger Display    3-12
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.          Table 3-10: Menu Option Keys
  2147.          --------------------------------------------------------------
  2148.          Key               Action
  2149.          --------------------------------------------------------------
  2150.          <Option letter>   Select designated option
  2151.          Return            Select highlighted option
  2152.          Uparrow/Ctrl-E    Move highlight bar up one option; 
  2153.                            wrap if on first option
  2154.          Dnarrow/Ctrl-X    Move highlight bar down one option; 
  2155.                            wrap if on last option
  2156.          --------------------------------------------------------------
  2157.  
  2158.  
  2159.          --------------------------------------------------------------
  2160.          Accelerator Keys
  2161.  
  2162.          Once a menu is open, all options within the menu have an
  2163.          associated accelerator key that you can press to select the
  2164.          option.  The accelerator key is a single letter which is
  2165.          usually the first letter of the option name.
  2166.  
  2167.          Within a menu, the accelerator key for each option is
  2168.          highlighted within the option name.  Typing the indicated key
  2169.          is equivalent to moving the highlight to that option and
  2170.          pressing Return.  For example, pressing Alt-P followed by the
  2171.          letter B selects Point:Breakpoint.
  2172.  
  2173.  
  2174.          --------------------------------------------------------------
  2175.          Menu Commands
  2176.  
  2177.          Any menu option can be turned into a command that can be
  2178.          executed from the Command Window or a script file.  These
  2179.          commands, called menu commands, are formed using the menu
  2180.          name followed by the first word of the option name.  For
  2181.          example, the Monitor:Public menu option can be executed using
  2182.          the following command:
  2183.  
  2184.          > MONITOR PUBLIC <Return>
  2185.          
  2186.          Arguments can be specified following a menu command if the
  2187.          menu option requires further input.  For example, selecting
  2188.          Run:Speed prompts you for the step delay using a dialog box. 
  2189.          To specify the delay speed of .5 seconds using a menu
  2190.          command:
  2191.  
  2192.          > RUN SPEED 5 <Return>
  2193.          
  2194.          Menu commands can be abbreviated down to one letter per word,
  2195.          but in some cases a second letter is required in the option
  2196.          keyword to distinguish it from another option that begins
  2197.          with the same letter.
  2198.  
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.                                           The Debugger Display    3-13
  2206.  
  2207.  
  2208.  
  2209.  
  2210.  
  2211.  
  2212.  
  2213.       The File Menu
  2214.  
  2215.          The File menu contains options to view other files, and
  2216.          allows you to access DOS without leaving the current
  2217.          program.  It is opened by pressing Alt-F.
  2218.  
  2219.  
  2220.          --------------------------------------------------------------
  2221.          Open...
  2222.  
  2223.          The Open option allows you to examine another program or
  2224.          header file.  When you select this option, a dialog box is
  2225.          displayed and you are prompted to enter the name of the file
  2226.          you want to view.  If no extension is specified, (.prg) is
  2227.          assumed.  When you have entered the name of the file, the
  2228.          current program is cleared from the Code Window, and the new
  2229.          file is displayed in its place.  To continue with the
  2230.          original program, select the File:Resume menu option or use
  2231.          the RESUME command.
  2232.  
  2233.          See also: File:Resume, VIEW
  2234.  
  2235.  
  2236.          --------------------------------------------------------------
  2237.          Resume
  2238.  
  2239.          The Resume option clears the file currently being viewed from
  2240.          the screen and redisplays the program originally being
  2241.          debugged.
  2242.  
  2243.          See also: File:Open, RESUME
  2244.  
  2245.  
  2246.          --------------------------------------------------------------
  2247.          DOS Access
  2248.  
  2249.          This option allows you to access DOS without leaving the
  2250.          Debugger.  The screen is cleared and a temporary copy of
  2251.          COMMAND.COM is invoked, allowing you to type DOS commands in
  2252.          the usual way.  When you have finished, type "Exit" at the
  2253.          DOS prompt to return to the program you are debugging.
  2254.  
  2255.          See also: DOS
  2256.  
  2257.  
  2258.          --------------------------------------------------------------
  2259.          Exit
  2260.  
  2261.          Selecting the Exit option tells the Debugger that you have
  2262.          finished the current debugging session.  All Debugger
  2263.          settings are cleared, database and index files are closed,
  2264.          and the system returns to DOS.  Pressing Alt-X is equivalent
  2265.          to selecting File:Exit.
  2266.  
  2267.          See also: QUIT
  2268.  
  2269.  
  2270.  
  2271.  
  2272.                                           The Debugger Display    3-14
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.       The Locate Menu
  2281.  
  2282.          The Locate menu contains options that allow you to search for
  2283.          a character string in a program and move the cursor in the
  2284.          Code Window to a particular line number.  This menu is
  2285.          selected by pressing Alt-L.
  2286.  
  2287.          --------------------------------------------------------------
  2288.          Note
  2289.  
  2290.          If the Command Window is active when a Locate menu option is
  2291.          selected, you will not see the cursor move to its new
  2292.          location in the Code Window.  You must select the Code Window
  2293.          in order to see the new cursor position in the file.
  2294.          --------------------------------------------------------------
  2295.  
  2296.  
  2297.          --------------------------------------------------------------
  2298.          Find...
  2299.  
  2300.          The Find option searches the file displayed in the Code
  2301.          Window for a particular character string.  When selected, a
  2302.          dialog box is displayed and you are asked to enter a search
  2303.          string.  
  2304.  
  2305.          The search always begins at the first line of code and moves
  2306.          down through the file, regardless of the current cursor
  2307.          position in the Code Window.  If a match is found, the
  2308.          Debugger moves the cursor to the line containing the first
  2309.          occurrence of the string; otherwise, the cursor remains at
  2310.          its current location.
  2311.  
  2312.          See also: Locate:Next, Locate:Previous, Locate:Case
  2313.          Sensitive, FIND
  2314.  
  2315.  
  2316.          --------------------------------------------------------------
  2317.          Next
  2318.  
  2319.          This option searches for the next occurrence of the last
  2320.          character string found.  If no search string has been
  2321.          specified, a dialog box is displayed to prompt you for one.
  2322.  
  2323.          The search begins at the current cursor position in the Code
  2324.          Window and moves down through the file.  If a match is found,
  2325.          the Debugger moves the cursor to the line containing the next
  2326.          occurrence of the string; otherwise, the cursor remains at
  2327.          its current location.
  2328.  
  2329.          See also: Locate:Find, Locate:Previous, NEXT
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.                                           The Debugger Display    3-15
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.          --------------------------------------------------------------
  2348.          Previous
  2349.  
  2350.          The Previous option searches for the previous occurrence of a
  2351.          character string.  If no search string has been specified, a
  2352.          dialog box is displayed to prompt you for one.
  2353.  
  2354.          The search begins at the current cursor position in the Code
  2355.          Window and moves up through the file.  If a match is found,
  2356.          the Debugger moves the cursor to the line containing the
  2357.          previous occurrence of the string; otherwise, the cursor
  2358.          remains at its current location.
  2359.  
  2360.          See also: Locate:Find, Locate:Next, PREV
  2361.  
  2362.  
  2363.          --------------------------------------------------------------
  2364.          Goto Line...
  2365.  
  2366.          Goto Line moves the cursor to a particular line number.  When
  2367.          you select this option, a dialog box is displayed and you are
  2368.          prompted to enter a line number.  If your entry is valid, the
  2369.          Debugger moves the cursor to the indicated line; otherwise,
  2370.          the cursor remains at its current location.
  2371.  
  2372.          Locate:Goto Line is functional regardless of whether or not
  2373.          Line Numbers are currently displayed.
  2374.  
  2375.          See also: Options:Line Numbers, GOTO
  2376.  
  2377.  
  2378.          --------------------------------------------------------------
  2379.          Case Sensitive
  2380.  
  2381.          The setting of this option determines whether or not searches
  2382.          performed with the Find, Next, and Previous options in the
  2383.          Locate menu are case sensitive.  If Case Sensitive is ON
  2384.          (indicated by a check mark), two strings match only if they
  2385.          have an identical pattern of upper and lower case letters. 
  2386.          If it is OFF, two strings containing identical characters
  2387.          match, regardless of the casing of letters within the
  2388.          strings.
  2389.  
  2390.          The Case Sensitive setting also applies to searches performed
  2391.          with the FIND, NEXT, and PREV commands.
  2392.  
  2393.          See also: Locate:Find, Locate:Next, Locate:Previous, FIND,
  2394.          NEXT, PREV
  2395.  
  2396.  
  2397.       The View Menu
  2398.  
  2399.          The View menu, selected by pressing Alt-V, contains a set of
  2400.          options that allow you to view certain information that is
  2401.          not normally displayed as part of the Debugger screen.
  2402.  
  2403.  
  2404.  
  2405.  
  2406.                                           The Debugger Display    3-16
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.          --------------------------------------------------------------
  2415.          Sets
  2416.  
  2417.          When you select this option, the View Sets Window is
  2418.          activated.  When this window is active, you can view and
  2419.          change the status of the Clipper system settings.
  2420.  
  2421.          Use Uparrow and Dnarrow to move the highlight up and down in
  2422.          the list of settings.  To change a setting, highlight it and
  2423.          press Return.  After changing the value, press Return again
  2424.          and move on to the next setting.
  2425.  
  2426.          To close the View Sets Window and continue debugging, press
  2427.          Esc.  The new settings are saved and take effect immediately
  2428.          in your program.
  2429.  
  2430.  
  2431.          --------------------------------------------------------------
  2432.          Workareas
  2433.  
  2434.          Selecting this option activates the View Workareas Window. 
  2435.          Pressing F6 has the same effect.  This window allows you to
  2436.          view information regarding all database files that are
  2437.          currently in use.  To close the window and continue
  2438.          debugging, press Esc.
  2439.  
  2440.          See also: F6
  2441.  
  2442.  
  2443.          --------------------------------------------------------------
  2444.          App Screen
  2445.  
  2446.          When you select this option, the Debugger screen is erased,
  2447.          and your application screen is displayed in its place.  This
  2448.          allows you to see the output of the program being debugged
  2449.          exactly as the person using your application will see it. 
  2450.          Pressing F4 achieves the same effect.  To return to the
  2451.          Debugger, press any key.
  2452.  
  2453.          See also: F4, OUTPUT
  2454.  
  2455.  
  2456.          --------------------------------------------------------------
  2457.          Callstack
  2458.  
  2459.          The Callstack option acts as a toggle for opening and closing
  2460.          the Callstack Window.  When the option is ON (indicated by a
  2461.          check mark next to the menu option), the Callstack Window is
  2462.          displayed on the main Debugger screen.  If the option OFF,
  2463.          the Callstack Window is closed (not displayed).
  2464.  
  2465.          See also: CALLSTACK
  2466.  
  2467.  
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.                                           The Debugger Display    3-17
  2474.  
  2475.  
  2476.  
  2477.  
  2478.  
  2479.  
  2480.  
  2481.       The Run Menu
  2482.  
  2483.          The options found on the Run menu allow you to restart the
  2484.          current application, load a new (.EXE) file, or step through
  2485.          code one line at a time at a specified speed.  This menu is
  2486.          selected by pressing Alt-R.
  2487.  
  2488.  
  2489.          --------------------------------------------------------------
  2490.          Restart
  2491.  
  2492.          The Restart option reloads the current application, retaining
  2493.          all Debugger settings.  The Debugger does not allow portions
  2494.          of an application which have already been executed to be run
  2495.          again.  Instead, the entire application must be restarted.
  2496.  
  2497.          See also: RESTART
  2498.  
  2499.  
  2500.          --------------------------------------------------------------
  2501.          Animate
  2502.  
  2503.          When you select the Animate option, the Debugger steps
  2504.          through the current application one line at a time, moving
  2505.          the Execution Bar to each line as it is executed.  This form
  2506.          of execution is called "Animate Mode."  If Options:Exchange
  2507.          Screens is ON, the output of each line is shown after the
  2508.          line has been executed.  Control then returns to the
  2509.          Debugger, the Execution Bar moves to the next line, that line
  2510.          is executed, and so on.  This continues until a Breakpoint or
  2511.          Tracepoint is reached.  For more information on modes of
  2512.          execution, see Chapter 4, Debugging a Program.
  2513.  
  2514.          See also: Options:Exchange Screens, Options:Swap on Input,
  2515.          Run:Speed, ANIMATE
  2516.  
  2517.  
  2518.          --------------------------------------------------------------
  2519.          Step
  2520.  
  2521.          The Step option executes your application in Single Step
  2522.          Mode.  This mode executes the line of program code
  2523.          highlighted by the Execution Bar, moves the Execution Bar to
  2524.          the next line of code to be executed, and stops.  As
  2525.          functions are called by the current program, their code is
  2526.          displayed in the Code Window.  F8 performs the same function
  2527.          as the Run:Step menu option.
  2528.  
  2529.          See also: F8, Options:Codeblock Trace, STEP
  2530.  
  2531.  
  2532.  
  2533.  
  2534.  
  2535.  
  2536.  
  2537.  
  2538.  
  2539.  
  2540.                                           The Debugger Display    3-18
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.          --------------------------------------------------------------
  2549.          Trace
  2550.  
  2551.          The Trace option is similar to Step in that it executes one
  2552.          line of program code at a time.  However, Trace does not
  2553.          display the code for functions called by the current
  2554.          program.  F10 performs the same function as the Run:Trace
  2555.          menu option.
  2556.  
  2557.          See also: F10
  2558.  
  2559.  
  2560.          --------------------------------------------------------------
  2561.          Go
  2562.  
  2563.          When you select the Go option, the Debugger displays your
  2564.          application screen and begins execution in Run Mode;
  2565.          execution continues until a Breakpoint or Tracepoint is
  2566.          encountered, or until the Debugger is invoked with ALTD() or
  2567.          Alt-D.  F5 performs the same function as the Run:Go menu
  2568.          option.
  2569.  
  2570.          See also: F5, GO
  2571.  
  2572.  
  2573.          --------------------------------------------------------------
  2574.          To Cursor
  2575.  
  2576.          The To Cursor option allows you to execute only those lines
  2577.          of code up to the line indicated by the current cursor
  2578.          position in the Code Window.  The application is executed in
  2579.          Run Mode until that line is reached.  If the line is never
  2580.          executed, the Debugger continues to the end of the
  2581.          application.  F7 performs the same function as the Run:To
  2582.          Cursor menu option.
  2583.  
  2584.          See also: F7
  2585.  
  2586.  
  2587.          --------------------------------------------------------------
  2588.          Speed...
  2589.  
  2590.          The Speed option allows you to set the step delay for Animate
  2591.          Mode in tenths of seconds (for an explanation of this mode,
  2592.          see Chapter 4, Debugging a Program).
  2593.  
  2594.          When you select this option, a dialog box is displayed and
  2595.          you are asked to enter a number representing the step speed. 
  2596.          The number that you enter is interpreted as tenths of
  2597.          seconds, so that entering a small number such as zero results
  2598.          in a faster display time than entering a larger number.  The
  2599.          current setting is displayed in the dialog box when you
  2600.          select Run:Speed.
  2601.  
  2602.          See also: Run:Animate, SPEED
  2603.  
  2604.  
  2605.  
  2606.  
  2607.                                           The Debugger Display    3-19
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.       The Point Menu
  2616.  
  2617.          The Point menu contains options to set and delete
  2618.          Breakpoints, Watchpoints, and Tracepoints, and is selected by
  2619.          pressing Alt-P.
  2620.  
  2621.          Breakpoints are lines of code at which the application pauses
  2622.          and returns control to the Debugger.  Watchpoints are
  2623.          variables and expressions whose values are displayed in the
  2624.          Watch Window and updated as each line of the application
  2625.          executes.  Tracepoints are very similar; however, whenever
  2626.          the value of a Tracepoint changes, execution pauses and
  2627.          control passes to the Debugger.  Tracepoints are also
  2628.          displayed in the Watch Window.  For more information on
  2629.          Watchpoints and Tracepoints, see Chapter 4, Debugging a
  2630.          Program.
  2631.  
  2632.  
  2633.          --------------------------------------------------------------
  2634.          Watchpoint...
  2635.  
  2636.          The Watchpoint option designates a field variable, memory
  2637.          variable or expression as a Watchpoint.  When you select this
  2638.          option, a dialog box is displayed and you are asked to enter
  2639.          a variable or expression.  Your entry is then displayed in
  2640.          the Watch Window at the top of the screen, together with its
  2641.          type and value and the word "wp."  As each line of the
  2642.          current program is executed, the value of the Watchpoint is
  2643.          updated.
  2644.  
  2645.          See also: Point:Delete, WP
  2646.  
  2647.  
  2648.          --------------------------------------------------------------
  2649.          Tracepoint...
  2650.  
  2651.          This option allows you to specify a field variable, memory
  2652.          variable or expression as a Tracepoint.  As is the case for
  2653.          Watchpoints, a dialog box is displayed and you are prompted
  2654.          for an expression or the name of a variable.  This is then
  2655.          displayed in the Watch Window along with its type and value,
  2656.          and noted as "tp."  Unlike Watchpoints, every time the value
  2657.          of the Tracepoint changes, program execution pauses and
  2658.          control passes to the Debugger.
  2659.  
  2660.          See also: Point:Delete, TP
  2661.  
  2662.  
  2663.          --------------------------------------------------------------
  2664.          Breakpoint
  2665.  
  2666.          The Breakpoint option designates the line of code indicated
  2667.          by the cursor in the Code Window as a Breakpoint.  When you
  2668.          select this option, the line of code is indicated in a new
  2669.          color to distinguish it is as a Breakpoint.  This menu option
  2670.  
  2671.  
  2672.  
  2673.  
  2674.                                           The Debugger Display    3-20
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.          acts as a toggle so that if the current line of code is
  2683.          already a Breakpoint, the Breakpoint is deleted and the color
  2684.          of the line returns to normal.
  2685.  
  2686.          Pressing F9 is equivalent to selecting the Point:Breakpoint
  2687.          menu option.
  2688.  
  2689.  
  2690.          --------------------------------------------------------------
  2691.          Delete...
  2692.  
  2693.          When you select the Delete option, a dialog box is displayed
  2694.          and you are asked to enter the number that appears to the
  2695.          left of the Watchpoint or Tracepoint you want to delete. 
  2696.          Your selection is then removed from the Watch Window.
  2697.  
  2698.          See also: Point:Watchpoint, Point:Tracepoint, DELETE
  2699.  
  2700.  
  2701.       The Monitor Menu
  2702.  
  2703.          The Monitor menu contains a set of options that control the
  2704.          display of PUBLIC, PRIVATE, STATIC and LOCAL variables in the
  2705.          Monitor Window.  This menu is activated by pressing Alt-M. 
  2706.          Variables displayed using the menu options described in this
  2707.          section are known as "monitored" variables.
  2708.  
  2709.          Monitored variables relate to the routine currently displayed
  2710.          in the Code Window.  When a pending activation is viewed, the
  2711.          values displayed for the monitored variables are the values
  2712.          that they held when the routine was active.  Inspecting the
  2713.          variables with the ?|?? command or specifying them as
  2714.          Watchpoints or Tracepoints yields the current value, which
  2715.          may be different from the value displayed in the Monitor
  2716.          Window.  Any existing variables which are not visible to the
  2717.          activation in the Code Window do not appear in the Monitor
  2718.          Window.
  2719.  
  2720.          Each of the options on the Monitor menu can either be ON
  2721.          (indicated by a check mark) or OFF.  When ON, variables of
  2722.          the appropriate storage class are displayed in the Monitor
  2723.          Window.  To toggle between the two states, highlight the
  2724.          appropriate option and press Return.
  2725.  
  2726.  
  2727.          --------------------------------------------------------------
  2728.          Public
  2729.  
  2730.          When ON, the Public option monitors PUBLIC variables in the
  2731.          Monitor Window.
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.                                           The Debugger Display    3-21
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.          --------------------------------------------------------------
  2750.          Private
  2751.  
  2752.          When ON, this option, specifies PRIVATE variables as
  2753.          monitored variables, and displays them in the Monitor Window.
  2754.  
  2755.  
  2756.          --------------------------------------------------------------
  2757.          Static
  2758.  
  2759.          When the Static option is ON, STATIC variables are monitored
  2760.          in the Monitor Window.
  2761.  
  2762.  
  2763.          --------------------------------------------------------------
  2764.          Local
  2765.  
  2766.          When this option is ON, LOCAL variables are displayed in the
  2767.          Monitor Window.
  2768.  
  2769.  
  2770.          --------------------------------------------------------------
  2771.          Sort
  2772.  
  2773.          The Sort option controls the order in which items are
  2774.          displayed in the Monitor Window.  When Sort is ON (indicated
  2775.          by a check mark), items in the Monitor Window are displayed
  2776.          in alphabetical order according to variable name.  When the
  2777.          option is OFF, the monitored variables are grouped by storage
  2778.          class.
  2779.  
  2780.  
  2781.       The Options Menu
  2782.  
  2783.          The Options menu allows you to control the Debugger display
  2784.          options and to create and run Debugger script files.  This
  2785.          menu is selected by pressing Alt-O.
  2786.  
  2787.  
  2788.          --------------------------------------------------------------
  2789.          Preprocessed Code
  2790.  
  2791.          The Preprocessed Code option is a toggle.  If it is ON
  2792.          (indicated by a check mark), the pre-processed code for the
  2793.          current program is displayed in the Code Window underneath
  2794.          each line of source code.  Since the pre-processed code is
  2795.          taken from the corresponding (.ppo) file, the program in the
  2796.          Code Window must have been compiled with the /P option. 
  2797.          Otherwise, no pre-processed code is displayed.
  2798.  
  2799.          If Preprocessed Code is OFF, the default, the source code is
  2800.          displayed in the Code Window without pre-processed output.
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.                                           The Debugger Display    3-22
  2809.  
  2810.  
  2811.  
  2812.  
  2813.  
  2814.  
  2815.  
  2816.          --------------------------------------------------------------
  2817.          Line Numbers
  2818.  
  2819.          The Line Numbers option is a toggle used to control the
  2820.          display of line numbers in the Code Window.  If the option is
  2821.          ON (indicated by a check mark), a line number is displayed to
  2822.          the left of each line of source code.  If not, no line
  2823.          numbers are visible.
  2824.  
  2825.          Having Line Numbers displayed in the Code Window is
  2826.          especially helpful when using the Locate:Goto Line menu
  2827.          option to move the cursor to a particular line of code.
  2828.  
  2829.          See also: NUM
  2830.  
  2831.  
  2832.          --------------------------------------------------------------
  2833.          Exchange Screens
  2834.  
  2835.          The Exchange Screens option is a toggle that controls the
  2836.          display of program output while in Animate Mode.  If this
  2837.          option is ON (indicated by a check mark), Animate Mode
  2838.          displays application output for each line of code executed.
  2839.  
  2840.          If Exchange Screens is OFF, the Debugger displays the
  2841.          application screen only when input is required.  For more
  2842.          information on modes of execution, see Chapter 4, Debugging a
  2843.          Program.
  2844.  
  2845.          See also: Run:Animate, Options:Swap on Input
  2846.  
  2847.  
  2848.          --------------------------------------------------------------
  2849.          Swap on Input
  2850.  
  2851.          If Options:Exchange Screens is ON, Swap on Input has no
  2852.          effect.  If, however, Options:Exchange Screens is OFF, Swap
  2853.          on Input acts as a toggle to control whether or not the
  2854.          application screen is displayed when input is required.
  2855.  
  2856.          By default, Swap on Input is ON (indicated by a check mark)
  2857.          which causes Run:Animate to swap to the application screen
  2858.          when input is required.  If Swap on Input is OFF, the
  2859.          application screen is not displayed during Animate Mode.
  2860.  
  2861.          See also: Options:Exchange Screens, Run:Animate
  2862.  
  2863.  
  2864.          --------------------------------------------------------------
  2865.          Codeblock Trace
  2866.  
  2867.          The Codeblock Trace option is a toggle that controls whether
  2868.          or not the Debugger traces code blocks in Step Mode.  If the
  2869.          option is ON (indicated by a check mark), Step Mode traces a
  2870.          code block back to its definition each time the code block is
  2871.  
  2872.  
  2873.  
  2874.  
  2875.                                           The Debugger Display    3-23
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.          evaluated.  It does this by moving the Execution Bar to the
  2884.          line where the code block was defined, allowing you to see
  2885.          the code block definition.
  2886.  
  2887.          Tracing code blocks involves an extra step each time a code
  2888.          block is evaluated because you also have to step over the
  2889.          definition line.  If you do not want to trace code block
  2890.          definitions, deselect Codeblock Trace.
  2891.  
  2892.          See also: Run:Step
  2893.  
  2894.  
  2895.          --------------------------------------------------------------
  2896.          Menu Bar
  2897.  
  2898.          The Menu Bar option is a toggle that controls the display of
  2899.          the menu bar.  If the option is ON (indicated by a check
  2900.          mark), the menu bar is displayed at the top of the main
  2901.          Debugger screen at all times.  If the option is OFF, the menu
  2902.          bar is not displayed unless you activate a menu.
  2903.  
  2904.  
  2905.          --------------------------------------------------------------
  2906.          Mono Display
  2907.  
  2908.          The Mono Display option is a toggle that controls whether the
  2909.          screen display is color or monochrome.  Note that the default
  2910.          status of this option depends on the kind of monitor you are
  2911.          using, and that the option is effective only for color
  2912.          monitors.  If you have a color monitor and Mono Display is ON
  2913.          (indicated by a check mark), a full range of color settings
  2914.          are available for the Debugger display.  If the option is
  2915.          OFF, the display is monochrome.
  2916.  
  2917.          See also: Options:Colors
  2918.  
  2919.  
  2920.          --------------------------------------------------------------
  2921.          Colors...
  2922.  
  2923.          The Colors options activates the Set Colors Window where you
  2924.          can inspect the Debugger display colors.  Press Esc to close
  2925.          the window and continue debugging.  See The Set Colors Window
  2926.          section earlier in this chapter for more information on this
  2927.          window.
  2928.  
  2929.  
  2930.          --------------------------------------------------------------
  2931.          Tab Width...
  2932.  
  2933.          The Tab Width option allows you to set the tab width for the
  2934.          Code Window.  Selecting this option opens a dialog box where
  2935.          the new value is entered.
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.                                           The Debugger Display    3-24
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.          Options:Tab Width is effective only if the file you are
  2951.          viewing contains tabs.  Lines that are indented with spaces
  2952.          are not affected.  The default Tab Width setting is 4.
  2953.  
  2954.  
  2955.          --------------------------------------------------------------
  2956.          Save Settings...
  2957.  
  2958.          The Save Settings option saves the current Debugger settings
  2959.          in a script file using menu commands.  Selecting this option
  2960.          opens a dialog box where you enter a filename (default
  2961.          extension is .CLD).
  2962.  
  2963.          The script file can be executed by selecting Options:Restore
  2964.          Settings or using the INPUT command.  It can also be executed
  2965.          from the CLD command-line the next time you execute the
  2966.          Debugger.
  2967.  
  2968.          See also: Options:Restore Settings, INPUT
  2969.  
  2970.  
  2971.          --------------------------------------------------------------
  2972.          Restore Settings...
  2973.  
  2974.          The Restore Settings option executes a Debugger script file. 
  2975.          Selecting this option opens a dialog box where you enter a
  2976.          filename (default extension is .CLD).
  2977.  
  2978.          See also: Options:Save Settings, INPUT
  2979.  
  2980.  
  2981.       The Window Menu
  2982.  
  2983.          The Window menu, selected by pressing Alt-W, allows you to
  2984.          perform certain Window operations including sizing and moving
  2985.          the active window.  See the Window Operations section earlier
  2986.          in this chapter for information on how to navigate within the
  2987.          Help Window.
  2988.  
  2989.  
  2990.          --------------------------------------------------------------
  2991.          Next
  2992.  
  2993.          The Next option selects the next window on the main Debugger
  2994.          screen.  The order of the windows is as follows: Code,
  2995.          Monitor, Watch, Callstack, Command.  Thus, if the Callstack
  2996.          Window is active, Window:Next selects the Command Window. 
  2997.          Pressing Tab is equivalent to selecting this menu option.
  2998.  
  2999.  
  3000.          --------------------------------------------------------------
  3001.          Prev
  3002.  
  3003.          The Prev option selects the previous window on the main
  3004.          Debugger screen.  The order of the windows is as follows:
  3005.          Code, Monitor, Watch, Callstack, Command.  Thus, if the
  3006.  
  3007.  
  3008.  
  3009.                                           The Debugger Display    3-25
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.          Callstack Window is active, Window:Prev selects the Watch
  3018.          Window.  Pressing Shift-Tab is equivalent to selecting this
  3019.          menu option.
  3020.  
  3021.  
  3022.          --------------------------------------------------------------
  3023.          Move
  3024.  
  3025.          Move allows you to move the active window around on the
  3026.          screen.  When you select this option, the border of the
  3027.          active window changes to a different pattern and the cursor
  3028.          keys are used to move the window.  Return completes the
  3029.          moving process.
  3030.  
  3031.          --------------------------------------------------------------
  3032.          Note
  3033.  
  3034.          Windows cannot be moved if you are running the Debugger in
  3035.          split screen mode.
  3036.          --------------------------------------------------------------
  3037.  
  3038.  
  3039.          --------------------------------------------------------------
  3040.          Size
  3041.  
  3042.          The Size option allows you to change both the height and the
  3043.          width of the active window.  When you select this option, the
  3044.          border of the active window changes to a different pattern
  3045.          and the cursor keys are used to change the size of the
  3046.          window.  Return completes the sizing process.
  3047.  
  3048.          --------------------------------------------------------------
  3049.          Note
  3050.  
  3051.          Windows cannot be sized if you are running the Debugger in
  3052.          split screen mode.
  3053.          --------------------------------------------------------------
  3054.  
  3055.  
  3056.          --------------------------------------------------------------
  3057.          Zoom
  3058.  
  3059.          The Zoom option allows you to zoom the active window to full
  3060.          screen.  This menu option acts as a toggle between the full
  3061.          screen and window display modes so that when the active
  3062.          window is zoomed to full screen, selecting Window:Zoom
  3063.          resumes the original window display.  When a window is
  3064.          zoomed, some window operations such as moving and sizing are
  3065.          not allowed.  Pressing F2 is equivalent to selecting this
  3066.          menu option.
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.                                           The Debugger Display    3-26
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.          --------------------------------------------------------------
  3085.          Iconize
  3086.  
  3087.          The Iconize option reduces the active window to an icon (its
  3088.          name).  A window that is iconized remains open, but you
  3089.          cannot see the window contents.  Certain window operations
  3090.          such as moving, however, are possible.
  3091.  
  3092.  
  3093.          --------------------------------------------------------------
  3094.          Tile
  3095.  
  3096.          The Tile option provides a quick way to clean up the screen
  3097.          by restoring each window on the screen to its default
  3098.          location and size.  Any windows that have been zoomed or
  3099.          iconized are also restored to the original window display
  3100.          mode.
  3101.  
  3102.  
  3103.       The Help Menu
  3104.  
  3105.          The Help menu, selected by pressing Alt-H, allows you to
  3106.          activate the Help Window.  The menu options select the help
  3107.          topic that is initially highlighted when the window is
  3108.          opened.  Pressing F1 opens the same Help Window, but with the
  3109.          About Help topic highlighted.
  3110.  
  3111.          After making a selection and getting the help you want, press
  3112.          Esc to return to the Debugger.  See the The Help Window
  3113.          section earlier in this chapter for information on how to
  3114.          navigate within the Help Window.
  3115.  
  3116.          See also: F1, HELP
  3117.  
  3118.  
  3119.          --------------------------------------------------------------
  3120.          Keys
  3121.  
  3122.          The Keys option causes the Keys topic to be highlighted when
  3123.          the Help Window is opened, and a general discussion of
  3124.          Debugger keys is displayed.  Keys subtopics include Function,
  3125.          Menu, Window, and Other which can be selected using Dnarrow.
  3126.  
  3127.  
  3128.          --------------------------------------------------------------
  3129.          Windows
  3130.  
  3131.          The Windows option highlights the Windows topic when the Help
  3132.          Window is opened, and a general discussion of Debugger
  3133.          windows is displayed.  The Windows topic is further
  3134.          subdivided into discussions on the Command, Code, Watch,
  3135.          Monitor, and Callstack which can be selected using Dnarrow.
  3136.  
  3137.  
  3138.  
  3139.  
  3140.  
  3141.  
  3142.  
  3143.                                           The Debugger Display    3-27
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.          --------------------------------------------------------------
  3152.          Menus
  3153.  
  3154.          The Menus option causes the Menus topic to be highlighted
  3155.          when the Help Window is opened, and a general discussion of
  3156.          the Debugger menus is displayed.  Each Menu (except Help) is
  3157.          discussed further as a subtopic.  To get help on a particular
  3158.          menu, highlight the menu name using Dnarrow.
  3159.  
  3160.  
  3161.          --------------------------------------------------------------
  3162.          Commands
  3163.  
  3164.          The Commands option causes the Commands topic to be
  3165.          highlighted when the Help Window is opened.  Commands is not
  3166.          subdivided into topics, but the discussion includes a list of
  3167.          commands in alphabetical order.  Use PgUp and PgDn to page
  3168.          through the help text until the command you are seeking is
  3169.          displayed.
  3170.  
  3171.  
  3172.       -----------------------------------------------------------------
  3173.       The Function Keys
  3174.  
  3175.          All of the function keys used in the Debugger are shortcuts
  3176.          to using a menu selection or command.  For example, using F9
  3177.          to set a Breakpoint is slightly easier than selecting the
  3178.          Breakpoint option from the Point menu and much easier than
  3179.          entering the appropriate BP or DELETE command.  The following
  3180.          table shows a list of all the available functions keys and
  3181.          their actions:
  3182.  
  3183.          Table 3-11:  Function Keys
  3184.          --------------------------------------------------------------
  3185.          Key   Action                     Alternative
  3186.          --------------------------------------------------------------
  3187.          F1    Help                       Help Menu, HELP
  3188.          F2    Full screen/window toggle  Window:Zoom
  3189.          F4    Application Screen         View:App Screen, OUTPUT
  3190.          F5    Execute Application        Run:Go, GO
  3191.          F6    View Workareas Window      View:Workareas
  3192.          F7    Run to Cursor              Run:To Cursor
  3193.          F8    Step                       Run:Step, STEP
  3194.          F9    Set/Delete Breakpoint      Point:Breakpoint, BP and 
  3195.                                           DELETE BP
  3196.          F10   Trace                      Run:Trace
  3197.          --------------------------------------------------------------
  3198.  
  3199.  
  3200.          F1 Help
  3201.  
  3202.          Pressing F1 displays the Help Window.  Use Uparrow and
  3203.          Dnarrow to select a topic in the left pane of the window; the
  3204.          help text for the currently highlighted topic appears in the
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.                                           The Debugger Display    3-28
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.          right window pane.  Press Esc to return to the Debugger.  You
  3219.          can display the Help Window using the Help menu or entering
  3220.          the HELP command.
  3221.  
  3222.  
  3223.          F2 Zoom Full Screen/Window Display
  3224.  
  3225.          F2 acts as a toggle between the full-screen and window
  3226.          displays.  To zoom the active window to full-screen press F2,
  3227.          and to restore the window display press F2 again.  F2
  3228.          performs the same function as the Window:Zoom menu option.
  3229.  
  3230.  
  3231.          F4 Application Screen
  3232.  
  3233.          Pressing F4 erases the Debugger screen and displays your
  3234.          application screen in its place.  This allows you to see the
  3235.          output of the program being debugged exactly as the person
  3236.          using your application will see it.  F4 performs the same
  3237.          function as the OUTPUT command and the View:App Screen menu
  3238.          option.
  3239.  
  3240.  
  3241.          F5 Execute Application
  3242.  
  3243.          This key displays your application screen and begins
  3244.          execution in Run Mode; that is, until a Breakpoint or
  3245.          Tracepoint is encountered, or until the Debugger is
  3246.          deliberately invoked (i.e., by pressing Alt-D or using
  3247.          ALTD()).  F5 performs the same function as the GO command and
  3248.          the Run:Go menu option.  For more information on modes of
  3249.          execution, see Chapter 4, Debugging a Program.
  3250.  
  3251.  
  3252.          F6 View Workareas
  3253.  
  3254.          The F6 key displays the View Workareas Window.  This window
  3255.          contains information on the currently open database (.dbf)
  3256.          files.  F6 performs the same function as the View:Workareas
  3257.          menu option.  
  3258.  
  3259.  
  3260.          F7 Run to Cursor
  3261.  
  3262.          This key sets a temporary Breakpoint on the line indicated by
  3263.          the cursor in the Code Window.  The application is executed
  3264.          in Run Mode until that line is reached, or until the value of
  3265.          a Tracepoint changes.  If the line is never executed, the
  3266.          Debugger continues to the end of the application.  F7
  3267.          performs the same function as the Run:To Cursor menu option. 
  3268.          For an explanation of execution modes, see Chapter 4,
  3269.          Debugging a Program.
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.                                           The Debugger Display    3-29
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.          F8 Step
  3286.  
  3287.          F8 executes the program in Single Step Mode.  This mode
  3288.          executes the line of program code highlighted by the
  3289.          Execution Bar, moves the Execution Bar to the next line of
  3290.          code to be executed, and stops.  As functions are called by
  3291.          the current program, their code is displayed in the Code
  3292.          Window.  F8 performs the same function as the STEP command
  3293.          and the Run:Step menu option.
  3294.  
  3295.          When single stepping through a piece of code containing a
  3296.          code block, the Execution Bar moves to the line of code where
  3297.          the block was created when the code block is evaluated.  This
  3298.          allows you to see the contents of the block (which are
  3299.          unavailable during normal inspection), and occurs regardless
  3300.          of whether the block was declared in the current routine. 
  3301.          Press F8 again to move past this line to the next executable
  3302.          line.  For more information on execution modes, see Chapter
  3303.          4, Debugging a Program.
  3304.  
  3305.  
  3306.          F9 Set/Delete Breakpoint
  3307.  
  3308.          F9 acts as a toggle between setting and deleting a Breakpoint
  3309.          at the current line (indicated by the cursor in the Code
  3310.          Window).  To set the Breakpoint press F9, and to delete the
  3311.          Breakpoint press F9 again.  Breakpoints are indicated in the
  3312.          Code Window using a display attribute that is different from
  3313.          other lines.  F9 performs the same function as the BP/DELETE
  3314.          BP commands and the Point:Breakpoint menu option.  For more
  3315.          information on Breakpoints, see Chapter 4, Debugging a
  3316.          Program.
  3317.  
  3318.  
  3319.          F10 Trace
  3320.  
  3321.          F10 performs a similar function to F8, namely, executing one
  3322.          line of program code.  However, F10 does not display the code
  3323.          for functions called by the current program.  F10 performs
  3324.          the same function as the Run:Trace menu option.  
  3325.  
  3326.  
  3327.  
  3328.  
  3329.  
  3330.  
  3331.  
  3332.  
  3333.  
  3334.  
  3335.  
  3336.  
  3337.  
  3338.  
  3339.  
  3340.  
  3341.  
  3342.  
  3343.  
  3344.                                           The Debugger Display    3-30
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.      ==================================================================
  3353.      Chapter 4:  Debugging a Program
  3354.  
  3355.      ------------------------------------------------------------------
  3356.  
  3357.           In This Chapter                   4-1
  3358.           
  3359.           Executing Program Code            4-1
  3360.           
  3361.           Inspecting Data and Expressions   4-5
  3362.           
  3363.           Inspecting Program Code           4-7
  3364.           
  3365.           Accessing DOS                     4-10
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  
  3390.  
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.          Chapter 4 -- Debugging a Program
  3419.  
  3420.          So far, we have described some of the most commonly used
  3421.          features of The Clipper Debugger.  We have explained how to
  3422.          start the debugging process and given a description of all
  3423.          the elements of the screen display.  In order to make full
  3424.          use of this knowledge, this chapter provides a more detailed
  3425.          study of the most powerful features, together with
  3426.          suggestions on the most appropriate places to use them.
  3427.  
  3428.  
  3429.       -----------------------------------------------------------------
  3430.       In This Chapter
  3431.  
  3432.          This chapter takes an in-depth look at the features you will
  3433.          use most when debugging a program.  The following topics are
  3434.          covered:
  3435.  
  3436.          *  Executing program code
  3437.  
  3438.          *  Inspecting data and expressions
  3439.  
  3440.          *  Inspecting program code
  3441.  
  3442.          *  Accessing DOS
  3443.  
  3444.  
  3445.       -----------------------------------------------------------------
  3446.       Executing Program Code
  3447.  
  3448.          The most basic function of a debugger is to execute an
  3449.          application and display the results.  This section describes
  3450.          the various ways to run a program and explains how to control
  3451.          the speed and view the output.
  3452.  
  3453.  
  3454.       Modes of Execution
  3455.  
  3456.          The Clipper Debugger provides several different ways to
  3457.          execute a program.  The following table lists each of these
  3458.          methods, together with the mode of execution:
  3459.  
  3460.          Table 4-1: Program Execution Methods
  3461.          --------------------------------------------------------------
  3462.          Method         Execution Mode
  3463.          --------------------------------------------------------------
  3464.          Run:Animate    Animate
  3465.          F5             Run
  3466.          F7             Run to Cursor
  3467.          F8             Single Step
  3468.          F10            Trace
  3469.          ANIMATE        Animate
  3470.          GO             Run
  3471.          STEP           Single Step
  3472.          --------------------------------------------------------------
  3473.  
  3474.  
  3475.  
  3476.  
  3477.                                             Debugging a Program    4-1
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.          *  Single Step Mode
  3486.  
  3487.             F8 executes the program in Single Step Mode.  This mode
  3488.             executes the line of program code highlighted by the
  3489.             Execution Bar, moves the Execution Bar to the next line of
  3490.             code to be executed, and stops.  As functions are called
  3491.             by the current program, their code is displayed in the
  3492.             Code Window.  F8 performs the same function as the STEP
  3493.             command and the Run:Step menu option.
  3494.  
  3495.             When single stepping through a piece of code containing a
  3496.             code block, the Execution Bar moves to the line of code
  3497.             where the block was created when the code block is
  3498.             evaluated.  This allows you to see the contents of the
  3499.             block (which are unavailable during normal inspection),
  3500.             and occurs regardless of whether the block was declared in
  3501.             the current routine.  Press F8 again to move past this
  3502.             line to the next executable line.  This behavior can be
  3503.             controlled using the Options:Codeblock Trace menu option.
  3504.  
  3505.             This execution mode is best used in situations where the
  3506.             error you are looking for has been narrowed down to a few
  3507.             lines of code.  It allows you to step slowly through each
  3508.             line, viewing the output and examining variables as you
  3509.             go.
  3510.  
  3511.  
  3512.          *  Trace Mode
  3513.  
  3514.             Trace Mode is similar to Single Step Mode in that it
  3515.             executes one line of program code at a time.  However,
  3516.             Trace Mode does not display the code for functions and
  3517.             procedures called by the current program nor does it trace
  3518.             code blocks back to their definition.  F10 executes the
  3519.             line of code currently at the Execution Bar in Trace
  3520.             Mode.  Alternatively, the Run:Trace menu option can be
  3521.             used.
  3522.  
  3523.  
  3524.          *  Animate Mode
  3525.  
  3526.             In Animate Mode, the application runs one line at a time,
  3527.             with the Execution Bar moving to each line as it is
  3528.             executed.  If the Options:Exchange Screens menu option is
  3529.             ON, the output of each line is shown after the line has
  3530.             been run.  The next line is then executed, and so on. 
  3531.             This continues until you press a key, or until a
  3532.             Breakpoint or Tracepoint is reached.  Animate Mode allows
  3533.             you to execute large portions of an application, stopping
  3534.             when the value of a "suspect" variable or expression
  3535.             changes.  It is used by the ANIMATE command and the
  3536.             Run:Animate menu option.
  3537.  
  3538.  
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544.                                             Debugging a Program    4-2
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.          *  Run Mode
  3553.  
  3554.             The Run Mode is the fastest way to execute a program. 
  3555.             Your application runs until a Breakpoint or Tracepoint is
  3556.             reached, without returning to the Debugger display for
  3557.             each line of code executed.  This mode is used by the GO
  3558.             command, the Run:Go and Run:To Cursor menu options, and
  3559.             the F5 and F7 keys.
  3560.  
  3561.  
  3562.       Finding Program Errors
  3563.  
  3564.          As we have already mentioned, the Debugger provides several
  3565.          ways to execute a program.  The method you use depends on how
  3566.          far you have progressed in your debugging effort.  The
  3567.          following sections explain three common debugging stages and
  3568.          suggest an appropriate method for each stage.
  3569.  
  3570.  
  3571.          --------------------------------------------------------------
  3572.          Starting Out
  3573.  
  3574.          The easiest way to debug a program for the first time is to
  3575.          use the F5 key or the GO command to run the application
  3576.          without pausing, showing the program output in the context of
  3577.          the application (Run Mode).  As soon as you notice a possible
  3578.          error, press Alt-D to invoke the Debugger.
  3579.  
  3580.          Simple errors, such as mistakes in screen design, can be
  3581.          amended immediately.  In these cases, it usually is not
  3582.          necessary to re-compile and re-link before continuing; the
  3583.          errors do not affect the actual execution of a program, only
  3584.          the display.  For more complex problems, you must continue to
  3585.          the next stage of debugging: taking a closer look.
  3586.  
  3587.  
  3588.          --------------------------------------------------------------
  3589.          Taking a Closer Look
  3590.  
  3591.          When the cause of a problem is not immediately obvious, the
  3592.          next step is to closely examine the contents of suspected
  3593.          fields, memory variables and expressions.  Often, the ?|??
  3594.          command reveals an unexpected value for one of these items. 
  3595.          If this is the case, specify the item as a Watchpoint or
  3596.          Tracepoint.  This allows you to pinpoint exactly where in the
  3597.          application the erroneous value was stored.
  3598.  
  3599.          If you suspect that several variables in a particular storage
  3600.          class may be at fault, use the options on the Monitor menu to
  3601.          display these variables in the Monitor Window.  For example,
  3602.          to display PRIVATE variables, select the Monitor:Private
  3603.          option.  As you continue your debugging session, the PRIVATE
  3604.          variables visible to the routine displayed in the Code Window
  3605.          are updated in the Monitor Window.
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.                                             Debugging a Program    4-3
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.          After setting up the necessary Watchpoints and Tracepoints,
  3620.          use the ANIMATE command or the Run:Animate menu option to run
  3621.          the program slowly, displaying the code for each line
  3622.          executed (Animate Mode).  The SPEED command and the Run:Speed
  3623.          menu option can be used to control the speed of the display.
  3624.  
  3625.          Continue this process until the problem has been confined to
  3626.          a few lines of code.  Now it is time to move on to the final
  3627.          stage.
  3628.  
  3629.  
  3630.          --------------------------------------------------------------
  3631.          Final Stage
  3632.  
  3633.          When the cause of an error has been narrowed down to a few
  3634.          lines of code, use the F9 key or the BP command to set a
  3635.          Breakpoint at the first of these lines.  Then use the F5 key
  3636.          or the GO command to execute the application up to that
  3637.          point.
  3638.  
  3639.          When you have reached the suspect area of code, use the F8
  3640.          key to step through the code one line at a time.  If you are
  3641.          certain that the error is in the current program and not in
  3642.          any subsidiary procedures or functions, use the F10 key
  3643.          instead; this does not display the code for called
  3644.          procedures.
  3645.  
  3646.          Executing your application in Single Step Mode while watching
  3647.          the values of the items in the Watch Window is usually
  3648.          sufficient to uncover the cause of a problem.  Having done
  3649.          that, simply alter your code, re-compile, re-link, and begin
  3650.          searching for the next error.
  3651.  
  3652.  
  3653.       Viewing Program Output
  3654.  
  3655.          There may be times when you want to look at the output of a
  3656.          program rather than the code.  The first three ways to
  3657.          achieve this are the F4 key, the OUTPUT command, and the
  3658.          View:App Screen menu option.  Each of these methods erases
  3659.          the Debugger screen and displays the current output exactly
  3660.          as the person running the application will see it.  Press any
  3661.          key to return to the original display.
  3662.  
  3663.          Alternatively, program output can be viewed following
  3664.          execution of each individual line of code.  This is achieved
  3665.          by setting the Options:Exchange Screens menu option, then
  3666.          using the ANIMATE command or the Run:Animate menu option.
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.                                             Debugging a Program    4-4
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.       -----------------------------------------------------------------
  3687.       Inspecting Data and Expressions
  3688.  
  3689.          One of the most common uses for a debugger is examining
  3690.          (inspecting) and altering the values of variables and
  3691.          expressions.  The Clipper Debugger provides several ways to
  3692.          do this: the first of these is the ?|?? command.
  3693.  
  3694.          When you enter "?" followed by an expression, the expression
  3695.          is evaluated and the return value displayed in the Command
  3696.          Window.  This is a useful feature that allows you to execute
  3697.          procedures and functions linked into your application.
  3698.  
  3699.          An alternative way to inspect data and expressions is to set
  3700.          up Watchpoints and Tracepoints.  These are explained in the
  3701.          following sections.
  3702.  
  3703.  
  3704.       Using Watchpoints and Tracepoints
  3705.  
  3706.          Watchpoints and Tracepoints are two of the most valuable
  3707.          features of The Clipper Debugger.  They allow you to examine
  3708.          field variables, memory variables and expressions, and to
  3709.          pinpoint exactly where in your application their values
  3710.          change.  This section gives a definition of Watchpoints and
  3711.          Tracepoints and explains how they are set, deleted and
  3712.          inspected.
  3713.  
  3714.  
  3715.          --------------------------------------------------------------
  3716.          Definition of Watchpoints and Tracepoints
  3717.  
  3718.          A Watchpoint is a field, memory variable or expression whose
  3719.          current value is displayed in the Watch Window.  This value
  3720.          is updated as your application executes.
  3721.  
  3722.          A Tracepoint is similar to a Watchpoint; however, whenever
  3723.          its value changes, program execution pauses and control
  3724.          passes to the Debugger.  In this respect, a Tracepoint is
  3725.          similar to a Breakpoint.
  3726.  
  3727.  
  3728.          --------------------------------------------------------------
  3729.          Setting Watchpoints and Tracepoints
  3730.  
  3731.          There are several ways to set Watchpoints and Tracepoints. 
  3732.          If you use the Watchpoint and Tracepoint options on the Point
  3733.          menu, a dialog box is displayed and you are prompted to enter
  3734.          an expression or the name of a variable.  Your entry then
  3735.          appears in the Watch Window, together with the type and value
  3736.          and the word "wp" or "tp."  Alternatively, you can use the WP
  3737.          or TP commands and specify the name of the variable on the
  3738.          command-line.
  3739.  
  3740.          > WP nPageNum <Return>
  3741.          
  3742.  
  3743.  
  3744.  
  3745.                                             Debugging a Program    4-5
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.          > TP nInvNum = 1000 <Return>
  3754.  
  3755.  
  3756.          --------------------------------------------------------------
  3757.          Deleting Watchpoints and Tracepoints
  3758.  
  3759.          To delete an individual Watchpoint or Tracepoint, use the
  3760.          Point:Delete menu option.  When the dialog box appears, enter
  3761.          the number that appears on the far left-hand side of the
  3762.          Watch Window.  Alternatively, you can use the DELETE command
  3763.          and specify the Watchpoint or Tracepoint number on the
  3764.          command-line.  Using either method, the specified entry is
  3765.          removed from the Watch Window and the numbers of all the
  3766.          remaining entries are updated.
  3767.  
  3768.          To delete all Watchpoints and Tracepoints, use the DELETE
  3769.          command as follows:
  3770.  
  3771.          > DELETE ALL WP <Return>
  3772.          
  3773.          > DELETE ALL TP <Return>
  3774.          
  3775.          --------------------------------------------------------------
  3776.          Warning
  3777.  
  3778.          Be careful not to use DELETE ALL on its own: this deletes all
  3779.          Watchpoints, Tracepoints, and Breakpoints.
  3780.          --------------------------------------------------------------
  3781.  
  3782.  
  3783.          --------------------------------------------------------------
  3784.          Listing Watchpoints and Tracepoints
  3785.  
  3786.          To display all Watchpoints and Tracepoints, use the LIST
  3787.          command as follows:
  3788.  
  3789.          > LIST WP <Return>
  3790.          
  3791.          > LIST TP <Return>
  3792.  
  3793.  
  3794.          --------------------------------------------------------------
  3795.          Inspecting Watchpoints and Tracepoints
  3796.  
  3797.          To inspect a Watchpoint or Tracepoint and change its value,
  3798.          select the Watch Window, move the highlight bar to the item
  3799.          you wish to inspect, and press Return.  The current value of
  3800.          the field, memory variable or expression is displayed in a
  3801.          dialog box.  Within the dialog box, you can either enter a
  3802.          new value and press Return, or press Esc to leave the
  3803.          variable as it is.
  3804.  
  3805.          When you are finished inspecting items in the Watch Window,
  3806.          you can select another window with Tab or Shift-Tab.  For
  3807.          more information on the keys used to navigate the Watch
  3808.          Window, see Chapter 3, The Debugger Display.
  3809.  
  3810.  
  3811.  
  3812.                                             Debugging a Program    4-6
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.          --------------------------------------------------------------
  3821.          Creating New Variables
  3822.  
  3823.          Sometimes, an error may be caused by something as simple as a
  3824.          misspelled variable name.  In this case, you may want to
  3825.          create the variable from within the Debugger in order to
  3826.          continue debugging.
  3827.  
  3828.          Using the ?|?? command, a PRIVATE variable can be created and
  3829.          assigned a value.  For example:
  3830.  
  3831.          > ? myVar := 100 <Return>
  3832.          
  3833.          This creates a variable called myVar and assigns it a value
  3834.          of 100.  Remember that this variable is PRIVATE to the
  3835.          routine being executed when it was created.
  3836.  
  3837.          Only the in-line assignment (:=) operator can be used in this
  3838.          way: if the = operator had been used in the above example,
  3839.          the Debugger would have performed a comparison.
  3840.  
  3841.  
  3842.       -----------------------------------------------------------------
  3843.       Inspecting Program Code
  3844.  
  3845.          As you debug an application, you may need to examine the code
  3846.          of programs other than the one currently being executed. 
  3847.          This section describes how to view other programs and header
  3848.          files, and how to use the Callstack to access programs which
  3849.          have already been executed.  Breakpoints are also discussed.
  3850.  
  3851.  
  3852.       Using Breakpoints
  3853.  
  3854.          Breakpoints are similar to, and just as powerful as,
  3855.          Watchpoints and Tracepoints.  However, Breakpoints refer to
  3856.          actual lines of code rather than variables and expressions.  
  3857.  
  3858.          Breakpoints allow you to return control to the Debugger and
  3859.          execute problem areas of code in Single Step Mode (for an
  3860.          explanation of the modes of execution, see Executing Code in
  3861.          this chapter).  This section explains what Breakpoints are
  3862.          and how to set, delete and list them.
  3863.  
  3864.  
  3865.          --------------------------------------------------------------
  3866.          Definition of a Breakpoint
  3867.  
  3868.          A Breakpoint is a line of program code that causes execution
  3869.          to halt as soon as it is reached.
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.                                             Debugging a Program    4-7
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.          --------------------------------------------------------------
  3888.          Setting Breakpoints
  3889.  
  3890.          To set a Breakpoint, use the BP command or move the cursor to
  3891.          the appropriate line in the Code Window and select the
  3892.          Point:Breakpoint menu option.  Selecting this menu option is
  3893.          equivalent to pressing F9.  The selected line is highlighted.
  3894.  
  3895.          To pause execution whenever a particular routine is called,
  3896.          use the following syntax:
  3897.  
  3898.          > BP SayData <Return>
  3899.          
  3900.          Breakpoints can also be set in programs other than the one
  3901.          currently displayed in the Code Window.  This example sets a
  3902.          Breakpoint at line 15 in the program OpenDbfs.prg:
  3903.  
  3904.          > BP 15 IN OpenDbfs.prg <Return>
  3905.  
  3906.  
  3907.          --------------------------------------------------------------
  3908.          Deleting Breakpoints
  3909.  
  3910.          There are several ways to delete an individual Breakpoint. 
  3911.          The first is to move the cursor to the appropriate line in
  3912.          the Code Window and select Point:Breakpoint or press F9. 
  3913.          When the Breakpoint is deleted, the line returns to its
  3914.          normal color.
  3915.  
  3916.          Another way to delete a Breakpoint is to use the DELETE BP
  3917.          command followed by the Breakpoint number on the
  3918.          command-line.  Note that Breakpoint numbering begins with
  3919.          zero.  If you do not know the number, use the LIST command
  3920.          (see Listing Breakpoints in this chapter).
  3921.  
  3922.          To delete all Breakpoints, use the DELETE command as follows:
  3923.  
  3924.          > DELETE ALL BP <Return>
  3925.          
  3926.          --------------------------------------------------------------
  3927.          Warning
  3928.  
  3929.          Note that DELETE ALL without any other arguments also deletes
  3930.          all Watchpoints and Tracepoints.
  3931.          --------------------------------------------------------------
  3932.  
  3933.  
  3934.          --------------------------------------------------------------
  3935.          Listing Breakpoints
  3936.  
  3937.          To display all Breakpoints, use the LIST BP command.  This
  3938.          lists and numbers Breakpoints in the order they were
  3939.          entered.  Note that numbering begins with zero.
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.                                             Debugging a Program    4-8
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.       Navigating the Callstack
  3955.  
  3956.          The Callstack is a list of pending activations, including
  3957.          procedures, functions, code blocks and message sends.  It is
  3958.          displayed in the Callstack Window on the right-hand side of
  3959.          the screen, which is controlled using the CALLSTACK command
  3960.          or the View:Callstack menu option.
  3961.  
  3962.          When it is active, the Callstack Window allows you to
  3963.          highlight a program and view it in the Code Window.  To
  3964.          select the window, press Tab until its border is highlighted.
  3965.  
  3966.          When the Callstack Window is active, the highlight bar
  3967.          appears on the first item in the window.  You can use Uparrow
  3968.          and Dnarrow to move to the activation whose code you wish to
  3969.          view.  As the highlight is moved within the window, the Code
  3970.          Window is immediately updated to display the selected code. 
  3971.          To return to the program originally being debugged, use the
  3972.          RESUME command or the File:Resume menu option.  For a list of
  3973.          the Callstack navigation keys, see Chapter 3, The Debugger
  3974.          Display.
  3975.  
  3976.          If the activation you have chosen is a code block (denoted by
  3977.          a lower case "b"), the name in the Callstack is the name of
  3978.          the routine in which the block was created.  It is this code
  3979.          that appears in the Code Window.
  3980.  
  3981.          The Callstack is only concerned with executable code.  If you
  3982.          want to view the contents of a header file you must use the
  3983.          procedure outlined in the following section.
  3984.  
  3985.  
  3986.       Viewing Files
  3987.  
  3988.          Although inspecting the Callstack provides an easy way to
  3989.          select and view program code, it does not display header
  3990.          files.  If you already know the name of the program you want
  3991.          to look at, or you want to examine a header file, use the
  3992.          VIEW command or the File:Open menu option.
  3993.  
  3994.          The following example displays the code for the header file
  3995.          Inkey.ch in the Code Window:
  3996.  
  3997.          > VIEW C:\CLIPPER5\INCLUDE\Inkey.ch <Return>
  3998.          
  3999.          Notice that this example gives a file extension; if none is
  4000.          supplied, a (.prg) extension is assumed.
  4001.  
  4002.          When viewing a program file, Breakpoints can be set.  When
  4003.          you return to the original program by using the RESUME
  4004.          command or the File:Resume menu option, these settings are
  4005.          saved.
  4006.  
  4007.          For a list of navigation keys used within the Code Window,
  4008.          see Chapter 3, The Debugger Display.
  4009.  
  4010.  
  4011.  
  4012.  
  4013.                                             Debugging a Program    4-9
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.       -----------------------------------------------------------------
  4022.       Accessing DOS
  4023.  
  4024.          There may be times when you wish to execute a DOS command
  4025.          without leaving the Debugger.  For example, you may want to
  4026.          see a directory listing of all program (.prg) files.  To do
  4027.          this, use the DOS command or select the File:DOS Access menu
  4028.          option.
  4029.  
  4030.          Both DOS access methods mentioned above invoke a temporary
  4031.          copy of COMMAND.COM.  Make sure that you have sufficient
  4032.          memory available to load this file and any others you may
  4033.          wish to execute.  Remember that you are using a temporary
  4034.          copy of DOS, so any environment variables you set will be
  4035.          lost upon returning to the Debugger.
  4036.  
  4037.          When you have finished and wish to continue executing your
  4038.          application, type "Exit" at the DOS prompt.
  4039.  
  4040.  
  4041.  
  4042.  
  4043.  
  4044.  
  4045.  
  4046.  
  4047.  
  4048.  
  4049.  
  4050.  
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.  
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.                                            Debugging a Program    4-10
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.      ==================================================================
  4089.      Chapter 5:  Command Reference
  4090.  
  4091.      ------------------------------------------------------------------
  4092.           ?|??               5-2
  4093.           ANIMATE            5-4
  4094.           BP                 5-5
  4095.           CALLSTACK          5-6
  4096.           DELETE             5-7
  4097.           DOS                5-9
  4098.           FIND               5-10
  4099.           GO                 5-11
  4100.           GOTO               5-12
  4101.           HELP               5-13
  4102.           INPUT              5-14
  4103.           LIST               5-15
  4104.           NEXT               5-16
  4105.           NUM                5-17
  4106.           OUTPUT             5-18
  4107.           PREV               5-19
  4108.           QUIT               5-20
  4109.           RESTART            5-21
  4110.           RESUME             5-22
  4111.           SPEED              5-23
  4112.           STEP               5-24
  4113.           TP                 5-25
  4114.           VIEW               5-26
  4115.           WP                 5-27
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.          Chapter 5 -- Command Reference
  4155.  
  4156.          Once you have become familiar with the features of The
  4157.          Clipper Debugger, you may want to bypass the menu system and
  4158.          enter commands directly.  To do this, simply type the command
  4159.          and press Return to execute.  No matter which window is
  4160.          active, the command will appear in the Command Window as you
  4161.          are typing.  Command results, if any, are also displayed in
  4162.          the Command Window.
  4163.  
  4164.          There are two sets of Debugger commands: the menu commands
  4165.          and the commands discussed in this chapter.  Any Debugger
  4166.          menu option can be expressed in the form of a menu command
  4167.          using the menu name followed by the first word of the option
  4168.          name.  If required, arguments are placed at the end of the
  4169.          menu command-line.
  4170.  
  4171.          This chapter explains the syntax and arguments of all other
  4172.          Debugger commands and offers examples of their use.
  4173.  
  4174.  
  4175.  
  4176.  
  4177.  
  4178.  
  4179.  
  4180.  
  4181.  
  4182.  
  4183.  
  4184.  
  4185.  
  4186.  
  4187.  
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.                                               Command Reference    5-1
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.          ?|??
  4222.          Display the value of an expression
  4223.  
  4224.          Syntax
  4225.  
  4226.             ? | ?? <exp>
  4227.             
  4228.          Arguments
  4229.  
  4230.             <exp> is the expression to be displayed.
  4231.  
  4232.          Description
  4233.  
  4234.             ? causes the value of the specified expression to be
  4235.             displayed in the Command Window.  ?? displays the value in a
  4236.             pop-up window which is closed by pressing Esc.  The
  4237.             expression used as the ?|?? command-line argument can be any
  4238.             valid Clipper expression, including user-defined function,
  4239.             arrays, and in-line assignments.
  4240.  
  4241.             When the display expression is a code block or an object, the
  4242.             value cannot actually be displayed.  For these data types, an
  4243.             icon is displayed instead.
  4244.  
  4245.             If the expression is an array, an icon is displayed if the
  4246.             array name is displayed with either ? or ??.  ??, however,
  4247.             will also display the array contents if you press Return in
  4248.             the first pop-up window.  To close both pop-ups, you must
  4249.             press Esc twice.  With ?, you can query individual array
  4250.             elements by subscripting the array name.
  4251.  
  4252.             The ability to display the return value of a user-defined
  4253.             function allows you to extend the abilities of The Clipper
  4254.             Debugger.  For example, you might want to modify the
  4255.             structure of a database file while debugging an application. 
  4256.             To do this, simply write a function to perform the
  4257.             modification, compile and link it with your application, and
  4258.             execute it using the ?|?? command.  Any feature that doesn't
  4259.             already exist can be written as a user-defined function and
  4260.             executed in this way.
  4261.  
  4262.             Using the in-line assignment (:=) operator with the ?|??
  4263.             command allows you to create new variables.
  4264.  
  4265.          Examples
  4266.  
  4267.             *  This example displays the value of a numeric field in the
  4268.                Command Window:
  4269.  
  4270.                > ? InvNum <Return>
  4271.                   465
  4272.                
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.                                               Command Reference    5-2
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.  
  4287.  
  4288.             *  This shows the result of an expression in the Command
  4289.                Window:
  4290.  
  4291.                > ? X = Y <Return>
  4292.                   .T.
  4293.                
  4294.             *  Here, the return value of a Clipper function is shown in
  4295.                the Command Window:
  4296.  
  4297.                > ? EOF() <Return>
  4298.                   .F.
  4299.  
  4300.             *  In this example, the EVAL() function is used to execute a
  4301.                code block:
  4302.  
  4303.                > ? EVAL(bSortBlock) <Return>
  4304.                
  4305.             *  This example creates a new PRIVATE variable called
  4306.                nPageNo, assigns it the value 2, and displays the variable
  4307.                in a pop-up window.  To close the window, press Esc:
  4308.  
  4309.                > ?? nPageNo := 2 <Return>
  4310.                
  4311.  
  4312.  
  4313.  
  4314.  
  4315.  
  4316.  
  4317.  
  4318.  
  4319.  
  4320.  
  4321.  
  4322.  
  4323.  
  4324.  
  4325.  
  4326.  
  4327.  
  4328.  
  4329.  
  4330.  
  4331.  
  4332.  
  4333.  
  4334.  
  4335.  
  4336.  
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.                                               Command Reference    5-3
  4348.  
  4349.  
  4350.  
  4351.  
  4352.  
  4353.  
  4354.  
  4355.          ANIMATE
  4356.          Run application in Animate Mode
  4357.  
  4358.          Syntax
  4359.  
  4360.             ANIMATE
  4361.             
  4362.          Description
  4363.  
  4364.             The ANIMATE command runs the application in Animate Mode. 
  4365.             This means that the debugger executes a single line, move the
  4366.             Execution Bar to the next line, execute it, and so on. If the
  4367.             Options:Exchange Screens menu option is ON, the output of
  4368.             each line is displayed after the line has been executed.
  4369.  
  4370.             This continues until a Breakpoint or Tracepoint is reached. 
  4371.             To control the speed of this process, use the SPEED command
  4372.             or the Run:Speed menu option.  Press any key to stop
  4373.             execution.  For more information on execution modes, see
  4374.             Chapter 4, Debugging a Program.
  4375.  
  4376.          See also:  Run:Animate, SPEED
  4377.  
  4378.  
  4379.  
  4380.  
  4381.  
  4382.  
  4383.  
  4384.  
  4385.  
  4386.  
  4387.  
  4388.  
  4389.  
  4390.  
  4391.  
  4392.  
  4393.  
  4394.  
  4395.  
  4396.  
  4397.  
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.                                               Command Reference    5-4
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.          BP
  4423.          Set a Breakpoint
  4424.  
  4425.          Syntax
  4426.  
  4427.             BP [AT] <lineNum> [[IN] <idProgramFile>]]
  4428.             BP <idFunction>  |  <idProcedure>
  4429.             
  4430.          Arguments
  4431.  
  4432.             <lineNum> is the line number where you want program execution
  4433.             to stop.
  4434.  
  4435.             <idProgramFile> is the filename of the program in which to
  4436.             set the Breakpoint.  If no extension is specified, (.prg) is
  4437.             assumed.
  4438.  
  4439.             <idFunction>|<idProcedure> is the name of the routine where
  4440.             you want program execution to stop.  Function names are
  4441.             specified without parentheses.
  4442.  
  4443.          Description
  4444.  
  4445.             BP designates a line of program code or a call to a routine
  4446.             as a Breakpoint.  This causes execution to pause as soon as
  4447.             the line is encountered or the routine is called.  To delete
  4448.             a Breakpoint, use the DELETE command.
  4449.  
  4450.             For more information on the use of Breakpoints, see Chapter
  4451.             4, Debugging a Program.
  4452.  
  4453.          Examples
  4454.  
  4455.             *  Entering:
  4456.  
  4457.                > BP 12 <Return>
  4458.                
  4459.                highlights line 12 of the program displayed in the Code
  4460.                Window.  Highlighted lines are those lines that have been
  4461.                designated as Breakpoints.
  4462.  
  4463.             *  This example inserts a Breakpoint at line 15 of File2.prg:
  4464.  
  4465.                > BP AT 15 IN File2.prg <Return>
  4466.                
  4467.             *  Here, a user-defined function is used as a Breakpoint. 
  4468.                Execution pauses as soon as the function is called:
  4469.  
  4470.                > BP TestUdf <Return>
  4471.                
  4472.          See also:  F9, DELETE, GO, LIST, STEP
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.                                               Command Reference    5-5
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.          CALLSTACK
  4490.          Control the Callstack Window
  4491.  
  4492.          Syntax
  4493.  
  4494.             CALLSTACK [on | OFF]
  4495.             
  4496.          Arguments
  4497.  
  4498.             ON opens the Callstack Window on the right-hand side of the
  4499.             screen.
  4500.  
  4501.             OFF closes the Callstack Window.
  4502.  
  4503.             If no options are specified, CALLSTACK acts as a toggle by
  4504.             changing the current status of the Callstack Window (e.g., if
  4505.             it is ON, CALLSTACK turns if OFF).
  4506.  
  4507.          Description 
  4508.  
  4509.             CALLSTACK toggles the display of the Callstack Window.  This
  4510.             window contains the Callstack: a list of pending activations
  4511.             with the current activation at the top.  For more information
  4512.             on the Callstack, see Chapter 4, Debugging a Program.
  4513.  
  4514.          Example
  4515.  
  4516.             *  To open the Callstack Window, enter:
  4517.  
  4518.                > CALLSTACK ON <Return>
  4519.                
  4520.             *  To close the window, type:
  4521.  
  4522.                > CALLSTACK OFF <Return>
  4523.                
  4524.          See also:  View:Callstack
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.  
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542.  
  4543.  
  4544.  
  4545.  
  4546.  
  4547.  
  4548.                                               Command Reference    5-6
  4549.  
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.          DELETE
  4557.          Delete debugger settings
  4558.  
  4559.          Syntax
  4560.  
  4561.             DELETE ALL [BP | TP | WP]
  4562.             DELETE BP | TP | WP <number>
  4563.             
  4564.          Arguments
  4565.  
  4566.             ALL deletes all settings of a specified type or all settings
  4567.             if no type is specified.
  4568.  
  4569.             BP specifies Breakpoints.
  4570.  
  4571.             TP specifies Tracepoints.
  4572.  
  4573.             WP specifies Watchpoints.
  4574.  
  4575.             <number> is the number of the individual Watchpoint,
  4576.             Tracepoint, or Breakpoint to delete.
  4577.  
  4578.          Description
  4579.  
  4580.             DELETE deletes Watchpoints, Tracepoints, and Breakpoints,
  4581.             either individually or as a whole.  For a detailed
  4582.             explanation of these items, see Chapter 4, Debugging a
  4583.             Program.
  4584.  
  4585.             If you want to perform a single deletion, you must specify
  4586.             the number of the item to be deleted.  If not, DELETE opens a
  4587.             dialog box to prompt you for the item number.  For
  4588.             Watchpoints and Tracepoints, this is the number that appears
  4589.             on the left-hand side of the Watch Window.  For Breakpoints
  4590.             the LIST command must be used to determine the number.
  4591.  
  4592.          Examples
  4593.  
  4594.             *  To delete a Breakpoint, you must first find out where it
  4595.                falls in the list of Breakpoints:
  4596.  
  4597.                > LIST BP <Return>
  4598.                
  4599.                If the Breakpoint you want to delete is number three on
  4600.                the list, type:
  4601.  
  4602.                > DELETE BP 3 <Return>
  4603.                
  4604.                and the Breakpoint is deleted.
  4605.  
  4606.             *  This example deletes all Watchpoints:
  4607.  
  4608.                > DELETE ALL WP <Return>
  4609.                
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.                                               Command Reference    5-7
  4616.  
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.             *  Here, all Breakpoints, Tracepoints, and Watchpoints are
  4624.                deleted:
  4625.  
  4626.                > DELETE ALL <Return>
  4627.                
  4628.          See also:  F9, Point:Delete, BP, LIST, TP, WP
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.  
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.  
  4647.  
  4648.  
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.                                               Command Reference    5-8
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.          DOS
  4691.          Access DOS without leaving the current application
  4692.  
  4693.          Syntax
  4694.  
  4695.             DOS
  4696.             
  4697.       Description
  4698.  
  4699.          DOS loads a temporary copy of COMMAND.COM, allowing you to
  4700.          enter DOS commands without leaving the current application. 
  4701.          To return to the debugger, type "Exit" from the DOS
  4702.          command-line.
  4703.  
  4704.          When using this command, you must make sure sufficient memory
  4705.          is available to load COMMAND.COM and any additional programs
  4706.          you want to execute from the DOS command-line.  If the amount
  4707.          of memory is insufficient, an error message is displayed.
  4708.  
  4709.          See also:  File:DOS Access
  4710.  
  4711.  
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.  
  4748.  
  4749.                                               Command Reference    5-9
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.          FIND
  4758.          Locate a character string
  4759.  
  4760.          Syntax
  4761.  
  4762.             FIND <searchString>
  4763.             
  4764.          Arguments
  4765.  
  4766.             <searchString> is the character string you want to locate.
  4767.  
  4768.          Description
  4769.  
  4770.             FIND searches the file displayed in the Code Window for a
  4771.             specified search string.  If no search string is specified on
  4772.             the FIND command-line, a dialog box opens on the screen to
  4773.             prompt you for one.
  4774.  
  4775.             The search always begins at the first line of code and moves
  4776.             down through the file, regardless of the current cursor
  4777.             position in the Code Window.  If the search string is found,
  4778.             the Debugger moves the cursor to the line containing the
  4779.             first occurrence of the string in the Code Window; otherwise,
  4780.             the cursor remains at its current location.
  4781.  
  4782.             --------------------------------------------------------------
  4783.             Note
  4784.  
  4785.             If the Command Window is active when a FIND command is
  4786.             executed, you will not see the cursor move to its new
  4787.             location in the Code Window.  You must select the Code Window
  4788.             in order to see the new cursor position in the file.
  4789.             --------------------------------------------------------------
  4790.  
  4791.             This command obeys the Locate:Case Sensitive menu setting. 
  4792.             If Case Sensitive is ON (indicated by a check mark), FIND
  4793.             looks for a character string which matches the contents and
  4794.             case of the specified search string.  If OFF, only the
  4795.             contents need be the same.
  4796.  
  4797.          Examples
  4798.  
  4799.             If you suspect that the error you are trying to eliminate
  4800.             relates to a database (.dbf) file that is not open, search
  4801.             for the keyword "USE":
  4802.  
  4803.             > FIND USE <Return>
  4804.             
  4805.          See also:  Locate:Case Sensitive, Locate:Find, NEXT, PREV
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.                                              Command Reference    5-10
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.          GO
  4825.          Execute the application in Run Mode
  4826.  
  4827.          Syntax
  4828.  
  4829.             GO
  4830.             
  4831.          Description
  4832.  
  4833.             GO displays your application screen and executes the
  4834.             application until a Breakpoint or Tracepoint is reached, or
  4835.             until the Debugger is deliberately invoked (i.e., by pressing
  4836.             Alt-D or using ALTD()).  At that point, the debugger screen
  4837.             is redisplayed and program execution halts.  This is known as
  4838.             Run Mode.  Using GO again causes the application to be
  4839.             executed from the current position to the next Breakpoint or
  4840.             Tracepoint.  For more information on modes of execution and
  4841.             the use of Breakpoints and Tracepoints, see Chapter 4,
  4842.             Debugging a Program.
  4843.  
  4844.          Examples
  4845.  
  4846.             Suppose Breakpoints have been set at lines 15 and 30 of the
  4847.             current program.  Typing
  4848.  
  4849.             > GO <Return>
  4850.             
  4851.             executes the application as far as line 15.  Entering GO
  4852.             again executes up to line 30, and so on.
  4853.  
  4854.          See also:  F5, Run:Go
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.  
  4883.                                              Command Reference    5-11
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.          GOTO
  4892.          Move the cursor to a specified line in the Code Window
  4893.  
  4894.          Syntax
  4895.  
  4896.             GOTO <lineNum>
  4897.             
  4898.          Arguments
  4899.  
  4900.             <lineNum> is the number of the line where you want to move
  4901.             the cursor.
  4902.  
  4903.          Description
  4904.  
  4905.             GOTO moves the cursor from its current position in the Code
  4906.             Window to the specified line number.  If no line number is
  4907.             specified on the command-line, GOTO opens a dialog box to
  4908.             prompt you for one.
  4909.  
  4910.             GOTO moves to a specified line number regardless of whether
  4911.             or not line numbers are currently displayed in the Code
  4912.             Window.  However, for the sake of readability we recommend
  4913.             that line numbers be displayed.  For more information refer
  4914.             to the NUM command in this chapter.
  4915.  
  4916.             --------------------------------------------------------------
  4917.             Note
  4918.  
  4919.             If the Command Window is active when a GOTO command is
  4920.             executed, you will not see the cursor move to its new
  4921.             location in the Code Window.  You must select the Code Window
  4922.             in order to see the new cursor position in the file.
  4923.             --------------------------------------------------------------
  4924.  
  4925.          Examples
  4926.  
  4927.             This example moves the cursor to line 30 of the program
  4928.             currently being debugged:
  4929.  
  4930.             > GOTO 30 <Return>
  4931.             
  4932.          See also:  Locate:Goto Line
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.  
  4946.  
  4947.  
  4948.  
  4949.  
  4950.                                              Command Reference    5-12
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956.  
  4957.  
  4958.          HELP
  4959.          Activate the Help Window
  4960.  
  4961.          Syntax
  4962.  
  4963.             HELP
  4964.             
  4965.          Description
  4966.  
  4967.             The Debugger Help Window is divided into two panes: the left
  4968.             pane contains a list of topics for which help is available,
  4969.             and the right pane contains the help text for the currently
  4970.             highlighted topic.  When the Help Window is activated with
  4971.             the HELP command, About Help is highlighted on the left with
  4972.             a very general discussion of navigation within the Help
  4973.             Window.
  4974.  
  4975.             Moving the highlight bar using Uparrow or DnArrow selects a
  4976.             new help topic.  PgUp and PgDn page through the associated
  4977.             help text on the right.  Esc closes the Help Window and
  4978.             returns you to the main Debugger screen.
  4979.  
  4980.             Note that the Help menu can also be used to activate the Help
  4981.             Window.  Each option in this menu activates the Help Window
  4982.             with a particular topic that is highlighted when the window
  4983.             opens.  For example Help:Commands displays the help screen
  4984.             for the Debugger commands.
  4985.  
  4986.             For more information on the Help Window, see Chapter 3, The
  4987.             Debugger Display.
  4988.  
  4989.          See also:   F1, Help:Commands, Help:Keys, Help:Menus,
  4990.                      Help:Windows
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.  
  5007.  
  5008.  
  5009.  
  5010.  
  5011.  
  5012.  
  5013.  
  5014.  
  5015.  
  5016.  
  5017.                                              Command Reference    5-13
  5018.  
  5019.  
  5020.  
  5021.  
  5022.  
  5023.  
  5024.  
  5025.          INPUT
  5026.          Read commands from a script file
  5027.  
  5028.          Syntax
  5029.  
  5030.             INPUT <idScriptFile>
  5031.             
  5032.          Arguments
  5033.  
  5034.             <idScriptFile> is the name of the script file from which to
  5035.             read commands.  If no extension is specified, (.cld) is
  5036.             assumed.
  5037.  
  5038.          Description
  5039.  
  5040.             INPUT causes the debugger to temporarily suspend input from
  5041.             the keyboard and begin reading commands from the specified
  5042.             script file instead.  All commands in this file are read and
  5043.             executed.  For a full explanation of script files and their
  5044.             uses, see Chapter 2, Starting the Debugger.
  5045.  
  5046.             If no filename is entered on the command-line, INPUT opens a
  5047.             dialog box to prompt you for one.
  5048.  
  5049.          Examples
  5050.  
  5051.             To execute the commands in the script file "ViewBug.cld",
  5052.             enter the following:
  5053.  
  5054.             > INPUT ViewBug<Return>
  5055.             
  5056.          See also:  Options:Restore Settings
  5057.  
  5058.  
  5059.  
  5060.  
  5061.  
  5062.  
  5063.  
  5064.  
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.  
  5071.  
  5072.  
  5073.  
  5074.  
  5075.  
  5076.  
  5077.  
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.                                              Command Reference    5-14
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.          LIST
  5093.          List Watchpoints, Tracepoints, and Breakpoints
  5094.  
  5095.          Syntax
  5096.  
  5097.             LIST BP | TP | WP
  5098.             
  5099.          Description
  5100.  
  5101.             LIST displays all Watchpoints, Tracepoints, or Breakpoints in
  5102.             the Command Window.  For more information on the setting and
  5103.             deleting of these items, see Chapter 4, Debugging a Program.
  5104.  
  5105.          Examples
  5106.  
  5107.             *  If there are Breakpoints at lines 10 and 15 of AddData.prg
  5108.                and lines 2 and 6 of ViewData.prg, LIST BP displays the
  5109.                following:
  5110.  
  5111.                0) 10 ADDDATA.PRG
  5112.                1) 15 ADDDATA.PRG
  5113.                2) 2 VIEWDATA.PRG
  5114.                3) 6 VIEWDATA.PRG
  5115.                
  5116.             *  To list all Watchpoints, type:
  5117.  
  5118.                > LIST WP <Return>
  5119.                
  5120.          See also:  BP, DELETE, TP, WP
  5121.  
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.                                              Command Reference    5-15
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.  
  5159.          NEXT
  5160.          Locate the next occurrence of a character string
  5161.  
  5162.          Syntax
  5163.  
  5164.             NEXT
  5165.             
  5166.          Description
  5167.  
  5168.             NEXT locates the next occurrence of the most recently defined
  5169.             search string.  A search string is defined using the FIND
  5170.             command or the Locate:Find menu option.  If no search string
  5171.             has been defined, NEXT opens a dialog box to prompt you for
  5172.             one.
  5173.  
  5174.             The search begins at the current cursor position in the Code
  5175.             Window and moves down through the file.  If a match is found,
  5176.             the Debugger moves the cursor to the line containing the next
  5177.             occurrence of the string; otherwise, the cursor remains at
  5178.             its current location.  Like FIND, NEXT obeys the Locate:Case
  5179.             Sensitive menu setting.
  5180.  
  5181.             --------------------------------------------------------------
  5182.             Note
  5183.  
  5184.             If the Command Window is active when a NEXT command is
  5185.             executed, you will not see the cursor move to its new
  5186.             location in the Code Window.  You must select the Code Window
  5187.             in order to see the new cursor position in the file.
  5188.             --------------------------------------------------------------
  5189.  
  5190.          See also:  Locate:Case Sensitive, Locate:Next, FIND, PREV
  5191.  
  5192.  
  5193.  
  5194.  
  5195.  
  5196.  
  5197.  
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.                                              Command Reference    5-16
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.          NUM
  5227.          Toggle the display of line numbers
  5228.  
  5229.          Syntax
  5230.  
  5231.             NUM [ON | off]
  5232.             
  5233.          Arguments
  5234.  
  5235.             ON displays the line number at the beginning of each line of
  5236.             code.
  5237.  
  5238.             OFF removes the line numbers.
  5239.  
  5240.             If no options are specified, NUM acts as a toggle by changing
  5241.             the line number status.
  5242.  
  5243.          Description
  5244.  
  5245.             NUM toggles the display of line numbers at the beginning of
  5246.             each line of code in the Code Window.  When you first start
  5247.             the debugger, NUM is ON and line numbers are displayed.  This
  5248.             is particularly useful when using the GOTO command to move
  5249.             the cursor to a certain line in the Code Window.
  5250.  
  5251.          See also:  Options:Line Numbers
  5252.  
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.  
  5277.  
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.  
  5285.                                              Command Reference    5-17
  5286.  
  5287.  
  5288.  
  5289.  
  5290.  
  5291.  
  5292.  
  5293.          OUTPUT
  5294.          Display program output
  5295.  
  5296.          Syntax
  5297.  
  5298.             OUTPUT
  5299.             
  5300.          Description
  5301.  
  5302.             OUTPUT temporarily clears the debugger screen and displays
  5303.             your application screen in its place.  This allows you to see
  5304.             the output of the current program in the context of the
  5305.             application itself.  To return to the original screen, press
  5306.             any key.
  5307.  
  5308.          See also:  F4, View:App Screen
  5309.  
  5310.  
  5311.  
  5312.  
  5313.  
  5314.  
  5315.  
  5316.  
  5317.  
  5318.  
  5319.  
  5320.  
  5321.  
  5322.  
  5323.  
  5324.  
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.  
  5352.                                              Command Reference    5-18
  5353.  
  5354.  
  5355.  
  5356.  
  5357.  
  5358.  
  5359.  
  5360.          PREV
  5361.          Locate the previous occurrence of a character string
  5362.  
  5363.          Syntax
  5364.  
  5365.             PREV
  5366.             
  5367.          Description
  5368.  
  5369.             PREV searches for the previous occurrence of the most
  5370.             recently defined search string.  A search string is defined
  5371.             using the FIND command or the Locate:Find menu option.  If no
  5372.             search string has been defined, PREV opens a dialog box to
  5373.             prompt you for one.
  5374.  
  5375.             The search begins at the current cursor position in the Code
  5376.             Window and moves up through the file.  If a match is found,
  5377.             the Debugger moves the cursor to the line containing the
  5378.             previous occurrence of the string; otherwise, the cursor
  5379.             remains at its current location.  Like FIND, PREV obeys the
  5380.             Locate:Case Sensitive menu setting.
  5381.  
  5382.             --------------------------------------------------------------
  5383.             Note
  5384.  
  5385.             If the Command Window is active when a PREV command is
  5386.             executed, you will not see the cursor move to its new
  5387.             location in the Code Window.  You must select the Code Window
  5388.             in order to see the new cursor position in the file.
  5389.             --------------------------------------------------------------
  5390.  
  5391.          See also:  Locate:Case Sensitive, Locate:Previous, FIND, NEXT
  5392.  
  5393.  
  5394.  
  5395.  
  5396.  
  5397.  
  5398.  
  5399.  
  5400.  
  5401.  
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.  
  5408.  
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.  
  5417.  
  5418.  
  5419.                                              Command Reference    5-19
  5420.  
  5421.  
  5422.  
  5423.  
  5424.  
  5425.  
  5426.  
  5427.          QUIT
  5428.          Exit the debugger
  5429.  
  5430.          Syntax
  5431.  
  5432.             QUIT
  5433.             
  5434.          Description
  5435.  
  5436.             QUIT terminates the debugger, closes all files and returns to
  5437.             DOS.
  5438.  
  5439.          See also:  File:Exit
  5440.  
  5441.  
  5442.  
  5443.  
  5444.  
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.  
  5454.  
  5455.  
  5456.  
  5457.  
  5458.  
  5459.  
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.  
  5473.  
  5474.  
  5475.  
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.  
  5483.  
  5484.  
  5485.  
  5486.                                              Command Reference    5-20
  5487.  
  5488.  
  5489.  
  5490.  
  5491.  
  5492.  
  5493.  
  5494.          RESTART
  5495.          Reload the current application again
  5496.  
  5497.          Syntax
  5498.  
  5499.             RESTART
  5500.             
  5501.          Description
  5502.  
  5503.             RESTART reloads the current application in preparation to be
  5504.             re-executed, keeping intact all debugger settings.  This
  5505.             command is the only way to execute an application which has
  5506.             already been run.
  5507.  
  5508.          Examples
  5509.  
  5510.             In this example, the current application is executed:
  5511.  
  5512.             > GO <Return>
  5513.             
  5514.             If errors are discovered, you may want to make changes and
  5515.             run the application again:
  5516.  
  5517.             > RESTART <Return>
  5518.             
  5519.          See also:  Run:Restart
  5520.  
  5521.  
  5522.  
  5523.  
  5524.  
  5525.  
  5526.  
  5527.  
  5528.  
  5529.  
  5530.  
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.                                              Command Reference    5-21
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.          RESUME
  5562.          Return from viewing a file
  5563.  
  5564.          Syntax
  5565.  
  5566.             RESUME  |  .
  5567.             
  5568.          Description
  5569.  
  5570.             RESUME clears the file being viewed with the VIEW command (or
  5571.             using the Callstack Window) and redisplays the file
  5572.             originally shown in the Code Window.  Any Breakpoints which
  5573.             have been set are saved.
  5574.  
  5575.             The period (.) is a synonym for the RESUME command.
  5576.  
  5577.          Examples
  5578.  
  5579.             Suppose the program currently being debugged is called
  5580.             PrintData.prg.  The following line temporarily removes
  5581.             PrintData.prg from the screen and displays ReportHead.prg in
  5582.             its place:
  5583.  
  5584.             > VIEW ReportHead.prg <Return>
  5585.             
  5586.             To return to PrintData.prg, type the following:
  5587.  
  5588.             > RESUME <Return>
  5589.             
  5590.          See also:  File:Resume, VIEW
  5591.  
  5592.  
  5593.  
  5594.  
  5595.  
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.  
  5605.  
  5606.  
  5607.  
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.  
  5615.  
  5616.  
  5617.  
  5618.  
  5619.  
  5620.                                              Command Reference    5-22
  5621.  
  5622.  
  5623.  
  5624.  
  5625.  
  5626.  
  5627.  
  5628.          SPEED
  5629.          Set step delay for Animate Mode
  5630.  
  5631.          Syntax
  5632.  
  5633.             SPEED <delay>
  5634.             
  5635.          Arguments
  5636.  
  5637.             <delay> is the increment of delay for animation in tenths of
  5638.             seconds.
  5639.  
  5640.          Description
  5641.  
  5642.             SPEED controls the speed of display while in Animate Mode
  5643.             (for an explanation of this mode, see Chapter 4, Debugging a
  5644.             Program).  If no argument is specified, SPEED opens a dialog
  5645.             box which displays the current setting and allows you to
  5646.             enter a new setting.
  5647.  
  5648.             Remember that this setting is expressed in tenths of seconds
  5649.             so that smaller settings are faster than larger ones.
  5650.  
  5651.          See also:  Run:Speed, ANIMATE
  5652.  
  5653.  
  5654.  
  5655.  
  5656.  
  5657.  
  5658.  
  5659.  
  5660.  
  5661.  
  5662.  
  5663.  
  5664.  
  5665.  
  5666.  
  5667.  
  5668.  
  5669.  
  5670.  
  5671.  
  5672.  
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.  
  5682.  
  5683.  
  5684.  
  5685.  
  5686.  
  5687.                                              Command Reference    5-23
  5688.  
  5689.  
  5690.  
  5691.  
  5692.  
  5693.  
  5694.  
  5695.          STEP
  5696.          Execute the current program in single step mode
  5697.  
  5698.          Syntax
  5699.  
  5700.             STEP
  5701.             
  5702.          Description
  5703.  
  5704.             STEP executes the current program in single step mode.  This
  5705.             means that it executes the line of code at the Execution Bar,
  5706.             moves the Execution Bar to the next line, and stops.
  5707.  
  5708.          Examples
  5709.  
  5710.             This example executes the next line of the application being
  5711.             debugged:
  5712.  
  5713.             > STEP <Return>
  5714.             
  5715.             The debugger stops with the Execution Bar on the next line to
  5716.             be executed.
  5717.  
  5718.          See also:  F8, Run:Step
  5719.  
  5720.  
  5721.  
  5722.  
  5723.  
  5724.  
  5725.  
  5726.  
  5727.  
  5728.  
  5729.  
  5730.  
  5731.  
  5732.  
  5733.  
  5734.  
  5735.  
  5736.  
  5737.  
  5738.  
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.  
  5748.  
  5749.  
  5750.  
  5751.  
  5752.  
  5753.  
  5754.                                              Command Reference    5-24
  5755.  
  5756.  
  5757.  
  5758.  
  5759.  
  5760.  
  5761.  
  5762.          TP
  5763.          Specify a variable or expression as a Tracepoint
  5764.  
  5765.          Syntax
  5766.  
  5767.             TP <exp>
  5768.             
  5769.          Arguments
  5770.  
  5771.             <exp> is the field variable, memory variable or expression to
  5772.             be traced.  It can be of any data type.
  5773.  
  5774.          Description
  5775.  
  5776.             TP designates the specified variable or expression as a
  5777.             Tracepoint.  If no expression is specified on the
  5778.             command-line, TP opens a dialog box to prompt you for one. 
  5779.             The Tracepoint is then added to the list in the Watch Window.
  5780.  
  5781.             A Tracepoint can be thought of as a conditional Breakpoint. 
  5782.             The two are very similar, except that a Tracepoint halts
  5783.             program execution as soon as its value changes.  For more
  5784.             information on Tracepoints, see Chapter 4, Debugging a
  5785.             Program.
  5786.  
  5787.          Examples
  5788.  
  5789.             *  This example halts execution as soon as the value of the
  5790.                variable nInvNum changes:
  5791.  
  5792.                > TP nInvNum <Return>
  5793.                
  5794.             *  This pauses when end-of-file is reached:
  5795.  
  5796.                > TP EOF() <Return>
  5797.                
  5798.             *  This example halts as soon as the value of i exceeds 10,
  5799.                and is very useful in looping operations:
  5800.  
  5801.                > TP i > 10 <Return>
  5802.                
  5803.          See also:  Point:Tracepoint, DELETE, LIST
  5804.  
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.  
  5819.  
  5820.  
  5821.                                              Command Reference    5-25
  5822.  
  5823.  
  5824.  
  5825.  
  5826.  
  5827.  
  5828.  
  5829.          VIEW
  5830.          Examine a file during the current debugging session
  5831.  
  5832.          Syntax
  5833.  
  5834.             VIEW <idFileName>
  5835.             
  5836.          Arguments
  5837.  
  5838.             <idFileName> is the name of the file you want to examine.
  5839.  
  5840.          Description
  5841.  
  5842.             VIEW allows you to look at other files without leaving the
  5843.             current debugging session.  It can also be used to view
  5844.             header files specified with the #include pre-processor
  5845.             directive.  Breakpoints can be set and are saved when you
  5846.             return to the original program.
  5847.  
  5848.             If no filename is specified on the command-line, VIEW opens a
  5849.             dialog box to prompt you for one.
  5850.  
  5851.          Examples
  5852.  
  5853.             *  To view ListDbfs.prg from within the current program
  5854.                (EnterData.prg), type:
  5855.  
  5856.                > VIEW ListDbfs.prg <Return>
  5857.                
  5858.             *  It is possible to continue viewing other programs without
  5859.                returning to the original program.  For example:
  5860.  
  5861.                > VIEW PrintDbfs.prg <Return>
  5862.                
  5863.                loads PrintDbfs.prg in place of ListDbfs.prg.  Typing
  5864.                RESUME returns the debugger to EnterData.prg--the original
  5865.                program.
  5866.  
  5867.          See also:  File:Open, RESUME
  5868.  
  5869.  
  5870.  
  5871.  
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.  
  5879.  
  5880.  
  5881.  
  5882.  
  5883.  
  5884.  
  5885.  
  5886.  
  5887.  
  5888.                                              Command Reference    5-26
  5889.  
  5890.  
  5891.  
  5892.  
  5893.  
  5894.  
  5895.  
  5896.          WP
  5897.          Specify a variable or expression as a Watchpoint
  5898.  
  5899.          Syntax
  5900.  
  5901.             WP <exp>
  5902.             
  5903.          Arguments
  5904.  
  5905.             <exp> is the field variable, memory variable or expression to
  5906.             be watched and can be of any data type.
  5907.  
  5908.          Description
  5909.  
  5910.             WP designates the specified variable or expression as a
  5911.             Watchpoint.  If no expression is specified on the
  5912.             command-line, WP opens a dialog box to prompt you for one. 
  5913.             The Watchpoint is then added to the list in the Watch Window
  5914.             where it is updated as each line of code is executed.
  5915.  
  5916.             A Watchpoint is identical to a Tracepoint, except that it
  5917.             does not cause a break in program execution every time its
  5918.             value changes.  For more information on Watchpoints, see
  5919.             Chapter 4, Debugging a Program.
  5920.  
  5921.          Examples
  5922.  
  5923.             *  This example specifies the field CustNum as a Watchpoint:
  5924.  
  5925.                > WP CustNum <Return>
  5926.                
  5927.                CustNum now appears in the Watch Window.
  5928.  
  5929.             *  In this example, the current record number is displayed as
  5930.                each line of code is executed:
  5931.  
  5932.                > WP RECNO() <Return>
  5933.                
  5934.          See also:  Point:Watchpoint, DELETE, LIST
  5935.  
  5936.  
  5937.  
  5938.  
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.  
  5945.  
  5946.  
  5947.  
  5948.  
  5949.  
  5950.  
  5951.  
  5952.  
  5953.  
  5954.  
  5955.                                              Command Reference    5-27
  5956.  
  5957.  
  5958.  
  5959.  
  5960.  
  5961.  
  5962.  
  5963.          Glossary
  5964.  
  5965.  
  5966.          Active Window                     Cursor
  5967.                                            
  5968.          The window where all              The cursor indicates the
  5969.          keystrokes (except those valid    current line and/or column
  5970.          in the Command Window) apply.     position in the active window
  5971.          An active window is indicated     or dialog box.  Note that some
  5972.          by a highlighted border.  The     windows, such as the Monitor
  5973.          Tab and Shift-Tab keys are used   Window, do not utilize the
  5974.          to select the next and previous   cursor.  When a window that
  5975.          window, respectively.             does not utilize the cursor is
  5976.                                            active, the cursor appears in
  5977.          Animate Mode                      the Code Window.
  5978.                                            
  5979.          The mode of execution in which    Debugger
  5980.          an application runs one line at   
  5981.          a time until a Breakpoint or      A tool used to track down
  5982.          Tracepoint is reached, with the   errors in a program.
  5983.          Execution Bar moving to each      
  5984.          line as it is executed.           Dialog box
  5985.                                            
  5986.          Breakpoint                        A box displayed from within the
  5987.                                            debugger whenever further input
  5988.          A point at which an application   is required.
  5989.          pauses execution and returns      
  5990.          control to the debugger.          Execution Bar
  5991.                                            
  5992.          Callstack                         The highlight bar which is
  5993.                                            positioned on the line of code
  5994.          A list containing the names of    to be executed next.
  5995.          all pending activations at the    
  5996.          current point in an               Help Window
  5997.          application.                      
  5998.                                            The window in which on-line
  5999.          Callstack Window                  help is displayed.
  6000.                                            
  6001.          The window in which the           Inspecting
  6002.          Callstack is displayed.           
  6003.                                            The process of examining work
  6004.          Code Window                       areas, variables, expressions
  6005.                                            and activations inside the
  6006.          The window in which source code   debugger.
  6007.          is displayed.                     
  6008.                                            Menu Bar
  6009.          Command Window                    
  6010.                                            The bar at the top of the
  6011.          The window in which commands      debugger screen, on which the
  6012.          are displayed and entered.        available menu choices are
  6013.                                            displayed.
  6014.                                            
  6015.                                            
  6016.                                            
  6017.  
  6018.  
  6019.  
  6020.  
  6021.  
  6022.                                          Clipper Debugger Glossary    G-1
  6023.  
  6024.  
  6025.  
  6026.  
  6027.  
  6028.  
  6029.  
  6030.  
  6031.          Monitor Window                    Tracepoint
  6032.                                            
  6033.          The window in which monitored     A variable or expression whose
  6034.          variables are displayed.          value is displayed in the Watch
  6035.                                            Window, and which causes an
  6036.          Monitored variable                application to pause whenever
  6037.                                            that value changes.
  6038.          A variable which is selected by   
  6039.          the options on the Monitor Menu   View Sets Window
  6040.          and displayed in the Monitor      
  6041.          Window.                           The window in which Clipper
  6042.                                            status settings can be
  6043.          Run Mode                          inspected.
  6044.                                            
  6045.          The mode of execution in which    View Workareas Window
  6046.          an application executes without   
  6047.          pausing, until a Breakpoint or    The window in which work area
  6048.          Tracepoint is reached.            information is displayed.
  6049.                                            
  6050.          Script File                       Watch Window
  6051.                                            
  6052.          A file in which frequently used   The window in which Watchpoints
  6053.          debugger commands are stored      and Tracepoints are displayed.
  6054.          and from which those commands     
  6055.          can be executed.                  Watchpoint
  6056.                                            
  6057.          Set Colors Window                 A variable or expression whose
  6058.                                            value is displayed in the Watch
  6059.          The window in which the           Window and updated as an
  6060.          Debugger color settings can be    application executes.
  6061.          inspected.                        
  6062.                                            
  6063.          Single Step Mode                  
  6064.                                            
  6065.          The mode of execution in which    
  6066.          only the line of code             
  6067.          highlighted by the Execution      
  6068.          Bar is executed, and its output   
  6069.          displayed.                        
  6070.                                            
  6071.          Trace Mode                        
  6072.                                            
  6073.          A mode of execution similar to    
  6074.          Single Step Mode, the             
  6075.          difference being that Trace       
  6076.          Mode traces over function and     
  6077.          procedure calls.                  
  6078.                                            
  6079.                                            
  6080.                                            
  6081.                                            
  6082.  
  6083.  
  6084.  
  6085.  
  6086.  
  6087.  
  6088.  
  6089.                                          Clipper Debugger Glossary    G-2
  6090.  
  6091.  
  6092.  
  6093.