OS/2 Shareware BBS: 10 Tools/10-Tools.zip/cset21v1.zip/IBMCPP/HELP/DDE4XTRA.HLP

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.