TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Using the Ada Debugger

The Apex debugger provides a variety of facilities for analyzing the behavior of programs developed using Apex. After you start the debugger, program execution is under your control. You can cause the program to execute; you can cause program execution to stop and wait for you to request further progress; you can examine source and object; and you can perform other debugging functions. The debugger is case-insensitive.

Prerequisites for this Module

Submodules in this Module

Average Time to Complete this Module

90 minutes.


Setting Up the Ada Debugger Tutorial

The setup for the Debugger module takes about 10 minutes.

Note: You must execute the debugger setup in order to perform the debugger exercises. This will place the sample code in $HOME/project1.ss/motion.wrk (Apex/Summit) or <vob_dir>/project1.rss (Apex/ClearCase), hereafter called the <debugger_sample_dir>

For Apex/Summit:

The setup creates the $HOME/project1.ss/motion.wrk subdirectory.This view contains source code and an executable for the planetary_motion program that is used in the debugger module. All the Ada code in this view is controlled.

To set up the debugger tutorial view, in an Apex xterm (created by the Tools > Shell command or click the Shell button on the Apex Panel Window), enter:

For Apex/ClearCase:

The setup creates the <vob_dir>/project1.rss Rational subsystem. This Rational subsystem contains source code and an executable for the planetary_motion program that is used in the debugger module. All the Ada code in this view is controlled.

Warning: You must be in the VOB directory when running this script.

To set up the debugger tutorial Rational subsystem, in an Apex xterm (created by the Tools > Shell command or click the Shell button on the Apex Panel Window), enter:

The setup is complete when a directory viewer containing <debugger_sample_dir> is visited. Please do not try to continue until this window is displayed. The Jobs window is displayed several times as the <debugger_sample_dir> is being set up. If the Frame cursor is reactivated and the directory viewer window is not displayed, please see your system administrator and do not continue.

This might be a good time to take a break.

Running the Ada Planetary Motion Program without the Debugger

You are first going to run the program without the debugger just to see what it does. You can start running a program by either issuing a File > Run command, or by double-clicking on the executable name in a viewer window. Either method displays the Run dialog box so you can enter the program's name and any required arguments.

You are going to run the planetary_motion program.

1. . Double-click on the planetary_motion* object in the <debugger_sample_dir> viewer window. Note that the standard UNIX file types are also displayed (* is an executable) making it easier to identify executables.

2. . In the Run/Debug dialog box, select the Direct output to an xterm option. Select OK to run the program.

In an xterm window with the title of execute of <debugger_sample_dir>/planetary_motion, the program will begin executing.

The upper portion of the window displays the two planets orbiting the sun (*). Note that the two orbits are in opposite directions and are updated frequently.

The lower portion of the window displays the velocities and coordinates of each planet.

3. . Enter Control-C in the xterm window to kill this program.


Getting Started with the Debugger

Prerequisites

Topics in this Submodule

Time to Complete the Submodule

10 minutes.


Starting to Debug a Program

You are going to run the same program, planetary_motion, but this time with the debugger.

1. . Double-click on the planetary_motion* object in the viewer window.

The Run/Debug dialog box is displayed.

2. . Select the Debug tab in the Run/Debug dialog box.

3. . Click on OK in the Run/Debug dialog box.

The Apex debugger can be configured to behave in one of two modes for the display of source code: either through one of the editors or through its own source pane in the debugger window. You can configure the default source display method when the debugger starts up and you can toggle between modes during a debugging session by using the View > Show Source command. Directions for doing this can be found in Using the Apex Debugger.

Using an Apex editor to display source allows you to retain the full capabilities of the editor while you're debugging. For example, you can perform configuration control operations, compilation, or editing operations during a debugging session.This display mode is called Editor mode. It is the default.

The debugger's source display is optimized for debugging. It doesn't provide facilities for editing, compilation, or source control, for example. It does provide extra features specifically designed for debugging. For example, it contains source indicators that show where breakpoints are set. This mode is called Show Source mode.

We will be using the editor mode for this tutorial. This is the default mode.

