ICAT Debugger

ICAT Debugger
2 Sep 1997

Notices


First Edition (September 1997)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

This publication was developed for products and services offered in the United States of America. IBM may not offer the products, services, or features discussed in this document in other countries, and the information is subject to change without notice. Consult your local IBM representative for information on the products, services, and features available in your area.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.


Copyright Notices

© Copyright International Business Machines Corporation 1997. All rights reserved.

Note to U.S. Government Users: Documentation related to restricted rights - use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.


Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.

Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

IBM
OS/2
OS/2 Warp
VisualAge

The following terms are trademarks of other companies:

Microsoft, Windows, Windows NT®, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Corporation.

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.


Table of Contents

The ICAT Debugger

  • What is the ICAT Debugger
  • Before You Begin
  • Hardware Requirements
  • Software Requirements
  • Compiling and Linking Your Program
  • Setting Environment Variables
  • Finding Source Files
  • Limitations
  • Helpful Tips and Hints
  • When Things Go Wrong
  • Using the Demo
  • Getting Started
  • Starting the Debugger from OS/2
  • Using the Initialization Window
  • Ending the Debugging Session
  • Frequently Used Features of the Debugger

  • Using the Tool Buttons
  • Executing a Program
  • Setting Breakpoints
  • Using the Drag-and-Drop Function
  • Introducing the Main Debugging Windows

  • Using the Debug Session Control Window
  • File Menu Choices
  • Open new source...
  • Find function...
  • Where is execution point
  • Save thread list in file
  • Save component list in file
  • Reboot target
  • Initialization...
  • Close debugger
  • Breakpoints Menu Choices
  • Set line...
  • Set function...
  • Set address...
  • Set watchpoint...
  • Set load occurrence...
  • List
  • Delete all
  • Monitors Menu Choices
  • Run Menu Choices
  • Run
  • Halt
  • Hide debugger on Run
  • Options Menu Choices
  • Window settings->
  • Debugger settings->
  • Debugger properties...
  • Monitor properties...
  • Default data representation->
  • Program profiles->
  • Save debugger window positions
  • Global font change...
  • Enable window cascading
  • Display tool buttons
  • Display hover help
  • Display infoarea
  • Place tool buttons on title bar
  • Windows Menu Choices
  • Help Menu Choices
  • Using the Source Windows
  • Drag-and-Drop Function
  • File Menu Choices
  • Save window in file...
  • View Menu Choices
  • Find...
  • Find next
  • Scroll to line number...
  • Select include...
  • Change text file
  • Source
  • Disassembly
  • Mixed
  • Breakpoints Menu Choices
  • Monitors Menu Choices
  • Monitor expression...
  • Call stack
  • Registers
  • Storage
  • Local variables
  • Passthru
  • Run Menu Choices
  • Step over
  • Step into
  • Step debug
  • Step return
  • Run
  • Halt
  • Run to location
  • Jump to location
  • Hide debugger on Run
  • Options Menu Choices
  • Window settings->
  • Debugger settings->
  • Windows Menu Choices
  • Help Menu Choices
  • Introducing the Other Debugging Windows

  • Using the Call Stack Window
  • File Menu Choices
  • Save to file
  • Close debugger
  • Options Menu Choices
  • Fonts...
  • Display style...
  • Restore defaults
  • Tool buttons
  • Hover help
  • Infoarea
  • Windows Menu Choices
  • Help Menu Choices
  • Using the Registers Window
  • Drag-and-Drop Function
  • File Menu Choices
  • Options Menu Choice
  • Fonts...
  • Display style...
  • Restore defaults
  • Tool buttons
  • Hover help
  • Infoarea
  • Windows Menu Choices
  • Help Menu Choices
  • Using the Storage Window
  • Drag-and-Drop Function
  • File Menu Choices
  • Save to file
  • Close debugger
  • Options Menu Choices
  • Fonts...
  • Display style...
  • Fill Storage...
  • Monitor expression...
  • Restore defaults
  • Tool buttons
  • Hover help
  • Infoarea
  • Windows Menu Choices
  • Help Menu Choices
  • Using the Local Variables Window
  • File Menu Choice
  • Edit Menu Choices
  • Delete
  • Select all
  • Deselect all
  • Other elements...
  • Representation->
  • Copy to clipboard
  • Save window in file
  • Options Menu Choices
  • Fonts...
  • Restore defaults
  • Show context
  • Tool buttons
  • Hover help
  • Infoarea
  • Windows Menu Choices
  • Help Menu Choices
  • Using the Passthru Window
  • REXX Command Files
  • File Menu Choice
  • Edit Menu Choices
  • Edit
  • Delete
  • Delete all
  • Find...
  • Find Next
  • Options Menu Choices
  • Fonts...
  • Display style...
  • Restore defaults
  • Add custom tool buttons
  • Tool buttons
  • Hover help
  • Infoarea
  • Resync with ring 3
  • Windows Menu Choices
  • Help Menu Choices
  • Using the Monitor Windows
  • Drag-and-Drop Function
  • Using the Breakpoints List Window
  • File Menu Choice
  • Edit Menu Choices
  • Delete
  • Disable
  • Modify
  • Delete all
  • Disable all
  • Enable all
  • Set Menu Choices
  • Options Menu Choices
  • Fonts...
  • Display style...
  • Sort
  • Restore defaults
  • Tool buttons
  • Hover help
  • Infoarea
  • Windows Menu Choices
  • Help Menu Choices
  • Expressions Supported

  • Supported Expression Operands
  • Supported Expression Operators
  • Supported Data Types
  • Index


    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.


    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).


    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.

    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.

    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 ICATOS2.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.

    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.

    The debugger supports a separate debug file (from your created application) for the VACPP compiler. This file can either be generated from the ilink linker or a tool that strips out debug information. This assumes that you have a version of ilink that supports debug files.

    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. Most users rename the separate Watcom .sym file to a .dbg file.

    Note: 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.

    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:

    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
    

    CAT_TAB
    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 CAT_TAB=5
    

    The debugger will convert each tab in the source to 5 spaces when the source is displayed.

    CAT_TAB_GRID
    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 CAT_TAB_GRID=6
    

    CAT_DEBUG_NUMBER_OF_ELEMENTS
    CAT_DEBUG_NUMBER_OF_ELEMENTS 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 CAT_DEBUG_NUMBER_OF_ELEMENTS=100
    

    The next 100 elements are displayed.

    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.

    Limitations

    The debugger has the following restriction:

    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. (Note that KDB can be directed to use a particular COM port via the KBD.INI file.)

    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.

    Helpful Tips and Hints

    The following are tips and hints that may be helpful:

    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.

    When Things Go Wrong

    Here are some things to check when the debugger is not doing what you think it should:

    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.


    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.

    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.

    Using the Initialization Window

    Use the Initialization window to attach to the OS2KRNL.

    Figure 1. Initialization Window

    * Figure gaminit not displayed.


    To use this window:

    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:

    You can also end the debugging session by pressing F3 in any of the debugger windows.


    Frequently Used Features of the Debugger

    This section introduces the tool buttons, ways to execute your program, and describes how to set breakpoints.


    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:

    * Figure icon0 not displayed.
    Step over executes the current line in the program. If the current line is a call, execution is halted when the call is completed.

    * Figure icon1 not displayed.
    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.

    * Figure icon2 not displayed.
    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.

    * Figure icon3 not displayed.
    Step return automatically executes the lines of code up to and including the return statement of the current function.

    * Figure icon4 not displayed.
    Run allows you to start and stop the program.

    When the debugger is running, the Run button is disabled and the Halt button * Figure icon5 not displayed. 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.

    * Figure icon6 not displayed.
    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.

    * Figure icon7 not displayed.
    Monitor Expression displays the Monitor Expression window, which allows you to type in the name of the expression you want to monitor.

    * Figure icon8 not displayed.
    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.

    * Figure icon9 not displayed.
    Registers displays the Registers window, which allows you to view all the processor and coprocessor registers for a particular thread.

    * Figure icon11 not displayed.
    Storage displays the Storage window, which shows the storage contents and the address of the storage.

    * Figure icon12 not displayed.
    Breakpoints displays the Breakpoints List window, which allows you to view all the breakpoints that have been set.

    * Figure merpass not displayed.
    Passthru displays the Passthru window, which allows you to send commands and receive responses from KDB directly.

    * Figure icon13 not displayed.
    Debug Session Control displays the Debug Session Control window.

    * Figure icon14 not displayed.
    Growth direction allows you to change the direction that items are displayed on the stack.

    * Figure icon15 not displayed.
    Delete allows you to delete the highlighted item.

    * Figure icon16 not displayed.
    Delete all allows you to delete all the items in the window.

    * Figure icon17 not displayed.
    32-float displays the storage contents as a 32-bit floating point.

    * Figure icon18 not displayed.
    64-float displays the storage contents as a 64-bit floating point.

    * Figure icon19 not displayed.
    32-bit unsigned displays the storage contents as a 32-bit unsigned integer.

    * Figure icon20 not displayed.
    32-bit signed displays the storage contents as a 32-bit signed integer.

    * Figure icon21 not displayed.
    ASCII displays the storage contents in ASCII.

    * Figure icon22 not displayed.
    Hex and ASCII displays the storage contents in Hex and ASCII.

    * Figure icon23 not displayed.
    Change representation allows you the change the data representation.

    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.


    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.


    Using the Drag-and-Drop Function

    Drag-and-drop is supported in the Storage, Registers, Private Monitor, and Program Monitor windows. Additionally, drag is supported from the Source window. When you press and hold the right mouse button then move the mouse, the drag is in operation. Then move the mouse to the target location and release the mouse button to perform a drop.


    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.


    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.

    Figure 2. Debug Session Control Window

    * Figure merdscw not displayed.


    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.

    Set instruction fetch breakpoint
    Sets an instruction fetch watchpoint to stop the execution of your program when the function is to be executed next in the instruction stream.

    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.

    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.

    Figure 3. Open New Source Window

    * Figure gamonsw not displayed.


    To use the Open New Source window:

    Find function...

    Displays the Find Function window, which allows you to open a source window to a particular function.

    Figure 4. Find Function Window

    * Figure gamffw not displayed.


    To use the Find Function window:

    Where is execution point

    Opens a source window containing the next line to be executed.

    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.

    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.

    Reboot target

    Reboots the victim machine while the debugger stays attached.

    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.

    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.

    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.

    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.

    Figure 5. Line Breakpoint Window

    * Figure gamlbw not displayed.


    The Line Breakpoint window is divided into two group headings: Required Parameters and Optional Parameters.

    The Required Parameters group heading contains the following:

    The Optional Parameters group heading contains the following:

    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.

    Figure 6. Function Breakpoint Window

    * Figure gamfbw not displayed.


    The entry fields in this window are the same as in the Line Breakpoint window except for the following:

    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...".

    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.

    Figure 7. Address Breakpoint Window

    * Figure gamabw not displayed.


    The entry fields in this window are the same as in the Line Breakpoint window except for the following:

    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...".

    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.

    Figure 8. Watchpoint Window

    * Figure mercadd not displayed.


    Use the Watchpoint window to set a watchpoint.

    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...".

    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.

    Figure 9. Load Occurrence Breakpoint Window

    * Figure gamlocb not displayed.


    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.

    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...".

    List

    Displays the Breakpoints List window, which lists all the breakpoints that have been set. It also shows the state of each breakpoint.

    Figure 10. Breakpoints List Window

    * Figure break00 not displayed.


    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.

    For more information on the Breakpoints List window, refer to "Using the Breakpoints List Window".

    Delete all

    Deletes all the breakpoints that have been set.

    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 "Using the 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.

    Run Menu Choices

    Select choices from the Run menu to execute your program or stop execution.

    Run

    Executes the program from the current line until a breakpoint is encountered or the program ends.

    Halt

    Interrupts the program you are debugging.

    Hide debugger on Run

    Minimizes the debugger windows while your application is running.

    Options Menu Choices

    Select choices from the Options menu to control how the debugger windows display.

    Window settings->

    Use the Window settings cascading choices to modify the characteristics of the Debug Session Control window.

    Fonts...
    Displays the Font 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. .

    Debugger settings->

    Use the Debugger settings cascading 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.

    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:

    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:

    Figure 11. Debugger Properties Window - Remote Page

    * Figure debprop not displayed.


    Use this window to do the following tasks:

    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, you need customized serial drivers such as SIO.SYS or the COM.SYS that ships with Warp Version 4 (which can be used with earlier versions of Warp).

    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:

    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:

    Figure 12. Debugger Properties Window - Source Page

    * Figure mersrc not displayed.


    Use this window to determine:

    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:

    Figure 13. Debugger Properties Window - Modules Page

    * Figure gammods not displayed.


    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.

    Monitor properties...

    Displays the Monitor Properties window, which allows you to select the settings for monitoring variables or expressions.

    Figure 14. Monitor Properties Window

    * Figure mermonp not displayed.


    Use the Monitor Properties window to set the following:

    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. The meta key (Ctrl-Q) will toggle this support on and off from the view windows, too.

    Popup Duration Group Heading

    If you select Popup monitor 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.

    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.

    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.

    Save debugger window positions

    When you select this choice, the window positions and sizes are saved for each type of debugger window currently open.

    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 window displays.

    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.

    Display tool buttons

    Select the Display tool buttons choice if you want tool buttons to be shown in all the debugger windows.

    Display hover help

    Select the Display hover help choice if you want hover help to be shown in all the debugger windows.

    Display infoarea

    Select the Display infoarea choice if you want the information area to be shown in all the debugger windows.

    Place tool buttons on title bar

    Select the Place tool buttons on title bar choice if you want the tool buttons to be shown on the title bar of each window.

    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.

    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.

    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:

    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.

    Figure 15. Source Window

    * Figure source not displayed.


    Drag-and-Drop Function

    The Source window can only be used to drag values. Drop is not supported in the Source window.

    To drag an item in the Source window, press and hold the right mouse button on the string that you want to drag while moving the mouse. If you want to drag an extended line, highlight the line using the left mouse button and then press and hold the right mouse button to move the highlighted text.

    When an item is dragged from the Source window, its context is dragged with it. However, only the monitors windows (Private and Program) use this context on the drop operation. So only values that have global context can be dropped from the Source window onto the Storage window or the Registers window.

    See "Using the Drag-and-Drop Function" for more information about the drag-and-drop function.

    The Disassembly window displays the assembler instructions for your program without symbolic information.

    Figure 16. Disassembly Window

    * Figure merdisw not displayed.


    The Mixed window displays your program as follows:

    Note: The Mixed window cannot be opened if the source code is not available.

    Figure 17. Mixed Window

    * Figure mixed not displayed.


    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) with the addition of the Save window in file... choice.

    Save window in file...

    Displays the Save to File window, which allows you to save your current source view to a named file.

    Figure 18. Save to File Window

    * Figure savfil not displayed.


    To save the current view to a named file:

    1. Type a name for the file you want to save in the File name entry field.

    2. Select the OK push button.

    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.

    Find...

    Displays the Find window, which allows you to search for a text string.

    Figure 19. Find Window

    * Figure gamfind not displayed.


    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.

    Find next

    Allows you to search for the next occurrence of the text string that you typed in the Find window.

    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.

    Figure 20. Scroll to Line Number Window

    * Figure gamstlw not displayed.


    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.

    Select include...

    Displays the Select Include window, which allows you to view the files that are included in your program.

    Figure 21. Select Include Window

    * Figure gamsinc not displayed.


    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.

    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.

    Figure 22. Change Text File Window

    * Figure ctxt0 not displayed.


    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.

    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.

    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.

    Mixed

    Displays the Mixed window, which is a combination of the Source and Disassembly windows.

    Refer to "Using the Source Windows" for more information.

    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".

    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.

    Monitor expression...

    Displays the Monitor Expression window, which allows you to monitor expressions or variables and add them to various monitor windows.

    Figure 23. Monitor Expression Window

    * Figure gammew not displayed.


    Use the Monitor Expression window to type the name of the expression you want to monitor. This window lists the following contextual information:

    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.

    Call stack

    Displays the Call Stack window, which allows you to monitor the call stack for a particular thread. This window is described in "Using the 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

    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".

    Run Menu Choices

    Select choices from the Run menu to perform step commands, run your program or hide debugger windows.

    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.

    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.

    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.

    Step return

    Automatically executes the lines of code up to, and including, the return statement of the current function.

    Run

    Runs the program. Control returns to the debugger when the program ends or execution stops at an enabled breakpoint.

    Halt

    Interrupts the program you are debugging.

    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.

    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.

    Hide debugger on Run

    For a description of this choice, refer to "Hide debugger on Run".

    Options Menu Choices

    Select choices from the Options menu to control how the debugger windows display.

    Window settings->

    Use the Window settings cascading choices to modify the characteristics of the source windows.

    Colors...
    Displays the Source Window Colors 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.

    Debugger settings->

    Use the Debugger settings cascading 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.

    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.

    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.


    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.


    Using the Call Stack Window

    The Call Stack window lists all of the active functions for a particular thread including system calls.

    Figure 24. Call Stack Window

    * Figure gamcstk not displayed.

    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 * Figure icon8 not displayed. from the tool bar.

    File Menu Choices

    Use the choices from the File menu to save the contents of the Call Stack window or to end the debugging session.

    Save to file

    The Save to file choice saves the contents of the Call Stack window to a file. You can choose the file name by selecting Options -> Display Style from the Call Stack window and filling in the Save file field.

    Close debugger

    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.

    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.

    Fonts...

    Displays the Font window, which allows you to select the type of font you want to use for the Call Stack window.

    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.

    Figure 25. Display Style Window

    * Figure gamcsds not displayed.


    To use the Display Style window:

    Restore defaults

    Select the Restore defaults choice to reset all of the window settings to their original settings.

    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.

    Hover help

    Select the Hover help choice if you want hover help to be shown.

    Infoarea

    Select the Infoarea choice if you want the information area to be shown in the window.

    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.

    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.


    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. Note that registers that change after a run or a step are highlighted by using reverse video.

    Figure 26. Registers Window

    * Figure merregw not displayed.


    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 * Figure icon9 not displayed. from the tool bar.

    Drag-and-Drop Function

    The Registers window can be used as a source or a target for drag-and-drop operations. All register values that are dragged are treated as hex numbers. When an item is dropped into the Registers window, it is dropped on the register under the mouse when the mouse button is released. This register will be updated with the value from the drag operation.

    See "Using the Drag-and-Drop Function" for more information about the drag-and-drop function.

    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.

    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.

    Fonts...

    When you select Fonts..., the Font window displays. From this window, select the font you want shown in the Registers window.

    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.

    Figure 27. Display Style Window

    * Figure gamrgds not displayed.


    Groups Group Heading

    This specifies the five types of registers that the debugger displays. General registers are as follows:

    Status Flags registers include the PC and the EFLAGS registers. Segment registers are as follows:

    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. The MMX registers include MM0 through MM7.

    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.

    Restore defaults

    Select the Restore defaults choice to reset all of the window settings to their original settings.

    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.

    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.

    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.

    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.

    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.


    Using the Storage Window

    The Storage window shows the storage contents and the address of the storage.

    Figure 28. Storage Window

    * Figure gamstgw not displayed.


    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. Note that if you update (patch) a code area in the Storage window, the disassembly of that code is automatically adjusted by the debugger.

    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 * Figure icon11 not displayed. from the tool buttons.

    Drag-and-Drop Function

    The Storage window can be used as a source or a target for drag-and-drop operations. The item that is dragged is the item in the column under the mouse. You cannot drag a portion of the column. When items are dropped in the address portion of the Storage window, the Storage window adjusts to show memory at this new address. When items are dropped in the content fields of the Storage window, the item in the column under the mouse is updated. Columns that display hex values can only have hex values dropped on them. Columns that display strings can only have strings dropped on them.

    See "Using the Drag-and-Drop Function" for more information about the drag-and-drop function.

    File Menu Choices

    Use the choices from the File menu to save the contents of the Storage window to a file or to end the debugging session.

    Save to file

    The Save to file choice saves the contents of the Storage window to a file. You can choose the file name by selecting Options -> Display Style from the Storage window and filling in the Save file field.

    Close debugger

    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.

    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.

    Fonts...

    Displays the Font window, which allows you to select the type of font you want to use for the Storage window.

    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.

    Figure 29. Display Style Window

    * Figure gamsdsw not displayed.


    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. Scroll to the address style you want.
    2. Select the address style.
    3. 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.

    Use the Save file entry field to identify the file where the Storage window saves its contents when the Save to file choice is selected.

    Fill Storage...

    Displays the Storage Fill Dialog window, which allows you to fill memory with a specific character or hexadecimal pattern.

    Figure 30. Fill Storage Dialog Window

    * Figure filstor not displayed.


    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.

    Monitor expression...

    Displays the Monitor Expression in Storage window, which allows you to type in the name of the expression you want to monitor.

    Figure 31. Monitor Expression in Storage Window

    * Figure gamsmew not displayed.


    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.

    Restore defaults

    Select the Restore defaults choice to reset all of the window settings to their original settings.

    Tool buttons

    Select the Tool buttons choice if you want tool buttons.

    Hover help

    Select the Hover help choice if you want hover help.

    Infoarea

    Select the Infoarea choice if you want the information area to be shown in the window.

    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.

    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.


    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.

    Figure 32. Local Variables Window

    * Figure ctxt1 not displayed.


    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.

    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.

    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.

    Select all

    Select the Select all choice to select all the expressions in the window.

    Deselect all

    Select the Deselect all choice to cancel the selection of all the expressions in the window,

    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 CAT_DEBUG_NUMBER_OF_ELEMENTS. For example, you would type the following to change it to 100:

       set CAT_DEBUG_NUMBER_OF_ELEMENTS=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.

    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.

    Copy to clipboard

    Select the Copy to clipboard choice to copy the selected (highlighted) local variable data to the clipboard.

    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.

    Options Menu Choices

    Select choices from the Options menu to control how the contents of variables display and set debugger options.

    Fonts...

    Displays the Font window, which allows you to select the type of font you want to use for the Local Variables window.

    Restore defaults

    Select the Restore defaults choice to reset all of the window settings to their original settings.

    Show context

    Select the Show context choice to display the contextual information for the variable you are monitoring. The following information displays:

    Tool buttons

    Select the Tool buttons choice if you want tool buttons.

    Hover help

    Select the Hover help choice if you want hover help.

    Infoarea

    Select the Infoarea choice if you want the information area to be shown in the window.

    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.

    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.


    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.

    Figure 33. Passthru Window

    * Figure gampass not displayed.


    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    Find Next

    Select Find Next to search for the next occurrence of the text string that you typed in the Find window.

    Options Menu Choices

    Select choices from the Options menu to change the font and control what items are shown in the Passthru window.

    Fonts...

    Displays the Font window, which allows you to select the type of font you want to use for the Passthru window.

    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.

    Figure 34. Display Style Window

    * Figure gamptds not displayed.


    To use the Display Style window:

    Restore defaults

    Select the Restore defaults choice to reset all of the window settings to their original settings.

    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

    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.

    Hover help

    Select the Hover help choice if you want hover help.

    Infoarea

    Select the Infoarea choice if you want the information area to be shown in the window.

    Resync with ring 3

    Select the Resync with ring 3 choice when you want the debugger to act as though it is in the ring-3 context just before it entered the kernel on the current thread. This assumes that the current thread is at ring 0. You can examine the ring-3 context in this manner to see what contributed to a system failure.

    Note: Do not step or go once you have changed to a ring-3 context before issuing the Resync push button! The Resync push button re-establishes your ring-0 context.

    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.

    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.


    Using the Monitor Windows

    The debugger has four other windows that allow you to monitor variables and expressions. These windows are as follows:

    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.

    Drag-and-Drop Function

    Monitor windows can be used as a source or a target for the drag-and-drop operations. You can drag either the variable/expression or the value of a monitor.

    Note: The context is not dragged with the monitor, so some variables/expressions may not be accepted in other windows. When an item is dropped on a monitor item, that monitor item is updated with the new value. When an item from the Source window is dragged onto a monitor in white space, that variable/expression is added to the monitor. Adding variables/expressions this way is only supported in the Private and Program monitors.

    See "Using the Drag-and-Drop Function" for more information about the drag-and-drop function.


    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:

    To display the Breakpoints List window, select List from the Breakpoints menu or select the Breakpoints button * Figure icon12 not displayed. in the tool bar.

    Figure 35. Breakpoint List Window

    * Figure break00 not displayed.


    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.

    Edit Menu Choices

    Select the choices from the Edit menu of the Breakpoints List window to delete, disable, modify, or enable breakpoints.

    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.

    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.

    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.

    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.

    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.

    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.

    Set Menu Choices

    Refer to "Breakpoints Menu Choices" for a description of the Set menu choices.

    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.

    Fonts...

    Displays the Font window that allows you to select the font you want to use for the text in the Breakpoints List window.

    Display style...

    Displays the Display Style window, which allows you to control how the items appear in the Breakpoints List window.

    Figure 36. Breakpoints - Display Style Window

    * Figure merbds not displayed.


    To change the columns which are displayed in the Breakpoint List window:

    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.

    Sort

    Displays the Sort window, which allows you to sort the breakpoints by the characteristics of the breakpoint.

    Figure 37. Sort Window

    * Figure ctxt2 not displayed.


    Use the Sort window to sort the breakpoints that have been set in your program.

    Breakpoints can be sorted according to the following categories:

    Select the category you want and select the OK push button.

    Restore defaults

    Select the Restore defaults choice to reset all of the window settings to their original settings.

    Tool buttons

    Select the Tool buttons choice if you want tool buttons.

    Hover help

    Select the Hover help choice if you want hover help.

    Infoarea

    Select the Infoarea choice if you want the information area to be shown in the window.

    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.

    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.


    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.


    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:

    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.


    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


    Supported Data Types

    You can monitor an expression that uses the following typecasting operations:


    Index

    A B C D E F G H I J K L M O P R S T U W
    A
  • address breakpoint (76)
  • attaching to the OS2KRNL (41)
  • B
  • before you begin debugging (7)
  • breakpoint list (82)
  • Breakpoints List window (114)
  • breakpoints menu (67)
  • C
  • Call Stack window (100)
  • change watchpoint (78)
  • close debugger (66)
  • closing the debugging session (44)
  • CodeView (6)
  • compiling your program (10)
  • components box (58)
  • D
  • data types, valid (121)
  • Debug Session Control window (54)
  • debugging windows (53)
  • defer breakpoint (72)
  • delete all breakpoints (83)
  • demo (35)
  • drag-and-drop function, using
  • Monitor windows (113)
  • Registers window (103)
  • Source window (89)
  • Storage window (106)
  • E
  • ending the debugging session (43)
  • enumerated variable (118)
  • environment variables
  • CAT_COMMUNICATION_TYPE (16)
  • CAT_DEBUG_NUMBER_OF_ELEMENTS (26)
  • CAT_DIAL (21)
  • CAT_HOST_BIN_PATH (15)
  • CAT_HOST_SOURCE_PATH (17)
  • CAT_MACHINE (13)
  • CAT_MODEM_INIT (22)
  • CAT_MODULE_LIST (19)
  • CAT_OVERRIDE (23)
  • CAT_PATH_RECURSE (18)
  • CAT_RESUME (20)
  • CAT_SETUP_RATE (14)
  • CAT_TAB (24)
  • CAT_TAB_GRID (25)
  • executing a program (49)
  • expression operands (116)
  • expression operators (119)
  • expression, monitor (91)
  • expressions supported (115)
  • F
  • Find Function window (62)
  • finding source files (27)
  • frequently used features (45)
  • function breakpoint (74)
  • G
  • getting started (36)
  • H
  • halt (85)
  • hardware requirements (8)
  • hide debugger on run (86)
  • HLL (5)
  • I
  • ICAT debugger (2)
  • include environment variable (33)
  • Initialization window (40)
  • introducing the basic windows (99)
  • introduction to the debugger (1)
  • J
  • jump to location (97)
  • K
  • Kernel Debugger (KDB) (4)
  • L
  • line breakpoint (71)
  • Line Breakpoint window (69)
  • linking your program (11)
  • list breakpoints (81)
  • load occurrence breakpoint (80)
  • Local Variables window (107)
  • location, jump to (98)
  • M
  • monitor expression (90)
  • Monitor windows (111)
  • O
  • open new source (59)
  • Open New Source window (61)
  • operands, valid expression (117)
  • operators, valid expression (120)
  • OS/2 Warp Version 4 system (3)
  • OS2KRNL, attaching (42)
  • P
  • parameters (38)
  • Passthru window (108)
  • popup menu, thread (57)
  • program profile information (39)
  • R
  • Register window (101)
  • REXX command files (110)
  • run (84)
  • run to location (96)
  • S
  • save component list in file (65)
  • save thread list in file (64)
  • search path
  • CAT_HOST_BIN_PATH (30)
  • CAT_HOST_SOURCE_PATH (31)
  • CAT_OVERRIDE (29)
  • INCLUDE (32)
  • sending commands to KDB (109)
  • set address breakpoint (75)
  • set function breakpoint (73)
  • set line breakpoint (68)
  • set load occurrence breakpoint (79)
  • set watchpoint (77)
  • setting breakpoints (50)
  • setting line breakpoint (70)
  • software requirements (9)
  • source windows (55)
  • source, open new (60)
  • starting the debugger from OS/2 (37)
  • step debug (94)
  • step into (93)
  • step over (92)
  • step return (95)
  • Storage window (104)
  • T
  • threads box (56)
  • tool buttons (46), (48)
  • typecasting, data types in monitors (122)
  • U
  • using the demo (34)
  • using the drag-and-drop function (51)
  • Monitor windows (112)
  • Registers window (102)
  • Source window (88)
  • Storage window (105)
  • using the source windows (87)
  • using the tool buttons (47)
  • W
  • where is execution point (63)
  •