═══ 1. The ICAT Debugger ═══ The IBM Interactive Code Analysis Tool (ICAT) Debugger is used for debugging OS/2 device drivers, kernel code, Installable File Systems (IFS), and applications that are running on an OS/2 Warp Version 4 remote machine. The debugger helps you detect and diagnose errors in code written in C, C++, and assembler languages at the source level. ═══ 1.1. What is the ICAT Debugger ═══ The ICAT Debugger (hereafter referred to in this document as the debugger) is a source-level debugger which uses OS/2 Warp 3.0, OS/2 Warp Connect, or OS/2 Warp Version 4 to assist in detecting and diagnosing errors in an OS/2 Warp Version 4 system. It provides a graphical user interface and debugs PM and non-PM (single- or multi-threaded) applications as well as device drivers and other system-level binaries. This debugger has been designed to debug remotely an OS/2 Warp Version 4 system. The Kernel Debugger (KDB) runs on a victim OS/2 Warp Version 4 machine and replies to debug service requests that are sent from the debugger while running on an Intel-based OS/2 Warp 3.0, OS/2 Warp Connect, or OS/2 Warp Version 4 machine. The supported communication mode between machines is serial. Supported debug file formats include HLL (which is IBM VisualAge C++ (VACPP)) and CodeView (CV). ═══ 1.2. Before You Begin ═══ This section lists the hardware and software requirements, considerations you need to be aware of, compiling and linking options, environment variables, limitations, helpful tips, and a demo to help get you started. ═══ 1.2.1. Hardware Requirements ═══ The debugger must be run on an Intel-based system capable of running OS/2 Warp 3.0, OS/2 Warp Connect, or OS/2 Warp Version 4. Slightly less than 11 megabytes of disk space is required to install the debugger. We recommend that you run with at least a 486SX processor for performance reasons. ═══ 1.2.2. Software Requirements ═══ There are software requirements for both the victim machine where the programs are debugged and run and the host machine where the debugger runs. To set up the victim OS/2 machine: 1. Obtain or build an OS2KRNLD that has the debugger packet-handling code. This code is now part of the regular KDB builds. 2. OS2KRNL is in the root directory of the victim system's boot drive but is hidden. Use the following command to make it visible: attrib -r -s -h os2krnl Use the following commands to back up the file and replace it with its debug equivalent: copy os2krnl os2krnl.bak copy os2krnld os2krnl To set up the host OS/2 machine: 1. Unzip the ICATMERL.ZIP file into the directory where you want to run the debugger. This file contains the debugger, the victim sample binaries, and the original source files. 2. Set the environment variables. Refer to Setting Environment Variables for more information. ═══ 1.2.3. Compiling and Linking Your Program ═══ Before using the debugger, you need to compile and link your program. For VACPP programs, use the following 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. /O- Compiles your program with optimization off. This is the default. /Oi- Compiles your program with inlining off. This is the default. /DEbug Links your program to produce an executable file that includes line number information and a symbol table in addition to the executable code. Note: When you specify the /Ti+ option with the /DEbug option, icc passes this option to the linker automatically, so you only need to use it if you link separately from the compile. For more information about compiling and linking your program, refer to IBM C++ Tools Programming Guide. For Microsoft CL, CL386, MASM, and MASM386 programs, use the following options: /Zi Compiles your program to produce an object file that includes line number information and a symbol table, in addition to the source code. /Od Compiles your program with optimization off. /CO Links your program to produce an executable file that includes line number information and a symbol table in addition to the executable code. For Watcom wpp386 programs, use the following options: -d2 Compiles your program with full debugging information. -hc Compiles your program emitting CodeView debug format (currently, the debugger only supports Watcom's CodeView debug format). -od Compiles your program with optimization off. For the Watcom linker, wlink, use this option: d codeview Links your program with CodeView debug format. The debugger supports a separate debug file (from your created application) for the Watcom compiler. For the Watcom linker, wlink, use this option to create a separate debug file if desired: op symf This will create a .sym file. Be careful not to confuse this file with a KDB .sym file. The debugger looks for debug information first in the application file. If it doesn't find it, it looks for the debug information in a .dbg file and then in a .sym file as a last resort. Most users rename the separate Watcom .sym file to a .dbg file. ═══ 1.2.4. Setting Environment Variables ═══ The debugger uses environment variables to manage debugging sessions and remote communications. To set the environmental variables, you will need to edit the SETICAT.CMD file. The environment variables should be set in the OS/2 session where the debugger is to be run. The environment variables are as follows: CAT_MACHINE Specifies which host com port the debugger uses to communicate with KDB and the baud rate for communications. This variable has the following form: COMx:nnnn where x identifies the port (for example, 1 for COM1) and nnnn specifies the baud rate. The following rates are supported:  9600 (the default)  19200  38400  57600  115200 For speeds above 19200, you need buffered UARTs on both the host and victim machines. For speeds above 57600, you need customized serial drivers such as SIO.SYS or the COM.SYS that ships with Warp Version 4 (which can also be used with earlier versions of Warp). For example, type the following at the command prompt: set CAT_MACHINE=COM2:57600 Note: Ensure that your communication port is enabled if you use a ThinkPad. CAT_SETUP_RATE When the debugger first attempts to communicate with KDB, it does so at the baud rate specified by this environment variable or at 9600 baud if this variable is not defined. If the communication succeeds, the debugger changes the baud rate to the rate specified by the CAT_MACHINE environment variable and proceeds. Otherwise, the debugger tries to initiate contact at the rate specified by the CAT_MACHINE environment variable. If neither attempt succeeds, the debugger issues an error message. In most cases, you do not need to set CAT_SETUP_RATE. It is primarily useful if you have been communicating with the victim system directly (for example, using ZOC or T) and have left the serial line running at a rate other than 9600 baud that does not match the rate specified by the CAT_MACHINE environment variable. Additionally, if this environment variable is set, the debugger will reset KDB to this rate when the debugger is closed. For example, type the following at the command prompt: set CAT_SETUP_RATE=9600 CAT_HOST_BIN_PATH Tells the debugger where to find your debug binaries (the .SYS and .EXE files with debug information) on your host system. For example, type the following at the command prompt: set CAT_HOST_BIN_PATH=I:\SDE\SAMDETW CAT_COMMUNICATION_TYPE Allows asynchronous communications. Currently, this must be set to ASYNC_SIGBRK in subsequent releases it is planned to support other forms of communication. For example, type the following at the command prompt: set CAT_COMMUNICATION_TYPE=ASYNC_SIGBRK CAT_HOST_SOURCE_PATH Tells the debugger where to find the source files that were used to build your debug binaries. See Finding Source Files for more details. For example, type the following at the command prompt: set CAT_HOST_SOURCE_PATH=I:\SDE\SAMDETW;E:\icat\testcases\src CAT_PATH_RECURSE Causes a recursive search of the subdirectories below the subdirectories listed in CAT_HOST_BIN_PATH and CAT_HOST_SOURCE_PATH. For example, with the CAT_HOST_SOURCE_PATH=i\sde\samdetw variable, the debugger will search the samdetw subdirectory and all subdirectories below samdetw as well as their subdirectories. The default is NULL, which means the debugger will not perform a recursive search. When the variable is set to any non-null value, the recursive search is performed. For example, type the following at the command prompt: set CAT_PATH_RECURSE=ON CAT_MODULE_LIST By default, the debugger obtains information about every executable module (DLL, EXE, device driver, and so on) running on the victim system. As a result, it can take several minutes to attach to the victim system. If the CAT_MODULE_LIST environment variable is defined, the debugger only obtains information about a module if its name appears in the environment variable string. (The debugger always obtains information about the kernel itself.) This can dramatically reduce the amount of time it takes for the debugger to come up. For example, type the following at the command prompt: set CAT_MODULE_LIST=SAMPLEDD.SYS SAMPLE.EXE The debugger will only obtain information on the kernel and the two modules listed in CAT_MODULE_LIST. (If a program named LE.EXE were running, the debugger would also obtain information on it since LE.EXE is a substring of SAMPLE.EXE.) CAT_RESUME During debugger initialization, the debugger stops the victim system in order to establish the desired baud rate. The debugger then continues its initialization and eventually allows the user to attach to the victim system. By default, the debugger does not allow the victim system to resume execution during this interval. This behavior is necessary to debug a system that has already reached a failure or that contains a hardcoded INT3 instruction (as device drivers often do). There could be situations where you want to initialize the debugger, but somehow time your attach to the victim system using the Attach push button. In this case, define CAT_RESUME, and then the debugger will resume the victim system waiting for your attach command to stop it again. For example, type the following at the command prompt: set CAT_RESUME=ON CAT_DIAL and CAT_MODEM_INIT The host and victim machines can be connected directly (with a null modem serial cable) or by way of modem. If either of these variables is defined, the debugger sets up the COM port specified by the CAT_MACHINE environment variable so that the debugger can talk to a modem. The debugger then issues the modem attention string (+++) followed by the string specified by the CAT_MODEM_INIT variable (if any) to initialize the modem. The debugger then issues the string specified by the CAT_DIAL variable (if any) and waits 500 seconds for the remote modem to answer. The CAT_MODEM_INIT environment variable should be based on the string your terminal emulator uses to initialize the modem. This string presumably doesn't change very often. Once you have determined the correct AT commands, you can keep the CAT_MODEM_INIT environment variable constant and change CAT_DIAL when you need to place calls to different numbers. For example, type the following at the command prompt: set CAT_MODEM_INIT=ATZ set CAT_DIAL=ATDT4840 CAT_OVERRIDE Specifies a path that the debugger searches first to find the source files that were used to build your debug binaries. See "Finding Source Files" below for a complete description of the process. For example, type the following at the command prompt: set CAT_OVERRIDE=e:\temp\updates CATTAB Specifies the number of spaces between tab stops when source code containing tabs is displayed in a debugger window. For example, type the following at the command prompt: set CATTAB=5 The debugger will convert each tab in the source to 5 spaces when the source is displayed. CATTABGRID Specifies the column positions for the tab stops when source code containing tabs is displayed in a debugger window. For example, typing the following command at the command prompt sets tab stops at the 6th position: set CATTABGRID=6 DEBUG_NUMBEROFELEMENTS DEBUG_NUMBEROFELEMENTS is an environment variable that is set to an integer, n. This integer represents the default number of elements displayed for a variable or structure that has a substantial number of elements. The last element displayed for such a structure is labeled "more elements." Clicking on this entry will display the next n elements of the variable or structure. For example, type the following at the command prompt: set DEBUG_NUMBEROFELEMENTS=100 The next 100 elements are displayed. ═══ 1.2.5. Finding Source Files ═══ The search path tells the debugger where to find the source file used in the source windows. The debugger searches for the source files in the following order: 1. The path defined by the CAT_OVERRIDE environment variable, if specified. 2. The directory where the object file was compiled. 3. The path defined by the CAT_HOST_BIN_PATH environment variable, if specified. 4. The directory where the executable file is located. 5. The path defined by the CAT_HOST_SOURCE_PATH environment variable, if specified. 6. The current directory. 7. The path defined in the INCLUDE environment variable. 8. The directory of the last source file found in this debug session. Note: The CAT_PATH_RECURSE environment variable, if specified, will cause the debugger to search recursively all subdirectories of the CAT_HOST_BIN_PATH and CAT_HOST_SOURCE_PATH environment variables. ═══ 1.2.6. Limitations ═══ The debugger has the following restriction:  You can not launch an application with the debugger. You can only attach to the OS/2 Warp Version 4 system. The victim system communicates over COM2 if COM2 exists and over COM1 otherwise. The COM port the victim system uses must not be usurped by an application. For example, if the victim system is using COM2 and you issue the following command: mode com2 you may disrupt communications. The device driver and executables associated with the IBM LAN Management Utilities (for example, LMUIPL.SYS) can also prevent the victim system from communicating. Similarly, the COM port the host system uses must be dedicated to the debugger. If the debugger fails to attach, make sure you're not running a terminal emulator (for example, T or ZOC) in the background that has the COM port tied up. Currently, there are limitations with C++ support for the Watcom compiler. The debugger does not support mangled names from the Watcom compiler. This can show up when the debugger can not find certain functions (external functions and overloaded member functions) or sets function breakpoints. ═══ 1.2.7. Helpful Tips and Hints ═══ The following are tips and hints that may be helpful:  You must have OS/2 WARP 3.0, OS/2 Warp Connect, or OS/2 Warp Version 4 on your host machine.  If CAT_HOST_BIN_PATH points to a remote-mounted drive, the drive must be mounted in binary mode.  Put any environment variables that you want set in a command file. For example, you could put them in the SETICAT.CMD file or create your own command file.  The DBGSTRIP utility can be used to strip debug information from binaries placed on the victim machine but should not be used on binaries placed in CAT_HOST_BIN_PATH (if you want to do source-level debugging).  Using C and C++, you can write your program code with stylistic features that are not supported by the debugger. For example, multiple statements on the same line are difficult to debug. None of the individual statements can be accessed separately when you set breakpoints or when you use step commands. ICAT allows you to manipulate any thread running on the victim machine. Because certain portions of the address space are not shared by all threads, you must be sure that you are in the proper context when you set breakpoints, display storage, etc. The title of a thread-specific window includes the thread's identifier as shown in the Debug Session Control window (see Using the Debug Session Control Window). To ensure you are in the context of the proper thread, select the thread from the Debug Session Control window's Threads pane. For example, suppose you attach to the victim system and wish to set a breakpoint. If the breakpoint is in a shared region (for example, in a device driver, a DLL, or the kernel), it does not matter which context you are in when you set the breakpoint. But if the breakpoint is not in a shared region such as in an EXE file, you must ensure that you are in the context of a thread that belongs to the process that owns the region before you set the breakpoint. Because the debugger does not necessarily have information about every EXE file in the system, a window may show source for a module even though the thread listed in the title of the window is not part of the process that is running the EXE file. If you set the breakpoint without first verifying you are in the proper context, you will actually set a breakpoint in a different module entirely. ═══ 1.2.8. When Things Go Wrong ═══ Here are some things to check when the debugger is not doing what you think it should:  If the debugger can't attach to the victim system: - Ensure your serial cable is a "null modem" cable (one that connects the transmit data pin of one machine to the receive data pin of the other). - Ensure that your serial cable is securely attached to both the host and victim machines. - Ensure that you have the serial cable connected to the correct COMx port that KDB will use on the victim machine and to the COMx port that you specified with the CAT_MACHINE environment variable on the host machine. - Ensure that KDB is installed on the victim machine, and if necessary, check this by using a terminal emulator from the host machine before running the debugger. If the terminal emulator is successful, don't forget to shut it down before invoking the debugger. - Ensure that your CAT_HOST_BIN_PATH is set correctly. - Ensure that your CAT_COMMUNICATION_TYPE environment variable is set to ASYNC_SIGBRK. - Ensure that you have buffered UARTs on both host and victim machines if you want to run at baud rates > 19200. - Ensure that your communication port is enabled if you use a ThinkPad.  If the debugger only displays the disassembly listing of your program and not the source listing: - Ensure that the program was compiled with the proper flags to enable source-level debugging. See Compiling and Linking Your Program. - Ensure that the executable in the CAT_HOST_BIN_PATH was not processed by the DBGSTRIP utility. DBGSTRIP makes the executable smaller by removing the debug information. - Ensure that your CAT_HOST_SOURCE_PATH is set to reference your source files. - Ensure that the modules you want to debug are specified by the CAT_MODULE_LIST environment variable. ═══ 1.2.9. Using the Demo ═══ This demo shows a very simple set of DevIOCtl calls being made from a sample application to a device driver. It explains some of the actions you could take to debug this scenario at the source level. To run the demo, follow these steps: 1. Copy SAMPLEDD.SYS to the root directory of the C drive on your victim system. 2. On the victim system, edit CONFIG.SYS so that it contains the following line: DEVICE=C:\SAMPLEDD.SYS This loads the sample device driver when you reboot the victim system. 3. Copy SAMPLE.EXE to your victim system. 4. Reboot your victim machine so that the SAMPLEDD.SYS binary and the debug OS2KRNL and OS2LDR binaries are instantiated. You can perform a quick check to see if the victim machine is OK by running your normal terminal emulator (T, ZOC, and so on). This will show if KDB is communicating at 9600 baud. 5. Shut down the terminal emulator before you run the debugger. 6. Run the SETICAT.CMD file to set the environment variables on your host system. 7. Type icatgam. The Initialization window displays. 8. From the Initialization window, select the Attach push button. 9. In the Debug Session Control, make sure you see SAMPLEDD.SYS. Click on the plus sign (+) next to it and notice that one part is displayed. Click on that plus sign (+) and notice eight entries are now displayed. 10. Click on STRATEGY. The STRATEGY routine of the sampledd device driver should display in a source window. Note: This is MASM source, so you will see assembler directives, but it is source. We support both CodeView (CL and CL386) and HLL (IBM VACPP) debug formats for C. 11. Set a breakpoint on line 209 inside the STRATEGY routine by double-clicking on the line number. Run the debugger by selecting the Run button. 12. On the victim machine, type sample. SAMPLE.EXE will emit a DevIOCtl to open the SAMPLEDD device driver. 13. When the debugger notifies you that the breakpoint has been encountered, open the Registers window and then open the Storage window. Edit one of the addresses in this storage window by double-clicking on the address and change the address value to that of the PC register, which is located at the top of the list of status flags registers in the Registers window. You will see memory that corresponds to the code space. 14. From the Source window, select Passthru from the Monitors menu. 15. In the Passthru window, type dg cs in the Command entry field and select the Send push button or press the Enter key. This sends the command to KDB and the output is displayed in the response area. Notice that it provides information about SAMPLEDD's code descriptor. You can emit most KDB commands from the Passthru window. Commands that cause the victim machine to resume execution (for example, g and t) should be avoided. Note: If you change the state of the victim machine with KDB commands in the Passthru window, you must select the Resync push button to allow the debugger to reflect the changes. 16. Set another breakpoint on line 275 inside the Open subroutine. Run the debugger until the breakpoint is encountered. 17. Select the step into choice or button to do a step into on the Ccall macro to SubrWFrame. You are in the SubrWFrame subroutine. Click on the Call Stack icon. 18. From the Call Stack window, select the Display style choice from the Options menu. 19. From the Display style window, enable the Return Address choice, which is located under the Select items group heading. Select the OK push button. 20. Select the step over choice or button and notice the change in the Call Stack window. 21. Look at the Debug Session Control window and find SAMPLE.EXE. Click on the plus sign (+) and notice that one part is displayed. Click on that plus sign (+) and you will see MAIN. 22. Click on MAIN and set a breakpoint at line 44. Run the debugger by selecting the Run button. The breakpoint will be encountered in the STRATEGY routine again. 23. Run one more time and the breakpoint will be encountered in SAMPLE.EXE in MAIN. After you have completed these steps, close the debugger. At this point, you can use your terminal emulator to communicate with KDB. If you did not use the CAT_SETUP_RATE environment variable, KDB will be set at the baud rate you used to communicate with the debugger. ═══ 1.3. Getting Started ═══ This section describes how to start a debugging session from the OS/2 command prompt, attach to a process you want to debug, and how to end a debugging session. ═══ 1.3.1. Starting the Debugger from OS/2 ═══ To start the debugger from the OS/2 command prompt, enter the command icatgam. For example, type the following: icatgam /x where /x represents a debugger parameter. The debugger parameters are: /p+ Use program profile information. /p- Do not use any program profile information. If you type icatgam and press Enter, the Initialization Window displays. See Using the Initialization Window for more information. ═══ 1.3.2. Using the Initialization Window ═══ Use the Initialization window to attach to the OS2KRNL. Initialization Window To use this window:  Select the Use program profile check box if you want to restore the windows and breakpoints when debugging a program more than once.  Select the Attach push button to attach to the OS2KRNL.  Select the Settings push button to display the Debugger Properties window, which allows you to select how threads and source files initially display and set environment variables. See Debugger properties... for more information. ═══ 1.3.3. Ending the Debugging Session ═══ To end the debugging session, select Close debugger from the File menu in a debugger window. The Close Debugger window displays. Select one of the following choices:  Select Yes to end your debugging session.  Select No to return to the previous screen without exiting the debugger. You can also end the debugging session by pressing F3 in any of the debugger windows. ═══ 2. Frequently Used Features of the Debugger ═══ This section introduces the tool buttons, ways to execute your program, and describes how to set breakpoints. ═══ 2.1. Using the Tool Buttons ═══ A tool bar has been provided for easier access to frequently used features. Not all buttons are displayed in the windows. To display buttons in a window, enable the Tool buttons choice that is listed under the Options menu. The following is a list of features that are provided: Step over executes the current line in the program. If the current line is a call, execution is halted when the call is completed. Step into executes the current line in the program. If the current line is a call, execution is halted at the first statement in the called function. Step debug executes the current 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 automatically executes the lines of code up to and including the return statement of the current function. Run allows you to start and stop the program. When the debugger is running, the Run button is disabled and the Halt button is enabled. You can click on the Halt button to halt the program execution. You can also interrupt the program you are debugging by selecting the Halt choice from the Run menu. View changes the current source window to one of the other source windows. For example, you can change from the Disassembly window to the Mixed window. Monitor Expression displays the Monitor Expression window, which allows you to type in the name of the expression you want to monitor. Call Stack displays the Call Stack window, which allows you to view all of the active functions for a particular thread including the system calls. The functions are displayed in the order that they were called. Registers displays the Registers window, which allows you to view all the processor and coprocessor registers for a particular thread. Storage displays the Storage window, which shows the storage contents and the address of the storage. Breakpoints displays the Breakpoints List window, which allows you to view all the breakpoints that have been set. Passthru displays the Passthru window, which allows you to send commands and receive responses from KDB directly. Debug Session Control displays the Debug Session Control window. Growth direction allows you to change the direction that items are displayed on the stack. Delete allows you to delete the highlighted item. Delete all allows you to delete all the items in the window. 32-float displays the storage contents as a 32-bit floating point. 64-float displays the storage contents as a 64-bit floating point. 32-bit unsigned displays the storage contents as a 32-bit unsigned integer. 32-bit signed displays the storage contents as a 32-bit signed integer. ASCII displays the storage contents in ASCII. Hex and ASCII displays the storage contents in Hex and ASCII. Change representation allows you the change the data representation. ═══ 2.2. Executing a Program ═══ You can execute your program by using step commands or the Run command. Step commands Step commands control the execution of the program. The step commands are located in the tool bar of the source windows and under the Run menu of the source windows. Run command The Run command runs the program until a breakpoint is encountered, the program is halted, or the program ends. You can start the RUN command from the Run button in the tool bar or the Run menu of the source windows. When you execute your program, a clock icon displays to indicate that the program is running and might require input to continue to the next breakpoint or termination of the program. ═══ 2.3. Setting Breakpoints ═══ You can control how your program executes by setting breakpoints. A breakpoint stops the execution of your program at a specific location or when a specific event occurs. To set breakpoints, select the Breakpoints menu from the Debug Session Control window or from any of the source windows and select the appropriate choice for the type of breakpoint you want to set. You can also set a simple line breakpoint by double-clicking in the prefix area of an executable statement in any of the source windows. The prefix area is the area to the left of the source code where line numbers or addresses are displayed. The prefix area turns red indicating that the breakpoint has been set. You can also use the arrow keys to move the cursor to the prefix area and then use the space bar to toggle the breakpoints. This allows you to set or delete a breakpoint. Refer to Breakpoints Menu Choices for more information on breakpoints. ═══ 3. Introducing the Main Debugging Windows ═══ This section introduces the Debug Session Control window and the three source windows which offer different views of your source code. It describes the menu items and choices that are located in each of these windows. ═══ 3.1. Using the Debug Session Control Window ═══ The Debug Session 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 shows the threads for the program you are debugging and the corresponding process IDs, process names, kernel thread IDs, and processor number (when applicable). The other pane shows the components for the program that you are debugging. Debug Session Control Window The Threads pane contains the threads and the state of the threads started by your program. These values can be used in conjunction with the KDB .p command to match an ICAT thread to a corresponding KDB slot. To display the state of a thread, select the plus icon to the left of the thread. The Thread Popup Menu contains choices to take you to different debugger windows. The popup menu is shown when you place the mouse pointer on a highlighted thread name and click mouse button 2. The following are the popup choices: Execution point Opens a source window containing the next line to be run. Registers Displays the Registers window. Call stack Displays the Call Stack window. Local variables Displays the Local Variables window. The Components pane shows the path name of the executable files that are associated with the OS2KRNL. 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 of a specific function, double-click on the function name. You can display any object or function in a source window by double-clicking on the name in the Components pane or by highlighting the component name and selecting the View popup choice. To specify which components are shown in the Components list, select Options -> Window Settings -> Display style. The Display Style window displays. Disable the Show all components choice if you want only components compiled and linked with debugging data to be listed. If the choice is enabled, all components are listed. The Object or Function Popup Menu contains choices that allow you to display the object or function in a source window or set a function breakpoint. The popup menu is shown when you place the mouse pointer on a object or function name and click mouse button 2. The choices in the popup menu are: View Shows the object or function in a source window. Set function breakpoint Sets a function breakpoint to stop the execution of your program after calling a specific function in the current selected thread. Set breakpoint (every) Sets a breakpoint to stop the execution of your program on a function in all the threads. ═══ 3.1.1. File Menu Choices ═══ Select choices from the File menu of the Debug Session Control window to open a new source file, locate a particular function, open a source window that contains the next line to be executed, start a new debugging session, or end a debugging session. ═══ 3.1.1.1. Open new source... ═══ Displays the Open New Source window, which allows you to open a new source file. If you have multiple source files in your program, only one source file is initially displayed. Use the Open New Source window to open additional source files. Open New Source Window To use the Open New Source window:  Type the name of the object file you want to open the source for in the Source entry field. For example, to look for the source used to compile A123.OBJ, type the following: A123 If you are unsure of the file name, select the File list... push button to view a list of the files that you can select.  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.  Enable the All Executables check box if you want to search all the executable files. Disable the All Executables check box to search for a particular executable file.  Enable the Debugging Information Only check box if you want to search only the source files that contain debugging information.  Select the OK push button. ═══ 3.1.1.2. Find function... ═══ Displays the Find Function window, which allows you to open a source window to a particular function. Find Function Window To use the Find Function window:  Type the name of the function you want to search for in the Function entry field. 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. 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 that file for any static function with the same name.  Enable the Debugging information only check box if you want to search only the object files that contain debugging information.  Enable the Case sensitive 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.  Select the OK push button. ═══ 3.1.1.3. Where is execution point ═══ Opens a source window containing the next line to be executed. ═══ 3.1.1.4. Save thread list in file ═══ Saves the contents of the Threads pane into a file. The default file name is threads.out. To change the default file name, select Options -> Window settings -> Display style... from the Debug Session Control window. ═══ 3.1.1.5. Save component list in file ═══ Saves the contents of the Components pane into a file. The default file name is comps.out. To change the default file name, select Options -> Window settings -> Display style... from the Debug Session Control window. ═══ 3.1.1.6. Initialization... ═══ Displays the Initialization window, which allows you to start a debugging session by attaching to the OS2KRNL. Refer to Using the Initialization Window for more information. ═══ 3.1.1.7. Close debugger ═══ Ends the debugging session. When you select the Close debugger choice, the Close Debugger message box prompts you to confirm that you want to end the debugging session. ═══ 3.1.2. Breakpoints Menu Choices ═══ 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 Debug Session Control window or from the source windows. When you set a breakpoint in one source window, it is reflected in the other source windows. ═══ 3.1.2.1. Set line... ═══ Displays the Line Breakpoint window, which allows you to set a line breakpoint to stop the execution of your program at a specific line number. Line Breakpoint Window The Line Breakpoint window is divided into two group headings: Required Parameters and Optional Parameters. The Required Parameters group heading contains the following:  Executable Entry Field To select a component from the Executable list: 1. Type the executable name in the entry field or open the Executable list by selecting the list button. This displays a drop-down combination box. 2. Highlight the executable where you want to set the breakpoint  Source Entry Field To select a component from the Source list: 1. Type the source name in the entry field or open the Source list by selecting the list button. This displays a drop-down combination box. 2. Highlight the source where you want to set the breakpoint.  Include 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. Type the name of the file in the entry field or open the File list by selecting the list button. This displays a drop-down combination box. 2. Highlight the file where you want to set the breakpoint.  Line Entry Field To set a line breakpoint, type the line number in the Line entry field. The breakpoint is set on the line number. The Optional Parameters group heading contains the following:  Thread Entry Field To select a thread ID from the Thread list: 1. Open the Thread list by selecting the list button. This displays a drop-down combination box. 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.  From Entry Field This field is used for location breakpoints, address breakpoints and load occurrence breakpoints. Type in a number to start activating the breakpoint the nth time the location is encountered.  To Entry Field This field is used for location breakpoints, address breakpoints and load occurrence breakpoints. Type in a number to stop activating the breakpoint after the nth time the location is encountered.  Every Entry Field This field is used for location breakpoints, address breakpoints and load occurrence breakpoints. Type in a number to indicate how often the breakpoint should be activated within the From and To range.  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 will not evaluate correctly. The maximum length of the condition is 256 characters.  Defer breakpoint Check Box Enable the Defer breakpoint check box if you want to set a breakpoint in a module that is not currently loaded. 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 module is loaded. When a module is loaded and a deferred breakpoint has been set in the module, the state of the breakpoint changes from deferred to active. When a module is freed, any breakpoints that were set in the module change from the active state to deferred state. If you enter an invalid source, file or line number, the debugger will be unable to activate the breakpoint when the module is loaded. Therefore, the invalid breakpoint will remain in the deferred state even after the module is loaded. ═══ 3.1.2.2. Set function... ═══ Displays the Function Breakpoint window, which allows you to set a function breakpoint to stop the execution of your program when the first instruction of the function is encountered where the breakpoint has been set. Function Breakpoint Window The entry fields in this window are the same as in the Line Breakpoint window except for the following:  Function Entry Field Type the name of the function where you want to set the breakpoint or select a function from the Function list. To select a function, do the following: 1. Open the Function list by selecting the list button. This displays a drop-down combination box. 2. Highlight the function where you want to set the breakpoint. If a function is overloaded, then a window displays with a list of all the overloaded function names. Select the appropriate function from the list.  Debugging information 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. For a description of the types of data you can enter in the entry fields under the Optional Parameters group heading, refer to Set line.... ═══ 3.1.2.3. Set address... ═══ Displays the Address Breakpoint window, which allows you to set an address breakpoint to stop the execution of your program at a specific address. Address Breakpoint Window The entry fields in this window are the same as in the Line Breakpoint window except for the following:  Address or Expression Entry Field Type the name of the address or expression in the Address or Expression entry field. For example, to set an address breakpoint for the address 0x000A1FCC, you would type one of the following in the Address entry field: 0x000A1FCC or A1FCC The 0x is optional. For a description of the types of data you can enter in the entry fields under the Optional Parameters group heading, refer to Set line.... ═══ 3.1.2.4. Set watchpoint... ═══ Displays the Watchpoint window, which allows you to set a watchpoint to stop the execution of your program when contents of memory at a given address are referenced, when an instruction is fetched from a particular address, or when an I/O port at a particular address is referenced. Watchpoint Window Use the Watchpoint window to set a watchpoint.  Address (or Expression) or Port # Entry Field Type a hexadecimal address or port or an expression that can be evaluated to a hexadecimal address. Note: If you type ABC in the Address (or Expression) or Port # entry field, and there is a variable named ABC, the value of the variable is used instead of the hex value ABC. Also, you can type &a in the Address (or Expression) or Port # entry field to set the watchpoint on the address of a variable a. For example, type the following in the Address (or Expression) or Port # entry field to set a watchpoint for the address A1FCC. A1FCC Type the following in the Address (or Expression) or Port # entry field to set a watchpoint for the expression &variable. &variable  Bytes to Monitor Radio Buttons The debugger will monitor 1, 2, or 4 bytes for the type of watchpoint operation that you select. This choice is made for you on the Instruction fetch and I/O Port types.  Watchpoint Radio Buttons The debugger supports four types of watchpoints. They are as follows: I/O Port Causes a break when the port address is read from or written to. Write Causes a break when the address is written to. Read or write Causes a break when the address is read from or written to. Instruction fetch Causes a break when the instruction at that address is fetched. Warning: If you set a watchpoint that is on the call stack, you should remove the watchpoint before leaving the routine associated with the watchpoint. Otherwise, when you return from the routine, the routine's stack frame will be removed from the stack leaving the watchpoint intact. Any other routine that gets loaded on the stack will then contain the watchpoint. You can set up to four watchpoints. For a description of the types of data you can enter in the entry fields under the Optional Parameters group heading, refer to Set line.... ═══ 3.1.2.5. Set load occurrence... ═══ Displays the Load Occurrence Breakpoint window, which allows you to set a load occurrence breakpoint to stop the execution of your program when a specific module is loaded. Load Occurrence Breakpoint Window To use the Load Occurrence Breakpoint window, type the name of the module in the Module Name entry field. Execution stops when the module is loaded.  Module Name Entry Field To set a load occurrence breakpoint when MY.DLL is loaded, you would type one of the following in the Module Name entry field: MY or MY.DLL Note: If the CAT_MODULE_LIST environment variable has been defined, and the module's name is not contained in the CAT_MODULE_LIST, the module will not be reported. If the module can not be found in the module search path, the module name will not be accepted. See Debugger properties... for information on identifying modules. For a description of the types of data you can enter in the entry fields under the Optional Parameters group heading, refer to Set line.... ═══ 3.1.2.6. List ═══ Displays the Breakpoints List window, which lists all the breakpoints that have been set. It also shows the state of each breakpoint. Breakpoints List Window Use the Breakpoints List window to display a list of the breakpoints that have been set. The following information is also provided for each breakpoint.  The enablement state  The type of breakpoint  The position of the breakpoint  The conditions under which the breakpoint is activated. For more information on the Breakpoints List window, refer to Using the Breakpoints List Window. ═══ 3.1.2.7. Delete All ═══ Deletes all the breakpoints that have been set. ═══ 3.1.3. Monitors Menu Choices ═══ Select choices from the Monitors menu of the Debug Session Control window to open other debugging windows such as monitors, call stack, registers, and storage. The choices listed under the Monitors menu are also accessible from the tool bar of the source windows. Call stack Displays the Call Stack window, which allows you to monitor the call stack for a particular thread. This window is described in Call Stack Window. Registers Displays the Registers window, which allows you to monitor registers and flags for a particular component or thread. This window is described in Using the Registers Window. Storage Displays the Storage window, which allows you to monitor the storage in your program. This window is described in Using the Storage Window. Local variables Displays the Local Variables window, which allows you to display the local variables for the program's current function. This window is described in Using the Local Variables Window. Passthru Allows you to send commands to KDB and displays the formatted KDB response. ═══ 3.1.4. Run Menu Choices ═══ Select choices from the Run menu to execute your program or stop execution. ═══ 3.1.4.1. Run ═══ Executes the program from the current line until a breakpoint is encountered or the program ends. ═══ 3.1.4.2. Halt ═══ Interrupts the program you are debugging. ═══ 3.1.4.3. Hide Debugger on Run ═══ Minimizes the debugger windows while your application is running. ═══ 3.1.5. Options Menu Choices ═══ Select choices from the Options menu to control how the debugger windows display. ═══ 3.1.5.1. Window settings-> ═══ Use the Window settings cascading choices to modify the characteristics of the Debug Session Control window. Fonts Displays the Fonts window, which allows you to select the font you want to use for the text displayed in the Debug Session Control window. Display style... Displays the Display Style window, which allows you to select the settings you want to use. Restore defaults Resets all of the window settings to their original settings. Tool buttons Enables or disables tool buttons. Hover help Enables or disables the hover help. Infoarea Enables or disables the information area. . ═══ 3.1.5.2. Debugger settings-> ═══ Use 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. ═══ 3.1.5.3. Debugger properties... ═══ Displays the Debugger Properties window, which allows you to select how the threads and source files initially display. This window contains the following three tabs:  Source  Remote  Modules. The Remote page displays by default if you open the window using the Initialization window. If not, the Source page displays. When you select the Remote tab, the following page displays: Debugger Properties Window - Remote Page Use this window to do the following tasks:  Set the communication baud rate for the debugger.  Set the communication port.  Set the communication baud rate for KDB on initialization and after exiting.  Set the path where the debugger finds source.  Set the path where the debugger finds the debug binary modules.  View the communication mode (ASYNC_SIGBRK is all that is currently available).  Set modem communication information, if used.  Set a string to initialize KDB.  Set the option for recursive subdirectory searching of the source and binary paths. This window's values are dithered and cannot be changed after communication has been established with the victim machine. ICAT Baud Rate Group Heading This group of radio buttons allows you to select communication baud rates from 9600 to 115200. Ensure that your machine can handle rates greater than 19200 if you choose them. You must have buffered UARTs on both machines in this case. If you choose a rate of 115200, your host machine must have a COM.SYS different than the default supplied with OS/2. KDB Baud Rate Group Heading This group of radio buttons allows you to select the initial (setup) communication rate that the debugger uses to communicate with KDB. If any rate other than default is selected, that same rate will be used to reset the victim machine's communication port when the debugger is exited. Communications Port Spin Button This spin button allows you to select the communication port number for the debugger on the host machine. Environment Variables Group Heading These entry fields correspond respectively to the following environment variables:  CAT_HOST_SOURCE_PATH  CAT_HOST_BIN_PATH  CAT_COMMUNICATION_TYPE  CAT_DIAL  CAT_MODEM_INIT  CAT_KDB_INIT By adjusting these fields, you can alter your communication and serial paths dynamically before communication is established with the victim machine. See Setting Environment Variables for detailed information on environment variables. Path Recursion Check Box This check box, when selected, forces the debugger to search all source and binary path subdirectories recursively. When you select the Source tab, the following page displays: Debugger Properties Window - Source Page Use this window to determine:  when a source window first displays during a debugging session.  how to process a source window from which execution has just left. The window can remain displayed, be turned into an icon, or be discarded. Old source disposition Group Heading 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 radio buttons control 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. Minimize 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. Settings Group Heading You can choose to display more than one source window for a particular source file. Enable the Multiple views check box if you want to have multiple source windows open at the same time. Mouse button 2 behavior Group Heading Select the radio button that represents the action that you want mouse button 2 to perform. When you select the Modules tab, the following page displays: Debugger Properties Window - Modules Page Use this window to add a module name to or delete a module name from the CAT_MODULE_LIST environment variable. See Setting Environment Variables for detailed information on this environment variable. Modules List Box This contains a list of modules which the debugger obtains information about if or when they are loaded. If a module is loaded and it is not in the list, the debugger ignores the module. New Module Entry Field Type the name of the module that you want to add or delete. Select the appropriate push button to perform this task. ═══ 3.1.5.4. Monitor properties... ═══ Displays the Monitor Properties window, which allows you to select the settings for monitoring variables or expressions. Monitor Properties Window Use the Monitor Properties window to set the following:  The window into which the variable or expression being monitored is placed.  For popup expression windows, how long the monitor windows display. Monitor Location Group Heading 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: 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 Monitor window. Storage monitor Display the variable or expression in the Storage window. Save File Entry Field Use this field to identify the file where all monitor windows will write their contents when the Save to file choice is selected. Number of elements to show entry field Use this field to identify the maximum number of structure or class elements that will be displayed at one time for a given variable in the monitors. Enable bubble variables check box Select this option if you want a bubble value for the contents of a variable to appear as you place the mouse or the variable in the Source, Disassembly, and Mixed view windows. Popup Duration Group Heading If you select Popup from the Monitor Location group heading, 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 file. Permanent This monitor window is associated with a specific source window and closes when the associated source window closes. ═══ 3.1.5.5. Default data representation-> ═══ Use the Default data representation cascading choices to change the representation for a data type in a specific language. 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. Select the System choice to change the default representation of the math coprocessor registers. This choice is language independent. ═══ 3.1.5.6. Program profiles-> ═══ Use the Program profiles cascading choices to enable program profiles, delete program profiles, or change the location where the program profiles are stored, Program profiles are used to restore the debugger windows and breakpoints when debugging a program more than once. They are stored separately for each program debugged. The file extension for the files that contain this information is @DR. Select information Select what information you want saved in the program profiles. Delete program profiles Delete program profiles for a program that you have debugged. Change location Change the location of the file that holds the program profiles. This also moves any existing profiles to the new directory. ═══ 3.1.5.7. Save debugger window positions ═══ When you select this choice, the window positions and sizes are saved for each type of debugger window currently open. ═══ 3.1.5.8. Global font change ═══ Select the Global font change choice to change the font in all the debugger windows. When you select Global font change, the Font Selection window displays. ═══ 3.1.5.9. Enable window cascading ═══ Select the Enable window cascading choice to have the debugging windows overlap each other. When you enable this choice, successive windows that are opened overlap each other on the screen. However, they are cascaded so that you can see the underlying windows. When this choice is disabled, successive windows cover previously displayed windows so that you do not see the underlying windows. ═══ 3.1.5.10. Display tool buttons ═══ Select the Display tool buttons choice if you want tool buttons to be shown in all the debugger windows. ═══ 3.1.5.11. Display hover help ═══ Select the Display hover help choice if you want hover help to be shown in all the debugger windows. ═══ 3.1.5.12. Display infoarea ═══ Select the Display infoarea choice if you want the information area to be shown in all the debugger windows. ═══ 3.1.5.13. Display tool buttons on title bar ═══ Select the Display tool buttons on title bar choice if you want the tool buttons to be shown on the title bar of each window. ═══ 3.1.6. Windows Menu Choices ═══ Select the Windows menu from the Debug Session Control window to view 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. ═══ 3.1.7. Help Menu Choices ═══ Select choices from the Help menu of the Debug Session Control window to display the various types of help information. Help index Displays an alphabetical index of all available debugger help topics. General help Displays help information for the active window. Using help Describes how to use the help facility. Product information Displays product information. ═══ 3.2. Using the Source Windows ═══ A source window allows you to view the program you are debugging. You can look at your source in one of the following windows:  Source  Disassembly  Mixed A source window is thread specific. Executable lines initially display in blue, and non-executable lines initially display in black. Lines with breakpoints have a red prefix, and lines with disabled breakpoints have a green prefix. The Source window displays the source code for the current function of the program being debugged. If source is available, the Source window displays with the Debug Session Control window when the debugging session starts. Otherwise, the Disassembly window displays. Source Window The Disassembly window displays the assembler instructions for your program without symbolic information. Disassembly Window The Mixed window displays your program as follows:  Each line of source code is prefixed by its line number as in the Source window.  Each disassembled line is prefixed by an address as in the Disassembly window.  Source comment lines also display.  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. Note: The Mixed window cannot be opened if the source code is not available. Mixed Window ═══ 3.2.1. File Menu Choices ═══ The choices in the File menu are a subset of those listed under the File menu of the Debug Session Control window. Refer to File Menu Choices for a description of the choices. ═══ 3.2.2. View Menu Choices ═══ Select choices from the View menu to locate strings of text, scroll to a particular line, view include files, change the text file, or select a different view of your program. ═══ 3.2.2.1. Find Window ═══ Displays the Find window which allows you to search for a text string. 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 Text entry field. 2. Enable the Case sensitive check box if you want to search for the string exactly as typed. Disable this check box to search for uppercase and lowercase characters. 3. Select the OK push button. The search string can have alphabetic and numeric characters, a maximum of 256 characters, and uppercase and lowercase characters. ═══ 3.2.2.2. Find next ═══ Allows you to search for the next occurrence of the text string that you typed in the Find window. ═══ 3.2.2.3. Scroll to line number... ═══ Displays the Scroll to Line Number window, which allows you to go to a particular line in your program or set a line breakpoint. Scroll to Line Number Window 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 Line entry field. 2. Select the OK push button to scroll to that line. 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 set a breakpoint: 1. Type the line number you want to set the breakpoint on in the Line entry field. 2. Select the Breakpoint push button to set the breakpoint on the specified line number. ═══ 3.2.2.4. Select include file ═══ Displays the Select Include window that allows you to view the files that are included in your program. Select Include Window To use the Select Include window: 1. Select the include file. The include file name is highlighted. 2. Select the OK push button. The selected include file view displays. ═══ 3.2.2.5. Change text file ═══ Displays the Change Text File window, which allows you to specify a file name to be used 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. 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. To replace the file name: 1. Type the new path name and file name in the File entry field. 2. Select the appropriate push button. ═══ 3.2.2.6. Source ═══ Displays the Source window, which displays the source code for the current function of the program being debugged. Refer to Using the Source Windows for more information. ═══ 3.2.2.7. Disassembly ═══ Displays the Disassembly window, which displays the assembler instructions for your program without symbolic information. Refer to Using the Source Windows for more information. ═══ 3.2.2.8. Mixed ═══ Displays the Mixed window, which is a combination of the Source and Disassembly windows. Refer to Using the Source Windows for more information. ═══ 3.2.3. Breakpoints Menu Choices ═══ The choices listed under the Breakpoints menu are the same as those listed for the Debug Session Control window with the addition of the Toggle at current line choice. The Toggle at current line choice sets a breakpoint on the current line or deletes an existing breakpoint from the current line. For a description of the other menu choices, refer to Breakpoints Menu Choices. ═══ 3.2.4. Monitors Menu Choices ═══ Select choices from the Monitors menu of the source windows to monitor expressions or variables and view the other debugger windows such as call stack, registers, and so on. The next four choices listed under the Monitors menu are also accessible from the tool bar in the Debug Session Control Window. ═══ 3.2.4.1. Monitor expression... ═══ Displays the Monitor Expression window, which allows you to monitor expressions or variables and add them to various monitor windows. Monitor Expression Window Use the Monitor Expression window to type the name of the expression you want to monitor. This window lists the following contextual information:  The component you are in.  The active line of the source code, which is highlighted.  The view of the module that is active.  The thread you are in. 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 radio button 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 Debug Session Control window. ═══ 3.2.4.2. Call stack ═══ Displays the Call Stack window, which allows you to monitor the call stack for a particular thread. This window is described in Call Stack Window. ═══ 3.2.4.3. Registers ═══ Displays the Registers window, which allows you to monitor registers and flags for a particular component or thread. This window is described in Using the Registers Window. ═══ 3.2.4.4. Storage ═══ Displays the Storage window, which allows you to monitor the storage in your program. This window is described in Using the Storage Window. ═══ 3.2.4.5. Local variables ═══ Displays the Local Variables window, which allows you to display the local variables for the program's current function. This window is described in Using the Local Variables Window. ═══ 3.2.4.6. Passthru ═══ Displays the Passthru window, which allows you to send commands to KDB and displays the formatted KDB response. This window is described in Using the Passthru Window. ═══ 3.2.5. Run Menu Choices ═══ Select choices from the Run menu to perform step commands, run your program or hide debugger windows. ═══ 3.2.5.1. Step over ═══ Executes the current, highlighted line in the program. If the line includes a function call, the debugger does not regain control until the function has returned. ═══ 3.2.5.2. Step into ═══ Executes the current, highlighted line in the program. If the line includes a function call, the debugger regains control before the first statement in the function has been performed. ═══ 3.2.5.3. Step debug ═══ 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. ═══ 3.2.5.4. Step return ═══ Automatically executes the lines of code up to, and including, the return statement of the current function. ═══ 3.2.5.5. Run ═══ Runs the program. Control returns to the debugger when the program ends or execution stops at an enabled breakpoint. ═══ 3.2.5.6. Halt ═══ Interrupts the program you are debugging. ═══ 3.2.5.7. Run to location ═══ Executes your program from the current line up to the line that is highlighted or black 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 black. 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. ═══ 3.2.5.8. Jump to location ═══ 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 unpredictable results. ═══ 3.2.5.9. Hide Debugger on Run ═══ For a description of this choice, refer to Hide Debugger on Run. ═══ 3.2.6. Options Menu Choices ═══ Select choices from the Options menu to control how the debugger windows display. ═══ 3.2.6.1. Window settings-> ═══ Use the Window settings cascading choices to modify the characteristics of the source windows. Colors... Displays the Source Window Controls window, which allows you to change the color in the windows. Fonts... Displays the Font window, which allows you to change the font in the windows. Restore defaults Resets all of the window settings to their original settings. Notebook Displays the source windows in a notebook format. Tool buttons Enables or disables tool buttons. Hover help Enables or disables hover help. Infoarea Enables or disables the information area. ═══ 3.2.6.2. Debugger settings-> ═══ Use the Debugger settings cascaded choices 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. Refer to Debugger settings-> for a description of the choices. ═══ 3.2.7. Windows Menu Choices ═══ Select the Windows menu of the source windows to view 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. ═══ 3.2.8. Help Menu Choices ═══ Select choices from the Help menu of the source windows to display the various types of help information. Refer to Help Menu Choices for a description of the help choices. ═══ 4. Introducing the Other Debugging Windows ═══ This section introduces the basic debugging windows. These are the windows that are normally located in the Monitors menu of the Debug Session Control and the source windows. The windows include call stack, registers, storage, local variables, and passthru. ═══ 4.1. Using the Call Stack Window ═══ The Call Stack window lists all of the active functions for a particular thread including system calls. Call Stack Window 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 stack entry is highlighted. The remaining stack size shows the bytes left in the stack for the thread. Note: The stack may not display correctly if the code does not follow standard calling conventions or if you step into optimized code. To display the Call Stack window, select Call Stack from the Monitors menu or select the Call Stack button from the tool bar. ═══ 4.1.1. File Menu Choice ═══ Use the choice from the File menu to end the debugging session. The Close debugger choice allows you to end the 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. ═══ 4.1.2. Options Menu Choices ═══ Use choices from the Options menu to select the font you want for the Call Stack window and control how the items on the call stack display. ═══ 4.1.2.1. Fonts... ═══ Displays the Font window, which allows you to select the type of font you want to use for the Call Stack window. ═══ 4.1.2.2. Display style... ═══ Displays the Display Style window, which allows you to select the type of information you want displayed in the call stack and choose how the items are to be displayed. Display Style Window To use the Display Style window:  Select one or more of the items under Select Items 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 started. 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 Debug Session Control window. Ring Tells the ring level (0, 2, or 3) at which this frame is established. Return Address Indicates where execution will return in that function. Recursion Lists the recursion level. 0 is the first invocation. Frame Address Indicates the start of the call stack frame for that function. Variable Base Indicates the end of the call stack frame for that function. Size Indicates the size of the call stack frame for that function.  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. Enable the Unwind rings check box to have the debugger unwind the call stack across ring (privilege) transitions. This allows you to view the call sequence from user applications into the kernel. ═══ 4.1.2.3. Restore defaults ═══ Select the Restore defaults choice to reset all of the window settings to their original settings. ═══ 4.1.2.4. Tool buttons ═══ Select the Tool buttons choice to enable or disable tool buttons. If enabled, the tool buttons are displayed in the window. If disabled, the tool buttons are not displayed. ═══ 4.1.2.5. Hover help ═══ Select the Hover help choice if you want hover help to be shown. ═══ 4.1.2.6. Infoarea ═══ Select the Infoarea choice if you want the information area to be shown in the window. ═══ 4.1.3. Windows Menu Choices ═══ Select the Windows menu of the Call Stack window to view 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. ═══ 4.1.4. Help Menu Choices ═══ Select choices from the Help menu of the Call Stack window to display the various types of help information. Refer to Help Menu Choices for a description of the help choices. ═══ 4.2. Using the Registers Window ═══ The Registers window lists all the processor registers for a particular thread. The contents of all of the registers except floating-point registers are displayed in hexadecimal. To update a register, double-click on the register and a multiple-line entry field displays. Type over the contents and press Enter. Registers Window In the Registers window, floating-point registers display as floating-point decimal numbers. They can be updated with a floating-point decimal number or with a hexadecimal string that represents a floating-point number. To display the processor registers and flags, select Registers from the Monitors menu or select the Registers button from the tool bar. ═══ 4.2.1. File Menu Choices ═══ Use the choice from the File menu to end the debugging session. The Close debugger choice allows you to end the 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. ═══ 4.2.2. Options Menu Choice ═══ Use the choices from the Options menu to select the font you want for the Registers window, select the items you want shown in the window, restore the defaults, and enable or disable the tool buttons. ═══ 4.2.2.1. Fonts... ═══ When you select Fonts..., the Font window displays. From this window, select the font you want shown in the Registers window. ═══ 4.2.2.2. Display style... ═══ When you select the Display style... choice, the Display Style window is displayed, which allows you to select the type of information you want displayed in the Registers window. Display Style Window Groups Group Heading This specifies the five types of registers that the debugger displays. General registers are as follows:  EIP  EAX  EBX  ECX  EDX  EBP  ESP  ESI  EDI Status Flags registers include the PC and the EFLAGS registers. Segment registers are as follows:  CS  DS  ES  FS  GS  SS The PC register is the linear address of the current instruction. The FP stack registers are those defined by the math coprocessor. The Debug registers include miscellaneous processor registers such as CR0 and DR0. Orientation Heading The registers groups are separated with either vertical or horizontal split bars. Select the radio button which represents how you want the groups separated. Enable the Column titles check box if you want the registers group to have a title. For example, General. Enable the Save split bars check box if you want to save the adjustment of the split bars for the next time you open the Registers window. ═══ 4.2.2.3. Restore defaults ═══ Select the Restore defaults choice to reset all of the window settings to their original settings. ═══ 4.2.2.4. Tool buttons ═══ Select the Tool buttons choice to enable or disable tool buttons. If enabled, the tool buttons are displayed in the window. If disabled, the tool buttons are not displayed. ═══ 4.2.2.5. Hover help ═══ Select the Hover help choice to enable or disable hover help. If enabled, hover help is displayed in the window. If disabled, hover help is not displayed. ═══ 4.2.2.6. Infoarea ═══ Select the Infoarea choice to enable or disable the information area. If enabled, the infoarea is displayed in the window. If disabled, the infoarea is not displayed. ═══ 4.2.3. Windows Menu Choices ═══ Select the Windows menu from the Registers window to view 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. ═══ 4.2.4. Help Menu Choices ═══ Select choices from the Help menu of the Registers window to display the various types of help information. Refer to Help Menu Choices for a description of the help choices. ═══ 4.3. Using the Storage Window ═══ The Storage window shows the storage contents and the address of the storage. Storage Window Multiple storage windows can display the same storage. When you run a program or update displayed data, the Storage window is updated to reflect the change. To update the storage contents and all affected windows, double-click in the multiple-line entry field that displays. Type over the contents of the field. To specify a new address location, type over the address field in the Storage window. The window scrolls to the appropriate storage location. To display the Storage window, select Storage from the Monitors menu or select the Storage button from the tool buttons. ═══ 4.3.1. File Menu Choice ═══ Use the choice from the File menu to end the debugging session. The Close debugger choice allows you to end the 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. ═══ 4.3.2. Options Menu Choices ═══ Use choices from the Options menu to monitor expressions, control how the items in the storage window display, and select the font you want for the Storage window. ═══ 4.3.2.1. Fonts... ═══ Displays the Font window, which allows you to select the type of font you want to use for the Storage window. ═══ 4.3.2.2. Display style... ═══ Displays the Display Style window, which allows you to select the format for the storage contents and storage addresses and change the columns per line that display. Display Style Window Use the Storage Display Style window to select the parameters that control how the storage contents display and set how the storage addresses display. Content Style Group Heading 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 Group Heading Select the available address style. To select the address style: 1. Select the address style. 2. The address style becomes highlighted. Columns per line Entry Field 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. Enable the Column titles check box if you want to display the titles of the columns in the Storage window. ═══ 4.3.2.3. Fill Storage... ═══ Displays the Storage Fill Dialog window, which allows you to fill memory with a specific character or hexadecimal pattern. Fill Storage Dialog Window To fill memory with a specific character or hexadecimal pattern: 1. Type the starting address of the memory area to fill in the Starting Address entry field. 2. Type the ending address of the area or the length of the area to fill in the corresponding entry field. 3. Select either Character or Hexadecimal as the string type. 4. Type the fill string in the Repeated String, Character or Byte(s) field. This string is repeated as necessary to fill the specified area. ═══ 4.3.2.4. Monitor expression... ═══ Displays the Monitor Expression in Storage window, which allows you to type in the name of the expression you want to monitor. Monitor Expression in Storage Window To specify an expression, type the name or address of the variable or expression you want to monitor in the 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 updates the stop value of the program to the 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. ═══ 4.3.2.5. Restore defaults ═══ Select the Restore defaults choice to reset all of the window settings to their original settings. ═══ 4.3.2.6. Tool buttons ═══ Select the Tool buttons choice if you want tool buttons. ═══ 4.3.2.7. Hover help ═══ Select the Hover help choice if you want hover help. ═══ 4.3.2.8. Infoarea ═══ Select the Infoarea choice if you want the information area to be shown in the window. ═══ 4.3.3. Windows Menu Choices ═══ Select the Windows menu from the Storage window to view 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. ═══ 4.3.4. Help Menu Choices ═══ Select choices from the Help menu of the Storage window to display the various types of help information. Refer to Help Menu Choices for a description of the help choices. ═══ 4.4. Using the Local Variables Window ═══ The Local Variables window monitors the local variables (static, automatic, and parameters) for the current execution point in the program. The contents of the Local Variables window change each time your program enters or leaves a function. Local Variables Window ═══ 4.4.1. File Menu Choice ═══ Use the choice from the File menu to end the debugging session. The Close debugger choice allows you to end the 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. ═══ 4.4.2. Edit Menu Choices ═══ Select the choices from the Edit menu of the Local Variables window to delete, select, deselect, show other elements, or change representation of the variables. ═══ 4.4.2.1. Delete ═══ 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 using your mouse pointer. The variable or expression becomes highlighted. 2. Select the Delete choice from the Edit menu. ═══ 4.4.2.2. Select all ═══ Select the Select all choice to select all the expressions in the window. ═══ 4.4.2.3. Deselect all ═══ Select the Deselect all choice to cancel the selection of all the expressions in the window, ═══ 4.4.2.4. Other elements... ═══ Select the Other elements choice to view the next n items (classes, arrays, or structures) that are related to the variable or expression that you are monitoring. Currently, n defaults to 50. You can override this number by setting the environment variable DEBUG_NUMBEROFELEMENTS. For example, you would type the following to change it to 100: set DEBUG_NUMBEROFELEMENTS=100 You can also change this number dynamically in the Number of elements to show field by selecting Options -> Debugger settings -> Monitor properties from the Debug Session Control window or any of the source windows. ═══ 4.4.2.5. Representation-> ═══ Use the Representation cascading choices 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. ═══ 4.4.2.6. Copy to clipboard ═══ Select the Copy to clipboard choice to copy the selected (highlighted) local variable data to the clipboard. ═══ 4.4.2.7. Save window in file ═══ Select the Save window in file choice to save the Local Variables window contents in a file. You can choose the file name by selecting Options -> Debugger settings -> Monitor properties from the Debug Session Control window or any of the source windows and filling in the Save File entry field. ═══ 4.4.3. Options Menu Choices ═══ Select choices from the Options menu to control how the contents of variables display and set debugger options. ═══ 4.4.3.1. Fonts... ═══ Displays the Font window, which allows you to select the type of font you want to use for the Local Variables window. ═══ 4.4.3.2. Restore defaults ═══ Select the Restore defaults choice to reset all of the window settings to their original settings. ═══ 4.4.3.3. Show context ═══ Select the Show context choice to display the contextual information for the variable you are monitoring. The following information displays: comapct.  Source  File  Line  Thread. ═══ 4.4.3.4. Tool buttons ═══ Select the Tool buttons choice if you want tool buttons. ═══ 4.4.3.5. Hover help ═══ Select the Hover help choice if you want hover help. ═══ 4.4.3.6. Infoarea ═══ Select the Infoarea choice if you want the information area to be shown in the window. ═══ 4.4.4. Windows Menu Choices ═══ Select the Windows menu from the Local Variables window to view 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. ═══ 4.4.5. Help Menu Choices ═══ Select choices from the Help menu of the Local Variables window to display the various types of help information. Refer to Help Menu Choices for a description of the help choices. ═══ 4.5. Using the Passthru Window ═══ The Passthru window allows you to send commands to KDB and view its responses. The window is divided into two areas. The Command entry field area is where you enter the KDB commands, and the response area is used to display the KDB output. The KDB response area is scrollable, which allows you to review previous KDB responses from prior commands. This output area also appends a status icon for each line to indicate your input, the debugger's acceptance of that input, and text from KDB. Note: When you send KDB commands using the Passthru window, the debugger does not update its state. Thus, you should use this window for obtaining information instead of altering registers or data. Passthru Window To send a command to KDB, do the following: 1. Type the command you want to send in the Command entry field. 2. Select the Send push button. You can also press the Enter key if the Enter key performs send function check box is enabled in the Display Style window. 3. Select the Resync button to force the debugger to refresh all of its internal caches of the victim machine state. Use this button if you used the Passthru window to alter the state on the victim machine. Note: Commands that cause the victim machine to resume execution (for example, g and t) should be avoided. They can cause the debugger to lock up. The debugger tries to filter out the KDB commands that can cause a lockup, but you should always exercise caution. ═══ 4.5.1. REXX Command Files ═══ The debugger supports the execution of DEBUGO REXX command files. To start a DEBUGO REXX command file, specify an * before the command filename in the Command entry field. For example: * memcount.cmd would trigger the execution of the DEBUGO REXX command file memcount.cmd. ═══ 4.5.2. File Menu Choice ═══ Use the choice from the File menu to end the debugging session. The Close debugger choice allows you to end the 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. ═══ 4.5.3. Edit Menu Choices ═══ Select the choices from the Edit menu to edit lines in the response area, delete a line in the response area, or delete all the lines in the response area of the Passthru window. ═══ 4.5.3.1. Edit ═══ Select the Edit choice to edit a line in the response area of the Passthru window. To edit a line: 1. Highlight the line you want to edit. 2. Select the Edit choice. ═══ 4.5.3.2. Delete ═══ Select the Delete choice to delete a line in the response area of the Passthru window. To delete a line: 1. Highlight the line you want to delete. 2. Select the Delete choice. ═══ 4.5.3.3. Delete all ═══ Select the Delete all choice to delete all the lines in the response area of the Passthru window. To delete all the lines in the response area: 1. Select the Delete all choice. When you select the Delete all choice, a message box prompts you to confirm that you want to delete all the lines. 2. Select Yes. ═══ 4.5.3.4. Find ═══ Select the Find choice to search for a text string in the active window. To find a text string: 1. Type in the string of text you want to find in the Text entry field. 2. Enable the Case sensitive check box if you want to search for the string exactly as typed. Disable this check box to search for uppercase and lowercase characters. 3. Select the OK push button. ═══ 4.5.3.5. Find Next ═══ Select Find Next to search for the next occurrence of the text string that you typed in the Find window. ═══ 4.5.4. Options Menu Choices ═══ Select choices from the Options menu to change the font and control what items are shown in the Passthru window. ═══ 4.5.4.1. Fonts... ═══ Displays the Font window, which allows you to select the type of font you want to use for the Passthru window. ═══ 4.5.4.2. Display style... ═══ Displays the Display Style window, which allows you to select the items you want displayed in the window, select the number of items you want displayed, change the function of the Enter key, and save the output in a file. Display Style Window To use the Display Style window:  Select the items you want under the Select Items group heading. Each item you select causes a new column to be added to the response area of the Passthru window.  In the Number Items entry field, type the number of lines you want to be displayed in the response area. The maximum number of lines is 10,000.  The Output File entry field allows you to specify the name of the file where Passthru responses are optionally saved.  The Save output in file also check box allows you to copy the Passthru response items into a file (logging function). If the check box is enabled, the responses are copied into the file that you specified in the Output File entry field.  The Enter key performs send function check box allows you to enable or disable the Enter key from performing a send function. If the check box is enabled, the Enter key will perform the same function as the Send push button. If it is disabled, the Enter key will perform a carriage return. ═══ 4.5.4.3. Restore defaults ═══ Select the Restore defaults choice to reset all of the window settings to their original settings. ═══ 4.5.4.4. Add custom tool buttons ═══ Select the Add custom tool buttons choice to associate a Passthru command with a tool button icon. To do this: 1. Select one of the 10 icons to associate with a command. 2. Enter a Passthru command in the Commands entry field. For example, dg cs. 3. Select the Add push button to place the icon on the toolbar. When you select the icon from the toolbar, the associated command is executed. You can add, delete, or change icons and their associated text. Note: If the tool buttons choice has not been selected or if the tool buttons are on the title bar, you can not select the Add custom tool buttons choice ═══ 4.5.4.5. Tool buttons ═══ Select the Tool buttons choice to enable or disable tool buttons. If enabled, the tool buttons are displayed in the window. If disabled, the tool buttons are not displayed. ═══ 4.5.4.6. Hover help ═══ Select the Hover help choice if you want hover help. ═══ 4.5.4.7. Infoarea ═══ Select the Infoarea choice if you want the information area to be shown in the window. ═══ 4.5.5. Windows Menu Choices ═══ Select the Windows menu from the Passthru window to view 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. ═══ 4.5.6. Help Menu Choices ═══ Select choices from the Help menu of the Passthru window to display the various types of help information. Refer to Help Menu Choices for a description of the help choices. ═══ 4.6. Using the Monitor Windows ═══ The debugger has four other windows that allow you to monitor variables and expressions. These windows are as follows:  Popup Monitor  Program Monitor  Private Monitor  Storage Monitor. A Popup Monitor window monitors single variables or expressions. This window is associated with a specific source window and closes when the associated window closes. The Program Monitor, Private Monitor, and Storage Monitor windows are used as collectors for individual variables or expressions in which you might be interested. The difference between the Private Monitor window and the Program Monitor window is the length of time that each remains open. The Program Monitor window remains open for the entire debugging session. The Private Monitor window is associated with the source window from which it was opened and closes when its associated view is closed. ═══ 4.7. Using the Breakpoints List Window ═══ Use the Breakpoints List window to display a list of the breakpoints that have been set. The following information is provided for each breakpoint that has been set:  The type of breakpoint  The position of the breakpoint  The enablement state  The conditions under which the breakpoint is activated. To display the Breakpoints List window, select List from the Breakpoints menu or select the Breakpoints button in the tool bar. Breakpoint List Window ═══ 4.7.1. File Menu Choice ═══ Use the choice from the File menu to end the debugging session. The Close debugger choice allows you to end the 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. ═══ 4.7.2. Edit Menu Choices ═══ Select the choices from the Edit menu of the Breakpoints List window to delete, disable, modify, or enable breakpoints. ═══ 4.7.2.1. Delete ═══ Deletes any breakpoints that are highlighted in the Breakpoints List window. To delete a breakpoint: 1. Highlight the breakpoint you want to delete. 2. Select the Delete choice. ═══ 4.7.2.2. Disable ═══ Disables any highlighted breakpoints. The breakpoint remains set but is not activated. This allows you to run your program 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. ═══ 4.7.2.3. Modify ═══ 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. ═══ 4.7.2.4. Delete all ═══ Deletes all the breakpoints that have been set. To delete all the breakpoints: 1. Select the Delete all choice. The Delete All Breakpoints window displays. 2. Select Yes from the Delete All Breakpoints window. ═══ 4.7.2.5. Disable all ═══ Disables all the breakpoints that have been set. To disable all the breakpoints: Select the Disable all choice. The prefix area in the source window changes from red to green to show that the breakpoints are disabled. ═══ 4.7.2.6. Enable all ═══ Enables all the breakpoints that have been disabled. To enable the breakpoints: Select the Enable all choice. The prefix area in the source window changes from green to red to show that the breakpoints are enabled. ═══ 4.7.3. Set Menu Choices ═══ Refer to Breakpoints Menu Choices for a description of the Set menu choices. ═══ 4.7.4. Options Menu Choices ═══ Select choices from the Options menu of the Breakpoints List window to sort the breakpoints, change the style, and change the font for the window. ═══ 4.7.4.1. Fonts... ═══ Displays the Font window that allows you to select the font you want to use for the text in the Breakpoints List window. ═══ 4.7.4.2. Display style... ═══ Displays the Display Style window, which allows you to control how the items appear in the Breakpoints List window. Breakpoints - Display Style Window To change the columns which are displayed in the Breakpoint List window: comapct. 1. Select one or more of the items under the Select Items group heading. Each item you select causes a new column to be added to the Breakpoint List window. 2. Select the OK push button. The Show Watchpoint Types check box allows you to see more type information for watchpoints when they are enabled. For example, a type field of Watch - Instruction fetch would be displayed. ═══ 4.7.4.3. Sort ═══ Displays the Sort window, which allows you to sort the breakpoints by the characteristics of the breakpoint. Sort Window Use the Sort window to sort the breakpoints that have been set in your program. Breakpoints can be sorted according to the following categories:  Type  Executable  Source  File  Function  Line  Address  State  Status  Thread  Expression  From  To  Every. Select the category you want and select the OK push button. ═══ 4.7.4.4. Restore defaults ═══ Select the Restore defaults choice to reset all of the window settings to their original settings. ═══ 4.7.4.5. Tool buttons ═══ Select the Tool buttons choice if you want tool buttons. ═══ 4.7.4.6. Hover help ═══ Select the Hover help choice if you want hover help. ═══ 4.7.4.7. Infoarea ═══ Select the Infoarea choice if you want the information area to be shown in the window. ═══ 4.7.5. Windows Menu Choices ═══ Select the Windows menu from the Breakpoints List window to view 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. ═══ 4.7.6. Help Menu Choices ═══ Select choices from the Help menu of the Breakpoints List window to display the various types of help information. Refer to Help Menu Choices for a description of the help choices. ═══ 5. Expressions Supported ═══ This section describes the expression language supported by the debugger, which is a subset of C/C++. This includes the operands, operators, and data types. Note: You can display and update bit fields for C/C++ code only. You cannot look at variables that have been defined using the #DEFINE preprocessor directive. ═══ 5.1. 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:  Fixed or floating-point constant. Note: The largest floating-point constant is 1.8E308. The smallest floating-point is 2.23E-308.  A string constant, enclosed in quotation marks (" ")  A character constant, enclosed in single quote marks (' ') Registers 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. 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. ═══ 5.2. Supported Expression Operators ═══ You can monitor an expression that uses the following operators only:   Table 1. Supported Expression Operators    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    ═══ 5.3. Supported Data Types ═══ You can monitor an expression that uses the following typecasting operations:  8-bit signed byte  8-bit unsigned byte  16-bit signed integer  16-bit unsigned integer  32-bit signed integer  32-bit unsigned integer  32-bit floating-point  64-bit floating-point  128-bit floating-point  Pointers  User-defined types.