How to Use the Visual C++ DEBUGGER
<xmp> Section Four How to Use the Visual C++ DEBUGGER Table of Contents Page 1. When to Use the Debugger.................................. 1 2. Putting Developer Studio in DEBUG MODE.................... 2 3. How to Start the Debugger................................. 3 4. Setting and Using Breakpoints............................. 3 Introduction............................................ 3 Breakpoints............................................. 4 Setting a LOCATION Breakpoint......................... 5 The &quot;quick-set&quot; method.............................. 5 The Breakpoint Dialog Box method.................... 6 Setting a Breakpoint at a line.................... 6 Set a Breakpoint on the &quot;current line&quot;.......... 6 Set a Breakpoint at a specific line of code..... 7 Setting a Breakpoint at a specified function...... 7 Removing a Breakpoint................................. 8 The &quot;Quick-remove&quot; Method....................... 8 The Breakpoint Dialog Box Method................ 8 Setting a DATA Breakpoint............................. 9 Setting a VALUE-CHANGE Breakpoint................... 10 Setting a Breakpoint on an Array.................. 12 Setting a Breakpoint on a STRUCTURE............... 13 Setting a Breakpoint on a POINTER................. 15 Setting a CONDITIONAL Breakpoint.................... 16 5. Debugging a Program....................................... 19 Running (Starting) the Visual C++ Debugger.............. 19 The &quot;F5 Key Method.................................... 19 The &quot;Run-to-Cursor&quot; Method............................ 20 The &quot;Step-Into&quot; Method................................ 21 Restarting and Exiting the Debugger..................... 21 Step Through the Program One Line at a Time............. 22 Run to Cursor......................................... 24 Break Debugger Execution.............................. 26 Examining the State of a Program........................ 26 Using the VARIABLES Window............................ 27 The LOCALS Tab...................................... 27 The AUTO Tab........................................ 29 The THIS Tab........................................ 30 Using the WATCH Window................................ 30 Finding a bug that causes an &quot;Illegal Operation&quot; error.. 34 When to Use the Debugger. --------------------------------------------------------------------- When your source-code compiles/builds with no ERRORS, you will want to &quot;run&quot; (execute) the compiled (machine-code) form of your program (to see how to compile/build your program, see the document entitled &quot; How to Create and Run a Simple Project&quot;). To &quot;run&quot; the executable form of your program, do the following: - Click &quot;Build&quot; in the Main Menu [Main(6)]. - Select the &quot;Execute&quot; option from the menu that appears and the program making up the current project will begin to run. If one of the following errors occur, you will need to use the Debugger to find the associated &quot;run-time&quot; error. Once the error is found using the debugger, you must fix that error and compile-build- execute the program again. - The Program Output Window appears, but the program produces no output (assuming it is supposed to). All you see in the Program Output Window is the message &quot;Press any key to continue&quot;. - The Program Output Window appears and the program produces output, but either that output is incomplete and/or incorrect. The last line in the Program Output Window is &quot;Press any key to continue&quot;. - The Program Output Window appears and the program produces some output, but either that output is incomplete and/or incorrect, AND the last line in the Program Output Window is NOT &quot;Press any key to continue&quot;. What has happened is that your program has entered an INFINITE LOOP. To get out of an infinite loop, press the CTRL key and the 'c' key at the same time and then release both at the same time. This will terminate the running program and put you back in the Editor. - The program begins to run, but then a dialog box having the same name as your project appears displaying the error message: &quot;The program has performed an illegal operation and will be shut down&quot;. This error message can appear for many and varied reasons (such as division-by-zero, de-referencing a pointer that does not store a legitimate address value, exceeding the bounds of an array etc. This dialog box gives you three options. See the section below entitled &quot;Finding a bug that causes an ILLEGAL OPERATION error&quot; to learn about each option. - If the program performs in some other strange manner as it executes. Putting Developer Studio in DEBUG MODE. ----------------------------------------------------------------------- For the debugger to work properly, Developer Studio MUST be in &quot;debug mode&quot; when you compile a project. By default, the Visual C++ compiler compiles in debug mode. Therefore, unless you have changed the default state of the compiler, you do not need to do anything to have the compiler create special files for use by the debugger. However, to be sure that the compiler is currently in &quot;debug mode&quot;, do the following: 1. Click &quot;Project&quot; in the Main Menu [MM(5)]. 2. Select the &quot;Settings&quot; option from the menu that appears and the &quot;Project Settings&quot; Dialog Box will appear. 3. Click the &quot;C/C++&quot; tab at the top of the &quot;Project Settings&quot; dialog box. Be sure that the terms &quot;Disable [Debug]&quot; appear in the &quot;Optimizations&quot; window. If not, then click the small &quot;menu icon&quot; immediately to the right of that window and select &quot;Disable [Debug]&quot;. 4. Now click the &quot;Link&quot; tab at the top of the Project Settings Dialog Box. Be sure there is a check mark in the &quot;Generate debug info&quot; checkbox. If not, then click that checkbox to set it. How to Start the Debugger. ---------------------------------------------------------------------- 1. Bring up the source-code file in the Visual C++ Editor. 2. Be sure the compiler is in &quot;debug mode&quot;. See &quot;Putting Developer Studio in DEBUG MODE &quot; above to do this. 3. Be sure you have set &quot;Breakpoints&quot; where needed (see the section &quot;Setting and Using Breakpoints&quot; below to learn how to set up and make use of Breakpoints). 4. Compile and build your program (if you have not already done so). 5. Press the &quot;F5&quot; key to start the debugger. Your program will begin to execute, but will stop execution at the first Breakpoint. To learn what you can do when execution stops at a Breakpoint, see the section below entitled &quot;Setting and Using Breakpoints&quot;. Setting and Using Breakpoints. -------------------------------------------------------------------- A. Introduction: ------------- A BREAKPOINT is a condition which will suspend the execution of your program as it is executing under the Visual C++ Debugger. When program execution is stooped, the debugger will allow you to perform certain actions that will help you find a &quot;run-time&quot; (logical) program error (bug). Two of the most important actions the debugger will allow you to perform upon the occurrence of a Breakpoint include: 1. You can &quot;step&quot; through execution of the program one (or more) line(s) at a time. This stepping through a program allows you to see what actions, outcomes, events etc. are occurring in your executing program line-by-line. This makes it easy to immediately detect when something goes wrong such as when an incorrect value is assigned to a variable, or the index of an array has exceeded acceptable bounds, or a pointer has been incorrectly set, etc. 2. You can have displayed in a debugger window the current value of: - All visible LOCAL and GLOBAL variables; - A specified subset of visible LOCAL and GLOBAL variables. - All variables referenced in the line of code currently being executed. See &quot;Debugging a Program&quot; below to see how do perform these actions. B. Breakpoints: ------------ The Visual C++ Debugger provides you with two kinds of Breakpoints. A variety of options are available for each of these two kinds of Breakpoints. 1. LOCATION Breakpoints. Here the Breakpoint is associated with a specific line of the program. When the line of code for which the Location Breakpoint is set is to be executed, program execution stops and you can then use the debugger facilities to examine the current state of the executing program to find a bug. 2. DATA Breakpoint. Here the Breakpoint is associated with a specific data item such as a variable. You can set the Data Breakpoint so that program execution will stop when the value stored in this specified variable changes (i.e. is altered) or you can set the Data Breakpoint to occur when the specified variable is assigned a certain value. When program execution stops because of this Data Breakpoint, you can then use the debugger facilities to examine the current state of the executing program to find a bug. Setting Breakpoints. WARNING - - When running your executable program under the debugger, you may have to wait for prolonged periods of time for the debugger to get to the first or next Breakpoint. This is particularly true if you have many &quot;output&quot; statements in your program (the moral is not to have a lot of output statements in the form of the program you are trying to debug). Comment out all but the most essential output statements while debugging. Be patient and just wait. If nothing seems to be happening after 5 minutes, turn off the debugger and alter one or more of your Breakpoints and/or comment out more output statements. 1. Setting a LOCATION Breakpoint. ------------------------------ The following methods for setting/removing/disabling Location Breakpoints will work if done from the Editor and will also work if done while the program is being executed under the debugger): A. The &quot;quick-set&quot; method. ----------------------- To quickly set a Breakpoint on a specific line of the source-code, do the following: a. Get the file that contains the line where the Breakpoint is to be set into the Editor Window. Place the &quot;Insert Cursor&quot; anywhere on the line of code on which you want to set a Line Number Breakpoint and then click the RIGHT mouse button. b. Select the &quot;Insert/Remove Breakpoint&quot; option from the menu that appears. A special &quot;icon&quot; will appear to the left of this line of code. To quickly remove a Breakpoint on a specific line of the source-code, do the following: a. Place the &quot;Insert Cursor&quot; anywhere on the line of code on which you want to remove a Breakpoint and then click the RIGHT mouse button. b. Select the &quot;Remove Breakpoint&quot; option from the menu that appears. If you just want to temporarily DISABLE the Line Number Breakpoint (not remove it), do the following: a. Place the &quot;Insert Cursor&quot; anywhere on the line of code which contains the Breakpoint to be disabled and then click the RIGHT mouse button. b. Select the &quot;Disable Breakpoint&quot; option from the menu that appears. When disabled, a Breakpoint will have no effect. To enable a disabled Breakpoint, do the following: a. Place the &quot;Insert Cursor&quot; anywhere on the line of code which contains the Breakpoint to be enabled and then click the RIGHT mouse button. b. Select the &quot;Enable Breakpoint&quot; option from the menu that appears. B. The Breakpoint Dialog Box method. --------------------------------- Using the Breakpoint Dialog Box to set a Line Number Breakpoint at a specific line of source-code is not as easy as method &quot;A&quot; above, but gives you more options to choose from (i.e. is more powerful). To have the Breakpoint Dialog Box displayed, do the following: 1. Click &quot;Edit&quot; in the Main Menu [MM(2)]. 2. Select the &quot;Breakpoints&quot; option from the menu that appears. The Breakpoint Dialog Box will appear. Note that there are three tabs at the top of the Breakpoint Dialog Box. Click the &quot;Location&quot; tab (if it is not already selected) to set a Location Breakpoint. The other two tabs are discussed in later sections. You can use the Breakpoint Dialog Box to set a Location Breakpoint at a specific line number in the source code, or at the first line of a specified function. a. Setting a Breakpoint at a line. ------------------------------- i. Set a Breakpoint on the &quot;current line&quot;. --------------------------------------- If you want to set a Breakpoint on the line where the &quot;current insert position&quot; has been set, do the following (it is assumed that you have set the &quot;current insert position&quot; appropriately - remember the insert position is at the blinking vertical cursor) a. Click the &quot;menu icon&quot; at the immediate right of the &quot;Break At&quot; text field in the dialog box and a menu will appear. b. Select the option that begins with the word &quot;Line&quot; and is followed by an integer value. c. Click the &quot;OK&quot; button to set the Breakpoint and exit the Breakpoint Dialog Box. ii. Set a Breakpoint at a specific line of code. -------------------------------------------- a. Type a period and then the source-code line number into the &quot;Break At&quot; text field of the dialog box. b. Click the &quot;OK&quot; button on the dialog box. A small &quot;stop sign&quot; will appear to the left of the line of code for which the Breakpoint was set. If you want to set several Line Number Breakpoints consecutively, do the following: 1. Type a period and then the line number into the &quot;Break At&quot; text field. 2. Press the ENTER key. 3. Repeat steps &quot;1&quot; and &quot;2&quot; above until you have set all the Breakpoints you desire. 4. Click the &quot;OK&quot; button on the dialog box. A small &quot;stop sign&quot; will appear to the left of each line of code for which the Breakpoints were set. b. Setting a Breakpoint at a specified function. --------------------------------------------- It is assumed that the Breakpoints Dialog Box is currently displayed. To set a Breakpoint at the first line of a specific function (external or member function), do the following: 1. Type the name of the function into the &quot;Break At&quot; text field. If the function is a MEMBER of a class, you must precede the member function name with its &quot;class&quot; and &quot;::&quot;. For example, if member function &quot;doit&quot; is declared in a class named &quot;classa&quot;, then you would have to type &quot;classa::doit&quot;. Note that you do NOT type any parentheses or parameter list after the function name. 2. Click the &quot;OK&quot; button on the dialog box. If you want to set several Function Breakpoints consecutively, do the following: 1. Type the function name in the &quot;Break At&quot; text field. 2. Press the ENTER key. 3. Repeat steps &quot;1&quot; and &quot;2&quot; immediately above until you have set all the Breakpoints you desire. 4. Click the &quot;OK&quot; button on the dialog box to set the Breakpoints and exit the Breakpoints Dialog Box. 2. Removing a Breakpoint. ---------------------- To remove any (or all) LOCATION Breakpoint(s) (Line number or Function Breakpoint), do the following: a. The &quot;quick remove&quot; method. -------------------------- To remove a Breakpoint &quot;set&quot; using the &quot;quick-set&quot; method of creating a Breakpoint (as described above). 1. Get the source-code that contains the Breakpoint to be removed into the Editor Window. 2. You will see a small &quot;stop sign&quot; immediately to the left of the line that contains the Breakpoint. 3. Put the &quot;Insert Cursor&quot; anywhere on that line and click the RIGHT mouse button. A menu will appear. 4. Select the &quot;Remove Breakpoint&quot; option and the Breakpoint is removed (and the small &quot;stop sign&quot; disappears). b. Using the Breakpoint Dialog Box to remove one or more LOCATION (Line Number or Function) Breakpoints. 1. Click &quot;Edit&quot; in the Main Menu [MM(2)]. 2. Select the &quot;Breakpoints&quot; option from the menu that appears. The Breakpoint Dialog Box will appear. 3. At the bottom of the Breakpoint Dialog Box you will see all currently set Breakpoints. Click the name of the Breakpoint you want to remove and that name is highlighted, or if you want to remove ALL currently set Breakpoints, just click the &quot;Remove All&quot; button in the dialog box and then click the &quot;OK&quot; button in the dialog box to exit the Breakpoint Dialog Box (and skip step &quot;4&quot; below). To temporarily DISABLE a Breakpoint listed at the bottom of the Breakpoints Dialog Box, click the small &quot;check&quot; icon to the left of the Breakpoint name. To re-enable that Breakpoint, just click that same icon (and the &quot;check&quot; will reappear). 4. Click the &quot;Remove&quot; button in the dialog box. To remove another Breakpoint, just repeat steps &quot;3&quot; and &quot;4&quot;. Once you have removed all the Breakpoints you desire, click the &quot;OK&quot; button in the dialog box to exit the Breakpoint Dialog Box. Keep in mind that if you edit the source-code using some other editor (not the Visual C++ Editor), then your Breakpoints can be all messed up. The moral is - edit the source-code only with the Visual C++ Editor. 3. Setting a DATA Breakpoint. -------------------------- The following methods for setting/removing/disabling Data Breakpoints will work if done from the Editor and will also work if done while the program is being executed under the debugger): You can set a Breakpoint that will be activated when: a. The value of a variable changes during program execution under the debugger (called a VALUE-CHANGE Breakpoint). b. The value of a specified conditional expression becomes true as the program executes under the debugger (called a CONDITIONAL Breakpoint). Note that when you run the debugger with Data Breakpoints set, program execution will stop at the next Data Breakpoint and a pop-up message window will appear with the message &quot;Break ...... when&quot; and an &quot;OK&quot; button. You must click the &quot;OK&quot; button to actually get to the next Data Breakpoint. To set a Data Breakpoint, you must use the &quot;Breakpoint Dialog Box&quot;. To get this dialog box to be displayed, do the following. 1. Click &quot;Edit&quot; in the Main Menu [MM(2]. 2. Select the &quot;Breakpoints&quot; option from the menu that appears. The Breakpoint Dialog Box will appear. Note that there are three tabs at the top of the Breakpoint Dialog Box. Click the &quot;Data&quot; tab to set a Data Breakpoint. Be very careful that you do NOT click the &quot;Location&quot; tab as you will get no error when you try to set a &quot;Data&quot; Breakpoint with the &quot;Location&quot; tab, but the &quot;Data&quot; Breakpoint will not be set and will not work. A. Setting a VALUE-CHANGE Breakpoint. ---------------------------------- It is assumed you are in the Breakpoints Dialog Box. Here, program execution under the debugger will stop the next time the value in the specified variable is modified. However, the manner in which you set this kind of &quot;Data&quot; Breakpoint depends on where in the program the specified variable is declared. 1. If the variable on which you are setting the Breakpoint is declared as a GLOBAL variable (outside any function), then do the following: a. Type the name of the GLOBAL variable in the text field named &quot;Enter the Expression to be Evaluated&quot;. If you want to set this kind of Data Breakpoint on one or more additional GLOBAL variables, then put the cursor on the &quot;dotted box&quot; that is in the &quot;Breakpoints&quot; window at the bottom of the dialog box and click the left mouse button. Type the name of the next GLOBAL variable on which you want to set this kind of Breakpoint, and then click the dotted box again. Keep entering GLOBAL variable names and clicking the dotted box until you have set all the &quot;global&quot; breakpoints you desire. b. Click on the &quot;OK&quot; button in the dialog box to activate all the Breakpoints (Data-Change or Conditional) you just set and to exit the &quot;Breakpoints&quot; Dialog Box. 2. If the variable on which you are setting the Breakpoint is declared in an EXTERNAL function (a function that is not a member function of any class), then do the following (this includes function &quot;main&quot;): a. Click the small &quot;menu icon&quot; immediately to the right of the text field named &quot;Enter the Expression to be Evaluated&quot;. b. Click the word &quot;Advanced&quot; that appears and the &quot;Advanced Breakpoints&quot; Dialog Box appears. c. Type the name of the variable (declared in the EXTERNAL function) on which you are setting a Breakpoint in the text field named &quot;Expression&quot;. d. In the text field named &quot;Function&quot;, type the name of the EXTERNAL function where this data item is declared (e.g. &quot;main&quot; or &quot;doit&quot; {without the quotes}). e. In the text field named &quot;Source file&quot;, type the name of the source-code file that contains the EXTERNAL function entered in step &quot;d&quot; above. For example, if &quot;doit&quot; is defined in source-code file &quot;main.cpp&quot;, then type &quot;main.cpp&quot; (without the quotes). f. Click the &quot;OK&quot; button in the Advanced Breakpoint Dialog Box and it will disappear and you will be back at the Breakpoints Dialog Box. If you want to set this kind of Data Breakpoint on additional variables declared in an EXTERNAL function, just repeat steps &quot;a&quot; through &quot;f&quot; above. If not, then click the &quot;OK&quot; button in the Breakpoint Dialog Box to exit this dialog box. 3. If the variable on which you are setting the Breakpoint is declared in a MEMBER function of a class, then do the following: a. Click the small &quot;menu icon&quot; immediately to the right of the text field named &quot;Enter the Expression to be Evaluated&quot;. b. Click the word &quot;Advanced&quot; that appears and the &quot;Advanced Breakpoint&quot; Dialog Box appears. c. Type the name of the variable on which you are setting a Breakpoint in the text field named &quot;Expression&quot;. d. In the text field named &quot;Function&quot;, type the name of the MEMBER function in which the variable is declared preceded by &quot;classname::&quot; where &quot;classname&quot; is the name of the class of which this function is a member. For example, if the data member on which you are setting this kind of Breakpoint is declared in function &quot;domore&quot; which is a member of class &quot;List&quot;, then type &quot;List::domore&quot; (without the quotes). e. In the text field named &quot;Source file&quot; type the name of the source-code file that contains the DEFINITION (implementation) of this MEMBER function. For example, if &quot;domore&quot; is in source- code file &quot;list.cpp&quot;, then type &quot;list.cpp&quot; (without the quotes). f. Click the &quot;OK&quot; button in the Advanced Breakpoint Dialog Box and it will disappear and you will be back at the Breakpoints Dialog Box. If you want to set this kind of Data Breakpoint on additional variables declared in a MEMBER function, just repeat steps &quot;a&quot; through &quot;f&quot; above. If not, then click the &quot;OK&quot; button in the Breakpoints Dialog Box to exit this dialog box. Some helpful hints: a. Setting a Breakpoint on an ARRAY: --------------------------------- For the following discussion of &quot;arrays&quot;, it is assumed that if you are in the &quot;Advanced Breakpoint Dialog Box&quot; that you will type in values in the &quot;Function&quot; and &quot;Source file&quot; text fields as described above for simple variables. 1. To set a Data Breakpoint on an &quot;array&quot; so that program execution will stop any time the value stored in any element of the array is altered, do the following. Type in the &quot;Enter the expression to be evaluated&quot; text field of the Breakpoints Dialog Box (or the &quot;Expression&quot; text field of the Advanced Dialog Box of the Breakpoints Dialog Box) the name of the array (and nothing else). For example, if the name of the array is &quot;vect&quot;, then just type &quot;vect&quot; (without the quotes). 2. To set a Data Breakpoint on a single element of an array so that program execution will stop only if the value in that specified element is altered, do the following. Type in the &quot;Enter the expression to be evaluated&quot; text field of the Breakpoints Dialog Box (or the &quot;Expression&quot; text field of the Advanced Dialog Box of the Breakpoints Dialog Box) the name of the array followed by [elem_num] where &quot;elem_num&quot; is the index of the array element you want to set the Breakpoint on. For example, if the name of the array is &quot;vect&quot; and you want to set a Data Breakpoint on element index &quot;3&quot; of that array, then just type &quot;vect[3]&quot; (without the quotes). 3. To set a Data Breakpoint on the first &quot;n&quot; elements of an array so that program execution will stop only if the value in one of the first &quot;n&quot; elements is altered, do the following. - Type in the &quot;Enter the expression to be evaluated&quot; text field of the Breakpoints Dialog Box (or the &quot;Expression&quot; text field of the Advanced Dialog Box of the Breakpoints Dialog Box) the name of the array (and nothing else). For example, if the name of the array is &quot;vect&quot;, then just type &quot;vect&quot; (without the quotes). - Now look for the text field named &quot;Enter the number of elements to watch in an array&quot; in the Breakpoints Dialog Box. Place the cursor in that window and click the left mouse button. Now erase any number that is currently in that window and type the number that will be used for &quot;n&quot; (the first &quot;n&quot; elements of the array to be watched). - Then click the OK button in the Breakpoints Dialog Box as usual. b. Setting a Breakpoint on a STRUCTURE: ------------------------------------ For the following discussion of &quot;structures&quot;, it is assumed that if you are in the &quot;Advanced Dialog Box&quot; that you will type in values in the &quot;Function&quot; and &quot;Source file&quot; text fields as described above for simple variables. 1. To set a Data Breakpoint on a &quot;structure&quot; so that program execution will stop whenever the value stored in any field of the structure is altered, do the following. Type in the &quot;Enter the expression to be evaluated&quot; text field of the Breakpoints Dialog Box (or the &quot;Expression&quot; text field of the Advanced Dialog Box of the Breakpoints Dialog Box) the name of the structure (and nothing else). For example, if the name of the structure is &quot;rec&quot;, then just type &quot;rec&quot; (without the quotes). One caution - if the structure contains an &quot;array-of-characters&quot; (string) field, the debugger may display the debugger output in ASSEMBLY language form rather than source-code form when the &quot;string&quot; field is altered. If this happens, click the &quot;Break Out&quot; button on the DEBUGGER Button Bar [Debugger(7)] and the source-code form of the program will be re- displayed with the current line set to the appropriate Data Breakpoint. If you ever get &quot;stuck&quot; in an ASSEMPLY language display of the Debugger Window, you can get back to the SOURCE-CODE display by doing the following: - Click &quot;Window&quot; in the Main Menu [MM(8)]. The &quot;Window&quot; menu will appear. - Select the &quot;Windows&quot; option from that menu and the &quot;Windows Dialog Box&quot; will appear. - If there is already a &quot;box&quot; around the name of the window that is displaying the ASSEMBLY language form of the program, just click on the &quot;Close Window(s)&quot; button, else click on the name of the window that is displaying the ASSEMBLY language form of the program, and then click on &quot;Close Window(s)&quot;. 2. To set a Data Breakpoint on a single field of a structure so that program execution will stop only if the value in that specified field is altered, do the following. Type in the &quot;Enter the expression to be evaluated&quot; text field of the Breakpoints Dialog Box (or the &quot;Expression&quot; text field of the Advanced Dialog Box of the Breakpoints Dialog Box) the name of the structure followed by .fieldname where &quot;fieldname&quot; is the name of the field you want to set the Breakpoint on.. For example, if the name of the structure is &quot;rec&quot; and you want to set a Data Breakpoint on the &quot;age&quot; field of that structure, then just type &quot;rec.age&quot; (without the quotes). One caution - if a Data Breakpoint is set on an &quot;array-of-characters&quot; (string) field, the debugger may display the debugger output in ASSEMBLY language form rather than source-code form when the &quot;string&quot; field is altered. If this happens, click the &quot;Break Out&quot; button on the DEBUGGER Button Bar [Debugger(7)] and the source-code form of the program will be re- displayed with the current line set to the appropriate Data Breakpoint. c. Setting a Breakpoint on a POINTER: ---------------------------------- You can set a Data Breakpoint to occur when the &quot;address&quot; stored in a pointer is altered. To set this kind of Data Breakpoint, type in the &quot;Enter the expression to be evaluated&quot; text field of the Breakpoints Dialog Box (or the &quot;Expression&quot; text field of the Advanced Dialog Box of the Breakpoints Dialog Box) the name of the pointer variable. For example, if the pointer variable is named &quot;ptr&quot;, then type &quot;ptr&quot; (without the quotes). It is NOT possible to set a Breakpoint to occur when the value &quot;pointed to&quot; by the pointer is altered (thus, if the pointer variable is &quot;ptr&quot;, you cannot set a Breakpoint on &quot;*ptr&quot;). You can get around this by assigning the value pointed to another variable and then setting a Data Breakpoint on that other variable. For example, we could write: double *num_ptr=new double, tmp_num; and later in the program we could write: *num_ptr = val; tmp_num = *num_ptr; and then we can set a Data Breakpoint on &quot;tmp_num&quot;. B. Setting a CONDITIONAL Breakpoint. --------------------------------- It is assumed you are in the Breakpoints Dialog Box. Setting a CONDITIONAL Breakpoint will stop program execution when a specified CONDITION arises. Here, program execution under the debugger will stop at the line of source-code where a specified expression (condition) first becomes TRUE. A condition can be any legitimate C++ Boolean Expression. As soon as that expression evaluates to TRUE, program execution will stop. Example of BOOLEAN expressions include: v1 &lt; v2, !done, k == 0, ((x!=y) &amp;&amp; (!v)) To set this kind of CONDITIONAL Breakpoint, do the following: 1. In the Editor Window, display the line of source- code that contains the BOOLEAN expression you are setting the CONDITIONAL Breakpoint for. For example, if the condition on which a conditional Breakpoint is to be set is &quot;k&gt;=10&quot;, then you must get a line of source-code that references this instance of &quot;k&quot; displayed in the Editor Window. For example, the line of code might be: ary[k]=a*b; When the BOOLEAN conditional Breakpoint is set on that line of code, then program execution will stop when the value of &quot;k&quot; gets to be greater than or equal to &quot;10&quot; at this line of code. 2. Place the &quot;Insert Cursor&quot; anywhere on the line of code displayed from doing step &quot;1&quot; above, and then click the left mouse button to select that line. 3. Get the Breakpoints Dialog Box displayed by doing the following: - Click &quot;Edit&quot; in the Main Menu [MM(2)]. - Select the &quot;Breakpoints&quot; option from the menu that appears. The Breakpoint Dialog Box will appear. 4. Click the &quot;Location&quot; tab at the top of the &quot;Breakpoints Dialog Box&quot;. 5. Click the &quot;menu icon&quot; (the small right-pointing arrow) at the far right of the &quot;Break at&quot; text field. 6. Click the &quot;Line #&quot; option from the menu (where &quot;#' is an integer value that represents the number of the line in the source-code that you selected in step &quot;2&quot; above). For example, if the &quot;Insert Cursor&quot; was on line 170 when you selected a line in step &quot;2&quot; above, then click the &quot;Line 170&quot; menu option. You will now see at '.170' in the &quot;Breakpoints&quot; window at the bottom of the dialog box. 7. Click the &quot;Condition&quot; button in the Breakpoints Dialog Box and the &quot;Breakpoint Condition&quot; dialog box will be displayed. 8. In the &quot;Enter the expression to be evaluated&quot; text field, type a C++ expression such as v1 &lt; v2, !done, k == 0, ((x!=y) &amp;&amp; (!v)) For example, you might type: k&gt;=10; 9. Click the &quot;OK&quot; button in the &quot;Breakpoint Condition&quot; Dialog Box and that dialog box is removed. You will now see: at '.170' when k&gt;=10 displayed in the &quot;Breakpoints&quot; window at the bottom of the Breakpoints Dialog Box. 10. Click the &quot;OK&quot; button in the Breakpoints Dialog Box to set this CONDITIONAL breakpoint and exit the Breakpoints Dialog Box. NOTE - setting &quot;Data Breakpoints&quot; is particularly useful when trying to find a bug that is causing your program to enter an INFINITE LOOP. Using the Breakpoint Dialog Box to remove one or more DATA (Value-Change or Conditional) Breakpoints. 1. Click &quot;Edit&quot; in the Main Menu [MM(2)]. 2. Select the &quot;Breakpoints&quot; option from the menu that appears. The Breakpoint Dialog Box will appear. 3. At the bottom of the Breakpoint Dialog Box you will see all currently set Breakpoints. Click the name of the Breakpoint you want to remove and that name is highlighted, or if you want to remove ALL currently set Breakpoints, just click the &quot;Remove All&quot; button in the dialog box and then click the &quot;OK&quot; button in the dialog box to exit the Breakpoint Dialog Box (and skip step &quot;4&quot; below). To temporarily DISABLE a Breakpoint listed at the bottom of the Breakpoints Dialog Box, click the small &quot;check&quot; icon to the left of the Breakpoint name. To re-enable that Breakpoint, just click that same icon (and the &quot;check&quot; will reappear). 4. Click the &quot;Remove&quot; button in the dialog box. To remove another Breakpoint, just repeat steps &quot;3&quot; and &quot;4&quot;. Once you have removed all the Breakpoints you desire, click the &quot;OK&quot; button in the dialog box to exit the Breakpoint Dialog Box. Keep in mind that if you edit the source-code using some other editor (not the Visual C++ Editor), then your Breakpoints can be all messed up. The moral is - edit the source-code only with the Visual C++ Editor. If you try to set a &quot;bad&quot; Breakpoint (a Location Breakpoint on a line that does not exist, or a Data Breakpoint for a variable that does not exist or is not &quot;visible&quot;) you will get an error message when you try to run your program in the debugger. The error message will say &quot;One or more breakpoints cannot be set and have been disabled&quot;. If this happens to you, click the OK button on the error message box, exit the debugger, and get back in the Breakpoints Dialog Box and remove the &quot;bad&quot; Breakpoint (and set the proper breakpoint). Debugging a Program. -------------------------------------------------------------------- Breakpoints have their effect (suspending program execution) only when your program is run under the control of the Debugger. The Debugger can only help you find RUN-TIME (logical) errors, not COMPILE-TIME (syntax) errors. You cannot execute your program under the Debugger's control until that program compiles without error. Note - your program will compile if only WARNINGS are reported by the compiler. However, if the compiler reports even one (fatal) ERROR, then the program is not compiled and cannot be executed under the Debugger. Get rid of all SYNTAX (compile-time) errors and then your program can be run under the Debugger. A. Running (Starting) the Visual C++ Debugger. ------------------------------------------- There are three methods by which you can have the Debugger execute the program under its control. 1. The &quot;F5&quot; key method. -------------------- To run the Debugger using this method, do the following: - Get the project file that contains the function named &quot;main&quot; displayed in the Editor Window. It is assumed that the program was created as a PROJECT. To get this file displayed in the Editor Window, see the document entitled &quot;Editing Source-Code Files&quot;. - Have the Debugger Button Bar displayed. To do this, do the following: a. Place the mouse cursor over an empty area of the Main Menu (at the top of the screen). b. Click the RIGHT mouse button. c. Select the &quot;Debug&quot; option from the menu that appears. You can then move and/or dock this Debugger Button Bar where you wish. It is usually best to &quot;dock&quot; the Debugger Button Bar. - Press the &quot;F5&quot; key on the keyboard. The debugger will start executing the program that is the current project and will suspend program execution at the first Breakpoint it encounters (or when your program tries to perform an &quot;Illegal Operation&quot;). You will see some buttons on the Debugger Button Bar displayed &quot;sharper&quot; (darker) than other buttons on that bar. The darker buttons are those that can be used (clicked) and the fainter (lighter) buttons are those that cannot at this time be used (clicked). For a &quot;Location&quot; Breakpoint, program execution stops on the line of source-code where the Location Breakpoint was set, and this line of source-code (and several lines above and below this line) is displayed in the Editor Window. If the Debugger suspends program execution due to the occurrence of a &quot;Data&quot; Breakpoint, it displays a small window that contains the message: Stop at ... condition ... and an &quot;OK&quot; button. Click the &quot;OK&quot; button and the section of your program source-code that contains the current Data Breakpoint is displayed in the Editor Window. You can now examine properties of your program and view the values stored in the variables currently &quot;visible&quot; by taking any actions described under the heading &quot;Examining the State of Your Program&quot; below. To re-start the Debugger when a Breakpoint is encountered, and have it continue executing your program until the next Breakpoint is encountered (or until the program ends), just press the &quot;F5&quot; key again. To terminate and exit the debugger, click the &quot;Stop Debugging&quot; button on the Debugger Button Bar [Debug(2)]. You will now see most of the buttons on the Debugger Button Bar become very &quot;faint&quot; (light) which means they are inactive and cannot be used. Some of the buttons will remain &quot;sharp&quot; (dark) which means they are still active 2. The &quot;run-to-cursor&quot; method. --------------------------- With this method, you can execute your program until it reaches the line of source-code where you placed the &quot;Insert Cursor&quot;. To have the Debugger start program execution and then suspend execution at the current &quot;Insert Position&quot;, do the following: - Get the line of source-code on which you want to set this kind of temporary Breakpoint displayed in the Editor Window. - In the Editor Window, place the &quot;Insert Cursor&quot; on the line of source-code where the temporary Breakpoint is to be set and then click the left mouse button to &quot;set&quot; the &quot;Insert Position&quot; (and select this line). - Click the &quot;Run to Cursor&quot; button on the Debugger Button Bar [Debug(8)] (you do not have to press the F5 key) and your program will be executed until the line of source- code on which the current &quot;Insert Position&quot; was set is reached. At that point, program execution is suspended and now you can examine properties of your program and view the values stored in the variables currently &quot;visible&quot; by taking any actions described under the heading &quot;Examining the State of Your Program&quot; below. You can set the &quot;Insert Position&quot; for any line of any file that makes up your program. Remember, this kind of &quot;temporary&quot; Breakpoint is NOT maintained from one debugging session to another. 3. The &quot;step-into&quot; method. ----------------------- Another way to &quot;start&quot; the debugger is to click the &quot;Step Into&quot; button on the Debugger Button Bar [Debug(5)] (or the &quot;Step Over&quot; button [Debug(6)]). Clicking either of these two buttons has the same effect; the debugger will start, but will suspend program execution at the first line of function &quot;main&quot;. You can then examine properties of your program and view the values stored in the variables currently &quot;visible&quot; by taking any actions described under the heading &quot;Examining the State of Your Program&quot; below. B. Restarting and exiting the debugger. ------------------------------------ 1. The Debugger MUST already be running your program before you can &quot;re-start&quot; Debugger execution (i.e. do not try to re-start the Debugger when it is not currently running your program). To RE-START the debugger means that the &quot;current debugging line&quot; is re-set from its current position in the program code to the first line in function &quot;main&quot;. To RE-START the debugger, click the &quot;Restart&quot; button on the Debugger Button Bar [Debug(1)], and then press the &quot;F5&quot; key on the keyboard. When you press this key you will note that the debugger starts running the program from the first line of function &quot;main&quot; and suspends execution at the first Breakpoint it encounters (which is not necessarily the same Breakpoint where you were when you initiated the re-start action). The purpose of &quot;re-starting&quot; the debugger is to have the debugger re-run your program from its beginning so you can (a) review the execution of lines of code you have already passed through, or (b) to re-run the program after you have made a changes to variable values or program code and you want to see the effects of these changes. That is, you can &quot;edit&quot; your source-code while in the debugger and then re-start the debugger to see what occurs as a result of the editing. Note - if you make a change to your source-code (i.e. edit the source-code) while you are in the debugger and then try to &quot;re- start&quot; the debugger, you will get the message &quot;One or more files are out of date or do not exist. Would you like to build them?&quot; Click the &quot;YES&quot; button and your altered programs will be re-compiled and then the debugger will re-start the program. Remember to press the &quot;F5&quot; key each time you want to run the debugger to the next Breakpoint. 2. To stop and exit the debugger and return to the Editor, click the &quot;Stop Debugging&quot; button on the Debugger Button Bar [Debug(2)]. If you choose this option, you cannot &quot;re-start&quot; the debugger by clicking the &quot;Restart&quot; button. You must use one of the three &quot;start debugger&quot; methods described above to start the debugger running again. C. Step through the program one line at a time. -------------------------------------------- You may want to execute certain lines of the program one line at a time. You could then: a. Examine the value of one or more variables after the current line of code is executed. b. See which path through a conditional statement is taken. c. View the output produced by the execution of a line of code. d. Check to see if a function is entered. Executing a program (under the control of the debugger) one line of code at a time is called &quot;stepping through a program&quot;. Once a Breakpoint has been encountered and the debugger has suspended program execution, you can &quot;step through&quot; one or more lines of code (and have that code executed) by taking one of the following three actions. 1. Click the &quot;Step Over&quot; button on the Debugger Button Bar [Debug(6)]. When this button is clicked, the line of code preceded by the &quot;current line marker&quot; (which is a small right-pointing arrow at the left of the line of code), is executed and then the &quot;current line marker&quot; is moved to the next line of code that would be executed if this button were to be clicked again. The next line of code to be executed is not necessarily the line immediately below the line of code just executed. Which line is executed next depends upon the flow of program control. Each time you click the &quot;Step Over&quot; button, the line preceded by the &quot;current line marker&quot; is executed. Note that if the next line of code to be executed is a call to a function, clicking the &quot;Step Over&quot; button will &quot;step over&quot; (i.e. not enter) that function. However, all the code contained within that function will automatically be executed (even if it contains many lines of code). Thus, if this &quot;stepped-over&quot; function changes the values of variables and/or produces outcomes, you can be sure that all these changes and outcomes will have taken place and will have their effect on subsequent program execution. That is to say, &quot;stepping over&quot; a function does NOT result in the code contained in that function being left unexecuted. The code in that function will be executed as one step. After the code in the skipped function has been executed, the &quot;current line marker&quot; will be moved to the first line of executable code that follows the line where that function was called. Click the &quot;Step Over&quot; button to avoid entering functions in which you have no interest (i.e. you do not want to step through the code in that function). Remember, many calls to functions do not look like a call to a function. For example: cout &lt;&lt; str &lt;&lt; endl; is a call to a built-in overloaded operator function. If you click the &quot;Step Over&quot; button when the above line of code is the &quot;next-to-be-executed&quot; line, then the code contained in that function will be executed, but you will not &quot;step into&quot; than function (which you probably would not want to do anyway). If you are not sure which of the three &quot;step&quot; buttons on the Debugger Button Bar to click, it is always safest to click the &quot;Step Over&quot; button. 2. Click the &quot;Step Out&quot; button on the Debugger Button Bar [Debug(7)]. When this button is clicked, the debugger automatically executes the remaining unexecuted lines of code in the current function, exits that function, and stops program execution at the next line of code to be executed following the call to that function. Thus, this provides a way to leave the currently executing function and, thereby, make it unnecessary to &quot;step through&quot; the remainder of the current function. Use the &quot;Step Out&quot; option if: a. You want to exit the function you are currently stepping through because you have no need to step through any more of its code, or; b. You accidentally &quot;stepped into&quot; a function you do not want to step through and you want to immediately get out of that function. 3. Click the &quot;Step Into&quot; button on the Debugger Button Bar [Debug(5)]. This option works just like the &quot;Step Over&quot; button except that if the next line of code to be executed is a call to a function, then when the &quot;Step Into&quot; button is clicked, the function that is called WILL be entered (and not skipped as with the &quot;Skip Over&quot; option), and the next line of code executed by the debugger will be the first line of code in the function entered. Be careful about clicking &quot;Step Into&quot; because it is very easy to &quot;step into&quot; uninteresting functions accidentally. For example, if the next line of code to be executed when &quot;Step Into&quot; is clicked is a &quot;built-in&quot; function such as &quot;strcpy&quot;, then the debugger will actually enter that function and stop at the first line of code in that function (and you probably have no interest in looking at the execution of code within that function). When the debugger enters certain &quot;built-in&quot; functions (e.g. strcpy), it displays the code in that function in ASSEMBLY language form (which may not be of much use to you). In other cases, the debugger will display the built-in function in its source-code from. For example, if the next line of code to be executed when you click the &quot;Step Into&quot; button is: cout &lt;&lt; str &lt;&lt; endl; then the debugger will enter this overloaded operator function for the stream insertion operator for a string value (&lt;&lt;) and the code contained in that function is displayed in its source-code form which you will have to either step through or &quot;step out&quot; of. If you accidentally &quot;step into&quot; a function you do not want to step through, just click the &quot;Step Out&quot; button [Debug(7)] (as discussed above), and the debugger will make the line of code that follows the call to this function the next-to-be- executed line. The moral is WATCH WHAT YOU STEP INTO. There are two other interesting buttons on the Debugger Button Bar that you may need to use: Run to cursor. -------------- 1. Click the &quot;Run to Cursor&quot; button on the Debugger Button Bar [Debug(8)] to: a. Start the debugger running and have the debugger suspend program execution at a specified line of code. To specify the line of code at which program execution should be suspended, do the following (it is assumed that your source-code is in the &quot;Editor Window&quot; and the debugger is not currently running): - In the Editor Window, place the &quot;Insert Cursor&quot; on the line where you want program execution suspension to occur. - Click the left muse button to &quot;select&quot; that line. Now if you click the &quot;Run to Cursor&quot; button, the debugger will start and will execute your program until it reaches the &quot;selected&quot; line of code at which point it will suspend program execution. You can then choose one of the other debugger options. Keep in mind that if a regular Breakpoint is encountered before the selected line is reached, program suspension will occur at that regular Breakpoint and the &quot;run to cursor&quot; setting will be lost. You can think of this method as setting a &quot;temporary&quot; Breakpoint which will disappear the first time it is encountered. b. Have the debugger continue program execution from the current Breakpoint until a specified line is reached at which point program execution is suspended again. Here it is assumed the debugger is already running, but has stopped at a Breakpoint. To continue program execution to the specified line, do the following: - In the Editor Window, place the &quot;Insert Cursor&quot; on the line where you want program execution suspension to occur. This line of code must be one that FOLLOWS (is executed after) the current debugging line. - Click the left muse button to &quot;select&quot; that line. Now if you click the &quot;Run to Cursor&quot; button, the debugger will CONTINUE executing your program until it reaches the &quot;selected&quot; line of code at which point it will suspend program execution. You can then choose one of the other debugger options. Keep in mind that if a regular Breakpoint is encountered before the selected line is reached, program suspension will occur at that regular Breakpoint and the &quot;run to cursor&quot; setting will be lost. The &quot;Run-to-Cursor&quot; option is great for getting out of executing loops. Just put the cursor on the first line of code below the loop statement, click the left mouse button to select that line, and then click the &quot;Run to Cursor&quot; button. The loop will complete looping in its normal manner and program execution will be suspended at the first line of code below that loop. Break Debugger execution. ------------------------- 2. Click the &quot;Break Execution&quot; button on the Debugger Button Bar [Debug(3)] if the debugger is currently actively running your program (that is it is actively executing lines of code and is not stopped at a Breakpoint), and you want to have the debugger stop executing lines of program code (i.e. suspend itself). You may want to &quot;break execution&quot; so you can exit the debugger, or perform other debugger actions. Clicking &quot;Break Execution&quot; will not cause you to exit the debugger, it will just stop the debugger from executing lines of program code. If the debugger is not actively executing program code, clicking the &quot;Break Execution&quot; button will have no effect. D. Examining the state of a program. --------------------------------- Before trying to do any of the following, bring up the &quot;Debugger Button Bar&quot; first by doing the following: a. Place the mouse cursor over an empty area of the Main Menu (at the top of the screen). b. Click the RIGHT mouse button. c. Select the &quot;Debug&quot; option from the menu that appears. You can then move and/or dock this Debugger Button Bar where you wish. It is usually best to &quot;dock&quot; the Debugger Button Bar. When the debugger has suspended program execution because a Breakpoint has been encountered, you can take any of the following actions to examine program properties and to view the values stored in currently visible variables/parameters of your program. To debug a program it is often necessary to examine the value stored in a specific variable (or set of variables) at specific points during program execution. You may want to determine the value assigned to a counter, an array index specifier, a function parameter, or just some variable as the program is executed under the control of the debugger. You may want to see what main memory address is currently stored in a &quot;pointer&quot;, or you may want to examine the value(s) stored in the block of memory pointed to by a pointer. You can see what values are stored in the fields of a structure and/or the data members of an object. It is easy to examine and trace the values assigned to program variables as the program executes under the control of the debugger. 1. Using the VARIABLES window. --------------------------- a. The LOCALS Tab. -------------- You can examine and trace the value currently assigned to each variable/parameter that is currently visible in the function being executed by the debugger. You CANNOT examine variables that are not currently visible (e.g. as variables that are local to a function that is not the currently executing function). CURRENTLY VISIBLE means: - All parameters passed into the currently executing function. - All variables declared within the currently executing function (i.e. all LOCAL variables). - All GLOBAL variables that do not share the same name as a currently visible LOCAL variable or parameter of the currently executing function. In addition, if the value associated with any one of the &quot;visible&quot; variables/parameters is altered by code in the executing function, you will see the new (altered) value assigned to the variable/parameter at the instant that value change occurs. In this way, you can see how variable values change as the program executes and where in the program a variable is assigned an incorrect value (that is, where a program error has occurred). Once you know where such a misasignment of a value occurred, you can examine your code to see why this error occurred and fix that error. To have the value of EVERY visible variable/parameter displayed in a special window, do the following: - Click the &quot;Variables&quot; button on the Debugger Button Bar [Debug(11)]. - At the bottom of the special window that appears you will see three tabs. Click the &quot;Locals&quot; tab (if it is not already selected). You will now see two columns; one called &quot;Name&quot; and one called &quot;Value&quot;. The data item(s) under &quot;Name&quot; is the name of a currently visible variable/parameter, and the data item under &quot;Value&quot; is the value associated with the variable whose name is listed to the immediate left. For simple data types such as &quot;int&quot;, &quot;float&quot;, &quot;double&quot;, and &quot;char&quot;, you will see the variable name and its associated value. If a visible variable/parameter has not been assigned (or initialized to) a value as yet, you will see some strange value reported (or an &quot;error message&quot; is displayed). For more complex data types such as an array, a structure, a pointer, or an object, the &quot;Name&quot; data item is preceded by a small plus (+) icon. Click this icon to view the separate values stored within this more complex variable (note that the '+' icon becomes a '-' icon). For example: Click the '+' preceding And see ----------------------- ------------------------------- An array The values stored in each ELEMENT of the array. A structure The values stored in each FIELD of the structure A pointer The value(s) stored in the block of memory pointed to by the pointer. An object The values stored in each data member of the object. Use the vertical scroll bar at the right side of this special &quot;Variables&quot; window to scroll up and down in the list of variable names/values. To get back to only the variable name wit