Liren Large Software Subsidy 5

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 5 / 05.iso / a / a009 / 5.ddi / DOC.LIF / DEBUGGER.DOC next >

Wrap

Text File | 1991-04-14 | 172.1 KB | 6,007 lines

The Clipper Debugger Version 5.01 The Clipper Debugger Copyright (C) 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991 Nantucket Corporation. All Rights Reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any other language or computer language in whole or in part, in any form or by any means, whether it be electronic, mechanical, magnetic, optical, manual or otherwise, without prior written consent of Nantucket Corporation, 12555 W. Jefferson Blvd., Suite 300, Los Angeles, California 90066. Clipper 5.0 user documentation is printed in the U.S.A. Nantucket believes that the user documentation (both printed and online) accompanying the program contains the necessary information to utilize the program. However, Nantucket reserves the right to make revisions and/or periodic changes to the user documentation content without the direct or inferred obligation of Nantucket to notify any person of such revisions or changes. Except for the limited warranty set forth in the applicable Nantucket Software License Agreement accompanying this product, the user documentation is provided "as is." Nantucket makes no other warranty, express or implied, with respect to the software and/or user documentation, and specifically disclaims the implied warranties of merchantability and fitness for a particular purpose. Nantucket does not warrant that the software and/or user documentation will meet your requirements or that the operation/use of the software and/or user documentation will be uninterrupted or error free. You are solely responsible for the selection of the software and/or user documentation to achieve your intended results and for the results actually obtained. Except as specifically set forth in the applicable Nantucket Software License Agreement accompanying this product, Nantucket does not assume responsibility for the use of the software and/or user documentation. The software contains valuable copyrights, trade secrets and proprietary information all of which are reserved by Nantucket and subject only to the license granted herein. Unauthorized use of the documentation or the software can result in civil damages and criminal prosecution. Please refer to the applicable Nantucket Software License Agreement accompanying this product for additional information. Copyright, Trademark and Service Mark Notices Nantucket (R), the Nantucket logo, and Clipper (R) are registered trademarks of Nantucket Corporation. Nantucket News (TM) is a trademark of Nantucket Corporation. Nantucket Support (sm) is a service mark of Nantucket Corporation. The Guide To Clipper (R) is a product of Nantucket Corporation. dBASE (R), dBASE III (R), dBASE IV (R) and Ashton-Tate (R) are registered trademarks of Ashton-Tate Corporation. dBASE III PLUS (TM) is a trademark of Ashton-Tate Corporation. IBM (R), PC-DOS (R) and PC-AT (R) are registered trademarks of International Business Machines Corporation. Intel (R) is a registered trademark of Intel Corporation. Microsoft (R) is a registered trademark of Microsoft Corporation. Microsoft (R) C Runtime Library Routines, (C) Microsoft Corporation 1984, 1985, 1986, 1987. All Rights Reserved. MS-DOS (R) is a registered trademark of Microsoft Corporation. MASM (TM) is a trademark of Microsoft Corporation. The Norton Instant Access Engine (TM) is a trademark of Peter Norton Computing Incorporated. .RTLINK (TM), (C) Pocket Soft, Inc., 1988, 1989. .RTLink is a trademark of Pocket Soft Inc. Trademarks of other companies mentioned in this documentation appear for identification purposes only. Credits Software Development Architect Richard McConnell Primary Developers Dennis L. Dias Basil Hosmer Richard McConnell Key Contributors Brian Russell (architecture and implementation) Eric Jakstadt (linker) Corey Schwartz (debugger) Leonard Zerman (install system) Documentation Christopher White Deborah Ridolfo Debby Moody Savannah Brentnall Key Contributors Charles R. Gehman (desktop publishing) Administration Dana Wood Software Test Phil Usher Ed Bell Tom Chang Woon L. Leong Tim Wong Fred Ho Jon Rognerud Special thanks to the beta test sites and documentation reviewers whose efforts and patience helped make Clipper 5.01 a reality. ================================================================== Table of Contents ------------------------------------------------------------------ Chapter 1: Introduction to the Debugger............1-1 Chapter 2: Starting the Debugger...................2-1 Chapter 3: The Debugger Display....................3-1 Chapter 4: Debugging a Program.....................4-1 Chapter 5: Command Reference.......................5-1 Glossary ================================================================== Chapter 1: Introduction to the Debugger ------------------------------------------------------------------ In This Chapter 1-1 What is a Debugger? 1-1 Symbols and Conventions 1-2 System Requirements 1-2 What does The Clipper Debugger do? 1-2 Chapter 1 -- Introduction to the Debugger Welcome to The Clipper Debugger. Although you may already be familiar with the process of debugging a compiled application, we recommend that you take the time to read this chapter. The terms used throughout this manual are explained here, together with a list of requirements for using the Debugger and descriptions of some of the most commonly used features. ----------------------------------------------------------------- In This Chapter This chapter provides a brief overview of the Debugger and explains some of its most powerful features. The following topics are covered: * What is a Debugger? * Symbols and conventions * System requirements * What does The Clipper Debugger do? ----------------------------------------------------------------- What is a Debugger? Once you have finished writing a program, it must be tested to make sure there are no errors. Some errors will be spotted by the compiler or linker; in these cases, corrections can be made without having to actually execute the program. It is not at all unusual for a program to contain errors which can only be spotted while the program is running. This is where a debugger becomes useful. As its name suggests, a Debugger is a tool that helps you track down and remove errors (bugs) from your source code. The Clipper Debugger allows you to look at your source code while your program is running. Whenever you notice an error, simply edit the code, re-compile, re-link, and try again. You may need to perform these steps several times. Other features of the Debugger include watching the values of variables and expressions as your program executes, examining database (.dbf) files and executing your program slowly, a line at a time. Introduction 1-1 ----------------------------------------------------------------- Symbols and Conventions In order to specify commands in a general way, certain symbols are used to identify special behavior. For example, keywords and metasymbols in square brackets are optional. The following table shows a list of symbols used throughout this manual: Table 1-1: Symbols -------------------------------------------------------------- Symbol Description -------------------------------------------------------------- < > Indicates an item that is entered by the user [ ] Indicates an optional item or list | Indicates two or more mutually exclusive options -------------------------------------------------------------- ----------------------------------------------------------------- System Requirements * At least one disk drive * 512K of RAM memory * Clipper 5.0 * DOS version 2.0 or greater The Debugger will work on any IBM PC or compatible. At least one disk drive is needed for installation, and a hard disk is recommended. Your computer should have at least 512K of memory, but 640K or more is preferred for best results. The operating system must be DOS version 2.0 or higher. ----------------------------------------------------------------- What does The Clipper Debugger do? There are certain features in The Clipper Debugger that you will find yourself using over and over again. This section is intended as a quick guide to each of these features; more detailed explanations can be found in Chapter 3, The Debugger Display and Chapter 5, Command Reference. -------------------------------------------------------------- Trace Source Code Line by Line When you run a program from within the Debugger, the source code is displayed inside a window called the Code Window. A horizontal Execution Bar highlights each line of code as it is executed, allowing you to see the progress of your Introduction 1-2 application. This can often help eliminate logic or looping errors. The speed of the display can be controlled to suit your needs. -------------------------------------------------------------- Inspect the Values of Variables and Expressions While debugging your application, you may want to examine a memory or field variable. This is called inspecting a variable. Using a highlight bar, the Debugger allows you to select from a list of variables and enter a new value for your selection. This value is then assigned to the variable you selected. In addition, any valid expression can be inspected. This includes Clipper functions, code blocks, macro expressions and user-defined functions. In these cases, the specified code is actually executed, and the return value displayed. -------------------------------------------------------------- Create New Variables Often, an error in your application is caused by the failure to create a particular variable. Using the ?|?? command and the := operator, the Debugger allows you to create a new PRIVATE variable and assign it a value. You can then continue debugging, and correct the error on your next edit/compile/link cycle. -------------------------------------------------------------- Execute Linked Procedures and Functions Any procedure or function which has been compiled and linked with your application can be executed during a debugging session. This provides an easy way to extend the functionality of the Debugger: simply write a function to perform the desired action, re-compile, re-link, and execute. -------------------------------------------------------------- Inspect Work Areas and Set Values There may be times when you need to examine the structure of a database (.dbf) file. The Debugger uses the View Workareas Window to provide this information. The names of the databases open in each work area are shown on the left pane of the window with the currently selected file enclosed in angle brackets (< >). The work area flag settings and file structure for the highlighted filename appear on the right. There is a similar window called the View Sets Window that allows you to inspect and change the status of Clipper SET commands. Introduction 1-3 ================================================================== Chapter 2: Starting the Debugger ------------------------------------------------------------------ In This Chapter 2-1 Preparing your Programs for Debugging 2-1 Invoking the Debugger 2-4 How the Debugger Searches for Files 2-7 Using a Script File 2-7 Getting Help 2-8 Leaving the Debugger 2-9 Chapter 2 -- Starting the Debugger In order to debug an application, you must first create your executable (.EXE) file using the compiler option for debugging. You can then invoke the Debugger and begin the debugging session. Some parts of your application may require source code changes in order to be properly debugged; each of these changes is explained here. ----------------------------------------------------------------- In This Chapter This chapter explains the compilation process, necessary program changes and some techniques to increase debugging speed. The following topics are covered: * Preparing your programs for debugging * Invoking the Debugger * How the Debugger searches for files * Using a script file * Getting help * Leaving the Debugger ----------------------------------------------------------------- Preparing Your Programs for Debugging To take full advantage of the features offered by The Clipper Debugger, there are certain changes you may want to make to your source code. This section describes these changes, together with an explanation of the compilation process. Compiling Your Source Code The first step in debugging an application with the Debugger is to compile using the /B compiler option. This option tells the compiler to include debugging information in the object (.OBJ) file. For example: CLIPPER MainProg /B In this example, all programs called by MainProg.prg are also compiled with the /B option. If, however, you have used (.clp) files or have compiled each program in your application separately, you must specify the /B option every time you invoke the compiler. During the debugging session, any subsidiary programs which have been compiled without this option are ignored. Starting the Debugger 2-1 -------------------------------------------------------------- Warning In order to use The Clipper Debugger, your application must be compiled with Clipper 5.0. -------------------------------------------------------------- Programming Considerations Certain parts of your code present special problems when debugging. This section explains the techniques for debugging multi-statement command-lines, header files, manifest constants, pseudo-functions, code blocks and macros. -------------------------------------------------------------- Multi-statement Command-lines Clipper 5.0 allows you to place more than one program statement on a single line. For example: nNewPage = (nLineNo > 55); ReportPage(nNewPage) When you use Uparrow or Dnarrow in the Code Window, the cursor moves up and down one complete line at a time. This is true regardless of how many statements are on the line in question. In the above example, the Debugger does not allow you to "step" through the first and second statements independently, nor does it allow you to set a Breakpoint at either statement. The entire line is treated as a single entity. The code in the above example should be broken up into two lines, as follows: nNewPage = (nLineNo > 55) ReportPage(nNewPage) This makes debugging easier, and also makes the code more readable. -------------------------------------------------------------- Header Files Header files are files which are referenced using the #include pre-processor directive. They typically contain manifest constant and pseudo-function definitions, but can also contain program source code. To view a header file, press Alt-F to access the File menu, and select the Open option. A dialog box is displayed and you are asked to enter the name of the file you want to Starting the Debugger 2-2 view. Simply enter the name of the header file and its extension, and press Return. The code for the specified header file appears in the Code Window. -------------------------------------------------------------- Manifest Constants and Pseudo-functions Constants and pseudo-functions defined with the #define pre-processor directive cannot be inspected in the same way as variables and expressions. As their name suggests, pre-processor directives are instructions to the pre-processor and do not exist at runtime. If you compile a program using the /P compiler option, a file with a (.ppo) extension is produced. This file shows the pre-processor output, and can be viewed using the Preprocessed Code option on the Options menu. When this menu option is selected (indicated by a check mark) each line of source code is displayed in the Code Window with the output from the pre-processor shown underneath. -------------------------------------------------------------- Code Blocks A code block contains executable program code which is treated by Clipper 5.0 as data and can be passed as a parameter to other programs. This program code is compiled at compile-time, and inspecting the code block only reveals its name, not the actual code. However, code blocks can be executed from within the Debugger as follows: > ? EVAL(bMyBlock) <Return> This example, when entered in the Command Window, causes the code block bMyBlock to be evaluated. Any code within bMyBlock is executed and displayed accordingly. When "stepping" through a piece of code containing a code block, the Execution Bar moves to the line of code where the block was created each time the code block is evaluated. This allows you to see the contents of the block (which are unavailable during normal inspection), and occurs regardless of whether the block was declared in the current routine. -------------------------------------------------------------- Macro Substitution The Debugger treats macros as ordinary character strings. As such, they can be inspected or viewed using the ?|?? command. For example: > ? ¯oVar <Return> Starting the Debugger 2-3 displays the contents of the expanded macro variable macroVar. If the macro variable refers to a code block, the ?|?? command merely displays the code block symbol: "{||...}." Since the code contained within the code block was compiled at compile-time, it is not available to The Clipper Debugger. ----------------------------------------------------------------- Invoking the Debugger There are several ways to invoke the Debugger, each of which is discussed below. All of the methods require that the application be compiled with the /B option--debugging is not possible otherwise. From DOS To invoke the Debugger from the DOS prompt, use the following syntax: CLD [[/43 | /50 | /S] [@<scriptFile>] <exeFile> [<argument list>]] CLD.EXE is The Clipper Debugger executable file. If you installed the Clipper 5.0 development system using the default configuration, CLD.EXE is located in the \CLIPPER5\BIN directory and your DOS PATH should be altered accordingly. /43 | /50 | /S specifies the screen mode used by the Debugger. These three options are mutually exclusive and, if more than one is specified, CLD.EXE uses the last one that occurs on the command-line. The default screen mode is 25 lines, with the Debugger using the entire screen. /43 specifies 43 line mode and is available on EGA monitors only. /50 specifies 50 line mode and is available on EGA and VGA monitors only. /S is available on EGA and VGA monitors only. This option splits the screen between your application and the Debugger, allowing you to view the application and the Debugger simultaneously. On a VGA monitor /S uses 50 line mode, and on an EGA monitor it uses 43 line mode. In split screen mode, the top 25 lines of the screen are used by your application, and the remaining lines are used for the Debugger display. In this mode, you cannot move or size windows in the Debugger. Starting the Debugger 2-4 <scriptFile> is the name of a script file with a default extension of (.cld). CLD searches for the specified <scriptFile> in the current directory and then searches the DOS PATH. A script file is simply an ASCII text file containing one or more Debugger commands, with each command appearing on a separate line. When the Debugger is invoked with a script file, each command in the file is executed automatically after the <exeFile> file is loaded. In addition to any script file called for on the CLD command-line, the Debugger automatically searches for a script file with the name Init.cld. If a file by this name is located in the current directory or anywhere in the DOS PATH, the Debugger executes it as a script file. If both Init.cld and a command-line script file are present, Init.cld is executed first followed by the command-line script file. <exeFile> is the name of the executable (.EXE) file you want to debug. CLD searches for the <exeFile> in the current directory only--the DOS PATH is not searched. If this file has not been compiled using the /B compiler option to embed debugging information, debugging is not possible. <argument list> is the argument list for <exeFile>. Note that with the exception of the argument list, all other CLD arguments must come before the executable filename on the command-line. If no command-line arguments are specified, CLD displays a brief help screen. Linking the Debugger Under certain circumstances, you may want to link the Debugger into your application. Doing this would allow you, for example, to debug a program at a customer's site in the event that an unforeseen problem occurred after the application was already in the field. The Debugger library, CLD.LIB, must be linked into your program as an object file as in the following example: C>RTLINK FI Myprog, \CLIPPER5\LIB\CLD.LIB <Return> Again, your program must be compiled with the /B option. When the Debugger is linked into a program in this manner, it does not come up automatically but must be invoked. Starting the Debugger 2-5 -------------------------------------------------------------- Invoking with Alt-D When an application is linked with CLD.LIB as one of the object files, the Debugger is enabled and can be invoked by pressing Alt-D while the application is running. Doing this invokes the Debugger with the Execution Bar positioned on the current line of executing code. Using ALTD() The ALTD() function serves two purposes: it allows you to control whether or not the Debugger is enabled or disabled, and it allows you to invoke the Debugger if it is enabled. ALTD() can be used regardless of whether the Debugger is invoked using the CLD command-line or using Alt-D. When it appears in a program compiled with the /B option, ALTD() used with no arguments acts like a Breakpoint by stopping the application and giving control to the Debugger. ALTD(0) temporarily disables the Debugger so that any code following the function call is executed as if the Debugger were not present. When the Debugger is disabled, all Breakpoints and Tracepoints are ignored and even calls to ALTD() and pressing Alt-D will not invoke the Debugger while it is disabled. ALTD(1) is used to enable the Debugger again. Note that for programs compiled with /B, the default state for the Debugger is enabled. For applications that are linked with CLD.LIB, you can use ALTD() to prevent the user for inadvertently invoking the Debugger. By including code similar to the following at the beginning of the main program, the ability to invoke the Debugger is controlled by the presence a command-line parameter: PARAMETERS dBug IF dBug != NIL ALTD(1) // Invoke Debugger with ALTD() or Alt-D ELSE ALTD(0) // Debugger cannot be invoked ENDIF Using the code shown above, the Debugger is disabled unless the application is invoked with an argument. Even though the program may contain calls to ALTD() and the user may press Alt-D, the Debugger cannot be invoked unless the application command-line argument is specified. If your application accepts other arguments, use dBug as the last one in the list. Starting the Debugger 2-6 ----------------------------------------------------------------- How the Debugger Searches for Files When you make a file open request to the Debugger, you may specify the drive, directory and file extension explicitly as part of the filename. Otherwise, the Debugger makes certain assumptions about the filename and location. Depending on the context of the file open request, the default file extension supplied by the Debugger varies. For example, when the request is for a script file the Debugger assumes a (.cld) extension and for a pre-processed output file the default extension is (.ppo). Default file extensions are supplied only when you do not specify an explicit file extension. If no explicit file location (i.e., drive or directory) is specified or if the file location cannot be obtained from the application, the Debugger looks for the file in the current directory. Then, with the exception of the .EXE file, the Debugger searches the DOS PATH--the Debugger searches for the executable file in the current directory only. Only after these locations are exhausted will an error message be displayed indicating that the file could not be found. ----------------------------------------------------------------- Using a Script File The Debugger allows you to record commands in a script file and execute the commands directly from the file. A script file is simply an ASCII text file that can be created and edited using any word processor. The file consists of one or more Debugger commands, with each command on a new line in the file and has a default extension of (.cld). Some programs may require several debug/edit/compile/link cycles in order to trace persistent errors. Recording repetitive commands in a script file eliminates the amount of typing necessary to reach the same position in your application each time. For example, the following script file sets a Breakpoint at the first call to the function ViewData(), designates the variables lMadeChanges and lSaveChanges as Watchpoints, and specifies nFieldNum and nFileArea as Tracepoints: BP ViewData WP lMadeChanges WP lSaveChanges TP nFieldNum TP nFileArea Another advantage to using script files is to record preferred Debugger settings so that you do not have to set them each time you debug. The easiest way to record option Starting the Debugger 2-7 settings in a script file is to set them using the Debugger menus. Then, select the Save Settings option from the Options menu and enter a filename when prompted. The script file is saved to disk and can be used or modified at any time. The settings that you can save in this way include most Options menu settings, the Monitor menu settings, and case sensitivity and Callstack status. As an alternative to setting the options and saving them to a script file using the Options menu, you can include the appropriate menu commands in any script file. Menu commands are formed using the menu name followed by the first word of the menu option you want to set. Any necessary arguments are placed at the end of the command. An example of some menu command settings recorded in a script file follows: Locate Case Monitor Local View Callstack Options Line Options Tab 3 When the Debugger is active, you can execute a script file with the View Restore option in the Options menu or with the INPUT command as in the following example: > INPUT MyScript <Return> You can also execute a script file from the Debugger command-line as in the following example: C>CLD @MyScript MainProg <Return> Each time the Debugger is invoked, it automatically searches for a script file with the name Init.cld. If a file by this name is located in the current directory or anywhere in the DOS PATH, the Debugger executes it as a script file. If both Init.cld and a command-line script file are present, Init.cld is executed first followed by the command-line script file. ----------------------------------------------------------------- Getting Help The Clipper Debugger offers on-line help in the form of the Help Window, which is divided into two panes: the left pane contains a list of topics for which help is available, and the right pane contains the help text for the currently highlighted topic. You can activate the Help Window by using the Help menu, pressing F1, or entering the HELP command. Starting the Debugger 2-8 There are several main topics of discussion in the Help Window including About Help, Keys, Windows, Menus, and Commands. When the Help Window is first activated, one of these topics is highlighted on the left, and the text on the right discusses the topic. To get help on a particular topic, highlight it using Uparrow or DnArrow. As the highlight moves, the associated help text on the right changes to reflect the current topic. If the indicator at the bottom right of the window shows more than one page of information, use PgUp and PgDn to scroll the help text. Press Esc to remove the Help Window and continue debugging. For more information on the Help Window, see Chapter 3, The Debugger Display. ----------------------------------------------------------------- Leaving the Debugger When you have finished your debugging session, select the Exit option from the File menu, press Alt-X, or enter the QUIT command. The Debugger automatically closes all files and returns you to the DOS prompt. Starting the Debugger 2-9 ================================================================== Chapter 3: The Debugger Display ------------------------------------------------------------------ In This Chapter 3-1 The Debugger Windows 3-1 Dialog Boxes 3-11 The Debugger Menus 3-11 The Function Keys 3-28 Chapter 3 -- The Debugger Display Before you can make full use of The Clipper Debugger, you must be familiar with the various windows, menus and function keys on which the debugging environment is based. This chapter provides an explanation and illustration of each of these components. ----------------------------------------------------------------- In This Chapter This chapter describes each of the windows, boxes, menus and keys that constitute the main display. The topics covered are: * The Debugger windows * Dialog boxes * The Debugger menus * Function keys ----------------------------------------------------------------- The Debugger Windows The Debugger display is based on a series of windows, each with a unique purpose. The following table gives the name and a brief description of each of these windows: Table 3-1: The Debugger Windows -------------------------------------------------------------- Window Name Purpose -------------------------------------------------------------- Callstack Window Display the Callstack Code Window Display program code Command Window Display commands and their results Help Window Display help information Monitor Window Display monitored variables Set Color Window Display and modify color settings View Sets Window Display and modify SET values View Work Area Window Display work area and (.dbf) information Watch Window Display Watchpoints and Tracepoints -------------------------------------------------------------- Windows are used to display program code, enter commands and offer help. The following sections explain the various windows and their functions. The Debugger Display 3-1 Window Operations This section describes the general behavior of windows that appear on the main Debugger screen (i.e., Code, Command, Monitor, Watch, and Callstack), including the processes of sizing and moving between windows. -------------------------------------------------------------- Navigating Between Windows Of all the windows on the main screen, one is said to be the active window and the rest are inactive. When you select a window, you make it the active window. The active window is indicated by a highlighted border; inactive windows have a single-line border. To move back and forth between windows, use Tab and Shift-Tab. Tab selects the next window on the screen. Shift-Tab selects the previous window. These keystrokes are equivalent to the Next and Prev selections in the Windows menu. The order of the windows is as follows: Code, Monitor, Watch, Callstack, Command. When a window is active, any valid keystrokes affect only that window. For example, when the Monitor Window is active, pressing Dnarrow moves the highlight bar to the next variable in the list of monitored variables, but does not affect the cursor or highlight bar in any other window. The exception to this rule is that a command can be typed and executed from any active window. For example if you type "LIST BP" while the Code Window is active, the command will appear in the Command Window next to the > prompt as you are typing. As soon as you press Return, the command will be executed and the result displayed in the Command Window. Furthermore, Return always executes the command pending in the Command Window (if any), taking precedence over the normal operation of the Return key for the active window. -------------------------------------------------------------- Iconizing Any window on the screen can be effectively put out of sight without actually closing the window. For example, if the Callstack Window is open and you are not interested in its contents for the moment, you could shrink it down so small that only the window name would be visible. This process, called iconizing, is accomplished by selecting the Window:Iconize menu option. The active window is replaced by an icon (its name), and you can no longer see the contents of the window. When a window is iconized, certain window operations, such as sizing, are not available. The Debugger Display 3-2 -------------------------------------------------------------- Zooming To zoom the active window to full screen, simply press F2. When a window is zoomed, other window operations such as moving and sizing are not allowed. F2 acts as a toggle between the full screen and window display modes so that when the active window is zoomed to full screen, pressing F2 resumes the original window display. F2 is equivalent to the Windows:Zoom menu option. -------------------------------------------------------------- Sizing The height and width of all Debugger windows is determined by the display mode and which windows are open at any given time. The size of a window, however, can be changed to suit your particular needs. The following table lists some shortcut keys for changing the height of a window: Table 3-2: Sizing Windows -------------------------------------------------------------- Key Action -------------------------------------------------------------- Alt-G Grow active window by one line Alt-S Shrink active window by one line Alt-D Shrink Command Window by one line Alt-U Grow Command Window by one line -------------------------------------------------------------- The Windows:Size menu option allows you to change both the height and the width of the active window. When you select this option, the border of the active window changes to a different pattern and the cursor keys are used to change the size of the window. Return completes the sizing. -------------------------------------------------------------- Note Windows cannot be sized if you are running the Debugger in split screen mode. -------------------------------------------------------------- -------------------------------------------------------------- Moving The location of all Debugger windows is determined by the display mode and which windows are open at any given time and can be changed to suit your particular needs. The Debugger Display 3-3 The Windows:Move menu option allows you to move the active window around on the screen. When you select this option, the border of the active window changes to a different pattern and the cursor keys are used to move the window. Return completes the move. -------------------------------------------------------------- Note Windows cannot be moved if you are running the Debugger in split screen mode. -------------------------------------------------------------- -------------------------------------------------------------- Tiling Windows The Windows:Tile option is a quick way to clean up the screen. This option restores each window on the screen to its default location and size. Any windows that have been zoomed or iconized are also restored to the original window display mode. The Code Window The Code Window is located underneath the Menu Bar, and is used to display program code and header (.ch) files. Pre-processed output can be displayed beneath program code on a line-by-line basis using the Options:Preprocessed Code menu option. The name of the file currently being displayed is shown at the top of the window. The Code Window is initially set to display a certain number of lines, but can be sized to display fewer or more lines (see Sizing Windows in this chapter for more information). The minimum number of display lines is zero, and the initial and maximum number of lines depend on the display mode. Inside the Code Window is a highlight bar called the Execution Bar which is positioned on the line of code about to be executed. The Execution Bar moves as execution continues. When the Code Window is active, the cursor appears in the window to indicate your current position in the file being viewed. Initially the cursor and Execution Bar appear on the same line, but the cursor can be moved up and down using the cursor keys. The cursor is used to show the result of Locate menu selections, to mark (or delete) a line of code as a Breakpoint, and to tell the Run:To Cursor menu option where to stop. To navigate within the Code Window, use the keys shown in the table below: The Debugger Display 3-4 Table 3-3: Code Window Active Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- Uparrow/Ctrl-E Move cursor up one line Dnarrow/Ctrl-X Move cursor down one line Leftarrow/Ctrl-S Pan left one character Rightarrow/Ctrl-D Pan right one character Home/Ctrl-A Pan left one screen End/Ctrl-F Pan right one screen PgUp/Ctrl-R Scroll window contents up PgDn/Ctrl-C Scroll window contents down Ctrl-PgUp Move cursor to first line Ctrl-PgDn Move cursor to last line Return Execute pending command Tab Activate next window Shift-Tab Activate previous window F2 Toggle full screen/window display -------------------------------------------------------------- The Command Window The Command Window displayed at the bottom of the screen displays the Debugger commands that you enter. The output of Debugger commands (if any) is also displayed in this window directly underneath the command. Commands are entered by typing the command and pressing Return to execute it (see Chapter 5, Command Reference for a list of commands). The Command Window is like most other Debugger windows in that it can be sized, moved, and zoomed to full screen when it is the active window (see Sizing Windows in this chapter for more information). The window is made active by selecting it with Tab or Shift-Tab. When the Command Window is active, its border is highlighted. Note, however, that the Command Window does not have to be active in order to enter commands. Commands are entered in the same manner no matter what window happens to be active at the time, and the command appears in the Command Window next to the greater than (>) prompt as you are typing. The following table gives a summary of keys that are available when the Command Window is active: The Debugger Display 3-5 Table 3-4: Command Window Active Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- Uparrow/Ctrl-E Move cursor to previous line in history Dnarrow/Ctrl-X Move cursor to next line in history Leftarrow/Ctrl-S Move cursor one character to the left Rightarrow/Ctrl-D Move cursor one character to the right Home/Ctrl-A Move cursor to the beginning of line End/Ctrl-F Move cursor to the end of line Ins/Ctrl-V Toggle the insert mode on or off Del/Ctrl-G Delete character under cursor Backspace/Ctrl-H Delete character to the left of cursor Esc Clear command line Return Execute pending command Tab Activate next window Shift-Tab Activate previous window F2 Toggle full screen/window display -------------------------------------------------------------- -------------------------------------------------------------- History The commands that you enter are saved in a history buffer where they can be accessed when the Command Window is active. Use Uparrow to move to the previous command and Dnarrow to move to the next one. F2 zooms the Command Window to full screen, allowing you to see more commands at one time. When a command is displayed next to the > prompt in the Command Window, it can be edited and executed just as if you had typed it. -------------------------------------------------------------- Overwrite and Insert Modes When the Command Window is active, there are two data entry modes: Overwrite and Insert. Overwrite mode (the default) is indicated by the underscore cursor and causes any characters typed to overwrite existing characters. To toggle between Overwrite and Insert mode, press Ins. The cursor changes to a block and new characters are inserted to the right of the cursor position. The Watch Window The Watch Window is displayed at the top of the screen, underneath the Menu Bar and above the Code Window. It appears whenever a Watchpoint or Tracepoint is created. In this window, the number and name of each Watchpoint and Tracepoint is displayed along with its data type, value, and storage class (e.g., LOCAL). Watchpoints and Tracepoints are indicated by the words "wp" or "tp." The Debugger Display 3-6 When the Watch Window is active, you can inspect the value of almost any variable or expression that appears in the window by highlighting it and pressing Return. This action opens a dialog box in which you can inspect (and edit) the value. Pressing Return takes you back to the Watch Window. Code blocks and objects, however, cannot be inspected and inspecting an array is slightly more complicated. To inspect an array, highlight the array name and select it with Return. When the dialog box appears, you can either enter array values or press Return again to inspect each element of the array in another dialog box. In this dialog box, Uparrow and Dnarrow move the highlight bar and Return enters the edit mode for the current value. After making changes, press Return again to leave the edit mode. When you are finished making changes, press Esc twice to return to the Watch Window and the changes you have made to the array will be saved. The following table summarizes the keys that are available when the Watch Window is active: Table 3-5: Watch and Monitor Window Active Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- Uparrow/Ctrl-E Move highlight bar up one line Dnarrow/Ctrl-X Move highlight bar down one line PgUp/Ctrl-R Scroll window contents up PgDn/Ctrl-C Scroll window contents down Ctrl-PgUp Move highlight bar to first line Ctrl-PgDn Move highlight bar to last line Return Execute pending command or change selected item Tab Activate next window Shift-Tab Activate previous window F2 Toggle full screen/window display -------------------------------------------------------------- See also: Point:Watchpoint, Point:Tracepoint, DELETE, LIST, TP, WP The Monitor Window The Monitor Window is similar to the Watch Window except that it is used to monitor variables of a particular storage class rather than variables that are set as Watchpoints and Tracepoints. The Monitor Window appears on the screen only when one or more of the storage classes in the Monitor menu is turned ON (indicated by a check mark next to the storage class). The Debugger Display 3-7 If the Callstack window is active, the Monitor window displays variables at the point of the activation level represented by the highlight bar in the Callstack. In this window, each variable name that is being monitored is displayed along with its storage class, data type, and value. By default, the variables are grouped by storage class. If Monitor:Sort is ON (indicated by a check mark beside the menu option), variables listed in the Monitor window are displayed in alphabetical order by variable name. When the Monitor Window is active, you can change the value of almost any variable in the window by highlighting it and pressing Return. Editing variables in this window is identical to the method described above for the Watch Window and with the same exceptions--code blocks and objects cannot be edited and editing array values is slightly more complicated than other data types. The keys for this window are the same as for the Watch Window and are summarized in Table 3-5. See also: Monitor:Local, Monitor:Private, Monitor:Public, Monitor:Static, Monitor:Sort The Callstack Window The Callstack Window appears on the right-hand side of the screen and contains the names of all pending activations. This list is called the Callstack. The current activation is always at the top of the Callstack. To open the Callstack Window, select the View:Callstack menu option or use the CALLSTACK command. To select the window, press Tab or Shift-Tab until it is highlighted. The following is a list of keys available when the Callstack Window is active: Table 3-6: Callstack Window Active Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- Uparrow/Ctrl-E Move highlight bar up one line Dnarrow/Ctrl-X Move highlight bar down one line PgUp/Ctrl-R Scroll window contents up PgDn/Ctrl-C Scroll window contents down Ctrl-PgUp Move highlight bar to first line Ctrl-PgDn Move highlight bar to last line Return Execute pending command Tab Activate next window Shift-Tab Activate previous window F2 Toggle full screen/window display -------------------------------------------------------------- See also: View:Callstack, CALLSTACK The Debugger Display 3-8 The Help Window The Debugger offers on-line help in the form of a Help Window, which is divided into two panes: the left pane contains a list of topics for which help is available, and the right pane contains the help text for the currently highlighted topic. You can activate the Help Window by using the Help menu, pressing F1, or entering the HELP command. There are several main topics of discussion in the Help Window and when the window is first activated, one of these topics is highlighted on the left with its associated help text displayed on the right. The following table summarizes the keys used to navigate within the Help Window: Table 3-7: Help Window Active Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- Uparrow/Ctrl-E Move highlight bar up one line Dnarrow/Ctrl-X Move highlight bar down one line PgUp/Ctrl-R Scroll window contents up PgDn/Ctrl-C Scroll window contents down Esc Leave Help Window -------------------------------------------------------------- See also: F1, Help:Commands, Help:Keys, Help:Menus, Help:Windows, HELP The View Sets Window To activate the View Sets Window, select the View:Sets menu option. When this window is active, you can view and change the status of the Clipper system settings. Uparrow and Dnarrow move the highlight up and down in the list of settings. To change a setting, highlight it and press Return. After changing the value, press Return again and move on to the next setting. To close the View Sets Window and continue debugging, press Esc. The new settings are saved and take effect immediately in your program. See also: View:Sets The View Workareas Window To activate the View Workareas Window, select the View:Workareas menu option or press F6. This window is divided into three panes called Area, Status, and Structure. The Tab and Shift-Tab keys move back and forth between window panes. The Debugger Display 3-9 The Area pane displays the alias name for each open database file, with the active file displayed in angle brackets. Uparrow and Dnarrow are used to move the highlight up and down in the Area window pane. Information regarding the currently highlighted file is shown in the other two window panes. The Status pane shows the status of most work area flag settings with information regarding the selected database file underneath. When this pane is active, the alias name is highlighted and Uparrow and Dnarrow are used to move the highlight. The database information is in the form of an outline that can be expanded and collapsed by pressing Return. For instance, if you highlight Current Record and press Return the value of each field in the current record is displayed underneath. Similarly, expanding the Workarea Information heading displays additional work area settings that are not shown at the top of the window pane. Finally, the Structure pane lists the structure of the selected database file. When this window pane is active, Uparrow and Dnarrow move the highlight from field to field allowing you to scroll through the file structure. To close the View Workareas Window and continue debugging, press Esc. See also: F6, View:Workareas The Set Colors Window To activate the Set Colors Window, select the Options:Colors menu option. When this window is active, you can view and change the status of the Debugger color settings. Uparrow and Dnarrow move the highlight up and down in the list of color settings. To change a setting, highlight it and press Return. Each setting is a foreground/background color string enclosed in double quotes (see SETCOLOR() in the Reference book for a list of colors). After changing the value, press Return again and move on to the next setting. To close the Set Colors Window and continue debugging, press Esc. The new colors will take effect immediately but will be lost as soon as you exit the Debugger. To save the new colors in a script file for future use, select the Options:Save Settings menu option. See also: Options:Colors, Options:Restore Settings, Options:Save Settings The Debugger Display 3-10 ----------------------------------------------------------------- Dialog Boxes Several menu options and window selections require that you enter further information before continuing. Menu options that require more input are always indicated by an ellipsis (...) to the right of the option name. Some examples of window selections that require additional information are items in the Monitor and Watch windows. Anytime more information is required to proceed, a dialog box is displayed to prompt you. The following table summarizes the keys that are available when a dialog box is open: Table 3-8: Dialog Box Active Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- Leftarrow/Ctrl-S Move cursor one character to the left Rightarrow/Ctrl-D Move cursor one character to the right Home/Ctrl-A Move cursor to the beginning of line End/Ctrl-F Move cursor to the end of line Ins/Ctrl-V Toggle the insert mode on or off Del/Ctrl-G Delete character under cursor Backspace/Ctrl-H Delete character to the left of cursor Esc Close dialog box without executing Return Execute and close dialog box -------------------------------------------------------------- Dialog boxes are also used if you enter an incomplete command. For example, FIND with no search string opens a dialog box to ask for the search string. ----------------------------------------------------------------- The Debugger Menus The following section contains a description of the menus available in The Clipper Debugger. Many of the options on these menus can also be accessed by using function keys or commands; in such cases, the appropriate command or function key is mentioned in the description of the menu option. The Menu Bar Menu selections appear on the Menu Bar at the top of the screen. Each of these menus contains a group of similar, commonly used options. For example, the Find, Next, Previous and Goto Line options are found on the Locate menu. Although each of these options has an associated command that performs the same function (in the above example: FIND, NEXT, PREV and GOTO), the menu system provides a quick way for the beginner to learn how to use the Debugger. The Debugger Display 3-11 Menu Operations This section describes the process of accessing menus and selecting particular menu options. Also included are tables of menu system active keys. -------------------------------------------------------------- Accessing a Menu To access a menu, hold down the Alt key and press the first letter of the menu name. For example, to access the View menu, press Alt-V. To cancel a menu, press Esc. Whenever a menu is displayed on the screen, the other menus can be accessed by using Leftarrow and Rightarrow (as shown in the table below). If you are positioned at the first item on the Menu Bar--the File menu--pressing Leftarrow causes the cursor to "wrap-around" and display the last item--the Help menu. The reverse is true if you press Rightarrow from the last item. Table 3-9: Menu Access Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- Alt-<Menu first letter> Activate designated menu Leftarrow/Ctrl-S Activate menu to the left; wrap if on first menu Rightarrow/Ctrl-D Activate menu to the right; wrap if on last menu Esc Close menu -------------------------------------------------------------- -------------------------------------------------------------- Selecting a Menu Option Once inside a menu, Uparrow and Dnarrow move the highlight bar up and down the list of options. To select an option, highlight it and press Return. When selecting a menu option, pressing Uparrow on the first option causes the highlight bar to wrap-around to the last option; the reverse is true if you press Dnarrow on the last option. The following table lists the active keys within a menu: The Debugger Display 3-12 Table 3-10: Menu Option Keys -------------------------------------------------------------- Key Action -------------------------------------------------------------- <Option letter> Select designated option Return Select highlighted option Uparrow/Ctrl-E Move highlight bar up one option; wrap if on first option Dnarrow/Ctrl-X Move highlight bar down one option; wrap if on last option -------------------------------------------------------------- -------------------------------------------------------------- Accelerator Keys Once a menu is open, all options within the menu have an associated accelerator key that you can press to select the option. The accelerator key is a single letter which is usually the first letter of the option name. Within a menu, the accelerator key for each option is highlighted within the option name. Typing the indicated key is equivalent to moving the highlight to that option and pressing Return. For example, pressing Alt-P followed by the letter B selects Point:Breakpoint. -------------------------------------------------------------- Menu Commands Any menu option can be turned into a command that can be executed from the Command Window or a script file. These commands, called menu commands, are formed using the menu name followed by the first word of the option name. For example, the Monitor:Public menu option can be executed using the following command: > MONITOR PUBLIC <Return> Arguments can be specified following a menu command if the menu option requires further input. For example, selecting Run:Speed prompts you for the step delay using a dialog box. To specify the delay speed of .5 seconds using a menu command: > RUN SPEED 5 <Return> Menu commands can be abbreviated down to one letter per word, but in some cases a second letter is required in the option keyword to distinguish it from another option that begins with the same letter. The Debugger Display 3-13 The File Menu The File menu contains options to view other files, and allows you to access DOS without leaving the current program. It is opened by pressing Alt-F. -------------------------------------------------------------- Open... The Open option allows you to examine another program or header file. When you select this option, a dialog box is displayed and you are prompted to enter the name of the file you want to view. If no extension is specified, (.prg) is assumed. When you have entered the name of the file, the current program is cleared from the Code Window, and the new file is displayed in its place. To continue with the original program, select the File:Resume menu option or use the RESUME command. See also: File:Resume, VIEW -------------------------------------------------------------- Resume The Resume option clears the file currently being viewed from the screen and redisplays the program originally being debugged. See also: File:Open, RESUME -------------------------------------------------------------- DOS Access This option allows you to access DOS without leaving the Debugger. The screen is cleared and a temporary copy of COMMAND.COM is invoked, allowing you to type DOS commands in the usual way. When you have finished, type "Exit" at the DOS prompt to return to the program you are debugging. See also: DOS -------------------------------------------------------------- Exit Selecting the Exit option tells the Debugger that you have finished the current debugging session. All Debugger settings are cleared, database and index files are closed, and the system returns to DOS. Pressing Alt-X is equivalent to selecting File:Exit. See also: QUIT The Debugger Display 3-14 The Locate Menu The Locate menu contains options that allow you to search for a character string in a program and move the cursor in the Code Window to a particular line number. This menu is selected by pressing Alt-L. -------------------------------------------------------------- Note If the Command Window is active when a Locate menu option is selected, you will not see the cursor move to its new location in the Code Window. You must select the Code Window in order to see the new cursor position in the file. -------------------------------------------------------------- -------------------------------------------------------------- Find... The Find option searches the file displayed in the Code Window for a particular character string. When selected, a dialog box is displayed and you are asked to enter a search string. The search always begins at the first line of code and moves down through the file, regardless of the current cursor position in the Code Window. If a match is found, the Debugger moves the cursor to the line containing the first occurrence of the string; otherwise, the cursor remains at its current location. See also: Locate:Next, Locate:Previous, Locate:Case Sensitive, FIND -------------------------------------------------------------- Next This option searches for the next occurrence of the last character string found. If no search string has been specified, a dialog box is displayed to prompt you for one. The search begins at the current cursor position in the Code Window and moves down through the file. If a match is found, the Debugger moves the cursor to the line containing the next occurrence of the string; otherwise, the cursor remains at its current location. See also: Locate:Find, Locate:Previous, NEXT The Debugger Display 3-15 -------------------------------------------------------------- Previous The Previous option searches for the previous occurrence of a character string. If no search string has been specified, a dialog box is displayed to prompt you for one. The search begins at the current cursor position in the Code Window and moves up through the file. If a match is found, the Debugger moves the cursor to the line containing the previous occurrence of the string; otherwise, the cursor remains at its current location. See also: Locate:Find, Locate:Next, PREV -------------------------------------------------------------- Goto Line... Goto Line moves the cursor to a particular line number. When you select this option, a dialog box is displayed and you are prompted to enter a line number. If your entry is valid, the Debugger moves the cursor to the indicated line; otherwise, the cursor remains at its current location. Locate:Goto Line is functional regardless of whether or not Line Numbers are currently displayed. See also: Options:Line Numbers, GOTO -------------------------------------------------------------- Case Sensitive The setting of this option determines whether or not searches performed with the Find, Next, and Previous options in the Locate menu are case sensitive. If Case Sensitive is ON (indicated by a check mark), two strings match only if they have an identical pattern of upper and lower case letters. If it is OFF, two strings containing identical characters match, regardless of the casing of letters within the strings. The Case Sensitive setting also applies to searches performed with the FIND, NEXT, and PREV commands. See also: Locate:Find, Locate:Next, Locate:Previous, FIND, NEXT, PREV The View Menu The View menu, selected by pressing Alt-V, contains a set of options that allow you to view certain information that is not normally displayed as part of the Debugger screen. The Debugger Display 3-16 -------------------------------------------------------------- Sets When you select this option, the View Sets Window is activated. When this window is active, you can view and change the status of the Clipper system settings. Use Uparrow and Dnarrow to move the highlight up and down in the list of settings. To change a setting, highlight it and press Return. After changing the value, press Return again and move on to the next setting. To close the View Sets Window and continue debugging, press Esc. The new settings are saved and take effect immediately in your program. -------------------------------------------------------------- Workareas Selecting this option activates the View Workareas Window. Pressing F6 has the same effect. This window allows you to view information regarding all database files that are currently in use. To close the window and continue debugging, press Esc. See also: F6 -------------------------------------------------------------- App Screen When you select this option, the Debugger screen is erased, and your application screen is displayed in its place. This allows you to see the output of the program being debugged exactly as the person using your application will see it. Pressing F4 achieves the same effect. To return to the Debugger, press any key. See also: F4, OUTPUT -------------------------------------------------------------- Callstack The Callstack option acts as a toggle for opening and closing the Callstack Window. When the option is ON (indicated by a check mark next to the menu option), the Callstack Window is displayed on the main Debugger screen. If the option OFF, the Callstack Window is closed (not displayed). See also: CALLSTACK The Debugger Display 3-17 The Run Menu The options found on the Run menu allow you to restart the current application, load a new (.EXE) file, or step through code one line at a time at a specified speed. This menu is selected by pressing Alt-R. -------------------------------------------------------------- Restart The Restart option reloads the current application, retaining all Debugger settings. The Debugger does not allow portions of an application which have already been executed to be run again. Instead, the entire application must be restarted. See also: RESTART -------------------------------------------------------------- Animate When you select the Animate option, the Debugger steps through the current application one line at a time, moving the Execution Bar to each line as it is executed. This form of execution is called "Animate Mode." If Options:Exchange Screens is ON, the output of each line is shown after the line has been executed. Control then returns to the Debugger, the Execution Bar moves to the next line, that line is executed, and so on. This continues until a Breakpoint or Tracepoint is reached. For more information on modes of execution, see Chapter 4, Debugging a Program. See also: Options:Exchange Screens, Options:Swap on Input, Run:Speed, ANIMATE -------------------------------------------------------------- Step The Step option executes your application in Single Step Mode. This mode executes the line of program code highlighted by the Execution Bar, moves the Execution Bar to the next line of code to be executed, and stops. As functions are called by the current program, their code is displayed in the Code Window. F8 performs the same function as the Run:Step menu option. See also: F8, Options:Codeblock Trace, STEP The Debugger Display 3-18 -------------------------------------------------------------- Trace The Trace option is similar to Step in that it executes one line of program code at a time. However, Trace does not display the code for functions called by the current program. F10 performs the same function as the Run:Trace menu option. See also: F10 -------------------------------------------------------------- Go When you select the Go option, the Debugger displays your application screen and begins execution in Run Mode; execution continues until a Breakpoint or Tracepoint is encountered, or until the Debugger is invoked with ALTD() or Alt-D. F5 performs the same function as the Run:Go menu option. See also: F5, GO -------------------------------------------------------------- To Cursor The To Cursor option allows you to execute only those lines of code up to the line indicated by the current cursor position in the Code Window. The application is executed in Run Mode until that line is reached. If the line is never executed, the Debugger continues to the end of the application. F7 performs the same function as the Run:To Cursor menu option. See also: F7 -------------------------------------------------------------- Speed... The Speed option allows you to set the step delay for Animate Mode in tenths of seconds (for an explanation of this mode, see Chapter 4, Debugging a Program). When you select this option, a dialog box is displayed and you are asked to enter a number representing the step speed. The number that you enter is interpreted as tenths of seconds, so that entering a small number such as zero results in a faster display time than entering a larger number. The current setting is displayed in the dialog box when you select Run:Speed. See also: Run:Animate, SPEED The Debugger Display 3-19 The Point Menu The Point menu contains options to set and delete Breakpoints, Watchpoints, and Tracepoints, and is selected by pressing Alt-P. Breakpoints are lines of code at which the application pauses and returns control to the Debugger. Watchpoints are variables and expressions whose values are displayed in the Watch Window and updated as each line of the application executes. Tracepoints are very similar; however, whenever the value of a Tracepoint changes, execution pauses and control passes to the Debugger. Tracepoints are also displayed in the Watch Window. For more information on Watchpoints and Tracepoints, see Chapter 4, Debugging a Program. -------------------------------------------------------------- Watchpoint... The Watchpoint option designates a field variable, memory variable or expression as a Watchpoint. When you select this option, a dialog box is displayed and you are asked to enter a variable or expression. Your entry is then displayed in the Watch Window at the top of the screen, together with its type and value and the word "wp." As each line of the current program is executed, the value of the Watchpoint is updated. See also: Point:Delete, WP -------------------------------------------------------------- Tracepoint... This option allows you to specify a field variable, memory variable or expression as a Tracepoint. As is the case for Watchpoints, a dialog box is displayed and you are prompted for an expression or the name of a variable. This is then displayed in the Watch Window along with its type and value, and noted as "tp." Unlike Watchpoints, every time the value of the Tracepoint changes, program execution pauses and control passes to the Debugger. See also: Point:Delete, TP -------------------------------------------------------------- Breakpoint The Breakpoint option designates the line of code indicated by the cursor in the Code Window as a Breakpoint. When you select this option, the line of code is indicated in a new color to distinguish it is as a Breakpoint. This menu option The Debugger Display 3-20 acts as a toggle so that if the current line of code is already a Breakpoint, the Breakpoint is deleted and the color of the line returns to normal. Pressing F9 is equivalent to selecting the Point:Breakpoint menu option. -------------------------------------------------------------- Delete... When you select the Delete option, a dialog box is displayed and you are asked to enter the number that appears to the left of the Watchpoint or Tracepoint you want to delete. Your selection is then removed from the Watch Window. See also: Point:Watchpoint, Point:Tracepoint, DELETE The Monitor Menu The Monitor menu contains a set of options that control the display of PUBLIC, PRIVATE, STATIC and LOCAL variables in the Monitor Window. This menu is activated by pressing Alt-M. Variables displayed using the menu options described in this section are known as "monitored" variables. Monitored variables relate to the routine currently displayed in the Code Window. When a pending activation is viewed, the values displayed for the monitored variables are the values that they held when the routine was active. Inspecting the variables with the ?|?? command or specifying them as Watchpoints or Tracepoints yields the current value, which may be different from the value displayed in the Monitor Window. Any existing variables which are not visible to the activation in the Code Window do not appear in the Monitor Window. Each of the options on the Monitor menu can either be ON (indicated by a check mark) or OFF. When ON, variables of the appropriate storage class are displayed in the Monitor Window. To toggle between the two states, highlight the appropriate option and press Return. -------------------------------------------------------------- Public When ON, the Public option monitors PUBLIC variables in the Monitor Window. The Debugger Display 3-21 -------------------------------------------------------------- Private When ON, this option, specifies PRIVATE variables as monitored variables, and displays them in the Monitor Window. -------------------------------------------------------------- Static When the Static option is ON, STATIC variables are monitored in the Monitor Window. -------------------------------------------------------------- Local When this option is ON, LOCAL variables are displayed in the Monitor Window. -------------------------------------------------------------- Sort The Sort option controls the order in which items are displayed in the Monitor Window. When Sort is ON (indicated by a check mark), items in the Monitor Window are displayed in alphabetical order according to variable name. When the option is OFF, the monitored variables are grouped by storage class. The Options Menu The Options menu allows you to control the Debugger display options and to create and run Debugger script files. This menu is selected by pressing Alt-O. -------------------------------------------------------------- Preprocessed Code The Preprocessed Code option is a toggle. If it is ON (indicated by a check mark), the pre-processed code for the current program is displayed in the Code Window underneath each line of source code. Since the pre-processed code is taken from the corresponding (.ppo) file, the program in the Code Window must have been compiled with the /P option. Otherwise, no pre-processed code is displayed. If Preprocessed Code is OFF, the default, the source code is displayed in the Code Window without pre-processed output. The Debugger Display 3-22 -------------------------------------------------------------- Line Numbers The Line Numbers option is a toggle used to control the display of line numbers in the Code Window. If the option is ON (indicated by a check mark), a line number is displayed to the left of each line of source code. If not, no line numbers are visible. Having Line Numbers displayed in the Code Window is especially helpful when using the Locate:Goto Line menu option to move the cursor to a particular line of code. See also: NUM -------------------------------------------------------------- Exchange Screens The Exchange Screens option is a toggle that controls the display of program output while in Animate Mode. If this option is ON (indicated by a check mark), Animate Mode displays application output for each line of code executed. If Exchange Screens is OFF, the Debugger displays the application screen only when input is required. For more information on modes of execution, see Chapter 4, Debugging a Program. See also: Run:Animate, Options:Swap on Input -------------------------------------------------------------- Swap on Input If Options:Exchange Screens is ON, Swap on Input has no effect. If, however, Options:Exchange Screens is OFF, Swap on Input acts as a toggle to control whether or not the application screen is displayed when input is required. By default, Swap on Input is ON (indicated by a check mark) which causes Run:Animate to swap to the application screen when input is required. If Swap on Input is OFF, the application screen is not displayed during Animate Mode. See also: Options:Exchange Screens, Run:Animate -------------------------------------------------------------- Codeblock Trace The Codeblock Trace option is a toggle that controls whether or not the Debugger traces code blocks in Step Mode. If the option is ON (indicated by a check mark), Step Mode traces a code block back to its definition each time the code block is The Debugger Display 3-23 evaluated. It does this by moving the Execution Bar to the line where the code block was defined, allowing you to see the code block definition. Tracing code blocks involves an extra step each time a code block is evaluated because you also have to step over the definition line. If you do not want to trace code block definitions, deselect Codeblock Trace. See also: Run:Step -------------------------------------------------------------- Menu Bar The Menu Bar option is a toggle that controls the display of the menu bar. If the option is ON (indicated by a check mark), the menu bar is displayed at the top of the main Debugger screen at all times. If the option is OFF, the menu bar is not displayed unless you activate a menu. -------------------------------------------------------------- Mono Display The Mono Display option is a toggle that controls whether the screen display is color or monochrome. Note that the default status of this option depends on the kind of monitor you are using, and that the option is effective only for color monitors. If you have a color monitor and Mono Display is ON (indicated by a check mark), a full range of color settings are available for the Debugger display. If the option is OFF, the display is monochrome. See also: Options:Colors -------------------------------------------------------------- Colors... The Colors options activates the Set Colors Window where you can inspect the Debugger display colors. Press Esc to close the window and continue debugging. See The Set Colors Window section earlier in this chapter for more information on this window. -------------------------------------------------------------- Tab Width... The Tab Width option allows you to set the tab width for the Code Window. Selecting this option opens a dialog box where the new value is entered. The Debugger Display 3-24 Options:Tab Width is effective only if the file you are viewing contains tabs. Lines that are indented with spaces are not affected. The default Tab Width setting is 4. -------------------------------------------------------------- Save Settings... The Save Settings option saves the current Debugger settings in a script file using menu commands. Selecting this option opens a dialog box where you enter a filename (default extension is .CLD). The script file can be executed by selecting Options:Restore Settings or using the INPUT command. It can also be executed from the CLD command-line the next time you execute the Debugger. See also: Options:Restore Settings, INPUT -------------------------------------------------------------- Restore Settings... The Restore Settings option executes a Debugger script file. Selecting this option opens a dialog box where you enter a filename (default extension is .CLD). See also: Options:Save Settings, INPUT The Window Menu The Window menu, selected by pressing Alt-W, allows you to perform certain Window operations including sizing and moving the active window. See the Window Operations section earlier in this chapter for information on how to navigate within the Help Window. -------------------------------------------------------------- Next The Next option selects the next window on the main Debugger screen. The order of the windows is as follows: Code, Monitor, Watch, Callstack, Command. Thus, if the Callstack Window is active, Window:Next selects the Command Window. Pressing Tab is equivalent to selecting this menu option. -------------------------------------------------------------- Prev The Prev option selects the previous window on the main Debugger screen. The order of the windows is as follows: Code, Monitor, Watch, Callstack, Command. Thus, if the The Debugger Display 3-25 Callstack Window is active, Window:Prev selects the Watch Window. Pressing Shift-Tab is equivalent to selecting this menu option. -------------------------------------------------------------- Move Move allows you to move the active window around on the screen. When you select this option, the border of the active window changes to a different pattern and the cursor keys are used to move the window. Return completes the moving process. -------------------------------------------------------------- Note Windows cannot be moved if you are running the Debugger in split screen mode. -------------------------------------------------------------- -------------------------------------------------------------- Size The Size option allows you to change both the height and the width of the active window. When you select this option, the border of the active window changes to a different pattern and the cursor keys are used to change the size of the window. Return completes the sizing process. -------------------------------------------------------------- Note Windows cannot be sized if you are running the Debugger in split screen mode. -------------------------------------------------------------- -------------------------------------------------------------- Zoom The Zoom option allows you to zoom the active window to full screen. This menu option acts as a toggle between the full screen and window display modes so that when the active window is zoomed to full screen, selecting Window:Zoom resumes the original window display. When a window is zoomed, some window operations such as moving and sizing are not allowed. Pressing F2 is equivalent to selecting this menu option. The Debugger Display 3-26 -------------------------------------------------------------- Iconize The Iconize option reduces the active window to an icon (its name). A window that is iconized remains open, but you cannot see the window contents. Certain window operations such as moving, however, are possible. -------------------------------------------------------------- Tile The Tile option provides a quick way to clean up the screen by restoring each window on the screen to its default location and size. Any windows that have been zoomed or iconized are also restored to the original window display mode. The Help Menu The Help menu, selected by pressing Alt-H, allows you to activate the Help Window. The menu options select the help topic that is initially highlighted when the window is opened. Pressing F1 opens the same Help Window, but with the About Help topic highlighted. After making a selection and getting the help you want, press Esc to return to the Debugger. See the The Help Window section earlier in this chapter for information on how to navigate within the Help Window. See also: F1, HELP -------------------------------------------------------------- Keys The Keys option causes the Keys topic to be highlighted when the Help Window is opened, and a general discussion of Debugger keys is displayed. Keys subtopics include Function, Menu, Window, and Other which can be selected using Dnarrow. -------------------------------------------------------------- Windows The Windows option highlights the Windows topic when the Help Window is opened, and a general discussion of Debugger windows is displayed. The Windows topic is further subdivided into discussions on the Command, Code, Watch, Monitor, and Callstack which can be selected using Dnarrow. The Debugger Display 3-27 -------------------------------------------------------------- Menus The Menus option causes the Menus topic to be highlighted when the Help Window is opened, and a general discussion of the Debugger menus is displayed. Each Menu (except Help) is discussed further as a subtopic. To get help on a particular menu, highlight the menu name using Dnarrow. -------------------------------------------------------------- Commands The Commands option causes the Commands topic to be highlighted when the Help Window is opened. Commands is not subdivided into topics, but the discussion includes a list of commands in alphabetical order. Use PgUp and PgDn to page through the help text until the command you are seeking is displayed. ----------------------------------------------------------------- The Function Keys All of the function keys used in the Debugger are shortcuts to using a menu selection or command. For example, using F9 to set a Breakpoint is slightly easier than selecting the Breakpoint option from the Point menu and much easier than entering the appropriate BP or DELETE command. The following table shows a list of all the available functions keys and their actions: Table 3-11: Function Keys -------------------------------------------------------------- Key Action Alternative -------------------------------------------------------------- F1 Help Help Menu, HELP F2 Full screen/window toggle Window:Zoom F4 Application Screen View:App Screen, OUTPUT F5 Execute Application Run:Go, GO F6 View Workareas Window View:Workareas F7 Run to Cursor Run:To Cursor F8 Step Run:Step, STEP F9 Set/Delete Breakpoint Point:Breakpoint, BP and DELETE BP F10 Trace Run:Trace -------------------------------------------------------------- F1 Help Pressing F1 displays the Help Window. Use Uparrow and Dnarrow to select a topic in the left pane of the window; the help text for the currently highlighted topic appears in the The Debugger Display 3-28 right window pane. Press Esc to return to the Debugger. You can display the Help Window using the Help menu or entering the HELP command. F2 Zoom Full Screen/Window Display F2 acts as a toggle between the full-screen and window displays. To zoom the active window to full-screen press F2, and to restore the window display press F2 again. F2 performs the same function as the Window:Zoom menu option. F4 Application Screen Pressing F4 erases the Debugger screen and displays your application screen in its place. This allows you to see the output of the program being debugged exactly as the person using your application will see it. F4 performs the same function as the OUTPUT command and the View:App Screen menu option. F5 Execute Application This key displays your application screen and begins execution in Run Mode; that is, until a Breakpoint or Tracepoint is encountered, or until the Debugger is deliberately invoked (i.e., by pressing Alt-D or using ALTD()). F5 performs the same function as the GO command and the Run:Go menu option. For more information on modes of execution, see Chapter 4, Debugging a Program. F6 View Workareas The F6 key displays the View Workareas Window. This window contains information on the currently open database (.dbf) files. F6 performs the same function as the View:Workareas menu option. F7 Run to Cursor This key sets a temporary Breakpoint on the line indicated by the cursor in the Code Window. The application is executed in Run Mode until that line is reached, or until the value of a Tracepoint changes. If the line is never executed, the Debugger continues to the end of the application. F7 performs the same function as the Run:To Cursor menu option. For an explanation of execution modes, see Chapter 4, Debugging a Program. The Debugger Display 3-29 F8 Step F8 executes the program in Single Step Mode. This mode executes the line of program code highlighted by the Execution Bar, moves the Execution Bar to the next line of code to be executed, and stops. As functions are called by the current program, their code is displayed in the Code Window. F8 performs the same function as the STEP command and the Run:Step menu option. When single stepping through a piece of code containing a code block, the Execution Bar moves to the line of code where the block was created when the code block is evaluated. This allows you to see the contents of the block (which are unavailable during normal inspection), and occurs regardless of whether the block was declared in the current routine. Press F8 again to move past this line to the next executable line. For more information on execution modes, see Chapter 4, Debugging a Program. F9 Set/Delete Breakpoint F9 acts as a toggle between setting and deleting a Breakpoint at the current line (indicated by the cursor in the Code Window). To set the Breakpoint press F9, and to delete the Breakpoint press F9 again. Breakpoints are indicated in the Code Window using a display attribute that is different from other lines. F9 performs the same function as the BP/DELETE BP commands and the Point:Breakpoint menu option. For more information on Breakpoints, see Chapter 4, Debugging a Program. F10 Trace F10 performs a similar function to F8, namely, executing one line of program code. However, F10 does not display the code for functions called by the current program. F10 performs the same function as the Run:Trace menu option. The Debugger Display 3-30 ================================================================== Chapter 4: Debugging a Program ------------------------------------------------------------------ In This Chapter 4-1 Executing Program Code 4-1 Inspecting Data and Expressions 4-5 Inspecting Program Code 4-7 Accessing DOS 4-10 Chapter 4 -- Debugging a Program So far, we have described some of the most commonly used features of The Clipper Debugger. We have explained how to start the debugging process and given a description of all the elements of the screen display. In order to make full use of this knowledge, this chapter provides a more detailed study of the most powerful features, together with suggestions on the most appropriate places to use them. ----------------------------------------------------------------- In This Chapter This chapter takes an in-depth look at the features you will use most when debugging a program. The following topics are covered: * Executing program code * Inspecting data and expressions * Inspecting program code * Accessing DOS ----------------------------------------------------------------- Executing Program Code The most basic function of a debugger is to execute an application and display the results. This section describes the various ways to run a program and explains how to control the speed and view the output. Modes of Execution The Clipper Debugger provides several different ways to execute a program. The following table lists each of these methods, together with the mode of execution: Table 4-1: Program Execution Methods -------------------------------------------------------------- Method Execution Mode -------------------------------------------------------------- Run:Animate Animate F5 Run F7 Run to Cursor F8 Single Step F10 Trace ANIMATE Animate GO Run STEP Single Step -------------------------------------------------------------- Debugging a Program 4-1 * Single Step Mode F8 executes the program in Single Step Mode. This mode executes the line of program code highlighted by the Execution Bar, moves the Execution Bar to the next line of code to be executed, and stops. As functions are called by the current program, their code is displayed in the Code Window. F8 performs the same function as the STEP command and the Run:Step menu option. When single stepping through a piece of code containing a code block, the Execution Bar moves to the line of code where the block was created when the code block is evaluated. This allows you to see the contents of the block (which are unavailable during normal inspection), and occurs regardless of whether the block was declared in the current routine. Press F8 again to move past this line to the next executable line. This behavior can be controlled using the Options:Codeblock Trace menu option. This execution mode is best used in situations where the error you are looking for has been narrowed down to a few lines of code. It allows you to step slowly through each line, viewing the output and examining variables as you go. * Trace Mode Trace Mode is similar to Single Step Mode in that it executes one line of program code at a time. However, Trace Mode does not display the code for functions and procedures called by the current program nor does it trace code blocks back to their definition. F10 executes the line of code currently at the Execution Bar in Trace Mode. Alternatively, the Run:Trace menu option can be used. * Animate Mode In Animate Mode, the application runs one line at a time, with the Execution Bar moving to each line as it is executed. If the Options:Exchange Screens menu option is ON, the output of each line is shown after the line has been run. The next line is then executed, and so on. This continues until you press a key, or until a Breakpoint or Tracepoint is reached. Animate Mode allows you to execute large portions of an application, stopping when the value of a "suspect" variable or expression changes. It is used by the ANIMATE command and the Run:Animate menu option. Debugging a Program 4-2 * Run Mode The Run Mode is the fastest way to execute a program. Your application runs until a Breakpoint or Tracepoint is reached, without returning to the Debugger display for each line of code executed. This mode is used by the GO command, the Run:Go and Run:To Cursor menu options, and the F5 and F7 keys. Finding Program Errors As we have already mentioned, the Debugger provides several ways to execute a program. The method you use depends on how far you have progressed in your debugging effort. The following sections explain three common debugging stages and suggest an appropriate method for each stage. -------------------------------------------------------------- Starting Out The easiest way to debug a program for the first time is to use the F5 key or the GO command to run the application without pausing, showing the program output in the context of the application (Run Mode). As soon as you notice a possible error, press Alt-D to invoke the Debugger. Simple errors, such as mistakes in screen design, can be amended immediately. In these cases, it usually is not necessary to re-compile and re-link before continuing; the errors do not affect the actual execution of a program, only the display. For more complex problems, you must continue to the next stage of debugging: taking a closer look. -------------------------------------------------------------- Taking a Closer Look When the cause of a problem is not immediately obvious, the next step is to closely examine the contents of suspected fields, memory variables and expressions. Often, the ?|?? command reveals an unexpected value for one of these items. If this is the case, specify the item as a Watchpoint or Tracepoint. This allows you to pinpoint exactly where in the application the erroneous value was stored. If you suspect that several variables in a particular storage class may be at fault, use the options on the Monitor menu to display these variables in the Monitor Window. For example, to display PRIVATE variables, select the Monitor:Private option. As you continue your debugging session, the PRIVATE variables visible to the routine displayed in the Code Window are updated in the Monitor Window. Debugging a Program 4-3 After setting up the necessary Watchpoints and Tracepoints, use the ANIMATE command or the Run:Animate menu option to run the program slowly, displaying the code for each line executed (Animate Mode). The SPEED command and the Run:Speed menu option can be used to control the speed of the display. Continue this process until the problem has been confined to a few lines of code. Now it is time to move on to the final stage. -------------------------------------------------------------- Final Stage When the cause of an error has been narrowed down to a few lines of code, use the F9 key or the BP command to set a Breakpoint at the first of these lines. Then use the F5 key or the GO command to execute the application up to that point. When you have reached the suspect area of code, use the F8 key to step through the code one line at a time. If you are certain that the error is in the current program and not in any subsidiary procedures or functions, use the F10 key instead; this does not display the code for called procedures. Executing your application in Single Step Mode while watching the values of the items in the Watch Window is usually sufficient to uncover the cause of a problem. Having done that, simply alter your code, re-compile, re-link, and begin searching for the next error. Viewing Program Output There may be times when you want to look at the output of a program rather than the code. The first three ways to achieve this are the F4 key, the OUTPUT command, and the View:App Screen menu option. Each of these methods erases the Debugger screen and displays the current output exactly as the person running the application will see it. Press any key to return to the original display. Alternatively, program output can be viewed following execution of each individual line of code. This is achieved by setting the Options:Exchange Screens menu option, then using the ANIMATE command or the Run:Animate menu option. Debugging a Program 4-4 ----------------------------------------------------------------- Inspecting Data and Expressions One of the most common uses for a debugger is examining (inspecting) and altering the values of variables and expressions. The Clipper Debugger provides several ways to do this: the first of these is the ?|?? command. When you enter "?" followed by an expression, the expression is evaluated and the return value displayed in the Command Window. This is a useful feature that allows you to execute procedures and functions linked into your application. An alternative way to inspect data and expressions is to set up Watchpoints and Tracepoints. These are explained in the following sections. Using Watchpoints and Tracepoints Watchpoints and Tracepoints are two of the most valuable features of The Clipper Debugger. They allow you to examine field variables, memory variables and expressions, and to pinpoint exactly where in your application their values change. This section gives a definition of Watchpoints and Tracepoints and explains how they are set, deleted and inspected. -------------------------------------------------------------- Definition of Watchpoints and Tracepoints A Watchpoint is a field, memory variable or expression whose current value is displayed in the Watch Window. This value is updated as your application executes. A Tracepoint is similar to a Watchpoint; however, whenever its value changes, program execution pauses and control passes to the Debugger. In this respect, a Tracepoint is similar to a Breakpoint. -------------------------------------------------------------- Setting Watchpoints and Tracepoints There are several ways to set Watchpoints and Tracepoints. If you use the Watchpoint and Tracepoint options on the Point menu, a dialog box is displayed and you are prompted to enter an expression or the name of a variable. Your entry then appears in the Watch Window, together with the type and value and the word "wp" or "tp." Alternatively, you can use the WP or TP commands and specify the name of the variable on the command-line. > WP nPageNum <Return> Debugging a Program 4-5 > TP nInvNum = 1000 <Return> -------------------------------------------------------------- Deleting Watchpoints and Tracepoints To delete an individual Watchpoint or Tracepoint, use the Point:Delete menu option. When the dialog box appears, enter the number that appears on the far left-hand side of the Watch Window. Alternatively, you can use the DELETE command and specify the Watchpoint or Tracepoint number on the command-line. Using either method, the specified entry is removed from the Watch Window and the numbers of all the remaining entries are updated. To delete all Watchpoints and Tracepoints, use the DELETE command as follows: > DELETE ALL WP <Return> > DELETE ALL TP <Return> -------------------------------------------------------------- Warning Be careful not to use DELETE ALL on its own: this deletes all Watchpoints, Tracepoints, and Breakpoints. -------------------------------------------------------------- -------------------------------------------------------------- Listing Watchpoints and Tracepoints To display all Watchpoints and Tracepoints, use the LIST command as follows: > LIST WP <Return> > LIST TP <Return> -------------------------------------------------------------- Inspecting Watchpoints and Tracepoints To inspect a Watchpoint or Tracepoint and change its value, select the Watch Window, move the highlight bar to the item you wish to inspect, and press Return. The current value of the field, memory variable or expression is displayed in a dialog box. Within the dialog box, you can either enter a new value and press Return, or press Esc to leave the variable as it is. When you are finished inspecting items in the Watch Window, you can select another window with Tab or Shift-Tab. For more information on the keys used to navigate the Watch Window, see Chapter 3, The Debugger Display. Debugging a Program 4-6 -------------------------------------------------------------- Creating New Variables Sometimes, an error may be caused by something as simple as a misspelled variable name. In this case, you may want to create the variable from within the Debugger in order to continue debugging. Using the ?|?? command, a PRIVATE variable can be created and assigned a value. For example: > ? myVar := 100 <Return> This creates a variable called myVar and assigns it a value of 100. Remember that this variable is PRIVATE to the routine being executed when it was created. Only the in-line assignment (:=) operator can be used in this way: if the = operator had been used in the above example, the Debugger would have performed a comparison. ----------------------------------------------------------------- Inspecting Program Code As you debug an application, you may need to examine the code of programs other than the one currently being executed. This section describes how to view other programs and header files, and how to use the Callstack to access programs which have already been executed. Breakpoints are also discussed. Using Breakpoints Breakpoints are similar to, and just as powerful as, Watchpoints and Tracepoints. However, Breakpoints refer to actual lines of code rather than variables and expressions. Breakpoints allow you to return control to the Debugger and execute problem areas of code in Single Step Mode (for an explanation of the modes of execution, see Executing Code in this chapter). This section explains what Breakpoints are and how to set, delete and list them. -------------------------------------------------------------- Definition of a Breakpoint A Breakpoint is a line of program code that causes execution to halt as soon as it is reached. Debugging a Program 4-7 -------------------------------------------------------------- Setting Breakpoints To set a Breakpoint, use the BP command or move the cursor to the appropriate line in the Code Window and select the Point:Breakpoint menu option. Selecting this menu option is equivalent to pressing F9. The selected line is highlighted. To pause execution whenever a particular routine is called, use the following syntax: > BP SayData <Return> Breakpoints can also be set in programs other than the one currently displayed in the Code Window. This example sets a Breakpoint at line 15 in the program OpenDbfs.prg: > BP 15 IN OpenDbfs.prg <Return> -------------------------------------------------------------- Deleting Breakpoints There are several ways to delete an individual Breakpoint. The first is to move the cursor to the appropriate line in the Code Window and select Point:Breakpoint or press F9. When the Breakpoint is deleted, the line returns to its normal color. Another way to delete a Breakpoint is to use the DELETE BP command followed by the Breakpoint number on the command-line. Note that Breakpoint numbering begins with zero. If you do not know the number, use the LIST command (see Listing Breakpoints in this chapter). To delete all Breakpoints, use the DELETE command as follows: > DELETE ALL BP <Return> -------------------------------------------------------------- Warning Note that DELETE ALL without any other arguments also deletes all Watchpoints and Tracepoints. -------------------------------------------------------------- -------------------------------------------------------------- Listing Breakpoints To display all Breakpoints, use the LIST BP command. This lists and numbers Breakpoints in the order they were entered. Note that numbering begins with zero. Debugging a Program 4-8 Navigating the Callstack The Callstack is a list of pending activations, including procedures, functions, code blocks and message sends. It is displayed in the Callstack Window on the right-hand side of the screen, which is controlled using the CALLSTACK command or the View:Callstack menu option. When it is active, the Callstack Window allows you to highlight a program and view it in the Code Window. To select the window, press Tab until its border is highlighted. When the Callstack Window is active, the highlight bar appears on the first item in the window. You can use Uparrow and Dnarrow to move to the activation whose code you wish to view. As the highlight is moved within the window, the Code Window is immediately updated to display the selected code. To return to the program originally being debugged, use the RESUME command or the File:Resume menu option. For a list of the Callstack navigation keys, see Chapter 3, The Debugger Display. If the activation you have chosen is a code block (denoted by a lower case "b"), the name in the Callstack is the name of the routine in which the block was created. It is this code that appears in the Code Window. The Callstack is only concerned with executable code. If you want to view the contents of a header file you must use the procedure outlined in the following section. Viewing Files Although inspecting the Callstack provides an easy way to select and view program code, it does not display header files. If you already know the name of the program you want to look at, or you want to examine a header file, use the VIEW command or the File:Open menu option. The following example displays the code for the header file Inkey.ch in the Code Window: > VIEW C:\CLIPPER5\INCLUDE\Inkey.ch <Return> Notice that this example gives a file extension; if none is supplied, a (.prg) extension is assumed. When viewing a program file, Breakpoints can be set. When you return to the original program by using the RESUME command or the File:Resume menu option, these settings are saved. For a list of navigation keys used within the Code Window, see Chapter 3, The Debugger Display. Debugging a Program 4-9 ----------------------------------------------------------------- Accessing DOS There may be times when you wish to execute a DOS command without leaving the Debugger. For example, you may want to see a directory listing of all program (.prg) files. To do this, use the DOS command or select the File:DOS Access menu option. Both DOS access methods mentioned above invoke a temporary copy of COMMAND.COM. Make sure that you have sufficient memory available to load this file and any others you may wish to execute. Remember that you are using a temporary copy of DOS, so any environment variables you set will be lost upon returning to the Debugger. When you have finished and wish to continue executing your application, type "Exit" at the DOS prompt. Debugging a Program 4-10 ================================================================== Chapter 5: Command Reference ------------------------------------------------------------------ ?|?? 5-2 ANIMATE 5-4 BP 5-5 CALLSTACK 5-6 DELETE 5-7 DOS 5-9 FIND 5-10 GO 5-11 GOTO 5-12 HELP 5-13 INPUT 5-14 LIST 5-15 NEXT 5-16 NUM 5-17 OUTPUT 5-18 PREV 5-19 QUIT 5-20 RESTART 5-21 RESUME 5-22 SPEED 5-23 STEP 5-24 TP 5-25 VIEW 5-26 WP 5-27 Chapter 5 -- Command Reference Once you have become familiar with the features of The Clipper Debugger, you may want to bypass the menu system and enter commands directly. To do this, simply type the command and press Return to execute. No matter which window is active, the command will appear in the Command Window as you are typing. Command results, if any, are also displayed in the Command Window. There are two sets of Debugger commands: the menu commands and the commands discussed in this chapter. Any Debugger menu option can be expressed in the form of a menu command using the menu name followed by the first word of the option name. If required, arguments are placed at the end of the menu command-line. This chapter explains the syntax and arguments of all other Debugger commands and offers examples of their use. Command Reference 5-1 ?|?? Display the value of an expression Syntax ? | ?? <exp> Arguments <exp> is the expression to be displayed. Description ? causes the value of the specified expression to be displayed in the Command Window. ?? displays the value in a pop-up window which is closed by pressing Esc. The expression used as the ?|?? command-line argument can be any valid Clipper expression, including user-defined function, arrays, and in-line assignments. When the display expression is a code block or an object, the value cannot actually be displayed. For these data types, an icon is displayed instead. If the expression is an array, an icon is displayed if the array name is displayed with either ? or ??. ??, however, will also display the array contents if you press Return in the first pop-up window. To close both pop-ups, you must press Esc twice. With ?, you can query individual array elements by subscripting the array name. The ability to display the return value of a user-defined function allows you to extend the abilities of The Clipper Debugger. For example, you might want to modify the structure of a database file while debugging an application. To do this, simply write a function to perform the modification, compile and link it with your application, and execute it using the ?|?? command. Any feature that doesn't already exist can be written as a user-defined function and executed in this way. Using the in-line assignment (:=) operator with the ?|?? command allows you to create new variables. Examples * This example displays the value of a numeric field in the Command Window: > ? InvNum <Return> 465 Command Reference 5-2 * This shows the result of an expression in the Command Window: > ? X = Y <Return> .T. * Here, the return value of a Clipper function is shown in the Command Window: > ? EOF() <Return> .F. * In this example, the EVAL() function is used to execute a code block: > ? EVAL(bSortBlock) <Return> * This example creates a new PRIVATE variable called nPageNo, assigns it the value 2, and displays the variable in a pop-up window. To close the window, press Esc: > ?? nPageNo := 2 <Return> Command Reference 5-3 ANIMATE Run application in Animate Mode Syntax ANIMATE Description The ANIMATE command runs the application in Animate Mode. This means that the debugger executes a single line, move the Execution Bar to the next line, execute it, and so on. If the Options:Exchange Screens menu option is ON, the output of each line is displayed after the line has been executed. This continues until a Breakpoint or Tracepoint is reached. To control the speed of this process, use the SPEED command or the Run:Speed menu option. Press any key to stop execution. For more information on execution modes, see Chapter 4, Debugging a Program. See also: Run:Animate, SPEED Command Reference 5-4 BP Set a Breakpoint Syntax BP [AT] <lineNum> [[IN] <idProgramFile>]] BP <idFunction> | <idProcedure> Arguments <lineNum> is the line number where you want program execution to stop. <idProgramFile> is the filename of the program in which to set the Breakpoint. If no extension is specified, (.prg) is assumed. <idFunction>|<idProcedure> is the name of the routine where you want program execution to stop. Function names are specified without parentheses. Description BP designates a line of program code or a call to a routine as a Breakpoint. This causes execution to pause as soon as the line is encountered or the routine is called. To delete a Breakpoint, use the DELETE command. For more information on the use of Breakpoints, see Chapter 4, Debugging a Program. Examples * Entering: > BP 12 <Return> highlights line 12 of the program displayed in the Code Window. Highlighted lines are those lines that have been designated as Breakpoints. * This example inserts a Breakpoint at line 15 of File2.prg: > BP AT 15 IN File2.prg <Return> * Here, a user-defined function is used as a Breakpoint. Execution pauses as soon as the function is called: > BP TestUdf <Return> See also: F9, DELETE, GO, LIST, STEP Command Reference 5-5 CALLSTACK Control the Callstack Window Syntax CALLSTACK [on | OFF] Arguments ON opens the Callstack Window on the right-hand side of the screen. OFF closes the Callstack Window. If no options are specified, CALLSTACK acts as a toggle by changing the current status of the Callstack Window (e.g., if it is ON, CALLSTACK turns if OFF). Description CALLSTACK toggles the display of the Callstack Window. This window contains the Callstack: a list of pending activations with the current activation at the top. For more information on the Callstack, see Chapter 4, Debugging a Program. Example * To open the Callstack Window, enter: > CALLSTACK ON <Return> * To close the window, type: > CALLSTACK OFF <Return> See also: View:Callstack Command Reference 5-6 DELETE Delete debugger settings Syntax DELETE ALL [BP | TP | WP] DELETE BP | TP | WP <number> Arguments ALL deletes all settings of a specified type or all settings if no type is specified. BP specifies Breakpoints. TP specifies Tracepoints. WP specifies Watchpoints. <number> is the number of the individual Watchpoint, Tracepoint, or Breakpoint to delete. Description DELETE deletes Watchpoints, Tracepoints, and Breakpoints, either individually or as a whole. For a detailed explanation of these items, see Chapter 4, Debugging a Program. If you want to perform a single deletion, you must specify the number of the item to be deleted. If not, DELETE opens a dialog box to prompt you for the item number. For Watchpoints and Tracepoints, this is the number that appears on the left-hand side of the Watch Window. For Breakpoints the LIST command must be used to determine the number. Examples * To delete a Breakpoint, you must first find out where it falls in the list of Breakpoints: > LIST BP <Return> If the Breakpoint you want to delete is number three on the list, type: > DELETE BP 3 <Return> and the Breakpoint is deleted. * This example deletes all Watchpoints: > DELETE ALL WP <Return> Command Reference 5-7 * Here, all Breakpoints, Tracepoints, and Watchpoints are deleted: > DELETE ALL <Return> See also: F9, Point:Delete, BP, LIST, TP, WP Command Reference 5-8 DOS Access DOS without leaving the current application Syntax DOS Description DOS loads a temporary copy of COMMAND.COM, allowing you to enter DOS commands without leaving the current application. To return to the debugger, type "Exit" from the DOS command-line. When using this command, you must make sure sufficient memory is available to load COMMAND.COM and any additional programs you want to execute from the DOS command-line. If the amount of memory is insufficient, an error message is displayed. See also: File:DOS Access Command Reference 5-9 FIND Locate a character string Syntax FIND <searchString> Arguments <searchString> is the character string you want to locate. Description FIND searches the file displayed in the Code Window for a specified search string. If no search string is specified on the FIND command-line, a dialog box opens on the screen to prompt you for one. The search always begins at the first line of code and moves down through the file, regardless of the current cursor position in the Code Window. If the search string is found, the Debugger moves the cursor to the line containing the first occurrence of the string in the Code Window; otherwise, the cursor remains at its current location. -------------------------------------------------------------- Note If the Command Window is active when a FIND command is executed, you will not see the cursor move to its new location in the Code Window. You must select the Code Window in order to see the new cursor position in the file. -------------------------------------------------------------- This command obeys the Locate:Case Sensitive menu setting. If Case Sensitive is ON (indicated by a check mark), FIND looks for a character string which matches the contents and case of the specified search string. If OFF, only the contents need be the same. Examples If you suspect that the error you are trying to eliminate relates to a database (.dbf) file that is not open, search for the keyword "USE": > FIND USE <Return> See also: Locate:Case Sensitive, Locate:Find, NEXT, PREV Command Reference 5-10 GO Execute the application in Run Mode Syntax GO Description GO displays your application screen and executes the application until a Breakpoint or Tracepoint is reached, or until the Debugger is deliberately invoked (i.e., by pressing Alt-D or using ALTD()). At that point, the debugger screen is redisplayed and program execution halts. This is known as Run Mode. Using GO again causes the application to be executed from the current position to the next Breakpoint or Tracepoint. For more information on modes of execution and the use of Breakpoints and Tracepoints, see Chapter 4, Debugging a Program. Examples Suppose Breakpoints have been set at lines 15 and 30 of the current program. Typing > GO <Return> executes the application as far as line 15. Entering GO again executes up to line 30, and so on. See also: F5, Run:Go Command Reference 5-11 GOTO Move the cursor to a specified line in the Code Window Syntax GOTO <lineNum> Arguments <lineNum> is the number of the line where you want to move the cursor. Description GOTO moves the cursor from its current position in the Code Window to the specified line number. If no line number is specified on the command-line, GOTO opens a dialog box to prompt you for one. GOTO moves to a specified line number regardless of whether or not line numbers are currently displayed in the Code Window. However, for the sake of readability we recommend that line numbers be displayed. For more information refer to the NUM command in this chapter. -------------------------------------------------------------- Note If the Command Window is active when a GOTO command is executed, you will not see the cursor move to its new location in the Code Window. You must select the Code Window in order to see the new cursor position in the file. -------------------------------------------------------------- Examples This example moves the cursor to line 30 of the program currently being debugged: > GOTO 30 <Return> See also: Locate:Goto Line Command Reference 5-12 HELP Activate the Help Window Syntax HELP Description The Debugger Help Window is divided into two panes: the left pane contains a list of topics for which help is available, and the right pane contains the help text for the currently highlighted topic. When the Help Window is activated with the HELP command, About Help is highlighted on the left with a very general discussion of navigation within the Help Window. Moving the highlight bar using Uparrow or DnArrow selects a new help topic. PgUp and PgDn page through the associated help text on the right. Esc closes the Help Window and returns you to the main Debugger screen. Note that the Help menu can also be used to activate the Help Window. Each option in this menu activates the Help Window with a particular topic that is highlighted when the window opens. For example Help:Commands displays the help screen for the Debugger commands. For more information on the Help Window, see Chapter 3, The Debugger Display. See also: F1, Help:Commands, Help:Keys, Help:Menus, Help:Windows Command Reference 5-13 INPUT Read commands from a script file Syntax INPUT <idScriptFile> Arguments <idScriptFile> is the name of the script file from which to read commands. If no extension is specified, (.cld) is assumed. Description INPUT causes the debugger to temporarily suspend input from the keyboard and begin reading commands from the specified script file instead. All commands in this file are read and executed. For a full explanation of script files and their uses, see Chapter 2, Starting the Debugger. If no filename is entered on the command-line, INPUT opens a dialog box to prompt you for one. Examples To execute the commands in the script file "ViewBug.cld", enter the following: > INPUT ViewBug<Return> See also: Options:Restore Settings Command Reference 5-14 LIST List Watchpoints, Tracepoints, and Breakpoints Syntax LIST BP | TP | WP Description LIST displays all Watchpoints, Tracepoints, or Breakpoints in the Command Window. For more information on the setting and deleting of these items, see Chapter 4, Debugging a Program. Examples * If there are Breakpoints at lines 10 and 15 of AddData.prg and lines 2 and 6 of ViewData.prg, LIST BP displays the following: 0) 10 ADDDATA.PRG 1) 15 ADDDATA.PRG 2) 2 VIEWDATA.PRG 3) 6 VIEWDATA.PRG * To list all Watchpoints, type: > LIST WP <Return> See also: BP, DELETE, TP, WP Command Reference 5-15 NEXT Locate the next occurrence of a character string Syntax NEXT Description NEXT locates the next occurrence of the most recently defined search string. A search string is defined using the FIND command or the Locate:Find menu option. If no search string has been defined, NEXT opens a dialog box to prompt you for one. The search begins at the current cursor position in the Code Window and moves down through the file. If a match is found, the Debugger moves the cursor to the line containing the next occurrence of the string; otherwise, the cursor remains at its current location. Like FIND, NEXT obeys the Locate:Case Sensitive menu setting. -------------------------------------------------------------- Note If the Command Window is active when a NEXT command is executed, you will not see the cursor move to its new location in the Code Window. You must select the Code Window in order to see the new cursor position in the file. -------------------------------------------------------------- See also: Locate:Case Sensitive, Locate:Next, FIND, PREV Command Reference 5-16 NUM Toggle the display of line numbers Syntax NUM [ON | off] Arguments ON displays the line number at the beginning of each line of code. OFF removes the line numbers. If no options are specified, NUM acts as a toggle by changing the line number status. Description NUM toggles the display of line numbers at the beginning of each line of code in the Code Window. When you first start the debugger, NUM is ON and line numbers are displayed. This is particularly useful when using the GOTO command to move the cursor to a certain line in the Code Window. See also: Options:Line Numbers Command Reference 5-17 OUTPUT Display program output Syntax OUTPUT Description OUTPUT temporarily clears the debugger screen and displays your application screen in its place. This allows you to see the output of the current program in the context of the application itself. To return to the original screen, press any key. See also: F4, View:App Screen Command Reference 5-18 PREV Locate the previous occurrence of a character string Syntax PREV Description PREV searches for the previous occurrence of the most recently defined search string. A search string is defined using the FIND command or the Locate:Find menu option. If no search string has been defined, PREV opens a dialog box to prompt you for one. The search begins at the current cursor position in the Code Window and moves up through the file. If a match is found, the Debugger moves the cursor to the line containing the previous occurrence of the string; otherwise, the cursor remains at its current location. Like FIND, PREV obeys the Locate:Case Sensitive menu setting. -------------------------------------------------------------- Note If the Command Window is active when a PREV command is executed, you will not see the cursor move to its new location in the Code Window. You must select the Code Window in order to see the new cursor position in the file. -------------------------------------------------------------- See also: Locate:Case Sensitive, Locate:Previous, FIND, NEXT Command Reference 5-19 QUIT Exit the debugger Syntax QUIT Description QUIT terminates the debugger, closes all files and returns to DOS. See also: File:Exit Command Reference 5-20 RESTART Reload the current application again Syntax RESTART Description RESTART reloads the current application in preparation to be re-executed, keeping intact all debugger settings. This command is the only way to execute an application which has already been run. Examples In this example, the current application is executed: > GO <Return> If errors are discovered, you may want to make changes and run the application again: > RESTART <Return> See also: Run:Restart Command Reference 5-21 RESUME Return from viewing a file Syntax RESUME | . Description RESUME clears the file being viewed with the VIEW command (or using the Callstack Window) and redisplays the file originally shown in the Code Window. Any Breakpoints which have been set are saved. The period (.) is a synonym for the RESUME command. Examples Suppose the program currently being debugged is called PrintData.prg. The following line temporarily removes PrintData.prg from the screen and displays ReportHead.prg in its place: > VIEW ReportHead.prg <Return> To return to PrintData.prg, type the following: > RESUME <Return> See also: File:Resume, VIEW Command Reference 5-22 SPEED Set step delay for Animate Mode Syntax SPEED <delay> Arguments <delay> is the increment of delay for animation in tenths of seconds. Description SPEED controls the speed of display while in Animate Mode (for an explanation of this mode, see Chapter 4, Debugging a Program). If no argument is specified, SPEED opens a dialog box which displays the current setting and allows you to enter a new setting. Remember that this setting is expressed in tenths of seconds so that smaller settings are faster than larger ones. See also: Run:Speed, ANIMATE Command Reference 5-23 STEP Execute the current program in single step mode Syntax STEP Description STEP executes the current program in single step mode. This means that it executes the line of code at the Execution Bar, moves the Execution Bar to the next line, and stops. Examples This example executes the next line of the application being debugged: > STEP <Return> The debugger stops with the Execution Bar on the next line to be executed. See also: F8, Run:Step Command Reference 5-24 TP Specify a variable or expression as a Tracepoint Syntax TP <exp> Arguments <exp> is the field variable, memory variable or expression to be traced. It can be of any data type. Description TP designates the specified variable or expression as a Tracepoint. If no expression is specified on the command-line, TP opens a dialog box to prompt you for one. The Tracepoint is then added to the list in the Watch Window. A Tracepoint can be thought of as a conditional Breakpoint. The two are very similar, except that a Tracepoint halts program execution as soon as its value changes. For more information on Tracepoints, see Chapter 4, Debugging a Program. Examples * This example halts execution as soon as the value of the variable nInvNum changes: > TP nInvNum <Return> * This pauses when end-of-file is reached: > TP EOF() <Return> * This example halts as soon as the value of i exceeds 10, and is very useful in looping operations: > TP i > 10 <Return> See also: Point:Tracepoint, DELETE, LIST Command Reference 5-25 VIEW Examine a file during the current debugging session Syntax VIEW <idFileName> Arguments <idFileName> is the name of the file you want to examine. Description VIEW allows you to look at other files without leaving the current debugging session. It can also be used to view header files specified with the #include pre-processor directive. Breakpoints can be set and are saved when you return to the original program. If no filename is specified on the command-line, VIEW opens a dialog box to prompt you for one. Examples * To view ListDbfs.prg from within the current program (EnterData.prg), type: > VIEW ListDbfs.prg <Return> * It is possible to continue viewing other programs without returning to the original program. For example: > VIEW PrintDbfs.prg <Return> loads PrintDbfs.prg in place of ListDbfs.prg. Typing RESUME returns the debugger to EnterData.prg--the original program. See also: File:Open, RESUME Command Reference 5-26 WP Specify a variable or expression as a Watchpoint Syntax WP <exp> Arguments <exp> is the field variable, memory variable or expression to be watched and can be of any data type. Description WP designates the specified variable or expression as a Watchpoint. If no expression is specified on the command-line, WP opens a dialog box to prompt you for one. The Watchpoint is then added to the list in the Watch Window where it is updated as each line of code is executed. A Watchpoint is identical to a Tracepoint, except that it does not cause a break in program execution every time its value changes. For more information on Watchpoints, see Chapter 4, Debugging a Program. Examples * This example specifies the field CustNum as a Watchpoint: > WP CustNum <Return> CustNum now appears in the Watch Window. * In this example, the current record number is displayed as each line of code is executed: > WP RECNO() <Return> See also: Point:Watchpoint, DELETE, LIST Command Reference 5-27 Glossary Active Window Cursor The window where all The cursor indicates the keystrokes (except those valid current line and/or column in the Command Window) apply. position in the active window An active window is indicated or dialog box. Note that some by a highlighted border. The windows, such as the Monitor Tab and Shift-Tab keys are used Window, do not utilize the to select the next and previous cursor. When a window that window, respectively. does not utilize the cursor is active, the cursor appears in Animate Mode the Code Window. The mode of execution in which Debugger an application runs one line at a time until a Breakpoint or A tool used to track down Tracepoint is reached, with the errors in a program. Execution Bar moving to each line as it is executed. Dialog box Breakpoint A box displayed from within the debugger whenever further input A point at which an application is required. pauses execution and returns control to the debugger. Execution Bar Callstack The highlight bar which is positioned on the line of code A list containing the names of to be executed next. all pending activations at the current point in an Help Window application. The window in which on-line Callstack Window help is displayed. The window in which the Inspecting Callstack is displayed. The process of examining work Code Window areas, variables, expressions and activations inside the The window in which source code debugger. is displayed. Menu Bar Command Window The bar at the top of the The window in which commands debugger screen, on which the are displayed and entered. available menu choices are displayed. Clipper Debugger Glossary G-1 Monitor Window Tracepoint The window in which monitored A variable or expression whose variables are displayed. value is displayed in the Watch Window, and which causes an Monitored variable application to pause whenever that value changes. A variable which is selected by the options on the Monitor Menu View Sets Window and displayed in the Monitor Window. The window in which Clipper status settings can be Run Mode inspected. The mode of execution in which View Workareas Window an application executes without pausing, until a Breakpoint or The window in which work area Tracepoint is reached. information is displayed. Script File Watch Window A file in which frequently used The window in which Watchpoints debugger commands are stored and Tracepoints are displayed. and from which those commands can be executed. Watchpoint Set Colors Window A variable or expression whose value is displayed in the Watch The window in which the Window and updated as an Debugger color settings can be application executes. inspected. Single Step Mode The mode of execution in which only the line of code highlighted by the Execution Bar is executed, and its output displayed. Trace Mode A mode of execution similar to Single Step Mode, the difference being that Trace Mode traces over function and procedure calls. Clipper Debugger Glossary G-2