The clock cursor is displayed as execution is started:

Automatic Debugger Windows

The Debugger Log Window

When the debugger is initially created, it automatically creates the Debugger Log window in which to record the status of the debugger. All interactions with the debugger are displayed in the Debugger Log window as a sequential log.

After you click on the OK or Apply button in the Run/Debug dialog box, the Debugger Log is raised and displays the current information on the job you are debugging:

The first message tells you the complete UNIX pathname of the executable.

As you do more in your debugging session, the number of messages displayed as you start debugging a program may increase.

The Input/Output Window

By default, the Input/Output window is also raised when you start debugging the program. This is not an Apex window, but a standard Motif xterm in which the planetary_motion program executes.

Starting Execution

You are going to execute the planetary_motion program, identify a program bug, and then kill the program.

1. . Iconify the Jobs window because it will not change as we run this program.

2. . Move the Input/Output window so that you can view both the Input/Output window and the Debugger Log window.

3. . In the Debugger Log window, select Execution > Continue to execute the program.

You want to run this program without issuing debugging commands, so the Continue command starts the program executing and only stops for breakpoints and exceptions. Because the program loops forever, you will need to stop or kill it. Note that the menu bar in the Debugger Log window is shaded when the program is executing.

As the planetary_motion program runs, note that the planet information at the lower left-hand corner of the Input/Output window is not formatted correctly. You are going to locate and correct this formatting bug as you learn about breakpoints, stepping, and displaying objects.

4. . In the Debugger Log window, select File > Kill.

The Input/Output window is automatically closed. The Debugger Log window displays messages indicating the process has been stopped.


Setting Breakpoints

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

10 minutes.

Starting Execution with the Debugger

You are going to start executing the planetary_motion program again so you can learn more about the debugger. This time you are going to use the File > Debugcommand. The File > Debug command is available in all windows.

1. . In the Debugger Log window, select File > Debug.

The Run/Debug dialog box is displayed.

    Note: From the Debugger Log window, the Run/Debug dialog box defaults the Execute field to the previously run executable during this Apex session. The Debug option is also selected.

    Note: The Run/Debug dialog box defaults depend on which window was used to issue the File > Debug command.

2. . Verify that the Execute field contains the executable <debugger_sample_dir>/planetary_motion.

3. . Verify that the Context field contains <debugger_sample_dir>, your working view.

4. . Click on OK in the Run/Debug dialog box.

The Debugger Log window is raised to tell you that the planetary_motion program is going to be run.

The Input/Output window is raised.

The Jobs window is raised.

5. . Iconify the Jobs window because it will not change as we run this program.

Setting a Breakpoint

Breakpoints define predetermined stopping places in the program. Whenever the conditions associated with a breakpoint are met, the program stops executing, allowing you to perform any debugger function including displaying or modifying objects.

To understand what this program is doing, you are going to set a breakpoint in the Planetary_Motion procedure. One way to set a breakpoint is to use the Ada editor window:

1. . Activate the Ada Editor window containing planetary_motion.2.ada.

This is the main procedure.

2. . Page down this procedure using the scroll bars on the right or by pressing the page-down key on the keyboard until you see the loop statement.

3. . Move the cursor to be on the line:

4. . Issue a Debug > Break Here command in the Ada editor window.

The Debugger Log window displays a message indicating breakpoint on line 71.

The Debug > Break Here command can be used in most situations. If you want to specify additional options, you can enter Control-Debug > Break Here in an editor window or click the Debug > Break... command in any debugger window.

5. . Bring up the Breakpoints window by selecting the Windows > Breakpoints command from the Debugger Log window.

The Breakpoints Window

The Breakpoints window displays all the currently defined breakpoints. The window has an active area that displays the active breakpoints and an inactive area that displays the inactive breakpoints.

A breakpoint is either active or inactive. When a breakpoint is active, it is installed in the program being debugged and will stop a task in which execution reaches the location where the breakpoint is placed (and any task, trip count, or breakpoint conditions are satisfied). When a breakpoint is inactive, it has no effect on the execution of the program.

