═══ About this Information ═══ The How Do I... information provides solutions to common tasks that you would perform with the various components of VisualAge C++. Before you begin to use this information, it would be helpful to understand how to navigate through it: o Use the Contents and Index facilities to locate topics. o Use the Search facility to search the text of this document. o Use hypertext links to acquire related information on the current topic. Hypertext links appear in a different color (which you can customize using the OS/2 Scheme Palette). For example, below there are two lists of hypertext links. By double-clicking on the text of the link or by pressing Enter on a highlighted link, you will open a panel of related information. To shift the focus to other links using the keyboard, use the Tab key. For more information on using this help facility, see: o How to Use the Contents o How to Obtain Additional Information o How to Access and Use IPF Facilities For more information, see: o Other Information You Might Find Helpful o Communicating Your Comments to IBM o Notices o Trademarks ═══ How to Use the Contents ═══ The Contents window is the first to appear. Some topics have a plus ( ) icon beside them. This icon indicates that additional topics are available. To expand the Contents if you are using a mouse, click on the plus ( ) icon. If you are using the keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus (+) key. To see additional topics for a heading with a plus ( ) icon, click on the icon or highlight that topic and press the plus (+) key. To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press the Enter key). ═══ How to Obtain Additional Information ═══ After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. Certain words and phrases are highlighted in a different color from the surrounding text. These are called hypertext terms. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information then appears in a window. ═══ How to Access and Use IPF Facilities ═══ Several choices are available for managing the information presented in this document. There are three PullDown menus: the Services menu, the Options menu, and the Help menu. The actions that are selectable from the Services menu operate on the active window currently displayed on the screen. These actions include the following: Placing Bookmarks You can set a placeholder so you can retrieve information of interest to you. Searching for Information You can find occurrences of a word or phrase in the current topic, selected topics, or all topics. Printing Information You can print one or more topics. You can also print a set of topics by first marking the topics in the Contents list. Copying Information to a File You can copy a topic that you are viewing to the System Clipboard or to a file that you can edit. This method is particularly useful for copying syntax definitions and program samples into the application that you are developing. Using the actions that are selectable from the Options menu, you can change the way your Contents list is displayed. To expand the Contents and show all levels for all topics, choose Expand all from the Options PullDown menu. You can also press the Ctrl, Shift and * keys together. The actions that are selectable from the Help menu allow you to select different types of help information. For information about any of the menu choices, highlight the choice in the menu and press F1. ═══ Placing Bookmarks ═══ When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty. To set a bookmark, do the following: 1. Select a topic from the Contents. 2. When that topic appears, select the Bookmark option from the Services menu. 3. If you want to change the name used for the bookmark, type the new name in the field. 4. Click on the Place radio button (or press the Up or Down Arrow key to select it). 5. Click on OK (or select it and press Enter). The bookmark is then added to the bookmark list. ═══ Searching for Information ═══ You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list. To search for a word or phrase in all topics, do the following: 1. Select the Search option from the Services menu. 2. Type the word or words to be searched for. 3. Click on All sections (or press the Up or Down Arrow keys to select it). 4. Click on Search (or select it and press Enter) to begin the search. 5. The list of topics where the word or phrase appears is displayed. ═══ Printing Information ═══ You can print one or more topics, the index, or the table of contents. Make sure that your printer is connected to the serial port, configured correctly, and ready for input. To print: 1. Select Print from the Services menu. 2. Select what you want to print. Note that the This section and Marked sections choices are only available if you are viewing a topic or if you have marked topics, respectively. To mark topics in the table of contents, press the Ctrl key and click on the topics, or use the arrow keys. 3. Select Print to print what you've chosen on your printer. ═══ Copying Information to a File ═══ You can copy a topic that you are viewing in two ways: o Copy copies the topic that you are viewing into the System Clipboard. If you are using a Presentation Manager (PM) editor (for example, the Enhanced Editor) that copies or cuts (or both) to the System Clipboard, and pastes to the System Clipboard, you can easily add the copied information to your program source module. o Copy to file copies the topic that you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using any editor. TEXT.TMP is placed in the directory where your viewable document resides. To copy a topic, do the following: 1. Expand the Contents list and select a topic. 2. When the topic appears, select Copy to file from the Services menu. 3. The system puts the text pertaining to that topic into the temporary file TEXT.TMP. ═══ Other Information You Might Find Helpful ═══ The VisualAge C++ provides a number of online guides and references that we hope you'll find helpful as you develop applications. This information includes: o User's Guide information provides conceptual and usage information, o Reference information is organized for quick access, and o How Do I... information gives you specific instructions for performing common tasks. You can get to this online information from the Information folder inside the main product folder. You can also get to it from the Help menu in any of the components of the product. ═══ Communicating Your Comments to IBM ═══ If there is something you like, or dislike, about this document, please let us know. You can use one of the methods listed below to send your comments to IBM. Please be sure to include the complete title of the publication that you are commenting on. For example, you would refer to the How Do I... information for the Browser as: VisualAge C++ Browser: How Do I... for OS/2. The comments you send should only pertain to the information in this document and its presentation. To request additional publications or to ask questions or make comments about the functions of IBM products or systems, you should talk to your IBM representative or your authorized IBM remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. You can send your comments to IBM in the following ways: o By mail to the following address: IBM Canada Ltd. Laboratory Information Development 2G/345/1150/TOR 1150 EGLINTON AVENUE EAST NORTH YORK, ONTARIO CANADA M3C 1H7 o By FAX to the following number: - United States and Canada: (416) 448-6161 - Other countries (+1) 416-448-6161 o By electronic mail to one of the following IDs. Be sure to include your entire network address if you wish to get a reply. - Internet: torrcf@vnet.ibm.com - IBMLink: toribm(torrcf) - IBM/PROFS: torolab4(torrcf) - IBMMAIL: ibmmail(caibmwt9) ═══ Notices ═══ Copyright International Business Machines Corporation, 1995. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. This edition applies to Version 3.0 of IBM VisualAge C++ for OS/2 (30H1664, 30H1665, 30H1666) and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; any such changes will be reported in subsequent revisions. Requests for publications and for technical information about IBM products should be made to your IBM Authorized Dealer or your IBM Marketing Representative. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any ways it believes appropriate without incurring any obligation to you. Any reference to an IBM licensed program in this publication is not intended to state or imply that only IBM's licensed program may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing. IBM Corporation, 500 Columbus Avenue, Thornwood, NY, 10594, USA. This publication contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. ═══ Trademarks and Service Marks ═══ The following terms used in this publication are trademarks or service marks of IBM Corporation in the United States or other countries: C/2 C Set/2 C Set ++ Common User Access CUA IBM Operating System/2 OS/2 Personal System/2 Presentation Manager PS/2 VisualAge WorkFrame/2 Other company, product, and service names, which may be denoted by a double asterisk(**), may be trademarks or service marks of others. ═══ 1. Access windows that are hidden or minimized ═══ To access any debugger window that is already open and hidden or minimized: 1. Select the Windows menu from any of the debugger windows. 2. Select the window you want from the list of choices. The window is brought into focus and made the active window. ═══ 2. Change line colors in a source window ═══ Use the Source Window Colors window to change the color of lines in a source window. To change the color of the background in the source window: 1. Select Options  Window settings  Colors from a source window. 2. Open the OS/2 Color Palette window. 3. Using the mouse pointer, select a color from the color palette. 4. Hold down mouse button two and drag the selected color to the Source Window Colors window. 5. Release mouse button two over the text line that represents the source window area that you want to change. 6. Select the Apply push button. To change the color of the foreground in the source window: 1. Select Options  Window settings  Colors from a source window. 2. Open the OS/2 Color Palette window. 3. Using the mouse pointer, select a color from the color palette. 4. Hold down the Ctrl key and mouse button two and drag the selected color into the Source Window Colors window. 5. Release the Ctrl key and mouse button two over the text line that represents the source window area that you want to change. 6. Select the Apply push button. To change the colors in the other debugger windows, simply drag and drop the selected colors directly on the window that you want to change. ═══ 3. Change the font ═══ To change the font in the Control or any of the source windows: 1. Select Options  Window settings  Fonts from the Control window or from a source window. The Font Selection window displays. 2. Choose the font you want and select the OK push button. To change the font in the other debugger windows: 1. Select Options  Fonts. The Font Selection window displays. 2. Choose the font you want and select the OK push button. ═══ 4. Change program profiles location ═══ To change the location where you want program profiles stored: 1. Select Options  Debugger settings  Program profiles  Change location from the Control window or from a source window. The Change Location window displays. 2. Type the full path name of the directory where you want the program profiles file stored in the Path entry field. 3. Select the OK push button. Note: Any existing program profiles will be moved to the specified directory. ═══ 5. Change representation of an expression ═══ To change the representation of an expression or a variable: 1. Select the expression or variable that you want to change from any of the monitor windows. These include the Program Monitor, Private Monitor, and Popup Monitor. The expression becomes highlighted. 2. Select Options  Representation. 3. Select an alternate representation from the choices that are available. The new representation takes effect immediately. You can change the representation of the value displayed in a monitor to: o Hexadecimal o Decimal o String o Character o Floating-point o Hexadecimal pointer o Decimal pointer o Array. Note: The representation you can select varies with the data type being displayed. ═══ 6. Change the Presentation Manager debugging mode ═══ The PM debugging mode choice allows to set the debugging mode to asynchronous or synchronous. This controls the interaction between the program windows and Presentation Manager, while the application has stopped executing. To change the debugging mode: 1. Select Options  Debugger settings  PM debugging mode from the Control window or a source window. The PM Debugging Mode window displays. 2. Select one of the following radio buttons: o Synchronous o Asynchronous 3. Select the other parameters you want from this window. 4. Select the OK push button. ═══ Asynchronous ═══ When the debugger is operating in asynchronous mode and the program you are debugging is stopped, the debugger immediately responds to messages that have been sent to the program being debugged on this program's behalf. The debugger answers the messages with a simple default response, freeing up other processes to operate while the debugger has control. When you are running the debugger in asynchronous mode, other Presentation Manager applications running in the system are not blocked when the program being debugged stops. Warning: Do not operate the debugger in asynchronous mode if the Presentation Manager application that you are debugging requires the appropriate response to its messages. For example, a dynamic data exchange (DDE) message would require the appropriate response. ═══ 7. Change views ═══ To select a different view of your program: 1. Select the View menu from a source window. 2. Select the view you want. You can view the program as Source, Disassembly, or Mixed You may also select the View button located in the title bar. This allows you to cycle through the source windows. The order depends on the view priority. ═══ 8. Check the heap ═══ This checks all memory blocks allocated or freed by the compiler debug memory management functions. This makes sure that overwriting has not occurred outside the bounds of allocated blocks and free memory blocks have not been overwritten. To enable heap check: 1. Select Run  Check heap when stopping from the Control window or from a source window. 2. Enable the Check heap when stopping choice. When a check mark symbol displays, heap check is enabled. When Check heap when stopping choice is enabled, each time the program stops, the heap is checked. For example, stopping at a breakpoint or at the end of a step command would cause the heap check to be performed. If a heap error is detected, your application terminates. The Termination window displays showing the source line number where the application stopped and the heap check was performed. Notes o For the Check heap when stopping choice to work, you have to compile your application using the Tm+ compiler option. o If you enable the Check heap when stopping choice and you run your application to termination and the application contains a heap error, the heap check is not made. To check the heap just before termination, set a breakpoint on the last line of our application. ═══ 9. Close the debugger ═══ To close the debugger: 1. Select File  Close debugger from any of the debugger windows. The Close Debugger message box displays. 2. Select Yes to end the debugging session. You can also press F3 in any primary debugger window to end the debugging session. ═══ 10. Close the How Do I... information ═══ To close the How Do I... information: Mouse Users: o Click on a How Do I... panel with mouse button 2 (usually the right). o Select Exit Note that this popup menu provides access to the services (such as, search, bookmark, copy), options (such as, expand, collapse, index, libraries), and help provided for the Information Presentation Facility (IPF). Keyboard Users: o Press F3 ═══ 11. Debug child processes ═══ To debug child processes: 1. Open the Program Startup window. 2. Enable the Debug child process(es) check box. When you enable this check box, the Child name(s) entry field becomes active. 3. Type the name of the child process you want to debug in the Child name(s) entry field. You can also select the Child list push button. If you select Child list, the Select Child Process window displays. From this window, select the child process or processes you want to debug. The Program Startup window displays again with the child names displayed in the Child name(s) entry field. After your program starts running and the selected child process is started by OS/2, the debugger begins debugging the child process. ═══ 12. Delete breakpoints ═══ To delete all the breakpoints that have been set: 1. Select Breakpoints  Delete all from the Control window or from a source window. An information box displays for verification to delete all breakpoints. 2. Select Yes. You can also select the Delete all choice from the Edit menu in the Breakpoint List window. To delete a simple line breakpoint: 1. Place your mouse pointer on the line number of the breakpoint you want to delete. The prefix area displays in red indicating that a breakpoint has been previously set. 2. Double-click on the red prefix area. The color clears indicating that the breakpoint cleared. If the prefix area turns gray instead, double-click again to make sure the breakpoint clears. To delete all other breakpoints: 1. Select Breakpoints  List from the Control window or from a source window. The Breakpoints List window displays. 2. Select the breakpoint you want to delete. The line becomes highlighted. 3. Select Edit  Delete. The highlighted breakpoint is deleted. If the prefix area turns gray instead, double-click again to make sure the breakpoint clears. ═══ 13. Delete program profiles ═══ To delete program profiles for a program that you have previously debugged: 1. Select Options  Debugger settings  Program profiles  Delete from the Control window or from a source window. The Delete window displays. 2. Select the path names of the programs whose program profile you want to delete. 3. Select the Delete push button. ═══ 14. Display a list of object files ═══ The Components pane, which is located in the Control window, shows the executable files that are associated with the program you are debugging. To display a list of object files contained within the executable file: o Select the plus icon to the left of the executable file name. To open a source window of an object file: o Double-click on the object file name. You can display any component (object or function) by double-clicking on the component name or by highlighting the component name and selecting a view from the View menu. ═══ 15. Display functions for a particular thread ═══ To list the active functions or procedures for a particular thread: o Select Monitors  Call chain from the Control window or from a source window. When you select Call chain, the Call Chain window displays. ═══ 16. Display local variables for the current function ═══ To show the local variables (static, automatic, and parameters) for a specific function: o Select Monitors  Local variables from the Control window or from a source window. The local variables display in the Local Variables window. ═══ 17. Display Presentation Manager messages ═══ Select Monitors  Message queue monitor from the Control window or from a source window. The Message Queue Monitor window presents formatted messages in a list as they occur. Using the message queue monitor, you can control the following: o How the information displays for each message. o How message parameters are formatted. o Which messages are monitored. o Which windows have their messages monitored. o Which message queues have their messages monitored. o How the user generated messages display. ═══ 18. Display specific components ═══ To specify which components display in the Components list: 1. Select Options  Debugger settings  Only components with debug data. 2. Enable the Only components with debug data choice from the Control window or from a source window. When this choice is enabled, only components compiled and linked with debugging data are listed. Otherwise, all components are listed. ═══ 19. Display the contents of storage ═══ To display the contents of storage used by your program: o Select Monitors  Storage from the Control window or from a source window. To open additional storage windows, repeat the above step. You can also select the Storage button in the title bar of any of the source windows. ═══ 20. Display the functions for a specific object ═══ To display a list of functions for a specific object file: o Select the plus icon to the left of the object file name in the Control window. To open a source window to a specific function: o Double-click on the function name. You can display any component (object or function) by double-clicking on the component name that displays in the Components box or by highlighting the component name and selecting a view from the View menu. ═══ 21. Display the registers ═══ To display the processor and math coprocessor registers: o Select the Monitors  Registers from the Control window or from a source window. You can also select the Registers button in the title bar of any of the source windows. ═══ 22. Display the state of a thread ═══ To display the state of a thread: 1. Go to the Control window. 2. Select the plus icon to the left of the thread name. When a check mark symbol displays, threads are enabled and the debugger allows the highlighted thread to execute. When the check mark symbol does not display, threads are disabled and do not execute. You can also double-click on Enabled to change the thread status to Disabled. You may enable or disable the highlighted thread in the Threads list by toggling the Enabled choice from the Run menu in the Control window or from a source window. ═══ 23. Enable threads ═══ To enable threads: o Select Run  Thread enabled from the Control window or from a source window. The thread that is highlighted in the Threads box of the Control window is executed when the program runs. When threads are enabled, a check mark symbol displays beside the Thread enabled choice. When threads are not enabled, a check mark symbol is not displayed and the highlighted thread is not executed when the program runs. ═══ 24. Filter exceptions ═══ Use the Exception Filtering window to select exceptions that you want the debugger to recognize. o Select Options  Debugger settings  Exception filtering from the Control window or from a source window. The Exception Filtering window displays. To highlight an exception: 1. Select the exception by clicking on the name. It becomes highlighted. 2. Select the OK push button. If a highlighted exception is encountered during the execution of your program, the Exception window is displayed. Any other exceptions that are encountered are ignored. For details on the OS/2 exception definitions listed in this window, refer to the Control Program Programming Reference (S10G-6263-00). The Software exception will not be listed, since this is a user-defined OS/2 exception generated by the DosRaiseException call. ═══ 25. Halt execution of my program ═══ To interrupt execution of your program: o Select Run  Halt from the Control window or from a source window. This stops your program from running. You can also access this choice by pressing SysRq (Alt+PrintScreen). ═══ 26. Hide the debugger when running a program ═══ To hide the debugger windows whenever your program is running: o Select Run  Hide debugger on Run from the Control window or from a source window. The debugger windows will display again when the program is finished running. ═══ 27. Jump to Location ═══ Select Run  Jump to Location from any of the source windows. This takes you to the current line in your program without executing the lines between the present current line and the new current line. To use the Jump to location choice: 1. Single-click in the prefix area of the line you want to become the current line. The prefix area turns gray. 2. Select the Jump to location choice. The current line is changed and the lines between are not executed. The Jump to location choice stops only on executable lines. If a highlighted line is not executable, the jump is not performed. Warning Jumping out of the current function may corrupt the call chain and cause your program to produce unpredictable results. ═══ 28. List all the breakpoints ═══ To list all the breakpoints that have been set, do the following: o Select Breakpoints  List from the Control window or from a source window. When you select List, the Breakpoint List window displays. This window displays all the breakpoints that have been set and provides a description of each breakpoint. ═══ 29. Locate a function ═══ To open a source window to a particular function: 1. Select View  Locate function from a source window. The Locate Function window displays. 2. Type the name of the function you want to search for in the Function entry field. 3. Select the OK push button. If the function that you specify is not found, the following message displays: No matching function found This means it may be a static function or the function you specified does not exist. ═══ 30. Look at Presentation Manager windows ═══ To help you understand Presentation Manager (PM) application windows: o Select Monitors  Window analysis from the Control window or from a source window. The Window Analysis window presents both graphical and textual information of debugged windows and lets you observe the relationships between windows. Note: To display the Window Analysis window, you must stop your program. ═══ 31. Modify a breakpoint ═══ To change the state of a breakpoint that has been set in your program: 1. Select Breakpoints List from the Control window or from a source window. The Breakpoints List window displays. 2. Highlight the breakpoint you want to change. 3. Select Edit  Modify from the Breakpoint List window. The breakpoint window containing information pertaining to that breakpoint displays. Make the necessary changes to the entry fields. 4. Select the OK push button. If you want to make other changes, select Set to accept the changes and keep the window open. ═══ 32. Open a new source file ═══ To open a new source file: 1. Select View  Open new source from a source window. The Open New Source window displays. 2. Type the name of the object file you want to open the source for in the Source entry field. For example, to look for the source used to compile A123.OBJ, type the following: A123. If you are unsure of the file name, select the File List push button to view a list of the files that you can select. 3. Type the name of the executable file in the Executable entry field. The source files for the executable file display in the Source entry field. Note: You have to disable the All executables check box option to search only one executable file. 4. Select the OK push button. ═══ 33. Perform a step debug ═══ Select the Step debug choice to execute the current line in the program. The debugger steps over any function for which debugging data is not available, such as library and system functions, and steps into any function for which debugging information is available. To perform a step debug: o Select Run  Step debug from any of the source windows. You may also select the Step debug button which is located in the title bar of any source window. ═══ 34. Perform a step into ═══ Select the Step into choice to execute the current line in the program. If the current line is a call, execution stops at the first statement in the called function. Note: If you have multiple calls on the same source line and perform a step into for which there is no source code available, the Disassembly view displays. To return to the Source view, you have to do a step return. To avoid this, perform step debug so that the debugger will step over any calls for which debugging data is not available, such as library and system functions, and steps into any function for which debugging information is available. To perform a step into: o Select Run  Step into from any of the source windows. You may also select the Step into button which is located in the title bar of any source window. ═══ 35. Perform a step return ═══ Select the Step return choice to automatically execute the lines of code up to, and including, the return statement of the current function. To perform a step return: o Select Run  Step return from any of the source windows. You may also select the Step return button which is located in the title bar of any source window. ═══ 36. Perform a step over ═══ Select the Step over choice to execute the current line of the program. If the current line is a call, execution stops when the call completes. You can also access the Step over function by placing the mouse pointer in a source window and clicking mouse button two to execute one line. All enabled threads continue execution. Note: The debugger stops in a called function if it encounters a breakpoint. To perform a step over: o Select Run  Step over from any of the source windows. You may also select the Step over button which is located in the title bar of any source window. ═══ 37. Restart a debugging session ═══ To restart a debugging session: o Select Run  Program restart from the Control window or from a source window. Program restart allows you to restart the current debugging session on the existing program, while Program startup allows you to debug another program. ═══ 38. Run my program ═══ To run your program: o Select Run  Run from the Control window or from a source window. You can also select the run button located in the title bar of the source windows or press R. ═══ 39. Run from the current line to a highlighted line ═══ Select Run  Run to Location from a source window to execute your program from the current line up to the line that is highlighted or gray in the prefix area. To use the Run to location choice: 1. Single-click in the prefix area of the line you want to become the current line. The prefix area turns gray. 2. Select the Run to location choice. The program runs up to the line that you marked. The Run to location choice stops only on executable lines. ═══ 40. Scroll to a particular line ═══ To scroll to a particular line in your program or set a line breakpoint: 1. Select View  Scroll to line number from a source window. The Scroll to Line Number window displays. 2. Type the line number you want to scroll to in the Enter line number: entry field. 3. Select the OK push button to scroll to that line. the Note: If the Source window is active, you can type in a number and the Scroll to Line Number window displays. To use the Scroll to Line Number window to set a breakpoint: 1. Type the line number you want to set the breakpoint on in the Enter line number: entry field. 2. Select the Set Breakpoint push button to set the breakpoint on the specified line number. ═══ 41. Set a breakpoint in a DLL that is not loaded ═══ To set a deferred breakpoint in a DLL that is not loaded: 1. Select Breakpoints  Set function from the Control window or from a source window. The Set Function window displays. 2. Type the name of the DLL in the Executable entry field. 3. Type the name of the object file in the Source entry field. 4. Type the name of the function in the Function entry field. 5. Enable the Defer breakpoint check box. 6. Select the Set push button. Note: If your application consists of an EXE or preloaded DLLs, do not use this choice. If your application consists of DLLs that are dynamically loaded, use this choice to set breakpoints in DLLs which have not been loaded yet. If you set a deferred breakpoint in a function and that function is overloaded, the debugger sets the breakpoint in all of the overloaded functions when the DLL is loaded. ═══ 42. Set breakpoints ═══ To set breakpoints: 1. Select the Breakpoints menu from the Control window or from a source window to set breakpoints. 2. Select the appropriate choice that represents the type of breakpoint that you want to set. You can set various types of breakpoints. Double-click on any of the following to learn how to set the breakpoint: o Set a simple line breakpoints o Set a line breakpoint o Set a function breakpoint o Set an address breakpoint o Set a change address breakpoint o Set a load occurrence breakpoint o Set a deferred breakpoint. ═══ 42.1. Set a line breakpoint ═══ To set a line breakpoint: o Select Breakpoints  Set line from the Control window or from a source window. When you select Set line, the Set Line window displays. You can also set simple line breakpoints. Double-click on one of the following for the procedures you use to set or clear simple line breakpoints: o Setting simple line breakpoints o Deleting simple line breakpoints. ═══ 42.2. Set simple line breakpoints ═══ To set a simple line breakpoint in all threads: o Double-click in the prefix area of an executable statement in any of the source windows. The prefix area turns red indicating that the breakpoint has been set. To set a line breakpoint for a specific thread, hold down the CTRL key as you double-click in the prefix area. ═══ 42.3. Delete Simple Line Breakpoints ═══ To remove a simple line breakpoint in all threads: o Double-click in a red prefix area of a source window. The color changes indicating that the breakpoint cleared. If the prefix area turns gray instead, double-click again to make sure the breakpoint clears. ═══ Set Line Window ═══ Use the Set Line window to set a breakpoint on a specific line. For a description of the entry fields in the window, double-click on one of the following topics: o Executable o Source o File o Line number o Thread o From o To o Every o Expression Defer breakpoint Check Box Enable this check box if you want to postpone the setting of a breakpoint in a DLL. Note: If your application consists of an EXE or preloaded DLLs, do not use this choice. If your application consists of DLLs that are dynamically loaded, you must use this choice to set breakpoints in the dynamically loaded DLLs that have not been loaded yet. If you enter an invalid source, source file or invalid line number, the debugger is unable to activate the breakpoint when the DLL is loaded. Therefore, the invalid breakpoint remains in the deferred state even after the DLL is loaded. The state of the breakpoints will change from active state to deferred state depending on whether the DLL has been loaded or not. For example, if the DLL has been loaded and a deferred breakpoint has been set, the breakpoint becomes active. If you stop the program and the DLL has been freed, the breakpoint changes from active state to deferred state. If you set a deferred line breakpoint and the line is located in a template, the debugger sets the line breakpoint in all of the templates when the DLL is loaded. ═══ Executable Entry Field ═══ To select a component from the Executable list: 1. Open the Executable list by selecting the arrow with your mouse. 2. Highlight the executable where you want to set the breakpoint. OR Type the executable name in the entry field. ═══ Source Entry Field ═══ To select a component from the Source list: 1. Open the Source list by selecting the arrow with your mouse. 2. Highlight the source where you want to set the breakpoint. OR Type the source name in the entry field. ═══ Line Number Entry Field ═══ To set a line breakpoint, type the line number in the Line number entry field. The breakpoint is set on the line number. ═══ 42.4. Set a function breakpoint ═══ To set a function breakpoint: o Select Breakpoints  Set function from the Control window or from a source window. When you select Set function, the Set Function window displays. ═══ Set Function Window ═══ Use the Set Function window to set a function breakpoint. Type the name of the function. If a function is overloaded, then a window displays with a list of all the overloaded function names. Select one of the functions from the list. To set a function breakpoint for the function my_func, you would type the following in the Function entry field. my_func Note: You cannot set a function breakpoint to a function name that was defined using the define preprocessor directive. For a description of types of data you can enter in the entry fields, double-click on one of the following topics: o Executable o Source o Function o Expression o Thread o From o To. All executables Check Box Enable this check box if you want to search all the executable files for the function. Note: To search for a function in a particular executable file, disable this check box and type in the name of the executable file in the Executable entry field and the name of the source file in the Source entry field. Debug data only Check Box Enable this check box if you want to search only the object files that contain debugging data. Case sensitive Check Box Enable this check box if you want to search for the string exactly as typed. Disable this check box if you want to search for both uppercase and lowercase characters. Defer breakpoint Check Box Enable this check box if you want to postpone the setting of a breakpoint in a DLL. Note: If your application consists of an EXE or preloaded DLLs, do not use this choice. If your application consists of DLLs that are dynamically loaded, you must use this choice to set breakpoints in the dynamically loaded DLLs that have not been loaded yet. If you enter an invalid source file or invalid function, the debugger is unable to activate the breakpoint when the DLL is loaded. Therefore, the invalid breakpoint remains in the deferred state even after the DLL is loaded. The state of the breakpoints will change from active state to deferred state depending on whether the DLL has been loaded or not. For example, if the DLL has been loaded and a deferred breakpoint has been set, the breakpoint becomes active. If you stop the program and the DLL has been freed, the breakpoint changes from active state to deferred state. If you set a deferred breakpoint in a function and that function is overloaded, the debugger sets the breakpoint in all of the overloaded functions when the DLL is loaded. ═══ 42.5. Set an address breakpoint ═══ To set an address breakpoint: o Select Breakpoints  Set address from the Control window or from a source window. When you select Set address, the Set Address window displays. ═══ Set Address Window ═══ Use the Set Address window to set an address breakpoint. Type in the address that represents the location in your program where you want to set the breakpoint. Note: The address can be either segmented or flat format. To set an address breakpoint for the address 000A1FCC, you would type the following in the Address or expression entry field. A1FCC For a description of types of data you can enter in the window entry fields, double-click on any of the following topics: o Thread o Every o From o To o Expression ═══ 42.6. Set a change address breakpoint ═══ To set a change address breakpoint: o Select Breakpoints  Set change address from the Control window or from a source window. When you select Set change address, the Set Change Address window displays. ═══ Set Change Address Window ═══ Use the Set Change Address window to set a change address breakpoint. To do so, type a hexadecimal address or an expression and select the range of bytes. Note: The debugger supports up to 4 enabled change address breakpoints. However, you can set as many disabled change address breakpoints as you want. To set a change address breakpoint, complete the fields as follows: Address or expression Entry Field You would type the following in the Address or expression entry field to set a change address breakpoint for the expression 0xA1FCC. 0xA1FCC Note: If you type ABC in the Address or expression entry field, and there is a variable named ABC, it uses the value of the variable instead of the hex value ABC. Also, you can type &a in the Address or expression entry field to set the breakpoint on the address of a variable a. Warning: If you set a change address breakpoint that is on the call chain, you should remove the breakpoint prior to leaving the routine associated with the breakpoint. Otherwise, when you return from the routine, the routine's stack frame will be removed from the stack leaving the breakpoint intact. Any other routine that gets loaded on the stack will then contain the breakpoint. Bytes to monitor Radio Buttons Select one of the radio buttons to specify the range of bytes. The 2-byte range must be aligned on a word boundary and the 4-byte range must be aligned on a double-word boundary. Execution stops when the specified range of memory changes. For a description of types of data you can enter in the other window entry fields, double-click on one of the following topics: o Thread o From o To o Every ═══ 42.7. Set a load occurrence breakpoint ═══ To set a load occurrence breakpoint which stops your program when a specific DLL is loaded: o Select Breakpoints  Set load occurrence from the Control When you select Set load occurrence, the Set Load Occurrence window displays. ═══ Set Load Occurrence Window ═══ Use the Set Load Occurrence window to set a DLL load occurrence breakpoint. Type the name of the DLL in the DLL file name entry field. Execution stops when the DLL is loaded. DLL file name Entry Field To set a DLL load occurrence breakpoint when MY.DLL is loaded, you would type the following in the DLL file name entry field: MY or MY.DLL For a description of types of data you can enter in the other window entry fields, double-click on one of the following topics: o Thread o From o To o Every ═══ File List ═══ If the source you selected has include files with executable statements, then the File list displays all the file names that contain executable lines. 1. Open the File list by selecting the arrow with your mouse. 2. Highlight the file where you want to set the breakpoint. OR 3. Type the name of the file in the entry field. ═══ Function List ═══ Type in the name of the function where you want to set the breakpoint or select a function from the Function list: 1. Open the Function list by selecting the arrow with your mouse. 2. Highlight the function you want to set the breakpoint. OR 3. Type the name of the function in the entry field. ═══ Expression Entry Field ═══ If you are setting an address, function, or line breakpoint, you can also type in an expression. The execution of the program stops only if this condition tests true. For example, you could type the following: (i==1) || (j==k) && (k!=5) Note: Variables in a conditional expression associated with a Function breakpoint are limited to any static or global variables that are known to the called function when the function is called. Local variables and automatic variables cannot be used. The maximum length of the condition is 256 characters. ═══ Thread List ═══ To select a thread ID from the Thread list: 1. Open the Thread list by selecting the arrow with your mouse. 2. Highlight the thread where you want to set the breakpoint. Select Every, the default, to set a breakpoint in all of the active threads in your program. The Every choice is thread independent. Select one of the individual threads to set a breakpoint in one thread only. Threads are added to the Thread list as new threads are activated. ═══ Every Entry Field ═══ This field is used for location breakpoints and load occurrence breakpoints. Type in a whole integer number to indicate how often the breakpoint should be activated within the From and To range. ═══ From Entry Field ═══ This field is used for location breakpoints and load occurrence breakpoints. Type in a whole integer number to start activating the breakpoint the nth time the location is encountered. ═══ To Entry Field ═══ This field is used for location breakpoints and load occurrence breakpoints. Type in a whole integer number to stop activating the breakpoint after the nth time the location is encountered. ═══ 43. Set the search path ═══ The search path tells the debugger where to find the source file used in the source windows. The debugger searches for the source files in the following order: 1. The path defined by the PMDOVERRIDE environment variable, if specified. 2. The path where the object file was compiled. 3. The path where the executable file is located. 4. The path defined by the PMDPATH environment variable, if specified. 5. The current path. 6. The path defined in the INCLUDE environment variable. The debugger uses two environment variables: PMDOVERRIDE and PMDPATH to set the search path. To set the PMDOVERRIDE environment variable, type the following at the command line: Set PMDOVERRIDE=path;path where, path is the location of your source files. If the source file is not found in the defined override path, the debugger uses the normal search order. To set the PMDPATH environment variable, type the following at the command line: Set PMDPATH=path;path where, path is the location of your source files. To override the normal search order, use the PMDOVERRIDE environment variable: ═══ 44. Sort breakpoints ═══ Use the Sort window to sort the breakpoints by categories. To use the Sort window: 1. Select an item from the list that represents how you want the breakpoints sorted. 2. Select the OK push button. ═══ 45. Sort components alphabetically ═══ To sort the components in alphabetical order: o Select Options  Window settings  Sort components from the Control window. If enabled, a check mark symbol displays beside the Sort components choice and components are sorted alphabetically. ═══ 46. Sort threads numerically ═══ To sort the threads in numerical order: o Select Options  Window settings  Sort threads from the Control window. If enabled, a check mark symbol displays beside the sort threads choice and threads are sorted numerically. ═══ 47. Start a program ═══ To start a program: 1. Select File  Program startup from the Control window or from a source window. The Program Startup window displays. 2. Type the name of the program you want to start in the Program entry field. 3. Type any parameters you want to pass to your program in the Parameters entry field. Separate multiple parameters with a space. 4. Enable the Debug child process(es) check box if you want to debug processes that are started under the parent program. When you enable this check box, the Child name(s) entry field becomes active. 5. In the Child name(s) entry field, type the name of the child process you want to debug. You can also select the Child list push button. If you select Child list, the Select Child Process window displays. From this window, select the child process or processes you want to debug. The Program Startup window displays again with the child names displayed in the Child name(s) entry field. After your program starts running and the selected child process is started by OS/2, the debugger begins debugging the child process. 6. Enable the Debug program initialization check box if you want to start the debugger in the system initialization routine to debug initialization code. This allows you to halt the execution of the application before any initialization routines have been executed. It also you to debug any DLL initialization routines. 7. Select the Use program profile check box if you want to start the debugging session with program profiles. 8. Select the OK push button. Program startup allows you to debug another program, while Program restart allows you to restart the current debugging session on the existing program. ═══ 48. Turn the titles on or off ═══ You can specify to display the titles or to turn the titles off in the Control window. The titles are Threads and Components. To turn the titles on: o Select Options  Window settings  Titles on from the Control window. If enabled, a check mark symbol displays beside the Titles on choice and titles display. ═══ 49. Update storage ═══ To display the Storage window: o Select Monitors  Storage from the Control window or any of the source windows. You can also select the Storage button located in the title bar of the source windows. To update the contents of storage, use one of the following methods: o Highlight the appropriate line and press Enter. An entry field displays, Type the new storage information in the entry field. o Double-click on the appropriate column. An entry field displays. Type in the new storage information. To move around in the Storage window, press the Tab key to move the selected column to the right or press Shift+Tab to move the selected column to the left. The up and down arrow keys move the highlighted line up and down. After you have made a change in the Storage window, click anywhere in the window and it saves your changes. If you enter an incorrect storage address, a prompt box displays and the previous storage address is returned in the column. ═══ 50. Use shortcut keys ═══ Shortcut keys are usually two key names that are joined by a plus sign (+). However, they can also be a single key stroke. To use the shortcut keys that are joined by a plus sign(+): o Hold down the first key and press the second key. The following shortcut keys are available from the Control window: Where is execution point Ctrl+P Close debugger F3 List Ctrl+X Call stack Ctrl+K Registers Ctrl+E Storage Ctrl+G Local variables Ctrl+V Run R Halt SysRq The following shortcut keys are available from the source windows (Source/Disassembly/Mixed): Where is execution point Ctrl+P Close debugger F3 Find Ctrl+F Find next Ctrl+N List Ctrl+X Monitor expression Ctrl+M Call stack Ctrl+K Registers Ctrl+E Storage Ctrl+G Local variables Ctrl+V Step over O Step into I Step debug D Step return T Run R Run to location L Jump to location N Halt SysRq Note: If you press F3 from any primary window, the debugger will close. ═══ 51. View include files ═══ To look at include files: 1. Select View  Select Include files from a source window. The Select Include File window displays. 2. Select the include file. The include file name is highlighted. 3. Select the OK push button. The selected include file view displays. ═══ Breakpoint ═══ A breakpoint is a defined location or condition in a program that, when it is met, stops the execution of the program. ═══ Debugging data ═══ Debugging data is the symbolic and line number information contained in the executable file. ═══ Disable ═══ Disable prevents a thread from executing. ═══ Enable ═══ Enable allows a thread to execute. ═══ Executable files ═══ Executable files are the EXE or DLL files. ═══ Functions ═══ A Function is a block of statements executed by a function call. Synonymous with procedures. ═══ Load occurrence breakpoints ═══ A load occurrence breakpoint allows you to stop the execution of your program after the DLL that you specify is loaded. ═══ Location breakpoint ═══ A location breakpoint is one of the following: o A line breakpoint o An address breakpoint o A function breakpoint. ═══ Program Profiles ═══ Program profiles are used to restore the debugger windows and breakpoints when debugging a program more than once. It is stored separately for each program debugged. The file extension for the files that contain this information is @2R. Note: Only information for executable files and preloaded DLLs relating to the primary thread is restored. To delete this information, erase the @2R file. ═══ Synchronous ═══ When the debugger is operating in synchronous mode, the messages that are passed between Presentation Manager applications are answered by their target applications in the order that they were created. The messages that are passed within the debugger take priority over any other messages that are passed in the system. When the program being debugged is stopped and the debugger is in synchronous mode, other Presentation Manager applications are locked, leaving the debugger free to operate. In synchronous mode, you will not be able to use any other Presentation Manager applications that are running. ═══ ═══ Trademark of International Business Machines Corporation