═══ 1. Notices ═══ References in this online information to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. 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 Commercial Relations, IBM Corporation, Purchase, NY 10577. This publication could contain technical inaccuracies or typographical errors. ═══ 1.1. Trademarks and Service Marks ═══ The following terms, denoted by an asterisk (*) in this online documentation, are trademarks of the IBM Corporation in the United States and/or other countries: o IBM o Presentation Manager o Operating System/2 o OS/2 o WorkFrame/2 ═══ 2. New and Enhanced Features ═══ The following describes the new and enhanced features that have been added to the debugger since the previous release: New Features Deferred breakpoints Allows you to set a breakpoint in a DLL that is not currently loaded. If your application consists of DLLs that are dynamically loaded, use this feature to set breakpoints in DLLs which have not been loaded yet. These deferred breakpoints become active once the DLL is loaded. See the Set Line Window or the Set Function Window for more details. Child process debugging Supports debugging of processes started by a parent program. See Program Startup Window for more details. Exception filtering Allows you to select the exceptions that you want the debugger to recognize. An exception occurs when your application is unable to interpret specific requests. See Exception Filtering Window for more details. Check heap when stopping Helps to isolate memory management problems by checking for memory overwriting each time your program stops executing. See Check Heap When Stopping Choice for more details. Hide debugger on Run Hides the debugger windows while your application is running. See Hide Debugger on Run Choice for more details. Color support Allows you to change the color of the various window elements such as executable lines, non-executable lines, and the breakpoint prefix area. See Colors Window for more details. SOM support Allows you to debug SOM objects created with the compiler using Direct-to-SOM support or created with the SOM compiler. Support includes monitoring SOM classes in the monitor windows. Scroll to line number Allows you to scroll to a particular line number in the source code. This feature also provides the ability to set breakpoints. See Scroll to Line Number Window for more details. Autosave window positions and sizes Saves the window positions and sizes when the windows are moved or re-sized. Alternatively, you may save the window positions and sizes by positioning the debugger windows on the desktop and selecting the Save window positions and sizes choice. See Autosave Window Positions and Sizes Choice for more details. Integration Provides quick and easy access to other tools such as an editor or the browser. This feature is available when the debugger is started from within the WorkFrame environment. Select include files Allows you to select the include files you want to view. Include files are files that are included in your source file by a compiler directive and are considered program source files. See Select Include File Window for more details. Windows menu Displays a list of all the active debugger windows. Hover help for title bar buttons Displays the name of the title bar button when you place the mouse pointer on a button. If you drag the mouse pointer across the buttons, the name in the title bar area changes to reflect the button you are on. Enhanced Features The following describes the enhanced features that have been added to the debugger since the previous release. Call stack window Provides the option of displaying the remaining stack size, the stack frame size, the return address, the ESP value and the EBP value. See Call Stack Window for more details. Breakpoint list window Displays as a window allowing you to continuously monitor the breakpoint list. You can also display the source code where the breakpoint is set. See Breakpoint List Window for more details. Storage window Allows you to monitor expressions in a storage window. For example, if you are monitoring a pointer, as the pointer changes, the storage window changes to show the new location referenced by the pointer. See Storage Window for more details. Change address breakpoint Allows you to set a change address breakpoint by typing in an expression. See Set Change Address Window for more details. Enable program profiling Allows you to enable or disable the use of program profiles which restores a program's breakpoints, source windows and monitors to the same state as when last debugged. See Program Profiles Choice for more details. ═══ 3. Compiling and Linking Your Program ═══ To use the debugger, compile and link your program with the following options: Compiler Options /Ti+ Compiles your program to produce an object file that includes line number information and a symbol table, in addition to the source code. /Oi- Compiles your program with inlining off. This is the default. /Tm+ This option is required if you want to use the debugger heap check feature. Linker Options /DEbug Links your program to produce an executable file that includes line number information and a symbol table, in addition to the executable code. For more information about compiling and linking your program, refer to the IBM VisualAge C++ Tools Programming Guide. ═══ 4. Program Startup Window ═══ Use the Program Startup window to specify the program you want to start for this debugging session. 1. Select a program for debugging using one of the following methods: o Type the name of the program you want to start in the Program entry field. o Open the Program list by selecting the list button then selecting a program name. o Select the File list push button and select a program from the Select Program window. 2. Type any parameters you want to pass to your program in the Parameters entry field. Separate multiple parameters with a space. 3. Select one of the push buttons to continue. Program Entry Field Type the name of the program you want to start for your debugging session. You do not need to include the file name extension when you type the program name. However, the extension does default to exe. You can also select the list button to display a drop-down combination box. The drop-down combination box contains a list of up to five previously debugged programs. File List Push Button If you select the File list push button, the Select Program window displays. From this window, select the program you want to debug. The Program Startup window displays again with the program name displayed in the Program entry field. Parameters Entry Field If the program accepts parameters, type the parameters that you want to pass to the program you are starting. Debug child process(es) Check Box Enable the Debug child process(es) check box to debug processes that are started under the parent program. When you enable this check box, the Child name(s) entry field becomes active. Child name(s) Entry Field In the Child name(s) entry field, type the name of the child process you want to debug. You can also select the list button to display a drop-down combination box. The drop-down combination box contains a list of up to five previously debugged child processes. Child List Push Button 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. Debug program initialization Check Box Enable the Debug program initialization check box to start the debugger in the system initialization routine so that you can debug initialization code. This allows you to halt the execution of the application before any initialization routines have been executed. This allows you to debug any DLL initialization routines. Use program profile Check Box Select the Use program profile check box to start the debugging session using a program profile. Related Information o Command Line Parameters. ═══ Command Line Parameters ═══ To start the debugger from the OS/2 command prompt, enter the command icsdebug and the following parameters, in the order they are listed: 1. Any debugger parameters that you want to use. 2. Name of the program you want to debug. 3. Any input parameters that you want to pass to the program. For example, type the following: icsdebug /x myprog xyz where /x represents a debugger. parameter, myprog represents your program name, and xyz represents the program parameter you want to pass to the program. The debugger parameters are: /p+ Use program profile information. /p- Do not use program profile information. /i Start the debugger in the system initialization routine so that you can debug initialization code. /c"child1.exe [child2.exe.. childn.exe]" List the child processes that you want to debug. To debug REXX DLLs, type the following: icsdebug cmd.exe /K When ICSDEBUG.EXE displays the code for CMD.EXE, do the following: 1. Set a deferred breakpoint to stop when the DLL is loaded. 2. Run the program. 3. When the breakpoint is encountered, open the desired component in the DLL and set breakpoints. To debug WorkPlace Shell objects, replace the RUNWORKPLACE line in your config.sys with the following line: SET RUNWORKPLACE=C:/OS2/CMD.EXE then type the following at an OS/2 prompt: icsdebug c:/os2/pmshell 1. Set a deferred breakpoint for the DLL containing the WPS program. 2. Run the program. 3. When the breakpoint is encountered, open the desired component in the DLL and set breakpoints. ═══ 5. Control Window ═══ Control Window The Control window is the control window of the debugger and displays during the entire debugging session. This window is divided into two panes. One pane contains the threads and the other contains the components for the program you are debugging. Threads Pane The Threads pane contains the threads and the state of the threads started by your program. To display the state of a thread, select the plus icon to the left of the thread. The following states are possible for the threads listed in the Threads box: o Enabled and runnable o Disabled and runnable o Critical and runnable o Suspended and runnable o Enabled and blocked o Disabled and blocked o Critical and blocked o Suspended and blocked. You may enable or disable the highlighted thread in the Threads list by toggling the Thread enabled choice from the Run menu. 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 executed. You can also double-click on the word Enabled in the Thread pane to change the thread status to Disabled or vice-versa. Components Pane The Components pane shows the executable files that are associated with the program you are debugging. To display a list of object files contained within an executable file, select the plus icon to the left of the executable file name. To open a source window of an object file, double-click on the object file name. To display a list of functions for a specific object file, select the plus icon to the left of the object file name. To open a source window to a specific function, double-click on the function name. You can display any component 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. You specify which components display in the Components list by selecting Options  Window Settings  Only components with debug data. When this choice is enabled, only components compiled and linked with debugging data are listed. Otherwise, all components are listed. You can also access any debugger window that is already open and hidden or minimized by selecting the menu choice that displays that window from the Windows menu. Menu Bar Summary File Start or end the debugging session and control the source windows. Breakpoints Set and manipulate breakpoints in your program. Monitors Select other debugger windows. Run Execute the program, halt execution, or enable and disable threads. Options Access various utility windows where you can set debugger options. These debugger options control the various debugger windows. Windows Display the active debugger windows. Help Display online help that compliments the information you get when you press F1 or select the Help push button. Shortcut Keys The following shortcut keys are available from the Control window: Where is execution point Ctrl+P Close debugger F3 List (Breakpoints) Ctrl+X Call stack Ctrl+K Registers Ctrl+E Storage Ctrl+G Local variables Ctrl+V Run R Halt SysRq Related Information o Program Startup Window o Source Windows o Registers Window o Call Stack Window o Local Variables Window o Monitor Expression Window o Private Monitor Window o Popup Expression Window o Storage Window o Breakpoint List Window o Window Analysis Window o Monitor Properties o Message Queue Window. ═══ 5.1. File Menu ═══ Select choices from the File menu of the Control window to start a program, find the current line, replace your current program file with a program file from another location or with a different name, restart the current debugging session, restart a previous debugging session for this program, and end the debugging session. Menu Summary Open new source Display a new source file. Locate function Open a source window to a particular function. Where is execution point Open a source window containing the next line to be executed. Program startup Start the program you want to debug after ending the current program. Close debugger End the debugging session. ═══ 5.1.1. Open New Source Choice ═══ Select the Open new source choice to open a new source file. When you select Open new source, the Open New Source window displays. ═══ 5.1.2. Locate Function Choice ═══ Select the Locate function choice to open a source window to a particular function. When you select Locate function, the Locate Function window displays. ═══ 5.1.3. Where Is Execution Point Choice ═══ Select the Where is execution point choice to locate the next line to be executed in the thread. ═══ 5.1.4. Program Startup Choice ═══ Select the Program startup choice to start a program for debugging. Program startup allows you to debug another program, while Program restart allows you to restart the current debugging session on the existing program. When you select Program startup, the Program Startup window displays. ═══ 5.1.5. Program Restart Choice ═══ Select the Program restart choice to start debugging your program again. Program restart allows you to restart the current debugging session on the existing program, while Program startup allows you to debug another program. ═══ 5.1.6. Close Debugger Choice ═══ Select the Close debugger choice to close your current debugging session. When you select Close debugger, the Close Debugger message box prompts you to confirm that you want to end the debugging session. ═══ 5.2. Breakpoints Menu ═══ Select choices from the Breakpoints menu to set breakpoints and stop the execution of your program at any point. You can set as many breakpoints as you want. Breakpoints can be set from the Control window or from the source window. When you set a breakpoint in the source window of your program, it is reflected in the other views. There are five types of breakpoints that you can set. You can customize the breakpoints using the various breakpoint windows. Menu Summary Set line Set a line breakpoint to stop the execution of your program at a specific line number. Set function Set a function breakpoint to stop the execution of your program after calling a specific function. Set address Set an address breakpoint to stop the execution of your program at a specific address. Set change address Set a change address breakpoint to stop the execution of your program when contents of memory at a given address changes. Set load occurrence Set a load occurrence breakpoint to stop the execution of your program after loading a DLL. List List the breakpoints that have been set. Delete all Delete all breakpoints. You can also set simple line breakpoints. Double-click on the following to learn how to set or clear simple line breakpoints: o Setting simple line breakpoints o Clearing simple line breakpoints. ═══ 5.2.1. Set Line Choice ═══ Select the Set line choice to stop the execution of your program at the line number you select. 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. ═══ 5.2.2. Set Function Choice ═══ Select the Set function choice to stop the execution of your program after the function that you specify is called. When you select Set function, the Set Function window displays. ═══ Set Function Window ═══ Use the Set Function window to set a function breakpoint. Program execution stops when the first instruction of the function is encountered where the breakpoint has been set. Function Entry Field Type the name of the function in the Function entry field. 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. For example, to set a function breakpoint for the function my_func, 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. Other Entry Fields For a description of types of data you can type in the other entry fields, double-click on one of the following topics: o Executable o Source o Expression o Thread o From o To o Every. 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 set a breakpoint in a DLL that is not currently loaded. If your application consists of DLLs that are dynamically loaded, use this choice to set breakpoints in DLLs which have not been loaded yet. Note: If your application consists of an EXE or preloaded DLLs, do not enable this choice. To debug preloaded DLLs, you must enable the Debug initialization code check box in the Program Startup window. 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. When a DLL is loaded and a deferred breakpoint has been set in the DLL, the state of the breakpoint changes from deferred to active. When a DLL is freed, any breakpoints that were set in the DLL change from the active state to deferred state. Refer to the Breakpoints List window for the current state of the breakpoints that have been set. If you enter an invalid source file or invalid function, the debugger will not recognize the name as invalid and will be unable to activate the breakpoint when the DLL is loaded. The invalid breakpoint will remain in the deferred state even after the DLL is loaded and program execution will not stop when the breakpoint is encountered. Push Buttons Select the appropriate push button to continue. ═══ 5.2.3. Set Address Choice ═══ Select the Set address choice to stop the execution of your program at the selected address. When you select Set address, the Set Address window displays. ═══ Set Address Window ═══ Use the Set Address window to set an address breakpoint. Program execution stops when the address is encountered where the breakpoint has been set. Address Entry Field Type the name of the address in the Address entry field. Note: The address can be either segmented or flat format. For example, to set an address breakpoint for the address 0x000A1FCC, you would type the following in the Address entry field. 0x000A1FCC The 0x is optional. or A1FCC Other Entry Fields For a description of types of data you can type in the other entry fields, double-click on any of the following topics: o Thread o Every o From o To o Expression Push Buttons Select the appropriate push button to continue. ═══ 5.2.4. Set Change Address Choice ═══ Select the Set change address choice to stop the execution of your program after the contents of memory at a given address changes. 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. Program execution stops when the contents of memory at a given address changes where the breakpoint has been set. Note: The debugger supports up to 4 enabled change address breakpoints. However, you may set as many disabled change address breakpoints as you want. Warning: If you set a change address breakpoint that is on the call stack, 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. Address or expression Entry Field Type a hexadecimal address or an expression that can be evaluated to a hexadecimal address. 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. For example, type the following in the Address or expression entry field to set a change address breakpoint for the address A1FCC. A1FCC Type the following in the Address or expression entry field to set a change address breakpoint for the expression &variable. &variable Other Entry Fields For a description of types of data you can type in the other window entry fields, double-click on one of the following topics: o Thread o From o To o Every Bytes to monitor Radio Buttons Select one of the radio buttons to specify the range of bytes. The range of bytes can be one of numbers: 1, 2, or 4. The 2-byte range must be aligned on a word boundary and the 4-byte range must be aligned on a double-word boundary. Push Buttons Select the appropriate push button to continue. Related Information o Expression Language Guidelines. ═══ 5.2.5. Set Load Occurrence Choice ═══ Select the Set load occurrence choice to stop the execution of your program when the DLL that you specify is loaded. When you select Set load occurrence, the Set Load Occurrence window displays. ═══ Expression Language Guidelines ═══ The following are the rules for evaluating data within these fields. 0x0100000 Treated as hex number (per language rules of C) 0100000 Treated as hex number (C language would treat as octal) 100000 Treated as hex number (C language would treat as decimal) 0027:0100 Treated as segmented hex address (C language would treat as octal segmented address) 0100:1002 Treated as segmented hex address (C language would treat as octal/hex segmented address) 0x287e8 Treated as hex number (per language rules of C) 287e8 Treated as hex number (C would treat as floating point 287 * 10^8) abad Treated as hex number, unless user has a variable defined with this name in the current scope. If that variable can be represented as a hexadecimal value, the value of the variable will be used. Otherwise, the hex value of 0xabad will be used. You can force this to be treated as hex value by using the prefix 0x. For example, 0xABAD. All other strings will be evaluated strictly by the language rules that apply to the part that is currently in scope. EBP + 10 Treated as value of EBP register plus decimal 10. 10 + 5 Treated as decimal 15. 10 + 6F Cannot be evaluated. Values for expressions that cannot have a hexadecimal representation will not be supported. The following error message will be displayed for cases of invalid expression. Invalid address ═══ Set Load Occurrence Window ═══ Use the Set Load Occurrence window to set a load occurrence breakpoint. Program execution stops when the DLL is encountered where the breakpoint has been set. DLL file name Entry Field Type the name of a DLL in the DLL file name entry field. Execution stops when the DLL is loaded. For example, to set a load occurrence breakpoint when the DLL MY.DLL is loaded, type the following in the DLL file name entry field: MY or MY.DLL Other Entry Fields For a description of types of data you can type in the other entry fields, double-click on one of the following topics: o Thread o From o To o Every Push Buttons Select the appropriate push button to continue. ═══ File Entry Field ═══ 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 Entry Field ═══ 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. ═══ 5.2.6. List Choice ═══ Select the List choice to list the breakpoints that you have set. When you select List, the Breakpoint List window displays. ═══ 5.2.7. Delete All Choice ═══ Select the Delete all choice to delete all the breakpoints that you have set. When you select Delete all, an information box displays for verification that you want to delete all the breakpoints. ═══ 5.3. Monitors Menu ═══ Select choices from the Monitors menu to display other debugger windows. Menu Summary Call stack Displays the Call Stack window to allow you to monitor the call stack for a particular thread. Registers Displays the Registers window to allow you to monitor registers and flags for a particular component or thread. Storage Displays the Storage window to allow you to monitor the storage in your program. Local variables Displays the local variables for the program's current function. Window analysis Displays the windows of the program in a three dimensional view. Message queue Displays the Presentation Manager messages associated with Presentation Manager applications. ═══ 5.4. Run Menu ═══ Select choices from the Run menu to execute your program, halt execution, or enable or disable threads. When you select a choice from the Run menu, the mouse pointer changes to a clock icon to indicate that the application is running and might require input to continue to the next breakpoint or end of the program. Menu Summary Run Execute the program from the current line until a breakpoint is encountered or the program ends. Halt Interrupt the program you are debugging. Program restart Restart the current debugging session. Hide debugger on Run Hides the debugger windows while your application is running. Check heap when stopping Check all memory blocks allocated or freed by the compiler debug memory management functions to make sure that overwriting has not occurred outside the bounds of allocated blocks and free memory blocks have not been overwritten. Thread enabled Enable or disable threads. ═══ 5.4.1. Thread Enabled Choice ═══ Select the Thread enabled choice so that the thread that is highlighted in the Threads box 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. ═══ 5.4.2. Run Choice ═══ Select the Run choice to execute the program, including all enabled threads, from the current line until a breakpoint is encountered or the program ends. ═══ 5.4.3. Halt Choice ═══ Select the Halt choice to interrupt the program that you are debugging. You can also access this choice by pressing SysRq (Alt+PrintScreen). ═══ 5.4.4. Hide Debugger on Run Choice ═══ Select the Hide debugger on Run choice to hide the debugger windows when your program is running. The hidden windows are restored when your program stops. For example, when a breakpoint is encountered. ═══ 5.4.5. Check Heap When Stopping Choice ═══ Select the Check heap when stopping choice to check 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. 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, a message box displays with error information. 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, the heap check is not made. To check the heap just before termination, set a breakpoint on the last line of your application. o If you are debugging a multiple thread program and a thread stops while running in compiler memory management code which is holding a memory semaphore, the heap check will not be performed. o If the stopping thread is running in 16-bit code, the heap check will not be performed. ═══ 5.5. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 5.5.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 5.5.2. Local Variables Choice ═══ Select the Local variables choice to display the local variables (static, automatic, and parameters) for the current function. The local variables display in the Local Variables window. ═══ 5.5.3. Registers Choice ═══ Select the Registers choice to display the processor and math coprocessor registers. When you select Registers, the Registers window displays. ═══ 5.5.4. Call Stack Choice ═══ Select the Call stack choice to list the active functions or procedures for the thread that is highlighted in the Threads pane of the Control window. When you select Call stack, the Call Stack window displays. ═══ 5.5.5. Storage Choice ═══ Select the Storage choice to display the contents of storage used by your program. When you select Storage, the Storage window displays. ═══ 5.5.6. Monitor Expression Choice ═══ Select the Monitor expression choice to display the Monitor Expression window. Use the Monitor Expression window to collect variables or expressions that you want to monitor. ═══ 5.5.7. Window Analysis Choice ═══ Select the Window analysis choice to display the Window Analysis window which helps you understand Presentation Manager application windows. It 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. ═══ 5.5.8. Message Queue Choice ═══ Select the Message queue choice to display the Message Queue Monitor window which displays Presentation Manager messages. ═══ 5.5.9. Breakpoints Choice ═══ Select the Breakpoints choice to list the breakpoints that you have set. When you select Breakpoints, the Breakpoints window displays. ═══ 5.6. Options Menu ═══ Select choices from the Options menu of the Control window to control how and what the debugger windows display. Menu Summary Window settings Control how the items in the Control window display. Debugger settings Display windows to control the debugger windows. ═══ 5.6.1. Window Settings Cascading Choice ═══ Select choices from the Window settings choice to modify the characteristics of the Control window. Menu Summary Only components with debug data Display components that contain debugging data. Sort threads Sort the threads in numerical order. Sort components Sort the components in alphabetical order. Titles on Enable or disable the titles from being displayed in the window. Fonts Select the font you want to use for the text displayed in the active window. ═══ 5.6.1.1. Only Components with Debug Data Choice ═══ You can specify which components display in the Components box. If this choice is enabled, a check mark symbol displays beside the Only components with debug data menu choice and only components containing debugging information are listed. If it is not, all components are listed. ═══ 5.6.1.2. Sort Threads Choice ═══ You can specify to sort the threads in numerical order from the Threads box. If this choice is enabled, a check mark symbol displays beside the sort threads choice and threads are sorted numerically. ═══ 5.6.1.3. Sort Components Choice ═══ You can specify to sort the components in alphabetical order from the Components box. If this choice is enabled, a check mark symbol displays beside the Sort components choice and components are sorted alphabetically. ═══ 5.6.1.4. Titles On Choice ═══ You can specify to display the titles or to turn the titles off in the Control window. The titles are Threads and Components. If this choice is enabled, a check mark symbol displays beside the Titles on choice and titles display. ═══ 5.6.1.5. Fonts Choice ═══ Select the Fonts choice to choose the font you want to use for the text that displays in the Control window. When you select Fonts, a Fonts window displays. ═══ 5.6.2. Debugger Settings Cascading Choice ═══ Select choices from the Debugger settings cascading choice to set various debugger options that control how the debugger windows display. These settings affect the behavior of the debugger and remain in effect for the duration of the debugging session. Menu Summary Source window properties Select the view that is to be displayed when the debugger starts and how to process the views. Monitor properties Select the settings for the variable monitor windows. PM debugging mode Set parameters that control how the debugger handles messages passed within the debugger and between other Presentation Manager applications. Default data representation Select how you want your data displayed in the monitor windows. Program profiles Enable or disable the use of program profiles, delete, or change the location where the program profiles are stored. Exception filtering Select exceptions that you want the debugger to recognize. Save window positions and sizes Save the position and sizes of all debugger windows. Autosave window positions and sizes When you enable this choice, the window positions and sizes are automatically saved when you move or resize a window. When you close the debugging session and start another session the positions and sizes that you selected are displayed in the new session. Alternatively, you may save the window positions and sizes by positioning the debugger windows on the desktop and selecting the Save window positions and sizes choice. ═══ 5.6.2.1. Source Window Properties Choice ═══ Select the Source window properties choice to set the default characteristics of the Source windows. When you select Source window properties, the Source Window Properties window displays. ═══ 5.6.2.2. Monitor Properties Choice ═══ Select the Monitor Properties choice to select the settings for monitoring variables or expressions. When you select Monitor properties, the Monitor Properties window displays. ═══ 5.6.2.3. PM Debugging Mode Choice ═══ The PM Debugging Mode choice allows to set the debugging mode to asynchronous or synchronous, and control the interaction between the program windows and PM, while the application has stopped executing. When you select PM debugging mode, the PM Debugging Mode window displays. ═══ 5.6.2.4. Default Data Representation Cascading Choice ═══ When you select Default data representation, a cascaded menu displays with language choices. This lets you change the default representation for a data type in the language that you select. ═══ 5.6.2.5. Language Choices ═══ Select a language to change the default representation of the selected data type. For example, you can change the default representation for an integer in the C language from decimal to hexadecimal. When you select System, the Default Representation window displays. ═══ 5.6.2.6. System Choice ═══ Select the System choice to change the default representation of the math coprocessor registers. This choice is language independent. When you select the System choice, the Default Representation window displays. ═══ 5.6.2.7. Save Window Positions and Sizes Choice ═══ Select the Save window positions and sizes choice to save the position and size of each type of debugger window currently open. Type refers to the different windows such as Registers, Storage, and so on. When you select this choice, the window positions are saved and any new windows will display in the saved positions. ═══ 5.6.3. Autosave Window Positions and Sizes Choice ═══ Select the Autosave window positions and sizes choice to enable automatic saving of window positions and sizes for each type of debugger window currently open. Type refers to the different windows such as Registers, Storage, and so on. When you enable this choice, the window positions and sizes are automatically saved when you move or resize a window. When you close the debugging session and start another session the positions and sizes that you selected are displayed in the new session. Alternatively, you may save the window positions and sizes by positioning the debugger windows on the desktop and selecting the Save window positions and sizes choice. ═══ 5.6.4. Exception Filtering Choice ═══ Use the Exception filtering choice to select the exceptions that you want the debugger to recognize. When you select Exception filtering, the Exception Filtering window displays. ═══ 5.6.5. Program Profiles Choice ═══ Select the Program profiles cascading choice to specify if you want to enable program profiling, delete program profiles, or change the location where the program profiles are stored. Menu Summary Enable program profiling Enable or disable the use of program profiles. Delete Delete program profiles that have been saved for a program that you have previously debugged. Change location Change the directory where all the program profiles are stored. ═══ 5.6.5.1. Enable Program Profiling Choice ═══ Select the Enable program profiling choice to enable or disable the use of program profiles. When debugging a program more than once, this will restore the breakpoints, source windows and monitors to the same state as when last debugged. When it is enabled, a check mark symbol displays. If it is disabled, a check mark symbol is not displayed. ═══ 5.6.5.2. Delete Choice ═══ Select the Delete choice to delete the program profiles which for programs that have been previously debugged. When you select Delete, the Delete window displays. ═══ 5.6.5.3. Change Location Choice ═══ Select the Change location choice to specify the directory where you want the program profiles stored. The default location for the program profiles is as follows: C:\OS2\ Where C: is your OS/2 boot drive. When you select Change location, the Change Location window displays. ═══ 5.7. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. How do I Display the debugger task help. Product information Display product information. ═══ 5.7.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 5.7.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 5.7.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 5.7.4. How Do I Choice ═══ Select the How do I choice to display the online task help. This lists tasks that you may want to do and instructions on how to complete these tasks. ═══ 5.7.5. Product Information Choice ═══ Select the Product information choice to display the product information. ═══ Shortcut Keys ═══ 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 any source window (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. ═══ 6. Source Windows ═══ Source Windows The Source window displays the source code for the program you are debugging. When you start the debugger, the Source window displays if the source file is available. If the source file is not available, the Source Filename window displays. Although, only one source window initially displays, you can display additional source windows at any time. Executable statements display in blue. You can set breakpoints or execute your program only on executable lines. Non-executable lines, such as comments, display in black. The prefix area of each source line displays a line number. If your source file contains include files, the Source window displays in a notebook format where the tabs represent the include files. Title Bar The title bar contains the name of the source file, the thread where the source file runs, and buttons that provide easy access to frequently used features. Title Bar Buttons The title bar buttons display in the title bar of the source window. Double-click on any of the following for a description of that button. Note: If you place your mouse pointer on a button in the title bar, the name of that button displays in the window title area. As you drag the mouse pointer across the buttons, the name in the window title area changes to reflect the button you are on. The buttons listed in the title bar can also be accessed from the menu items of the source windows. For example, the step buttons can be found under the Run menu. Views You can display your source in three different views. The Source view displays the source code for the program you are debugging as it was written. The Disassembly view displays the source code as assembler instructions without the symbolic information. The prefix area of each line displays the address of the assembler instruction. The Mixed view displays the source code for the component and the assembler instructions that are generated for each source line without the symbolic information. You can change from one view to another using one of the following two methods: o Select the View menu from a source window and then select the view you want displayed. o 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. Note: You can change the view priority of the source windows using the Source Window Properties window. Basic Tasks The following are tasks that can be performed from the Source window: Setting line breakpoints Double-click on the prefix area of any line to set a simple line breakpoint. For more information about breakpoints, see Breakpoints. Single stepping your program Press mouse button two to single step your program. This performs a Step over command. Scrolling to a paticular line number Allows you to scroll to a particular line number in the source code. This feature also provides the ability to set breakpoints. Select View  Scroll to line number from a source window. Selecting include files Allows you to select the include files you want to view. Include files are files that are included in your source file by a compiler directive and are considered program source files. Select View  Select include file from a source window. Monitoring and modifying variables Double-click on any variable name in your program to display that variable in a monitor window. Drag the mouse over an expression, and then double-click on the highlighted expression, to display the expression in a monitor window. The four windows for monitoring variables and expressions are Monitor expression, Private monitor, Popup expression, and Local Variables. Note: You can change the settings for monitoring variables and expressions using the Monitor Properties window. Using integration When you start the debugger from within the WorkFrame/2 environment, additional tool support is provided. A new menu item is added to the Source window called Project. This menu allows you to access other tools such as the editor, the browser, or the compiler. This feature also provides context sensitive help. This help becomes available when you select a string, using the mouse pointer, and press and hold down Ctrl+H. If you place the mouse pointer on a space in the Source window and double-click, an editor opens to the corresponding source line that you selected. Menu Bar Summary File Open a new source file, locate a function, find the current execution point, start a new debugging session or close the debugger. View Search for strings in your source file, select a different view of your program, scroll to a particular line, or change the current window to a notebook format. Breakpoints Set and manipulate breakpoints in your program. Monitors Display the other debugging windows. Run Run your program in several ways. Options Change the parameters that control how your program displays and runs. Windows Display the active debugger windows. Project Select other tools such as the editor, compiler, or browser. Help Display online help that compliments the information you get when you press F1 or select the Help push button. Shortcut Keys The following shortcut keys are available from the source views (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 Related Information o Program Startup Window o Control Window o Registers Window o Call Stack Window o Local Variables Window o Monitor Expression Window o Private Monitor Window o Popup Expression Window o Storage Window o Breakpoint List Window o Window Analysis Window o Monitor Properties o Message Queue Window o Search Path for Source Files. ═══ Step Over Button ═══ Executes the current, highlighted line in the program, but does not enter any called function. 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. ═══ Step Into Button ═══ Executes the current, highlighted line in the program and enters any called program or 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 window, 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. ═══ Step Debug Button ═══ Executes the current, highlighted line in the program. The debugger steps over any function for which debugging information is not available (for example, library and system routines), and steps into any function for which debugging information is available. ═══ Step Return Button ═══ Automatically executes the lines of code up to, and including, the return statement of the current function. ═══ Run Button ═══ Runs the program, executing all enabled threads. Control returns to the debugger when: o the program ends o execution stops at an enabled breakpoint. When the debugger is running, the run button changes to You can click on this button to halt the program execution. You can also interrupt the program you are debugging by selecting the Halt choice from the Run menu or by pressing SysRq (Alt+PrintScreen). ═══ Control Button ═══ Displays the Control window. ═══ Call Stack Button ═══ Displays the Call Stack window. ═══ Registers Button ═══ Displays the Registers window. ═══ Monitor Expression Button ═══ Displays the Monitor Expression window. ═══ Storage Button ═══ Displays a new Storage window. ═══ Breakpoints Button ═══ Displays the Breakpoints window. ═══ View Button ═══ Cycles through the available views. For example, you can change from the Source view to the Disassembly view and then to the Mixed view. ═══ 6.1. File Menu ═══ Select choices from the File menu of the source windows to start programs, find the current line, replace your current program file with a program file from another location or with a different name, restart the current debugging session, restart a previous debugging session for this program, and end the debugging session. Menu Summary Open new source Display a new source file. Locate function Open a source window to a particular function. Where is execution point Open a source window containing the next line to be executed. Program startup Start the program you want to debug after ending the current program. Close debugger Close the debugging session. ═══ 6.1.1. Source Choice ═══ Select the Source choice to display the source code for your program. The initial Source window displays the source code for the object that contains the main function to the program being debugged. If it is available, the Source window displays with the Control window when the debugging session starts. Otherwise, the Disassembly window displays. Note: You can change the order of the source window that are opened by using the Source Window Properties window. ═══ 6.1.2. Disassembly Choice ═══ Select the Disassembly choice to display the assembler instructions for your program, without symbolic information. The menu choices available in the Disassembly window are the same as for the Source window except for choices listed under the View menu. Note: You can change the order of the source window that are opened by using the Source Window Properties window. ═══ 6.1.3. Mixed Choice ═══ Select the Mixed choice to display each line of source code followed by the assembler instructions that the particular source line generates. The Mixed window displays your program as follows: o Each line of source code is prefixed by a line number, as in the Source window. o Each disassembled line is prefixed by an address, as in the Disassembly view. o Source comment lines also display. o The lines of source code are treated as comments within the lines of disassembly code. You can only set breakpoints or run your program on lines of disassembly code. Notes: 1. The Mixed window cannot be opened if the source code is not available. 2. You can change the order of the source windows that are opened by using the Source Window Properties window. ═══ 6.2. View Menu ═══ Select choices from the View menu to search for strings in the text and select a different view of your program or change the current window to a notebook format. Menu Summary Find Search for text strings in the active window. Find next Find the next occurrence of a string. Scroll to line number Scroll to a particular line or set a breakpoint on a specified line. Notebook Display the the source windows in a notebook format. Select include file Select to view the include files. Change text file Select the file name to use as the source in the current view. Source Displays the Source window. Disassembly Displays the Disassembly window. Mixed Displays the Mixed window. ═══ 6.2.1. Find Choice ═══ Select the Find choice to search for a text string in the active window. When you select Find, the Find window displays, prompting you for the text string you want to find. ═══ 6.2.1.1. Find Window ═══ To use the Find window to search for a text string: 1. Type the text string you want to search for in the Enter text: entry field. 2. Select the appropriate push button to continue. Enter text: Entry Field Type the text string you want to search for in this entry field. You can search for simple text strings that do not use wildcards (*). The search string can have: o Alphabetic and numeric characters o A maximum of 256 characters o Uppercase and lowercase characters. Case sensitive Check Box Enable this check box if you want to search for the string exactly as typed. Disable this check box to search for uppercase and lowercase characters. ═══ 6.2.2. Find Next Choice ═══ Select the Find next choice to search for the next occurrence of a text string. If you are searching in the same program component, the default is the text string you typed the last time you completed the Find window for this component. ═══ 6.2.3. Scroll to Line Number Choice ═══ Select the Scroll to line number choice from the source windows to go to a particular line in your program or set a line breakpoint. When you select Scroll to line Number, the Scroll to Line Number window displays. ═══ 6.2.3.1. Scroll to Line Number Window ═══ Use the Scroll to Line Number window to go to a specific line in your program or set a line breakpoint. Note: If the Source window is active, just type a number and the Scroll to Line Number window automatically displays. To use the Scroll to Line Number window to scroll to a specific line: 1. Type the line number you want to scroll to in the Enter line number: entry field. 2. Select the OK push button to scroll to that line. 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. ═══ 6.2.4. Notebook Choice ═══ Enable the Notebook choice to display the source windows in notebook format. Note: If you have include files in your program, the Notebook choice enables by default. You can enable or disable the Notebook choice by selecting it. When it is enabled, a check mark symbol displays. If it is disabled, a check mark symbol is not displayed. The Source and Mixed views can be displayed in a notebook. The Disassembly view cannot be displayed in a notebook. ═══ 6.2.5. Change Text File Choice ═══ Select the Change text file choice to specify the file name to use as the source in the current view. This is useful if the debugger found the incorrect source file for your program, so that you can specify the use of a different source file from a different directory. For information about how the debugger searches for source files, refer to understanding the search path. When you select Change text file, the Change text file window displays. ═══ 6.2.5.1. Change Text File Window ═══ Use the Change Text File window to replace the path name or file name of the program you are debugging with a new path name or file name. This specifies a new file name to use as the source in the current source window. This is useful if the debugger found the incorrect source file for your program, so that you can specify the use of a different source file from a different directory. To replace the file name: 1. Type the new path name or file name in the File name entry field. 2. Select the appropriate push button to continue. File name Entry Field Type the path name and file name of the program you want to replace with the program you are currently debugging. Related Information o Understanding The Search Path ═══ 6.2.6. Source Choice ═══ Select the Source choice to display the source code for your program. The initial Source window displays the source code for the object that contains the main function to the program being debugged. If it is available, the Source window displays with the Control window when the debugging session starts. Otherwise, the Disassembly window displays. Note: You can change the order of the source windows that are opened by using the Source Window Properties window. ═══ 6.2.7. Disassembly Choice ═══ Select the Disassembly choice to display the assembler instructions for your program, without symbolic information. The menu choices available in the Disassembly window are the same as for the Source window except that the Variable menu and the Change text file choice in the File menu are not available. Note: You can change the order of the source window that are opened by using the Source Window Properties window. ═══ 6.2.8. Mixed Choice ═══ Select the Mixed choice to display each line of source code followed by the assembler instructions that the particular source line generates. The Mixed window displays your program, as follows: o Each lines of source code is prefixed by its line number, as in the Source window. o Each disassembled line is prefixed by an address, as in the Disassembly view. o Source comment lines also display. o The lines of source code are treated as comments within the lines of disassembly code. You can only set breakpoints or run your program on lines of disassembly code. o The Mixed window cannot be opened if the source code is not available. Note: You can change the order of the source windows that are opened by using the Source Window Properties window. ═══ 6.2.9. Locate Function Choice ═══ Select the Locate function choice to open a source window to a particular function. When you select Locate function, the Locate Function window displays. ═══ 6.2.9.1. Locate Function Window ═══ Use the Locate Function window to open a source window to a particular function. To use the Locate Function window: 1. Type the name of the function you want to search for in the Function entry field. 2. Select the appropriate push button to continue. All executables Check Box Enable this check box to search all the executable files for the function. The debugger searches each object file for global functions that match the function name specified. If an object file contains the global function that was specified, then it will also search for any static function with the same name. Note: To search for a function in a specific executable file, disable this check box and type the name of the executable file in the Executable entry field and type 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 information. 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. 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. ═══ 6.2.10. Open New Source Choice ═══ Select the Open new source choice to open a new source file. When you select Open new source, the Open New Source window displays. ═══ 6.2.10.1. Open New Source Window ═══ Use the Open New Source window to open a new source file. To use the Open New Source window: 1. 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.CPP 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. 2. 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. 3. Select the appropriate push button to continue. All executables Check Box Enable this option if you want to search all the executable files. Disable this option to search only one executable file. Debug data only Check Box Enable this option if you want to search only the source files that contain debugging information. ═══ 6.2.11. Select Include File Choice ═══ Use the Select include file choice to select the include file you want to view. ═══ 6.2.11.1. Select Include File Window ═══ Use the Select Include File window to select the include file you want to view. To use the Select Include File window: 1. Select the include file. The include file name is highlighted. 2. Select the OK push button. The selected include file view displays. ═══ 6.2.12. Where Is Execution Point Choice ═══ Select the Where is execution point choice to locate the next line in the thread to be executed. ═══ 6.2.13. Program Startup Choice ═══ Select the Program startup choice to start a program for debugging. Program startup allows you to debug another program, while Program restart allows you to restart the current debugging session on the existing program. When you select Program startup, the Program Startup window displays. ═══ 6.2.14. Program Restart Choice ═══ Select the Program restart choice to start debugging your program again. Program restart allows you to restart the current debugging session on the existing program, while Program startup allows you to debug another program. ═══ 6.2.15. Close Debugger Choice ═══ Select the Close debugger choice to close your current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 6.3. Breakpoints Menu ═══ Select choices from the Breakpoints menu to set breakpoints and to stop the execution of your program at any point. You can set as many breakpoints as you want. Breakpoints can be set from the Control window or from a source window. When you set a breakpoint in one view of your program, it is reflected in the other appropriate views. There are five breakpoints that you can set. You can customize the breakpoints using the various breakpoint windows. Menu Summary Set line Set a line breakpoint to stop the execution of your program at a specific line number. Set function Set a function breakpoint to stop the execution of your program after calling a specific function. Set address Set an address breakpoint to stop the execution of your program at a specific address. Set change address Set a change address breakpoint to stop the execution of your program when contents of memory at a given address changes. Set load occurrence Set a load occurrence breakpoint to stop the execution of your program after loading a DLL. List List the set breakpoints. Delete all Delete all the set breakpoints. 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. ═══ 6.3.1. Set Line Choice ═══ Select the Set line choice to stop the execution of your program at the line number you select. 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. ═══ 6.3.2. Set Function Choice ═══ Select the Set function choice to stop the execution of your program after the function that you specify is called. When you select Set function, the Set Function window displays. ═══ 6.3.3. Set Address Choice ═══ Select the Set address choice to stop the execution of your program at the selected address. When you select Set address, the Set Address window displays. ═══ 6.3.4. Set Change Address Choice ═══ Select the Set change address choice to stop the execution of your program after the contents of memory at a given address changes. When you select Set change address, the Set Change Address window displays. ═══ 6.3.5. Set Load Occurrence Choice ═══ Select the Set load occurrence choice to stop the execution of your program when the DLL that you specify is loaded. When you select Set load occurrence, the Set Load Occurrence window displays. ═══ 6.3.6. List Choice ═══ Select the List choice to list the breakpoints that you have set. When you select List, the Breakpoint List window displays. ═══ 6.3.7. Delete All Choice ═══ Select the Delete all choice to delete all the breakpoints that you have set. When you select Delete all, an information box displays for verification that you want to delete all the breakpoints. ═══ 6.4. Monitors Menu ═══ Select choices from the Monitors menu to monitor expressions and variables and display other debugger windows. Menu Summary Monitor expression Displays the Monitor Expression window to allow you to type the name of the variable or expression you want to monitor. Call stack Displays the Call Stack window to allow you to monitor the call stack for a particular thread. Registers Displays the Registers window to allow you to monitor registers and flags for a particular component or thread. Storage Displays the Storage window to allow you to monitor the storage in your program. Local variables Displays the local variables for the program's current function. Window analysis Displays the windows of the program in a three dimensional view. Message queue Displays the Presentation Manager messages associated with Presentation Manager applications. ═══ 6.4.1. Popup Expression Choice ═══ Select the Popup expression choice to monitor the highlighted variable or expression in a popup expression window. When you select the Popup expression choice, the Popup Expression window displays. ═══ 6.4.2. Add to Private Monitor Choice ═══ Select the Add to private monitor choice to add the highlighted variable or expression to the Private Monitor window. To use the Add to private monitor choice: 1. Highlight the variable or expression you want to monitor by pressing and holding mouse button one on the variable and dragging the mouse pointer across the variable or expression. You can also highlight the variable by double-clicking on the variable. 2. Select the Add to private monitor choice. The variable or expression you highlighted is added to the Private Monitor window. ═══ 6.4.3. Add to Monitor Expression Choice ═══ Select the Add to monitor expression choice to add the highlighted variable or expression to the Monitor Expression window. To use the Add to monitor expression choice: 1. Highlight the variable or expression you want to monitor by pressing and holding mouse button one on the variable and dragging the mouse pointer across the variable or expression. You can also highlight the variable by double-clicking on the variable. 2. Select the Add to monitor expression choice. The variable or expression you highlighted is added to the Monitor Expression window. ═══ 6.4.4. Add to Storage Monitor Choice ═══ Select the Add to storage monitor choice to add a variable or expression to the Storage window. To add a variable or expression to the Storage window, do the following: 1. Highlight the variable or expression. 2. Select the Add to storage monitor choice. The value of whatever you highlight is evaluated and the contents found at this location is displayed. The Storage window displays with the selected variable or expression. ═══ 6.4.5. Monitor Expression Choice ═══ Select the Monitor expression choice if you want to use the keyboard to type the name of a variable or an expression you want to monitor. When you select Monitor expression, the Monitor Expression window displays. ═══ 6.4.5.1. Monitor Expression ═══ Use the Monitor Expression window to type in the expression you want to monitor. This window lists the following contextual information: o The component you are in. o The active line of the source code, which is highlighted. o The view of the program that is active. o The thread you are in. The expression language supported by the debugger is a subset of the C/C++ language. You can monitor only expressions with: o A supported operand type o A supported operator o A supported typecasting operation. To specify an expression to be monitored: 1. Type the name of the variable or expression you want to monitor in the Expression entry field. 2. Select the appropriate push button from the Add to group box for the location from where you want to monitor your expression. Note: The expression displays as specified in the Monitor Properties window. To change the default location, select Monitor properties from the Debugger settings choice from the Options menu in the source windows or the Control window. ═══ Selecting Variables with the Mouse ═══ To select a variable or expression for display using the mouse, use one of the following methods: o Point to any character within the variable name and double-click mouse button one. o Highlight the variable name or expression by pressing and holding mouse button one and dragging the mouse pointer across the variable name or expression, and then double-click mouse button one anywhere within the name. o Highlight the variable name or expression and select Add to monitor expression, Add to private monitor, or Popup expression from the Variable menu. ═══ Selecting Variables with the Mouse and Monitor Expression Window ═══ To monitor a variable or an expression using the mouse and the Monitor Expression window, use one of the two following methods: For a single variable name: 1. Highlight the variable name using either of the following methods: o Point to the variable name and click on mouse button one. o Highlight the variable by placing the mouse pointer on the beginning of the variable and dragging the mouse across the entire variable while pressing mouse button one. 2. Select Monitor expression from the Variable menu. The Monitor Expression window displays with the highlighted variable name in the Expression entry field. For an expression: 1. Highlight the expression by placing the mouse pointer on the beginning of the expression and dragging the mouse across the entire expression while pressing mouse button one. 2. Select Monitor expression from the Variable menu. The Monitor Expression window displays with the highlighted expression name in the Expression entry field. Select the appropriate push button to continue. ═══ Selecting Variables with the Keyboard ═══ To monitor a variable or expression using the keyboard: 1. Select Monitor expression from the Variable menu. The Monitor Expression window displays. 2. Type the name of the variable or expression in the Expression entry field. 3. To change the defaults that control how a variable or expression displays in a monitor or popup expression window, do the following: a. Select Monitor Properties push button to display the Monitor Properties window. b. Select OK to close the Monitor Properties window. 4. Select OK to close the Monitor Expression window. ═══ 6.5. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 6.5.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 6.5.2. Local Variables Choice ═══ Select the Local variables choice to display the local variables (static, automatic, and parameters) for the current function. When you select Local variables, the Local Variables window displays. ═══ 6.5.3. Registers Choice ═══ Select the Registers choice to display the processor and math coprocessor registers. ═══ 6.5.4. Call Stack Choice ═══ Select the Call stack choice to list the active functions or procedures for the thread that is displayed in the source window. When you select Call stack, the Call Stack window displays. ═══ 6.5.5. Private Monitor Choice ═══ Select the Private Monitor choice to display the Private Monitor window. ═══ 6.5.6. Monitor Expression Choice ═══ Select the Monitor expression choice to display the Monitor Expression window. Use the Monitor Expression window to collect variables or expressions that you want to monitor. ═══ 6.5.7. Storage Choice ═══ Select the Storage choice to display the contents of storage used by your program. When you select Storage, the Storage window displays. ═══ Using the Storage Window ═══ You can scroll through storage using the up or down arrow keys and the PageUp or PageDown keys. To update the storage contents, type over the contents displayed in the Storage window. The display is updated when an elapsed time of one second occurs after the last keystroke has been typed. The contents of all affected windows are updated for each character changed in the Storage window. To specify a new address location, type over the address field displayed in the Storage window. When an elapsed time of one second occurs after the last keystroke has been typed, the window scrolls to the appropriate storage location. ═══ 6.5.8. Window Analysis Choice ═══ Select the Window analysis choice to help you understand Presentation Manager application windows. It 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. ═══ 6.5.9. Message Queue Choice ═══ Select the Message queue choice to display the Message Queue Monitor window which displays Presentation Manager messages. ═══ 6.5.10. Breakpoints Choice ═══ Select the Breakpoints choice to list the breakpoints that you have set. When you select Breakpoints, the Breakpoints window displays. ═══ 6.5.11. Control Choice ═══ Select the Control choice to display the Control window. ═══ 6.6. Run Menu ═══ Select choices from the Run menu to control the execution of your program. You can step through your program in several ways, or you can run your program until a breakpoint is encountered or your program is ended. You can access any of the choices in the Run menu by using the shortcut keys. These keys are also listed in the Run menu. For the Step over command, you can use the mouse. When you select a choice from the Run menu, the mouse pointer changes to a clock icon to indicate that the application is running and might require input to continue to the next breakpoint or end of the program. Menu Summary Step over Execute the current line in your program. If the current line is a call, execution stops when the call completes. Step into Execute the current line in your program. If the current line is a call, execution stops at the first statement in the called function. Step debug Execute the current line in the program. The debugger steps over any function for which debugging information is not available and steps into any function for which debugging information is available. Step return Step through the current function until the return is executed. Run Execute the program from the current line until a breakpoint is encountered or the program ends. Halt Interrupt the program you are debugging. Run to location Execute your program from the current line up to the line that is highlighted with gray in the prefix area. Jump to location Change the current line in the program without executing the code between the present current line and the new current line. Hide debugger on Run Hide the debugger windows while your application is running. Check heap when stopping Check all memory blocks allocated or freed by the compiler debug memory management functions to make sure that overwriting has not occurred outside the bounds of allocated blocks and free memory blocks have not been overwritten. Thread enabled Enable or disable threads. ═══ 6.6.1. Step Over Choice ═══ 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 will execute during the step. Note: The debugger stops in a called function if it encounters a breakpoint. ═══ 6.6.2. Step Into Choice ═══ 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. All enabled threads will execute during the step. 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 window, 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. ═══ 6.6.3. Step Return Choice ═══ Select the Step return choice to automatically execute the lines of code up to, and including, the return statement of the current function. All enabled threads will execute during the step. ═══ 6.6.4. Step Debug Choice ═══ 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. All enabled threads will execute during the step. ═══ 6.6.5. Run Choice ═══ Select the Run choice to execute the program, including all enabled threads, from the current line until a breakpoint is encountered or the program ends. ═══ 6.6.6. Run to Location Choice ═══ Select the Run to Location choice 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. If a highlighted line is not executable, the run is not performed. ═══ 6.6.7. Jump to Location Choice ═══ Select the Jump to Location choice to change 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 stack and cause your program to produce unpredictable results. ═══ 6.6.8. Thread Enabled Choice ═══ Select the Thread enabled choice to execute the thread associated with the current source window, when the program runs. When a thread is enabled, a check mark symbol displays beside the Thread enabled choice. When a thread is not enabled, a check mark symbol does not display and the highlighted thread is not executed. ═══ 6.6.9. Halt Choice ═══ Select the Halt choice to interrupt the program that you are debugging. You can also access this choice by pressing SysRq (Alt+PrintScreen). ═══ 6.6.10. Hide Debugger on Run Choice ═══ Select the Hide debugger on Run choice to hide the debugger windows when your program is running. The hidden windows are restored when your program stops. For example, when a breakpoint is encountered. ═══ 6.6.11. Check Heap When Stopping Choice ═══ Select the Check heap when stopping choice to check 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. 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, a message box displays with error information. 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, the heap check is not made. To check the heap just before termination, set a breakpoint on the last line of your application. o If you are debugging a multiple thread program and a thread stops while running in compiler memory management code which is holding a memory semaphore, the heap check will not be performed. o If the stopping thread is running in 16-bit code, the heap check will not be performed. ═══ 6.7. Options Menu ═══ Select choices from the Options menu in the Source, Mixed or Disassembly source windows to control the debugger windows. Menu Summary Window Settings Select the color and font you want. Debugger settings Set various debugger options. ═══ 6.7.1. Window Settings Cascading Choice ═══ The following choices are available from the Window Settings cascading choice: Colors Change the color of various window elements. Fonts Select the font for the source window. ═══ 6.7.1.1. Colors Choice ═══ Use the Colors choice to change the color of the background and foreground (text) in the source windows. When you select Colors, the Colors window displays. ═══ 6.7.1.1.1. Colors Window ═══ Use the Colors window to change the color of the background and foreground (text) in the source windows. To change the color of the background in the source window: o Open the OS/2 Color Palette window. o Using the mouse pointer, select a color from the color palette. o Hold down mouse button two and drag the selected color into the Colors window. o Release mouse button two over the text line that represents the source window area that you want to change. o Select the Apply push button. To change the color of the foreground in the source window: o Open the OS/2 Color Palette window. o Using the mouse pointer, select a color from the color palette. o Hold down the Ctrl key and mouse button two and drag the selected color into the Colors window. o Release the Ctrl key and mouse button two over the text line that represents the source window area that you want to change. o Select the Apply push button. To continue, select the appropriate push button. Note: 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. ═══ 6.7.2. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Source windows. ═══ 6.7.2.1. Font Selection Window ═══ Use this window to change the font of the text in the current window. ----------------------------------* ═══ 6.7.3. Debugger Settings Cascading Choice ═══ Select choices from the Debugger settings cascading choice to set various debugger options that control how the debugger windows display. These settings affect the behavior of the debugger and remain in effect for the duration of the debugging session. Menu Summary Source window properties Select the view that is to be displayed when the debugger starts and how to process the views. Monitor properties Select the settings for the variable monitor windows. PM debugging mode Set parameters that control how the debugger handles messages passed within the debugger and between other Presentation Manager applications. Default data representation Select how you want your data displayed in the monitor windows. Program profiles Enable or disable the use of program profiles, delete, or change the location where the program profiles are stored. program profiles. Exception filtering Select exceptions that you want the debugger to recognize. Save window positions and sizes Saves the window positions for this debugging session. When you close the debugging session and start another session the default window position and sizes are displayed, Autosave window positions and sizes When you enable this choice, the window positions and sizes are automatically saved when you move or resize a window. When you close the debugging session and start another session the positions and sizes that you selected are displayed in the new session. Alternatively, you may save the window positions and sizes by positioning the debugger windows on the desktop and selecting the Save window positions and sizes choice. ═══ 6.7.4. Source Window Properties Choice ═══ Select the Source window properties choice to set the default characteristics of the Source windows. When you select Source window properties, the Source Window Properties window displays. ═══ 6.7.4.1. Source Window Properties Window ═══ Use the Source Window Properties Window to define: o Which source window displays when the debugger starts and when a source window first displays during a debugging session. o How to process a source window from which execution has just left. The window can: - Remain displayed - Be turned into an icon - Be discarded. New view priority Group Box Each source window displays as an icon: Source Displays the source code for the thread or component. Disassembly Displays your source code as assembler instructions without symbolic information. Mixed Displays a line of source code followed by the assembler instructions for that line of source code. When a source window opens, the New view priority indicates which source window displays, subject to the availability of the source code. You can select the order in which the source windows display. To change the order: o Press and hold mouse button two on the view icon you want to rearrange. o Drag the icon and release mouse button two when you have the icon in its new location. You can display the source views in the New view priority group box as icons or text. Select the appropriate push button to set the display mode. Old source disposition Group Box In the course of debugging, these selections allow you to control the behavior of source windows from which execution has just left. The Old source disposition controls the behavior of source windows within a thread. The dispositions that the views can take are: Keep Leaves open the source windows that contain the components and threads that you select with Display at stop. Iconize Changes into icons the views that contain the components and threads that you select with Display at stop. Discard Disposes of the views that contain the components and threads that you select with Display at stop. Display at stop Group Box You can control how many source windows are displayed at once. The choices are: Only stopping thread Keeps, iconizes, or discards all views that are not the stopping thread. All threads Keeps, iconizes, or discards the views for old components within each thread. For example, if you select Only stopping thread, the Old source disposition applies to all of the source windows except the current view of the stopping thread. If you select All threads, the Old source disposition applies only to the source windows for the components from which execution has just left within a thread. Source as notebook You can display your source window in a notebook format if there are include files in the source file. Multiple views You can choose to display more than one source window for a particular source file. The default is not to display multiple source windows. Title bar buttons Enable the Title bar buttons check box if you want the title bar buttons displayed in the window. When enabled, a check mark symbol is shown and the title bar buttons are displayed. If disabled, a check mark symbol is not shown and the title bar buttons do not display in the window. Title bar buttons help Enable the Title bar buttons help check box if you want the title bar buttons hover help displayed in the window. It displays the name of the title bar button in the title bar area whenever you place the mouse pointer on a button. If you drag the mouse pointer across the buttons, the name in the title bar area changes to reflect the button you are on. When enabled, a check mark symbol displays. If disabled, a check mark symbol is not shown and the title bar buttons help does not display in the window. Select the appropriate push button to continue. ═══ 6.7.5. Monitor Properties Choice ═══ Select the Monitor Properties choice to select the settings for monitoring variables or expressions. When you select Monitor properties, the Monitor Properties window displays. ═══ 6.7.6. Monitor Properties Window ═══ Use the Monitor Properties window to select the settings for monitoring variables or expressions. You can set the following: o Whether or not the context for variables or expressions displays in the monitor windows. o The window into which the variable or expression being monitored is placed. o Whether or not the displayed contents of the variable or expression are updated as the state of the program changes. o For popup expression windows, how long the monitor windows display. After you have selected the settings you want from this window, select one of the push buttons to continue. For a description of the settings that are available from this window, double-click on one of the following topics: o Show context o Monitor location o Enabled o Popup duration. ═══ 6.7.7. Show context Check Box ═══ Select the Show context check box to display the context for variables or expressions when they are selected for monitoring. ═══ 6.7.8. Monitor Location Group Box ═══ Choose one of the following radio buttons to select the monitor window that opens when you select a variable or expression to monitor. The selections you can make, and the corresponding windows, are as follows: Popup Display the variable or expression in a popup expression window. Private monitor Display the variable or expression in the Private Monitor window. Program monitor Display the variable or expression in the Program moniotor window. Storage monitor Display the variable or expression in the Storage window. Related Information o Using the mouse o Selecting Variables with the Mouse and Monitor o Selecting Variables with the Keyboard ═══ 6.7.9. Enabled Check Box ═══ Select the Enabled check box to update the displayed contents of variables when they are selected for monitoring. ═══ 6.7.10. Popup Duration ═══ If you select Popup from the Monitor location group box, select one of the following radio buttons to specify how long the popup expression window displays: Step/run The monitor window closes when the next step command or Run is executed. New source The monitor window closes when execution stops in a new source. Permanent This monitor window is associated with a specific source window and is closed when the associated source window is closed. ═══ 6.7.11. PM Debugging Mode Choice ═══ The PM Debugging Mode choice allows to set the debugging mode to asynchronous or synchronous, and control the interaction between the program windows and PM, while the application has stopped executing. When you select PM debugging mode, the PM Debugging Mode window displays. ═══ 6.7.11.1. PM Debugging Mode Window ═══ Use the PM Debugging Mode window to set the debugging mode to asynchronous or synchronous, and control the interaction between the program windows and PM, while the application has stopped executing. The Presentation Manager system is a message-based system. As program events are encountered by Presentation Manager programs, the programs communicate with each other by passing messages and by receiving user input through input messages. When a Presentation Manager program encounters an enabled breakpoint, the input queue can become blocked and dependent program events, or processes, can also become blocked as a result. For example, the input queue can become blocked when your program stops at a breakpoint that has been triggered by an input event. The debugger provides two modes of operation by which Presentation Manager messages can be processed while the debugger has control. Debugging mode Group Box Select one of the following Presentation Manager debugging modes: o Synchronous o Asynchronous. Program windows Group Box Select one of the following to select how you want the windows painted. No painting Radio Button Enable this option if you want none of the invalid areas of the window are repainted. Color invalid areas Radio Button The Color invalid areas option works only in asynchronous mode. Enable this option if you want the invalid areas painted in a solid fill color. The color can be changed by selecting a different color from the Invalid area color combination box. Restore Radio Button The Restore option works only in asynchronous mode. Enable this option if you want to restore the application window with the last available image of the window. The image that you can regain consists of the last available image when a step or run command ended, minus any parts of the window that were covered when the step or run command ended. The parts of the window that were covered are filled with the solid color you chose from the Invalid area color combination box. Repaint Radio Button Enable this option if you want to restore the application window with the last available image. The image that you can regain consists of the last available image when a step or run command ended minus any parts of the window that were covered when the step or run command ended. The parts of the window that were covered are filled with the solid color you chose from the Invalid area color combination box. The Repaint option differs from the Restore option. It interrupts the normal debugging process of the window as follows: o The program windows will not receive any screen interaction messages while the application is stopped. For example, the application will not receive any of the WM_MOUSEMOVE or WM_PAINT messages that were generated while the application was stopped. o An extra WM_PAINT message is generated for the program windows when execution resumes. Note: The program windows might not process the WM_PAINT message depending on where the breakpoints are set or on which step or run command was selected. Invalid area color Group Box Select the color that is to be used to repaint the invalid area of an application window. Depending on the original color of the application window, certain colors will be more appropriate for repainting. The color you choose is used when you select the Color invalid areas, Restore, or Repaint options. After you have selected the parameters you want from this window, click on the appropriate push buttons. ═══ 6.7.12. Default Data Representation Cascading Choice ═══ When you select Default data representation, a cascaded menu displays with language choices. This lets you change the default representation for a data type in the language that you select. ═══ 6.7.12.1. Language Choices ═══ Select a language to change the default representation of the selected data type. For example, you can change the default representation for an integer in the C language from decimal to hexadecimal. When you select the System choice, the Default Representation window displays. ═══ 6.7.12.2. System Choice ═══ Select the System choice to change the default representation of the math coprocessor registers. This choice is language independent. When you select the System choice, the Default Representation window displays. ═══ 6.7.12.2.1. Default Representation Window ═══ Use the Default Representation window to select how you want your data represented in the monitor windows. For example, you can change the default representation for an integer in the C language from decimal to hexadecimal. 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. Select the appropriate radio button for the data type you want. Select the appropriate push button to continue. ═══ 6.7.13. Exception Filtering Choice ═══ When you select Exception filtering, the Exception Filtering window displays. From this window, you select the exceptions that you want the debugger to recognize. ═══ 6.7.13.1. Exception Filtering Window ═══ Use the Exception Filtering window to select exceptions that you want the debugger to recognize. To highlight an exception: o Select the exception by clicking on the name. It becomes highlighted. o 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. Select the appropriate push button to continue. 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. ═══ 6.7.14. Save Window Positions and Sizes Choice ═══ Select the Save window positions and sizes choice to save the position and size of each type of debugger window currently open. Type refers to the different windows such as Registers, Storage, and so on. When you select this choice, the window positions are saved and any new windows will display in the saved positions. ═══ 6.7.15. Autosave Window Positions and Sizes Choice ═══ Select the Autosave window positions and sizes choice to enable automatic saving of window positions and sizes for each type of debugger window currently open. Type refers to the different windows such as Registers, Storage, and so on. When you enable this choice, the window positions and sizes are automatically saved when you move or resize a window. When you close the debugging session and start another session the positions and sizes that you selected are displayed in the new session. Alternatively, you may save the window positions and sizes by positioning the debugger windows on the desktop and selecting the Save window positions and sizes choice. ═══ 6.7.16. Program Profiles Choice ═══ Select the Program profiles cascading choice to specify if you want to enable program profiling, delete program profiles, or change the location where the program profiles are stored. Menu Summary Enable program profiling Enable or disable the use of program profiles. Delete Delete program profiles that have been saved for a program that you have previously debugged. Change location Change the directory where all the program profiles are stored. ═══ 6.7.16.1. Enable Program Profiling Choice ═══ Select the Enable program profiling choice to enable or disable the use of program profiles. When debugging a program more than once, this will restore the breakpoints, source windows and monitors to the same state as when last debugged. When it is enabled, a check mark symbol displays. If it is disabled, a check mark symbol is not displayed. ═══ 6.7.16.2. Change Location Choice ═══ Select the Change location choice to specify where you want the program profiles stored. The default location for the program profiles is as follows: C:\OS2\ Where C: is your OS/2 boot drive. When you select Change location, the Change Location window displays. ═══ 6.7.16.2.1. Change Location Window ═══ Use the Change Location window to specify the directory where you want the program profiles saved. The default location for the program profiles is as follows: C:\OS2\ Where C: is your OS/2 boot drive. To use the Change Location window, do the following: 1. Type the full path name of the directory where you want the debugger profile information file stored in the Path entry field. 2. Select the appropriate push button to continue. Note: Any existing program profiles will be moved to the new directory that you specified. ═══ 6.7.16.3. Delete Choice ═══ Select the Delete choice to delete the program profiles which for programs that have been previously debugged. When you select Delete, the Delete window displays. ═══ 6.7.16.3.1. Delete Window ═══ Use the Delete window to delete program profiles for a program that you have previously debugged. To delete program profiles: 1. Select the path name and file name of the program whose program profiles you want to delete. 2. Select the Delete push button. Note: You can delete program profiles to lessen the storage space required by the debugger files. ═══ 6.7.17. Control Choice ═══ Select the Control choice to display the Control window. ═══ 6.8. Project Menu ═══ When you start the debugger from within the WorkFrame/2 environment, additional tool support is provided. A new menu item is added to the Source window called Project. Select choices from the Project menu to open other tools such as an editor, browser, or the compiler. This menu is only available from the Source window. This feature also provides context sensitive help. This help becomes available when you select a string, using the mouse pointer, and press and hold down Ctrl+H. If you place the mouse pointer on a space in the Source window and double-click, an editor opens to the corresponding source line that you selected. Notes o This menu is only available if you started the debugger within the WorkFrame/2 environment. o If you are debugging a Presentation Manager application, the PM debugging mode should be asynchronous. Menu Summary Edit Display the system editor. Browse Display classes, functions, members, inheritance and include files. ═══ 6.8.1. Edit Choice ═══ Select the Edit choice to open the system editor. ═══ 6.8.2. Browser Choice ═══ Select the Browse cascading choice to view classes, functions, members, inheritance and include files. List all classes Display a list of classes. List all functions Display a list of functions. List members Display a list of class members. Graph inheritance Display an inheritance graph. Graph include files Display a graph that shows the include files. Graph classes Display a graph that shows classes. ═══ 6.8.3. List All Classes Choice ═══ Select the List all classes choice to view a list of the classes. ═══ 6.8.4. List All Functions Choice ═══ Select the List all functions choice to view a list of the functions. ═══ 6.8.5. List Members Choice ═══ Select the List members choice to view a list of the members. ═══ 6.8.6. Graph Inheritance Choice ═══ Select the Graph inheritance choice to view an inheritance graph. ═══ 6.8.7. Graph Include Files Choice ═══ Select the Graph include files choice to view a graph containing the include files. ═══ 6.8.8. Graph Classes Choice ═══ Select the Graph classes choice to view a graph containing the classes. ═══ 6.9. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. How do I Display the debugger task help. IBM VisualAge C++ for OS/2 Help Menu Choices Launches the IBM VisualAge C++ for OS/2 documentation associated with the menu item. This is only available when starting the debugger from the WorkFrame/2 environment. Product information Display product information. ═══ 6.9.1. Help Index Choice ═══ Select the Help index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 6.9.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 6.9.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 6.9.4. How do I Choice ═══ Select the How do I choice to display the online task help. This lists tasks that you may want to do and instructions on how to complete these tasks. ═══ 6.9.5. IBM VisualAge C++ for OS/2 Help Menu Choices ═══ The central portion of the Help menu is dedicated to all the online documentation that is shipped with IBM VisualAge C++ for OS/2. Making a selection from any of these cascade menus launches the IBM VisualAge C++ for OS/2 documentation associated with the menu item. You can find the same documentation in the Information folder found in the IBM VisualAge C++ for OS/2 Desktop folder. The cascade menus are organized as follows: At a Glance  Provides general information on using IBM VisualAge C++ for OS/2, such as what is new in this release, the overall tutorial, a description of all the sample programs, and answers to frequently asked questions. Using IBM VisualAge C++ for OS/2  Provides direct access to the individual sections of the User's Guide. For example, if you are using the Browser, you would look in the Browsing section for more information. How Do I... Selections  Provides access to the How Do I... information for each component of IBM VisualAge C++ for OS/2. Use How Do I... information to find out how to perform common tasks within IBM VisualAge C++ for OS/2. C/C++  Provides access to the information that is specific to programming in C and C++. Class Libraries  Provides access to the IBM VisualAge C++ for OS/2 Open Class Library documentation. Visual Programming  Provides access to the information that is specific to creating your programs visually. OS/2, PM, and Graphics  Provides access to the documentation for the key aspects of OS/2, Presentation Manager, and graphics programming. IPF, REXX, and Editing  Provides access to the IPF, REXX and Editor references. SOM and WorkPlace Shell  Provides access to the information specific to SOM and the WorkPlace Shell. Multimedia  Provides access to the information that is specific to creating multimedia applications. ═══ Product information ═══ Select the Product information choice to display the product information. ═══ 7. Registers Window ═══ Registers Window Use the Registers window to view or modify the contents of the registers monitored for your program. One set of processor registers exists for each thread. In the Registers window, floating-point registers display as floating-point decimal numbers or as hexadecimal. They are updated based on the current representation. Menu Bar Summary File End your debugging session. Options Change the font used for the text in the Registers window. Windows Display the active debugger windows. Help Display online help that compliments the information you get when you press F1 or select a Help push button. Related Information o Expression Language Guidelines ═══ 7.1. Options Menu ═══ Select the Options menu to change the fonts used for the text in the Registers window, set debugger options, and end the debugging session. Menu Summary Fonts Change the fonts for the text in the Registers window. ═══ 7.1.1. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Register window. When you select Fonts, a Fonts window displays. ═══ 7.1.2. Where Is Execution Point Choice ═══ Select the Where is execution point choice to locate the next line to be executed in the thread. ═══ 7.1.3. Save Window Positions and Sizes Choice ═══ Select the Save window positions and sizes choice to save the position of all debugger windows. When you select this choice, the window positions are saved and the windows display in the selected positions. Note: You do not need to save program profile for this choice to ═══ 7.1.4. Control Choice ═══ Select the Control choice to display the Control window. ═══ 7.1.5. Close Debugger Choice ═══ Select the Close debugger choice to close your current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 7.2. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 7.2.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 7.3. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 7.3.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 7.3.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 7.3.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 8. Call Stack Window ═══ Call Stack Window The Call Stack window lists all of the active functions for a particular thread, including Presentation Manager calls. The functions display in the order that they were called. Each Call Stack window displays call stack information for one thread only. When the state of the program changes, such as when you execute the program or you update displayed data, the Call Stack window changes to reflect the current state. You can double-click on any call stack entry to display the source code for that entry. The line that calls the next call stack entry is highlighted. The remaining call stack size shows the bytes left in the stack for the thread. Menu Bar Summary File End your debugging session. Options Select the font you want to use for the text in the Call Stack window and select the parameters that control how the items on the call stack display. Windows Display the active debugger windows. Help Display online help that compliments the information you get when you press F1 or select a Help push button. ═══ 8.1. File Menu ═══ Select the File menu choice to end your debugging session. Menu Summary Close debugger End your debugging session. ═══ 8.1.1. Close Debugger Choice ═══ Select the Close debugger choice to close your current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 8.2. Options Menu ═══ Select the Options menu choice to control how the items display in the window. Menu Summary Display style Control how the items on the call stack are displayed. Fonts Select the font you want to use for the text in the Call Stack window. ═══ 8.2.1. Display Style Choice ═══ Select the Display style choice to control how the items on the call stack display. You can select the type of information you want displayed for all of the call stack items and you can choose to display new call stack items on the top or the bottom of the stack. When you select Display style, the Display Style window displays. ═══ 8.2.1.1. Display Style Window ═══ Use the Display Style window to control how the items on the call stack display. You can select the type of descriptive information you want to display for all of the call stack items. You can also choose to display new call stack items on the top or the bottom of the stack. To change how call stack items display: 1. Select one or more of the items under Columns to select the information you want to display for each call stack entry. Each item causes a new column to be added to the Call Stack window. The following items are available: Entry No. Represents the position of the call stack item in the list. Entry level 1 is the first function invoked. Function Lists program name or the address of the function call that created the new call stack entry. Source Lists the component name that contains the function. The name displayed corresponds with a name listed in the Components list box in the Control window. Address The address represents where execution will return in that function. Recursion Lists the recursion level. 0 is the first invocation. EBP Start of the call stack frame for that function. ESP End of the call stack frame for that function. Size Size of the call stack frame for that function. 2. Select one of the following Growth direction radio buttons to determine how new items are displayed on the call stack. Up Displays new items at the top of the Call Stack window. Down Displays new items at the bottom of the Call Stack window. 3. Select one of the push buttons to continue. ═══ 8.2.2. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Call Stack window. ═══ 8.3. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 8.3.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 8.4. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or, if available, select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 8.4.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 8.4.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 8.4.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 9. Local Variables Window ═══ Local Variables Window The Local Variables window displays the local variables for the current execution point in a given thread. As execution moves from function to function, the window updates with the new local variables. Note: When your program returns from a called function, the data display options you previously selected (for example, representation) are lost. If you want to save these display options, monitor the variable or expression in a Private Monitor window, the Monitor Expression window, or a popup expression window. To monitor only specific variables or expressions, instead of all the local variables of a function, use the Monitor Expression window. Menu Bar Summary File End your debugging session. Edit Select or delete variables. Options Control how the contents of variables display. Windows Displays the active debugger windows. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. Shortcut Keys The following shortcut keys are available from the Local Variables window: Close debugger F3 Delete Delete Select all Ctrl+/ Deselect all Ctrl+\ Related Information o Monitor Properties o Monitor Expression Window o Private Monitor Window o Popup Expression Window ═══ 9.1. Edit Menu ═══ Select choices from the Edit menu to delete, select, and deselect expressions. Menu Summary Delete Delete all the selected expressions. Select all Select all expressions. Deselect all Deselect all expressions. ═══ 9.1.1. Delete Choice ═══ Select the Delete choice to delete variables or expressions that are being monitored from a monitor window. To delete a variable or expression from a monitor window: 1. Select the variable or expression with your mouse. The monitor for the variable or expression highlights. 2. Select the Delete choice from the Options menu. ═══ 9.1.2. Select All Choice ═══ Select the Select all choice to select all the expressions in the window. ═══ 9.1.3. Deselect All Choice ═══ Select the Deselect all choice to cancel the selection of all the expressions in the window. ═══ 9.1.4. Where Is Execution Point Choice ═══ Select the Where is execution point choice to locate the next line to be executed in the thread. ═══ 9.1.5. Close Debugger Choice ═══ Select the Close debugger choice to close the current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 9.2. Options Menu ═══ Select choices from the Options menu to control how the contents of variables display and to set the debugger options. Menu Summary Representation Display the contents of a monitored variable in a different format. Show context Display the contextual information for all selected expressions. Hide context Prevent the display of contextual information for all selected expressions. Fonts Select the font you want to use for the text in the Local Variables window. ═══ 9.2.1. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Local Variables window. ═══ 9.2.2. Representation Cascading Choice ═══ Select the Representation cascading choice to display the contents of the variable in a new representation. The types of representation that display on the menu depend on the data type of the variable you are monitoring. The following are possible representations: Hexadecimal Displays the contents of the monitored variable in hexadecimal notation. Decimal Displays the contents of the monitored variable in decimal notation. String Displays the contents of the monitored variable as a character string. Hexadecimal pointer Displays the contents of the monitored variable as a hexadecimal pointer. Decimal pointer Displays the contents of the monitored variable as a decimal pointer. Array Displays the contents of the monitored variable as an array. Floating point Displays the contents of the monitored variable in floating-point notation. Character Displays the contents of the monitored variable in character form. Note: Floating point registers or variables display as either a floating-point decimal number or as a hexadecimal string. However, they cannot be updated with a hexadecimal string that represents a floating-point number. If you need to update a floating-point variable with a hexadecimal representation of a floating-point number, you must step through the Disassembly window to see when the variable loads into a register and then change the value in the Registers window. ═══ 9.2.3. Representations ═══ Select the Hexadecimal choice to display the contents of a variable that is being monitored in hexadecimal notation. Select the Decimal choice to display the contents of a variable that is being monitored in decimal notation. Select the String choice to display the contents of a monitored variable as a character string. Select the Hexadecimal pointer choice to display the contents of a monitored variable as a hexadecimal pointer. Select the Decimal pointer choice to display the contents of a monitored variable as a decimal pointer. Select the Array choice to display the contents of a monitored variable as an array. Select the Floating point choice to display the contents of a monitored variable in floating-point notation. Select the Character choice to display the contents of a monitored variable as a character. ═══ 9.2.4. Show Context Choice ═══ Select the Show context choice to display the contextual information for the variable you are monitoring. The following information displays: o Source o File o Line o Thread. ═══ 9.2.5. Hide Context Choice ═══ Select the Hide context choice to hide the contextual information for the variable you are monitoring. ═══ 9.2.6. Save Window Positions and Sizes Choice ═══ Select the Save window positions and sizes choice to save the position of all debugger windows. When you select this choice, the window positions are saved and the windows display in the selected positions. Note: You do not need to save program profile for this choice to ═══ 9.2.7. Control Choice ═══ Select the Control choice to display the Control window. ═══ 9.3. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 9.3.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 9.4. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 9.4.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 9.4.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 9.4.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 10. Program Monitor Window ═══ Program Monitor Window Use the Program Monitor window to collect variables or expressions that you want to monitor. This window is not associated with any specific source window and remains open at all times unless you close it. You can select the variables or expressions you want to display from the source window by: o Using the mouse o Using the mouse and monitor expression window o Using the keyboard. You must select an expression with a valid: o Operand type o Operator o Typecasting operation. Menu Bar Summary File End your debugging session. Edit Select or delete monitors. Options Modify the style of monitoring and the presentation of variables and expressions. Windows Displays the active debugger windows. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. Related Information o Using the Variable Monitors o Local Variables Window o Monitor Properties o Private Monitor Window ═══ 10.1. File Menu ═══ Select the File menu choice to end your debugging session. Menu Summary Close debugger End your debugging session. ═══ 10.2. Edit Menu ═══ Select choices from the Edit menu to delete, select, and deselect expressions. Menu Summary Delete Delete all of the selected data items that are being monitored. Delete all Delete all the expressions and no longer monitor their values in this window, Select all Select all expressions. Selected expressions may be controlled by using the Optionsmenu. For example, by selecting one or more expressions, you can change the representation for all the selected expressions at one time. Deselect all Deselect all expressions. Close debugger Close the debugging session. ═══ 10.2.1. Delete Choice ═══ Select the Delete choice to delete variables or expressions that are being monitored from a monitor window. To delete a variable or expression from a monitor window: 1. Select the variable or expression with your mouse. The monitor for the variable or expression highlights. 2. Select the Delete choice from the Options menu. ═══ 10.2.2. Delete All Choice ═══ Select the Delete all choice to delete all the variables or expressions that are being monitored from a monitor window. To delete the variables or expressions from a monitor window, select the Delete all choice from the Options menu. ═══ 10.2.3. Select All Choice ═══ Select the Select all choice to select all the expressions in the window. Selected expressions may be controlled by using the Options menu. For example, by selecting one or more expressions, you can change the representation for all the selected expressions at one time. ═══ 10.2.4. Deselect All Choice ═══ Select the Deselect all choice to cancel the selection of all the expressions in the window. ═══ 10.2.5. Close Debugger Choice ═══ Select the Close debugger choice to close the current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 10.3. Options Menu ═══ Select choices from the Options menu to change the representation of a variable or expression, delete a variable or expression from the Monitor Expression window, control the updating of the displayed contents, display context, and change the font for the text in this window. Menu Summary Fonts Select the font for the text in the Monitor Expression window. Representation Display the contents of a monitored variable or expression in a different representation. Enable Displays the contents of a variable or expression as it updates. Disable Prevent the displayed contents of a variable or expression from updating. Show context Display the contextual information for a variable or expression being monitored. Hide context Prevent the contextual information for a monitored variable or expression from displaying. Close debugger Close the debugging session. ═══ 10.3.1. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Program Monitor window. ═══ Representation Cascading Choice ═══ Select the Representation cascading choice to display the contents of the variable in a new representation. The types of representation that display on the menu depend on the data type of the variable you are monitoring. The following are possible representations: Hexadecimal Displays the contents of the monitored variable in hexadecimal notation. Decimal Displays the contents of the monitored variable in decimal notation. String Displays the contents of the monitored variable as a character string. Hexadecimal pointer Displays the contents of the monitored variable as a hexadecimal pointer. Decimal pointer Displays the contents of the monitored variable as a decimal pointer. Array Displays the contents of the monitored variable as an array. Floating point Displays the contents of the monitored variable in floating-point notation. Character Displays the contents of the monitored variable in character form. Note: Floating point registers or variables display as either a floating-point decimal number or as a hexadecimal string. However, they cannot be updated with a hexadecimal string that represents a floating-point number. If you need to update a floating-point variable with a hexadecimal representation of a floating-point number, you must step through the Disassembly window to see when the variable loads into a register and then changes the value in the Registers window. ═══ 10.3.2. Enable Choice ═══ Select the Enable choice to have the displayed contents of a variable or expression updated as the state of the program changes. ═══ 10.3.3. Disable Choice ═══ Select the Disable choice to prevent the displayed contents of a variable or expression from updating as the state of the program changes. ═══ 10.3.4. Show Context Choice ═══ Select the Show context choice to display the contextual information for the variable you are monitoring. The following information displays: o Source o File o Line o Thread. ═══ 10.3.5. Hide Context Choice ═══ Select the Hide context choice to hide the contextual information for the variable you are monitoring. ═══ 10.3.6. Save Window Positions and Sizes Choice ═══ Select the Save window positions and sizes choice to save the position of all debugger windows. When you select this choice, the window positions are saved and the windows display in the selected positions. Note: You do not need to save program profile for this choice to ═══ 10.3.7. Control Choice ═══ Select the Control choice to display the Control window. ═══ 10.4. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 10.4.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 10.5. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 10.5.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 10.5.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 10.5.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 11. Private Monitor Window ═══ Private Monitor Window Use the Private Monitor window to collect variables or expressions that you want to monitor. This window is associated with a specific source window and is closed when the associated source window is closed. You can select the variables or expressions you want to display from a window: o Using the mouse o Using the mouse and the Monitor window o Using the keyboard. You must select an expression with a valid: o Operand type o Operator o Typecasting operation. Menu Bar Summary Edit Delete, select, and deselect expressions. Options Modify the style of monitoring and the presentation of variables and expressions. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. Related Information o Using the Variable Monitors o Local Variables Window o Monitor Properties o Monitor Expression Window ═══ 11.1. Edit Menu ═══ Select choices from the Edit menu to delete, select, and deselect expressions. Menu Summary Delete Delete a selected data item that is being monitored. Delete all Delete all the expressions. Select all Select all expressions. Deselect all Deselect all expressions. ═══ 11.1.1. Delete Choice ═══ Select the Delete choice to delete variables or expressions that are being monitored from a monitor window. To delete a variable or expression from a monitor window: 1. Select the variable or expression with your mouse. The monitor for the variable or expression highlights. 2. Select the Delete choice. ═══ 11.1.2. Delete All Choice ═══ Select the Delete all choice to delete all the variables or expressions that are being monitored from a monitor window. To delete the variables or expressions from a monitor window, select the Delete all choice. ═══ 11.1.3. Select All Choice ═══ Select the Select all choice to select all the expressions in the window. ═══ 11.1.4. Deselect All Choice ═══ Select the Deselect all choice to cancel the selection of all the expressions in the window. ═══ 11.1.5. Where Is Execution Point Choice ═══ Select the Where is execution point choice to locate the next line to be executed in the thread. ═══ 11.2. Options Menu ═══ Select choices from the Options menu to change the representation of a variable or expression, delete a variable or expression from the Private Monitor window, control the updating of the displayed contents, display context, and change the font for the text in this window. Menu Summary Fonts Select the font for the text in the Private Monitor window. Representation Display the contents of a monitored variable or expression in a different representation. Enable Displays the contents of a variable or expression as it updates. Disable Prevent the displayed contents of a variable or expression from updating. Show context Display the contextual information for a variable or expression being monitored. Hide context Prevent the contextual information for a monitored variable or expression from displaying. ═══ 11.2.1. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Private Monitor window. ═══ Representation Cascading Choice ═══ Select the Representation cascading choice to display the contents of the variable in a new representation. The types of representation that display on the menu depend on the data type of the variable you are monitoring. The following are possible representations: Hexadecimal Displays the contents of the monitored variable in hexadecimal notation. Decimal Displays the contents of the monitored variable in decimal notation. String Displays the contents of the monitored variable as a character string. Hexadecimal pointer Displays the contents of the monitored variable as a hexadecimal pointer. Decimal pointer Displays the contents of the monitored variable as a decimal pointer. Array Displays the contents of the monitored variable as an array. Floating point Displays the contents of the monitored variable in floating-point notation. Character Displays the contents of the monitored variable in character form. Note: Floating point registers or variables display as either a floating-point decimal number or as a hexadecimal string. However, they cannot be updated with a hexadecimal string that represents a floating-point number. If you need to update a floating-point variable with a hexadecimal representation of a floating-point number, you must step through the Disassembly window to see when the variable loads into a register and then changes the value in the Registers window. ═══ 11.2.2. Enable Choice ═══ Select the Enable choice to have the displayed contents of a variable or expression updated as the state of the program changes. ═══ 11.2.3. Disable Choice ═══ Select the Disable choice to prevent the displayed contents of a variable or expression from updating as the state of the program changes. ═══ 11.2.4. Show Context Choice ═══ Select the Show context choice to display the contextual information for the variable you are monitoring. The following information displays: o Source o File o Line o Thread. ═══ 11.2.5. Hide Context Choice ═══ Select the Hide context choice to hide the contextual information for the variable you are monitoring. ═══ 11.3. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 11.3.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 11.3.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 11.3.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 12. Popup Expression Window ═══ Popup Expression Window The Popup Expression window displays the variable or expression you select for monitoring. It is associated with a specific source window and is closed when the associated window is closed. You can select the variables or expressions you want to display: o Using the mouse o Using the mouse and the Monitor window o Using the keyboard. You must select an expression with a valid: o Operand type o Operator o Typecasting operation. Menu Bar Summary Options Transfer a variable to the Private Monitor or the Monitor Expression window, select how long to monitor a variable, and control how the contents of the variable display. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. Related Information o Local Variables Window o Monitor Properties o Monitor Expression Window o Private Monitor Window ═══ 12.1. Edit Menu ═══ Select choices from the Edit menu to copy and place selected items to the clipboard. Menu Bar Summary ═══ 12.1.1. Where Is Execution Point Choice ═══ Select the Where is execution point choice to locate the next line to be executed in the thread. ═══ 12.2. Options Menu ═══ The Options menu controls how the contents of the monitored variable display, updates the displayed contents, how long the Popup Expression window remains open, and the window to which you can transfer the variable. Menu Summary Fonts Choose the font for the text in the Popup Expression window. Representation Change the representation of the displayed contents. Enabled Control the updating of the displayed contents. Show context Display the contextual information for a variable. Duration Select when the Popup Expression window closes. Transfer to Transfer the variable to the Monitor Expression window or the Private Monitor window. ═══ 12.2.1. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Popup Expression window. ═══ Representation Cascading Choice ═══ Select the Representation cascading choice to display the contents of the variable in a new representation. The types of representation that display on the menu depend on the data type of the variable you are monitoring. The following are possible representations: Hexadecimal Displays the contents of the monitored variable in hexadecimal notation. Decimal Displays the contents of the monitored variable in decimal notation. String Displays the contents of the monitored variable as a character string. Hexadecimal pointer Displays the contents of the monitored variable as a hexadecimal pointer. Decimal pointer Displays the contents of the monitored variable as a decimal pointer. Array Displays the contents of the monitored variable as an array. Floating point Displays the contents of the monitored variable in floating-point notation. Character Displays the contents of the monitored variable in character form. Note: Floating point registers or variables display as either a floating-point decimal number or as a hexadecimal string. However, they cannot be updated with a hexadecimal string that represents a floating-point number. If you need to update a floating-point variable with a hexadecimal representation of a floating-point number, you must step through the Disassembly window to see when the variable loads into a register and then changes the value in the Registers window. ═══ 12.2.2. Enabled Choice ═══ Select the Enabled choice to update the displayed value of the variables or expressions you are monitoring as the state of the program changes. The Enabled choice is selected when check mark symbol is displayed. To disable the variable, select the Enabled menu choice again, to remove the check mark symbol. ═══ 12.2.3. Show Context Choice ═══ Select the Show context choice to display contextual information for the variables you are monitoring. The following information displays: o Source o File o Line o Thread. The Show context choice is selected when check mark symbol displays. To hide the contextual information, select the Show context choice again to remove check mark symbol. ═══ 12.2.4. Duration Choice ═══ Select the Duration choice to set the conditions under which the Popup Expression window closes. Menu Summary Step/run Closes the monitor window when the next step command or Run executes. New source Closes the monitor window when the debugger enters a new object file. Permanent Keeps the monitor window open for the remainder of the debugging session. ═══ 12.2.4.1. Step/Run Choice ═══ Select the Step/Run choice to close the Popup Expression window the next time a step command or Run executes. ═══ 12.2.4.2. New Source Choice ═══ Select the New source choice to close the Popup Expression window when the current line moves to a different part of the program. ═══ 12.2.4.3. Permanent Choice ═══ Select the Permanent choice to cause the Popup Expression window to remain open for the remainder of the debugging session. ═══ 12.2.5. Transfer to Choice ═══ Select the Transfer to choice to move the variable or expression you are monitoring to the Private Monitor or Monitor Expression window. Any variable or expression can be transferred either to the Private Monitor window or to the Monitor Expression window. It does not matter whether the variable or expression is used throughout the program. The Private Monitor window, however, is a secondary window to the source window for which it was opened. It closes when its associated source window closes. You should, therefore, monitor local variables in the Private Monitor window, and monitor global variables in the Monitor Expression window. Menu Summary Private monitor Move the variable or expression you are monitoring to the Private Monitor window. Monitor expression Move the variable or expression you are monitoring to the Monitor Expression window. Storage Monitor the storage in your program. ═══ 12.2.5.1. Private Monitor Choice ═══ Select the Private Monitor choice to move the variable or expression you are monitoring to the Private Monitor window. ═══ 12.2.5.2. Monitor Expression Choice ═══ Select the Monitor expression choice to display the Monitor Expression window. Use the Monitor Expression window to collect variables or expressions that you want to monitor. ═══ 12.2.5.3. Storage Choice ═══ Select the Storage choice to display the Storage window. Use this window to update the storage contents. ═══ 12.3. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 12.3.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 12.3.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 12.3.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ Using the Variable Monitors ═══ After you have selected a variable or expression for monitoring, you can: o Use the data manipulation icons o Use the keyboard to move around a monitor o Enable or disable monitors o Display context o Change the value of a variable o Change the representation of a variable or expression. ═══ Keyboard Sequences ═══ You can use various combinations of keys to move around the monitor windows. The key combinations you can use and the functions they provide are: Action Key Sequence Alt+ Move to the next monitor. Alt+ Move to the previous monitor. Tab Move to the next monitor component. (The cursor moves in a circular fashion from component to component. The monitor, itself, is included in the circular path.) BackTab Move to the previous monitor component. Alt+ Dereference a highlighted pointer. Enter Open or close data structures (structures or arrays). Alt+PageUp, Alt+PageDown Scroll through the monitor. ═══ Enabling and Disabling Monitors ═══ You can enable and disable monitors. When enabled, the monitor updates the stop value of the program to actual value in storage. However, a disabled monitor suspends this updating and reflects the stop value or the value held when the monitor was disabled. You cannot change the value of a disabled monitor. When you enable a disabled monitor, the current value displays. ═══ Displaying Context ═══ Monitors display the data value in their context. The context consists of: o Source o File o Line o Thread. ═══ Changing the Value of a Variable ═══ You can change the value of a variable or expression that displays in a monitor. To change the value, do the following: 1. Select the variable or expression with your mouse or the Tab key. 2. Type in the new value. 3. Press Enter (or select another part of the debugger). ═══ Changing the Representation ═══ To change the representation, do the following: 1. Select the expression. 2. Select an alternate representation from the Options  Default data representation choice. The new representation takes effect immediately. You 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. ═══ Supported Expression Operands ═══ You can monitor an expression that uses the following types of operands only: Operand Definition Variable A variable used in your program. Constant The constant can be one of the following types: o Fixed or floating-point constant. Note: The largest floating-point constant is 1.8E308. The smallest floating-point is 2.23E-308. o A string constant, enclosed in quotation marks (" ") o A character constant, enclosed in single quote marks (' ') o Segment:Offset address specification (0000:0000) When you are specifying a segment offset address for monitoring in a variable monitor window, specify the offset address in the following format: 0x0000:0 Registers One of the following register names: AX, BX, CX, DX, SP, BP, SI, DI, AL, BL, CL, DL, AH, BH, CH, DH, EAX, EBX, ECX, EDX, ESP, EBP, ESI, EDI, EIP, CS, DS, ES, FS, GS, SS, EFLAGS. One of the following floating-point register names: ST0 through ST7, FPCW, FPSW, FPTW, FPEIP, FPCS, FPEDP, FPDS. In the case of conflicting names, the program variable names take precedence over the register names. For conversions that are done automatically when the registers display in mixed-mode expressions, general purpose registers are treated as unsigned arithmetic items with a length appropriate to the register. For example, EAX is 32-bits, AX is 16-bits, and AL is 8-bits. If you monitor an enumerated variable, a comment displays to the right of the value. If the value of the variable matches one of the enumerated types, the comment contains the name of the first enumerated type that matches the value of the variable. If the length of the enumerated name does not fit in the monitor, the contents display as an empty entry field. The comment (empty or not) lets you distinguish between a valid enumerated value and an invalid value. An invalid value does not have a comment to the right of the value. You can not update an enumerated variable by entering an enumerated type. You must enter a value or expression. If the value is a valid enumerated value, the comment to the right of the value updates. Bit fields are supported for C/C++ compiled code only. You can display and update bit fields, but you cannot use them in expressions. You cannot look at variables that have been defined using the define preprocessor directive. ═══ Supported Expression Operators ═══ You can monitor an expression that uses the following operators only: Operator Coded as Global scope resolution ::a Class scope resolution a::b Subscripting a[b] Member selection a.b or a->b Size sizeof a or sizeof (type) Logical not !a One's complement ~a Unary minus -a Unary plus +a Dereference *a Type cast (type) a Multiply a * b Divide a / b Modulo a % b Add a + b Subtract a - b Left shift a << b Right shift a >> b Less than a < b Greater than a > b Less than or equal to a <= b Greater than or equal to a >= b Equal a == b Not equal a != b Bitwise AND a & b Bitwise OR a | b Bitwise exclusive OR a ^ b Logical AND a && b Logical OR a || b ═══ Supported Data Types ═══ You can monitor an expression that uses the following typecasting operations only: o 8-bit signed byte o 8-bit unsigned byte o 16-bit signed integer o 16-bit unsigned integer o 32-bit signed integer o 32-bit unsigned integer o 32-bit floating-point o 64-bit floating-point o 80-bit floating-point o Pointers o User-defined types. These data types include int, short, char and so on. ═══ 12.3.4. Using the Data Manipulation Icons ═══ You can select any of the following icons from any monitor window, such as Monitor Expression, Private Monitor, Popup Expression or Local Variables, to manipulate the data parts of variables: Expands the contracted parts of an array. Expands the contracted parts of a structure. Expands the contracted parts of a class. Contracts the parts of an expanded array, structure or class. Displays the object referenced by a pointer in a new monitor. The four windows to monitor variables and expressions are: o Monitor Expression o Private Monitor o Popup Expression o Local Variables. ═══ 13. Storage Window ═══ Storage Window Use the Storage window to view and update the contents of the storage used by your program. The following storage data displays in the Storage window: o Fields for the displayed addresses. You may select one of the following storage models for the addresses that display: - 16:16 (segmented) storage addresses - Flat storage model addresses - Both 16:16 and flat storage model addresses. o Fields for the data storage contents. Storage can be displayed in various styles. However, you can display only one storage style at a time. o Titles for the displayed addresses and storage content fields. You can open multiple storage windows to view different storage locations at once. When the state of your program changes, the contents of the Storage window updates to reflect the change. To scroll through memory, use one of the following methods: o Scroll bars o Up and Down arrow keys o PageUp and PageDown keys. The address of the cursor displays in the title bar of the Storage window. You can update the contents of storage or view the contents of storage at a new address location. Menu Bar Summary File End your debugging session. Options Set options that control how the storage content and addresses display. Windows Displays the active debugger windows. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. Double-click on one of the following topics to find out how to update the contents of storage or specify a new address location: Related Information o Updating Storage o Specifying an Address Location o Expression Language Guidelines ═══ 13.1. Options Menu ═══ Select choices from the Options menu to control how the storage contents and addresses display, control the display of the storage window control attributes, and end your debugging session. Menu Summary Monitor expression Type the name of the variable or expression you want to monitor. Display style Select the display format for the storage contents and addresses, and change the columns per line that display. Fonts Change the font used for text in the Storage window. ═══ 13.1.1. Window Settings Cascading Choice ═══ Select the Window settings cascaded choice to change the context and address style of the Storage window. Menu Summary Display style Select the display format for the storage contents and addresses, and change the columns per line that display. Fonts Change the font used for text in the Storage window. ═══ 13.1.1.1. Display Style Choice ═══ Select the Display style choice to display the format for the storage contents and storage addresses, and change the columns per line that display. You can select from several storage display styles. When you select Display style, the Display Style window displays. ═══ 13.1.1.1.1. Display Style Window ═══ Use the Display Style window to select the parameters that control how the storage contents display and set how the storage addresses display. Content Style Select how you want the storage contents displayed. You can select from several storage display styles. To select the storage content style: 1. Scroll to the content style you want. 2. Select the content style. 3. The style becomes highlighted. Address Style Select how you want the address style displayed. To select an address style: 1. Scroll to the address style you want. 2. Select the address style. 3. The address style becomes highlighted. Columns per line Select the number of columns per line you want displayed in the Storage window. Use the Up or Down arrow keys to select the number of columns you want displayed in the Storage window. The available number of columns per line are 1-16. Column titles Select this check box to display the titles of the columns in the Storage window. ═══ 13.1.2. Monitor Expression Choice ═══ Select the Monitor expression choice to type in the expression or variable that you want to monitor. When you select Monitor expression, the Monitor Expression In Storage window displays. ═══ 13.1.2.1. Monitor Expression In Storage Window ═══ Use the Monitor Expression In Storage window to type in the address or expression you want to monitor. To specify an expression: 1. Type the name of the variable or expression you want to monitor in the Address or Expression entry field. You must select an expression with: o A valid operand type o A valid operator o A valid typecasting operation To specify an address: 1. Type the name of the hexadecimal address you want to monitor in the Address or Expression entry field. The expression evaluator used is based on the context. For example if you display the Storage window by selecting the Monitor expression choice from the Monitors menu, the evaluator used is based on the context in the Monitor Expression window. However, if you display the Storage window first and then select the Monitor expression choice from the Options menu of the Storage window, the evaluator used is based on the context of the stopping thread. Note: You cannot look at variables that have been defined using the define preprocessor directive. If the variable is not in scope when the monitor is opened, the default address is displayed. If the variable goes out of scope, the address is changed to a hex constant. If you enable the Enabled monitor check box, the monitor is updated to reflect the actual value in storage once the program stops. However, a disabled monitor suspends the updating of the storage monitor and the monitor remains the same value as when the monitor was disabled. Related Information o Expression Language Guidelines. ═══ 13.1.2.2. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Storage window. ═══ 13.1.3. Control Choice ═══ Select the Control choice to display the Control window. ═══ 13.1.4. Save Debugger Window Position Choice ═══ Select the Save window positions and sizes choice to save the position of all debugger windows. When you select this choice, the window positions are saved and the windows display in the selected positions. Note: You do not need to save program profile for this choice to ═══ 13.1.5. Close Debugger Choice ═══ Select the Close debugger choice to close the current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 13.2. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 13.2.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 13.3. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 13.3.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 13.3.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 13.3.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ Storage Display Styles ═══ You can display storage content in the following value styles: o Hexadecimal and character text o Character text o 16-bit integer o 16-bit unsigned integer o 16-bit integer in hexadecimal (byte reversed) o 32-bit integer o 32-bit unsigned integer o 32-bit integer in hexadecimal (byte reversed) o 32-bit floating-point o 64-bit floating-point o 80-bit floating-point o 16-bit near pointers o 16:16-bit far pointers o 32-bit flat pointers. You can display storage in the following address styles: o Flat and 16:16 o Flat only o 16:16 only. You can also change the number of columns per line that display. This number varies depending on the content style you have selected. ═══ Updating Storage ═══ To update the contents of storage in the Storage window, 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. ═══ Specifying an Address Location ═══ To view the storage at a different address, double-click on the address which causes a Multiple Line Entry (MLE) field to display. Type the new address in the MLE field. You can choose to update either the Flat address field or the 16:16 (segmented) address field. The Storage window scrolls to the appropriate address. ═══ 14. Breakpoint List Window ═══ Breakpoint List Window Use the Breakpoint List window to display a list of the breakpoints that have been set. The following information is also provided for each breakpoint. o The enablement state o The type of breakpoint o The position of the breakpoint o The conditions under which the breakpoint is activated. Menu Bar Summary File End the debugging session. Edit Delete, disable, or modify breakpoints. Set Set and manipulate breakpoints in your program. Options Control how items are displayed, change the font and sort items. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. Related Information o Breakpoints Menu o Sort Window ═══ 14.1. File Menu ═══ Select the choice from the File menu of the Breakpoint window to end the debugging session. Menu Summary Close debugger End the debugging session. ═══ 14.1.1. Close Debugger Choice ═══ Select the Close debugger choice to close your current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 14.2. Edit Menu ═══ Select choices from the Edit menu to delete breakpoints, disable set breakpoints, and modify set breakpoints. Menu Bar Summary Delete Delete a breakpoint. Disable Disable a breakpoint. Modify Modify a breakpoint. Delete all Deletes all breakpoints. ═══ 14.2.1. Delete Choice ═══ Deletes any highlighted breakpoints in the Breakpoint List window. To delete a breakpoint: 1. Highlight the breakpoint you want to delete. 2. Select the Delete choice. The breakpoint is deleted. ═══ 14.2.2. Delete All Choice ═══ Deletes all breakpoints that are shown in the Breakpoint List window. ═══ 14.2.3. Disable Choice ═══ Select the Disable choice to keep the breakpoint set but not effective. This allows your program to run and not stop when the breakpoint is encountered. To disable a breakpoint: 1. Highlight the breakpoint you want to disable. 2. Select the Disable choice. The breakpoint becomes disabled. ═══ 14.2.4. Modify Choice ═══ Use the Modify choice to change the breakpoints that have been set in your program. To modify a breakpoint: 1. Highlight the breakpoint you want to change. 2. Select the Modify choice. The breakpoint window that represents the type of breakpoint displays. 3. Make the appropriate changes to the entry fields. 4. Select the OK push button to accept your changes and close the window. If you want to make other changes, select the Set push button to accept the changes and keep the window open. ═══ 14.3. Set Menu ═══ Select choices from the Set menu to set breakpoints and to stop the execution of your program at any point. You can set as many breakpoints as you want. Breakpoints can be set from the Control window or from a source window. When you set a breakpoint in one view of your program, it is reflected in the other appropriate views. There are five types of breakpoints that you can set. You can customize the breakpoints using the various breakpoint windows. Menu Summary Line... Set a line breakpoint to stop the execution of your program at a specific line number. Function... Set a function breakpoint to stop the execution of your program after calling a specific function. Address... Set an address breakpoint to stop the execution of your program at a specific address. Change address... Set a change address breakpoint to stop the execution of your program when contents of memory at a given address changes. Load occurrence... Set a load occurrence breakpoint to stop the execution of your program after loading a DLL. 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. ═══ 14.3.1. Address Choice ═══ Select the Address choice to stop the execution of your program at the selected address. When you select Address, the Set Address window displays. ═══ 14.3.2. Change Address Choice ═══ Select the Change address choice to stop the execution of your program after the contents of memory at a given address changes. When you select Change address, the Set Change Address window displays. ═══ 14.3.3. Function Choice ═══ Select the Function choice to stop the execution of your program after the function that you specify is called. When you select Function, the Set Function window displays. ═══ 14.3.4. Line Choice ═══ Select the Line choice to stop the execution of your program at the line number you select. When you select 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. ═══ 14.3.5. Load Occurrence Choice ═══ Select the Load Occurrence choice to stop the execution of your program after the DLL that you specify is loaded. When you select Load Occurrence, the Set Load Occurrence window displays. ═══ 14.4. Options Menu ═══ Select choices from the Options menu to control which items are displayed, change the font, or sort items in the window. Sort Sort the breakpoints. Display style Choose how the breakpoints display. Fonts Choose the font for the active window. ═══ 14.4.1. Display Style Choice ═══ Select the Display style choice to select the characteristics of the breakpoint you want displayed. When you select Display style, the Display Style window displays. ═══ 14.4.2. Sort Choice ═══ Select the Sort choice to sort the breakpoints by characteristics of the breakpoint. When you select Sort, the Sort window displays. ═══ Display Style Window ═══ Use the Display Style window to control how the items in the breakpoint list display. You can select the type of descriptive information you want to display for all of the breakpoint items. To change how breakpoint items display: o Select one or more of the items under Columns to select the information you want to display. Each item causes a new column to be added to the Breakpoint List window. ═══ 14.4.3. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Breakpoint List window. When you select Fonts, a Fonts window displays. ═══ Sort Window ═══ Use the Sort window to sort the breakpoints that have been set in your program. Breakpoints can be sorted according to any of the following categories: o Type o Executable o Source o File o Function o Line number o Address o Status o Thread o Condition o From o To o Every. Select the category you want and select the OK push button. ═══ 14.4.4. Control Choice ═══ Select the Control choice to display the Control window. ═══ 14.5. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 14.5.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 14.6. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 14.6.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 14.6.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 14.6.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ Set Line Window ═══ Use the Set Line window to set a line breakpoint. Program execution stops when a specific source line is executed that contains a line breakpoint. Line Number Entry Field Type a line number in the Line number entry field. The breakpoint is set on the line number. For example, to set a line breakpoint on the line number 610, you would type the following in the Line number entry field: 610 Other Entry Fields For a description of the types of data you can type in the other entry fields, double-click on one of the following topics: o Executable o Source o File o Thread o From o To o Every o Expression Defer breakpoint Check Box Enable this check box if you want to set a breakpoint in a DLL that is not currently loaded. If your application consists of DLLs that are dynamically loaded, use this choice to set breakpoints in DLLs which have not been loaded yet. Note: If your application consists of an EXE or preloaded DLLs, do not enable this choice. To debug preloaded DLLs, you must enable the Debug initialization code check box in the Program Startup window. 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. When a DLL is loaded and a deferred breakpoint has been set in the DLL, the state of the breakpoint changes from deferred to active. When a DLL is freed, any breakpoints that were set in the DLL change from the active state to deferred state. If you enter an invalid source, file, or line number, the debugger will not recognize the name as invalid and will be unable to activate the breakpoint. Therefore, the invalid breakpoint will remain in the deferred state even after the DLL is loaded. Refer to the Breakpoints List window for the current state of the breakpoints that have been set. Push Buttons Select the appropriate push button to continue. Related Information o Setting simple line breakpoints o Deleting simple line breakpoints. ═══ 14.6.4. Setting Simple Line Breakpoints ═══ To set a simple line breakpoint in all threads, double-click in the prefix area of an executable statement in the source windows: Source Sets the breakpoint at a specific statement. Disassembly Sets the breakpoint at a specific assembler instruction. Mixed Sets the breakpoint at a specific assembler instruction. (The lines of source code displayed in the Mixed window are treated as comment lines only.) The prefix area turns red indicating that the breakpoint has been set. To set a thread-specific breakpoint for the thread shown in a source view, hold down the CTRL key as you double-click in the prefix area. ═══ 14.6.5. Deleting Simple Line Breakpoints ═══ To remove a simple line breakpoint in all threads, double-click in a red prefix area of the Source, Disassembly, or Mixed 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. ═══ 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. ═══ 14.6.6. Modify Choice ═══ Use the Modify choice to change the breakpoints that have been set in your program. To modify a breakpoint: 1. Highlight the breakpoint you want to change. 2. Select the Modify choice. 3. The entry fields contain the information pertaining to that breakpoint. Make your changes to the entry fields. 4. Accepts the changes and close the window. If you want to make other changes, select Set to accept the changes and keep the window open. ═══ 15. Window Analysis Window ═══ Window Analysis Window Window Analysis gives you an understanding of Presentation Manager application windows. It presents both graphical and textual information about the windows of your application and lets you observe the relationships between windows. It allows you to view a three-dimensional image of your application's windows, characteristics of windows, and parent-child relationships between the windows. Your application creates many windows, directly or indirectly, to perform tasks. All of these windows are children or descendents of desktop and desktop-object windows. Windows created by the application being debugged are referred to as debuggee windows. Window Analysis consists of the following windows: o Window Analysis is the primary window. o Parent and Z-Order Tree is a secondary window. o Window Characteristics is a secondary window. The secondary windows provide information about the Window Analysis window. When you select an item in any of the three windows, it is reflected in the other two windows. If you close the Window Analysis window, the secondary windows closes. The Window Analysis presents an image of your debuggee windows. When this image displays, you can rotate the image to visually separate the windows, select a window on the image, and look at the detailed information about that window. The Window Analysis window is represented in a notebook format. The notebook is divided in two sections: desktop and desktop-object. The notebook has major and minor tabs. Major tabs correspond to the two major sections that are located at the bottom of the notebook. Major tab pages define the beginning of major sections and are called primary pages. Pages within major sections are called regular pages. They have minor tabs that are located at the right of the notebook. The images on the desktop and desktop-object primary pages represent children of the desktop window and desktop-object window, respectively. The images on the regular pages represent the child of the desktop or desktop-object window as a parent and all its descendents. To display the pages and tabs, you can use the notebook standard keyboard selection technique. Another method of displaying the pages is to double-click on the window on the primary page. You can select any window on a page by selecting the window. By using the Tab and BackTab keys, you can move the selection from window to another window. When you select an item in the Window Analysis window, it is reflected in the two secondary windows. Each page has a status line that is used to display sizes of a window that is selected on the page. Use the vertical slider or vertical arrows to rotate the page image vertically (around the x-axis). Use the horizontal slider to rotate the image horizontally (around the y-axis). The borders of the windows are drawn as follows: Screen Solid thick line (only on a primary page) Visible window Solid thin line Invisible window Dashed thin line Menu Bar Summary File End your debugging session. Monitors View the secondary windows of Window Analysis. Options Control the way that Window Analysis displays. Windows Displays the active debugger windows. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. Related Information o Parent and Z-Order Tree o Window Characteristics ═══ Desktop ═══ The desktop section contains a primary page and several regular pages. The primary page of the desktop section contains the image of the desktop window and debuggee windows that are children of the desktop window. The primary page has a major tab with the name Desktop at the bottom of the notebook. The major tab defines the beginning of the desktop section. The regular page of the desktop section contains the image of the child of the desktop as a parent and all its descendents. The regular page has a minor tab with the image of the desktop window child and its descendents or a text. The minor tabs are at the right of the notebook. Note: The sizes and distribution of windows may cause the image to be displayed as a small dot on the screen, or number of dots positioned according to the z-order. This may occur as a consequence of minimizing the debuggee windows, or if the sizes of windows are zero. ═══ Desktop-Object Windows ═══ The desktop-object section contains a primary page and a number of regular pages. The primary page of the desktop-object section contains the image of debuggee windows that are children of the Desktop-object window. The primary page has a major tab with the name "Desktop-object" at the bottom of the notebook. The major tab defines the beginning of the desktop-object section. ;p. The regular page of the desktop-object section contains the image of the child of the desktop-object as a parent and all its descendents. The regular page has a minor tab with a text on it. The minor tab is at the right of the notebook. The desktop-object part is optional. Note: The sizes and distribution of windows may cause the image to be displayed as a small dot on the screen, or number of dots positioned according to the z-order. This is a consequence of sizes of object windows often being zero. ═══ 15.1. Monitors Menu ═══ Select choices from the Monitors menu to view the secondary windows of Window Analysis. Menu Summary Parent and z-order tree Display the Parent and Z_Order Tree window to view the relationships between the debuggee window and non-debuggee windows. Window characteristics Display the Window Characteristics window to view characteristics of the window such as class, handle, and so on. ═══ 15.1.1. Parent and Z-Order Tree Choice ═══ Select the Parent and z-order tree choice to show the relationships between the following windows: o Debuggee o Non-debuggee o Debuggee and non-debuggee. Note: Items selected in this window are reflected in the other two windows (Window Analysis and Window Characteristics). When you select Parent and z-order tree, the Parent and Z-Order Tree window displays. ═══ 15.1.1.1. Parent and Z-Order Tree Window ═══ The Parent and Z-Order Tree window shows the relationship between the following windows: o Debuggee o Non-debuggee o Debuggee and non-debuggee. Note: Items selected in this window are reflected in the other two windows (Window Analysis and Window Characteristics). The non-debuggee windows shown in the Parent and Z-Order Tree window are the desktop and desktop-object windows and their children which are not debuggee windows. Menu Summary Options Control how the items in the Parent and Z-order Tree window display. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. ═══ 15.1.1.2. Options Menu ═══ Select choices from the Options menu to control the display of the window class and handle and select the fonts. Menu Summary Display style Select to display the window class and window handle. Fonts Select the font you want to use for the text in the active window. ═══ 15.1.1.2.1. Display Style Choice ═══ Select the Display style choice to display the window class and window handle in the Parent and Z-OrderTree window. When you select Display style, the Display Style window displays. ═══ 15.1.1.2.1.1. Display Style Window ═══ Use the Display Style window to select which items you want to display in the Parent and Z-Order Tree window. Visible Characteristics Select one of these radio button to select the information you want displayed for each window: Window class The registered class of the window. Window handle The handle of the window. Both window handle and class The handle and class of the window. Include non-debuggee desktop children Select this box if you want to display all the non-debuggee desktop children. Include non-debuggee desktop-object children Select this check box to display all of the non-debuggee desktop-object children. Note: This choice is only available if you selected Desktop-object windows from the Window Analysis window. ═══ 15.1.2. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Window Analysis window. When you select Fonts, a Fonts window displays. ═══ 15.1.3. Window Characteristics Choice ═══ Select the Window characteristics choice to view the characteristics of the debuggee windows. Note: Items selected in this window are reflected in the other two windows (Window Analysis and Parent and Z-Order Tree). When you select Window characteristics, the Window Characteristics window displays. ═══ 15.1.3.1. Window Characteristics Window ═══ The Window Characteristics window displays the characteristics of the debuggee windows. The Window Characteristics window displays in a table format with each row representing a different debuggee window and each column representing a different characteristic. The rows listed in the Window Characteristics window reflect the debuggee windows on the current page of the Window Analysis window. Note: Items selected in this window are reflected in the other two windows (Window Analysis and Parent and Z-Order Tree). Menu Summary Options Control which characteristics display. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. ═══ 15.1.4. Options Menu ═══ Select choices from the Options menu to control the display of window characteristics, titles in the window, and fonts for the window. Menu Summary Display style Select which window characteristics display. Window controls Turn titles on or off in the Window Characteristics window. Fonts Select the font you want to use for the text in the active window. ═══ 15.1.5. Display Style Choice ═══ Select the Display style choice to choose which window characteristics you want to display in the Window Characteristics window. When you select Display style, the Display Style window displays. ═══ 15.1.6. Window Controls Choice ═══ Select the window controls choice to choose whether titles display in the Window Characteristics window. When you select Window controls, the Window Controls window displays. ═══ 15.1.7. Window Controls Window ═══ Use the Window controls window to turn the titles on or off in the Window Characteristics window. Display titles Select this check box if you want titles to be displayed in the window. Select the appropriate push button to continue. ═══ 15.1.8. Display Style Window ═══ Use the Display Style window to select the characteristics you want to display in the Window Characteristics window. Visible characteristics Select the characteristics you want to display in the Window Characteristics window by selecting the names of the titles. The highlighted names will be displayed in the Window Characteristics window. Select one of the push buttons to continue. ═══ Characteristics List ═══ Class Window class of the window Hwnd Window handle in 32-bit hex format Hwnd (16:16) Window handle in 16:16-bit hex format Parent Parent window handle of the window in 32-bit hex format Parent (16:16) Parent window handle of the window in 16:16-bit hex format Owner Owner window handle of the window in 32-bit hex format Owner (16:16) Owner window handle of the window in 16:16-bit hex format X X-coordinate of the position of the window relative to the desktop Y Y-coordinate of the position of the window relative to the desktop Width Width of the window Height Height of the window X' X-coordinate of the position of the window relative to its parent window Y' Y-coordinate of the position of the window relative to its parent window PID Process identification of the window TID Thread identification of the window Text Window text (valid only for windows with the class of WC_BUTTON, WC_STATIC and WC_TITLEBAR) Active Whether the window is the active window Focus Whether the window has the focus Enabled Whether the window is enabled Checked Whether the window is checked (only for windows with a class of WC_BUTTON, WC_STATIC and WC_TITLEBAR) Visible Whether the window has its visibility set on Showing Whether the window is showing Function Address of the window procedure Function name Name of the window procedure Thunk function Address of the thunk function of the window Class function Address of the function for the class of the window Model The memory model of the window Msgq The handle of message queue of the window Style The window style settings HHeap The heap handle used by the child window of the window Hwnd focus The window handle of the child window of the window that last had the focus in 32-bit HEX format Hwnd focus (16:16) The window handle of the child window of the window that last had the focus in 16:16-bit hex format User A ULONG value for applications to use at the offset QWL_USER in the windows of some preregistered window classes Defbutton The window handle of the default push button for a dialog in 32-bit hex format Defbutton (16:16) The window handle of the default push button for a dialog in 16:16-bit hex format ID The window identity of the window. The value of the id parameter of the WinCreateWindow function. Flags The frame window flags of the window Result The dialog result parameter, as established by the WinDismissDlg function X Restore X coordinate of the position to which the window is restored Y Restore Y coordinate of the position to which the window is restored CX Restore Width to which the window is restored CY Restore Height to which the window is restored X Minimize X coordinate of the position to which the window is minimized If this value is -1 the window has not been minimized Y Minimize Y coordinate of the position to which the window is minimized If this value is -1 the window has not been minimized Minimized The window is minimized Maximized The window is maximized. ═══ 15.1.9. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Window Characteristics window. When you select Fonts, a Fonts window displays. ═══ 15.1.10. Save Window Positions and Sizes Choice ═══ Select the Save window positions and sizes choice to save the position of all debugger windows. When you select this choice, the window positions are saved and the windows display in the selected positions. ═══ 15.1.11. Close Debugger Choice ═══ Select the Close debugger choice to close your current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 15.2. Options Menu ═══ Select choices from the Options menu to control the display of bitmaps and desktop-object windows and to rotate the image to the center or to the default position. Menu Summary Bitmaps Display the bitmaps on the notebook tabs. Desktop-object windows Display the desktop-object windows in the Window Analysis and Parent and Z-Order Tree windows. Rotate to center Rotate the image on the window to the center position. Rotate to default Rotate the image on the window to the default position. ═══ 15.2.1. Bitmaps Choice ═══ Enable the Bitmaps choice to display bitmaps on the tabs of the notebook in the Window Analysis window. When bitmaps are enabled, a bitmap displays on the tab if the window is shown on the screen. If the window is hidden, text displays on the tab. (For desktop-object section, this is always the case). The text displays on the tabs when bitmaps are disabled. The text is the letter "D" (Desktop) or letter "O" (Desktop-object) concatenated with the number of a regular page in the section. ═══ 15.2.2. Desktop-Object Windows Choice ═══ You can enable or disable the Desktop-object windows choice to include the desktop-object windows in the Window Analysis window. ═══ 15.2.3. Rotate to Center Choice ═══ Select the Rotate to center choice to center the image on the Window Analysis window. ═══ 15.2.4. Rotate to Default Choice ═══ Select the Rotate to default choice to rotate the image to the default position in the Window Analysis window ═══ 15.2.5. Save Debugger Window Position Choice ═══ Select the Save window positions and sizes choice to save the position of all debugger windows. When you select this choice, the window positions are saved and the windows display in the selected positions. Note: You do not need to save program profile for this choice to ═══ 15.2.6. Control Choice ═══ Select the Control choice to display the Control window. ═══ 15.3. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 15.3.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 15.4. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 15.4.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 15.4.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 15.4.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 16. Message Queue Window ═══ Message Queue Window The Message Queue Monitor window displays Presentation Manager messages associated with a Presentation Manager application. It presents formatted messages in a list as they occur. Using the message queue monitor, you can control: 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. Menu Bar Summary File End the debugging session. Options Suspend messages, clear messages, resize the columns, and access various utility windows where you can set message queue options. These options control how messages are monitored and displayed. Windows Displays the active debugger windows. Help Displays online help that compliments the information you get when you press F1 or select a Help push button. ═══ 16.1. File Menu ═══ Select the choice from the File menu of the Message Queue window to end the debugging session. Menu Summary Close debugger End the debugging session. ═══ 16.1.1. Close Debugger Choice ═══ Select the Close debugger choice to close your current debugging session. When you select the Close debugger choice, a message box prompts you to confirm that you want to end the debugging session. ═══ 16.2. Options Menu ═══ Select choices from the Options menu to suspend messages, clear messages, resize the columns, and select what you want to monitor. Menu Summary Suspend Suspends messages from being added to the Message Queue Monitor window. Clear Delete all the messages that display in the Message Queue Monitor window. Resize column width Resize the columns in the Message Queue Monitor window. Monitor messages Select which Presentation Manager messages you want monitored and displayed. Monitor windows Select which windows have their messages monitored. Monitor queues Select which message queues have their messages monitored. Format parameters Select how Presentation Manager message parameters display. Define messages Select user-defined messages. Display style Select the information you want to display in the Message Queue Monitor window. Fonts Select the font you want to use for the text in the active window. ═══ 16.2.1. Suspend Choice ═══ Select the Suspend choice to stop any new messages from being added to the Message Queue Monitor window. ═══ 16.2.2. Clear Choice ═══ Select the Clear choice to clear all the messages in the Message Queue Monitor window. ═══ 16.2.3. Resize Column Width Choice ═══ Select the Resize column width choice to recalculate the widths of the columns in the Message Queue Monitor window. Note: This option is available only when the automatic column resizing choice is not selected in the Display Style window. ═══ 16.2.4. Monitor Messages Choice ═══ The Monitor messages choice lets you select which Presentation Manager messages you want monitored. When you select Monitor Messages, the Monitor Messages window displays. ═══ 16.2.5. Monitor Messages Window ═══ Use the Monitor Messages window to specify the messages you want monitored. The Monitor Messages window consists of the following: Defined Message IDs These are the pre-defined and user-defined messages. Each message displays as a name and hex number. You can select multiple messages for monitoring. Sort o Select the Name button to sort the message names alphabetically. o Select the ID button to sort the message IDs numerically. Undefined Messages IDs o Select the Include WM_USER check box to include all undefined messages that are in the range WM_USER and above. o Select the Include non WM_USER check box to include all undefined messages that are in the range less than WM_USER. Include all message IDs Select the Include all message IDs check box to include all messages. When this check box is enabled, the defined and undefined message selections are disabled. Define Messages IDs Select this button and the Define Messages window displays. Monitor o Select the Messages to application check box to monitor messages that are received by an application. o Select the Messages from application check box to monitor messages that are dispatched by an application. o Select the Post messages check box to monitor post messages. o Select the Send messages check box to monitor send messages. Select the appropriate push button to continue. ═══ 16.2.6. Monitor Windows Choice ═══ The monitor windows choice lets you select which windows have their messages monitored. When you select Monitor windows, the Monitor Windows window displays. ═══ 16.2.7. Monitor Windows Window ═══ Use the Monitor Windows window to specify the windows you want monitored. You may identify specific windows you want to monitor by using the Window Analysis window. The Monitor Windows window consists of the following: Windows Each window displays with the class and handle. You can select multiple windows for monitoring. Sort o Select the Class button to sort the window names alphabetically. o Select the Hwnd button to sort the window handles in numerical order. o Select the Parent and z-order button to sort the window handles to show the parent and z-order relationship of application windows. Monitor all windows Select the Monitor all windows check box to monitor all the windows. This disables individual selection. Select the appropriate push button to continue. ═══ 16.2.8. Monitor Queues Choice ═══ The Monitor queues choice lets you select which message queues are being monitored. When you select Monitor windows, the Monitor Message Queue window displays. ═══ 16.2.9. Monitor Message Queue Window ═══ Use the Monitor Message Queue window to specify the message queues you want monitored. The Monitor Message Queue window consists of the following: Message Queue This section contains a list of the message queues. You can select multiple queues. Sort o Select the HMQ button to sort the message queues by message queue handles. o Select the TID button to sort the message queues by thread id. Monitor all message queues Select the Monitor all message queues check box to monitor all the message queues. This disables individual selections. Select the appropriate push button to continue. ═══ 16.2.10. Format Parameters Choice ═══ The Format parameters choice lets you choose how Presentation Manager message parameters display. When you select Format parameters, the Format Message Parameters window displays. ═══ 16.2.11. Format Message Parameters Window ═══ Use the Format Message Parameters window to specify how message parameters display. The Format Message Parameters window consists of the following: Message This section contains a list of the all the defined messages. Sort o Select the Name button to sort the messages alphabetically by name. o Select the ID button to sort the messages numerically by ID. Parameter formatting o MP1 - Message parameter 1 Select the arrow to open the MP1 list. Select the type of formatting you want from the parameter list. The formatting selections are saved in program profiles. o MP2 - Message parameter 2 Select the arrow to open the MP2 list. Select the type of formatting you want from the parameter list. The formatting selections are saved in program profiles. Select the appropriate push button to continue. ═══ 16.2.12. Parameter List ═══ The following is a list of parameters that may not be self-explanatory: 32-bit fixed (int, frac) A 32-bit fixed number formatted by separating the integer and fractional parts. 32-bit fixed (decimal rounded) A 32-bit fixed number formatted as a rounded decimal number. WM_CHAR mp1 Parameter formatted as the message parameter 1 for a WM_CHAR message. WM_CHAR mp2 Parameter formatted as the message parameter 2 for a WM_CHAR message. ═══ 16.2.13. Define Messages Choice ═══ The Define message choice lets you define messages that you want to have displayed in the Message Queue Monitor window. When you select Define message, the Define Messages window displays. ═══ 16.2.14. Define Messages Window ═══ Use the Define Messages window to define messages. Message In the Name entry field, type in the name of the message that you want to define. In the ID entry field, type in the hex number for the message or use the spin button to locate the number of the message. Default parameter formatting o MP1 - Message parameter 1 Select the arrow to open the MP1 list. Select the default type of formatting you want from the parameter list. The formatting selections are saved in program profiles. o MP2 - Message parameter 2 Select the arrow to open the MP2 list. Select the default type of formatting you want from the parameter list. The formatting selections are saved in program profiles. Message monitored by default Select the Message monitored by default check box if you want to monitor the messages by default. Select the appropriate push button to continue. ═══ 16.2.15. Display Style Choice ═══ Use the Display style choice to select which columns you want to display in the Message Queue Monitor window. When you select Display style, the Display Style window displays. ═══ 16.2.16. Display Style Window ═══ Use the Display Style window to specify which columns you want to display in the Message Queue Monitor window. The items in this window affect system performance. You may want to experiment with different settings to see what works best for your system. Columns Select the columns you want to display in the Message Queue Monitor window. These are described in the column list. Messages count The following choices affect system performance: Maximum displayed Select the number of messages you want to display from the Maximum displayed entry field. You can type in a number or use the spin button to select the number you want. A higher maximum may cause the system to respond faster. However, too high a maximum may cause the system to respond slower. Note: You may need to experiment with this setting to see what works best for your system. Deleted at one time Select the number of messages you want deleted at one time from the Deleted at one time entry field. You can type in a number or use the spin button to enter the number you want. The more messages deleted at once causes the system to respond faster. Unlimited Select Unlimited to have no maximum on the number of messages to be displayed. When you select unlimited, the Maximum displayed and Deleted at one time entry fields are disabled. This choice sets no limit on messages to have displayed and the system may respond slower. Automatic scrolling Select Automatic scrolling if you want the window to automatically scroll forward when the screen is filled with messages. Selecting this decreases system performance. Automatic column resizing Select Automatic column resizing if you want the columns to automatically resize. Selecting this decreases system performance. Note: When this check box is selected, the Resize Column Width choice is not available. Display titles Select Display titles if you want titles to be displayed in the window. This does not affect system performance. Select the appropriate push button to continue. ═══ 16.2.17. Column List ═══ The following is a list of column titles that are available: Class Window class of the window handle the message is being directed to. Note: Some messages do not have a window handle (for example, WinPostQueueMsg). Hwnd Window handle the message is being directed to. Note: Some messages do not have a window handle (for example, WinPostQueueMsg). Queue Message queue the message is being directed to. Message Message name. Msg ID Message formatted as 32-bit signed integer. Msg-hex Message formatted as 32-bit hex number. MP1 Message parameter 1. MP2 Message parameter 2. Type Indicates whether the message is a post message or a send message. Time Indicates the time stamp of the message was generated. The time stamp is an offset from a starting time. Time style is only for Post messages. Mouse The mouse position when the message was generated. Mouse style is only for Post messages. Options Message removal options. Options style is only for Post messages. Model Message identity. Model style is only for Send messages. Task Whether the message was dispatched between tasks or not. Task style is only for Send messages. From PID Process identity of the process that dispatched the message. From PID style is only for Send messages. From TID Thread identity of the thread that dispatched the message. From TID style is only for Send messages. To PID Process identity of the process that received the message. To TID Thread identity of the thread that received the message. Direction Direction the message relative to the debuggee process. Dispatched Debuggee process dispatched a message to another process. Received Debuggee process received a message from anotherprocess. Internal Debuggee process dispatched a message to itself. Processed Whether the debugger processed message on behalf the debuggee. This occurs when the debuggee is stopped. ═══ 16.2.18. Fonts Choice ═══ Select the Fonts choice to set the font you want to use for the text that displays in the Message Queue window. When you select Fonts, a Fonts window displays. ═══ 16.2.19. Control Choice ═══ Select the Control choice to display the Control window. ═══ 16.3. Windows Menu ═══ Select the Windows menu to display a list of all the open debugger windows. By selecting a window from the Windows menu, it is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 16.3.1. Windows Choices ═══ Select this choice to make the window active. By selecting this choice, the window is brought into focus and made the active window. Also, if the window is minimized, it is restored. ═══ 16.4. Help Menu ═══ Select choices from the Help menu to complement the online help information that you can get for the debugger when you press F1 or select the Help push button. Menu Summary Help index An alphabetical index of all available debugger help topics. General help Help information for the active window. Using help How to use the help facility. ═══ 16.4.1. Help Index Choice ═══ Select the Index choice display an alphabetical list of index topics for the debugger. Use the Find choice provided with the online help facility to locate topics in the index. ═══ 16.4.2. General Help Choice ═══ Select the General help choice to display online help for the active debugger window. The online help panel displayed is the same panel that displays when you place your cursor inside the window and press F1. ═══ 16.4.3. Using Help Choice ═══ Select the Using help choice to display online help information about the OS/2help facility. ═══ 17. Exception Window ═══ Exception Window The Exception window displays whenever an OS/2 exception occurs. The exception may have occurred in the application or the system code. In either case, the debugger displays and highlights the line where the exception occurred in the Source window. You can do three things from this window: Examine/Retry Allows you to investigate the cause of the exception and if desired, retry execution of the line that caused the original fault. The debugger begins with the line causing the error and attempts to continue. This is the default. Step Exception Causes the debugger to step into the first registered exception handler (tracked by OS/2). Execution stops at the first executable line of code in that exception handler. You control what happens next. Run Exception Causes the debugger to run the normal exception handlers, which are registered with OS/2 to handle exception conditions. For details on the OS/2 exception definitions, 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. ═══ 18. Overloaded Window ═══ Overloaded Window Use the Overloaded window to select the appropriate function. This window displays when you have an overloaded function. To use the Overloaded window: 1. Select the name of the function you want from the list. 2. Select the appropriate push button to continue. Signature Displays the function name and any parameters that the function has. ═══ 19. Source Filename Window ═══ Source Filename Window The Source Filename window displays when you try to open a component for which you have debugging data, but the debugger cannot locate the source code. To use the Source Filename window, do one of the following: o If the source code is located in another directory on the system, type in the path name and select OK. o If you do not have the source code for this component, select Cancel. The Disassembly window opens for this component. ═══ 20. Program Termination Window ═══ Program Termination Window Use the Program Termination window to end the debugging session, restart the debugging session, or display the Program Startup window. Select the appropriate push button to continue. ═══ 21. Child Process Termination Window ═══ Child Process Termination Window Use the Child Process Termination window to continue debugging child processes, restart the parent program, or end the debugging session. Child Process(es) Entry Field In the Child Process(es) entry field, you may modify the names of the child processes you want to debug. Select the appropriate push button to continue. ═══ Push Buttons ═══ Continue Resume debugging the next child process that is listed in the Child Process(es) entry field that is started by OS/2. Restart Restart the parent program. Close Debugger Close the debugging session. Help Display help information for this window. ═══ Push Buttons ═══ Restart Restarts the debugging session. Program startup Displays the startup window. Close Debugger Closes the debugging session. Help Displays help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have typed and closes this window. Cancel Closes the window without saving any changes. Help Displays help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have typed and closes this window. Apply Substitutes the file and leaves the window open. Cancel Closes this window without saving any changes. File List Displays a list of the files that you can select. Help Displays help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have typed and closes this window. Reset Changes the information to the previously saved setting. Default Defaults to the default setting. Cancel Closes the window without saving any changes. Help Displays help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have typed and closes this window. Apply Applies the change to the window. The change applies only until you close the window. Select OK to close the window and keep the changes. Reset Changes the information to the previously saved setting. Default Replaces the current settings with the default settings. Cancel Closes the window without saving any changes. Help Displays help information for this window. ═══ 21.1. Push Buttons ═══ OK Accepts the information you have typed and closes this window. Apply Applies the change to the window. The change applies only until you close the window. Select OK to select the new font. Reset Changes the font back to your earlier selection. Default Replaces the current selection with the default. The default font is System Monospaced 8x8. Cancel Closes the window without saving any changes. Help Displays help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have typed and closes this window. Set Select Set to set a breakpoint. Default Defaults to the default settings. Cancel Closes the window without saving any changes. Help Displays help information for this window. ═══ 21.2. Push Buttons ═══ OK Accepts the information you have typed and closes this window. Set Select Set to set the breakpoints. Cancel Closes the window without saving any changes. Default Defaults to the default settings. File List Displays a list of the files that you can select. Help Displays help information for this window. ═══ Push Buttons ═══ OK Select OK to set the breakpoint and close this window. Cancel Closes the window without saving any changes. Help Displays help information for this window. Default Defaults the current window information to the debugger defaults. ═══ Push Buttons ═══ OK Accepts the information you have typed and close this window. Delete Remove the highlighted breakpoint. Delete all Remove all of the breakpoints displayed in the window. Sort Sort the breakpoints by different categories. Disable/Enable Disable or enable the highlighted breakpoint. Modify Modify the existing breakpoints. Help Displays the online help for this window. ═══ Push Buttons ═══ Add Select Add to add the new message you have defined. Update Select Update to update a message that previously existed. Delete Select Delete to delete a message that previously existed. Cancel Select Cancel to ignore any changes that were made and close this window. Help Displays help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have typed and to close this window. Reset Select Reset to clear any changes you have made in this session. Default Select Default to replace the current default display style with default display style. Cancel Closes the window without saving any changes. Help Displays Help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have selected in this window. Reset Select Reset to clear any changes you have made in this window. Default Select Default to replace the default selection in this window. Cancel Closes the window without saving any changes. Help Displays help information for this window. ═══ Push Buttons ═══ OK Accepts the information you have typed and closes this window. Apply Apply the changes to the window. Reset Select Reset to change the colors back to what they were when you opened this window. Default Select Default to change the color back to the default color. Cancel Closes the window without saving any changes. Help Displays Help information for this window. ═══ 22. Glossary ═══ Double-click on any term for a definition: o Asynchronous o Automatic variable o Breakpoint o Clock icon o Component o Context o Debug data o Debuggee o Desktop o Desktop-object o Disable o Enable o Event breakpoint o Executable files o Executable statement o Functions o Image o Include files o Local variables o Location breakpoint o Non-debuggee o Object files o Overloaded o Parent-child relationship o Post messages. o Prefix area o Process o Program generated breakpoint o Program profiles o Recursion level o Search path o Send messages o Session o Shortcut keys o Stopping thread o Storage o Synchronous o Tag word o Thread o Time stamp o Z-order. ═══ 22.1. 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. ═══ 22.2. Automatic variable ═══ A variable that is allocated during the invocation of the function containing the variable is called an automatic variable. Every time a function is invoked, a new copy of the variable is placed in storage. ═══ 22.3. Breakpoint ═══ A breakpoint is a defined location or condition in a program that, when it is met, stops the execution of the program. ═══ 22.4. Clock Icon ═══ There are two wait states in the debugger. When the debugger is busy doing something, it displays a clock icon. This icon displays when the wait is over (for example, loading a program into the debugger). When your program is running, the debugger displays a clock icon with a rectangle behind it. This may mean that your program is waiting for input. If so, select your application window (if necessary) and provide it with the input it needs. ═══ 22.5. Component ═══ Components are the executable files, source files or object files, and the functions that comprise a program. ═══ 22.6. Context ═══ Context is the information relating to an expression or variable when it is valid. The information consists of the source file, line number, and thread. ═══ 22.7. Debuggee ═══ Debuggee is the application that is being debugged. ═══ 22.8. Debuggee window ═══ Debuggee window is a window built by the application being debugged. Every debuggee window is a descendent of the desktop or desktop-object window. ═══ 22.9. Debugging data ═══ Debugging data is the symbolic and line number information contained in the executable file that exists when compiled and linked with the correct compiler and linker options. See Compiling and Linking Your Program for more information. ═══ 22.10. Disable ═══ Disable prevents a thread from executing. ═══ 22.11. Desktop window ═══ Desktop window is a window automatically created by OS/2 when it starts a Presentation Manager interface session. The desktop window serves as a base (bottom-most) window for the windows which can be displayed. Whether a descendent window is actually seen depends on the window visibility, its position and size, and overlapping windows. The desktop window paints the background color of the screen. ═══ 22.12. Desktop-Object Window ═══ Desktop-object window is a window automatically created by OS/2 when it starts a Presentation Manager interface session. The desktop-object window serves as a base (bottom-most) window for the windows that can not be displayed. This is irrespective for the window visibility, its position and size, and overlapping windows. Any descendents of the desktop-object windows are called object windows. Object windows provide services to other windows. ═══ 22.13. Enable ═══ Enable allows a thread to execute. ═══ 22.14. Event breakpoint ═══ An event breakpoint is one of the following: o A load occurrence breakpoint o A change address breakpoint. ═══ 22.15. Executable files ═══ Executable files are the EXE or DLL files. ═══ 22.16. Executable statement ═══ An executable statement is a statement where you can stop the execution of your program by setting breakpoints. These statements are initially displayed in blue. ═══ 22.17. Functions ═══ A Function is a block of statements executed by a function call. Synonymous with procedures. ═══ 22.18. Image ═══ Image is a graphical representation of a program's windows in three dimensions (x, y, and z). A window is represented on a plane (x and y), using its size and position. Window planes in the image are perpendicular to the z-axis and positioned in z-order. A window at the top of z-order has the largest z coordinate and is the top window. ═══ 22.19. Include files ═══ Include files are files that are included in your source file by a compiler directive and are considered program source files. ═══ 22.20. Load occurrence breakpoints ═══ A load occurrence breakpoint allows you to stop the execution of your program after the DLL that you specify is loaded. ═══ 22.21. Local variables ═══ A local variable is a variable that is specific to a function. The debugger displays the following types of local variables: o Static o Automatic o Parameters. ═══ 22.22. Location breakpoint ═══ A location breakpoint is one of the following: o A line breakpoint o An address breakpoint o A function breakpoint. ═══ 22.23. Non-Debuggee ═══ Non-debuggee is an application that is not being debugged. ═══ 22.24. Non-Debuggee window ═══ Non-debuggee window is a window not built by the application being debugged. Every non-debuggee window is a descendent of the desktop or desktop-object window. ═══ 22.25. Object files ═══ Object files are the object (OBJ) files. ═══ 22.26. Overloaded function ═══ An overloaded function in C++ is when you have two or more functions with the same name with different parameters. An overloaded function also occurs when you have the same function in different modules (EXE or DLLs). ═══ 22.27. Parent-Child relationship ═══ Parent-child relationship defines the appearance of a window when it is drawn on the screen. A child window is drawn relative to its parent window. No part of a child window ever displays outside the borders of its parent window. ═══ 22.28. Post messages ═══ Messages created through WinPostMsg or WinPostMsgQueu. The calls place the message on the Message Queue of the receiver. The message is posted on the Message Queue. The calls return immediately not waiting for the receiver to return. ═══ 22.29. Prefix area ═══ Prefix area is the area within the source views where line numbers or address numbers are located. ═══ 22.30. Process ═══ Process is the collection of one or more threads and their associated system resources, such as storage, open files, and devices. ═══ 22.31. Program generated breakpoint ═══ A program generated breakpoint is the trap instruction, which in the case of OS/2 is a CC instruction, which causes the program to stop as if a breakpoint has been encountered. If this occurs, use the jump to location feature to go to the next instruction or source line. ═══ 22.32. Program profiles ═══ Program profiles are used to restore the breakpoints, monitor expressions, and source windows when debugging a program more than once. They are stored separately for each program debugged and are saved at the end of each debugging process. The file extension for the files that contain this information is @4R. Note: All breakpoints are saved. All other information such as monitors and source windows is saved only for the primary thread and only for executables and preloaded DLLs. ═══ 22.33. Recursion level ═══ The number that represents the level of recursion of a function, where the number 0 represents the first invocation. A recursive function is a function that calls itself. ═══ 22.34. Search Path ═══ The search path tells the debugger where to find the source file used in the Source and Mixed 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. Using the Environment Variables The debugger uses two environment variables: PMDOVERRIDE and PMDPATH. 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, do the following: Set PMDPATH=path;path where, path is the location of your source files. To override the normal search order, use the PMDOVERRIDE environment variable. ═══ 22.35. Send messages ═══ Messages created through WinSendMsg call. The WinSendMsg function call does not complete until the message has been processed by the window procedure whose return value is returned. If the window receiving the message belongs to the same thread, the window function is called immediately as a subroutine. If the window is of another thread or process, the operating system switches to the appropriate thread then enters the necessary window procedure recursively. The message is not placed in the queue of the destination thread. ═══ 22.36. Session ═══ Session is the collection of one or more processes associated with a virtual console such as keyboard, video display, or mouse. ═══ 22.37. Shortcut keys ═══ Shortcut keys are the keyboard keys that you use to invoke menu choices. They are usually two key names joined by a plus sign (+). For example, Ctrl+S. To use these keys together, hold down the first key and press the second key. However, some shortcut keys are single keys. For example, F3 or Delete. ═══ 22.38. Stopping thread ═══ A stopping thread is the thread that caused the program being debugged to stop. ═══ 22.39. Storage ═══ The storage is the computer memory space in use during the execution of a program. ═══ 22.40. Synchronous ═══ When the debugger is operating in synchronous mode and the debuggee is stopped, message handling is stopped. All processing of Presentation Manager messages is suspended except for the debugger which will continue to operate. The order of all messages is maintained, except for the debugger. No messages are lost. ═══ 22.41. 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. ═══ 22.42. Tag word ═══ The contents of a tag word tell you which registers are in use at a specific time. ═══ 22.43. Thread ═══ A thread is the basic OS/2 unit of execution. A thread gives a program its context, including registers, stack, and processor mode. Multiple threads can be running at the same time, and any particular thread can start another thread. ═══ 22.43.1. Time Stamp Check ═══ Information that is program profile information includes the time stamps on the executable files that make up the application. When you select to start a program with program profile, the debugger compares the time stamp in the executable program file (and the pre-loaded dynamic link libraries) with the time stamp on the program profile. If these time stamps do not match, a message box displays. Select Yes from the message box to start the program with program profile, select No to load the program without the program profile, or select Cancel to cancel the startup process and return to the Control window. If the source file changed but was not compiled, breakpoints might be invalid or display on the wrong lines. ═══ 22.44. Z-Order ═══ Z-order is the order of overlapping windows. Every window, in addition to having a screen position, has a z-order position. This viewing order is oriented along an imaginary axis, the z-axis, extending outward from the screen. A window at the bottom of the z-order is overlapped by all sibling windows. ═══ ═══ Trademark of International Business Machines