A breakpoint is either permanent or temporary. Permanent breakpoints remain active as long as the program runs under the debugger or until they are explicitly removed. Temporary breakpoints are automatically deactivated after the first time they are encountered.

Each breakpoint in the Breakpoint window has the following format:

[breakpoint number] file:line number in executable_name

The Debug > Break Here command creates permanent, active breakpoints. You have created breakpoint 1, an active breakpoint listed in the Active area in the Breakpoints window.

Continuing Execution

Now that you have set your first breakpoint, you want the program to execute until it reaches this breakpoint location. Execution will stop before the statement at the breakpoint location is executed.

1. . In the Ada editor window, select Debug > Continue.

The Debugger Log window displays a message indicating that the program has started running. While the program is executing, the menubar background is greyed out.

When the breakpoint location is reached:

The program is now getting ready to display the planet information for the first planet (the planet represented by the + symbol). In the next subtopic, you are going to step though these statements.

Deleting Breakpoints

Now that you are stopped at breakpoint 1, breakpoint 1 can be deleted.

1. . Select the breakpoint 1 line in the Breakpoints window.

The line is highlighted.

2. . Select Breakpoints > Remove.

The Breakpoints window updates to show no breakpoints.

The Debugger Log window displays a message indicating 1 breakpoint has been removed.

3. . In the Breakpoints window, select Close button because there are no breakpoints.

The Online Reference provides additional information on breakpoints.


Stepping Through the Program

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

15 minutes.

Stepping Through Execution

Stepping allows you to control when the execution of a task will be stopped. The Apex debugger considers a statement to be an Ada statement or declaration which has associated assembly code. Some declarations and statements are optimized away, and thus have no associated assembly code. The Apex statements have statement numbers as discussed in the "Setting Breakpoints" topic.

If editor mode is on, whenever the execution of an Ada task stops, the default is:

If source mode is on, whenever the execution of an Ada task stops, the default is:

There are three step commands for source (in order from least detailed to most detailed):
Step Command:
Use:
Step Over
Steps to the next statement in the same context. For example, steps over a subprogram call to the next statement.
Step Into
If the current statement is not a subprogram call, this command steps to the next statement in the same context. If the current statement is a subprogram call, steps to the first statement of the subprogram without stopping in any function that might be evaluated as parameters.
Step Statement
Steps to the next source statement regardless of where it is located. This includes subprograms.

Stepping Over Calls

Before you begin this topic, you should be:

If you are not running the planetary_motion program, you may follow these steps.

If you are not stopped at line 71, you may follow these steps.

You are going to step over the first call to the Put_Summary_Info procedure.

1. . In the planetary_motion.2.ada Ada editor window, select Debug > Step > Step Over.

The debugger:

Stepping Into Calls

You are now going to step into the Put_Summary_Info procedure.

2. . In the planetary_motion.2.ada Ada Editor window, select Debug > Step > Step Into.

The debugger begins executing the call to Put_Summary_Info and stops at the first statement in the Put_Summary_Info procedure.

The Ada editor window with the display.2.ada unit is raised with the Put_Summary_Info procedure highlighted. Because you are not interested in the details of this procedure, you are going to Step Over this call.

3. . In the display.2.ada Ada editor window, select Debug > Step > Step Over.

The debugger assigns initial values and stops at the first statement after the begin. Because you are not interested in the details of this procedure, you are going to Step Over this call.

4. . In the display.2.ada Ada editor window, select Debug > Step > Step Over.

The debugger:

If you were to click on the Debug > Step > Step Into command again, execution would stop at the first statement of the Screen_Io.Put procedure; Step Into does not stop in function calls. However, you want to see how the string gets built for the Put procedure so you need to stop in the function using the Step Statement command.

Note: Step Into does not stop in function calls.

Stepping Statements

The Step Statement command stops at all Ada statements, regardless of their containing units. This means each function call and each procedure call will be stepped through statement by statement.

You are going to step through the Ada statements that generate and display the planetary summary information for planet 2.

1. . In the Debugger Log window, select Execution > Step Statement.

