This chapter describes in detail the function of each window, menu, and display in the Debugger's graphical user interface (GUI). In addition, the chapter describes the Debugger commands available on the Debugger command line (see "Debugger Command Line"). Most commands are available from either interface. You can move from one to the other as you prefer.
This chapter contains the following sections:
The major areas of the Main View window are shown in Figure A-1.
The Main View contains a menu bar, from which you can perform a number of functions and launch windows. The menu bar contains the following items, which are discussed in detail in later pages:
In addition, the Main View contains the following items:
| "Command" text field |
| |||
| Debug option menu |
| |||
| Continue | Continues the execution of the current process. This command is legal only if the running process is stopped. If the program has not been run or has been killed, the Continue button is desensitized (grayed-out). If the target program has not yet started executing, use the Run command to start execution. | |||
| Stop | Stops the execution of the current process while it is running. his command is valid only when a process is running; otherwise the command button is desensitized (grayed-out). Traps can also be planted to stop the program at a specific location or on a particular condition. See the Trap Manager for more details. | |||
| Step Into | Executes a source line single step of the current process. If a function call is encountered, it is stepped "into." That is, the current process continues to the next source statement, even if that statement is encountered in a function that is called. The Step Over command can be used to step over function calls, then stop.If a trap is encountered while executing Step Into, the command is canceled and the process is stopped where the trap was fired. This command is legal only if the running process is stopped; otherwise the command button is desensitized (grayed-out). When you press the right mouse button over the Step Into button, a menu pops up to allow you to choose the number of source lines to be stepped. The step value menu selections consist of "1, 2, 3, 4, 5, 10, 15, 20, N..." If you choose the last menu entry "N...", a dialog window is opened to allow you to enter a step value. | |||
| Step Over | Executes source line single step of the current process. If a function call is encountered, it is stepped "over." That is, the current process continues to the next source statement, but does not count statements in functions that are called while stepping. Step Into can be used to step into function calls, then stop. If a trap is encountered while executing Step Over, the command is canceled and the process is stopped where the trap was fired. When you press the right mouse button over Step Over, a menu pops up to allow you to choose the number of source lines to be stepped. The step value menu selections consist of "1, 2, 3, 4, 5, 10, 15, 20, N..." If you choose the last menu entry "N...", a dialog window is opened to allow you to enter a step value. | |||
| Return | Continues the execution of the process until the current function that is being executed returns. The process is stopped immediately upon returning to the calling function. All code within the current function is executed as usual. If a trap is encountered while executing the Return command, the command is canceled and the process is stopped where the trap was fired. This command is legal only if the running process is stopped; otherwise the command button is desensitized (grayed-out). This command is not allowed if the executable is instrumented for performance analysis. | |||
| Sample | Allows you to manually sample the state of a process for evaluation by the Performance Analyzer. This command is legal only if the process is running and the Enable Data Collection mode is set on the Performance panel; otherwise the command button is desensitized (grayed-out). | |||
Prints the value of the currently selected expression. | ||||
| Kill | Kills the currently running process that you are debugging by sending it the equivalent of a "kill -9" signal. This command is legal if the process is running or stopped; otherwise the command button is desensitized (grayed-out). | |||
| Run | Runs the program that you are currently debugging. After the initial run, Run allows you to rerun the program, maintaining the traps you have set. | |||
| Status area | Displays information about the process that you are debugging. | |||
| Source Code area |
| |||
| Annotation column |
| |||
| "File" text field |
| |||
| Command line area |
| |||
| Show/Hide annotations button |
|
The Admin menu in Main View performs general management functions dealing with processes, windows, and user preferences (see Figure A-3). The Admin menu provides these selections:
| "Library Search Path..." |
The Library Search Path dialog is opened automatically when you invoke the Debugger on an executable or core file and the Debugger is unable to find all of the required DSOs. You may also open the Library Search Path dialog box by selecting "Library Search Path..." from the Admin Menu (see Figure A-4). The list of required DSOs displays at the top of the dialog box, annotated by the status of each DSO. The status can be "OK," "Error: Cannot find library," or "Error: Core file and library mismatch." The status "Error: Core file and library mismatch" indicates that the debugger found a DSO that did not match the core file. There are three fields for the variables below the list area where you can modify their values. Insert Before and Insert After move the shared object specified in the Value field before or after the selected object in the list. Modify replaces the selected object in the list with the file entered in the Value field. Remove deletes the selected shared object from the list. | |
| "Multiprocess View..." |
| |
| "GLdebug" | Provides a toggle to turn on GLdebug. GLdebug is a graphical software tool for debugging application programs that use the IRIS Graphics Library (GL). GLdebug locates programming errors in executables when GL calls are used incorrectly. For more information, refer to the GLdebug User's Guide. | |
| "Switch Process..." |
| |
| "Switch Executable..." |
| |
| "Detach" | Releases the process from the Debugger. This allows you to make changes to the source code. You must detach the process before you recompile the program. | |
| "Load Settings..." |
| |
| "Save Settings..." |
| |
| "Iconify" | Iconifies all of the session's views. | |
| "Raise" | Brings all the session's view windows to the foreground and redisplays any iconified windows. | |
| "Launch Tool" | Lets you run the WorkShop tools. See Figure A-7. You can switch to the other tools by selecting "Build Manager," "Static Analyzer," "Performance Analyzer," or "Tester." Selecting "Debugger" lets you start another debugging session. If you buy WorkShop Pro MPF (for multi-process debugging), the "Parallel Analyzer" selection is enabled. | |
| "Project" | Lets you control the WorkShop tools operating on the same executable as a group. See Figure A-8. For more information on "Project View," a facility for managing CASEVision tools operating on a common target, see "Project View". | |
| "Exit" | Exits all views in the session and terminates the session. |
The Views menu in Main View (see Figure A-9) provides these selections for viewing the process(es) and their corresponding data:
The Query menu (see Figure A-10) lets you perform some of the queries available in the Static Analyzer. If you have previously built a cvstatic fileset, this is rather convenient; however, if you need to build the fileset from scratch, the process becomes more involved.
With a current fileset, you can double-click any defined entity in the source code, select the "Where Defined?" option appropriate to its type, and the source code display area will scroll to the location where the item is defined.
The Source menu in Main View (see Figure A-11) provides these selections to deal with source code files:
| "Open..." | Loads a source file. | ||
| "Save" | Records changes made during the debugging session to the source file. You must first select "Make Editable," which appears in the Source menu when the file is read-only. | ||
| "Save As..." | Records changes made during the debugging session to the source file under a different filename. | ||
| "Save As Text..." |
| ||
| "Insert Source..." |
| ||
| "Fork Editor" | Starts your default editor on the current file. The default editor is determined by the editorCommand resource in the app-defaults file. The value of this resource defaults to | ||
| "Recompile" | Displays the Build View window, which lets you compile the source code associated with the current executable. | ||
| "Make Read Only" / "Make Editable" |
| ||
| "Search..." | Searches for a literal case-sensitive, literal case-insensitive, or regular expression (see Figure A-12). After you have set your target and clicked Apply (or pressed <Enter>), each instance is marked by a search target indicator in the scroll bar. You can search forward or backward in the file by clicking the Next and Prev buttons. You can also click an indicator with the middle mouse button to scroll Main View to that point. Clicking Reset removes the search target indicators. | ||
| "Go to Line..." | Lets you scroll to a position in the source code by specifying a line number. "Go to Line..." brings up a dialog box similar to the one shown in Figure A-13. You can enter a line number or use the slider at the top of the box to select a line number. You do not have to display line numbers to use this feature. | ||
| Versioning" | Provides access to the configuration management tool, if you have designated one. The cvconfig script lets you designate CASEVision/ClearCase, RCS, or SCCS. Type:
The "Versioning" submenu appears in Figure A-14. Selecting any of these options displays a shell in which you can access the configuration management tool. The selections in the submenu are:
|
The Display menu in Main View (see Figure A-15) provides these selections to annotate the source code displayed:
| "Show Line Numbers"/"Hide Line Numbers" |
| |
| "Preferences..." |
| |
| "Hide Icons"/"Show Icons" |
|
The Perf (Performance) menu (see Figure A-17) offers the following menu selections:
| Select Task submenu |
| |
| Examine Results... |
| |
| Configs... | Brings up the configurations dialog, which contains the following items:
|
The Custom Task dialog contains the following items:
| "Sampling Data" toggles |
| |
| Tracing Data" toggles" |
| |
| "Pollpoint Sampling" text field |
| |
| "Fine Grained Usage" text field |
| |
| "Call Stack Profiling" text field |
|
For further information on the Performance Analyzer, see the Performance Analyzer User's Guide.
The Traps menu (see Figure A-20) offers the following menu selections:
| "Set Trap" | Allows you to set a trap in your source code. You can set a trap in a number of ways, depending on which selection you make from the submenu (see Figure A-21). | |
| "Set Trap":"Stop" |
| |
| "Set Trap":"Stop At Function Entry" |
| |
| "Set Trap":"Stop At Function Exit" |
| |
| "Set Trap":"Sample" |
| |
| "Set Trap":"Sample At Function Entry" |
| |
| "Set Trap":"Sample At Function Exit" |
| |
| "Clear Trap" | Deletes the trap on the line containing the cursor. You must designate "Stop" or "Sample" trap type, since both types can exist at the same location, appearing superimposed on each other (see Figure A-22). | |
| "Clear Trap":"Stop" |
| |
| "Clear Trap":"Sample" |
|
The PC (program counter) menu in Main View (see Figure A-23) provides these selections for controlling the execution of a process:
The Fix+Continue menu (see Figure A-24) offers the following menu selections:
| "Edit" | Allows you to edit functions using the Debugger editor. | |
| "External Edit" | Allows you to edit functions using an external editor. The default editor is vi, but can be changed by using the "Set Edit Tool..." popup menu in the Admin menu of the Status window. See "Fix+Continue Status Window" for further information. | |
| "Parse and Load" |
| |
| "Show Difference" submenu |
| |
| "Edited<-->Compiled" |
| |
| "Save As..." | Allows you to save your changes to a file (see Figure A-25). You can save the changes to the current source file (the default), or to a separate file. | |
| "Save All Files..." |
| |
| "View" submenu |
| |
| "Preferences" submenu |
| |
| "Cancel Edit" | Takes you out of edit mode. | |
| "Delete Edits" | Deletes any changes that you made to functions. |
(see Figure A-26) allows you to see the difference between the original and your modified code. It contains the following options:
| "For Function" |
| |
| "For File" | Opens a window that shows you the differences between the original source file and your modified version. | |
| "Set Diff Tool ..." |
|
(see Figure A-27) allows you to open different Fix+Continue view windows. It contains the following options:
| "Status Window" |
| |
| "Message Window" |
| |
| "Build Environment Window" |
|
The Preference
Menu (see Figure A-28) allows you to set various options for the Fix and Continue environment, such as the difference tool, the external editor command, and so on. The menu contains the following options:
| "Show Preferences" |
The preferences available through the dialog are
| |
| "Reset Factory Defaults" |
| |
| "Save Preferences" |
| |
| "Load Preferences..." |
|
Use the accelerators in Table A-1 to issue Fix+Continue commands directly from the keyboard.The accelerators are listed alphabetically by command.
Table A-1. Fix and Continue Keyboard Accelerators
Command | Ctrl + key |
|---|---|
Cancel Edit | U |
Edit | E |
External Edit | X |
Parse And Load | P |
The Help menu (see Figure A-30) provides these options:
This section discusses some of the basic additional views that are available throught the Debugger; the Execution View, Source View, and Process Meter.
The Execution View window is a simple shell that lets you set environment variables and inspect error messages. Your target program I/O, if any, will be displayed in the Execution View window. If the program is I/O-based, then all interaction takes place in Execution View.
The Execution View (see Figure A-31) is launched automatically with the Debugger.
The Source View (see Figure A-32) displays your source, opening your Main program file by default.
The Source View menu bar contains five items that are duplicated from the Main View: Display, Traps, PC, and Fix+Continue. Each of these menus has the same functionality as its counterpart in the Main View (see "Main View"). The only new menu bar item is the file menu (Figure A-33), described below:
| "Open..." | Launches the file dialog (see Figure A-139), allowing you to choose a file to load into the source view. | ||
| "Save" | records changes made during the debugging session to the source file. You must first select "Make Editable," which appears in the Source menu when the file is read only. | ||
| "Save As..." | records changes made during the debugging session to the source file under a different filename. | ||
| "Save As Text..." |
| ||
| "Open Separate..." |
| ||
| "Insert File..." | inserts the text of a file within your current file. | ||
| "Clone" | clones the current window. | ||
| "Fork Editor" | starts your default editor on the current file. The default editor is determined by the editorCommand resource in the app-defaults file. The value of this resource defaults to | ||
| "Recompile" | displays the Build View window, which lets you compile the source code associated with the current executable. | ||
| "Make Editable" |
| ||
| "Search" | searches for a literal case-sensitive, literal case-insensitive, or regular expression (see Figure A-12). After you have set your target and clicked Apply (or pressed <Enter>), each instance is marked by a search target indicator in the scroll bar. You can search forward or backward in the file by clicking the Next and Prev buttons. You can also click an indicator with the middle mouse button to scroll Main View to that point. Clicking Reset removes the search target indicators. | ||
| "Go To Line..." | launches the Go To Line dialog, which allows you to go to a specific line in the source. You can type in the line, or select the line number via the slider bar. | ||
| "Versioning" | provides access to the configuration management tool, if you have designated one. The cvconfig script lets you designate CASEVision/ClearCase from SGI, RCS or SCCS. Type:
Selecting any of these options displays a shell in which you can access the configuration management tool. The selections in the submenu are: | ||
| "Versioning":"CheckIn" |
| ||
| "Versioning":"CheckOut" |
| ||
| "Versioning":"UncheckOut" |
| ||
| "Close" | Dismisses the Source View window. |
The Process Meter monitors the resource usage of a running process without saving the data. Figure A-35 shows the Process Meter in its default configuration (with only the User/Sys Time chart active).
The Process Meter contains its own menu bar, which contains the Admin, Charts, Scale, and Help menus. The Admin menu is the same as that described in "Admin Menu". The Help menu is the same as that described in "Help Menu". The other menus are described in the following sections.
The Charts Menu contains a set of toggles that allow you to choose which charts are displayed in the Process Meter. You can display as many charts simultaneously as you wish. The choices available are:
User/Sys Time (the default)
Major/Minor Faults
Context Switches
Bytes Read/Written
Read/Write Sys Calls
Other Sys Calls
Total Sys Calls
Signals
Process Size
This section discusses the Debugger windows that are specific to Ada: the Task View and Exception View.
The Task View is an Ada-specific view that provides you with task and callstack information. If you do not have Ada installed on your system, the Task View menu item in the Views menu will be grayed-out.
The Task View contains its own menu bar, which contains the Admin, Config, Display, and Help menus. The Help menu is the same as that described in "Help Menu". The other menus are described in the following sections.
In addition, the Task View contains the following items:
| Process Sort toggles |
| |
| Process Display tabs |
| |
| Task Display tabs |
|
The Admin Menu (see Figure A-41) contains the following items:
"Active" toggle
Activates the current window in a set of cloned windows. In the current release, this toggle is always active.
| "Clone" | Creates a clone of the current window. This function is not supported in the current release, and the option is grayed out. | |
| "Save As Text..." |
| |
| "Close" | Closes the current window. |
The Config Menu (Figure A-42) contains the following items:
| "Preferences..." |
|
The Layout Menu (Figure A-41) contains the following toggles:
| "Task List" | Causes only the Callstack Display to be shown. | |
| "Single Task" | Causes only the Process Display to be shown. |
The Display Menu (Figure A-41) is divided into the Task List Format and Callstack Format sections. The Callstack Format toggles match the toggles that are contained in the Callstack View Display menu. The Task List Format toggles control what radio buttons are made available in the toggle sort list, as well as what information is displayed in the Process Display area.
The Task View Display menu contains the following toggles:
| "Status" | Displays the status of the process. This toggle is active by default. | |
| "Priority" | Displays the priority of the process. | |
| "Sproc" | Displays the sproc value of the process. This toggle is active by default. | |
| "Resource Vector" |
| |
| "Arg Values" | Allows you to set the argument values in the Task View. This toggle is active by default. | |
| "Arg Names" | Allows you to set the argument names in the Task View. This toggle is active by default. | |
| "Arg Types" | Allows you to set the argument types in the Task View. | |
| "Location" | Allows you to set the function location in the Task View. This toggle is active by default. | |
| "PC" | Allows you to set the PC in the Task View. |
The Exception View is an Ada-specific view that allows you to set traps on exceptions. This view only functions if Ada is installed.
The Exception View contains the following items:
| Admin menu | Contains the following items:
| |
| "Stop" toggle | Indicates when a trap is active. | |
| "When" option menu |
The process is always stopped at the point of a raise. | |
| "Search" text field |
|
The X/Motif analyzer provides specific debugging support for X/Motif applications. There are various examiners for different X/Motif objects, such as widgets and X graphics contexts, that might be difficult or impossible to inspect using ordinary debugger functionality.
To access the X/Motif analyzer window, you must pull down the Views menu and select "X/Motif Analyzer" (see Figure A-47).
Though the X/Motif Analyzer is made up of several different examiner windows, a number of objects remain constant throughout window changes. The examiner windows available are
The Admin menu (see Figure A-48) offers the following menu selections:
| "Active" toggle |
| |
| "Clone" | Creates a clone of the current window. This function is not supported in the current release, and the option is grayed out. | |
| "Save As Text..." |
| |
| "Close" | Closes the current window. |
The Examine menu (see Figure A-50) offers the following menu selections:
| "Selection" | Selects the currently highlighted object for examination. | |
| "Widget" | Uses the current selection as input to the widget examiner, then opens that examiner (see "Widget Examiner" for information). | |
| "Widget Tree" | Switches the window view to the widget tree examiner (see "Tree Examiner" for information). | |
| "Widget Class" | Switches the window view to the widget class examiner (see "Widget Class Examiner" for information). | |
| "Window" | Switches the window view to the window examiner (see "Window Examiner" for information). | |
| "X Event" | Switches the window view to the X Event examiner (see "Event Examiner" for information). | |
| "X Graphics Context" |
| |
| "X Pixmap" | Switches the window view to the X pixmap examiner (see "Pixmap Examiner" for information). |
In addition to access through the Examine menu, each examiner can be accessed through a tab at the bottom of each view (see Figure A-51).
When first launched, the X/Motif Analyzer has only four tabs: Breakpoints, Trace, Widget, and Tree. As you use new examiners through the Examine menu, new tabs are added for the new examiners. Any of these new tabs may be deleted at any time by selecting the tab, clicking the right mouse button, and then selecting "Remove Examiner" (see Figure A-52). The initial four tabs may not be removed.
The "Widget" and "Name" text fields both have return buttons (see Figure A-53) just to their right. Clicking these buttons causes the X/Motif Analyzer to respond exactly as if you had pressed Return on your keyboard.
The Breakpoints examiner is not really an examiner, but a control area where you can set widget-level breakpoints. The breakpoints examiner is divided into three areas (see Figure A-53):
The widget specification area, which contains the same information as that in the Widget examiner. You can select a widget address, name, or class in this area, as well as move to the widgets parents or children, or select a widget in the application. In cases where the breakpoint type does not apply to widgets (for example, input-handler breakpoints), this area is blank.
The parameter specification area, the contents of which vary according to the type of breakpoint you are setting. For example, for Callback breakpoints, this area contains the callback name and client data; for event-handler breakpoints, it contains the event type and the client data, and so on.
The breakpoint area, which contains the breakpoint name, a search field, and the Add, Modify, Delete, and Step To buttons.
The control area has eight different breakpoint types that it can examine. These types are set through the "Breakpoint Type" option button (see Figure A-54). The options for the "Breakpoint Type" option button are described below:
"Callback:" Widget callback installed by XtAddCallback. Parameters include callback name and client_dataXtPointer value. See "Callback Breakpoints Examiner" for more information.
"Event-Handler:" Widget event handler installed by XtAddEventHandler. Parameters include X event type and client_dataXtPointer value. See "Event-Handler Breakpoints Examiner" for more information.
"Resource-Change:" Resource change caused by XtSetValues or XtVaSetValues. Parameters include resource name and resource value, both strings. See "Resource-Change Breakpoints Examiner" for more information.
"Timeout-Procedure:" Timeout callback installed by XtAppAddTimeOut. Parameters include client_dataXtPointer value. See "Timeout-Procedure Breakpoints Examiner" for more information.
"Input-Handler:" Input callback installed by XtAppAddInput. Parameters include client_dataXtPointer value. See "Input-Handler Breakpoints Examiner" for more information.
"State-Change:" Various widget state changes (for example, "managed" or "realized"). Parameters include widget state. See "State-Change Breakpoints Examiner" for more information.
"X-Event:" X event received by target application. Parameters include X event type. See "X-Event Breakpoints Examiner" for more information.
"X-Request:" X request received by target application. Parameters include X request type. See "X-Request Breakpoints Examiner" for more information.
When the "Callback" option of the "Breakpoint Type" option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure A-55.
The Callback Breakpoints examiner contains the following items:
| "Widget" text field |
| |
| "Name" text field |
| |
| "Class" text field |
| |
| Parent button | Allows you to move the parent of the currently selected widget. | |
| Previous button | Moves you to the previously selected widget. | |
| Children... button |
| |
| Select... button | Allows you to select the widget in the target process. | |
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| "Callback Name" text field |
| |
| "Client_Data" text field |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
When the "Event-Handler" option of the "Breakpoint Type" option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure A-56.
The Event-Handler Breakpoints examiner contains the following items:
| "Widget" text field |
| |
| "Name" text field |
| |
| "Class" text field |
| |
| Parent button | Allows you to move the parent of the currently selected widget. | |
| Previous button | Moves you to the previously selected widget. | |
| Children... button |
| |
| Select... button | Allows you to select the widget in the target process. | |
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| "Event Type" option button |
| |
| "Client_Data" text field |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
When the "Resource-Change" option of the "Breakpoint Type" option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure A-58.
The Resource-Change Breakpoints examiner contains the following items:
| "Widget" text field |
| |
| "Name" text field |
| |
| "Class" text field |
| |
| Parent button | Allows you to move the parent of the currently selected widget. | |
| Previous button | Moves you to the previously selected widget. | |
| Children... button |
| |
| Select... button | Allows you to select the widget in the target process. | |
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| "Resource Name" text field |
| |
| "Resource Value" text field |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
When the "Timeout Procedure" option of the "Breakpoint Type" option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure A-59.
The Resource-Change Breakpoints examiner contains the following items:
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| "Client_Data" text field |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
When the "Input-Handler" option of the "Breakpoint Type" option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure A-60.
The Input-Handler Breakpoints examiner contains the following items:
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| "Client_Data" text field |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
When the "State-Change" option of the "Breakpoint Type" option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure A-61.
The Resource-Change Breakpoints examiner contains the following items:
| "Widget" text field |
| |
| "Name" text field |
| |
| "Class" text field |
| |
| Parent button | Allows you to move the parent of the currently selected widget. | |
| Previous button | Moves you to the previously selected widget. | |
| Children... button |
| |
| Select... button | Allows you to select the widget in the target process. | |
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| "State Type" option button |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
When you select the "X-Event" option of the "Breakpoint Type" option button in the Breakpoint Examiner, the examiner appears as shown in Figure A-63.
The X-Event Breakpoints examiner contains the following items:
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| "Event Type" option button |
| |
| "Window ID" text field |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
When the "X-Request" option of the "Breakpoint Type" option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure A-65.
The X-Request Breakpoints examiner contains the following items:
| "Breakpoint Type" option button |
| |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| Request Type button |
| |
| "Search" text field |
| |
| Add button | Allows you to add a new breakpoint. | |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Delete button | Deletes the selected breakpoint. | |
| Step To button | Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true. |
The Trace examiner (see Figure A-67) is a control area where you can trace the execution of your application and collect various forms of data. The following data is collected:
X Server Events
X Server Requests
Widget Event Dispatch Information
Widget Resource Changes (through XtSetValues)
Widget State Changes (create, destroy, manage, realize, unmanage)
Xt Callbacks (widget, event handler, work proc, timeout, input, signal)
The Trace examiner contains the following items:
| "Collect Trace" toggle |
| |
| "File" text field | Allows you to select the filename for the trace. If no file is selected, a default filename for the trace is chosen. | |
| "Search" text field |
| |
| Filter... button | Launches a dialog that allows you to select the trace entry types you want displayed in the list. | |
| Clear File button |
|
The Widget examiner (see Figure A-68) displays the internal Xt widget structure, as well as the Xt inheritance implemenation using nested C structs.
The Widget examiner contains the following items:
| "Widget" text field |
| |
| "Name" text field |
| |
| Parent button | Allows you to move the parent of the currently selected widget. | |
| Previous button | Moves you to the previously selected widget. | |
| Children... button |
| |
| Select... button | Allows you to select the widget in the target process. |
The Tree examiner (see Figure A-69) displays the widget hierarchy.
You may double-click a node to view that widget in the Widget examiner. Use the option menu in the bottom-right corner to switch the display among widget names, class names, and IDs.
If the Tree examiner is currently selected, it will not automatically fetch the current widget tree each time the process stops. To force retrieval of the widget tree, select another examiner and then go back to the Tree examiner. Or, click on the Tree tab.
You may display the tree according to widget name, class, or ID value. You can select this by choosing the appropriate option from the widget view type option button (see Figure A-70) in the lower-right portion of the examiner.
The Callback examiner (see Figure A-71) automatically appears when the process is stopped somewhere in a callback. It first displays the callstack frame for the callback function. Next, it displays information about the widget in the callback. Finally, it displays the proper callback structure contained in the call_data argument to the callback procedure, based on the widget type and the callback name.
The Window examiner (see Figure A-72) displays window attributes for an X window. These are the attributes returned by XGetWindowAttributes, with decoding of the Visual structure and enums and masks decoded. Additionally, the Window examiner shows the parent and children window IDs.
The Window examiner contains the "Window" text field, which displays the address of the window that is being examined. You may change to a different window by entering a new address and pressing the ENTER key.
The Event examiner (see Figure A-73) displays the event structure for an XEvent pointer. The proper XEvent union member is used, and enums and masks are decoded.
The Event examiner contains the "X Event" text field, which displays the address of the X event that is being examined. You may change to a different X event by entering a new address and pressing the ENTER key.
The Graphics Context examiner (see Figure A-74) displays the X graphics context attributes that are cached by Xlib in the form of an XGCValues structure. Enums and masks are decoded.
The Graphics Context examiner contains the "GC" text field, which displays the address of the graphics context that is being examined. You may change to a different context by entering a new address and pressing the ENTER key.
The Pixmap examiner (see Figure A-75) displays basic attributes of an X pixmap, like size and depth. It also attempts to provide an ASCII display of small pixmaps, using the units digit of the pixel values.
The Pixmap examiner displays the contents of an X pixmap. Specify the X pixmap identifier and optionally, the X colormap identifier, by entering expressions in the two text areas at the top of the window. Use 'default' as the colormap identifier to specify the default X colormap for your screen. In the actual pixmap display, left-click on a pixel to see the pixel value, position, and red-green-blue intensities.
The Widget Class examiner (see Figure A-76) displays the Xt widget class structure, as well as the Xt inheritance implementation using nested C structs.
The Widget Class examiner contains the "W Class" text field, which displays the address of the widget class that is being examined. You may change to a different widget class by entering a new address and pressing the ENTER key.
A project is a single CASEVision work session focused on a common task. Its purpose is to let you perform operations conveniently on selected project components or on the project as a whole. A project includes all CASEVision tools and windows invoked from the command line (unless invoked with the -privateProject switch) and from the graphical user interface of one of those tools.
When you are working on a single project, with only a few windows open simultaneously, you can keep track of your activities with relative ease. In situations where you have many windows open from one or more projects, it is easy to get confused. To simplify the use of multiple windows, WorkShop provides facilities for iconifying and raising windows in
Main View Admin menu
the "Project" submenu
the Project View window
Figure A-77 shows where these facilities are located.
The window facilities in the Main View Admin menu apply to the current application and its windows only. "Iconify" iconifies all of the application's views. "Raise" brings all the application's view windows to the foreground and redisplays any iconified windows.
The "Project" submenu selections "Iconify," "Raise," "Remap Paths...," and "Exit" operate the same way as their counterparts do in the MainView Admin menu, except that they are applied to all tools and windows in the current project.
To display the Project View window, in the Main View, pull down the Admin menu, select the "Project" submenu, and select "Project View..." The Project View window is shown in Figure A-78 with its Admin menu and right-button popup menu. Project View represents the components of a project (tools or windows depending on the toggles in the Admin menu) as buttons. Elements from the same project are grouped within a rectangle. A dashed-line rectangle indicates the currently selected project. When a project is selected, you can change its name or change the command.
The "Show Applications" and "Show Windows" toggle selections in the Admin menu determine whether applications or individual windows display as project element buttons. The "Rescan" selection reevaluates the state of your projects and redisplays the current elements. "Exit" closes the Project View window.
The Project field lets you enter a name to identify the current project.
The Command field lets you invoke other tools to be included in the project. These can be WorkShop tools or integrated tools, such as CASEVision/ClearCase.
The elements of a project are represented by buttons. When a button protrudes from the screen, the item is currently iconified; when it is recessed, the item is displayed. Clicking the button toggles it between display and iconify modes.
In addition to setting traps through the Main View and the command line, the debugger provides you with three views specific to trap management:
Trap Manager
Signal Panel
Syscall Panel
The Trap Manager allows you to set, edit, and manage traps (used in both the Debugger and Performance Analyzer). The Trap Manager is shown in Figure A-79.
The Trap Manager contains the following items (besides the menu bar, which is discussed below):
| "Trap" text field |
| |
| "Condition" text field |
| |
| "Cycle Count" text field |
| |
| "Current Count" text field |
| |
| Modify button | Allows you to change the selected breakpoint's settings. | |
| Add button | Allows you to add a new breakpoint. | |
| Clear button | Clears all the current breakpoint selections and text fields. | |
| Delete button | Deletes the selected breakpoint. | |
| Trap Display area |
| |
| "Search" text field |
|
The Trap Manager has a menu bar which contains the Admin, Config, Traps, Display, and Help menus. The Admin menu is the same as that described in "Admin Menu". The Help menu is the same as that described in "Help Menu". The other menus are described in the following sections.
The Config Menu (Figure A-80) contains the following items:
| "Load Traps..." |
| |
| "Save Traps..." |
|
The Traps Menu (Figure A-81) allows you to set traps under a number of conditions. These conditions are:
"At Source Line"
"Entry Function"
"Exit Function"
"Stop Trap Default"
"Sample Trap Default"
"Group Trap Default"
"Stop All Default"
The Display Menu (Figure A-82) contains the following items:
| "Delete All" | Deletes all traps from the trap list. |
The Signal Panel displays the signals that can occur. You can specify which signals trigger traps and which are to be ignored. The Signal Panel is shown in Figure A-83.
The Signal Panel contains an Admin menu (described in "Admin Menu") and a Help menu (described in "Help Menu"). Each signal trigger trap in the display has a toggle associated with it. In addition, the panel has a Search field.
The Syscall Panel lets you set traps at the entry to or exit from system calls. The Syscall Panel is shown in Figure A-84.
The Syscall Panel contains an Admin menu (described in "Admin Menu") and a Help menu (described in "Help Menu"). Each system call in the display has two toggle associated with it: one to set a trap on entry, one to set a trap on exit. In addition, the panel has a Search field.
There are several windows that are used primarily to examine your debugging data:
To examine data in an array variable, select Array Browser from the Views menu at a point in the process where the variable is present. Array Browser lets you view elements in a multi-dimensional array (up to 100 x 100 elements), presented in a spreadsheet and graphically, if desired. (For a tutorial example of the Array Browser, see "Examining Data".)
The array specification area lets you specify the variable and its dimensions. It consists of these fields:
The subscript control area serves two functions: (1) it lets you control which elements in the variable are to be displayed, and (2) it lets you shift the current element. The number of dimensions in the array governs the number of controls that are displayed. A close-up view of the subscript controls area appears in Figure A-86.
The subscript control area provides these features
The spreadsheet area is where numeric data is displayed. It can show two dimensions at a time (indicated in the upper left corner of the matrix). The column indexes run along the top of the matrix and the row indexes are displayed along the left column. The spreadsheet area has scroll bars for viewing data elements not currently visible in the viewing area. Figure A-87 shows a close-up of the spreadsheet area.
The current element is highlighted by a colored rectangle in the spreadsheet area. Its corresponding expression is shown in the current element identifier field, and the value is shown in the current element value field.
The Spreadsheet menu (see Figure A-88) lets you change the appearance of data in the spreadsheet area. It provides these selections:
| "Column Width..." |
| |
| "Wrapped Display" |
Figure A-89 shows an example of a wrapped array. There is only one index $i. The current cell is element 4 in the array (by adding 3 and +1). |
The Format menu (see Figure A-90) displays a separate menu that you lets you display the elements in the default format, as formatted values (decimal, unsigned, octal, and so forth) or as their data types.
The graphical display area presents the array data in a 3-D graph in one of the following forms:
surface (polyhedron)
bar chart
points
multiple lines (array vectors)
You select the graphical display mode through the Render menu. The Render menu (see Figure A-91) has the following items:
| "Surface" | Exhibits the data as a solid using the data values as vertices in a polyhedron. | |
| "Bar Chart" | Presents the data values as 3-D bar charts. | |
| "Points" | Simply plots the data values in 3-D space. | |
| "Multi Line" | Plots and connects the data values in each row. | |
| "None" | Lets you display Array Browser with no graphical display, in effect turning off graphical display mode. |
The Color menu (see Figure A-92) provides these options:
| "Monotone Ramp" |
| |
| "Hue Ramp" | Displays the data values in a spectrum of colors ranging from blue (lowest values) through green, yellow, orange, and red (highest values). | |
| "Exception" | Lets you flag certain conditions by color, usually for the purpose of spotting bad data. When you select "Exception," the controls shown in Figure A-93 appear in the window. Thus, you can highlight data values less than or greater than specified values, values of plus or minus infinity, values of plus or minus underflow, zero values, and NaN (not a number) values. |
The Scale menu (see Figure A-95) provides options for changing the ratio of the z-dimension, which represents the value of the element. The number on the left represents the value of the x- and y-dimensions (which are always the same as each other); the number on the right is the z dimension.
Manipulating the z-dimension affects the ease of spotting differences in values. If your data is scattered over a narrow range of values, you may wish to heighten the graph by selecting "10:1" as your scale; this exaggerates the values in the z-dimension. If your data is in a wide range, selecting "1:2" or "1:10" as the scale will minimize the differences, flattening the graph.
The graphical display uses controls and menus from Examiner Viewer. Examiner Viewer is based on a camera metaphor and borrows terms from the film industry, such as zoom and dolly, in naming its controls. The graphical display area of the window is shown in Figure A-96, with its main controls and menus. Note that the buttons on the upper right side of the graphical display area may not be visible if the area is too small; you can expose them by moving either the upper or lower sash to enlarge the display area.
Examiner Viewer provides these controls for viewing the graph. The right side buttons are:
| view mode | Toggles between a view-only mode (closed eye) and manipulation mode (open eye). In view-only mode, the cursor appears as an arrow and the graph cannot be moved. Clicking on a portion of the graph selects the corresponding array element in the spreadsheet. In manipulation mode, the cursor appears as a hand and you can move the graph. Dragging the graph with the left mouse button down moves the graph in any direction as if it were in a trackball; a quick movement spins the graph. Dragging the graph with the left mouse button and the ctrl button rolls (rotates) the graph in the plane of the screen. Dragging the graph with the middle mouse button moves it without changing the viewing angle. If you drag the graph with both the left and middle mouse buttons down, the graph will appear to move into or out of the window (this is the same as the dolly thumbwheel which is described in this section). | |
| help | Runs a special help system containing Inventor Viewer information. | |
| home | Repositions the graph in its original viewing position. | |
| set home | Changes the home (original viewing) position for subsequent use of the home button. | |
| view all | Repositions the display area so that the entire graph is visible. | |
| seek | Provides a special cursor that lets you reposition the graph in the center of the display area or lets you center the view on a point you select with the cursor. See "Seek to point <or object>" in the Preferences dialog box. |
These four controls let you move the graphic display:
| x rotation thumbwheel |
| |
| y rotation thumbwheel |
| |
| zoom slider and readout |
| |
| dolly thumbwheel |
|
You access the Examiner Viewer menu (see Figure A-96) by holding down the right mouse button in the graphical display area. The Examiner Viewer menu provides these selections:
| "Functions" | Displays a submenu with the selections "Help," "Home," "Set Home," "View All," and "Seek," which are the same as the right mouse button controls described in the previous section, and the "Copy View" and "Paste View" selections. These operate like standard copy and paste editing commands, enabling you to transfer graphs. | |
| "Draw Style" | Displays a submenu that controls how the graph is displayed. The selections "as is," "filled," "wireframe," and "points" control how the graph is displayed when it is static. These override the Render menu selections. The selections "move wireframe" and "move points" control how the graph is displayed while in motion. The selections "single," "double," and "interactive" refer to buffering techniques used in moving the graph. These affect the smoothness of the movement. | |
| "Viewing" | The same as the view mode button described in the previous section. When it is off, you can select points from the graph to display in the spreadsheet but cannot move the graph. When on, it lets you manipulate the graph. | |
| "Decoration" | Displays the right side buttons when it is on and hides them when it is off. | |
| "Headlight" | Controls the shadow effect on the graph. When it is on, the light appears to come from the camera. | |
| "Preferences" | Causes the Examiner Viewer Preferences dialog box to display. | |
| "Seek animation time" |
| |
| "Seek to point <or object>" |
| |
| "Zoom slider ranges from" |
| |
| "Auto clipping planes" |
| |
| "Enable spin automation" |
| |
| "Show point of rotation axes" |
|
The Call Stack View (Figure A-98) displays the functions in the call stack (referred to as frames) when the process has stopped.
The source display has two special annotations:
The location of the current program state is indicated by a large green (depending on color scheme) arrow representing the PC.
The location of the call to the function selected in the Call Stack View window is indicated by a smaller blue (depending on color scheme) arrow representing the current context, and the source line becomes highlighted.
The Call Stack View contains its own menu bar, which contains the Admin, Config, Display, and Help menus. The Admin menu is the same as that described in "Admin Menu". The Help menu is the same as that described in "Help Menu". The other menus are described in the following sections.
The Config Menu (Figure A-99) contains the following items:
| "Preferences..." |
|
The Display Menu (Figure A-100) contains the following toggles:
| "Arg Values" | Allows you to set the argument values in the Call Stack View. | |
| "Arg Names" | Allows you to set the argument names in the Call Stack View. | |
| "Arg Types" | Allows you to set the argument types in the Call Stack View. | |
| "Location" | Allows you to set the function location in the Call Stack View. | |
| "PC" | Allows you to set the PC in the Call Stack View. |
The Expression View window is shown in Figure A-101. The expression view displays a collection of expressions that are evaluated each time the process stops or the context changes.
In addition to the items on the menu bar, the Expression View has two popup menus: the Language menu and the Format menu. The menu bar items and the two popup menus are discussed in the following sections. (The Admin menu is the same as that described in "Admin Menu". The Help menu is the same as that described in "Help Menu". The other menus are described in the following sections.)
The Config Menu (see Figure A-102) contains the following items:
| "Load Expressions..." |
| |
| "Save Expressions..." |
|
The Display Menu (see Figure A-103) contains the following items:
| "Clear All" | Clears all fields in the view. |
The Language popup (see Figure A-104) contains three radio buttons, allowing you to select one of three languages for evaluation: C, C++ or Fortran. The Language popup is invoked by holding down the right mouse button while the cursor is in the Expression column.
The Format popup (see Figure A-105) The Format menu is displayed by holding down the right mouse button in the Result column.
The Format popup contains the following items:
| "Default" | A radio button that sets the format to the default values. | |
| "Value" | Launches a submenu of radio buttons from which you can select a value of type Decimal, Unsigned, Octal, Hex, Float, Char, or String. | |
| "Type" | Launches a submenu of radio buttons from which you can select a type of Decimal, Octal, or Hex. | |
| "Bit size" | A radio button that sets the format to the bit size. |
The File Browser displays a scrollable list of source files used by the current executable. Double-click a file in the list to load it directly into the source display area in Main View or Source View. The Search field lets you find files in the list quickly.
The File Browser contains an Admin menu (described in "Admin Menu") and a Help menu (described in "Help Menu"). In addition, the browser has a Search field.
The Structure Browser lets you examine data structures and the relationships of the data within them. It displays complex data structures as separate graphical objects, using arrows to indicate relationships. A typical Structure Browser example is shown in Figure A-107 with the Config, Display, Node, and Format menus displayed. (For a tutorial example of the Structure Browser, see "Examining Data".)
The structure name is entered in the Expression field. It then appears as an object or set of objects in the display area in the lower portion of the window. Each structure has a header identifying the structure, color coded by data type. Below the header are two columns: the left displays the field name and the right displays the field's value. If the structures to be displayed exceed the size of the Structure Browser window, scroll bars appear.
In addition to the Admin menu, Structure Browser provides four menus that are used to change the way the data displays. The menus are:
WorkShop provides the Overview window (from the "Show Overview" selection in the Display menu) as another way to navigate around the display area (see Figure A-108).
The Overview window is a reduced-scale view of the requested structures. The structures are represented by solid rectangles color- coded by data type. The relative position of the currently visible area is represented by a transparent rectangle. This rectangle can be dragged (using the left mouse button) to change the display of the Structure Browser. Clicking the left mouse button in an area of the Overview window repositions the currently visible area.
The Structure Browser accepts any valid expression. If the result type is simple, a structure displays showing the type and value. If the result type is a pointer, it is automatically dereferenced until a non-pointer type is reached. If the result type is a structure or union, an object is displayed showing the structures' fields and their values. After the expression is entered, the Expression field clears. The Structure Browser can display unrelated structures at the same time—you simply enter new structures using the Expression field.
The Expression field is also used to enter strings used in searches.
Within the display area, you select objects by clicking in the node headers. Shift-clicks add the selected object to the current selection. You can drag selected objects using the middle mouse button.
Clicking the right button while the cursor is in the right column of an object displays the Format menu, used to change the display of a specific result (see Figure A-109). You can set a default format or request that results be displayed by value, type, address, or size in bits.
Holding down the right button in the header of a Structure Browser object brings up the Node popup menu, which is the same as the Node Menu in the menu bar. It is used to change the way selected objects are displayed. When you left-click in the header of an object, it turns on the resizer, which lets you change the size of the object. Left-clicking the handle resizes; middle-clicking moves it.
Graphical arrows show the pointer relationships among the displayed structures. If a pointer field is not visible in a structure, its arrow tail is displayed at the top or bottom of the scrolling area for fields. Otherwise, its tail is adjacent to its field.
Double-clicking a value field (right column) for a pointer dereferences it, so that the data structure it points to is displayed.
Double-clicking a member field (left column) puts the full expression for that member in the Expression field.
The Display menu controls the way structures appear in the display area of Structure Browser. The menu is shown in Figure A-110.
The Display menu provides the following selections:
| "Display" | has two options: | |
| "Arrange" | rearranges the currently selected nodes. There are two options (see Figure A-111): | |
| "Search" | Lets you select structures containing the string specified in the Expression field. There are four options:
| |
| "Update" | Explicitly updates the displayed structures. This happens automatically in the current Structure Browser when the process stops. This can be used in an inactive Structure Browser to update it. It can also be used to update the display after changes have been made in other Debugger views. | |
| "Show Overview" |
| |
| "Clear All" | Clears all structures from the display area. |
The Node menu is shown in Figure A-112.
The Node menu consists of the following entries and applies to the currently selected objects:
| "State" | Controls the display of nodes. There are three options: | |
| "Geometry" | Manages graphical objects in the display area. There are four options:
| |
| "Select" | Lets you select objects in various ways. There are six options:
| |
| "Formatting" | Brings up the type formatting dialog for this type. See "Formatting Fields." | |
| "Dereference Ptrs" |
| |
| "Pattern Layout" |
| |
| "Remove" | Removes the selected object from the display. |
Each field in a data structure has certain display characteristics. These can be specified for all objects in the Structure Browser Preferences dialog box or for type-specific objects only in the Type Formatting dialog box. To display the Structure Browser Preferences dialog box, select "Preferences..." from the Config menu (see Figure A-113).
The Structure Browser Preferences dialog box has the following fields:
To bring up the Type Formatting dialog box, select the set of structures under consideration and select "Node Formatting" from the Node menu (see Figure A-114).
The Type Formatting dialog box has the following fields:
For structure and union types, the list box shows all the fields with their types. For each field, you can change the result format to one of the following:
default
decimal
unsigned
octal
hex
float
char
string
type
dec addr
oct addr
hex addr
size in Bits
You can also specify whether a field is visible in normal state, and if it is a pointer field, whether it should be automatically dereferenced.
Once you specify the format for this type, you can apply it to any combination of the following through the toggle buttons in the bottom left portion of the window:
The Variable Browser lets you view and change the values of local variables and arguments at a specific point in a process. (Global variables can be viewed or changed using Expression View or the "Evaluate Expression" selection from the Data menu for one-shot evaluations.) In addition to providing the values, Variable Browser is useful for getting a quick list of the local variables in a scope without having to search for their names. A sample Variable Browser window with the Language and Format menus displayed is shown in Figure A-115. (For a tutorial example of the Variable Browser see "Examining Data".)
Typically, you inspect variable values
at a stop trap
at a frame in a call stack
as you step through a process
 | Note: A useful technique is to set a trap at the entry to a function and inspect the values of the variables there. Some variables may be in an uninitialized state at that point. You can then step through the function and make sure that no uninitialized variables are used inadvertently. |
The Variable Browser lets you change the values of variables in the window. You simply enter the new value in the result column and press <Enter>. Thus, you can force new values into the process and see their effect.
The Variable Browser has a sash between columns that lets you adjust the relative widths of the Variable and Result columns (see Figure A-115). For example, you may wish to adjust for short variable names and long result values.
The Debugger views that are involved with variables (that is, the Variable Browser and Expression View) have indicators that show when the variable has changed since the last breakpoint. If you click the indicator, you can view the previous value. The variable change indicators for a Variable Browser window are shown in Figure A-116.
The Debugger offers three views useful in debugging at the machine level; the Disassembly View, Register View, and Memory View.
The Disassembly View of the Debugger lets you look at machine-level code rather than source-level code. A typical Disassembly View window appears in Figure A-117, with the Disassemble menu displayed.
At the top of the window are the same process control buttons as those in Debugger Main View. They behave the same way except for Step Into and Step Over, which do machine-level instruction stepping instead of source-level. Remember that you select the number of steps by holding down the right mouse button over the Step Into and Step Over buttons.
The menus are basically the same as in Main View except for the Disassemble menu. The PC menu selections "Continue To" and "Jump To" are based on machine-level instructions rather than source-level steps. The Config menu has a "Preferences..." selection that brings up a dialog box oriented to Disassembly View.
You can set traps either by using the Traps menu or by clicking in the annotation column of the source display area that contains the disassembled code.
The Disassemble menu (see Figure A-118) lets you display disassembled code. It contains the following items:
| "Address..." | allows you to disassemble a specified number of lines, starting from a specified source line address (see Figure A-119). | |
| "Function..." | allows you to disassemble a specified number of lines, starting from the beginning address of a specified function name (see Figure A-120). | |
| "File..." | allows you to disassemble a specified number of lines, starting from the address corresponding to a specified line number in a specified file (refer to Figure A-121). If you have a current selection in Main View or Source View, its file and cursor position are used as the default filename and line number, respectively. |
Selecting "Preferences..." from the Config menu brings up the Disassembly View Preferences dialog box (shown in Figure A-122) so that you can change the global preferences.
The dialog box provides you with these options:
| Number of instructions to disassemble |
| |
| Minimum lines around current instruction |
| |
| Register name display format |
The Display Options selections control what information is shown in each disassembled line. | |
| Show embedded source annotation |
| |
| Show source file and line number |
| |
| Show function name and line number |
| |
| Show machine address |
| |
| Show instruction value |
| |
| Show jal targets numerically |
|
Register View lets you examine and modify register values. You bring it up by selecting "Register View" from the Views menu in Main View. Figure A-123 shows a typical Register View window that has been resized to show all available registers.
Register View displays each register with its current value. A question mark (?) displayed immediately before a register value signifies that the value is suspect; it may not be valid for the current frame. This can occur if a register is not saved across a function call. A colored marker indicates that a register value has changed since the last time the process stopped.
The major features of the Register View window are:
| Current register field |
| |
| Current register value field |
| |
| Register display area |
|
| Note: The special registers p0, p1, and p2 are empty in the figure. These are used for instrumentation and display values only when instrumentation has taken place. |
The "Preferences..." selection in the Config menu lets you change the Register View display. It brings up the Register View Preferences dialog box (see Figure A-124).
The Register Display toggle buttons let you specify which types of registers are to be displayed by default.
The Register Formatting area lets you select formats for any of the registers. You have a choice of "default," "decimal," "octal," or "hex" format.
The default fields in the top row let you change the defaults for the four major types, which are set as follows:
general registers—hexadecimal
special registers—hexadecimal
float registers—floating point
double registers—floating point
The rows in the register formatting area let you change the modes for the individual registers.
Memory View lets you examine and modify memory. A typical Memory View window appears in Figure A-125.
To view a portion of memory, enter the beginning memory location in the Address field. You can enter the literal value or an expression that evaluates to an integer address. These address specifications must be in the language of the current process as indicated by the call stack frame. For example, you can enter 0x7fff4000+4 as the memory address when stopped in a C function or enter $7fff4000+4 as the equivalent for a Fortran routine. Press <Enter> while the cursor is in the field or click the View button to display the contents of that location and the subsequent locations in the display area. This also displays the contents of the first address in the Value field where it can be modified.
The memory display area shows the contents of individual byte addresses. The column at the left of the display shows the first address in the row. The contents at that address are shown immediately to its right, followed by the contents of the next seven byte locations. If you enlarge the Memory View window, you can see additional rows of memory.
To change the contents of a memory location, you select the address to be changed, either by direct entry or by clicking on the byte value in the display area. You can enter a single value or a sequence of hex byte values separated by spaces (for example, 00 3a 07 b2) in the Value field. You can also enter a quoted string to change a consecutive range of values to the ASCII values of that string. Pressing <Enter> while the cursor is in the Value field or clicking the Modify button substitutes the new value(s) starting at the specified location.
The Mode menu lets you change the format of the value field or byte locations to either decimal, octal, hex, or ASCII.
The four control buttons at the upper right of the window help you move around the display area. These buttons are:
| Up | for moving the displayed bytes up a single row. | |
| Down | for moving the displayed bytes down a single row. | |
| Page Up | for moving the displayed bytes upward by as many rows as are currently displayed. | |
| Page Down | for moving the displayed bytes downward by as many rows as are currently displayed. |
WorkShop supports performance analysis and debugging of multiprocess applications, including processes spawned either with fork or sproc. Multiprocess debugging is supported primarily through the Multiprocess View.
Select "Multiprocess View" from the Admin menu to bring up Multiprocess View. Main View is attached to the parent process. Figure A-126 shows a typical Multiprocess View with Config and Process menus displayed.
To open a Main View (or other debugging views) for another process, double-click the desired process in Multiprocess View. A separate Main View window displays the selected process, and you can select any debugging views desired. If a set of views exists for that process, the views are raised to the foreground. To reuse views already displayed, select "Switch Process..." from the Admin menu in Main View. (If a process is currently highlighted in Multiprocess View, its id is entered automatically in the Process id: field in the Switch Process dialog box.)
When Multiprocess View comes up, it lists the status of all processes in the process group. This information includes:
| PID: | shows the process identifier (id). | |
| PPID: | lists the parent process ids. Notice in Figure A-126 that the first process PID#7748 is the parent process of the second. | |
| State: | represents the state of the process: stopped, running, or created, which appears just prior to running. Terminated processes are not displayed. | |
| Name: | identifies the process by filename. | |
| Function/PC: | indicates the current function and program counter (PC) for any stopped processes. |
Multiprocess View uses the same control buttons as MainView with two exceptions. The buttons are applied to all processes as a group. There is no separate Run button. Using a control button in Multiprocess View has the same effect as clicking the button in each process's Main View window. The buttons are:
| Continue | resumes program execution after a halt and continues until a stop trap or other event stops execution. | |
| Stop | stops execution of all processes. When program execution stops, the current source line of each process is highlighted in its Main View, if one is active, and annotated with an arrow indicating the PC. | |
| Step Into | steps to the next source line and into function calls. To step a specific number of lines, hold down the right mouse button over the Step Into button. A popup menu displays that lets you select one of the fixed values or a specified number of steps. | |
| Step Over | steps to the next source line and over function calls. To step a specific number of lines, hold down the right button over the Step Over button. A popup menu displays that lets you select one of the fixed values or a specified number of steps. | |
| Return | executes the remaining instructions in the current function. Program execution stops upon return from that procedure. | |
| Sample | collects performance data for each process (if performance data collection is enabled). | |
| Kill | terminates all processes in the group. |
As discussed in Chapter 4, "Setting Traps," the trap qualifiers [all] and [pgrp] are used in multiprocess analysis. The [all] entry stops or samples all processes when a trap fires. The [pgrp] entry sets the trap in all processes within the process group containing the trap location. The qualifiers can be entered by default by the "Group Trap Default" and "Stop All Default" selections in the Traps menu in Trap Manager.
Note that the Sample button always samples all processes.
The Process menu lets you manually add or remove a process from the process group (see Figure A-127).
To remove a process, click the process and select "Remove" from the Process menu. Note that a process in a sproc share group cannot be removed from the process group.
To add a process, select "Add..." The dialog box shown in Figure A-128 displays. Enter the new process id and click OK.
The "Preferences..." option in the Config menu brings up the Preferences dialog box. It lets you control when processes are added to the group, and it specifies their behavior (see Figure A-129).
The Multiprocess View preference options are:
| Attach to forked processes |
| |
| Copy traps to forked processes |
| |
| Copy traps to sproc'd processes |
| |
| Resume parent after fork |
| |
| Resume child after attach on fork |
| |
| Resume parent after sproc |
| |
| Resume child after attach on sproc |
|
The Fix and Continue GUI affects several WorkShop windows and provides three more. The Debugger and Source View access the Fix and Continue utility from the menu bar. The results of running redefined code are displayed in the Debugger Execution View. Special line numbers (decimal notation) applied to redefined functions appear in several WorkShop views (refer to "Changes to Debugger Views"). Fix and Continue comes with three windows devoted entirely to Fix and Continue: Status, Message, and Build Environment. This section describes Fix and Continue menu selections and these windows.
The Fix and Continue menu is available from the Debugger Main View menu bar, as shown in Figure A-130. The menu selections operate on the selected function or on the file shown in the source view. The Fix and Continue menu is also available from Source View and from the Fix and Continue Status window.
This section describes the Fix+Continue Status window (see Figure A-131). The Status window provides you with a summary of the modifications that you have made during your session. It also allows you quick access to your modified functions, and a somewhat expanded Fix+Continue menu.
The function ID number, status, name, and filename are displayed in the Status window. Double-clicking a line item in the status window brings up the corresponding source in the Debugger main window.
The menus and submenus that provide you with extra functionality through the Status window (see Figure A-132) are described below.
The Admin menu (see Figure A-133) contains an option for closing the window.
| "Close" | Closes the Status window. |
The View menu (see Figure A-134) contains options for sorting the information in the window, and displaying filenames.
| "Sort Status View" |
| |
| "Show Long Filenames" |
|
The Fix+Continue menu (see Figure A-135) that is available from the Status view is somewhat different from that available through the Debugger main view. It contains a number of options and submenus, which are all described below. These options and submenus are active on the function that you select in the Source view. You can select a function by clicking on it.
| "External Editor" |
| |
| "Parse And Load" |
| |
| Update All Files..." |
| |
| "Show Difference" submenu (see Figure A-136) |
you to show the difference between the original source and your modified code. You can show the difference in the code in one of the two following ways:
| |
| "Enable" submenu (see Figure A-137) |
you to enable the changes in your modified code in one of the three following ways:
| |
| "Disable" submenu (see Figure A-137) |
| |
| "Save" submenu (see Figure A-138) |
you to save your code changes to a file. You can save the changes in one of the three following ways:
| |
| "Delete" submenu (see Figure A-137) |
| |
| "Show" submenu (see Figure A-140) |
you to launch any of the following three different Fix and Continue windows:
|
The Fix+Continue Message window (see Figure A-141) contains a list of any errors and other system messages that pertain to your source modifications, parses, and attempts to run your modified source.
You can highlight the source line where the error occurred by double-clicking the appropriate line in the Message window. The window contains the following buttons:
| Clear | Clears all the parsing errors and warnings. | |
| Next | Puts a tick mark on the next unticked error warning entry in the parse messages. It displays the corresponding file and line in the Source view, highlighting it according to the type of error or warning. Next doesn't function after all the entries in the messages are ticked. | |
| Rescan | Erases all the ticks, so that you can rescan all the error warnings from the beginning. |
The added functionality available through the Message window's Admin and View menus is described below.
The Admin menu allows you to perform either of the following two operations:
| "Clear All" | Clears all messages in the Message window. | |
| "Close" | Closes the window. |
The View menu allows you to set any of the following three toggles:
| "Show Warnings" |
| |
| "Append Parse Messages" |
| |
| "Append Load Messages" |
|
This section describes the Fix+Continue Build Environment window (see Figure A-142). The Build Environment window provides you with the build information for your source code in your current environment. It displays the command that was used to build your executable and the name of the file that contains the function that you currently have selected.
The compiler and associated flags that were used to compile the file are normally gathered from the target. You can use the Build Environment window to make any changes to these flags.
The Build Environment window allows you to select your build environment setting through the "Build Environment Setting" toggle, which contains the two options described below:
| "Default" | Sets the build environment to default that is displayed in the Build Environment window. | |
| "File Specific" | Sets the build environment to that of the file that contains the currently selected function. You can change the file by clicking the Select File button, which launches the File dialog (see Figure A-139). |
The Build Environment window also contains the following buttons:
| Select File | Launches the File dialog and allows you to select a file from which to set the build environment. | |
| Clear | Clears the window. | |
| Set | Sets the build environment to what is displayed in the window. | |
| Unset | Unsets the build environment. | |
| Done | Dismisses the window. |
When you use Fix and Continue, Debugger views change to show redefined functions or stopped lines containing redefined functions.
When you open the Debugger after installing Fix and Continue, you'll notice several changes to the environment. All Fix and Continue functions are available through the Fix+Continue menu. See Figure A-143 for details.
You select Fix and Continue commands from the Fix+Continue menu or enter them at the Debugger command line. The source code status is Read Only. Color coding shows the differences between editable code, enabled redefinitions, disabled definitions, and breakpoints. Line numbers in redefined functions have decimal notation that is used for every reference to the line number. The integer portion of the decimal is the same as the first line of the function. This ensures that compiled source code line numbers remain unchanged.
The Debugger command-line interface accepts Fix and Continue commands and reports status involving redefined functions or files. Figure A-144 shows a function successfully redefined using the command line. Change id 1 was previously redefined and assigned the number 1.
The Call Stack View recognizes redefined functions. It uses the decimal notation for line numbers, as shown in Figure A-145.
The Trap Manager recognizes redefined functions. It uses the decimal notation for line numbers, as shown in Figure A-146.
To use the Debugger commands, which are entered at the command line at the bottom of Main View (see Figure A-1), you should be familiar with dbx commands. For more information, refer to the dbx Reference Manual. The syntax for the debugging commands is as follows:
| add_source {"filename":line_number} |
| ||||
| alias [shortform command] |
| ||||
| assign expression1=expression2 |
| ||||
| attach pid | attaches to specified process ID pid. | ||||
| call function_name [argument, ...] |
| ||||
| catch [signal_name | all] |
| ||||
| clear [all | source_line] |
| ||||
| clearbuffer | Clears the currently displayed lines. | ||||
| clearcalls | Cancels pending interactive function calls. | ||||
| cont in function_name |
| ||||
| cont to line_number |
| ||||
| continue | Continues executing a program after a breakpoint. Note that you can c and cont as aliases for continue. | ||||
| continue [signal] |
| ||||
| corefile [filename] |
| ||||
| delete displaynumber [,displaynumber, ...] |
| ||||
| delete all | deletes all traps. | ||||
| delete_changes {func_spec | -all | {-file filename}} |
| ||||
| delete_source {"filename":line_number[,line_number]} |
| ||||
| delete trap_number [,trap_number, ...] |
| ||||
| detach | Detaches from the current process. | ||||
| disable all | Deactivates all inactive traps. | ||||
| disable_changes {func_spec | -all | {-file filename}} |
| ||||
| disable trap_number [,trap_number, ...] |
| ||||
| display [expression, ...] |
| ||||
| down [expression] |
| ||||
| dump | Prints local variable values. | ||||
| enable all | Reactivates all inactive traps. | ||||
| enable_changes {func_spec | -all | {-file filename}} |
| ||||
| enable trap_number [,trap_number, ...] |
| ||||
| expression/[count] [format] or expression,[count] /[format] |
d prints a short word in decimal | ||||
| file [filename] |
| ||||
| func [func_name] |
| ||||
| givenfile [filename] |
| ||||
| goto linenumber |
| ||||
| ignore [signal_name | all] |
| ||||
| kill [pid] | Kills the specified process currently controlled by the Debugger. | ||||
| list [[expression [,expression]] | [function_name]] |
| ||||
| list_changes [func_spec | -all | {-file filename}] |
For example:
The default is list_changes -all. | ||||
| next [INT] | Steps over the specified number of source instructions. This command does not step into procedures. The default is one instruction. | ||||
| nexti [INT] | Steps over the specified number of machine instructions. This command does not step into procedures. The default is one line. | ||||
| print expression [,expression, ...] |
| ||||
| printd expression [,expression, ...] |
| ||||
| printo expression [,expression, ...] |
| ||||
| printregs | Prints the contents of the registers. | ||||
| printx expression [,expression, ...] |
| ||||
| pwd | Sisplays the current directory. | ||||
| quit | Exits the debugging session. | ||||
| redefine func_spec |
| ||||
| replace_source {"filename":line_number[,line_number]} |
| ||||
| rerun | Runs the program again using the same arguments. | ||||
| return | Continues executing the current procedure and returns to the next sequential line in the calling function. | ||||
| run | Runs the program. | ||||
| runtime_check func_spec [-options key [key,...]] |
key = [[+|-] runtime_check option key] A unique identifier (key) is returned whenever you specify a function as an argument for runtime_check. | ||||
| save_changes {func_spec | {-file filename}} |
If you specify the -file option, then before saving to filename_to_save, all function changes are applied to the compiled source of the file (with the condition that the file has had only its functions redefined, and has not been edited since the last build). An example of saving an entire file is the following:
-w replaces the filename_to_save. -a appends to the file_to_save. An example of adding a function to a file is the following:
See also delete_changes. | ||||
| setbuildenv ["filename"] compiler-flag-list |
See also unsetbuildenv. | ||||
| sh [shell_command] |
| ||||
| showbuildenv ["filename"] |
| ||||
| show_changes [func_spec | -all | {-file filename}] |
| ||||
| show_diff {func_spec | {-file filename}} |
| ||||
| source filename |
| ||||
| status | Displays a list of currently set breakpoints and traces. | ||||
| step [INT] | Steps the specified number of source instructions. This command steps into procedures. The default is one instruction. | ||||
| stepi [INT] | Steps the specified number of machine instructions. This command steps into procedures. The default is one line. | ||||
| stop at [filename:] line_number [if expression] |
| ||||
| stop in [filename:] function_name [if expression] |
| ||||
| syscall catch | ignore [call | return] \ |
| ||||
| trace [variable] at [["filename":] \ |
| ||||
| unalias aliasname |
| ||||
| undisplay [displaynumber, ...] |
| ||||
| unsetbuildenv ["filename"] |
If filename is given, this command disregards the build environment flags specified for the file earlier. Further redefinition of the functions in the file use the default build environment flags, if set. See also setbuildenv. | ||||
| up [expression] | Moves up the specified number of frames in the call stack. up moves in the direction of the caller. | ||||
| use [path] | uses the specified path to search for source files. | ||||
| whatis identifier |
| ||||
| when at [filename:] line_number {command [; command ...]} |
| ||||
| when in [filename:] function_name {command [; command ...]} |
| ||||
| which identifier | Displays the qualification of the specified variable. | ||||
| where | Performs a stack trace. |
