home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
HELP
/
DDE4XTRA.HLP
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1993-04-28
|
111KB
|
4,192 lines
ΓòÉΓòÉΓòÉ 1. Notices ΓòÉΓòÉΓòÉ
References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM licensed program in this publication is not
intended to state or imply that only IBM's licensed program may be used. Any
functionally equivalent product, program or service that does not infringe any
of IBM's intellectual property rights may be used instead of the IBM product,
program, or service. Evaluation and verification of operation in conjunction
with other products, except those expressly designated by IBM, is the user's
responsibility.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director
of Commercial Relations, IBM Corporation, Purchase, NY 10577.
ΓòÉΓòÉΓòÉ 1.1. Trademarks and Special Notices ΓòÉΓòÉΓòÉ
The following terms, used in this online information, are trademarks and
service marks of IBM Corporation in the United States and other countries:
IBM
Operating System/2
OS/2
ΓòÉΓòÉΓòÉ 1.2. Conventions Used in the Online Help ΓòÉΓòÉΓòÉ
The following highlighting conventions are used in this online help:
Bold
Names of windows, menus, menu choices, push buttons, radio buttons,
and entry fields.
Monospace
Text displayed in a sample program and text that you type.
Italics
Words that are used for emphasis and variables in command strings.
ΓòÉΓòÉΓòÉ 1.3. Notes about this Online Help ΓòÉΓòÉΓòÉ
The following conventions are used in this online help:
o The words program and application are used synonymously in this online help.
Both words refer to the executable file that you are tracing.
o The word diagram is used to refer to all diagrams, as well as the Statistical
Summary and the Dynamic Call Graph.
o All examples in this online help used C/C++.
ΓòÉΓòÉΓòÉ 2. Adding Debugging Information to Your Application ΓòÉΓòÉΓòÉ
To add debugging information to your application, you must compile and link the
application with the proper options. The following topics explain how to
compile and link your application.
Compiling an Application
To compile your application, use the following options:
/Gh Includes the profile hooks that allow EXTRA to monitor your
executable.
/Ti Includes debugging information in the compiled object file, which
would be a file with the OBJ file extension. EXTRA needs this
information the same as a debugger does.
Linking an Application
You must link the DDE4XTRA.OBJ with your application.
To link with IBM LINK386, use the following option:
/DE Enables the linker to include debugging information in the executable
(EXE or DLL file). EXTRA needs this information the same as a
debugger does.
To view the MAKE file called PMLINES.MAK, see PMLINES.MAK.
ΓòÉΓòÉΓòÉ 2.1. Adding Debugging Information to PMLINES.MAK ΓòÉΓòÉΓòÉ
The following MAKE file shows how to compile and link the PMLINES.MAK
application so that EXTRA can trace it.
pmlines.exe: pmlines.obj dde4xtra.obj pmlines.res
link386 /DE /pmtype:pm pmlines extra,,pmlines,_doscall /
_pmwin _pmgpi;
rc pmlines.res
pmlines..res: pmlines.rc pmlines.ico pmlines.h pmlines.dlg
rc -r pmlines.rc
pmlines.obj: pmlines.c pmlines.h
icc /c /Fa /S2 /Ti /Gh pmlines.c
ΓòÉΓòÉΓòÉ 2.2. Tracing the System Calls ΓòÉΓòÉΓòÉ
If you want to trace calls into the OS/2* Toolkit Application Interface (API),
specify the following EXTRA libraries immediately before the OS/2 libraries in
your link statement. This is shown in the PMLINES.EXE example.
The APIs and their corresponding libraries are as follows:
DosCalls _DOSCALL.LIB
WinCalls _PMWIN.LIB
GPICalls _PMGPI.LIB
Notes:
1. Each library listed above also has an associated DLL.
2. The order is critical. If the replacement libraries are not immediately
before the OS/2 libraries in the link statement, EXTRA may not interpret
and trace the API calls.
ΓòÉΓòÉΓòÉ 2.3. Defining User Events ΓòÉΓòÉΓòÉ
The DDE4XTRA.OBJ file contains an entry point called EXTRA that accepts calls
from the application you are analyzing. The entry point inserts text strings,
which are called user events, into the trace file. User events help you
diagnose problems in your application. You can add user events to your
application by adding the following statement to your application source code:
EXTRA(string);
where string is an ASCIIZ string. When such a call is made, the string is
placed in the trace file. You can see these strings in the Call Nesting diagram
and in the Statistical Summary.
Warning:
The string must be unique static alphanumeric characters. Otherwise, you will
receive unpredictable results.
The string must exist in storage when the trace buffer containing the reference
is written to disk.
Creating EXTRA C and C++ Prototypes
The application that contains the EXTRA entry point must have a prototype. You
must declare a prototype for C applications, as follows:
VOID EXTRA (PSZ string);
You must declare a prototype for C++ applications, as follows:
EXTERN "C" {
VOID EXTRA (PSZ string);
}
ΓòÉΓòÉΓòÉ 3. Startup Information Window ΓòÉΓòÉΓòÉ
1. Type the full path and file name of the application you want to trace in
the Trace file name entry field. If the trace file is in your current
directory, you do not have to type the path.
2. Select the OK push button to display the diagram or select the Cancel push
button to return to the command prompt.
ΓòÉΓòÉΓòÉ 4. Directory Window ΓòÉΓòÉΓòÉ
When you start EXTRA for the first time, the Directory window is displayed. The
Directory window prompts you to type the path where you want to store the INI
file. The INI file stores your session settings. Type the full path name and
select OK. The INI file is created in the directory you specified.
ΓòÉΓòÉΓòÉ 5. Push Buttons ΓòÉΓòÉΓòÉ
The following push buttons are available in most EXTRA action windows unless
otherwise indicated:
All max
Select this push button to set the call depth of all threads to the
maximum limit of 128. The push button is only available in the Set
Call Depth action window.
All off
Select this push button to set the call depth of all threads to 0.
The push button is only available in the Set Call Depth action
window.
Cancel
Select this push button to exit the current action window without
saving any changes.
Clear all
Select this push button to clear all selected elements in the action
window. This push button is available from the Select Functions
action window and the Select threads action window.
Default
Select this push button to reset all changes in an action window to
the default settings.
Find callee
Select this push button in the Who Calls Whom action window to select
and center the node that is called. For more information, see the Who
Calls Whom action window.
Find caller
Select this push button in the Who Calls Whom action window to select
and center the node that makes the call. For more information, see
the Who Calls Whom action window.
Help
Select this push button to learn how to use the action window that is
currently displayed.
OK
Select this push button to save the changes and close the action
window.
Search
Select this push button in the Search action window to start
searching for a user event, a file access, a call for a function, a
return to a function, or an annotation. For more information, see the
Search action window.
Select all
Select this push button to select all elements in the action window.
Stop
Select this push button in the Application Termination window to stop
your application while it is being analyzed by EXTRA.
Trace
Select this push button to begin tracing your application.
Who calls me
Select this push button in the Function Information action window to
display only the selected node and the nodes that called the selected
node. For more information, see the Function Information action
window.
Whom do I call
Select this push button in the Function Information action window to
display only the selected node and the nodes that the selected node
calls. For more information, see the Function Information action
window.
ΓòÉΓòÉΓòÉ 6. Trace Generation Window ΓòÉΓòÉΓòÉ
The Trace Generation window is the main window of EXTRA. This window contains
the executable file names of the application you want to trace. An executable
contains object files and each object file contains functions.
An executable or object file that is displayed in black contains the necessary
debugging information for EXTRA to trace the application. An executable or an
object file that does not contain debugging information is displayed in cyan.
Note: For an executable or object file to be traceable, you must include
debugging information. For more information, see adding debugging information.
Showing and Hiding Object Files and Functions
To show the object files that comprise the executable, select the plus icon
next to the executable file name. The object files are displayed beneath the
executable. You can select the plus icon next to an object file to see the
functions. The functions are displayed beneath the object file.
By selecting the minus icon you can hide the object files and functions.
Enabling and Disabling Object Files and Functions
You can disable or enable an executable, an object file, or a function by using
the Options menu or using the pop-up menu. When you enable an executable, an
object file, or a function, EXTRA includes information about that item in the
trace file. When you disable an executable, an object file, or a function,
EXTRA does not include information about that item in the trace file. A
disabled executable, object file, or function is displayed in brown.
Menu Bar Summary
The Trace Generation window contains the following choices on the menu bar:
Edit
Accesses various action windows that let you view the executables,
object files, and functions of your application and controls which
parts of your application are traced.
Options
Selects specific actions used when your application is traced.
Help
Accesses information about menu choices, tasks, and key words. Press
F1 or select the Help push button to access Help.
Push Button and Check Box
The following push button and check box are available from the Trace Generation
window:
Trace push button
Begins a trace session.
Save settings check box
Specifies whether your menu settings are to be saved.
Pop-Up Menu Summary
A pop-up menu is available when you use mouse button two to select any
executable, object file, or function. Choices from the pop-up menu allow you to
select specific actions to customize the trace analysis.
ΓòÉΓòÉΓòÉ 6.1. Trace Push Button ΓòÉΓòÉΓòÉ
Select the Trace push button to close the Trace Generation window and begin
tracing your application.
ΓòÉΓòÉΓòÉ 6.2. Save Settings Check Box ΓòÉΓòÉΓòÉ
The Save settings check box is located at the bottom of the Trace Generation
window. If you want to save the current menu settings you have selected, select
the Save settings check box. Saving the current settings prevents you from
having to specify a complicated setup more than once.
When you select Save settings, a √ symbol is displayed. If a √ symbol is not
displayed, Save settings is disabled. This is the default.
Note: The settings are not saved until the Trace Generation window is closed
or until you begin the trace analysis. These settings are kept, for each
application, until you reset them.
ΓòÉΓòÉΓòÉ 6.3. Options Menu ΓòÉΓòÉΓòÉ
Select choices from the Options menu to access various action windows that let
you set options to customize your trace sessions. These options control the
operation of EXTRA.
Select clock
Select to log or not log time stamps.
Buffer control
Select the size of the event log buffer, plus enable and disable
buffer wrapping.
Set call depth
Select the call nesting depth limit for each thread.
Name trace file
Type a new path or rename the trace file for the application you are
analyzing.
Timeout control
Select the maximum number of seconds your application may run without
logging events. Use this choice when your application is in a
continuous loop.
File access
Select to trace or not trace file accesses.
Default setup
Select to revert to the default settings.
ΓòÉΓòÉΓòÉ 6.3.1. Select Clock Choice ΓòÉΓòÉΓòÉ
Select the Select clock choice to enable or disable time stamps. If you choose
to disable the time stamp choice, EXTRA produces a smaller trace file and only
the Statistical Summary, Call Nesting diagram, and Dynamic Call Graph can be
viewed. The default is to have the time stamps enabled.
When you select the Select clock choice, a Select Clock action window is
displayed.
ΓòÉΓòÉΓòÉ <hidden> Select Clock Action Window ΓòÉΓòÉΓòÉ
When you select the Select clock choice, a Select Clock action window is
displayed.
This action window lets you enable or disable time stamps.
To use the Select Clock action window:
1. Choose to enable or disable time stamps:
o Select the Yes radio button to enable the time stamp choice
OR
o Select the No radio button to disable the time stamp choice.
2. Select the OK push button to save the changes and exit the action window or
select the Cancel push button to ignore the changes and exit the action
window.
Note: To keep this setting active for more than one trace, select the Save
settings check box in the Trace Generation window. The settings are not saved
until the Trace Generation window is closed or you begin the trace analysis.
ΓòÉΓòÉΓòÉ 6.3.2. Buffer Control Choice ΓòÉΓòÉΓòÉ
Select the Buffer control choice to set the size of the event log buffer and to
enable or disable buffer wrapping.
The event log buffer size determines how often the data from the trace analysis
is written to the trace file. The default is set to 256 kilobytes (KB).
You can enable or disable the buffer wrapping to choose when the data is
written to the trace file. When buffer wrapping is enabled, the trace data is
written only when the tracing has stopped. As the program is traced, the buffer
fills and overwrites the older events in the buffer. When buffer wrapping is
disabled, the data is written to the trace file every time the buffer fills.
The default is to disable buffer wrapping.
When you select Buffer control, a Buffer Control action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Buffer Control Action Window ΓòÉΓòÉΓòÉ
When you select the Buffer control choice, a Buffer Control action window is
displayed. This action window has two entry fields: Buffer size and Buffer
Wrapping.
To use the Buffer Control action window:
1. Set the buffer size by selecting the spin buttons in the Buffer size entry
field. The top spin button increases the buffer size and the bottom spin
button decreases the buffer size.
2. Enable or disable buffer wrapping by selecting a radio button.
o Select the On radio button to enable buffer wrapping.
o Select the Off radio button to disable buffer wrapping.
3. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Note: To keep this setting active for more than one trace, select the Save
settings check box in the Trace Generation window. The settings are not saved
until the Trace Generation window is closed or you begin the trace analysis.
ΓòÉΓòÉΓòÉ 6.3.3. Set Call Depth Choice ΓòÉΓòÉΓòÉ
Select the Set call depth choice to set the nesting depth for each thread in
your application. You can select as many as 16 threads with a maximum nesting
depth of 128 for each thread. The default is to have all threads selected with
the maximum depth of 128.
When you select Set call depth, a Set Call Depth action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Set Call Depth Action Window ΓòÉΓòÉΓòÉ
When your select the Set call depth choice, the Set Call Depth action window is
displayed. The Set Call Depth action window displays 16 thread entry fields.
To use the Set Call Depth action window:
1. Select the All max push button to set the maximum depth of all threads to
128.
2. Select the All off push button to change the depth to 0 for all threads.
3. Select a thread entry field and type in a number.
Note: To disable tracing of any event in a thread, set the call depth of
that thread to 0.
4. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Note: To keep this setting active for more than one trace, select the Save
settings check box in the Trace Generation window. The settings are not saved
until the Trace Generation window is closed or you begin the trace analysis.
ΓòÉΓòÉΓòÉ 6.3.4. Name Trace File Choice ΓòÉΓòÉΓòÉ
Select the Name trace file choice to replace the name of the output file you
are analyzing. The default name for the trace file is filename.TRC, where
filename is the name of the application you are currently tracing.
When you select Name trace file, a Name Trace File action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Name Trace File Action Window ΓòÉΓòÉΓòÉ
When you select Name trace file, the Name Trace File action window is
displayed.
To use the Name Trace File action window:
1. Type the new path, file name, and file extension in the entry field.
2. Select OK to accept the changes and close the action window or select the
Cancel push button to close the action window without saving the changes.
Note: To keep this setting active for more than one trace, select the Save
settings check box in the Trace Generation window. The settings are not saved
until the Trace Generation window is closed or you begin the trace analysis.
ΓòÉΓòÉΓòÉ 6.3.5. Timeout Control Choice ΓòÉΓòÉΓòÉ
Select the Timeout control choice to specify the maximum number of seconds your
application can run without logging events. Use this choice when your
application deadlocks to determine where the problem is located.
When you select Timeout control, a Timeout Control action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Timeout Control Action Window ΓòÉΓòÉΓòÉ
When you select the Timeout control choice, a Timeout Control action window is
displayed.
To use the Timeout Control action window:
1. Type a number from 0 to 3600 in the Number entry field or use the spin
buttons to scroll to the number of seconds you want.
Note: A 0 in the Number entry field implies there is not a maximum limit.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Note: To keep this setting active for more than one trace, select the Save
settings check box in the Trace Generation window. The settings are not saved
until the Trace Generation window is closed or you begin the trace analysis.
ΓòÉΓòÉΓòÉ 6.3.6. File Access Choice ΓòÉΓòÉΓòÉ
Select the File access choice to keep track of file access calls, such as
DosOpen( ), DosRead( ), DosWrite( ), DosClose( ), and DosDupHandle( ). When a
Dos call references a file, EXTRA keeps track of the file name associated with
the traced Dos calls. These calls are shown in the Call Nesting diagram and in
the Statistical Summary under the function that made the file access.
To set file access, select File access from the Options menu. A √ symbol is
displayed next to the choice to show it is enabled. To reset file access,
select File access from the Options menu. The √ symbol is removed to show the
choice is disabled.
Notes:
1. To keep this setting active for more than one trace, select the Save
settings check box in the Trace Generation window. The settings are not
saved until the Trace Generation window is closed or you begin the trace
analysis.
2. File access is a choice only when the _DOSCALL.LIB file is linked.
ΓòÉΓòÉΓòÉ 6.3.7. Default Setup Choice ΓòÉΓòÉΓòÉ
Select the Default setup choice to reset all options to the default settings.
This includes removing any triggers and enabling all executables, object files,
and functions.
To choose the default settings, select Default setup from the Options menu.
ΓòÉΓòÉΓòÉ 6.4. Edit Menu ΓòÉΓòÉΓòÉ
Trace Generation
Select choices from the Edit menu or pop-up menu menu to set triggers and
manipulate the executables, object files, and functions.
Show object files
Displays the object files in a selected executable. This choice is
available when an executable is selected and object files are hidden.
Hide object files
Hides object files in a selected executable. This choice is available
when an executable is selected and object files are shown.
Show functions
Displays the functions in a selected object file. This choice is
available when an object file is selected and the functions are
hidden.
Hide functions
Hides the functions in a selected object file. This choice is
available when an object file is selected and the functions are
shown.
Enable executable
Enables the executable. This choice is available when an executable
is selected.
Disable executable
Disables the executable. This choice is available when an executable
is selected.
Enable object files
Enables all object files in a selected executable. This choice is
available when an executable is selected.
Disable object files
Disables all object files in a selected executable. This choice is
available when an executable is selected.
Enable object file
Enables an object file. This choice is available when an object file
is selected.
Disable object file
Disables an object file. This choice is available when an object file
is selected.
Enable functions
Enables the functions. This choice is available when an object file
is selected.
Disable functions
Disables the functions. This choice is available when an object file
is selected.
Enable function
Enables a function. This choice is available when a function is
selected.
Disable function
Disables a function. This choice is available when a function is
selected.
Set trigger
Sets or resets a trigger on a function. This choice is available when
a function is selected.
To keep these settings active for more than one trace, select the
Save settings check box in the Trace Generation window. The settings
are not saved until the Trace Generation window is closed or you
begin the trace analysis.
ΓòÉΓòÉΓòÉ 6.4.1. Show Object Files Choice ΓòÉΓòÉΓòÉ
Select the Show object files choice to display all the object files in a
selected executable. This choice is available when an executable is selected
and the object files are hidden.
When you choose to show the object files that make up the executable, they are
displayed beneath the executable. The object files that are displayed in black
are traceable and object files displayed in cyan are not traceable. The
executables that have a plus icon to the left of them are expandable.
Showing All Objects
There are three ways to show all object files in an executable: by using the
Edit menu, by using the pop-up menu, or by using the plus icon. The following
explains how to use each method:
1. Using the Edit menu.
a. Select the executable you want to show.
b. Select Show object files from the Edit menu. The object files are
displayed beneath the executable.
2. Using the pop-up menu.
a. Use mouse button two to select the executable you want to show. A pop-up
menu is displayed.
b. Choose Show object files from the pop-up menu. The object files are
displayed beneath the executable.
3. Using the plus icon.
a. Select the plus icon at the left of the executable. The object files are
displayed beneath the executable. The plus icon changes to a minus icon.
ΓòÉΓòÉΓòÉ 6.4.2. Hide Object Files Choice ΓòÉΓòÉΓòÉ
Select the Hide object files choice to hide the object files. This choice is
available when an executable is selected and the object files are shown.
This choice contracts the executable so that the object files are not
displayed. When a minus icon is displayed next to an executable indicates that
it is expanded.
Hiding object files
There are three ways to hide the object files of an executable: using the Edit
menu, using the pop-up menu, or using the minus icon. The following explains
how to use each method:
1. Using the Edit menu.
a. Select the executable you want to hide.
b. Select Hide object files from the Edit menu. The object files are
contracted.
2. Using the pop-up menu.
a. Use mouse button two to select the executable you want to hide. A pop-up
menu is displayed.
b. Choose Hide object files from the pop-up menu. The object files are
contracted.
3. Using the minus icon. an executable and object file in the Trace Generation
window when the file can be shown or expanded.
a. Select the minus icon at the left of the executable. The object files
are contracted. The minus icon changes to a plus icon.
ΓòÉΓòÉΓòÉ 6.4.3. Show Functions Choice ΓòÉΓòÉΓòÉ
Select the Show functions choice to display the functions. This choice is
available when an object file is selected and the functions are hidden.
When you choose to show or expand an object file, the functions that make up
the object file are displayed beneath the object file. The functions that are
displayed in black are traceable and functions displayed in cyan are not
traceable.
Showing Functions
There are three ways to show all the functions of an object file: using the
Edit menu, using the pop-up menu, or using the plus icon. The following
explains how to use each method:
1. Using the Edit menu.
a. Select the object file you want to show.
b. Select Show functions from the Edit menu. The functions are displayed
beneath the selected object file.
2. Using the pop-up menu.
a. Use mouse button two to select the object file you want to show. A
pop-up menu is displayed.
b. Choose Show functions from the pop-up menu. The functions are displayed
beneath the selected object file.
3. Using the plus icon.
a. Select the plus icon at the left of the object file. The functions are
displayed beneath the selected object file. The plus icon changes to a
minus icon.
ΓòÉΓòÉΓòÉ 6.4.4. Hide Functions Choice ΓòÉΓòÉΓòÉ
Select the Hide functions choice to hide the functions. This choice is
available when an object file is selected and the functions are shown.
This contracts the object file so that the functions are not displayed. A minus
icon displayed next to an object file indicates that it is expanded.
Hiding Functions
There are three ways to hide the functions in an object file; using the Edit
menu, using the pop-up menu, or using the minus icon. The following explains
how to use each method:
1. Using the Edit menu.
a. Select the object file you want to hide.
b. Select Hide functions from the Edit menu. The functions are hidden.
2. Using the pop-up menu.
a. Use mouse button two to select the object file you want to hide. A
pop-up menu is displayed.
b. Choose Hide functions from the pop-up menu. The functions are hidden.
3. Using the minus icon.
a. Select the minus icon at the left of the object file. The functions are
hidden. The minus icon changes to a plus icon.
ΓòÉΓòÉΓòÉ 6.4.5. Enable Executable Choice ΓòÉΓòÉΓòÉ
Select the Enable executable choice to enable the selected executable.
This choice is available when an executable is selected. When an executable has
been disabled, the executable is displayed in brown. When you enable an
executable, EXTRA includes information about the executable in the trace file.
The executable stays disabled only during this trace analysis unless the Save
settings check box is selected.
Enabling Executables
There are two ways to enable all object files in an executable: using the Edit
menu or using the pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the executable you want to enable.
b. Select Enable executable from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the executable you want to enable. A
pop-up menu is displayed.
b. Select Enable executable from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.6. Disable Executable Choice ΓòÉΓòÉΓòÉ
Select the Disable executable choice to disable an executable. This choice is
available when a disabled executable is selected. Disabled executables are
displayed in brown.
When an executable is disabled, EXTRA does not include information about that
executable in the trace file. The executable stays disabled only during this
trace analysis unless the Save settings check box is selected.
Disabling an Executable
There are two ways to disable an executable: using the Edit menu or using the
pop-up menu. The following explains how to use each method:
1. Use the Edit menu.
a. Select the executable you want to disable.
b. Select Disable executable from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the executable you want to disable. A
pop-up menu is displayed.
b. Select Disable executable from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.7. Enable Object Files Choice ΓòÉΓòÉΓòÉ
Select the Enable object files choice to enable all object files for a selected
executable.
This choice is available when an executable is selected. When all object files
in an executable have been disabled, the executable is displayed in brown. When
you enable object files, EXTRA includes information about the object files in
the trace file. When all object files are disabled, the font is changed to
italic. The executable stays disabled only during this trace analysis unless
the Save settings check box is selected.
Enabling Objects
There are two ways to enable all object files in an executable: using the Edit
menu or using the pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the executable you want to enable.
b. Select Enable object files from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the executable you want to enable. A
pop-up menu is displayed.
b. Select Enable object files from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.8. Disable Object Files Choice ΓòÉΓòÉΓòÉ
Select the Disable object files choice to disable all object files. This choice
is available when an executable is selected.
When you disable object files, EXTRA does not include information about those
object files in the trace file. Disabled object files are displayed in brown.
The object file stays disabled only during this trace analysis unless the Save
settings check box is selected.
Disabling Objects
There are two ways to disable an executable: using the Edit menu or using the
pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the executable you want to disable.
b. Select Disable object files from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the executable you want to disable. A
pop-up menu is displayed.
b. Select Disable object files from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.9. Enable Object File Choice ΓòÉΓòÉΓòÉ
Select the Enable object file choice to enable an object file. This choice is
available when an object file is selected.
When an object file is disabled, it is displayed in brown. When you enable an
object file, EXTRA includes information about that object file in the trace
file. The object file stays disabled only during this trace analysis unless the
Save settings check box is selected.
Enabling an Object
There are two ways to enable an object file: using the Edit menu or using the
pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the object file you want to enable.
b. Select Enable object file from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the object file you want to enable. A
pop-up menu is displayed.
b. Select Enable object file from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.10. Disable Object File Choice ΓòÉΓòÉΓòÉ
Select the Disable object file choice to disable an object file. This choice is
available when an object file is selected.
When an object file is disabled, EXTRA does not include information about that
object file in the trace file. Disabled object files are displayed in brown.
The object file stays disabled only during this trace analysis unless the Save
settings check box is selected.
Disabling an Object File
There are two ways to disable an object file: using the Edit menu or using the
pop-up menu. The following explains how to use each method:
1. Use the Edit menu.
a. Select the object file you want to disable.
b. Select Disable object file from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the object file you want to disable. A
pop-up menu is displayed.
b. Select Disable object file from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.11. Enable Functions Choice ΓòÉΓòÉΓòÉ
Select the Enable functions choice to enable the functions. This choice is
available when an object file is selected.
When the functions in an object file have been disabled, the object file is
displayed in brown. When you enable an object file or the functions, EXTRA
includes information about the object file in the trace file. The functions
stay disabled only during this trace analysis unless the Save settings check
box is selected.
Enabling Functions
There are two ways to enable the functions: using the Edit menu and using the
pop-up menu. The following explains how to use each method:
1. Use the Edit menu.
a. Select the function you want to enable.
b. Select Enable functions from the Edit menu.
2. Use the pop-up menu.
a. Use mouse button two to select the object file you want enabled. A
pop-up menu is displayed.
b. Select Enable functions from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.12. Disable Functions Choice ΓòÉΓòÉΓòÉ
Select the Disable functions choice to disable the functions. This choice is
available when an object file is selected.
When the functions are disabled, EXTRA does not include information about these
functions in the trace file. Disabled functions are displayed in brown. The
functions stay disabled only during this trace analysis unless the Save
settings check box is selected.
Disabling Functions
There are two ways to disable a function: using the Edit menu and using the
pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the object file you want disabled.
b. Select Disable functions from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the object file you want disabled. A
pop-up menu is displayed.
b. Select Disable functions from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.13. Enable Function Choice ΓòÉΓòÉΓòÉ
Select the Enable function choice to enable a function. This choice is
available when a function is selected.
When a function is disabled, it is displayed in brown. When you enable a
function, EXTRA includes information about the function in the trace file. The
function stays disabled only during this trace analysis unless the Save
settings check box is selected.
Enabling a Function
There are two ways to enable a function: using the Edit menu and using the
pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the function you want to enable.
b. Select Enable function from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the function you want enabled. A pop-up
menu is displayed.
b. Select Enable function from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.14. Disable Function Choice ΓòÉΓòÉΓòÉ
Select the Disable function choice to disable a function. This choice is
available when a function is selected.
When a function is disabled, EXTRA does not included information about the
function in the trace file. Disabled functions are displayed in brown. The
function stays disabled only during this trace analysis unless the Save
settings check box is selected.
Note: This choice is only available from the Edit menu.
Disabling a Function
There are two ways to disable a function: using the Edit menu and using the
pop-up menu. The following shows how to use each method:
1. Using the Edit menu.
a. Select the function you want disabled.
b. Select Disable function from the Edit menu.
2. Using the pop-up menu.
a. Use mouse button two to select the function you want disabled. A pop-up
menu is displayed.
b. Select Disable function from the pop-up menu.
ΓòÉΓòÉΓòÉ 6.4.15. Set Trigger Choice ΓòÉΓòÉΓòÉ
Select the Set trigger choice to add or remove a trigger from a function. This
choice is available when a function is selected.
A trigger function turns tracing on when it is called and then turns off the
tracing when it returns. If a trigger function is nested within another trigger
function, tracing is turned off only after the outer function returns. You can
set multiple triggers. The trigger is set for one trace analysis unless the
Save settings check box is selected.
Setting Triggers
There are two ways to set a trigger on a function: using the Edit menu or using
the pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the function you want to trigger.
b. Select Set trigger from the Edit menu.
c. Select the On choice from the cascaded menu. A box is displayed around
the function and the word trigger is displayed next to the function.
2. Using the pop-up menu.
a. Use mouse button two to select the function you want to trigger. A
pop-up menu is displayed.
b. Select Set trigger from the pop-up menu. A box is displayed around the
function and the word trigger is displayed next to the function.
Resetting Triggers
There are two ways to reset a trigger on a function: using the Edit menu or
using the pop-up menu. The following explains how to use each method:
1. Using the Edit menu.
a. Select the function you want to reset.
b. Select Set trigger from the Edit menu.
c. Select the Off choice from the cascaded menu.
2. Using the pop-up menu.
a. Use mouse button two to select the function you want to reset. A pop-up
menu is displayed.
b. Select Reset trigger from the pop-up menu. The box and the word trigger
are removed from the function.
ΓòÉΓòÉΓòÉ 6.4.16. Reset Trigger Function Choice ΓòÉΓòÉΓòÉ
Select the Reset trigger function choice to remove a trigger from a function.
This choice is only available from the pop-up menu menu when a function has a
trigger set.
To reset the triggers:
1. Use mouse button two to select a function that you want to reset. A pop-up
menu is displayed.
2. Select Reset trigger function from the pop-up menu. The box and the word
trigger are removed from the function.
ΓòÉΓòÉΓòÉ 6.5. Help Menu ΓòÉΓòÉΓòÉ
Trace Generation window
The choices available from the Help menu are:
Help index
Shows an alphabetical index of all available EXTRA help topics.
General help
Provides help information for the current action window.
Using help
Explains how to use the EXTRA help facility.
ΓòÉΓòÉΓòÉ 6.5.1. Using Help Choice ΓòÉΓòÉΓòÉ
Trace Generation window
Select the Using help choice to learn how to use the EXTRA help facility. To
get help, select Using help from the Help menu.
ΓòÉΓòÉΓòÉ 6.5.2. General Help Choice ΓòÉΓòÉΓòÉ
Trace Generation window
Select the General help choice to display online help for the active EXTRA
window. The online help panel displayed is the same panel that is displayed
when you place your cursor inside the window and press F1.
ΓòÉΓòÉΓòÉ 6.5.3. Help Index Choice ΓòÉΓòÉΓòÉ
Trace Generation window
Select the Help index choice to display an alphabetical list of index entries
for EXTRA. Use the Search push button to locate topics in the index.
ΓòÉΓòÉΓòÉ 7. Application Termination Window ΓòÉΓòÉΓòÉ
While EXTRA is analyzing your application, the Application Termination window
and the Trace Analysis Status window are displayed. Use the Application
Termination window to stop your application.
Tracing an Application
You can choose to trace your entire application or just a specific part.
To trace your application:
1. Use the Trace Generation window to set any special settings.
2. Select the Trace push button to begin the trace analysis.
3. Run your entire application or any specific part you want to trace.
4. To stop tracing, quit from your application or select the Stop push button.
The Trace Analysis Status window shows the following message:
Application terminated ... please wait
The Trace Analysis Selection is displayed.
ΓòÉΓòÉΓòÉ 8. Trace Analysis Status Window ΓòÉΓòÉΓòÉ
The Trace Analysis Status window is displayed while EXTRA is tracing your
application. It displays the status of EXTRA.
The following lists the statements that may be displayed:
Gathering trace events ...
EXTRA is writing trace events to the buffer.
Flushing buffer - avoid desktop input!
EXTRA is writing trace events to the trace file because the buffer is
full. You should not enter any information or select any push button
while this statement is displayed. Any desktop input is delayed until
the buffer flushing is complete.
Application terminated ... please wait.
EXTRA is writing information to the trace file.
ΓòÉΓòÉΓòÉ 9. Trace Analysis Selection Window ΓòÉΓòÉΓòÉ
After EXTRA has analyzed your application, the Trace Analysis Selection window
is displayed with a push button for each diagram. From this window, you can
view the trace file in one of the following diagrams:
Statistics
This push button opens the Statistical Summary. This is a textual
report of execution times by function. It also provides other timing
information.
Call Nesting
This push button opens the Call Nesting diagram. This diagram shows
the sequence of nested function calls and returns made during the
execution of application.
Exec Density
This push button opens the Execution Density diagram. This diagram
divides the entire execution time into horizontal slices with a
column representing each function. The slices are in different colors
to show the percentage of time spent in each function.
Time Line
This push button opens the Time Line diagram. This diagram displays
the sequence of nested function calls and returns, and it uses time
stamp information to place each event properly along the time
dimension.
Call Graph
This push button opens the Dynamic Call Graph. This graph shows a
graphical view of the target application execution. Each function
called is displayed as a node. Calls are shown as arcs between nodes.
The color and size of nodes and arcs show the amount of time spent in
the function and the number of calls between functions.
ΓòÉΓòÉΓòÉ 9.1. Opening Diagrams ΓòÉΓòÉΓòÉ
To open a diagram, use one of the following methods:
1. Type the diagram command at the command prompt. The following list shows
the diagram and the command to type. After the command, type the name of
the trace file where the filename equals the name of the trace file and ext
equals the file extension:
Diagram Command
Statistical Summary
istats filename.ext
Call Nesting
icalnest filename.ext
Time Line.
itime filename.ext
Execution Density
iexcdens filename.ext
Dynamic Call Graph
idcgraph filename.ext
2. Select one of the push buttons in the Trace Analysis Selection window. The
following lists the push button name and diagram:
Push Button Diagram
Statistics Statistical Summary
Time Line Time Line
Exec Density Execution Density
Call Nesting Call Nesting
Call Graph Dynamic Call Graph
3. Select Open from the File menu of the window you have open and then select
a diagram to view from the cascaded menu.
ΓòÉΓòÉΓòÉ <hidden> Statistics Choice ΓòÉΓòÉΓòÉ
The Statistics choice is available from the Open cascaded menu. When you select
Statistics, the Statistical Summary is displayed.
ΓòÉΓòÉΓòÉ <hidden> Time Line Choice ΓòÉΓòÉΓòÉ
The Time Line choice is available from the Open cascaded menu. When you select
Time Line, the Time Line diagram is displayed.
ΓòÉΓòÉΓòÉ <hidden> Exec Density Choice ΓòÉΓòÉΓòÉ
The Execution Density choice is available from the Open cascaded menu. When you
select Execution Density, the Execution Density diagram is displayed.
ΓòÉΓòÉΓòÉ <hidden> Call Nesting Choice ΓòÉΓòÉΓòÉ
The Call Nesting choice is available from the Open cascaded menu. When you
select Call Nesting, the Call Nesting diagram is displayed.
ΓòÉΓòÉΓòÉ <hidden> Call Graph Choice ΓòÉΓòÉΓòÉ
The Dynamic Call Graph choice is available from the Open cascaded menu. When
you select Dynamic Call Graph, the Dynamic Call Graph is displayed.
ΓòÉΓòÉΓòÉ 9.2. Statistics Startup Information Window ΓòÉΓòÉΓòÉ
The Statistical Summary Startup Information window displays your trace file. To
specify the trace file you want EXTRA to display, do the following:
1. Type the full path and file name of the application you want to trace in
the Trace file name entry field. If the trace file is in your current
directory, you do not have to type the path.
2. Select the OK push button to display the diagram or select the Cancel push
button to return to the command prompt.
ΓòÉΓòÉΓòÉ 9.3. Time Line Startup Information Window ΓòÉΓòÉΓòÉ
The Time Line Startup Information window displays your trace file. To specify
the trace file you want EXTRA to display, do the following:
1. Type the full path and file name of the application you want to trace in
the Trace file name entry field. If the trace file is in your current
directory, you do not have to type the path.
2. Select the OK push button to display the diagram or select the Cancel push
button to return to the command prompt.
ΓòÉΓòÉΓòÉ 9.4. Execution Density Startup Information Window ΓòÉΓòÉΓòÉ
The Execution Density Startup Information window displays your trace file. To
specify the trace file you want EXTRA to display, do the following:
1. Type the full path and file name of the application you want to trace in
the Trace file name entry field. If the trace file is in your current
directory, you do not have to type the path.
2. Select the OK push button to display the diagram or select the Cancel push
button to return to the command prompt.
ΓòÉΓòÉΓòÉ 9.5. Call Nesting Startup Information Window ΓòÉΓòÉΓòÉ
The Call Nesting Startup Information window displays your trace file. To
specify the trace file you want EXTRA to display, do the following:
1. Type the full path and file name of the application you want to trace in
the Trace file name entry field. If the trace file is in your current
directory, you do not have to type the path.
2. Select the OK push button to display the diagram or select the Cancel push
button to return to the command prompt.
ΓòÉΓòÉΓòÉ 9.6. Dynamic Call Graph Startup Information Window ΓòÉΓòÉΓòÉ
The Dynamic Call Graph Startup Information window displays your trace file. To
specify the trace file you want EXTRA to display, do the following:
1. Type the full path and file name of the application you want to trace in
the Trace file name entry field. If the trace file is in your current
directory, you do not have to type the path.
2. Select the OK push button to display the diagram or select the Cancel push
button to return to the command prompt.
ΓòÉΓòÉΓòÉ 10. Statistical Summary ΓòÉΓòÉΓòÉ
The Statistical Summary gives you a textual report of execution time by
function. Use this information to find hot spots in the overall application
execution.
The Statistical Summary has two windows: Summary and Details.
The Summary window is in the top-most area. You can scroll the windows and
window panes to view the summary information. The Details window is divided
into two panes. The left pane lists the function names. The right pane lists
the statistics for each function.
You can resize the windows horizontally and the panes vertically. To resize a
window or window pane, press and drag the mouse pointer on a split bar until
the windows or window panes are the size you want.
Using the Summary Window
The summary information provides data about the following:
o Number of executables or object files generating events
o Number of functions generating events
o Number of threads generating events
o Maximum nesting depth of each thread
o Number of user events
o Total number of events
o Number of buffer flushes
o Total trace time excluding overhead
o Trace overhead time.
Viewing the Details Window
The Details window contains the functions and information about the functions,
such as:
o Function names
o The total execution and active time as percentages of the total execution and
the total active time, respectively
o The minimum, maximum, and average call time
o The total number of calls.
Notes:
1. Times are shown in seconds and in milliseconds.
2. If you chose to have file accesses traced, the Statistical Summary lists
the Dos call with the number of calls to it under the function name. For
more information, see tracing file accesses.
3. If you have user events in your application, the Statistical Summary lists
the user event with the number of accesses under the function name. For
more information, see inserting user events.
Menu Bar Summary
The choices available from the Statistical Summary menu bar are:
o File
o Options
o Help.
ΓòÉΓòÉΓòÉ 10.1. File Menu ΓòÉΓòÉΓòÉ
The following choices are available from the File menu:
Open
Displays a new or an additional diagram.
Save as
Creates a file containing the summary information.
Print
Prints the Statistical Summary.
ΓòÉΓòÉΓòÉ 10.1.1. Open Choice ΓòÉΓòÉΓòÉ
Select the Open cascading choice to view another diagram. You can open as many
new diagram windows as you want.
To select a new diagram:
1. Select Open from the File menu. A cascaded menu is displayed with the
following choices:
Statistics
Time Line
Execution Density
Call Nesting
Dynamic Call Graph
2. Select the name of the diagram you want to view. A new window opens and
displays the diagram you selected.
ΓòÉΓòÉΓòÉ 10.1.2. Save As Choice ΓòÉΓòÉΓòÉ
Select the Save as choice to save the Statistical Summary as an ASCII file.
When you select Save as, a Save As action window is displayed.
ΓòÉΓòÉΓòÉ 10.1.3. Print Choice ΓòÉΓòÉΓòÉ
Select Print to print the Statistical Summary.
To print the Statistical Summary, select Print from the File menu. The
Statistical Summary is printed on the default printer.
Note: If you are printing over a network, see your LAN administrator about
creating a printer object.
ΓòÉΓòÉΓòÉ 10.2. Options Menu ΓòÉΓòÉΓòÉ
The choices from the Options menu are:
Font
Select the font and font size for the Summary and Details windows.
Horz. split bar
Controls the horizontal split bar between the Summary and Details
windows.
Vert. split bar
Controls the vertical split bar in the Details window.
ΓòÉΓòÉΓòÉ 10.2.1. Font Choice ΓòÉΓòÉΓòÉ
Select the Font cascading choice to change the font and font size for the
Summary window and the Details window.
When you select Font, a cascaded menu is displayed with the following choices:
o Summary
o Details.
ΓòÉΓòÉΓòÉ 10.2.2. Summary Choice ΓòÉΓòÉΓòÉ
Select the Summary choice to change the font and font size for the Summary
window. The Summary window is in the top-most area.
When you select Summary, a Font action window is displayed.
ΓòÉΓòÉΓòÉ 10.2.3. Details Choice ΓòÉΓòÉΓòÉ
Select the Details choice to change the font and font size for the Details
window panes.
When you select Details, a Font action window is displayed.
ΓòÉΓòÉΓòÉ 10.2.4. Horz. Split Bar Choice ΓòÉΓòÉΓòÉ
Controls the horizontal split bar between the Summary and Details windows.
ΓòÉΓòÉΓòÉ 10.2.5. Vert. Split Bar Choice ΓòÉΓòÉΓòÉ
Controls the vertical split bar in the Details window.
ΓòÉΓòÉΓòÉ 10.2.6. Vert. Split Bar Action Window ΓòÉΓòÉΓòÉ
The Vert. Split Bar Action Window lets you control the vertical split bar in
the Details window. To change the setting, select the spin buttons in the entry
field.
ΓòÉΓòÉΓòÉ 10.3. Help Menu ΓòÉΓòÉΓòÉ
The choices available from the Help menu are:
Help index
Shows an alphabetical index of all available EXTRA help topics.
General help
Provides help information for the current action window.
Using help
Explains how to use the EXTRA help facility.
ΓòÉΓòÉΓòÉ 10.3.1. Help Index Choice ΓòÉΓòÉΓòÉ
Select the Help index choice to display an alphabetical list of index entries
for EXTRA. Use the Search push button to locate topics in the index.
ΓòÉΓòÉΓòÉ 10.3.2. Using Help Choice ΓòÉΓòÉΓòÉ
Select the Using help choice to learn how to use the EXTRA help facility. To
get help, select Using help from the Help menu.
ΓòÉΓòÉΓòÉ 10.3.3. General Help Choice ΓòÉΓòÉΓòÉ
Select the General help choice to display online help for the active EXTRA
window.
ΓòÉΓòÉΓòÉ 11. Time Line Diagram ΓòÉΓòÉΓòÉ
The Time Line diagram displays the sequence of nested function calls and
returns. Time stamps determine the exact placement of an event along the time
dimension on the vertical axis. This provides a direct and natural presentation
of the chronological relationships of events.
Menu Bar Summary
The following choices are available from the Time Line diagram menu bar:
o File
o Options
o Help.
ΓòÉΓòÉΓòÉ 11.1. File Menu ΓòÉΓòÉΓòÉ
The following choices are available from the File menu:
Open
Shows a new or an additional diagram.
Print
Prints the information that is displayed in the current window.
ΓòÉΓòÉΓòÉ 11.1.1. Open Choice ΓòÉΓòÉΓòÉ
Select the Open choice to view another diagram. You can open as many new
diagram windows as you want.
To select a new diagram:
1. Select Open from the File menu. A cascaded menu is displayed with the
following choices:
Statistics
Time Line
Execution Density
Call Nesting
Dynamic Call Graph
2. Select the name of the diagram you want to view. A new window opens and
displays the diagram you selected.
ΓòÉΓòÉΓòÉ 11.1.2. Print Choice ΓòÉΓòÉΓòÉ
Select Print to print the information from the Time Line diagram that is
displayed in the window.
To print the Time Line diagram, select Print from the File menu. The Time Line
diagram is printed on the default printer.
Note: If you are printing over a network, see your LAN administrator about
creating a printer object.
ΓòÉΓòÉΓòÉ 11.2. Options Menu ΓòÉΓòÉΓòÉ
The following choices are available from the Options menu:
Call stack
Shows all functions on the call stack at a selected point.
Correlation
Uses a selected point to find a correlating point in another diagram.
Font
Selects the font, font style, and font size for the diagram.
Scale
Selects the size of the diagram and controls which functions are
displayed in the diagram.
Thread layout
Selects the indentation amount for each thread column and whether to
draw separator bars between threads.
Ruler
Shows the time between two points of interest in a diagram.
ΓòÉΓòÉΓòÉ 11.2.1. Call Stack Choice ΓòÉΓòÉΓòÉ
Select the Call stack choice to display the order in which the functions were
called at a selected point. A call stack is a display of the call nesting in a
given application. For example, if function A calls function B, which calls
function C, then the call stack for function C would show function C as the
first element, function B as the second element, and function A as the last
element.
When you select Call stack, the pointer turns into a plus icon. Select a point
in the diagram to display the Call Stack action window.
ΓòÉΓòÉΓòÉ <hidden> Call Stack Action Window ΓòÉΓòÉΓòÉ
Select the Call stack choice to display the order in which the functions were
called at a selected point.
To display a call stack:
1. Select Call stack from the Options menu. The pointer turns into a plus
icon.
2. Select a point in the diagram. A Call Stack action window is displayed that
shows the function you selected and the order in which the functions were
called.
3. Select the OK push button to close the action window.
ΓòÉΓòÉΓòÉ 11.2.2. Correlation Choice ΓòÉΓòÉΓòÉ
Select the Correlation choice to mark a point in the Call Nesting diagram,
Execution Density diagram, or Time Line diagram and then find that same point
in another Call Nesting diagram, Execution Density diagram, or Time Line
diagram. You can correlate more than two diagrams at a time.
There are two ways to correlate diagrams: using the mouse and using the menus.
The following explains both methods:
1. Using the mouse:
a. Open a Call Nesting, Execution Density, or Time Line window and then
open at least one other window with a different diagram or the same
diagram at a different scale.
b. Select Correlation from the Options menu. The pointer turns into a
double-headed arrow.
c. Press and hold mouse button two on the point in the diagram you want to
correlate, drag the mouse pointer into the window of a second diagram,
and release mouse button two. EXTRA highlights the correlated point.
2. Using the menus
a. Open a Call Nesting, Execution Density, or Time Line window and then
open at least one other window with a different diagram or the same
diagram at a different scale.
b. Select Correlation from the Options menu. The pointer turns into a
double-headed arrow.
c. Move the double-headed arrow to the point in the diagram that you want
to correlate, press the spacebar, and then the Enter key. EXTRA
highlights the correlated point and a Correlation list box is
displayed.
d. Select the name of each diagram you want to correlate and select OK.
EXTRA highlights the correlated points in the diagrams.
ΓòÉΓòÉΓòÉ <hidden> Correlation List Box ΓòÉΓòÉΓòÉ
Use the Correlation list box to select the name of each diagram you want to
correlate and select OK. EXTRA opens a diagram and highlights the correlated
point. For more information, see Push Buttons.
ΓòÉΓòÉΓòÉ 11.2.3. Font Choice ΓòÉΓòÉΓòÉ
Select the Font choice to change the font, font style, and font size for the
diagram. A Font action window is displayed.
ΓòÉΓòÉΓòÉ 11.2.4. Scale Choice ΓòÉΓòÉΓòÉ
Use the Scale choice to select the size of the diagram and to control which
functions are displayed in the diagram. Scaling is the process of changing the
granularity of the detail in a trace diagram: to step back from a diagram to
get a bigger picture or to zoom in to see the finer points.
When you select Scale, a Scale action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Scale Action Window ΓòÉΓòÉΓòÉ
When you select Scale, a Scale action window is displayed.
This action window lets you select the size of the diagram and control which
functions are displayed in the diagram. The total execution time of the
application is displayed at the top. The number of pages that the diagram is
using are displayed above the top slider. The number of pages and their size
are based on the current window size.
The first sentence in the action window shows the total execution time in
seconds.
You can prevent the Time Line diagram from becoming cluttered with many short
calls by selecting how long a call must take before it is displayed in the
diagram.
To use the Scale action window:
1. Use the Pages slider to control how many pages or screens are used to
display your diagram. The current number of pages is displayed above the
Pages slider. When you increase the number of pages, the diagram is
displayed in more detail.
o Slide the slider arm to the right to increase the number of pages.
o Slide the slider arm to the left to decrease the number of pages.
Note: Page size is based on the height and width of the current window.
As you move the slider, the page field increases or decreases.
2. The Time Calls slider controls which calls are displayed based on their
active time. This bar lets you limit the function calls that are displayed
in the diagram.
o Slide the slider arm to the right to increase the time in usec of the
calls.
o Slide the slider arm to the left to decrease the time in usec of the
calls.
3. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
ΓòÉΓòÉΓòÉ 11.2.5. Thread Layout Choice ΓòÉΓòÉΓòÉ
Select the Thread layout choice to control thread indentation and to control
drawing of thread separator bars between the threads. A Thread Layout action
window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Thread Layout Action Window ΓòÉΓòÉΓòÉ
Select the Thread layout choice to control thread indentation and to control
whether separator bars are drawn between the threads. The default is to indent
each thread 8 pels and to have separator bars.
To use the Thread Layout action window:
1. Type a new value or select the spin buttons in the Indents per thread entry
field until the value you want is displayed. The maximum indent value is 99
pels.
2. Select the check box to draw separator lines between the threads. A √
symbol in the box indicates to draw separator bars and an empty box
indicates not to draw the separator bars.
3. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
ΓòÉΓòÉΓòÉ 11.2.6. Ruler Choice ΓòÉΓòÉΓòÉ
Select the Ruler choice to show how much time elapsed between two points of
interest in the diagram.
There are two ways to display the time: using the menu and using the keyboard.
The following explains both methods:
o Using the mouse:
1. Select Ruler from the Options menu. The mouse pointer turns into a plus
icon.
2. Press and hold mouse button one on the first point of interest in the
diagram, then drag the mouse pointer to the second point of interest,
and release mouse button one.
o Using the keyboard:
1. Select Ruler from the Options menu. A plus icon is displayed.
2. Press the spacebar to select the first point of interest in the diagram.
3. Use the or key to move to the second point of interest.
4. Press the Esc key.
ΓòÉΓòÉΓòÉ 11.3. Help Menu ΓòÉΓòÉΓòÉ
The choices available from the Help menu are:
Help index
Shows an alphabetical index of all available EXTRA help topics.
General help
Provides help information for the current action window.
Using help
Explains how to use the EXTRA help facility.
ΓòÉΓòÉΓòÉ 11.3.1. Help Index Choice ΓòÉΓòÉΓòÉ
Select the Help index choice to display an alphabetical list of index entries
for EXTRA. Use the Search push button to locate topics in the index.
ΓòÉΓòÉΓòÉ 11.3.2. Using Help Choice ΓòÉΓòÉΓòÉ
Select the Using help choice to learn how to use the EXTRA help facility. To
get help, select Using help from the Help menu.
ΓòÉΓòÉΓòÉ 11.3.3. General Help Choice ΓòÉΓòÉΓòÉ
Select the General help choice to display online help for the active EXTRA
window.
ΓòÉΓòÉΓòÉ 12. Call Nesting Diagram ΓòÉΓòÉΓòÉ
The Call Nesting diagram shows the application execution as a vertical series
of function calls and returns. Each thread has its own starting column of
functions. A call is drawn as a step to the right and a return as a line back
to the left. The calls are labeled with the function name being called. Context
switches between threads are shown by dashed horizontal lines.
While the vertical lines do not show elapsed times to scale in this diagram,
you can clearly see the flow of control and the interactions among the various
threads. Problems with critical sections, sequencing protocols, application
deadlocks and crashes, and thread delays can be diagnosed with this diagram.
Menu Bar Summary
The menu choices in the Call Nesting diagram are:
o File
o Edit
o Options
o Draw
o Help.
ΓòÉΓòÉΓòÉ 12.1. File Menu ΓòÉΓòÉΓòÉ
The choice from the File menu is:
Open
Displays a new or an additional diagram.
Print
Prints the information that is displayed in the current window.
ΓòÉΓòÉΓòÉ 12.1.1. Open Choice ΓòÉΓòÉΓòÉ
Select the Open choice to view another diagram. You can open as many new
diagram windows as you want.
To select a new diagram:
1. Select Open from the File menu. A cascaded menu is displayed with the
following choices:
Statistics
Time Line
Execution Density
Call Nesting
Dynamic Call Graph
2. Select the name of the diagram you want to view. A new window opens and
displays the diagram you selected.
ΓòÉΓòÉΓòÉ 12.1.2. Print Choice ΓòÉΓòÉΓòÉ
Select Print to print the information from the Call Nesting diagram.
To print the Call Nesting diagram, select Print from the File menu. The Call
Nesting diagram is printed on the default printer.
Note: If you are printing over a network, see your LAN administrator about
creating a printer object.
ΓòÉΓòÉΓòÉ 12.2. Edit Menu ΓòÉΓòÉΓòÉ
The following choices are available from the Edit menu:
Search
Search for a function call or return, an annotation, a user event, or
a file access.
Find Next
Find the next occurrence of the last item you searched for.
Annotate
Lets you insert comments in your diagram.
ΓòÉΓòÉΓòÉ 12.2.1. Search Choice ΓòÉΓòÉΓòÉ
Select the Search choice to search for a function call or return, annotation,
user event, or file access. To search for a file access, you must have set the
File Access choice before tracing your application. For more information, see
tracing file accesses. To search for a user event, you must have included the
necessary information in the source code of your application. For more
information, see including user events.
When you select Search, the Search action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Search Action Window ΓòÉΓòÉΓòÉ
When you select Search, the Search action window is displayed.
You can use the Search action window to do the following:
1. Search for Functions
2. Search for Annotations
3. Search for User Events and File Accesses
ΓòÉΓòÉΓòÉ <hidden> Searching for Functions ΓòÉΓòÉΓòÉ
1. To search for a function call or return:
a. Use mouse button one to select the spin buttons in the entry field and
select a function from the menu.
b. Select the Function radio button.
2. Select to find when the function is called or returned:
a. Select the Call radio button to find when a function was called.
b. Select the Return radio button to find when a function returned.
3. To search for a thread:
a. Type the thread number in the Thread entry field.
OR
b. Press and hold mouse button one on the list button in the entry field
and select a number from the list.
Note: This entry field displays in gray when there is only one thread or
when you have selected a specific thread from the Draw menu.
4. Select the Search push button to search. The string is highlighted when
found. Otherwise, a beep indicates that EXTRA could not find the string.
ΓòÉΓòÉΓòÉ <hidden> Searching for Annotations ΓòÉΓòÉΓòÉ
To search for an annotation:
1. Type the annotation you want to search for in the Find annotation entry
field.
Notes:
a. Select the Case sensitive check box if you want EXTRA to search for the
string as typed in the entry field.
b. Make sure the other entry fields are cleared.
2. Select the Annotation radio button.
3. Select the Search push button to search. The string is highlighted when
found. Otherwise, a beep indicates that EXTRA could not find the string.
ΓòÉΓòÉΓòÉ <hidden> Searching for User Events and File Accesses ΓòÉΓòÉΓòÉ
To search for a file access, you must have set the File Access choice before
tracing your application. For more information, see tracing file accesses. To
search for a user event, you must have included the necessary information in
the source code of your application. For more information, see including user
events.
To search for a user event or file access:
1. Type the string you want to search for in the Find user event entry field.
Notes:
a. Select the Case sensitive check box if you want EXTRA to search for the
string as typed in the entry field.
b. Make sure the other entry fields are cleared.
c. Select the User event radio button.
2. Select the Search push button to begin the search. The string is
highlighted when found. Otherwise, a beep indicates that EXTRA could not
find the string.
ΓòÉΓòÉΓòÉ 12.2.2. Find Next Choice ΓòÉΓòÉΓòÉ
Select the Find Next choice to search for the next occurrence of the last
string for which you searched.
To find the next occurrence, select Find Next from the Edit menu. Press the
Enter key to start the search. The string is highlighted when found. A beep
indicates that EXTRA could not find the string.
ΓòÉΓòÉΓòÉ 12.2.3. Annotate Choice ΓòÉΓòÉΓòÉ
Select the Annotate choice to add comments to the Call Nesting diagram. The
annotated comments that are added to the diagram are saved.
Note: If Pattern Recognition has been enabled, then the Annotate choice is not
available. Turn Pattern recognition off to use Annotate.
To annotate a comment:
1. Select Annotate from the Edit menu. A plus icon is displayed.
2. To select add a comment to the diagram, move the plus icon to the point
where you want to add the comment, and then click on the point or press the
spacebar and the Enter key. An Annotate action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Annotate Action Window ΓòÉΓòÉΓòÉ
When you select the Annotate choice, a Annotate action window is displayed. The
annotated comments that are added to the diagram are saved.
To use the Annotate action window:
1. Type the comment in the action window. The comment is limited to 64
characters.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Note: If Pattern Recognition has been enabled, then the Annotate choice is not
available. Turn Pattern recognition off to use Annotate.
To delete an annotated comment:
1. Select Annotate from the Edit menu.
2. Select the point in the Call Nesting diagram where you added the comment
that you now want deleted. An Annotate action window is displayed with the
comment.
3. Backspace over the comment in the action window.
4. Press the Enter key to delete the comment or press the Esc key to cancel
the choice.
ΓòÉΓòÉΓòÉ 12.3. Options Menu ΓòÉΓòÉΓòÉ
The following choices are available from the Options menu:
Call stack
Displays all the functions currently on the call stack from a
selected point.
Correlation
Uses a selected point to find a correlating point in another diagram.
Font
Selects the font, font style, and font size for the function names.
Pattern recognition
Shows where a function pattern occurs and the number of times it
occurs.
Select functions
Isolates specific functions to view in your application.
Thread layout
Selects the indentation amount for each thread column and draws
separator bars between threads.
ΓòÉΓòÉΓòÉ 12.3.1. Call Stack Choice ΓòÉΓòÉΓòÉ
Select the Call stack choice to display the order in which the functions were
called at a selected point.
When you select Call stack, the pointer turns into a plus icon. Select a point
in the diagram by clicking on the point with the mouse or by pressing the
spacebar and then the Enter key. A Call Stack action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Call Stack Action Window ΓòÉΓòÉΓòÉ
When you select Call stack, the pointer turns into a plus icon. Select a point
in the diagram to display the Call Stack action window.
To display a call stack:
1. Select a point in the diagram by using the mouse or pressing the spacebar
and then the Enter key. A Call Stack action window is displayed that shows
the function you selected and the order in which the functions were called.
2. Select the OK push button.
ΓòÉΓòÉΓòÉ 12.3.2. Correlation Choice ΓòÉΓòÉΓòÉ
Select the Correlation choice to mark a point in the Call Nesting diagram,
Execution Density diagram, or Time Line diagram and then find that same point
in another Call Nesting diagram, Execution Density diagram, or Time Line
diagram. You can correlate more than two diagrams at a time.
There are two ways to correlate diagrams: using the mouse and using the menus.
The following explains both methods:
1. Using the mouse:
a. Open a Call Nesting, Execution Density, or Time Line window and then
open at least one other window with a different diagram or the same
diagram at a different scale.
b. Select Correlation from the Options menu. The pointer turns into a
double-headed arrow.
c. Press and hold mouse button two on the point in the diagram you want to
correlate, drag the mouse pointer into the window of a second diagram,
and release mouse button two. EXTRA highlights the correlated point.
2. Using the menus
a. Open a Call Nesting, Execution Density, or Time Line window and then
open at least one other window with a different diagram or the same
diagram at a different scale.
b. Select Correlation from the Options menu. The pointer turns into a
double-headed arrow.
c. Move the double-headed arrow to the point in the diagram that you want
to correlate, press the spacebar, and then the Enter key. EXTRA
highlights the correlated point and a Correlation list box is
displayed.
d. Select the name of each diagram you want to correlate and select OK.
EXTRA highlights the correlated points in the diagrams.
ΓòÉΓòÉΓòÉ <hidden> Correlation List Box ΓòÉΓòÉΓòÉ
Use the Correlation list box to select the name of each diagram you want to
correlate and select OK. EXTRA opens a diagram and highlights the correlated
point. For more information, see Push Buttons.
ΓòÉΓòÉΓòÉ 12.3.3. Font Choice ΓòÉΓòÉΓòÉ
Select the Font choice to change the font, font style, and font size for the
diagram.
When you select Font, a Font action window is displayed.
ΓòÉΓòÉΓòÉ 12.3.4. Pattern Recognition Choice ΓòÉΓòÉΓòÉ
Select the Pattern recognition choice to combine all consecutive, repeated
patterns of calls and returns into one sequence with the number of times the
pattern occurred displayed to the right of the pattern. This choice reduces the
size of the diagram.
Note: You must select a single thread using the Draw menu before this choice
is available.
To set pattern recognition, select Pattern recognition from the Options menu.
The thread is displayed showing where the patterns occur. A loop is drawn to
the right of the patterns and a number is shown indicating how many times the
pattern is repeated. When this choice is selected, a √ symbol displays next to
the choice in the menu.
To turn off pattern recognition, select Pattern recognition from the Options
menu again. The √ symbol is no longer displayed.
Note: EXTRA recognizes up to 8,000 patterns. If your trace file contains more
than 8,000 patterns, EXTRA does not display the additional patterns.
ΓòÉΓòÉΓòÉ 12.3.5. Select Functions Choice ΓòÉΓòÉΓòÉ
Select the Select functions choice to isolate specific functions to view in
your application.
When you select Select functions, a Select Functions action window is displayed
Note: If Select functions is not available, select All Threads from the Draw
menu.
ΓòÉΓòÉΓòÉ <hidden> Select Functions Action Window ΓòÉΓòÉΓòÉ
When you select Select functions, a Select Functions action window is
displayed. From this action window you can isolate specific functions or view
all functions.
Isolating Specific Functions
To select functions:
1. To select a specific function, select the Clear all push button.
2. Scroll the list to find the function or functions you want displayed.
3. Select each function you want displayed.
4. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Note: All calls which called the selected function are also displayed.
Viewing All Functions
1. To select all functions, select the Select all push button.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
For more information, see Push Buttons.
ΓòÉΓòÉΓòÉ 12.3.6. Thread Layout Choice ΓòÉΓòÉΓòÉ
Select the Thread layout choice to control the thread indentation and to
control whether separator bars are drawn between the threads.
When you select Thread layout, a Thread Layout action window is displayed.
Note: This choice is only available when all threads are displayed.
ΓòÉΓòÉΓòÉ <hidden> Thread Layout Action Window ΓòÉΓòÉΓòÉ
When you select Thread layout, a Thread Layout action window is displayed.
To use the Thread Layout action window:
1. Type a new value or select the spin buttons in the Indents per thread entry
field until the value you want is displayed. The maximum indentation value
is 99 pels.
2. Select the check box to draw separator lines between the threads. A √
symbol in the box indicates to draw separator bars and an empty box
indicates not to draw the separator bars.
3. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
ΓòÉΓòÉΓòÉ 12.4. Draw Menu ΓòÉΓòÉΓòÉ
The following choices are available from the Draw menu:
All threads
Draws all threads.
Thread n
Draws only the selected thread. There is a menu choice for each
thread.
ΓòÉΓòÉΓòÉ 12.4.1. All Threads Choice ΓòÉΓòÉΓòÉ
Select the All threads menu choice to draw all the threads in the diagram.
ΓòÉΓòÉΓòÉ 12.4.2. Thread n Choice ΓòÉΓòÉΓòÉ
Select the Thread n menu choice to draw a particular thread, where n represents
the thread number in the application that you want drawn.
ΓòÉΓòÉΓòÉ 12.5. Help Menu ΓòÉΓòÉΓòÉ
The choices available from the Help menu are:
Help index
Shows an alphabetical index of all available EXTRA help topics.
General help
Provides help information for the current action window.
Using help
Explains how to use the EXTRA help facility.
ΓòÉΓòÉΓòÉ 12.5.1. Help Index Choice ΓòÉΓòÉΓòÉ
Select the Help index choice to display an alphabetical list of index entries
for EXTRA. Use the Search push button to locate topics in the index.
ΓòÉΓòÉΓòÉ 12.5.2. General Help Choice ΓòÉΓòÉΓòÉ
Select the General help choice to display online help for the active EXTRA
window.
ΓòÉΓòÉΓòÉ 12.5.3. Using Help Choice ΓòÉΓòÉΓòÉ
Select the Using help choice to learn how to use the EXTRA help facility. To
get help, select Using help from the Help menu.
ΓòÉΓòÉΓòÉ 13. Execution Density Diagram ΓòÉΓòÉΓòÉ
The Execution Density diagram displays trace data in a vertical dimension
scaled by the execution time just like the Time Line diagram, but calls and
returns are not shown. Instead, the entire execution time is divided into a
fixed number of horizontal slices, or scan lines, as determined by the number
of pages to be used for the entire diagram. Each function that logs events is
assigned to a fixed column of the diagram. EXTRA draws the diagram by coloring
each slice of the column depending on the percentage of the slice that the
corresponding function used. For instance in the default setting, yellow
represents 0 to 1 percent of the time slice was used in the function and pink
represents that 2 to 5 percent of the time slice was used.
Current Column Indicator
An arrow called the current column indicator is displayed at the top of each
column. The current column indicator lets you move to each column and also lets
you search for functions. For more information, see current column indicator
and searching for functions
Note:
1. When a thread switch occurs in the Execution Density diagram, the first
event of the new thread may have its time allotted to the previous thread.
2. Events that take small amounts of time may not be displayed until the
number of pages has been increased.
Menu Bar Summary
The following lists the choices available from the Execution Density diagram
menu bar:
o File
o Options
o Help.
ΓòÉΓòÉΓòÉ 13.1. Using the Current Column Indicator ΓòÉΓòÉΓòÉ
An arrow called the current column indicator is displayed at the top of each
column. The current column indicator lets you move to each column and also lets
you search for functions. You can use the mouse or the keyboard to move to each
column and EXTRA automatically scrolls the diagram to show the columns.
o To use the mouse, press and drag the current column indicator.
o To use the keyboard, press the Tab key to move to the right and press Shift
and Backtab to move to the left.
To search for functions, double-click on the current column indicator or press
the spacebar to display the Search function action window.
ΓòÉΓòÉΓòÉ 13.1.1. Search Function Action Window ΓòÉΓòÉΓòÉ
When you select current column indicator a Search Function action window is
displayed.
The Search Function action window lets you search for a function.
To use the Search Function action window:
1. Scroll the list until the function you want to search for displays.
2. Select the function.
3. Select OK to find the function or Cancel to close the action window.
ΓòÉΓòÉΓòÉ 13.2. File Menu ΓòÉΓòÉΓòÉ
The choice from the File menu is:
Open
Shows a new or an additional diagram.
Print
Prints the information that is displayed in the current window.
ΓòÉΓòÉΓòÉ 13.2.1. Open Choice ΓòÉΓòÉΓòÉ
Select the Open choice to view another diagram. You can open as many new
diagram windows as you want.
To select a new diagram:
1. Select Open from the File menu. A cascaded menu is displayed with the
following choices:
Statistics
Time Line
Execution Density
Call Nesting
Dynamic Call Graph
2. Select the name of the diagram you want to view. A new window opens and
displays the diagram you selected.
ΓòÉΓòÉΓòÉ 13.2.2. Print Choice ΓòÉΓòÉΓòÉ
Select Print to print the information from the Execution Density diagram.
To print the Execution Density diagram, select Print from the File menu. The
Execution Density diagram is printed on the default printer.
Note: If you are printing over a network, see your LAN administrator about
creating a printer object.
ΓòÉΓòÉΓòÉ 13.3. Options Menu ΓòÉΓòÉΓòÉ
The following choices are available from the Options menu:
Correlation
Uses a selected point to find a correlating point in another diagram.
Color
Selects the colors used to display the percentage of time used by
each function and the percentage of time the color represents.
Select functions
Isolates specific functions to view in your application.
Select Threads
Select which threads are displayed in the diagram.
Scale pages
Controls the number of pages the diagram uses.
Scale columns
Controls the width (in pels) for each function column in the diagram.
Ruler
Displays the time between two points of interest on the diagram.
ΓòÉΓòÉΓòÉ 13.3.1. Correlation Choice ΓòÉΓòÉΓòÉ
Select the Correlation choice to mark a point in the Call Nesting diagram,
Execution Density diagram, or Time Line diagram and then find that same point
in another Call Nesting diagram, Execution Density diagram, or Time Line
diagram. You can correlate more than two diagrams at a time.
There are two ways to correlate diagrams: using the mouse and using the menus.
The following explains both methods:
1. Using the mouse:
a. Open a Call Nesting, Execution Density, or Time Line window and then
open at least one other window with a different diagram or the same
diagram at a different scale.
b. Select Correlation from the Options menu. The pointer turns into a
double-headed arrow.
c. Press and hold mouse button two on the point in the diagram you want to
correlate, drag the mouse pointer into the window of a second diagram,
and release mouse button two. EXTRA highlights the correlated point.
2. Using the menus
a. Open a Call Nesting, Execution Density, or Time Line window and then
open at least one other window with a different diagram or the same
diagram at a different scale.
b. Select Correlation from the Options menu. The pointer turns into a
double-headed arrow.
c. Move the double-headed arrow to the point in the diagram that you want
to correlate, press the spacebar, and then the Enter key. EXTRA
highlights the correlated point and a Correlation list box is
displayed.
d. Select the name of each diagram you want to correlate and select OK.
EXTRA highlights the correlated points in the diagrams.
ΓòÉΓòÉΓòÉ <hidden> Correlation List Box ΓòÉΓòÉΓòÉ
Use the Correlation list box to select the name of each diagram you want to
correlate and select OK. EXTRA opens a diagram and highlights the correlated
point. For more information, see Push Buttons.
ΓòÉΓòÉΓòÉ 13.3.2. Color Choice ΓòÉΓòÉΓòÉ
Select the Color choice to control the colors and time slices that are used in
the diagram. Each color represents a time slice. When you select Color, a Color
action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Color Action Window ΓòÉΓòÉΓòÉ
When you select Color, a Color action window is displayed.
The Color action window shows the current colors and time slices. For each
color, a value is displayed to the left that shows the amount of time the color
represents. For instance, in the default setting, yellow represents 0 to 1
percent, pink represents 2 to 5 percent, and so on. You can change the color
and the percentage time each color represents.
To use the Color action window:
1. Select the list button at the end of the Color entry field to display a
list of available colors. Select a color from the list. The color name is
displayed over each color. There are 17 colors available.
2. Select a spin button to the left of the color entry fields to change the
time percentage that each color represents. As you select a spin button,
the value below the list box to the left changes also.
3. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Note: Select the Default push button to set the colors and time to the
preset choices.
ΓòÉΓòÉΓòÉ 13.3.3. Select Functions Choice ΓòÉΓòÉΓòÉ
Select the Select functions choice to isolate specific functions to view in
your application.
When you select Select functions, a Select Functions action window is
displayed.
ΓòÉΓòÉΓòÉ <hidden> Select Functions Action Window ΓòÉΓòÉΓòÉ
When you select the Select functions choice, a Select Functions action window
is displayed.
From the Select Functions action window, you can select specific functions to
view or you can view all functions.
Selecting Specific Functions
To select functions:
1. To select a specific function, select the Clear all push button.
2. Scroll the list to find the function or functions you want displayed.
3. Select each function you want displayed.
4. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Note: All calls leading to the selected function are displayed.
Selecting All Functions
1. To select all functions, select the Select all push button.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
ΓòÉΓòÉΓòÉ 13.3.4. Select Threads Choice ΓòÉΓòÉΓòÉ
Select the Select threads choice to select which threads are displayed in the
diagram. When you select Select threads, a Select Threads action window is
displayed.
ΓòÉΓòÉΓòÉ <hidden> Select Threads Action Window ΓòÉΓòÉΓòÉ
When you select the Select threads, a Select Threads action window is
displayed. The Select Threads action window shows an entry field for each
thread. The application thread numbers are displayed in black, while the others
are displayed in gray. The threads selected to display have a √ symbol in the
box.
Selecting Specific Threads
To select a specific thread:
1. Select the Clear all push button to clear all the √ symbols.
2. Select the specific threads you want displayed. A √ symbol is displayed in
the box to indicate it is selected.
3. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
Selecting All Threads
To select all threads:
1. Select the Select all push button to select all threads.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
ΓòÉΓòÉΓòÉ 13.3.5. Scale Pages Choice ΓòÉΓòÉΓòÉ
Select the Scale pages choice to choose how many pages you want used to display
the diagram. When you select Scale pages, a Scale Pages action window is
displayed.
ΓòÉΓòÉΓòÉ <hidden> Scale Pages Action Window ΓòÉΓòÉΓòÉ
When you select Scale pages, a Scale Pages action window is displayed.
From the Scale Pages action window you can choose how many pages are used to
display the diagram. When you allow more pages, the diagram shows more detailed
information.
Note: Scaling adjusts the number that you select to get an integral number of
full display screens.
EXTRA shows the total execution time for your application above the slider and
beneath the slider it shows the current page size based on the size of the
current window.
The page size is determined by the height and depth of the current window.
To use the Scale Pages action window:
1. Use the slider to set the number of pages:
o Slide the slider arm to the right to increase the number of pages in the
diagram.
o Slide the slider arm to the left to decrease the number of pages in the
diagram.
When you move the slider arm, the page number changes to show the new
selection.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
ΓòÉΓòÉΓòÉ 13.3.6. Scale Columns Choice ΓòÉΓòÉΓòÉ
Select the Scale columns choice to choose how many columns that you want
displayed.
When you select the Scale columns choice, Scale Columns action window is
displayed.
ΓòÉΓòÉΓòÉ <hidden> Scale Columns Action Window ΓòÉΓòÉΓòÉ
When you select the Scale columns choice, a Scale Columns action window is
displayed.
To use the Scale Columns action window:
1. Use the spin buttons to change the numbers. You can set the number between
1 and 32 pels per column. The default is 16. Select the top spin button to
increase the value and select the bottom spin button to decrease the value.
Note: When you select the value, the sentence to the right of the spin
buttons displays how many columns are allowed based on the value shown in
the entry field. The number of logged events for the application is
displayed in parentheses.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes. The diagram is redrawn to reflect the changes.
ΓòÉΓòÉΓòÉ 13.3.7. Ruler Choice ΓòÉΓòÉΓòÉ
Select the Ruler choice to show how much time elapsed between two points of
interest in the diagram.
There are two ways to display the time: using the menu and using the keyboard.
The following explains both methods:
o Using the mouse:
1. Select Ruler from the Options menu. The mouse pointer turns into a plus
icon.
2. Press and hold mouse button one on the first point of interest in the
diagram, drag the mouse pointer to the second point of interest, and
release mouse button one.
o Using the keyboard:
1. Select Ruler from the Options menu. A plus icon is displayed.
2. Press the spacebar to select the first point of interest in the diagram.
3. Use the or key to move to the second point of interest.
4. Press the Esc key.
ΓòÉΓòÉΓòÉ 13.4. Help Menu ΓòÉΓòÉΓòÉ
The choices available from the Help menu are:
Help index
Shows an alphabetical index of all available EXTRA help topics.
General help
Provides help information for the current action window.
Using help
Explains how to use the EXTRA help facility.
ΓòÉΓòÉΓòÉ 13.4.1. Help Index Choice ΓòÉΓòÉΓòÉ
Select the Help index choice to display an alphabetical list of index entries
for EXTRA. Use the Search push button to locate topics in the index.
ΓòÉΓòÉΓòÉ 13.4.2. General Help Choice ΓòÉΓòÉΓòÉ
Select the General help choice to display online help for the active EXTRA
window.
ΓòÉΓòÉΓòÉ 13.4.3. Using Help Choice ΓòÉΓòÉΓòÉ
Select the Using help choice to learn how to use the EXTRA help facility. To
get help, select Using help from the Help menu.
ΓòÉΓòÉΓòÉ 14. Dynamic Call Graph ΓòÉΓòÉΓòÉ
The Dynamic Call Graph is a graphical view of the execution of the target
application. A node represents a function and an arc, which is displayed
between a pair of nodes, represents a call from one function to another. Only
calls made during the given execution of the application are displayed.
Colors and sizes of nodes and arcs depict the time spent in the node and the
number of calls between nodes. The colors values are gray for the least amount
of time, blue for a larger amount of time, yellow for a larger amount of time,
and red for the largest amount of time. The color and width of the arc is
proportional to the number of calls made between functions.
Menu Bar Summary
The following choices are available from the Dynamic Call Graph menu bar:
o File
o Views
o Help.
Using Action Windows
The following action windows are available by using the mouse or keyboard:
o Function Information action window
o Who Calls Whom action window
Note: When the trace file has just one function for each thread, the Dynamic
Call Graph does not display.
ΓòÉΓòÉΓòÉ 14.1. File Menu ΓòÉΓòÉΓòÉ
The following choices are available from the File menu:
Open
Shows a new or an additional graph.
Print
Prints the information that is displayed in the current window.
ΓòÉΓòÉΓòÉ 14.1.1. Open Choice ΓòÉΓòÉΓòÉ
Select the Open choice to view another diagram. You can open as many new
windows as you want.
To select a new diagram:
1. Select Open from the File menu. A cascaded menu is displayed with the
following choices:
Statistics
Time Line
Execution Density
Call Nesting
Dynamic Call Graph
2. Select the name of the graph you want to view. A new window opens and
displays the graph you selected.
ΓòÉΓòÉΓòÉ 14.1.2. Print Choice ΓòÉΓòÉΓòÉ
Select Print to print the information from the Dynamic Call Graph.
To print the Dynamic Call Graph, select Print from the File menu. The Dynamic
Call Graph is printed on the default printer.
Note: If you are printing over a network, see your LAN administrator about
creating a printer object.
ΓòÉΓòÉΓòÉ 14.2. Views Menu ΓòÉΓòÉΓòÉ
The following choices are available from the View menu:
Re-lay graph
Centers the graph in the window.
Restore graph
Restores the graph to the default view.
Select threads
Controls the threads to include or exclude in the graph.
Search functions
Controls the functions to include or exclude in the graph.
Overview
Shows an overview window for the total graph.
Zoom in
Enlarges the size of the graph without changing the size of the
window.
Zoom out
Decreases the size of the graph without changing the size of the
window.
ΓòÉΓòÉΓòÉ 14.2.1. Re-lay Graph Choice ΓòÉΓòÉΓòÉ
Select the Re-lay graph choice to center and resize the nodes. See Dynamic Call
Graph for more information about isolating nodes and arcs.
To re-lay the graph, select Re-lay graph from the View menu. The graph is
centered in the window with all selected elements sized to fit.
ΓòÉΓòÉΓòÉ 14.2.2. Restore Graph Choice ΓòÉΓòÉΓòÉ
Select the Restore graph choice to return the graph to the default view.
To restore a graph, select Restore graph from the View menu. The entire graph
is restored to the default view.
ΓòÉΓòÉΓòÉ 14.2.3. Overview Choice ΓòÉΓòÉΓòÉ
Select the Overview choice to display a scaled-down image of the diagram you
are viewing. The Overview window lets you navigate through large diagrams.
Switching Views
To change the view of the graph, use the following:
1. View a larger or smaller area of the graph.
Press and hold mouse button one while pointing to any edge of the shaded
rectangle in the Overview window. By moving the mouse forward or backward,
the rectangle becomes larger or smaller. When you release mouse button one,
the main window is redrawn to reflect the new view.
2. View a different area of the graph.
Press and hold mouse button one in the center of the shaded rectangle in
the Overview window. Move the rectangle over the part of the graph that you
want to view. When you release mouse button one, the main window is redrawn
to reflect the new view.
ΓòÉΓòÉΓòÉ 14.2.4. Zoom In Choice ΓòÉΓòÉΓòÉ
Select the Zoom in choice to enlarge the graph without changing the window
size. If a node or an arc is selected, the Zoom in centers that node in the
window while enlarging the diagram. You can enlarge the diagram up to five
times its default size.
To enlarge the graph, select Zoom in from the View menu or press the Ctrl and
the key. Each time you choose the choice or press Ctrl and the key, the
window displays a larger view of the graph.
ΓòÉΓòÉΓòÉ 14.2.5. Zoom Out Choice ΓòÉΓòÉΓòÉ
Select the Zoom out choice to decrease the size of the graph without changing
the window size. The original default view is as small as the graph can be
displayed.
To decrease the view of the graph, select Zoom out from the View menu or press
the Ctrl key and the key. Each time you choose the choice or press the Ctrl
key and the key, the window displays a smaller view of the graph.
ΓòÉΓòÉΓòÉ 14.2.6. Select Threads Choice ΓòÉΓòÉΓòÉ
Select the Select threads choice to select which threads are displayed in the
diagram. When you select this choice, a Select Threads action window is
displayed.
ΓòÉΓòÉΓòÉ <hidden> Select Threads Action Window ΓòÉΓòÉΓòÉ
Select the Select threads choice to choose which threads are displayed in the
graph. When you select this choice, an action window is displayed that shows a
check box for each thread. The application thread numbers in your application
are displayed in black while the others are displayed in gray. The threads
selected to display have a √ symbol in the box.
To select a thread:
1. Select the specific thread you want displayed. A √ symbol is displayed in
the box to indicate it is selected.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
To select all threads:
1. Select the Select all push button to select all threads.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes.
ΓòÉΓòÉΓòÉ 14.2.7. Search Functions Choice ΓòÉΓòÉΓòÉ
Select the Search function choice to search for a function in the diagram. When
you select this choice, a Select Functions action window is displayed.
ΓòÉΓòÉΓòÉ <hidden> Search Functions Action Window ΓòÉΓòÉΓòÉ
Select the Search function choice to search and display a specific function in
the graph. When you select this choice, an action window is displayed that
lists every function.
To search for a function:
1. Scroll the list until you find the function you want to search for and the
select the function.
2. Select the OK push button to save the changes and close the action window
or select the Cancel push button to close the action window without saving
the changes. When you select OK, the diagram selects and centers the
function.
ΓòÉΓòÉΓòÉ <hidden> Function Information Action Window ΓòÉΓòÉΓòÉ
The Function Information action window displays information about a selected
function, the total execution time and active time in seconds and percentages,
and lets you show which function called the selected function and the functions
that the selected function called.
Displaying the Function Information Action Window
There are two ways to display the Function Information action window. Use one
of the following:
o Double-click on a node using the mouse button one
OR
o Use the right or left arrow keys to move the plus icon over a node, select it
using the space bar, and press the Enter key.
ΓòÉΓòÉΓòÉ 14.2.8. Function Information Action Window ΓòÉΓòÉΓòÉ
The Function Information action window displays the name of the selected
function. Underneath the name is information about the total execution time and
the active time in actual time and as a percentage.
The following lists the push buttons and gives an explanation of each push
button:
Who calls me
Select this push button to display only the selected node and the
nodes that called the selected node. To return to the graph, select
Restore graph from the Options menu.
Whom do I call
Select this push button to display only the selected node and the
nodes that the selected node calls. To return to the graph, select
Restore graph from the Options menu.
Cancel
Exits the action window.
ΓòÉΓòÉΓòÉ <hidden> Who Calls Whom Action Window ΓòÉΓòÉΓòÉ
The Who Call Whom action window displays information about a selected arc.
Displaying the Who Calls Whom Action Window
There are two ways to display the Who Calls Whom action window. Use one of the
following:
1. Double-click on an arc.
2. Use the right or left arrow key to move the plus icon over an arc, select
it by pressing the spacebar, and then press the Enter key.
ΓòÉΓòÉΓòÉ <hidden> Who Calls Whom Action Window ΓòÉΓòÉΓòÉ
The Who Calls Whom action window displays the name of the calling function, the
called function, and the number of times the call is made.
The following lists the push buttons and how to use the push button:
Find caller
Select this push button to select and center the node that makes the
call represented by the selected arc.
Find callee
Select this push button to select and center the node that is called
by the call represented in the selected arc.
Cancel
Exits the action window.
ΓòÉΓòÉΓòÉ 14.3. Help Menu ΓòÉΓòÉΓòÉ
The choices available from the Help menu are:
Help index
Shows an alphabetical index of all available EXTRA help topics.
General help
Provides help information for the current action window.
Using help
Explains how to use the EXTRA help facility.
ΓòÉΓòÉΓòÉ 14.3.1. Help Index Choice ΓòÉΓòÉΓòÉ
Select the Help index choice to display an alphabetical list of index entries
for EXTRA Use the Search push button to locate topics in the index.
ΓòÉΓòÉΓòÉ 14.3.2. General Help Choice ΓòÉΓòÉΓòÉ
Select the General help choice to display online help for the active EXTRA
window.
ΓòÉΓòÉΓòÉ 14.3.3. Using Help Choice ΓòÉΓòÉΓòÉ
Select the Using help choice to learn how to use the EXTRA help facility. To
get help, select Using help from the Help menu.
ΓòÉΓòÉΓòÉ 15. Problem Solving ΓòÉΓòÉΓòÉ
This topic lists the problems you may encounter while running EXTRA. To see how
to solve the problem, double-click on the problem and a solution displays in
the right-hand window.
Compiling and Linking Your Program
o When I compile and link my C++ program, I receive the following error
message:
:'EXTRA(char*)':
Using the Trace Generation Window
o My program executables display in cyan.
o My executable is shown in black, but EXTRA cannot show the objects.
Tracing Your Program
o EXTRA cannot trace my program.
o EXTRA cannot trace the library calls to the system.
o EXTRA cannot trace dynamically-loaded DLLs.
o The trace file logged 0 events.
o EXTRA cannot generate or analyze child processes in a multi-process
application.
Viewing the Trace File
o I cannot open my trace file.
o The Statistical Summary, Call Nesting, and Dynamic Call Graph are the only
available diagrams.
o The Statistical Summary and Dynamic Call Graph cannot display the trace file.
o The trace file does not show all functions.
o The trace file is very large.
o The trace file is incomplete.
Using the Statistical Summary
o "---" displays next to a function in the Statistical Summary.
o Multiple different user events are incorrectly displayed as the same string.
o User events display with unintelligible information.
Using the Call Nesting Diagram
o Multiple different user events are incorrectly displayed as the same string.
o User events display with unintelligible information.
o The Annotate choice is disabled.
o The Pattern Recognition choice does not show all patterns.
o The Select functions choice is not available.
o The Thread Layout choice is not available.
Using the Execution Density Diagram
o The Execution Density diagram is not displaying all of the events.
Using the Time Line Diagram
o There are functions or threads that are not displaying.
Using the Dynamic Call Graph
o The Dynamic Call Graph does not display.
o When I try to open the Dynamic Call Graph, I receive an API error.
ΓòÉΓòÉΓòÉ <hidden> Solutions ΓòÉΓòÉΓòÉ
Solutions display here.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
Your program must be compiled and linked properly before you can use EXTRA.
See Adding Debugging Information to Your Application for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
None of the objects in the executable were compiled with the proper profile
hook (Gh) options. Compile the programs you want to trace with the proper
options.
See Adding Debugging Information to Your Application for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
1. Your program must be properly compiled and linked before you can use EXTRA.
See Adding Debugging Information to Your Application for more information.
2. EXTRA only supports 32-bit IBM C/C++ code.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
You must link the libraries properly.
See Tracing the System Calls for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
One of two things has happened:
1. The dynamic link library (DLL) was not compiled with the program.
2. You may not have properly compiled and linked your program so that it can
be traced.
See Adding Debugging Information to Your Application for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
EXTRA does not support this.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
Before the Statistical Summary or Dynamic Call Graph can display a trace file,
the EXTRA dynamic link libraries (DLL) must be available.
Ensure all the EXTRA DLLs are available by checking the LIBPATH environment
variable.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
Use the Select Functions or Select Threads menu choice to reduce the viewable
information.
See the Select functions action window for more information.
See the Select threads action window for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
When you traced your application, there was not enough timing information
available for EXTRA to analyze the function. You need to allow more time for
the function to run. Use the Timeout Control in the Trace Generation window.
See the Timeout control action window for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
Check your settings in the diagram. If you have Select Functions set to display
a certain function, change the selection to show the all functions..
See the Select functions action window for more information.
If you have Thread n set to display a certain thread, select All Threads from
the Draw menu.
See the All Threads action window for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
There are several things that could have happened:
1. All functions were disabled in the Trace Generation window from the Edit
menu.
See disabling functions for more information.
2. You need to allow more time for the function to run. Use the Timeout
Control choice in the Trace Generation window.
See the Timeout Control action window for more information.
3. If you set a trigger on a function, the triggered function may not have
been reached.
4. Your program must be compiled and linked with the proper options before you
can use EXTRA.
See Adding Debugging Information to Your Application for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
Your buffer may be set to overwrite the older events.
See the Buffer Control action window for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
If you are trying to open a diagram from the command line, you may not be
typing the correct command.
See Opening Diagrams for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
1. A trigger may have been set from the Trace Generation window.
See Resetting Triggers for more information.
2. The call depth may be set to null or a low number.
See Set Call Depth action window for more information.
3. Some of the functions may have been disabled before the trace.
See disabling functions for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
The string used to declare the prototype must be unique static alphanumeric
characters.
See Creating EXTRA C and C++ Prototypes for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
You must declare a prototype for C++ programs in the following way:
extern "C"
{
VOID EXTRA (PSZ string);
}
See Creating EXTRA C and C++ Prototypes for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
You may have chosen to disable the time stamps from the Trace Generation
window.
See the Select Clock action window for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
When Pattern Recognition is enabled, the Annotate choice is not available.
Disable Pattern Recognition before selecting Annotate.
See the Annotate. action window for more information.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
The trace file contains over 8,000 patterns and EXTRA recognizes up to 8,000
patterns.
To correct this, limit the number of functions traced, limit the call depth of
the threads traced, or both.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
This choice is only available when all threads are displayed. If you have
enabled a specific thread from the Draw menu, you must select All Threads
before you can use the Select functions choice.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
This choice is only available when all threads are displayed. If you have
enabled a specific thread from the Draw menu, you must select All Threads
before you can use the Select functions choice.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
Events that take small amounts of time may not be displayed until the number of
pages has been increased.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
When the trace file contains just one function per thread, the Dynamic Call
Graph does not display.
ΓòÉΓòÉΓòÉ <hidden> Solution ΓòÉΓòÉΓòÉ
You have duplicate functions with the same name. You may have compiled your
program without the inline option.
If you received this error for a C++ program, compile the program again using
the /Oi+ option.
If you received this error for a C program, make sure all your functions have
unique names.
ΓòÉΓòÉΓòÉ 16. Glossary ΓòÉΓòÉΓòÉ
Double-click on any term for a definition:
o Active time
o Annotations
o Arc
o Buffer wrap
o Call
o Call nesting
o Call stack
o Correlation
o Dos calls
o Environment variable
o Event
o Executable
o Execution Trace Analyzer
o Flush
o Hot spot
o Node
o Overview
o Pels
o Function
o Return
o Ruler
o Run time
o Scaling
o Shortcut keys
o Thread
o Tic
o Timeout control
o Time stamp
o Trace
o Trace file
o Trigger functions
o User event.
ΓòÉΓòÉΓòÉ 16.1. Active Time ΓòÉΓòÉΓòÉ
Active time is the total time a function is on the call stack while its thread
is executing. The time is displayed in the Statistical Summary and Dynamic Call
Graph.
ΓòÉΓòÉΓòÉ 16.2. Annotation ΓòÉΓòÉΓòÉ
An annotation is a descriptive comment or an explanatory note added by the user
to the Call Nesting diagram.
ΓòÉΓòÉΓòÉ 16.3. Arc ΓòÉΓòÉΓòÉ
An arc is a directed line connecting two nodes in the Dynamic Call Graph. It
displays the relationship between the two nodes.
ΓòÉΓòÉΓòÉ 16.4. Buffer Wrap ΓòÉΓòÉΓòÉ
A buffer wrap occurs when the trace buffer overflows so that subsequent events
are written to the beginning of the buffer. When this happens, older events
are overwritten. The trace file size is limited by the number of events
contained in the buffer. You can control the size of the buffer from the Trace
Generation window using the Set buffer wrap choice.
ΓòÉΓòÉΓòÉ 16.5. Call ΓòÉΓòÉΓòÉ
To call is to bring a function into effect, such as specifying the entry
conditions and then jumping to an entry point in the function.
ΓòÉΓòÉΓòÉ 16.6. Call nesting ΓòÉΓòÉΓòÉ
Call nesting describes the relationships between calling and called functions.
For example, if function A calls function B, then EXTRA defines calls to B as
being nested under call A.
ΓòÉΓòÉΓòÉ 16.7. Call stack ΓòÉΓòÉΓòÉ
A call stack is a display of the call nesting in a given application. For
example, if function A calls function B, which calls function C, then the call
stack for function C would show function C as the first element, function B as
the second element, and function A as the last element.
ΓòÉΓòÉΓòÉ 16.8. Correlation ΓòÉΓòÉΓòÉ
Correlation allows you to mark a point in a Call Nesting diagram, Execution
Density diagram, or Time Line diagram and then find that same point in another
Call Nesting diagram, Execution Density diagram, or Time Line diagram.
ΓòÉΓòÉΓòÉ 16.9. Dos calls ΓòÉΓòÉΓòÉ
Dos calls are calls made to the operating system through functions with names
beginning with a Dos prefix, such as, DosExit and DosOpen.
ΓòÉΓòÉΓòÉ 16.10. Environment variable ΓòÉΓòÉΓòÉ
An environment variable is a variable associated with a given process and is
inherited from its parent process. For example, PATH.
ΓòÉΓòÉΓòÉ 16.11. Event ΓòÉΓòÉΓòÉ
An event is an entry or exit from a function. Also, EXTRA allows for
user-defined calls that are also defined as events.
ΓòÉΓòÉΓòÉ 16.12. Executable ΓòÉΓòÉΓòÉ
An executable is a file of compressed images of an application that includes:
o Each of the application segments, such as code, data, and stack.
o Control records that tell the loader how to tie all of the application
segments together.
ΓòÉΓòÉΓòÉ 16.13. Execution Trace Analyzer ΓòÉΓòÉΓòÉ
An Execution Trace Analyzer is a tool used to obtain and present information
about an application's behavior during its execution.
ΓòÉΓòÉΓòÉ 16.14. Flush ΓòÉΓòÉΓòÉ
A flush occurs when the virtual logging buffer for a trace is full and the
Buffer wrap choice in the Trace Generation window has not been selected. EXTRA
processes the contents of the virtual logging buffer and the events are written
to the trace file. After the buffer is flushed, EXTRA resumes tracing the
application.
ΓòÉΓòÉΓòÉ 16.15. Function ΓòÉΓòÉΓòÉ
A function is defined by EXTRA to be a callable section within the application.
For EXTRA, procedures and functions are synonyms of functions.
ΓòÉΓòÉΓòÉ 16.16. Hot spot ΓòÉΓòÉΓòÉ
A hot spot is an area within an application where a disproportionate amount of
time is spent.
ΓòÉΓòÉΓòÉ 16.17. Node ΓòÉΓòÉΓòÉ
A node is the representation of an individual function in the Dynamic Call
Graph.
ΓòÉΓòÉΓòÉ 16.18. Overview ΓòÉΓòÉΓòÉ
An Overview is the compressed representation of the entire diagram presented in
the Dynamic Call Graph.
ΓòÉΓòÉΓòÉ 16.19. Pels ΓòÉΓòÉΓòÉ
Pels are picture elements of a display area.
ΓòÉΓòÉΓòÉ 16.20. Return ΓòÉΓòÉΓòÉ
A return is a language construct within a function designating the end of the
execution sequence in the function.
ΓòÉΓòÉΓòÉ 16.21. Ruler ΓòÉΓòÉΓòÉ
A ruler is a mechanism in the Time Line and Execution Density diagrams to
display the amount of time between two points in the diagram.
ΓòÉΓòÉΓòÉ 16.22. Run time ΓòÉΓòÉΓòÉ
Run time is the time during which an application is being executed.
ΓòÉΓòÉΓòÉ 16.23. Scaling ΓòÉΓòÉΓòÉ
Scaling is the process of changing the granularity of the detail in a trace
diagram: to step back from a diagram to get a bigger picture or to zoom in to
see the finer points.
ΓòÉΓòÉΓòÉ 16.24. Shortcut keys ΓòÉΓòÉΓòÉ
Shortcut keys are keys you use to invoke menu choices. When two key names are
joined by a plus sign (+), use these two keys together. Hold down the first key
and then press the second key.
You can use shortcut keys for most of the menu choices in the EXTRA.
For a list of shortcut keys, select any of the following:
o Trace Generation window
o Statistical Summary
o Time Line Diagram
o Execution Density Diagram
o Call Nesting Diagram
o Dynamic Call Graph
ΓòÉΓòÉΓòÉ 16.24.1. Shortcut Keys for Trace Generation Window ΓòÉΓòÉΓòÉ
Trace Generation window
The following lists the shortcut keys available from the Trace Generation
window:
o Double-click on an executable and an object file to toggle between showing
and hiding.
o Double-click on a function to disable and enable the function.
o Use the PageUp and PageDown keys to move through the names of the
executables, object files, and functions on the screen.
For choices in the Edit menu, use the following keys:
Show Alt+S
Hide Alt+H
Enable Alt+E
Disable Alt+D
Enables items below selected item Alt+N
Disables items below selected item Alt+I
Set trigger Alt+T
For choices in the Options menu, use the following keys:
Select clock Alt+C
Buffer control Alt+B
Set call depth Alt+S
Name trace file Alt+N
Timeout control Alt+T
File access Alt+F
Default setup Alt+D
ΓòÉΓòÉΓòÉ 16.24.2. Shortcut Keys for the Statistical Summary ΓòÉΓòÉΓòÉ
For choices in the File menu, use the following keys:
Open Alt+O
Statistics Alt+S
Time Line Alt+T
Execution Density Alt+E
Call Nesting Alt+C
Dynamic Call Graph Alt+D
Save as Alt+S
Print Alt+P
For choices in the Options menu, use the following keys:
Font Alt+F
Summary Alt+S
Details Alt+D
Horz. split bar Alt+H
Vert. split bar Alt+V
To move between the Details and Summary windows, use the Tab key. To move
between the Details panes, use the F6 key.
ΓòÉΓòÉΓòÉ 16.24.3. Shortcut Keys for the Time Line Diagram ΓòÉΓòÉΓòÉ
For choices in the File menu, use the following keys:
Open Alt+O
Statistics Alt+S
Time Line Alt+T
Execution Density Alt+E
Call Nesting Alt+C
Dynamic Call Graph Alt+D
Print Alt+P
For choices in the Options menu, use the following keys:
Call stack Alt+S
Correlation Alt+C
Font Alt+F
Scale Alt+L
Thread layout Alt+T
Ruler Alt+R
ΓòÉΓòÉΓòÉ 16.24.4. Shortcut Keys for the Call Nesting Diagram ΓòÉΓòÉΓòÉ
For choices in the File menu, use the following keys:
Open Alt+O
Statistics Alt+S
Time Line Alt+T
Execution Density Alt+E
Call Nesting Alt+C
Dynamic Call Graph Alt+D
Print Alt+P
For choices in the Edit menu, use the following keys:
Search Alt+S
Find next Alt+F
Annotate Alt+A
For choices in the Options menu, use the following keys:
Call stack Alt+S
Correlation Alt+C
Font Alt+F
Pattern recognition Alt+R
Select functions Alt+L
Thread layout Alt+T
For choices in the Draw menu, use the following keys:
All Threads Alt+A
ΓòÉΓòÉΓòÉ 16.24.5. Shortcut Keys for the Dynamic Call Graph ΓòÉΓòÉΓòÉ
For choices in the File menu, use the following keys:
Open Alt+O
Statistics Alt+S
Time Line Alt+T
Execution Density Alt+E
Call Nesting Alt+C
Dynamic Call Graph Alt+D
Print Alt+P
For choices in the Views menu, use the following keys:
Re-lay graph Alt+L
Restore graph Alt+R
Select threads Alt+S
Overview Alt+V
Zoom in .Ctrl+
Zoom out .Ctrl+
ΓòÉΓòÉΓòÉ 16.24.6. Shortcut Keys for the Execution Density Diagram ΓòÉΓòÉΓòÉ
For choices in the File menu, use the following keys:
Open Alt+O
Statistics Alt+S
Time Line Alt+T
Execution Density Alt+E
Call Nesting Alt+C
Dynamic Call Graph Alt+D
Print Alt+P
For choices in the Options menu, use the following keys:
Color Alt+L
Correlation Alt+C
Select Functions Alt+F
Select threads Alt+T
Scale pages Alt+P
Scale columns Alt+M
Ruler Alt+R
ΓòÉΓòÉΓòÉ 16.25. Thread ΓòÉΓòÉΓòÉ
A thread is the basic OS/2* unit of execution. A thread gives an application
its context, including registers, stack, and processor mode. Multiple threads
can be running at the same time, and any particular thread can start another
thread.
ΓòÉΓòÉΓòÉ 16.26. Tic ΓòÉΓòÉΓòÉ
A tic is the smallest unit of time measured by the EXTRA counter. A tic
measures approximately 838 nanoseconds.
ΓòÉΓòÉΓòÉ 16.27. Timeout control ΓòÉΓòÉΓòÉ
Timeout control lets you select the maximum number of seconds your application
can run without logging events. This choice is available in the Trace
Generation window from the Options Choice. This choice is helpful if your
application is in a continuous loop or is stalled.
ΓòÉΓòÉΓòÉ 16.28. Time stamp ΓòÉΓòÉΓòÉ
A time stamp is the actual time an event occurred when the application was
being traced.
ΓòÉΓòÉΓòÉ 16.29. Trace ΓòÉΓòÉΓòÉ
A trace is a record of events obtained during the execution of an application.
It contains the sequences and timing of the events during application
execution.
ΓòÉΓòÉΓòÉ 16.30. Trace file ΓòÉΓòÉΓòÉ
A trace file is a file that contains a chronological sequence of records
describing events which occurred during the execution of the application. The
trace file contains the trace analysis information from your application and is
displayed by the diagrams.
ΓòÉΓòÉΓòÉ 16.31. Trigger function ΓòÉΓòÉΓòÉ
A trigger function turns tracing on when it is called and then turns tracing
off when it returns. If a trigger function is nested within another trigger
function, tracing is turned off only after the outer function returns.
ΓòÉΓòÉΓòÉ 16.32. User event ΓòÉΓòÉΓòÉ
A user event is a call to EXTRA defined by the user in the application. EXTRA
inserts text strings into the trace diagrams given by the parameter supplied by
this call. User events can help diagnose problem areas in the application.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A user event is a call to EXTRA defined by the user in the application. EXTRA
inserts text strings into the diagrams given by the parameter supplied by this
call. User events can help you diagnose problem areas in your application.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A trace file is a file that contains a chronological sequence of records
describing events which occurred during the application execution. The trace
file contains the trace analysis information from your application and is
displayed by the diagrams.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
The Call Nesting diagram shows the application execution as a vertical series
of function calls and returns. Each thread has its own starting column of
functions. A call is drawn as a step to the right and a return as a line back
to the left. The calls are labeled with the name of the function being called.
Context switches between threads are shown by dashed horizontal lines.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
This summary provides a textual report of execution time by function. It also
provides summary information.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Object files are compiler output files that are linked to comprise an
executable.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A function is defined by EXTRA to be a callable section within the application.
For EXTRA, procedures and functions are synonyms of functions.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A time stamp is the actual time at which an event occurred when the application
was being traced.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
The Dynamic Call Graph shows a graphical view of the target application
executions. Each function called is displayed as a node. Calls are shown as
arcs between nodes. The color and size of nodes and arcs show the amount of
time spent in the function and the number of calls between functions.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A thread is the basic OS/2* unit of execution. A thread gives an application
its context, including registers, stack, and processor mode. Multiple threads
can be running at the same time, and any particular thread can start another
thread.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A trigger function turns tracing on when it is called and then turns tracing
off when it returns. If a trigger function is nested within another trigger
function, tracing is turned off only after the outer function returns.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
The plus icon is displayed beside an executable and object file in the Trace
Generation window when the file can be shown or expanded.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
The minus icon is displayed beside an executable and object file in the Trace
Generation window when the file can not be shown or expanded.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A node is the representation of an individual function in the Dynamic Call
Graph.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
An arc is a directed line connecting two nodes in the Dynamic Call Graph. It
displays the relationship between the two nodes.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A trace file is a file that contains a chronological sequence of records
describing events which occurred during the application execution. The trace
file contains the trace analysis information from your application. This file
can be displayed by diagrams.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Correlation allows you to mark a point in a Call Nesting diagram, Execution
Density diagram, or Time Line diagram and then find that same point in another
Call Nesting diagram, Execution Density diagram, or Time Line diagram.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Hot spots are areas within an application where a disproportionate amount of
time was spent. Plus, this information helps to determine which functions
caused those hot spots.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
An executable is a file of compressed images of an application that includes
each of the application segments, such as code, data, and stack and control
records that tell the loader how to tie all of the application segments
together.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Overhead is the time it takes to log events in the trace file. EXTRA measures
its overhead and adjusts the timing information accordingly.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Active time is the total time a function is on the call stack while its thread
is executing. The time is displayed in the Statistical Summary and Dynamic Call
Graph.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
To call is to bring a function into effect, such as specifying the entry
conditions and then jumping to an entry point in the function.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
An annotation is a descriptive comment or an explanatory note that you can add
to the Call Nesting diagram.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
File access occurs when a given file is opened, read, written, or closed in an
application.