The stepping commands are available in the editor window (under the Debug menu) and in all the debugger windows (under the Execution menu).

The debugger starts the call to Build_Orbit_String and stops before the first executable statement in the Build_Orbit_String function.

The Ada editor window with the display.2.ada unit is raised with the Build_Orbit_String function highlighted.

Because this declaration assigns an initial value, assembly code is generated for this declaration making this an executable statement.

2. . In the display.2.ada Ada editor window, select Debug > Step > Step Statement.

The debugger starts executing the call to the X_Offset function.

3. . In the display.2.ada Ada editor window, select Debug > Step > Step Statement.

The debugger stops before the first executable statement in the X_Offset function.

The Ada editor window with the velocity_2d.2.ada unit is raised with the X_Offset function highlighted.

4. . In the velocity_2d.2.ada Ada editor window, select Debug > Step > Step Statement three times to complete the function.

The function call is completed with object Xv assigned.

The Ada editor window containing the display.2.ada unit is raised with the second statement in the Build_Orbit_String function highlighted.

5. . Select Debug > Step > Step Over to assign Yv.

6. . Select Debug > Repeat Step four times to assign the last three objects.

The Repeat Step command repeats the last step command you issued.

You are now at the end statement in the Build_Orbit_String function.

You could also set a breakpoint at the end statement in the Build_Orbit_String function using the Debug > Break Here command in the Ada editor window and the Debug > Continue command to execute until the return statement.

In the next topic, you will examine the values of these objects.


Displaying Objects

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

10 minutes.

Displaying the Value of an Object

Before you begin this topic, you should be:

If you are not running the planetary_motion program, you may follow these steps.

If you are not stopped at the end statement in Build_Orbit_String, you may follow these steps.

The Apex debugger allows displaying the current value of an object in the Debugger Log window. This is done using the Debug > Show command. This command operates differently depending on whether you are in an Ada editor window or in a debugger window.

You are going to examine the value of the Xv and Yv objects in the Display.Put_Summary_Info.Build_Orbit_String function. All these steps are performed from the display.2.ada unit Ada editor window:

1. . Move the cursor to the Xv object.

Use the mouse to position the cursor on Xv and click the left mouse button.

2. . In the Ada editor window, select Debug > Show.

The Debugger Log window displays the current value of the Xv object.

You are now going to examine the value of the Yv object using the Show Data dialog box:

3. . In the Debugger Log window, select Debug > Show... (The ... means this command displays a dialog box).

The Show Data dialog box is displayed.

4. . Enter the object name Yv in the Expression field.

5. . Click on OK.

The Debugger Log window displays the current value and location of the Yv object.

Finding the Bug

You think that there are problems with the parameters to the Put procedure. Set a breakpoink at this procedure to display its parameters.

1. . In the Debugger Log window, select Debug > Break.

The Set Breakpoint dialog box is displayed.

2. . Change the On Line option to the On Location option. Enter Screen_Io.Put in this area.

3. . Click on OK.

