This document contains information to help you install, get started, and perform tasks with the Interactive Code Analysis Tool (ICAT) debugger.
If you need assistance from any window while using the debugger, press F1 from any window or choose the Help menu.
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.
The ICAT Debugger (hereafter referred to in this document as the debugger) is a source-level debugger which uses 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 target OS/2 Warp Version 4+ computer and replies to debug service requests that are sent from the debugger while running on an Intel-based OS/2 Warp Version 4+ computer. The supported communications mode between the target and host computers is serial or UDP.
Supported debug file formats include HLL (which is IBM VisualAge C++ (VACPP)) and CodeView (CV).
This section lists the minimum hardware and software requirements, options for compiling and linking your program, environment variables, and limitations.
There are software requirements for both the target computer where the programs are debugged and run and the host computer where the debugger runs.
Target Computer
OS/2 Warp Host Computer
Before using the debugger, you need to compile and link your program.
For VACPP programs, use the following options:
Note: When you specify the /Ti+ option with the /DEbug option, icc passes this option to the linker automatically, so you only need to use it if you link separately from the compile.
For more information about compiling and linking your program, refer to IBM C++ Tools Programming Guide.
For Microsoft CL, CL386, MASM, and MASM386 programs, use the following options:
For Watcom wpp386 programs, use the following options:
For the Watcom linker, wlink, use this option:
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 creates a .sym file. Be careful not to confuse this file with a KDB .sym file. The debugger looks for debug information first in the application file. If it doesn't find it, it looks for the debug information in a .dbg file and then in a .sym file as a last resort. Most users rename the separate Watcom .sym file to a .dbg file.
The Debugger enables you to view limited symbol information in the Disassembly view of an executable file compiled with no debug information if a separate symbol file is supplied.
Using the link symbol information from a separate symbol file (*.sym) function names are annotated to the disassembly lines for function calls and function entry points, making it easier for you to navigate through disassembly code.
To enable viewing of the symbol information in Disassembly view:
Whether the executable is located on the target machine, or both host and target machines, there is no difference in performance. Currently, the symbol file must be located on the host machine.
If the executable to be debugged was compiled to enable a separate map file to be generated, then the symbol file is obtained by running the MapSym.exe utility on that map (.map) file. Make certain that the symbol file has the same name as the executable.
The debugger uses environment variables to manage debugging sessions and remote communication. To set the environmental variables, edit the SETICAT.CMD file. The environment variables should be set in the OS/2 session where the debugger is to be run. Following is a list of the variables and a description of each:
Specifies which host COM port the debugger uses to communicate with KDB and the baud rate for communication. This variable has the following form:
COMx:nnnnwhere 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 target computers. 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.
Specifies the IP address and KDB port number of the target computer. This variable has the following form:
x.x.x.x:nnnn
where x.x.x.x is the IP address and nnnn specifies the KDB port number.
For example, type the following at the command prompt:
SET CAT_MACHINE=9.242.116.9:1000
In most cases, you do not need to set CAT_SETUP_RATE. It is primarily useful if you have been communicating with the target computer 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.
This variable is ignored if the debugger communicates using the LAN.
Additionally, if this environment variable is set, the debugger resets KDB to this rate when the debugger is closed.
For example, type the following at the command prompt:
SET CAT_SETUP_RATE=9600
For example, type the following at the command prompt:
SET CAT_HOST_BIN_PATH=I:\SDE\SAMDETW
For example, type the following at the command prompt for serial communication:
SET CAT_COMMUNICATION_TYPE=ASYNC_SIGBRKor type the following for LAN communication:
SET CAT_COMMUNICATION_TYPE=UDP
For example, type the following at the command prompt:
SET CAT_HOST_SOURCE_PATH=I:\SDE\SAMDETW;E:\ICAT\TESTCASES\SRC
For example, type the following at the command prompt:
SET CAT_PATH_RECURSE=ON
For example, type the following at the command prompt:
SET CAT_SOURCE_PATH_RECURSE=ON
If CAT_PATH_RECURSE is set ON, the debugger performs as if both CAT_BINARY_PATH_RECURSE and CAT_SOURCE_PATH_RECURSE are ON.
For example, type the following at the command prompt:
SET CAT_BINARY_PATH_RECURSE=ON
If CAT_PATH_RECURSE is set ON, the debugger performs as if both CAT_BINARY_PATH_RECURSE and CAT_SOURCE_PATH_RECURSE are ON.
For example, type the following at the command prompt:
SET CAT_MODULE_LIST=SAMPLEDD.SYS SAMPLE.EXE
The debugger only obtains 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.)
There could be situations where you want to initialize the debugger but somehow time your attach to the target computer using the Attach button. In this case, define CAT_RESUME, and then the debugger resumes the target computer waiting for your attach command to stop it again.
For example, type the following at the command prompt:
SET CAT_RESUME=ON
Note: The host and target computers can be connected directly (with a null-modem serial cable) or by a modem.
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
For example, type the following at the command prompt:
SET CAT_OVERRIDE=e:\temp\updates
For example, type the following at the command prompt:
SET CAT_TAB=5
The debugger converts each tab in the source to 5 spaces when the source is displayed.
For example, typing the following command at the command prompt sets tab stops at the 6th position:
SET CAT_TAB_GRID=6
Note: CAT_DEBUG_NUMBER_OF_ELEMENTS is an environment variable that is set to an integer, n.
For example, type the following at the command prompt:
SET CAT_DEBUG_NUMBER_OF_ELEMENTS=100
The next 100 elements are displayed.
For example, type the following at the command prompt:
SET CAT_DEBUGGER_NAME=target 1
This is useful if you want to run multiple copies of the debugger from a single host computer to debug multiple systems.
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:
Notes:
The debugger has the following restriction:
In serial mode, the target computer communicates over COM2 if COM2 exists and over COM1 otherwise. The COM port that the target computer uses must not be usurped by an application. For example, if the target computer is using COM2 and you issue the following command:
mode com2
you may disrupt communication. The device driver and executables associated with the IBM LAN Management Utilities (for example, LMUIPL.SYS) can also prevent the target computer from communicating. (Note that KDB can be directed to use a particular COM port by way of the KDB.INI file.)
Similarly, the COM port the host computer uses in serial mode 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.
This section describes how to set up the target and host computers, includes a demonstration session to help you get started, explains how to start a debugging session from the OS/2 command prompt, includes helpful tips, troubleshooting and how to end a debugging session.
To set up the target network computer:
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
DEVICE=x:\y\KDBNET.SYS /V /Id.d.d.d /Ppppp
where x and y are the drive letter and path to the directory where you wish to store KDBNET.SYS. The IBMCOM subdirectory is probably the most convenient place to store it.
d.d.d.d is the IP address of the target machine
pppp is the port number on which KDBNET accepts UDP data (1000 is the recommended port number)
kdbnet_nif = kdbnet.nif
[KDBNET_nif] Bindings = IBMFEEO2_nif DriverName = KDBNET$ KDBIPADDR = "d.d.d.d" KDBSNETMASK = "255.255.248.0" KDBPORT = 1000 NMPORT = 1001 BCASTNOTIFY = "YES" NNOACTION = "C"
where d.d.d.d is replaced with the IP address of the machine.
Note: Don't reboot the target machine from the debuggers File menu if KDBNET.SYS is installed on that target. The debugger, KDB, and KDBNET.SYS can't resync in this manner.
To set up the host OS/2 computer:
This demonstration session demonstrates 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:
DEVICE=C:\SAMPLEDD.SYS
This loads the sample device driver when you reboot the target computer.
You can perform a quick check to see if the target computer is OK by running your normal terminal emulator (T, ZOC, and so on). This shows if KDB is communicating at 9600 baud.
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.
Note: If you change the state of the target computer with KDB commands in the Passthru window, you must click the Resync button to allow the debugger to reflect the changes.
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 is set at the baud rate you used to communicate with the debugger.
To start the debugger:
The Initialization window is displayed.
Figure 1. Initialization Window
Note: It's usually a good idea to have set up your environment variables by way of a SETICAT.CMD file before invoking the debugger. See "Environment Variables" for more information.
A tool bar has been provided on the debugger windows for easier access to frequently used features. To display buttons in a window, enable the Tool Buttons choice (located within the Options menu). The following is a list of features that are provided:
When the debugger is running, the Run button
is disabled and the
Halt button
is enabled.
You can click on the Halt button to halt the program
execution. You can also interrupt the program you are debugging
by selecting the Halt choice from the Run
menu.
The following tips and hints might be helpful:
ICAT allows you to manipulate any thread running on the target computer. 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, and so on. The title of a thread-specific window includes the thread's identifier as shown in the Debug Session Control window (see "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, you attach to the target computer and want to set a breakpoint. If the breakpoint is in a shared region (for example, in a device driver, a DLL, or the kernel), it doesn't 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.
Following are some things to check when the debugger is not doing what you think it should:
If debugging serially:
If debugging using the LAN:
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.
This section introduces the Debug Session Control window and how to perform functions from this window. It also introduces the three source windows that offer different views of your source code.
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: Threads and Components.
Right-click on a selected item to display the Thread menu and press F1 to view help for this item.
Right-click on a selected item to display the Component menu and press F1 to view help for this item.
Figure 2. Debug Session Control Window
From the Debug Session Control window you can select menus that enable you to:
You can open additional source files from the Debug Session Control window.
To open a new source file:
For example, to look for the source used to compile A123.OBJ, type the following in the Source field:
A123
If you are uncertain of the file name, click the File list button to view a list of files that you can select.
You can use the Find Function window to open a source window to a particular function.
If the function that you specify is not found, the following message is displayed:
No matching function found. Desired function could be static.
This means it might be a static function or the function you specified does not exist.
The debugger searches each object file for global functions that match the function name specified. If an object file contains the global function that was specified, then it also searches that file for any static function with the same name.
To locate the execution point in your source, click Where is execution point (located within the File menu). A source window is displayed containing the next line to be executed.
If you want to save the contents of the Threads pane view in a file, click Save thread list in file (located within the File menu). This saves the view in a file named threads.out. To change the default file name, click Options, Window settings, and then Display style (located within the Debug Session Control window) and type the file name in the Threads output file field.
If you would like to save the contents of the Components pane view in a file, click Save component list in file (located within the File menu). This saves the view in a file named comps.out. To change the default file name, click Options, Window settings, and then Display style (located within the Debug Session Control window) and type the file name in the Components output file field.
To reboot the target computer while the debugger stays attached, click File and then Reboot target (located within the Debug Session Control window).
If you want to start a debugging session, click File and then Initialization (located within the Debug Session Control window). The Initialization window is displayed. See "Starting a Debug Session" for more information.
You can control program execution by setting breakpoints. A breakpoint stops the execution of your program at a specific location, or when a specific event occurs.
To set breakpoints, click the Breakpoints menu (located on the Debug Session Control window, or located on any source window) and then click the appropriate choice for the type of breakpoint you want to set. When you set a breakpoint in one source window, it is reflected in the other source windows. In addition, you can set a simple line breakpoint in a source window using either the mouse or the keyboard:
Note: You can set as many breakpoints as you want.
You can set either line, function, address, watchpoint, or set load occurrence breakpoints.
A line breakpoint enables you to stop the execution of your program at a specific line number.
You set a line breakpoint from the Line Breakpoint window. To display the window, from the Breakpoints menu, click Set line.
Figure 3. Line Breakpoint Window
The Line Breakpoint window is divided into two group headings: Required Parameters and Optional Parameters.
Required Parameters:
Optional Parameters:
Click Every, the default, to set a breakpoint in all of the active threads in your program. The Every choice is thread independent. Select one of the individual threads to set a breakpoint in only one thread. Threads are added to the Thread list as new threads are activated.
Note: The Frequency fields (From, To, and Every) are used for location, address, and load occurrence breakpoints.
(i==1) || (j==k) && (k!=5)
Note: Variables in a conditional expression associated with a function breakpoint are limited to any static or global variables that are known to the called function when the function is called. The debugger does not always evaluate local variables and automatic variables correctly.
The maximum length of the condition is 256 characters.
A function breakpoint stops the execution of your application when the first instruction of the function is encountered where the breakpoint has been set.
You set a function breakpoint from the Function Breakpoint window. To display the window, click Set function (located within the Breakpoints menu).
To set a function breakpoint:
If a function is overloaded, a window is displayed with a list of all the overloaded function names. Click the appropriate function from the list.
For a description of the fields under the Optional Parameters group heading, see Optional Parameters.
An address breakpoint enables you to stop the execution of your application at a specific address.
You set an address breakpoint from the Address Breakpoint window. To display the window, click Set address (located on the Breakpoints menu).
To set an address breakpoint:
For example, to set an address breakpoint for the address 0x000A1FCC, you would type one of the following in the Address field:
0x000A1FCC or A1FCC
The 0x is optional.
For a description of the fields under the Optional Parameters group heading, see Optional Parameters.
A watchpoint stops the execution of your application when contents of memory at a given address are referenced or when an instruction is fetched from a particular address.
You set a watchpoint from the Watchpoint window. To display the window, click Set watchpoint (located within the Breakpoints menu).
To set a watchpoint:
Note: If you type ABC in the Address (or expression) field, and there is a variable named ABC, the value of the variable is used instead of the hex value ABC. Also, you can type &a in the field to set the watchpoint on the address of variable a.
For example, type the following in the field to set a watchpoint for the address A1FCC.
A1FCC
Type the following in the field to set a watchpoint for the expression &variable.
&variable
The debugger supports four types of watchpoints. They are as follows:
Attention: 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 is removed from the stack leaving the watchpoint intact. Any other routine that gets loaded on the stack then contains the watchpoint. You can set up to four watchpoints.
For a description of the Optional Parameters group heading, see Optional Parameters.
Note: The debugger will monitor 1, 2, or 4 bytes for the type of watchpoint operation that you select. This choice is made for you on the Instruction fetch type.
A load occurrence breakpoint stops the execution of your application when a specific module is loaded.
You set a load occurrence breakpoint from the Load Occurrence window. To display this window, click Set load occurrence (located within the Breakpoints menu).
To set a load occurrence breakpoint:
Execution stops when the module is loaded.
To set a load occurrence breakpoint when MY.CLASS is loaded, you would type one of the following in the Module name field:
MY or MY.CLASS
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 is not reported. If the module cannot be found in the module search path, the module name is not accepted. See "Setting Debugger Properties" for information on identifying modules.
For a description of the fields under the Optional Parameters group heading, see Optional Parameters.
The Breakpoints List window lists all the breakpoints that have been set in your application. It also displays the state of each breakpoint.
To display the Breakpoints List window, click List (located within the Breakpoint menu of the Debug Session Control window).
Figure 4. Breakpoints List Window
The following information is provided for each breakpoint:
From the menu on this window you can:
Clicking Debugger properties (located within the Options menu of the Debug Session Control window) enables you to select how the threads and source files are initially displayed. The Debugger Properties window contains three tabs:
When you click the Remote tab (located on the Debugger Properties window), the following page is displayed:
Figure 5. Debugger Properties Window - Remote Page
From the Remote page you can:
Note: The values for this window are dithered and cannot be changed after communication has been established with the target computer.
To change your communication setting paths dynamically before communication is established with the target computer, adjust any of the Environment Variables fields. See "Environment Variables" for detailed information on environment variables.
These fields correspond respectively to the following environment variables:
If you select the Recursive file searching check box the debugger searches all source and binary path subdirectories recursively.
When you click the Source tab (located on the Debugger Properties window), the following page is displayed:
Figure 6. Debugger Properties Window - Source Page
Use this page to determine:
To display the source view of all threads or a particular thread when execution stops, choose any selection located under the Display at stop group heading.
In the course of debugging, the Old Source Disposition selections enable you to control the behavior of source windows following command execution. These radio buttons control the behavior of source windows within a thread.
The dispositions that the views can take are:
You can choose to display more than one source window for a particular source file. Enable the Multiple views check box located under Settings if you want multiple source windows open at the same time.
To select functions you want to perform with the right mouse button, choose the radio button that represents the action located under Mouse Button 2 Behavior.
When you click the Modules tab (located on the Debugger Properties window), the following page is displayed:
Figure 7. Debugger Properties Window - Modules Page
From this page you can add a module name to or delete a module name from the CAT_MODULE_LIST environment variable. See "Environment Variables" for detailed information on this environment variable.
The Modules list box displays a list of the modules that 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.
To add a new module, type the name of the new module in the New module field and click the Add button.
You can delete a module or a group of modules, select the modules in the Modules list box that you would like to delete and click either the Delete button or the Delete all button.
To select the settings for monitoring variables or expressions:
Figure 8. Monitor Properties Window
From this window you can set the following:
A source window enables you to view the program you are debugging. You can view your source in one of the following windows:
The Source window displays the source code for the current function of the program being debugged. If source is available, the Source window is displayed with the Debug Session Control window when the debugging session starts; otherwise, the Disassembly window is displayed.
A source window is thread specific. Executable lines are initially displayed in blue, and nonexecutable lines are initially displayed in black. Lines with breakpoints have a red prefix, and lines with disabled breakpoints have a green prefix.
The Disassembly window displays the assembler or bytecode instructions for your program without symbolic information.
The Mixed window displays your program as follows:
Note: The Mixed window cannot be opened if the source code is not available.
Each of the source windows have menus. The menus are the same as the Debug Session Control window menus (see the Debug Session Control window menus) with the following exceptions.
This choice enables you to save the current source view to a named file.
You can also use the Scroll to Line number window to set a breakpoint. In the Line field, enter the line number and then click the Breakpoint button.
Toggle at current line sets a breakpoint on the current line or deletes an existing breakpoint from the current line.
Enables you to monitor expressions or variables and add them to various monitor windows.
Note: If you need help with any of the menus, press F1 while the menu is selected.
You can execute a program from any of the source windows (Source, Mixed, or Disassembly) using step commands or the Run command.
The step commands are located in the tool bar of the source windows and under the Run menu of the source windows.
You can start the Run command from the Run button (located on the tool bar) or the Run menu of the source windows.
When you execute a program, a clock icon is displayed to indicate that the program is running and that the program might require input to continue to the next breakpoint or termination of the program.
To open Monitors windows, from the Monitors menu of the Debug Session Control window, click any of the following choices:
These windows are also accessible from the tool bar of the source windows. See "Using the Tool Buttons" for more information about the tool bar.
You can view all of the active functions for a particular thread including system calls from the Call Stack window.
The Call Stack window lists all of the active functions for a particular thread including system calls.
To display the Call Stack window,
click Call Stack (located within
the Monitors menu) or click the Call Stack
button (located on the tool bar).
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 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.
From the menus of the Call Stack window you can:
Choose the file name by clicking Options and then Display style. Enter the file name in the Save file field.
Note: If you need help with any of the menus, press F1 while the menu is selected.
You can view all the processor registers for a particular thread from the Registers window.
To display the processor registers and flags,
click Registers (located within the
Monitors menu) or click the Registers
button (located on the tool bar).
The contents of all of the registers except floating-point registers are displayed in hexadecimal. To update a register, double-click the register and a multiple-line field is displayed. Type over the contents and press Enter. If you decide not to change the value, press Esc.
In the Registers window, floating-point registers are displayed 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.
From the menus of the Registers window you can:
The Storage window shows the storage contents and the address of the storage.
To display the Storage window, click
Storage (located within the Monitors menu)
or click the Storage button
(located on the tool bar).
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 field that is displayed. Type over the contents of the field. If you decide not to make the change, press Esc.
To specify a new address location, type over the address field in the Storage window. The window scrolls to the appropriate storage location.
From the menus of the Storage window you can:
Choose the file name by clicking Options and then Display style. Type the file name in the Save file field.
The expression evaluator used is based on the context. For example, if you display the Storage window by clicking Monitor expression (located within 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 click Monitor expression (located within 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 select 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.
Note: If you need help with any of the menus, press F1 while the menu is selected.
You can monitor the local variables (static, automatic, and parameter) for the current execution point in the program from the Local Variables window. The contents of the Local Variables window change each time your program enters or leaves a function.
To display the Local Variables window, click Local Variables (located within the Monitors menu).
Figure 15. Local Variables Window
From the menus of the Local Variables window you can:
You can also save the Local Variables window contents in a file. Select Options, Debugger settings, and then Monitor properties from the Debug Session Control window or any of the source windows and enter the file name in the Save file field.
Note: If you need help with any of the menus, press F1 while the menu is selected.
The Passthru window allows you to send commands to KDB and view its responses. The window has a Command entry field where you enter the KDB commands, and a response area that displays the KDB output.
The KDB response area can be scrolled, which enables 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.
To display the Passthru window, click Passthru (located
within the Monitors menu) or click the
Passthru button
(located on the tool bar).
To send a command to KDB, do the following:
Note: Avoid commands that cause the target computer to resume execution (for example, g and t). 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.
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.cmdwould trigger the execution of the DEBUGO REXX command file memcount.cmd.
From the Passthru window you can:
Use the Messages window to view printfs that are emitted by the kernel (diagnostic) code. The contents of this window can be updated even while the debugger has control and your program is quiesced.
To display the Messages window, click Messages
(located within the Monitors menu)
or click the Messages button
(located on the tool bar).
From the messages window you can:
Choose the file name by clicking Options from the menu and then Display style. Type the name of the file in the File Name field.
Note: If you need help with any of the menus, press F1 while the menu is selected.
The debugger has four other windows that enable 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.
This section describes the expressions 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.
You can monitor an expression that uses the following types of operands only:
Note: The largest floating-point constant in C/C++ is 1.8E308. The smallest floating-point is 2.23E-308.
If you monitor an enumerated variable, a comment is displayed 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 are displayed as an empty field.
The comment (empty or not) lets you distinguish between a valid enumerated value and a value that is not valid. A value that is not valid does not have a comment to the right of the value.
You cannot 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 is updated.
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.
You can monitor an expression that uses the following operators
only:
Table 1. Supported Expression Operators
| Operator | Coded as |
|---|---|
| Subscripting | a[b] |
| Member selection | a.b or a->b (a->b for C/C++ only) |
| Size | sizeof (a) or sizeof (type) (C++ only) |
| Logical not | !a |
| One's complement | ~a |
| Unary minus | -a |
| Unary plus | +a |
| Dereference | *a (C/C++ only) |
| 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 |
You can monitor an expression that uses the following data types:
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 International Business Machines Corporation 1999. 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.
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
North Castle Drive
Armonk, NY 10504-1785
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
ThinkPad
Intel and Pentium are registered trademarks of the Intel Corporation in the United States and/or other countries.
Other company, product, and service names may be trademarks or service marks of others.