The Debugger Log window displays a message indicating that you must select which Put procedure at which to install the breakpoint. Put is an overloaded procedure and you must identify the one at which to place the breakpoint. Do this using the `N(n) attribute, where n is a natural number, is used to uniquely identify each Put procedure.

4. . Select the Debug > Break. command again, In the Set Breakpoint dialog box, change the On Line option to the On Location option and enter Screen_Io.Put'n(2).

    Note: Apex is NOT case-sensitive for Ada names.

The Debugger Log window displays a message stating that breakpoint 2 has been set.

5. . In the Debugger Log window, select Execution > Continue to execute to this breakpoint.

When the breakpoint location is reached:

6. . Display the value of S , by placing your cursor on the S and selecting the Debug > Show in the Ada Editor window command.

The Debugger Log displays the current value of S.

If you continue several more times and display the value of S, you will notice that the format of S is incorrect —— it needs more blank space. The return statement in the Build_Orbit_String function needs a different Width for each data item. If you try 8, 12, 12 and 8 for Xv, Yv, X and Y, respectively, your output will be formatted correctly.

Because you have found the bug, you want to remove the breakpoint.

1. . Raise the Breakpoint window by selecting Windows > Breakpoints in the Debugger Log window.

2. . Select Breakpoint 2 in the Breakpoints window.

3. . Select Breakpoints > Remove.

The Debugger Log window displays a message indicating one breakpoint has been removed.

4. . In the Breakpoints window, select Close button.

User exercise: change the Build_Orbit_String procedure to use correct values (8, 12, 12, 8) for the Width parameter. Recompile, relink, and rerun to verify the changes.

This ends this part of the debugger tutorial. Please Kill the execution of planetary_motion and close the Ada editor window.


Handling Exceptions

Prerequisites

Topics in this Submodule

Time to Complete the Submodule

10 minutes.

To demonstrate the exception handling capabilities of the Apex debugger, we are going to use a modified version the planetary_motion program to display the orbits for three planets. The third planet has an unstable orbit that goes beyond the screen bounds and causes an exception. These changes have been made for you and are in new versions of several units.

For Apex/Summit:

To set up the debugger tutorial view, in an Apex xterm (created by the Tools > Shell command), enter:

This may take a little while. Please wait for the "DEBUGGER TUTORIAL UPDATED FOR EXCEPTION HANDLING TOPIC" message before continuing.

For Apex/ClearCase:

To set up the debugger tutorial Rational subsystem, in an Apex xterm (created by the Tools > Shell command), enter:

This may take a little while. Please wait for the "DEBUGGER TUTORIAL UPDATED FOR EXCEPTION HANDLING TOPIC" message before continuing.

You are now going to explore the Apex exception-handling capabilities. In the directory-viewer window containing <debugger_sample_dir>:

1. . Start executing the planetary_motion executable without the debugger. Select the Set Direct output to an xterm option in the Run/Debug dialog box. Click OK.

A review on how to execute without the debugger is available.

After the program runs for a little while, The Out_Of_Bounds exception will be raised and the program will terminate.

2. . Close the Input/Output window using the close command on the Motif Menu.

Default Debugger Exception Handling

Exception handling specifies whether the program should stop when your program raises an exception. When your program raises an exception, the debugger either catches it or propagates it. When the debugger catches an exception, execution stops at the statement that raised the exception. Propagated exceptions are ignored by the debugger and handled by the program as usual.

The default is to catch all exceptions in all tasks in the program wherever they are raised (Catch All). Propagate and Catch requests combine to determine the action that the debugger takes when an exception is raised. When an exception in your program is raised, the debugger looks at its list of exception-handling requests to determine whether to stop the program and inform you. The first matching exception request determines the action to be taken. New exception requests are added to the front of the list.

If a new exception request exactly matches an existing exception handling request, the debugger removes the old request and adds the new request. Otherwise, the new exception handling request is added to the top of the list.

1. . Start executing the planetary_motion executable with the debugger.

A review on Starting to Debug a Program is available.

2. . Select the Continue button in the Debugger Log window.

The program will run until the exception is raised.

Displaying the Stack

At this point you are stopped at a OUT_OF_BOUNDS exception. Your focus is the Screen_Io.Translate_To_Screen_Coordinates procedure. You are going to display the execution Stack window:

Display the execution Stack window:

1. . In the Debugger Log window, select the Windows > Stack button.

The Stack window displays the current execution stack with the current context being displayed at the top.

Your Stack window shows that Translate_To_Screen_Coordinates was called by Position_Cursor'N(1) which was called by Display.Put'N(1) and so on.

2. . Double-click on the Translate_To_Screen_Coordinates line to move to that context.

An Ada editor window containing the Translate_To_Screen_Coordinates procedure is raised. The statement that is highlighted is the statement raising the exception. This statement is not very interesting so we are going to propagate this exception and continue.

3. . When you are finished looking at the Translate_To_Screen_Coordinates window, select File > Close.

4. . When you are finished looking at the Stack window, click the Close. button

The Online Reference provides more information on the Stack display.

Propagating an Exception

You are going to add an exception-handling request to propagate the OUT_OF_BOUNDS exception.

1. . Select the Debug > Propagate... command from the Debugger Log window.

The Catch/Propagate Exception dialog box is displayed.

2. . Enter the exception name in the Propagate Exception field: Screen_Io.OUT_OF_BOUNDS.

3. . Click on OK.

The Debugger Log displays a message indicating the Out_Of_Bounds exception is to be propagated.

4. . Bring up the Exceptions window by selecting the Windows > Exceptions menu item in the Debugger Log window.

The Exceptions Window

The Exceptions window displays the current catch and propagate exception-handling requests. Each exception handling request has the following format:

An example of the Exceptions window is

The Constraint_Error exception is to be propagated if it is raised at any location. Data_Error is to propagated at line 5 in the current task. All other exceptions are to be caught, i.e., stopped and reported by the debugger.

The Online Reference provides more information on the Exceptions window.

Continuing the Program

The planetary_motion program maps the 2-D planet coordinates into the xterm window screen coordinates. To see where the exception is raised, you are going to continue this program.

1. . Select the Continue button in the Debugger Log window.

The program runs awhile and then stops when the Out_Of_Bounds exception is raised. Execution stops and an Ada editor window containing the Screen_Io package is displayed.

2. . In the Debugger Log window, select the Stack button.

3. . The Stack window shows you are still in the Translate_To_Screen_Coordinates procedure, but in the exception handler. The exception handler raises the Out_Of_Bounds exception. Looking through the stack, it seems that an exception handler is needed in the routine that controls the displaying of the planets.

4. . Select File > Close in the Ada editor window containing Screen_Io.ada.

5. . In the Stack window, double-click on the frame 4 line.

Frame 4 is the line that starts with the number 4 and contains the Planetary_Motion.Planet_2.Display_Planet procedure.

An Ada editor window containing the planet.2.ada unit is raised.

6. . Select File > Close in the Stack window.

7. . Select File > Kill in the Debugger Log window.

You are going to add exception handlers to this procedure.

Adding Exception Handlers

You are going to add two exception handlers in the Display_Planet procedure in the planet.2.ada file)

1. . Around both Display.Put statements, add

2. . Save changes, recompile, relink, and start executing the updated program with the debugger. At the creation point, you are going to set the default exception handling.


Setting Debugger Options

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

5 minutes.

Setting Debugger Options

The debugger allows you to customize your usage of the debugger. The View > Options command sets debugger options such as default values for certain dialog boxes. When you select the View > Options command from any debugger window, the Debugger Options dialog box is displayed allowing you to customize your debugger.

Assume that you want to set the following debugger options:

1. . In the Debugger Log window (or any open debugger window), select View > Options.

The Debugger Options > Source Display dialog box is displayed.

2. . Change the Tab Size to 4.

3. . Select the Show Break Spots entry.

4. . Click on Apply. You will notice the appearance of breakspots in the Source Pane.

5. . Select the Object Display Tab.

6. . Click on OK.

Now that you have the debugger customized, you want to save these options so you do not have to set them each time you start Apex. This type of information is saved in debugger files. The next topic discusses these files.

Saving the Debugger State

You can save the debugger state across runs of the same program. You can also do so for initializing debugger state on a per-user basis and on a per-program basis. The debugger state information is preserved across debugging sessions if the corresponding debugger option is selected:

Debugger State Files

A user state file is used to save your personal preferences, regardless of which executable you are running.

A program state file is used to save state options that should be set by default for a particular executable:

A user-program state file is used to save each user's individual debugging defaults for that executable if there is more that one user debugging the executable.

A session-state file is used to save the debugger state for the last session of the program.

You are now going to save your current debugger defaults.

1. . In the Debugger Log window, select File > Debugger State > Save.

The Save Debugger State dialog box is displayed.

2. . Select the User State option and make sure all the debugger options settings/variables are selected.

3. . Click on OK.

The Debugger Log window displays a message indicating the information that has been saved.

The Online Reference provides additional information on debugger state files.

You are finished with the Ada Debugger module. Please kill the executable and close all open windows.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS